// 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.shopping.merchant.notifications.v1;

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.Shopping.Merchant.Notifications.V1";
option go_package = "cloud.google.com/go/shopping/merchant/notifications/apiv1/notificationspb;notificationspb";
option java_multiple_files = true;
option java_outer_classname = "NotificationsApiProto";
option java_package = "com.google.shopping.merchant.notifications.v1";
option php_namespace = "Google\\Shopping\\Merchant\\Notifications\\V1";
option ruby_package = "Google::Shopping::Merchant::Notifications::V1";
option (google.api.resource_definition) = {
  type: "merchantapi.googleapis.com/Account"
  pattern: "accounts/{account}"
};

// Service to manage notification subscriptions for merchants
service NotificationsApiService {
  option (google.api.default_host) = "merchantapi.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/content";

  // Gets notification subscriptions for an account.
  rpc GetNotificationSubscription(GetNotificationSubscriptionRequest)
      returns (NotificationSubscription) {
    option (google.api.http) = {
      get: "/notifications/v1/{name=accounts/*/notificationsubscriptions/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Creates a notification subscription for a business.
  // For standalone or subaccounts accounts, the business can create a
  // subscription for self. For MCAs, the business can create a
  // subscription for all managed accounts or for a specific subaccount.
  //
  // We will allow the following types of notification subscriptions to exist
  // together (per business as a subscriber per event type):
  //
  // 1. Subscription for all managed accounts + subscription for self.
  //
  // 2. Multiple "partial" subscriptions for managed accounts + subscription
  // for self.
  //
  // we will not allow (per business as a subscriber per event type):
  //
  // 1. Multiple self subscriptions.
  //
  // 2. Multiple "all managed accounts" subscriptions.
  //
  // 3. "All managed accounts" subscription and partial subscriptions at the
  // same time.
  //
  // 4. Multiple partial subscriptions for the same target account.
  rpc CreateNotificationSubscription(CreateNotificationSubscriptionRequest)
      returns (NotificationSubscription) {
    option (google.api.http) = {
      post: "/notifications/v1/{parent=accounts/*}/notificationsubscriptions"
      body: "notification_subscription"
    };
    option (google.api.method_signature) = "parent,notification_subscription";
  }

  // Updates an existing notification subscription for a merchant.
  rpc UpdateNotificationSubscription(UpdateNotificationSubscriptionRequest)
      returns (NotificationSubscription) {
    option (google.api.http) = {
      patch: "/notifications/v1/{notification_subscription.name=accounts/*/notificationsubscriptions/*}"
      body: "notification_subscription"
    };
    option (google.api.method_signature) =
        "notification_subscription,update_mask";
  }

  // Deletes a notification subscription for a merchant.
  rpc DeleteNotificationSubscription(DeleteNotificationSubscriptionRequest)
      returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/notifications/v1/{name=accounts/*/notificationsubscriptions/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Gets all the notification subscriptions for a merchant.
  rpc ListNotificationSubscriptions(ListNotificationSubscriptionsRequest)
      returns (ListNotificationSubscriptionsResponse) {
    option (google.api.http) = {
      get: "/notifications/v1/{parent=accounts/*}/notificationsubscriptions"
    };
    option (google.api.method_signature) = "parent";
  }

  // Retrieves notification subscription health metrics for a merchant.
  // We recommend calling this periodically (hourly or daily) to monitor health
  // of your callback endpoint.
  rpc GetNotificationSubscriptionHealthMetrics(
      GetNotificationSubscriptionHealthMetricsRequest)
      returns (NotificationSubscriptionHealthMetrics) {
    option (google.api.http) = {
      get: "/notifications/v1/{name=accounts/*/notificationsubscriptions/*}:getHealth"
    };
    option (google.api.method_signature) = "name";
  }
}

// Request message for the GetNotificationSubscription method.
message GetNotificationSubscriptionRequest {
  // Required. The `name` of the notification subscription.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "merchantapi.googleapis.com/NotificationSubscription"
    }
  ];
}

// Request message for the CreateNotificationSubscription method.
message CreateNotificationSubscriptionRequest {
  // Required. The merchant account that owns the new notification subscription.
  // Format: `accounts/{account}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "merchantapi.googleapis.com/NotificationSubscription"
    }
  ];

  // Required. The notification subscription to create.
  NotificationSubscription notification_subscription = 2
      [(google.api.field_behavior) = REQUIRED];
}

// Request message for the UpdateNotificationSubscription method.
message UpdateNotificationSubscriptionRequest {
  // Required. The new version of the notification subscription that should be
  // updated.
  NotificationSubscription notification_subscription = 1
      [(google.api.field_behavior) = REQUIRED];

  // List of fields being updated.
  google.protobuf.FieldMask update_mask = 2;
}

// Request message for the DeleteNotificationSubscription method.
message DeleteNotificationSubscriptionRequest {
  // Required. The name of the notification subscription to be deleted.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "merchantapi.googleapis.com/NotificationSubscription"
    }
  ];
}

// Request message for the ListNotificationSubscription method.
message ListNotificationSubscriptionsRequest {
  // Required. The merchant account who owns the notification subscriptions.
  // Format: `accounts/{account}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "merchantapi.googleapis.com/NotificationSubscription"
    }
  ];

  // The maximum number of notification subscriptions to return in a page.
  // The default value for `page_size` is 100. The
  // maximum value is `200`. Values above `200` will be coerced to `200`.
  int32 page_size = 2;

  // Token (if provided) to retrieve the subsequent page. All other parameters
  // must match the original call that provided the page token.
  string page_token = 3;
}

// Response message for the ListNotificationSubscription method.
message ListNotificationSubscriptionsResponse {
  // The list of notification subscriptions requested by the merchant.
  repeated NotificationSubscription notification_subscriptions = 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;
}

// Represents a notification subscription owned by a Merchant account.
message NotificationSubscription {
  option (google.api.resource) = {
    type: "merchantapi.googleapis.com/NotificationSubscription"
    pattern: "accounts/{account}/notificationsubscriptions/{notification_subscription}"
  };

  // Represents the event type that the merchant is interested in receiving
  // notifications for.
  enum NotificationEventType {
    // Notifications event type is unspecified.
    NOTIFICATION_EVENT_TYPE_UNSPECIFIED = 0;

    // Notification of product status changes, for example when product becomes
    // disapproved.
    PRODUCT_STATUS_CHANGE = 1;
  }

  oneof interested_in {
    // If this value is true, the requesting account is notified of the
    // specified event for all managed accounts (can be subaccounts or other
    // linked accounts) including newly added accounts on a daily basis.
    bool all_managed_accounts = 3;

    // The `name` of the account you want to receive notifications for.
    // Format: `accounts/{account}`
    string target_account = 4;
  }

  // Output only. The `name` of the notification configuration. Generated by the
  // Content API upon creation of a new `NotificationSubscription`. The
  // `account` represents the merchant ID of the merchant that owns the
  // configuration. Format:
  // `accounts/{account}/notificationsubscriptions/{notification_subscription}`
  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The event that the merchant wants to be notified about.
  NotificationEventType registered_event = 2;

  // URL to be used to push the notification to the merchant.
  string call_back_uri = 5;
}

// Request for notification subscription health metrics.
message GetNotificationSubscriptionHealthMetricsRequest {
  // Required. The `name` of the notification subscription for which metrics are
  // retrieved.
  // Format:
  // `accounts/{account}/notificationsubscriptions/{notification_subscription}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "merchantapi.googleapis.com/NotificationSubscriptionHealthMetrics"
    }
  ];
}

// Represents a notification subscription health metrics.
message NotificationSubscriptionHealthMetrics {
  option (google.api.resource) = {
    type: "merchantapi.googleapis.com/NotificationSubscriptionHealthMetrics"
    pattern: "accounts/{account}/notificationsubscriptions/{notification_subscription}"
  };

  // Output only. Identifier. The name of the notification configuration.
  // Generated by the Content API upon creation of a new
  // NotificationSubscription. The account represents the merchant ID of the
  // merchant that owns the configuration.
  string name = 1 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.field_behavior) = IDENTIFIER
  ];

  // The number of retained acknowledged messages for the last 24 hours
  int64 acknowledged_messages_count = 2;

  // The number of unacknowledged messages for the last 7 days, we will attempt
  // to re-deliver the unacknowledged message later and once successfully
  // delivered it will not be counted within unacknowledged messages (the number
  // of unacknowledged messages should gradually decrease to zero once the issue
  // is fixed).
  int64 undelivered_messages_count = 3;

  // The time since the oldest unacknowledged message was sent in seconds
  int64 oldest_unacknowledged_message_waiting_time = 4;
}