// 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.ordertracking.v1beta;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/shopping/type/types.proto";
import "google/type/datetime.proto";

option csharp_namespace = "Google.Shopping.Merchant.OrderTracking.V1Beta";
option go_package = "cloud.google.com/go/shopping/merchant/ordertracking/apiv1beta/ordertrackingpb;ordertrackingpb";
option java_multiple_files = true;
option java_outer_classname = "OrderTrackingSignalsProto";
option java_package = "com.google.shopping.merchant.ordertracking.v1beta";
option php_namespace = "Google\\Shopping\\Merchant\\OrderTracking\\V1beta";
option ruby_package = "Google::Shopping::Merchant::OrderTracking::V1beta";
option (google.api.resource_definition) = {
  type: "merchantapi.googleapis.com/Account"
  pattern: "accounts/{account}"
};

// Service to serve order tracking signals public API.
service OrderTrackingSignalsService {
  option (google.api.default_host) = "merchantapi.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/content";

  // Creates new order tracking signal.
  rpc CreateOrderTrackingSignal(CreateOrderTrackingSignalRequest)
      returns (OrderTrackingSignal) {
    option (google.api.http) = {
      post: "/ordertracking/v1beta/{parent=accounts/*}/ordertrackingsignals"
      body: "order_tracking_signal"
    };
    option (google.api.method_signature) = "parent,order_tracking_signal_id";
  }
}

// Signals only can be created but not updated.
// Businesses need to call this API only when the order is completely shipped.
// Creates new order signal.
message CreateOrderTrackingSignalRequest {
  // Required. The account of the business for which the order signal is
  // created. Format: accounts/{account}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "merchantapi.googleapis.com/Account"
    }
  ];

  // Output only. The ID that uniquely identifies this order tracking signal.
  string order_tracking_signal_id = 2
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. The order signal to be created.
  OrderTrackingSignal order_tracking_signal = 3
      [(google.api.field_behavior) = REQUIRED];
}

// Represents a business trade from which signals are extracted, such as
// shipping.
message OrderTrackingSignal {
  // The shipping information for the order.
  message ShippingInfo {
    // The current status of the shipments.
    enum ShippingState {
      // The shipping status is not known to business.
      SHIPPING_STATE_UNSPECIFIED = 0;

      // All items are shipped.
      SHIPPED = 1;

      // The shipment is already delivered.
      DELIVERED = 2;
    }

    // Required. The shipment ID. This field will be hashed in returned
    // OrderTrackingSignal creation response.
    string shipment_id = 1 [(google.api.field_behavior) = REQUIRED];

    // Optional. The tracking ID of the shipment. This field is required if one
    // of the following fields is absent: earliest_delivery_promise_time,
    // latest_delivery_promise_time, and actual_delivery_time.
    string tracking_id = 2 [(google.api.field_behavior) = OPTIONAL];

    // Optional. The name of the shipping carrier for the delivery. This field
    // is required if one of the following fields is absent:
    // earliest_delivery_promise_time, latest_delivery_promise_time,
    // and actual_delivery_time.
    string carrier = 3 [(google.api.field_behavior) = OPTIONAL];

    // Optional. The service type for fulfillment, such as GROUND, FIRST_CLASS,
    // etc.
    string carrier_service = 4 [(google.api.field_behavior) = OPTIONAL];

    // Optional. The time when the shipment was shipped.
    // Include the year and timezone string, if available.
    google.type.DateTime shipped_time = 5
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. The earliest delivery promised time.
    // Include the year and timezone string, if available.
    // This field is required, if one of the following fields is absent:
    // tracking_id or carrier_name.
    google.type.DateTime earliest_delivery_promise_time = 6
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. The latest delivery promised time.
    // Include the year and timezone string, if available.
    // This field is required, if one of the following fields is absent:
    // tracking_id or carrier_name.
    google.type.DateTime latest_delivery_promise_time = 7
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. The time when the shipment was actually delivered.
    // Include the year and timezone string, if available.
    // This field is required, if one of the following fields is absent:
    // tracking_id or carrier_name.
    google.type.DateTime actual_delivery_time = 8
        [(google.api.field_behavior) = OPTIONAL];

    // Required. The status of the shipment.
    ShippingState shipping_status = 9 [(google.api.field_behavior) = REQUIRED];

    // Required. The origin postal code, as a continuous string without spaces
    // or dashes, for example "95016". This field will be anonymized in returned
    // OrderTrackingSignal creation response.
    string origin_postal_code = 10 [(google.api.field_behavior) = REQUIRED];

    // Required. The [CLDR territory code]
    // (http://www.unicode.org/repos/cldr/tags/latest/common/main/en.xml) for
    // the shipping origin.
    string origin_region_code = 11 [(google.api.field_behavior) = REQUIRED];
  }

  // The line items of the order.
  message LineItemDetails {
    // Required. The ID for this line item.
    string line_item_id = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. The Content API REST ID of the product, in the
    // form channel:contentLanguage:targetCountry:offerId.
    string product_id = 2 [(google.api.field_behavior) = REQUIRED];

    // Optional. The Global Trade Item Number.
    string gtin = 3 [(google.api.field_behavior) = OPTIONAL];

    // Optional. The manufacturer part number.
    string mpn = 4 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Plain text title of this product.
    optional string product_title = 5 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Brand of the product.
    optional string brand = 6 [(google.api.field_behavior) = OPTIONAL];

    // Required. The quantity of the line item in the order.
    int64 quantity = 7 [(google.api.field_behavior) = REQUIRED];
  }

  // Represents how many items are in the shipment for the given shipment_id
  // and line_item_id.
  message ShipmentLineItemMapping {
    // Required. The shipment ID. This field will be hashed in returned
    // OrderTrackingSignal creation response.
    string shipment_id = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. The line item ID.
    string line_item_id = 2 [(google.api.field_behavior) = REQUIRED];

    // Required. The line item quantity in the shipment.
    int64 quantity = 3 [(google.api.field_behavior) = REQUIRED];
  }

  // Output only. The ID that uniquely identifies this order tracking signal.
  int64 order_tracking_signal_id = 11
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The Google Merchant Center ID of this order tracking signal. This
  // value is optional. If left unset, the caller's Merchant Center ID is used.
  // You must request access in order to provide data on behalf of another
  // business. For more information, see [Submitting Order Tracking
  // Signals](/shopping-content/guides/order-tracking-signals).
  int64 merchant_id = 12 [(google.api.field_behavior) = OPTIONAL];

  // Required. The time when the order was created on the businesses side.
  // Include the year and timezone string, if available.
  google.type.DateTime order_created_time = 1
      [(google.api.field_behavior) = REQUIRED];

  // Required. The ID of the order on the businesses side. This field will be
  // hashed in returned OrderTrackingSignal creation response.
  string order_id = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The shipping information for the order.
  repeated ShippingInfo shipping_info = 3
      [(google.api.field_behavior) = REQUIRED];

  // Required. Information about line items in the order.
  repeated LineItemDetails line_items = 4
      [(google.api.field_behavior) = REQUIRED];

  // Optional. The mapping of the line items to the shipment information.
  repeated ShipmentLineItemMapping shipment_line_item_mapping = 5
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The shipping fee of the order;
  // this value should be set to zero in the case of free shipping.
  optional google.shopping.type.Price customer_shipping_fee = 6
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The delivery postal code, as a continuous string without spaces
  // or dashes, for example "95016". This field will be anonymized in returned
  // OrderTrackingSignal creation response.
  string delivery_postal_code = 9 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The [CLDR territory code]
  // (http://www.unicode.org/repos/cldr/tags/latest/common/main/en.xml) for
  // the shipping destination.
  string delivery_region_code = 10 [(google.api.field_behavior) = OPTIONAL];
}