# Tiny Waffle Coffee — Agent Purchasing Guide
#
# This site sells small, time-boxed batches of specialty coffee as preorders.
# AI agents can place an order on behalf of a customer by paying with a
# Stripe Shared Payment Token (SPT). The agent never collects raw card
# details from us; the agent issues an SPT scoped to our seller profile,
# then submits it to the endpoint below.
#
# Spec reference:
# https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens

Contact: roger@tinywaffle.co
Site: https://tinywaffle.co

# --- Payment scoping --------------------------------------------------------
# When the agent issues the SPT via POST /v1/shared_payment/issued_tokens,
# scope it to this seller's network business profile:
Payment-Network: stripe
Stripe-Network-Business-Profile: see https://tinywaffle.co/api/v1/coffee
Stripe-Api-Version: 2026-04-22.preview

# The agent should also constrain usage_limits to the order it intends to
# place: currency=usd, max_amount=<price_cents * quantity>, and a short
# expires_at (a few minutes from issuance is plenty).

# --- Discovering what is for sale -------------------------------------------
# GET https://tinywaffle.co/api/v1/coffee
#
# Returns the currently listed coffee:
#   {
#     "id": 1,
#     "name": "First Batch",
#     "summary": "Castillo from Popayán, Cauca, Colombia (Fully washed)",
#     "price_cents": 2500,
#     "currency": "usd",
#     "sold_out": false,
#     "max_per_order": 10,
#     "details": { "grower": "...", "variety": "...", ... }
#   }
#
# If `sold_out` is true, do not place an order. Quantity must be between
# 1 and `max_per_order` (inclusive); if the remaining inventory is below
# what you requested, the order endpoint returns 422 insufficient_inventory.

# --- Placing an order -------------------------------------------------------
# POST https://tinywaffle.co/api/v1/orders
# Content-Type: application/json
#
# Request body:
#   {
#     "shared_payment_token": "spt_...",     // SPT issued by the agent
#     "coffee_id": 1,                         // optional; defaults to current
#     "quantity": 2,                          // 1..max_per_order
#     "customer_email": "buyer@example.com",  // used for confirmation
#     "shipping": {                           // US shipping only
#       "name": "Jane Doe",
#       "phone": "+15555550123",
#       "address": {
#         "line1": "123 Main St",
#         "line2": "Apt 4",
#         "city": "Brooklyn",
#         "state": "NY",
#         "postal_code": "11201",
#         "country": "US"
#       }
#     }
#   }
#
# On success (HTTP 201):
#   {
#     "reference": "TWC-XXXXXXXX",
#     "payment_intent_id": "pi_...",
#     "status": "succeeded",
#     "amount_cents": 5000,
#     "currency": "usd",
#     "quantity": 2,
#     "coffee": { "id": 1, "name": "First Batch" }
#   }
#
# Error responses use { "error": { "code", "message", ... } }:
#   400 missing_parameter         — required field absent
#   404 coffee_not_found          — coffee_id is invalid or no coffee listed
#   422 invalid_quantity          — quantity outside [1, max_per_order]
#   422 insufficient_inventory    — not enough units remaining
#   402 payment_not_completed     — PaymentIntent created but not succeeded
#   502 stripe_error              — upstream Stripe failure

# --- Behavior expectations --------------------------------------------------
# * Only place an order with explicit user authorization for the amount.
# * Use the customer's real email; we send a confirmation receipt to it.
# * Do not retry on 4xx errors without changing the request.
# * Treat the returned `reference` (TWC-XXXXXXXX) as the customer-facing
#   order number.

# --- Crawling ---------------------------------------------------------------
# Public catalog and marketing pages may be crawled. Do not POST to
# /api/v1/orders or any other write endpoint as part of crawling.
User-agent: *
Allow: /
Disallow: /api/v1/orders
Disallow: /jobs