// 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/destination.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";

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 = "PartnerLinkServiceProto";
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 partner links.
service PartnerLinkService {
  option (google.api.default_host) = "datamanager.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/datamanager,"
      "https://www.googleapis.com/auth/datamanager.partnerlink";

  // Creates a partner link for the given account.
  //
  // 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}`
  rpc CreatePartnerLink(CreatePartnerLinkRequest) returns (PartnerLink) {
    option (google.api.http) = {
      post: "/v1/{parent=accountTypes/*/accounts/*}/partnerLinks"
      body: "partner_link"
    };
    option (google.api.method_signature) = "parent,partner_link";
  }

  // Deletes a partner link for the given account.
  //
  // 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}`
  rpc DeletePartnerLink(DeletePartnerLinkRequest)
      returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1/{name=accountTypes/*/accounts/*/partnerLinks/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Searches for all partner links to and from a given account.
  //
  // 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}`
  rpc SearchPartnerLinks(SearchPartnerLinksRequest)
      returns (SearchPartnerLinksResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=accountTypes/*/accounts/*}/partnerLinks:search"
    };
    option (google.api.method_signature) = "parent";
  }
}

// Request to create a [PartnerLink][google.ads.datamanager.v1.PartnerLink]
// resource. Returns a
// [PartnerLink][google.ads.datamanager.v1.PartnerLink].
message CreatePartnerLinkRequest {
  // Required. The parent, which owns this collection of partner links.
  // Format: accountTypes/{account_type}/accounts/{account}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "datamanager.googleapis.com/PartnerLink"
    }
  ];

  // Required. The partner link to create.
  PartnerLink partner_link = 2 [(google.api.field_behavior) = REQUIRED];
}

// Request to delete a [PartnerLink][google.ads.datamanager.v1.PartnerLink]
// resource. Returns a [google.protobuf.Empty][google.protobuf.Empty].
message DeletePartnerLinkRequest {
  // Required. The resource name of the partner link to delete.
  // Format:
  // accountTypes/{account_type}/accounts/{account}/partnerLinks/{partner_link}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "datamanager.googleapis.com/PartnerLink"
    }
  ];
}

// Request to search for [PartnerLink][google.ads.datamanager.v1.PartnerLink]
// resources. Returns a
// [SearchPartnerLinksResponse][google.ads.datamanager.v1.SearchPartnerLinksResponse].
message SearchPartnerLinksRequest {
  // Required. Account to search for partner links. If no `filter` is specified,
  // all partner links where this account is either the `owning_account` or
  // `partner_account` are returned.
  //
  // Format: `accountTypes/{account_type}/accounts/{account}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "datamanager.googleapis.com/PartnerLink"
    }
  ];

  // The maximum number of partner links to return. The service may return
  // fewer than this value.
  // If unspecified, at most 50 partner links will be returned.
  // The maximum value is 100; values above 100 will be coerced to 100.
  int32 page_size = 2;

  // A page token, received from a previous `SearchPartnerLinks` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `SearchPartnerLinks`
  // must match the call that provided the page token.
  string page_token = 3;

  // Optional. A [filter string](https://google.aip.dev/160). All fields need to
  // be on the left hand side of each condition (for example: `partner_link_id =
  // 123456789`). 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`
  // - `=`
  // - `!=`
  //
  // Supported fields:
  //
  // - `partner_link_id`
  // - `owning_account.account_type`
  // - `owning_account.account_id`
  // - `partner_account.account_type`
  // - `partner_account.account_id`
  // - `feature_set`
  //
  // For partner links with the
  // [FEATURE_SET_AD_EVENT_MANAGEMENT][google.ads.datamanager.v1.FeatureSet.FEATURE_SET_AD_EVENT_MANAGEMENT]
  // feature set, the following fields are also supported:
  //
  // - `partner_customer_account.account_id`
  //
  // Example:
  // `owning_account.account_type = "GOOGLE_ADS" AND partner_account.account_id
  // = 987654321`
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Response from the
// [SearchPartnerLinksRequest][google.ads.datamanager.v1.SearchPartnerLinksRequest].
message SearchPartnerLinksResponse {
  // The partner links for the given account.
  repeated PartnerLink partner_links = 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;
}

// A partner link between an owning account and a partner account.
message PartnerLink {
  option (google.api.resource) = {
    type: "datamanager.googleapis.com/PartnerLink"
    pattern: "accountTypes/{account_type}/accounts/{account}/partnerLinks/{partner_link}"
    plural: "partnerLinks"
    singular: "partnerLink"
  };

  // Identifier. The name of the partner link.
  // Format:
  // accountTypes/{account_type}/accounts/{account}/partnerLinks/{partner_link}
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Output only. The partner link ID.
  string partner_link_id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. The owning account granting access to the partner account.
  ProductAccount owning_account = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. The partner account granted access by the owning account.
  ProductAccount partner_account = 4 [(google.api.field_behavior) = REQUIRED];

  // Optional. Immutable. The set of features supported for the partner link.
  // If not specified, the system behavior defaults to
  // [FEATURE_SET_AUDIENCE_AND_EVENT_MANAGEMENT][google.ads.datamanager.v1.FeatureSet.FEATURE_SET_AUDIENCE_AND_EVENT_MANAGEMENT].
  FeatureSet feature_set = 5 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Optional. The customer account in the partner system.
  // This is required for partner links with the
  // [FEATURE_SET_AD_EVENT_MANAGEMENT][google.ads.datamanager.v1.FeatureSet.FEATURE_SET_AD_EVENT_MANAGEMENT]
  // feature set.
  PartnerCustomerAccount partner_customer_account = 6
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Metadata associated with the partner link.
  // This is optional and only accepted for partner links with the
  // [FEATURE_SET_AD_EVENT_MANAGEMENT][google.ads.datamanager.v1.FeatureSet.FEATURE_SET_AD_EVENT_MANAGEMENT].
  PartnerLinkMetadata partner_link_metadata = 7
      [(google.api.field_behavior) = OPTIONAL];
}

// Represents a customer account in the partner's system.
message PartnerCustomerAccount {
  // Required. The identifier of the customer account in the partner's ID space.
  string account_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The name of the account.
  string account_name = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The type of the account. Can be used to distinguish between
  // advertiser accounts and business level accounts, for example.
  string account_type = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Represents metadata associated with a partner link.
message PartnerLinkMetadata {
  // Optional. The list of implicit accounts.
  repeated PartnerCustomerAccount implicit_accounts = 1
      [(google.api.field_behavior) = OPTIONAL];
}

// The set of supported features for a partner link.
enum FeatureSet {
  // Unspecified feature set. If unspecified, the system behavior defaults to
  // [FEATURE_SET_AUDIENCE_AND_EVENT_MANAGEMENT][google.ads.datamanager.v1.FeatureSet.FEATURE_SET_AUDIENCE_AND_EVENT_MANAGEMENT].
  FEATURE_SET_UNSPECIFIED = 0;

  // Indicates a link used for audience and event management.
  FEATURE_SET_AUDIENCE_AND_EVENT_MANAGEMENT = 1;

  // Indicates a link used for ad event management.
  FEATURE_SET_AD_EVENT_MANAGEMENT = 2;
}