syntax = "proto3"; package vendorportal.pricing.v1; import "google/protobuf/timestamp.proto"; import "vendorportal/common/v1/money.proto"; // PricingFeedService lets a vendor's own system (e.g. a venue whose prices move with // demand, season and weather) push live prices to the portal. // // This is one of three equivalent ways to send a price feed; the others are the HTTPS // API and signed webhooks (openapi/partner-pricing.v1.yaml). All three feed the same // ingestion core and have the same semantics. See docs/adr/0005. // // Authentication: send the feed connection's API key as gRPC metadata // `authorization: Bearer `. The key identifies the vendor; requests never name one. // A call without a key is refused (UNAUTHENTICATED) before its message is read. // // One message is at most 1.5 MiB (1,572,864 bytes), which every valid price sheet // fits; a larger one is refused with RESOURCE_EXHAUSTED. // // UNAVAILABLE means the gateway could not complete the call (a busy price list, its // storage out of reach or out of time, or a restart): send it again, every call is // repeatable. DEADLINE_EXCEEDED is only ever the caller's own deadline. service PricingFeedService { // Replace the vendor's whole price sheet. Items not in the sheet are removed. Every // item must be in the same currency. rpc PublishPriceSheet(PublishPriceSheetRequest) returns (PublishPriceSheetResponse); // Send incremental changes (upserts and removals) as they happen. A price list holds // at most 500 items: an upsert that would add a new SKU to a full list fails with // INVALID_ARGUMENT (changes received before it stay applied). // // A stream takes at most 10,000 messages; the next one ends it with // RESOURCE_EXHAUSTED, and what was sent before it stays applied. Messages also count // against the connection's rate limit (25 messages cost what one call costs): a // stream that outruns it ends with RESOURCE_EXHAUSTED and a `retry-after` trailer in // seconds. Either way, open a new stream for the rest. // // A stream is safe to send again from its start: an upsert of the same item changes // nothing, and a remove_sku for a SKU that is not in the list is accepted and does // nothing (it is not an error). // // The API key is checked again with every change: once the key is rotated or the // connection removed, the stream ends with UNAUTHENTICATED. // // A stream can end at any time with UNAVAILABLE (the gateway restarts on every // release, and connections are recycled): open a new one, with backoff, and send // again. What the ended stream had sent stays applied. rpc StreamPriceUpdates(stream StreamPriceUpdatesRequest) returns (StreamPriceUpdatesResponse); } enum PriceUnit { PRICE_UNIT_UNSPECIFIED = 0; PRICE_UNIT_PER_EVENT = 1; PRICE_UNIT_PER_HOUR = 2; PRICE_UNIT_PER_PERSON = 3; PRICE_UNIT_STARTING_AT = 4; } // Text fields (sku, name, description, and a sheet's notes) are refused with // INVALID_ARGUMENT, not cleaned, when they hold a control character (a line break is // allowed in description and notes), a bidirectional override or isolate, a zero-width // character, a tag character, a private-use character or U+FFFD. The guide lists the // exact code points. message PriceItem { // Stable identifier in the vendor's system. Upserts and removals match on it. // Required, at most 64 characters. string sku = 1; // Required, at most 120 characters. string name = 2; // At most 500 characters. string description = 3; // Required: an item without a price is refused with INVALID_ARGUMENT. proto3 cannot // tell an amount_minor that was left out from 0, so it is this message that must be // set; with it set, amount_minor 0 is a valid price (an item that is free or // included). amount_minor is 0 to 100,000,000 (1,000,000.00) and currency_code must // be CAD, the one currency the portal lists prices in. vendorportal.common.v1.Money price = 4; // Required: PRICE_UNIT_UNSPECIFIED is refused. PriceUnit unit = 7; // Optional validity window (e.g. a specific date or season). google.protobuf.Timestamp valid_from = 5; google.protobuf.Timestamp valid_until = 6; } message PublishPriceSheetRequest { repeated PriceItem items = 1; // When the vendor's system issued the sheet. Optional and informational only: it // is not stored and changes nothing about how the sheet is applied. Prices go live // when the sheet is received. The one rule is that scheduled sheets are not // supported, so a time more than 5 minutes in the future is rejected // (INVALID_ARGUMENT); any other value, or none, is accepted. Send next season's // prices when they should start to show, or use each item's valid_from / // valid_until. google.protobuf.Timestamp effective_at = 2; // Optional notes shown under the price list, e.g. taxes and service charges. string notes = 3; } message PublishPriceSheetResponse { string revision_id = 1; } message StreamPriceUpdatesRequest { oneof change { PriceItem upsert = 1; // The SKU to remove. A SKU that is not in the list is accepted and does nothing. string remove_sku = 2; } } message StreamPriceUpdatesResponse { // Messages accepted, including removals of SKUs that were not in the list. int32 accepted = 1; // The price list's revision after the last message that changed it; empty when // none did. string revision_id = 2; }