// Copyright 2025 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.marketingplatform.admin.v1alpha;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/marketingplatform/admin/v1alpha/resources.proto";
import "google/protobuf/empty.proto";
import "google/type/date.proto";
import "google/type/money.proto";

option csharp_namespace = "Google.Ads.MarketingPlatform.Admin.V1Alpha";
option go_package = "google.golang.org/genproto/googleapis/marketingplatform/admin/v1alpha;admin";
option java_multiple_files = true;
option java_outer_classname = "MarketingplatformAdminProto";
option java_package = "com.google.ads.marketingplatform.admin.v1alpha";
option php_namespace = "Google\\Ads\\MarketingPlatform\\Admin\\V1alpha";
option ruby_package = "Google::Ads::MarketingPlatform::Admin::V1alpha";
option (google.api.resource_definition) = {
  type: "analyticsadmin.googleapis.com/Property"
  pattern: "properties/{property}"
};

// Service Interface for the Google Marketing Platform Admin API.
service MarketingplatformAdminService {
  option (google.api.default_host) = "marketingplatformadmin.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/marketingplatformadmin.analytics.read,"
      "https://www.googleapis.com/auth/marketingplatformadmin.analytics.update";

  // Lookup for a single organization.
  rpc GetOrganization(GetOrganizationRequest) returns (Organization) {
    option (google.api.http) = {
      get: "/v1alpha/{name=organizations/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Returns a list of organizations that the user has access to.
  rpc ListOrganizations(ListOrganizationsRequest)
      returns (ListOrganizationsResponse) {
    option (google.api.http) = {
      get: "/v1alpha/organizations"
    };
  }

  // Returns a list of clients managed by the sales partner organization.
  //
  // User needs to be an OrgAdmin/BillingAdmin on the sales partner organization
  // in order to view the end clients.
  rpc FindSalesPartnerManagedClients(FindSalesPartnerManagedClientsRequest)
      returns (FindSalesPartnerManagedClientsResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{organization=organizations/*}:findSalesPartnerManagedClients"
      body: "*"
    };
  }

  // Lists the Google Analytics accounts link to the specified Google Marketing
  // Platform organization.
  rpc ListAnalyticsAccountLinks(ListAnalyticsAccountLinksRequest)
      returns (ListAnalyticsAccountLinksResponse) {
    option (google.api.http) = {
      get: "/v1alpha/{parent=organizations/*}/analyticsAccountLinks"
    };
    option (google.api.method_signature) = "parent";
  }

  // Creates the link between the Analytics account and the Google Marketing
  // Platform organization.
  //
  // User needs to be an org user, and admin on the Analytics account to create
  // the link. If the account is already linked to an organization, user needs
  // to unlink the account from the current organization, then try link again.
  rpc CreateAnalyticsAccountLink(CreateAnalyticsAccountLinkRequest)
      returns (AnalyticsAccountLink) {
    option (google.api.http) = {
      post: "/v1alpha/{parent=organizations/*}/analyticsAccountLinks"
      body: "analytics_account_link"
    };
    option (google.api.method_signature) = "parent,analytics_account_link";
  }

  // Deletes the AnalyticsAccountLink, which detaches the Analytics account from
  // the Google Marketing Platform organization.
  //
  // User needs to be an org user, and admin on the Analytics account in order
  // to delete the link.
  rpc DeleteAnalyticsAccountLink(DeleteAnalyticsAccountLinkRequest)
      returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1alpha/{name=organizations/*/analyticsAccountLinks/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Updates the service level for an Analytics property.
  rpc SetPropertyServiceLevel(SetPropertyServiceLevelRequest)
      returns (SetPropertyServiceLevelResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{analytics_account_link=organizations/*/analyticsAccountLinks/*}:setPropertyServiceLevel"
      body: "*"
    };
    option (google.api.method_signature) = "analytics_account_link";
  }

  // Get the usage and billing data for properties within the organization for
  // the specified month.
  //
  // Per direct client org, user needs to be OrgAdmin/BillingAdmin on the
  // organization in order to view the billing and usage data.
  //
  // Per sales partner client org, user needs to be OrgAdmin/BillingAdmin on
  // the sales partner org in order to view the billing and usage data, or
  // OrgAdmin/BillingAdmin on the sales partner client org in order to view the
  // usage data only.
  rpc ReportPropertyUsage(ReportPropertyUsageRequest)
      returns (ReportPropertyUsageResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{organization=organizations/*}:reportPropertyUsage"
      body: "*"
    };
    option (google.api.method_signature) = "organization";
  }
}

// Request message for GetOrganization RPC.
message GetOrganizationRequest {
  // Required. The name of the Organization to retrieve.
  // Format: organizations/{org_id}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "marketingplatformadmin.googleapis.com/Organization"
    }
  ];
}

// Request message for ListOrganizations RPC.
message ListOrganizationsRequest {
  // Optional. The maximum number of organizations to return in one call. The
  // service may return fewer than this value.
  //
  // If unspecified, at most 50 organizations will be returned. The
  // maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 1 [(google.api.field_behavior) = OPTIONAL];

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

// Response message for ListOrganizations RPC.
message ListOrganizationsResponse {
  // The Organization resource that the user has access to, which includes the
  // org id and display name.
  repeated Organization organizations = 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 FindSalesPartnerManagedClients RPC.
message FindSalesPartnerManagedClientsRequest {
  // Required. The name of the sales partner organization.
  // Format: organizations/{org_id}
  string organization = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "marketingplatformadmin.googleapis.com/Organization"
    }
  ];

  // Optional. If set, only active and just ended clients will be returned.
  bool is_active = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for FindSalesPartnerManagedClients RPC.
message FindSalesPartnerManagedClientsResponse {
  // Contains the client data.
  message ClientData {
    // The end client that has/had contract with the requested sales org.
    Organization organization = 1;

    // The start date of the contract between the sales org and the end client.
    google.type.Date start_date = 2;

    // The end date of the contract between the sales org and the end client.
    google.type.Date end_date = 3;
  }

  // The clients managed by the sales org.
  repeated ClientData client_data = 1;
}

// Request message for ListAnalyticsAccountLinks RPC.
message ListAnalyticsAccountLinksRequest {
  // Required. The parent organization, which owns this collection of Analytics
  // account links. Format: organizations/{org_id}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "marketingplatformadmin.googleapis.com/AnalyticsAccountLink"
    }
  ];

  // Optional. The maximum number of Analytics account links to return in one
  // call. The service may return fewer than this value.
  //
  // If unspecified, at most 50 Analytics account links 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 ListAnalyticsAccountLinks
  // call. Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to
  // `ListAnalyticsAccountLinks` must match the call that provided the page
  // token.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for ListAnalyticsAccountLinks RPC.
message ListAnalyticsAccountLinksResponse {
  // Analytics account links in this organization.
  repeated AnalyticsAccountLink analytics_account_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;
}

// Request message for CreateAnalyticsAccountLink RPC.
message CreateAnalyticsAccountLinkRequest {
  // Required. The parent resource where this Analytics account link will be
  // created. Format: organizations/{org_id}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "marketingplatformadmin.googleapis.com/AnalyticsAccountLink"
    }
  ];

  // Required. The Analytics account link to create.
  AnalyticsAccountLink analytics_account_link = 2
      [(google.api.field_behavior) = REQUIRED];
}

// Request message for DeleteAnalyticsAccountLink RPC.
message DeleteAnalyticsAccountLinkRequest {
  // Required. The name of the Analytics account link to delete.
  // Format:
  // organizations/{org_id}/analyticsAccountLinks/{analytics_account_link_id}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "marketingplatformadmin.googleapis.com/AnalyticsAccountLink"
    }
  ];
}

// Request message for SetPropertyServiceLevel RPC.
message SetPropertyServiceLevelRequest {
  // Required. The parent AnalyticsAccountLink scope where this property is in.
  // Format:
  // organizations/{org_id}/analyticsAccountLinks/{analytics_account_link_id}
  string analytics_account_link = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The Analytics property to change the ServiceLevel setting. This
  // field is the name of the Google Analytics Admin API property resource.
  //
  // Format: analyticsadmin.googleapis.com/properties/{property_id}
  string analytics_property = 2 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "analyticsadmin.googleapis.com/Property"
    }
  ];

  // Required. The service level to set for this property.
  AnalyticsServiceLevel service_level = 3
      [(google.api.field_behavior) = REQUIRED];
}

// Response message for SetPropertyServiceLevel RPC.
message SetPropertyServiceLevelResponse {}

// Request message for ReportPropertyUsage RPC.
message ReportPropertyUsageRequest {
  // Required. Specifies the organization whose property usage will be listed.
  //
  // Format: organizations/{org_id}
  string organization = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The target month to list property usages.
  //
  // Format: YYYY-MM. For example, "2025-05"
  string month = 2 [(google.api.field_behavior) = REQUIRED];
}

// Response message for ReportPropertyUsage RPC.
message ReportPropertyUsageResponse {
  // Contains the count of events received by the property, along with metadata
  // that influences the volume of `billable` events.
  message PropertyUsage {
    // The name of the Google Analytics Admin API property resource.
    //
    // Format: analyticsadmin.googleapis.com/properties/{property_id}
    string property = 1;

    // The display name of the property.
    string display_name = 2;

    // The ID of the property's parent account.
    int64 account_id = 3;

    // The service level of the property.
    AnalyticsServiceLevel service_level = 4;

    // The subtype of the analytics property. This affects the billable event
    // count.
    AnalyticsPropertyType property_type = 5;

    // Total event count that the property received during the requested month.
    int64 total_event_count = 6;

    // The number of events for which the property is billed in the requested
    // month.
    int64 billable_event_count = 7;
  }

  // Contains the bill amount.
  message BillInfo {
    // The amount of the monthly base fee.
    google.type.Money base_fee = 1;

    // The amount of the event fee.
    google.type.Money event_fee = 2;

    // The amount of the price protection credit, this is only available for
    // eligible customers.
    google.type.Money price_protection_credit = 3;

    // The total amount of the bill.
    google.type.Money total = 4;
  }

  // Usage data for all properties in the specified organization and month.
  repeated PropertyUsage property_usages = 1;

  // Bill amount in the specified organization and month.
  //
  // Will be empty if user only has access to usage data.
  BillInfo bill_info = 2;
}