// Copyright 2016, Beeswax.IO Inc.
//
// Beeswax augmentor API.

syntax="proto2";
package augment;

option java_package = "com.beeswax.augment";
option cc_enable_arenas = true;

import "beeswax/openrtb/openrtb.proto";

// Stinger will issue a HTTP request to the augmentor.
// The following message will be present in the body of the HTTP request.
// Next id: 2
message AugmentorRequest {
  // Bid request received from the exchange after it has been processed by Beeswax.
  optional openrtb.BidRequest bid_request = 1;
}

// Augmentor will respond to Stinger with a HTTP response.
// The following message will be present in the body of the HTTP response.
// Augmentor can choose not to bid at all in which case it must still
// respond to the HTTP request with a 204 status code.
//
// Also custom bidding agents can receive this data through the data field in
// the BidRequest.User.Data
// Next id: 3
message AugmentorResponse {

  // Next id: 4
  message Segment {
    // The Id of an augmentor segment.
    // This field is primarily used for line item targeting.
    // For targeting to work with the segment ids, it is necessary
    // to register the segment ids with Beeswax via the Buzz Segments API.
    // The segments should have the format "BUZZKEY-SEGMENT_ID". So if the segment
    // is 8 and the customer's buzz_key is "beeswax", the id field should be set to
    // "beeswax-8".
    optional string id = 1;

    // This field can be used to pass additional information about the segment
    // that Stinger will forward to the bidding agent.
    optional string value = 2;

    // This field is ONLY used for bid modifiers as a dynamic mulitplier. If
    // the segment is present in the request, the multiplier will be applied to
    // the bid price. A valid range of multipliers should be between 0 and 10
    // and invalid ones will be ignored.
    optional float multiplier = 3;
  }

  // Array of Augmentor segments
  repeated Segment segments = 1;

  // The creative's macros {{DYNAMIC:<name>:STRING}} in the value of a
  // creative content or creative template, will be replaced with the
  // content of `value`.
  // For example, if name = "foo", value = "bar", the macro
  // {{DYNAMIC:FOO:STRING}} will be replaced with "bar".
  //
  // Please note the following constraints:
  // (1) Macro values sent via the custom augmentor will apply to whatever
  // creative matches to the request. In other words, they are not specific
  // to a particular creative or line item.
  // (2) Macro name is case-insensitive. (if name = "foo",
  // the macro {{DYNAMIC:FOO:STRING}} will still be replaced)
  // (3) For a macro to be expanded as an empty string, you should
  // explicitly set the macro name in the `name` field, and leave the
  // `value` feild empty; Dynamic macros in creatives that does
  // not have a match from the `name` field here will not be expanded.
  // (4) If a dynamic macro was not expanded, a string of {{DY:<name>}}
  // (instead of {{DYNAMIC:<name>:STRING}}) will be placed at where the
  // {{DYNAMIC:<name>:STRING}} macro was placed.
  // (5) Values of dynamic macros cannot contain other Beeswax macros,
  // (including other dynamic macros), as the contained macros will
  // not be expanded.
  // (6) If the macro is part of a url, the value shold be url-safe
  // (e.g, by escaping). Note that click_url is properly escaped as a whole,
  // so if the macro is in click_url, its value does not need to
  // have extra escaping; url-safe is enough.
  // Next id: 3
  message Macro {
    optional string name = 1;
    optional string value = 2;
  }
  repeated Macro dynamic_macros = 2;
}