// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.ads.datamanager.v1;

import "google/ads/datamanager/v1/user_list.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";

option csharp_namespace = "Google.Ads.DataManager.V1";
option go_package = "cloud.google.com/go/datamanager/apiv1/datamanagerpb;datamanagerpb";
option java_multiple_files = true;
option java_outer_classname = "UserListServiceProto";
option java_package = "com.google.ads.datamanager.v1";
option php_namespace = "Google\\Ads\\DataManager\\V1";
option ruby_package = "Google::Ads::DataManager::V1";

// Service for managing UserList resources.
service UserListService {
  option (google.api.default_host) = "datamanager.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/datamanager";

  // Gets a UserList.
  //
  // Authorization Headers:
  //
  // This method supports the following optional headers to define how the API
  // authorizes access for the request:
  //
  // * `login-account`: (Optional) The resource name of the account where the
  //   Google Account of the credentials is a user. If not set, defaults to the
  //   account of the request. Format:
  //   `accountTypes/{loginAccountType}/accounts/{loginAccountId}`
  // * `linked-account`: (Optional) The resource name of the account with an
  //    established product link to the `login-account`. Format:
  //    `accountTypes/{linkedAccountType}/accounts/{linkedAccountId}`
  rpc GetUserList(GetUserListRequest) returns (UserList) {
    option (google.api.http) = {
      get: "/v1/{name=accountTypes/*/accounts/*/userLists/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Lists UserLists.
  //
  // Authorization Headers:
  //
  // This method supports the following optional headers to define how the API
  // authorizes access for the request:
  //
  // * `login-account`: (Optional) The resource name of the account where the
  //   Google Account of the credentials is a user. If not set, defaults to the
  //   account of the request. Format:
  //   `accountTypes/{loginAccountType}/accounts/{loginAccountId}`
  // * `linked-account`: (Optional) The resource name of the account with an
  //    established product link to the `login-account`. Format:
  //    `accountTypes/{linkedAccountType}/accounts/{linkedAccountId}`
  rpc ListUserLists(ListUserListsRequest) returns (ListUserListsResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=accountTypes/*/accounts/*}/userLists"
    };
    option (google.api.method_signature) = "parent";
  }

  // Creates a UserList.
  //
  // Authorization Headers:
  //
  // This method supports the following optional headers to define how the API
  // authorizes access for the request:
  //
  // * `login-account`: (Optional) The resource name of the account where the
  //   Google Account of the credentials is a user. If not set, defaults to the
  //   account of the request. Format:
  //   `accountTypes/{loginAccountType}/accounts/{loginAccountId}`
  // * `linked-account`: (Optional) The resource name of the account with an
  //    established product link to the `login-account`. Format:
  //    `accountTypes/{linkedAccountType}/accounts/{linkedAccountId}`
  rpc CreateUserList(CreateUserListRequest) returns (UserList) {
    option (google.api.http) = {
      post: "/v1/{parent=accountTypes/*/accounts/*}/userLists"
      body: "user_list"
    };
    option (google.api.method_signature) = "parent,user_list";
  }

  // Updates a UserList.
  //
  // Authorization Headers:
  //
  // This method supports the following optional headers to define how the API
  // authorizes access for the request:
  //
  // * `login-account`: (Optional) The resource name of the account where the
  //   Google Account of the credentials is a user. If not set, defaults to the
  //   account of the request. Format:
  //   `accountTypes/{loginAccountType}/accounts/{loginAccountId}`
  // * `linked-account`: (Optional) The resource name of the account with an
  //    established product link to the `login-account`. Format:
  //    `accountTypes/{linkedAccountType}/accounts/{linkedAccountId}`
  rpc UpdateUserList(UpdateUserListRequest) returns (UserList) {
    option (google.api.http) = {
      patch: "/v1/{user_list.name=accountTypes/*/accounts/*/userLists/*}"
      body: "user_list"
    };
    option (google.api.method_signature) = "user_list,update_mask";
  }

  // Deletes a UserList.
  //
  // Authorization Headers:
  //
  // This method supports the following optional headers to define how the API
  // authorizes access for the request:
  //
  // * `login-account`: (Optional) The resource name of the account where the
  //   Google Account of the credentials is a user. If not set, defaults to the
  //   account of the request. Format:
  //   `accountTypes/{loginAccountType}/accounts/{loginAccountId}`
  // * `linked-account`: (Optional) The resource name of the account with an
  //    established product link to the `login-account`. Format:
  //    `accountTypes/{linkedAccountType}/accounts/{linkedAccountId}`
  rpc DeleteUserList(DeleteUserListRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1/{name=accountTypes/*/accounts/*/userLists/*}"
    };
    option (google.api.method_signature) = "name";
  }
}

// Request message for GetUserList.
message GetUserListRequest {
  // Required. The resource name of the UserList to retrieve.
  // Format:
  // accountTypes/{account_type}/accounts/{account}/userLists/{user_list}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "datamanager.googleapis.com/UserList"
    }
  ];
}

// Request message for ListUserLists.
message ListUserListsRequest {
  // Required. The parent account which owns this collection of user lists.
  // Format: accountTypes/{account_type}/accounts/{account}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "datamanager.googleapis.com/UserList"
    }
  ];

  // Optional. The maximum number of user lists to return. The service may
  // return fewer than this value. If unspecified, at most 50 user lists will be
  // returned. The maximum value is 1000; values above 1000 will be coerced to
  // 1000.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous `ListUserLists` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `ListUserLists` must
  // match the call that provided the page token.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A [filter string](https://google.aip.dev/160). All fields need to
  // be on the left hand side of each condition (for example: `display_name =
  // "list 1"`). Fields must be specified using either all [camel
  // case](https://en.wikipedia.org/wiki/Camel_case) or all [snake
  // case](https://en.wikipedia.org/wiki/Snake_case). Don't use a combination of
  // camel case and snake case.
  //
  // Supported operations:
  //
  // - `AND`
  // - `=`
  // - `!=`
  // - `>`
  // - `>=`
  // - `<`
  // - `<=`
  // - `:` (has)
  //
  // Supported fields:
  //
  // - `id`
  // - `display_name`
  // - `description`
  // - `membership_status`
  // - `integration_code`
  // - `access_reason`
  // - `ingested_user_list_info.upload_key_types`
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for ListUserLists.
message ListUserListsResponse {
  // The user lists from the specified account.
  repeated UserList user_lists = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}

// Request message for CreateUserList.
message CreateUserListRequest {
  // Required. The parent account where this user list will be created.
  // Format: accountTypes/{account_type}/accounts/{account}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "datamanager.googleapis.com/UserList"
    }
  ];

  // Required. The user list to create.
  UserList user_list = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. If true, the request is validated but not executed.
  bool validate_only = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for UpdateUserList.
message UpdateUserListRequest {
  // Required. The user list to update.
  //
  // The user list's `name` field is used to identify the user list to update.
  // Format:
  // accountTypes/{account_type}/accounts/{account}/userLists/{user_list}
  UserList user_list = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The list of fields to update.
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. If true, the request is validated but not executed.
  bool validate_only = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for DeleteUserList.
message DeleteUserListRequest {
  // Required. The name of the user list to delete.
  // Format:
  // accountTypes/{account_type}/accounts/{account}/userLists/{user_list}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "datamanager.googleapis.com/UserList"
    }
  ];

  // Optional. If true, the request is validated but not executed.
  bool validate_only = 2 [(google.api.field_behavior) = OPTIONAL];
}