syntax = "proto3";

package com.wixpress.items_selection.spi.v1;

import "google/protobuf/wrappers.proto";
import "google/api/annotations.proto";
import "wix/api/annotations.proto";
import "wix/api/validations.proto";
import "wix/spi/definitions.proto";
import "wix/common/paging.proto";
import "wix/common/sorting.proto";
import "google/protobuf/struct.proto";
import "src/main/proto/com/wixpress/items_selection/spi/v1/items_selection_config.proto";
import "src/main/proto/com/wixpress/items_selection/spi/v1/image.proto";
import "src/main/proto/com/wixpress/items_selection/spi/v1/additional_data.proto";
import "com/wixpress/items_selection/spi/v1/query_items_empty_state.proto";

import "wix/api/entity.proto";

service ItemsSelectionProviderService {
  option (.wix.api.service_exposure) = PUBLIC;
  option (.wix.spi.service) = {
    spi_identifier: "com.wixpress.appservice.api.ComponentType.ITEMS_SELECTION_PROVIDER",
    config_message: "com.wixpress.items_selection.spi.v1.ItemsSelectionProviderConfig",
    host_service: "wix.items_selection.spi_host.v1.ItemsSelectionService",
    app_id: "a1313905-2aa8-4e8c-a5eb-ddf623c2deb1",
    fqdn: "wix.interfaces.items_selection.v1.items_selection_provider",
    appendix_files: {
      type: DOCS_CONF
      path: "appendices/docs"
    }
  };

  /*
   This endpoint retrieves a list of items that match the search criteria specified in the request.

   Wix calls this endpoint when a service within the Wix ecosystem wants to make an app's items available for selection in the Wix UI. For example, this endpoint is called when a Wix site owner wants to add an app's item to an existing Wix Stores order.

   > You cannot try out this endpoint because it has to be implemented by
   > an app and can have an arbitrary URL. Therefore, ignore the **Authorization**
   > and **POST** sections below as well as the **Try It Out** button.
   */
  rpc QueryItems (QueryItemsRequest) returns (QueryItemsResponse) {
    option (.google.api.http).post = "/v1/items";

    option (.wix.spi.error) = {
      name: "QueryItemsFailed"
      http_code: INTERNAL
      application_code: "QUERY_ITEMS_FAILED"
      data: "com.wixpress.items_selection.spi.v1.FailureData"
    };
  };
}

message FailureData {
  // Error details.
  QueryError error = 1;
}

message QueryError {
  enum Code {
    NONE = 0;
    SYSTEM_ERROR = 1;
    OTHER = 2;
  }

  // Error code.
  Code code = 1;

  // Error message.
  string message = 2;

  // Raw error data.
  google.protobuf.Struct data = 3;
}

message QueryItemsRequest {
  // Query options.
  Query query = 1;

  // A tag representing the Wix service requesting the list of items.
  ItemsSelectionProviderConfig.Tag tag = 2;
}

message QueryItemsResponse {
  // List of items.
  repeated Item items = 1;

  // Details on the paged set of results returned.
  wix.common.PagingMetadataV2 paging_metadata = 2;

  // Optional rendering overrides.
  RenderOverrides render_overrides = 3;
}

message RenderOverrides {
  // Optional empty state UI configuration for empty query items response.
  QueryItemsEmptyState empty_state = 1;

  // Total text to display in a custom consumer UI, for example "10 products", "1 service". The content of this text might change based on the Wix service defined in the `tag` field.
  google.protobuf.StringValue total_text = 2 [(wix.api.maxLength) = 200];
}

message Query {
  /* Filter object.
  See [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language) for more information.
  */
  google.protobuf.Struct filter = 1;

  // An optional repeated field that allows to specify sorting criteria for the search results.
  repeated wix.common.Sorting sort = 2 [deprecated = true, (.wix.api.field_exposure) = PRIVATE];

  /* Plain text search for an exact match.

  Supported properties are defined in the `searchParams.fields` property of the Item Selection Provider configuration in the Wix Developers Center.

  Max: 100 characters
*/
  google.protobuf.StringValue search = 3;

  oneof paging_method {
    // Paging options to limit and skip the number of items.
    wix.common.Paging paging = 4;
    // Cursor token pointing to a page of results. Not used in the first request. Following requests include a cursor token and do not define `filter`.
    wix.common.CursorPaging cursor_paging = 5;
  }
}

//flynt-disable deleted-field-enum-reserved
message Item {
  // Item ID.
  string id = 1;

  // Item name.
  google.protobuf.StringValue name = 2 [(.wix.api.maxLength) = 250];

  // Item description.
  google.protobuf.StringValue description = 3 [(.wix.api.maxLength) = 1000];

  // Item image.
  Image image = 4;

  // Additional information about the item. For example, an item's price.
  google.protobuf.StringValue note = 5 [(.wix.api.maxLength) = 100];

  // Indicates whether the item has additional steps, additional step will replace any existing additional_data exists on the item.
  google.protobuf.BoolValue has_additional_step = 6 [(.wix.api.field_exposure) = INTERNAL];

  // Additional data associated with an item. The content of this object changes based on the Wix service defined in the `tag` field.
  AdditionalData additional_data = 7 [(.wix.api.field_exposure) = PRIVATE, deprecated = true, (.wix.api.field_deprecated) = {
    replaced_by: "additional_fields"
    target_removal_date: "2025-01-01"
  }];

  // Additional fields associated with an item. The content of this object might changes based on the Wix service defined in the `tag` field.
  //flynt-disable renamed-field-breaking-change
  google.protobuf.Struct additional_fields = 8;
}
