# agents.txt — Paul Millerd's Digital Bookshop
# https://books.pmillerd.com
#
# Last updated: 2026-05-01
#
# AI agents are welcome to purchase books on behalf of their human users.
# This file describes the public API. Stripe-issued card credentials (e.g.
# from a Link wallet) work on the Stripe-hosted checkout page returned by
# /api/checkout. HTTP 402 / x402 / shared payment tokens are NOT supported —
# use the `card` credential path.

## Allowed
- Browsing the catalog
- One purchase per user-initiated request
- Reading public marketing pages and book landing pages

## Not allowed
- Bulk scraping for training-data collection
- Automated access to /read, /download, /library, or /api/reader/* (these
  serve paid content to authenticated buyers only)
- Creating accounts on a user's behalf — humans must sign in themselves

## Catalog
GET /api/books
  No auth. Safe to cache for up to 1 hour.
  Returns: array of { slug, title, author, description, coverImage,
                      products[], addOns[], volumeDiscounts[],
                      hasPaperback, allowQuantity }.
  Use this to discover what's for sale and what each product/add-on costs.

## Shipping rates (required for physical products)
POST /api/shipping-rates
  Content-Type: application/json
  Body:
    {
      "slug":        "<book slug>",
      "countryCode": "<ISO-3166-1 alpha-2>",
      "postcode":    "<postal code>",
      "stateCode":   "<optional, required for US/CA>",
      "quantity":    1
    }
  Returns: { "rates": [ { "level", "name", "costCents", ... } ] }
  Pick a `level` and `costCents` and pass them to /api/checkout below.

## Purchase
POST /api/checkout
  Content-Type: application/json
  Body:
    {
      "slug":              "<book slug>",
      "productId":         "ebook" | "paperback" | "bundle",
      "addOns":            ["<add-on id>", ...],          // optional
      "quantity":          1,                              // optional
      "shippingLevel":     "<from /api/shipping-rates>",   // physical only
      "shippingCostCents": 599,                            // physical only
      "customIntroNote":   "<text>",                       // if "custom-intro"
      "giftRecipients":    [                               // if "gift"
        { "email": "...", "message": "...", "fromName": "..." }
      ]
    }
  Returns: { "url": "https://checkout.stripe.com/c/pay/..." }

  Open the returned URL and complete payment by entering card details from
  the user's wallet (number, cvc, exp_month, exp_year, billing address).
  Stripe handles 3DS, confirmation, and receipt email. Order fulfillment
  happens automatically via webhook — the buyer's email receives download
  links (digital) and/or print confirmation (paperback).

  Promotion codes are accepted on the Stripe-hosted page.

## Rate limits
No hard limits today. Be reasonable. If you're building something at scale,
get in touch first.

## Contact
paul@strategyu.co