syntax = "proto3";

package wix.items_selection.spi_host.v1;
option java_package = "com.wixpress.items_selection.spi_host.v1";

import "google/api/annotations.proto";
import "wix/api/annotations.proto";
import "wix/api/entity.proto";
import "wix/api/permissions.proto";
import "wix/api/validations.proto";
import "wix/api/api_errors.proto";
import "wix/common/paging.proto";
import "src/main/proto/com/wixpress/items_selection/spi/v1/items_selection_spi.proto";
import "src/main/proto/com/wixpress/items_selection/spi/v1/items_selection_config.proto";
import "wix/api/errors.proto";

service ItemsSelectionService {
    option (.wix.api.service_entity).message = "wix.items_selection.spi_host.v1.ItemsSelectionProvider";
    option (wix.api.service_maturity) = BETA;
    option (wix.api.service_exposure) = PUBLIC;
    /**
        Returns list of installed app providers for a specific site
     */
    //flynt-disable missing-autovelo-def
    rpc ListInstalledProviders(ListInstalledProvidersRequest) returns (ListInstalledProvidersResponse) {
        option (.google.api.http).get = "/v1/items-selection/installed-providers";
        option (.wix.api.permission).name = "ITEMS_SELECTION.LIST_INSTALLED_PROVIDERS";
    }

    /**
        Returns list of all existing providers
     */
    rpc ListProviders(ListProvidersRequest) returns (ListProvidersResponse) {
        option (.google.api.http).post = "/v1/items-selection/providers";
        option (.wix.api.permission).name = "ITEMS_SELECTION.LIST_PROVIDERS";
    }

    /**
        Retrieves a list of items that match the specified criteria.

        Returns:
            - A list of items that match the search criteria.
            - Metadata about the search results, such as the total number of items and pagination information.
     */
    rpc QueryItems(QueryItemsRequest) returns (QueryItemsResponse) {
        option (.google.api.http).post = "/v1/items-selection/{provider_key}/items";
        option (.wix.api.permission).name = "ITEMS_SELECTION.LIST_ITEMS";

        option (.wix.api.required) = "QueryItemsRequest.provider_key";

        option (.wix.api.error) = {
            http_code: NOT_FOUND
            application_code: "PROVIDER_NOT_FOUND"
        };
    }
}

message ItemsSelectionProvider {
    option (wix.api.entity) = {
        fqdn: "wix.items_selection.spi_host.v1.provider",
        segment: USERS
    };

    // Provider unique identifier.
    string key = 1;

    // The app ID of the provider.
    string app_id = 2;

    // Supported search params.
    com.wixpress.items_selection.spi.v1.ItemsSelectionProviderConfig.SearchParams search_params = 3;

    // Visual content data like provider name and icon.
    com.wixpress.items_selection.spi.v1.ItemsSelectionProviderConfig.ContentData content_data = 4;

    // Optional additional step taken after the initial item selection.
    com.wixpress.items_selection.spi.v1.ItemsSelectionProviderConfig.AdditionalStepInfo additional_step_info = 5;

    // Optional supported tags, used to change the content of the request based on specified tag.
    repeated com.wixpress.items_selection.spi.v1.ItemsSelectionProviderConfig.Tag supported_tags = 6 [(wix.api.maxSize) = 50];

    // Optional add new button info to create during initial item selection.
    com.wixpress.items_selection.spi.v1.ItemsSelectionProviderConfig.CreateNewItemInfo create_new_item_info = 7;

    // Optional configuration settings for how the thumbnail is displayed.
    com.wixpress.items_selection.spi.v1.ItemsSelectionProviderConfig.ItemThumbnail item_thumbnail = 8;

    reserved 9;

    // Pagination Mode
    com.wixpress.items_selection.spi.v1.ItemsSelectionProviderConfig.PaginationMode pagination_mode = 10;

    // Additional fields associated with the provider.
    repeated com.wixpress.items_selection.spi.v1.ItemsSelectionProviderConfig.TagOverridesEntry tags_overrides = 11 [(.wix.api.maxSize) = 100, (.wix.api.field_exposure) = INTERNAL];

    // Optional render overrides for the provider.
    com.wixpress.items_selection.spi.v1.ItemsSelectionProviderConfig.RenderOverrides render_overrides = 12;
}

message ListInstalledProvidersRequest {
    // An optional tag to filter providers that have been tagged with the specified tag.
    com.wixpress.items_selection.spi.v1.ItemsSelectionProviderConfig.Tag tag = 1;
}

message ListInstalledProvidersResponse {
    // List of installed providers.
    repeated ItemsSelectionProvider providers = 1;
}

message ListProvidersRequest {
    // An optional tag to filter providers that have been tagged with the specified tag.
    com.wixpress.items_selection.spi.v1.ItemsSelectionProviderConfig.Tag tag = 1;
}

message ListProvidersResponse {
    // List of registered providers.
    repeated ItemsSelectionProvider providers = 1;
}

message QueryItemsRequest {
    // The provider key used to identify the provider being queried.
    string provider_key = 1;

    // An optional query object containing search parameters and filtering criteria.
    com.wixpress.items_selection.spi.v1.Query query = 2;

    // An optional tag to change the content of the request.
    com.wixpress.items_selection.spi.v1.ItemsSelectionProviderConfig.Tag tag = 3;
}

message QueryItemsResponse {
    // Items.
    repeated com.wixpress.items_selection.spi.v1.Item items = 1;

    // Pagination.
    wix.common.PagingMetadataV2 paging_metadata = 2;

    // Optional rendering overrides.
    com.wixpress.items_selection.spi.v1.RenderOverrides render_overrides = 3;
}
