# Connect the products

Point OrbPage, OrbCart and OrbSearch at the catalog, with the variables, secrets and calls each needs.

**OrbPage** reads products, categories and listings through `@orbcatalog/client`, as a storefront does. Point it at the catalog and the Channel its site belongs to:

```bash
# OrbPage's wrangler.jsonc vars
CATALOG_URL=https://catalog.nordgrat.de
CATALOG_CHANNEL=de   # its cards link into this Channel's shop, so an Austrian site's lead to nordgrat.at
```

A card shows a product's name, its address in that Channel's shop and its first picture; a discontinued product, one the catalog does not deliver and one not released in the page's language are left out and named in OrbPage's `meta.unresolved`. **No price and no availability**, because OrbPage keeps a page for a minute and hears of no change, so a card could show a price checkout no longer charges.

**OrbCart** borrows offers through its signed HTTP transport. No code in the merchant's Worker: its `http()` posts to exactly the address it is given and signs every call with the environment's key.

```ts
// OrbCart's src/worker.ts
import { defineCommerce, http } from "@orbcart/runtime";

export default defineCommerce({
  channels,
  offers: http("https://catalog.nordgrat.de/orbcart/offers"),
  inventory: {
    check: http("https://catalog.nordgrat.de/orbcart/inventory/check"),
    reserve: http("https://catalog.nordgrat.de/orbcart/inventory/reserve"),
    release: http("https://catalog.nordgrat.de/orbcart/inventory/release"),
    commit: http("https://catalog.nordgrat.de/orbcart/inventory/commit"),
    restock: http("https://catalog.nordgrat.de/orbcart/inventory/restock"),
  },
});
```

The catalog trusts that one environment: its keys at `ORBCART_URL/.well-known/jwks.json` verify every call, and its secret key sends the invalidations.

```bash
# wrangler.jsonc vars: "ORBCART_URL": "https://commerce.nordgrat.de"
npx wrangler secret put ORBCART_SECRET_KEY   # its sk_live_…; .dev.vars locally
```

When OrbCart's Worker runs in the catalog's Cloudflare account, bind it to the catalog instead: no public gateway, no signature and no fetch of OrbCart's keys stands between them. Export the entrypoint from the catalog's Worker beside its default export, `export const OrbCart = orbCartEntrypoint(nordgrat)` from `@orbcatalog/runtime/cloudflare`, bind OrbCart's Worker to it:

```jsonc
// OrbCart's wrangler.jsonc
"services": [{ "binding": "CATALOG", "service": "orbcatalog", "entrypoint": "OrbCart" }]
```

and attach the contracts to the binding. OrbCart calls each at its own path, such as `/offers` or `/pickup-locations`, and the entrypoint answers it with the `/orbcart` route there; `appointments` attach the same way.

```ts
// OrbCart's src/worker.ts
import { defineCommerce, service } from "@orbcart/runtime";

export default defineCommerce({
  channels,
  offers: service("CATALOG"),
  pickupLocations: service("CATALOG"),
  inventory: {
    check: service("CATALOG"),
    reserve: service("CATALOG"),
    release: service("CATALOG"),
    commit: service("CATALOG"),
    restock: service("CATALOG"),
  },
});
```

Only a Worker of the same account that is bound to the entrypoint reaches it, so the binding is the authentication. A call still names its `context.environment`, and each route still refuses a Channel the catalog does not sell in. The public `/orbcart` routes keep verifying every signature, for an OrbCart in another account or any other caller, and the invalidations still go out with `ORBCART_URL` and `ORBCART_SECRET_KEY`.

`POST /orbcart/offers` verifies the RFC 9421 signature (`tag="orbcart-contract"`, an `Idempotency-Key` covered wherever a call sends one), reads the SKU's Variant and its Offer for `context.channel` from the database primary (never the CDN, for `display` and `quote` alike) as they stand when the answer reaches OrbCart, at most three seconds on, so a price step on the way never arrives expired, and answers each reference with `title` ("Alpin 30", in the first of the Channel's languages the version is released in) with the Variant's options as `attributes` (`{ "Farbe": "Grün" }`), `price` in minor units, `compareAt`, `taxCategory`, `shipping` with its `weightInGrams`, `image` at most 400 px on its longer side, `limits` (a minimum above the maximum or above the 9,999 units a line holds is refused where it is written), `deliveryTime` wherever the Offer states its delivery days ("5–9 Tage"), `expiresAt` at the next price step or scheduled version and at most 15 minutes ahead, and `tags: ["p:BP-ALPIN-30"]`. A cart in another currency than its Channel is refused. A reference the catalog cannot sell is `unavailable`, and says why: `unknown`, `unavailable`, `discontinued`, `not_offered` or `out_of_stock`. When a SKU's price or availability moves, or a product is published, discontinued or withdrawn, the catalog calls OrbCart's `POST /v1/offers/invalidate` with the SKUs and tags, so open carts borrow again at once instead of at `expiresAt`; until OrbCart takes it, only that call waits.

`inventory` is the one place OrbCart is told about stock, whether an editor or a Source counts. The four routes verify the same signature and read and write the primary. `check` answers each counted SKU's `available`, the count less the orders booked since it and the holds open now; a SKU without a count is left out, which OrbCart reads as unlimited. `reserve` holds, under a lock on the SKUs' counts taken in SKU order, what is available of each up to what the hold asks, and answers what fell short as `[{ reference, reserved }]`; the same hold again holds nothing twice, a later `expiresAt` extends it, and what an open hold holds stays held, since OrbCart extends a hold with its quote's quantities and reads no answer. `release` frees a hold, a second time too. `commit` books the hold for the order and answers what it could not book as `[{ reference, committed }]`, never more than held; a hold that ran out or was released meanwhile, or whose count fell, books what is still available. A hold OrbCart never releases stops counting at its `expiresAt`. OrbCart's `Idempotency-Key` is the hold's id on all three: the catalog keys the hold's units and its bookings by it, so each call is idempotent on its own, and a repeat with a new request id changes nothing.

**OrbSearch** takes what it accepts today. Point it at the feed, polled every 10, 30, 60, 180, 360, 720 or 1440 minutes:

Published products whose Type takes appointments are discoverable without an offer in each Channel that sells a released locale, while appointments are enabled. The feed sends those Channels as entity membership and keeps the actual variants and offers; it invents no price, stock or availability. Other products need a real offer for Channel visibility. OrbSearch still applies its Channel assortments and permissions, and real offers independently confer visibility. Withdrawn and discontinued products leave the next feed; reindex after adopting this feed and an OrbSearch engine that supports entity membership. Keep the Channels configured in OrbSearch's release in step with the catalog.

```bash
curl -X PUT https://search.nordgrat.de/api/v1/catalog-source \
  -H "Authorization: Bearer $ORBSEARCH_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://catalog.nordgrat.de/feeds/orbsearch.ndjson","interval_minutes":10}'
```

and give the catalog OrbSearch's control plane and management key, so it pushes offers:

```bash
# wrangler.jsonc vars: "ORBSEARCH_URL": "https://search.nordgrat.de"
npx wrangler secret put ORBSEARCH_KEY   # .dev.vars locally
```

For Workers in the same account, add an HTTP service binding on the Catalog Worker instead of sending offer updates through a public gateway:

```jsonc
"services": [{ "binding": "ORBSEARCH", "service": "orbsearch-gateway" }]
```

Keep `ORBSEARCH_URL` and `ORBSEARCH_KEY`: the URL still supplies the request's address and the management key still authenticates it. The optional `ORBSEARCH` binding carries only Search offer updates, including retries and scheduled sale resends. Source media, Cart and webhooks keep their own transport. Without the binding, external deployments continue using HTTP. Outside Workers, an optional `orbSearch.fetch` transport can be supplied alongside its URL and key in the runtime ports.

Each variant carries its own colour's main image (or a shared image, never another colour's), its product URL and its actual offers only in Channels with a released locale. Search returns the SKU alongside the URL; a storefront can add its own variant-selection parameter. Catalog does not invent a variant URL convention.

Products and variants also carry `media`: at most one primary card-width image with its actual URL, dimensions, available `srcset` and alt text in the released locales. A variant's own colour image takes precedence over a shared image. An explicit `media: []` means that no image matches; Search must not fall back to another colour's product image. Omitting `media` remains the legacy `image`/`images` behavior for other feed producers. Linked external renditions stay direct CDN URLs and are never invented or rewritten. Full product galleries remain available through Catalog's product delivery, not this listing feed.

Every delivered SKU carries explicit `purchase` requirements: its published quantity minimum (one when absent), whole-unit increment of one and optional maximum, plus `requires_configuration`. Appointment needs follow the same rule as the public appointment read: a variant's complete override, otherwise its Type's default. Any published appointment requirement prevents direct quick-add, including while appointment booking is switched off. Draft edits never change these facts; a scheduled publication changes them at its delivery boundary. Requirements belong to each SKU, not a guessed family default. They authorize no purchase: Search must consider every eligible SKU before limiting previews, and Cart still validates quantities, stock and configuration.

Feed offers and incremental pushes share the same commercial projection: explicit currency, base and sale price, their comparison prices and unit prices, refundable deposit, availability including `limited`, and delivery days. Amounts are in the currency's major unit. Unit prices use the published net content and Type reference unit, with the same rounding as public offers and Cart; the deposit remains separate. Search switches `price`/`unit_price` to `sale_price`/`sale_unit_price` together inside the same `sale_window`, then restores both base values when it ends. Queued sales are pushed again at their scheduled transitions.

Incremental changes leave omitted fields unchanged, clear fields with `null`, and replace fields with values. Catalog explicitly clears removed deposits, unit prices and delivery days. `end_sale` clears the sale's price, window, comparison and unit price; `remove: true` removes an offer without a base price. Exact stock counts are not projected: public stock bands are display facts, and Cart checks and reserves stock authoritatively.

Content freshness follows feed imports, not offer pushes: publication, withdrawal, changed pictures and changed measurements move the feed's ETag. A draft does not. Configure and monitor the import interval separately from offer propagation; a fast price push is not proof of fast content updates. Cart and checkout remain authoritative for all purchase decisions.

The feed is the category tree, then every product that sells now, one OrbSearch entity per line. It opens with every delivered category, parents before their children, as an OrbSearch `category`: its title, URL and path in each locale it and its ancestors released, its parent, and its description as plain words, so a category page in search lists the products of the categories below it. Then the products, read a page at a time while it is sent: each product's name and URL in each released locale (OrbSearch keeps one URL per locale, so a locale's is its address in the first Channel that sells it), its description as plain words, its first image, brand, categories and list attributes, and its variants by their axes with their offers per Channel in OrbSearch's own shape (major units, its availability enum). A discontinued product leaves search. The attribute with the brand role is the entity's `brand`, the one with the description role (a text or rich text, per product) its `description`, and an attribute under a word OrbSearch keeps for a field of its own (`price`, `availability`, `category`, `rating` and the rest its contract lists) is not sent: OrbSearch fills those fields from the offers, the categories and its ranking signals. Its `ETag` moves only when published base data does (a product, a category, the Schema, the Channels or languages of the settings) or the catalog writes it otherwise (a deploy, a change of the Worker's settings, another media service), and no cache keeps the feed (`private, no-store`), since a kept copy would bring back a price pushed since, so every poll reaches the ETag: an unchanged catalog, or one whose prices alone moved, costs OrbSearch a `304`. Offer changes are pushed to `PUT /api/v1/offers` in batches of 1,000 as they happen, a sale with its `sale_window` so OrbSearch ends it by its own clock: a price is live in search in seconds, not at the next poll. An offer of a product OrbSearch has not imported yet is left to the feed, which brings the product with its offers.