edition = "2023";

package com.iabtechlab.bidstream.mutation.v1;

// Import OpenRTB definitions for BidRequest and BidResponse
import "com/iabtechlab/openrtb/v2.6/openrtb.proto";

// ------------------- Messages -------------------

message RTBRequest {
  // As per Programmatic Auction Definition IAB TL doc/spec
  Lifecycle lifecycle = 1;

  // ID of the extension point request, assigned by the exchange, and unique for the
  // exchange's subsequent tracking of the responses. The exchange may use
  // different values for different recipients.
  string id = 2;

  // Maximum time in milliseconds the exchange allows for mutations to be received including latency to avoid timeout
  int32 tmax = 3;

  // Bid request
  com.iabtechlab.openrtb.v2.BidRequest bid_request = 4;

  // Bid response
  com.iabtechlab.openrtb.v2.BidResponse bid_response = 5;

  // Business entity that created and owns the enclosed BidRequest or BidResponse
  Originator originator = 6;

  // List of intents the server is eligibible to send back
  repeated Intent applicable_intents = 7;

  // Extension fields
  Ext ext = 99;

  message Ext {
    extensions 500 to max;
  }
}

enum Lifecycle {
  // Placeholder to Define Programmatic Auction Definition Stages
  LIFECYCLE_UNSPECIFIED = 0;

  LIFECYCLE_PUBLISHER_BID_REQUEST = 1;

  LIFECYCLE_DSP_BID_RESPONSE = 2;

  // More to be added
}

message RTBResponse {
  // ID of the extension point request to which this is a response.
  string id = 1;

  // List of mutations suggesting changes to be applied
  repeated Mutation mutations = 2;

  // Metadata about the response
  Metadata metadata = 3;
}

message Originator {
  enum Type {
    TYPE_UNSPECIFIED = 0;
    TYPE_PUBLISHER = 1;
    TYPE_SSP = 2;
    TYPE_EXCHANGE = 3;
    TYPE_DSP = 4;
  }

  Type type = 1;
  string id = 2;
}

message Mutation {
  // The purpose of the mutation
  Intent intent = 1;

  // Defines the operation to perform (e.g. add, remove, replace) on the target data at the given path
  Operation op = 2;

  // The semantic business domain of where the operation will be applied
  string path = 3;

  // The structure of value depends on the specified intent.
  // Reserve 100+ for intent-specific payloads
  oneof value {
    // List of string Identifiers
    IDsPayload ids = 100;

    // Adjust properties of a specific deal
    AdjustDealPayload adjust_deal = 101;

    // Adjust the bid price
    AdjustBidPayload adjust_bid = 102;

    // Metrics or telemetry data
    MetricsPayload metrics = 103;

    // Content data
    DataPayload content_data = 104;
  }

  // Reserved for experimental/test payloads
  reserved 1000 to 1999;
}

enum Operation {
  OPERATION_UNSPECIFIED = 0;
  OPERATION_ADD = 1;
  OPERATION_REMOVE = 2;
  OPERATION_REPLACE = 3;

  // More operations can be added in the future
}

enum Intent {
  INTENT_UNSPECIFIED = 0;

  // Activate user segments by their external segment IDs
  ACTIVATE_SEGMENTS = 1;

  // Activate deals by their external deal IDs
  ACTIVATE_DEALS = 2;

  // Suppress deals by their external deal IDs
  SUPPRESS_DEALS = 3;

  // Adjust the bid floor of a specific deal
  ADJUST_DEAL_FLOOR = 4;

  // Adjust the deal margin of a specific deal
  ADJUST_DEAL_MARGIN = 5;

  // Adjust the bid price of a specific bid
  BID_SHADE = 6;

  // Add metrics to an impression
  ADD_METRICS = 7;

  // Add extended content IDs
  ADD_CIDS = 8;

  // More intents can be added in the future

  // Reserved for experimental/test intents
  reserved 1000 to 1999;
}

message Metadata {
  // Version of the data provider API
  string api_version = 1;

  // The model version utilized by the container or API to compute the mutation if applicable
  string model_version = 2;

  // More metadata fields can be added in the future
}

message IDsPayload {
  // List of IDs. Context of the ID is determined by the intent
  repeated string id = 1;
}

message AdjustDealPayload {
  // Suggested bid floor for the deal
  double bidfloor = 1;

  // Suggested margin for the deal
  Margin margin = 2;
}

message Margin {
  // The adjusted margin value
  double value = 1;

  // The type of margin adjustment
  enum CalculationType {
    // Absolute margin adjustment
    CPM = 0;

    // Relative margin adjustment (percentage)
    PERCENT = 1;
  }

  CalculationType calculation_type = 2;
}

message AdjustBidPayload {
  // The adjusted bid price
  double price = 1;
}

message MetricsPayload {
  // List of metrics to add
  repeated com.iabtechlab.openrtb.v2.BidRequest.Metric metric = 1;
}

message DataPayload {
  // List of data to add
  repeated com.iabtechlab.openrtb.v2.BidRequest.Data data = 1;
}