syntax = "proto3";

package wix.dealerOffersServing.api.v1;

import "google/api/annotations.proto";
import "wix/api/annotations.proto";
import "wix/api/validations.proto";
import "wix/api/entity.proto";
import "google/protobuf/wrappers.proto";
import "wix/api/permissions.proto";

import "wix/dealerOffersServing/api/v1/offer.proto";
import "wix/dealerBackoffice/api/v1/frequency-caps.proto";
import "wix/dealerBackoffice/api/v1/placements.proto";

option java_package = "com.wix.dealerOffersServing.api.v1";

// Main runtime endpoint of the Dealer.
// TODO: add explicit permission
// https://bo.wix.com/wix-docs/rnd/platformization-guidelines/authorization-&-permissions#platformization-guidelines_authorization-&-permissions_1-in-your-proto-files
service DealerOffersServing {
  option (wix.api.service_entity).message = "wix.dealerOffersServing.api.v1.Offer";
  option (wix.api.service_maturity) = GA;
  option (wix.api.service_exposure) = INTERNAL;

  // Get all offers the user or site are eligible for.
  // A realEstateId (placementId) defines the product location of the offers and is always required,
  // Context is taken implicitly from request with authorization header and wix session.
  rpc ListOffers (ListOffersRequest) returns (ListOffersResponse) {
    option (google.api.http) = {
      post: "/v1/dealer/serving/offers/list"
      additional_bindings: {
        get: "/v1/dealer/serving/offers"
      }
    };
    option (wix.api.required) = "ListOffersRequest.real_estate_id";
  }

  // Get a single offer if the user or site are eligible for.
  // Context is taken implicitly from request with authorization header and wix session.
  rpc ResolveOffer (ResolveOfferRequest) returns (ResolveOfferResponse) {
    option (google.api.http) = {
      post: "/v1/dealer/serving/offer/resolve"
      additional_bindings: {
        get: "/v1/dealer/serving/offer/resolve"
      }
    };
    option (wix.api.required) = "ResolveOfferRequest.offer_id";
  }

  // Get all offers the user or site are eligible for.
  // This is a bulk request for more then one realEstate (placement),
  // max limit of 30 offers is applied for each placement.
  // Context is taken implicitly from request with authorization header and wix session.
  rpc ListOffersBulk (ListOffersBulkRequest) returns (ListOffersBulkResponse) {
    option (google.api.http) = {
      post: "/v1/dealer/serving/offers/bulk"
      additional_bindings: {
        get: "/v1/dealer/serving/offers/bulk"
      }
    };
    option (wix.api.required) = "ListOffersBulkRequest.real_estate_ids";
  }
}

// Params required to list offers for given placement (real estate).
message ListOffersRequest {
  // Dealer placement guid (product location). Required.
  string real_estate_id = 1;

  // Only <= limit number of offers returned if more are applicable. Optional, default limit is 30 offers
  google.protobuf.Int32Value limit = 2;

  // Which offers to exclude from results. Optional.
  repeated string exclude_offer_ids = 3 [(wix.api.format) = GUID];

  reserved 4;

  // DEPRECATED - plz use server signer.
  // Optional - override specific fields that by default coming from aspects
  // if not set will be taken implicitly from request
  RequestExtensions extensions = 5;

  // Deviant Art specific use-case: signed jwt token with uuid of deviant art user in wix bi infra
  google.protobuf.StringValue deviant_art_user_id = 6;

  // List of custom param's values, some offers are targeted by those values. Optional
  repeated CustomParam custom_params = 7;

  // Optional - Enable to override or abort frequency caps configuration
  // if not set, the default offer or placement frequency caps hierarchy will be used (if configured)
  FrequencyCapsRequestOverrides frequency_caps_overrides = 8;

  // SkipTargeting flag allows bypassing the targeting validation and retrieving all live offers, regardless of user/site eligibility. Optional.
  google.protobuf.BoolValue skip_targeting = 9;

  // Optional - Enable to override the placement default prioritization strategy configuration
  PrioritizationStrategyOverrides prioritization_strategy_overrides = 10;

  message FrequencyCapsRequestOverrides {
    //Set of frequency caps conditions to use in the request
    //Set as null if you want to abort the frequency caps for this request (this will also follow the override type behaviour)
    wix.dealerBackoffice.api.v1.FrequencyCaps.Conditions conditions = 1;
    //Mandatory - this controls the conditions overrides behaviour and must be one of those 2 types:
    //PLACEMENT_LEVEL - Will only be applied for offers without frequency caps
    //OFFER_LEVEL - Will be applied to all offers with or without frequency caps
    FrequencyCapsOverridesType type = 2;

    enum FrequencyCapsOverridesType {
      UNKNOWN = 0;
      PLACEMENT_LEVEL = 1;
      OFFER_LEVEL = 2;
    }
  }

  message PrioritizationStrategyOverrides {
    // Set of prioritization strategy conditions to use in the request
    wix.dealerBackoffice.api.v1.Placement.PrioritizationStrategyConfig prioritization_strategy_config = 1;
  }
}

// Params required to list offers for multiple placements (real estates) in a single call.
message ListOffersBulkRequest {

  // List of dealer real estates (placements). Required.
  repeated string real_estate_ids = 1 [(wix.api.minSize) = 1];

  // Excluded offer ids will never be returend to the user. Optional
  repeated string exclude_offer_ids = 2 [(wix.api.format) = GUID];

  reserved 3;

  // DEPRECATED
  // This data overrides specific fields coming from aspects if not set will be taken implicitly from request.
  // Optional.
  RequestExtensions extensions = 4;

  // List of custom param's values, some offers are targeted by those values. Optional.
  repeated CustomParam custom_params = 5;

  // SkipTargeting flag allows bypassing the targeting validation and retrieving all live offers, regardless of user/site eligibility. Optional.
  google.protobuf.BoolValue skip_targeting = 6;
}

// Input params for evaluating the offer.
message ResolveOfferRequest {
  // Offer guid to evaluate
  string offer_id = 1;

  // List of custom param's values, some offers are targeted by those values. Optional
  repeated CustomParam custom_params = 2;
}


// DEPRECATED
// Explicit metasite id request option.
message RequestExtensions {
  // User needs permission DEALER.OFFERS_SERVING_SITE_TARGETING to pass it. Optional.
  google.protobuf.StringValue site_id = 1 [(wix.api.format) = GUID];
}

// All eligible offers with personalized content for given request params & aspects.
message ListOffersResponse {
  // Offers eligible for correspondent request at the moment of the call
  repeated Offer offers = 1;
}

// Return the requested offer (if eligible) with personalized content for given request params & aspects.
message ResolveOfferResponse {
  // Offer being inspected
  Offer offer = 1;
}

message ListOffersBulkResponse {
  // a map from realEstate(placement) id to list of offers
  map<string, ListOffersResponse> real_estates = 1;
}
