# Build with Atmosphere Tickets

Start here when given https://atmosphere.tickets/docs. You can scaffold an event
app and run the local starter without an ATM account or access to a private
repository. Connecting real test checkout requires the configuration listed
below. The docs describe ATM source contracts; confirm enabled capabilities in
your target environment before running an integration pilot.

## Read in this order

1. [Full agent guide](https://atmosphere.tickets/llms-full.txt): product boundaries,
   current methods, auth, lifecycle and published SDK limitations.
2. [Build](https://atmosphere.tickets/docs/build.md): server implementation,
   auth, availability, holds, free claims and scanner recipes.
3. [Callbacks](https://atmosphere.tickets/docs/callbacks.md): verification,
   current event payloads, durable processing and recovery.
4. [Reference](https://atmosphere.tickets/docs/reference.md) and
   [machine index](https://atmosphere.tickets/docs/agent-index.json): method verbs,
   errors and links to every raw lexicon. Read the raw schema, including referenced
   definitions, before implementing a request or parsing its response.
5. [Operations](https://atmosphere.tickets/docs/operations.md): test acceptance
   and launch checks. [ATM docs](https://atmosphere.money/docs) cover shared app
   registration, payment setup, signing and environment configuration.

All five HTML pages have generated Markdown mirrors. The
[overview](https://atmosphere.tickets/docs/overview.md) includes architecture
and onboarding. The [compact index](https://atmosphere.tickets/llms.txt) and
[source revision](https://atmosphere.tickets/docs/atm-source.json) are public.
Markdown mirrors and starter downloads are generated from the same checked-in
sources as the website.

## Run the public starter first

Requires Node.js 22 or later, npm, and unzip. These commands download an example
project and install its dependencies in a new local directory:

```sh
curl -fsS https://atmosphere.tickets/docs/tickets-node-app.zip -o tickets-node-app.zip
unzip tickets-node-app.zip
cd tickets-node-app
npm ci
npm run typecheck
npm run smoke
```

Expected result: `Tickets example smoke check passed.` This exercises mocked
HTTP ticket requests and signed webhook fixtures. It does not call ATM or
create payments. If archive downloads are unavailable, read the same allowlisted
sources in [the starter JSON bundle](https://atmosphere.tickets/docs/tickets-node-app.json):
`files` maps relative filenames to UTF-8 source contents. Its `sha256` map gives
each file's digest. It contains example placeholders only.

For a local health endpoint, copy `.env.example` to `.env`, run `npm run dev`,
then fetch `http://localhost:8788/health`. The dev command loads `.env`.
Ticket endpoints need real test configuration and a server auth adapter.

The example is a flow fixture. Before connecting it, replace its static app
token and local XRPC receiver verifier, authenticate your app's callers, persist
operation keys and private hold state, and add durable callback processing.
Its fixed demo keys, logs and token comparison do not implement those controls.

## What to build

Event apps own discovery, event pages, organizer/buyer UX and optional scanner
UX. ATM Tickets owns inventory, holds, issuance and admission truth inside ATM.
ATM owns checkout, payment settlement and app callbacks. Use the existing
`community.lexicon.calendar.event` event graph.

Build a trusted backend adapter plus the app UI:

- Render `getTicketAvailability.ticketTypes`. Omitted `availableQuantity`
  means unlimited. Public catalog records are never inventory authority.
- Create paid holds with `items: [{ ticketTypeId, quantity }]` and a durable
  per-order `idempotencyKey`. Save `holdId` and private `statusToken` server-side;
  redirect the browser to the top-level response `url`.
- Show issued tickets after verified `tickets.issued` or an authorized
  `listBuyerTickets` read. A browser return alone does not prove issuance.
- For zero-price types, call `claimFreeTicket` with the same item array,
  verified `buyerDid`/`buyerAssertionJwt`, private `customerEmail` and a stable
  key. Paid types discounted to zero still use ATM checkout.
- Verify callbacks against the exact raw body and expected environment. Use
  durable atomic delivery deduplication and retry/recovery; process refunds,
  voids, releases and cancellation as lifecycle updates.
- Use opaque tokens and authorized grants for verification/check-in. Keep buyer
  PII, assertions, webhook secrets, holds and scan tokens private.

After an uncertain purchase response, retry/reconcile the same operation and
key. A new key represents a new intentional order.

## Auth and SDK choices

Install the published `@atmosphere-money/app-node@0.0.0-beta.5` for supported
helpers, service-auth transport and callback verification. The wire schemas
are authoritative when SDK types differ:

| Area | Current wire contract / adapter requirement |
| --- | --- |
| Paid catalog setup | Send `product`, an active organizer-owned `kind=ticket` Product with a matching one-time default Price; omit `defaultPrice` when supplying Product. Beta.5 sends older `productRef`/`priceRef`; use raw authenticated XRPC here. |
| Buyer/organizer lists | Send `buyer` (DID/handle) or `paymentId`, exactly one, and `organizer` for organizer lists. Beta.5 sends older selectors. |
| Newer fields and methods | Use raw XRPC for authority fields, `eventCode`, `payerBinding`/`statusToken`, `releaseFreeTicket`, and lifecycle types missing from beta.5. |
| App requests | Mint fresh short-lived app service-auth for the target broker audience and exact method `lxm`. A single copied token cannot authorize all methods. |
| Paid buyer | Send both buyer DID and assertion, or neither for a guest. Buyer assertion method is `money.atmosphere.payment.assertPayer`; app method is `tickets.atmosphere.createTicketHold`. Asserted buyers default to fixed binding; guests default to switchable. |
| Free buyer | Mint a separate assertion scoped to `tickets.atmosphere.claimFreeTicket` (or `releaseFreeTicket` for release). |
| Organizer actions | Verify current event-control authority; commercial changes/cancellation are primary-only. Setup assertions and selling approval are separate. |

Construct raw requests at `${configuredBrokerOrigin}/xrpc/${methodNsid}` with
`Authorization: Bearer <fresh-app-service-auth>`. GET query fields belong in
the query string; POST inputs use JSON. Obtain the broker origin and audience
from the target environment's ATM app setup rather than guessing a DID service
fragment. `listPublicConfig` uses the public ATM AppView; it is catalog discovery
and does not reserve inventory or grant selling access.

[Auth model](https://atmosphere.tickets/docs/AUTH_MODEL.md) and the
[raw schemas](https://atmosphere.tickets/docs/agent-index.json) explain exact
fields. The machine index contains all ticket schemas and local schema
dependencies; HTML/Markdown field tables are summaries.

## Configuration needed for ATM test access

Build against fixtures while these are being obtained through ATM app onboarding:

| Configuration | Where it comes from / use |
| --- | --- |
| App DID and server signing provider | App registration and the app's AT Protocol identity; mint fresh exact-method assertions on the server. |
| Test broker origin and audience | Target environment's ATM app setup; keep test and live configuration separate. |
| Enabled modules and organizer selling approval | ATM app dashboard; confirm Tickets/payment capabilities for the exact app/organizer channel. |
| Event and type IDs | Public event shell plus organizer-authorized ticketed-event/type setup. Paid types need the Product/Price graph above. |
| Buyer and organizer auth | Method-scoped user assertions from your authenticated user flow; fresh free claims also require a delivery email. |
| HTTP receiver and test signing secret | Configure a reachable test webhook URL in ATM; preserve raw request bytes and verify signatures before processing. |
| Scanner grants / check-in list | Organizer-authorized event/list grants for staff or the selected scanner integration. |

Do not request secrets to begin scaffolding. Report the missing test settings
and auth-provider interfaces when connecting the adapter. Configure secrets
through the developer's private environment. The
[machine scanner pilot](https://atmosphere.tickets/docs/SCANNER_API.md) is a
separately provisioned optional interface.

## Acceptance criteria

Local completion: starter typecheck/smoke pass; app adapter and UI handle current
contracts; callback verification/deduplication and uncertain-result recovery
are implemented and tested with fixtures. Clearly identify mocked integrations.

Connected test completion: verify organizer/app approval, availability, paid
hold → checkout → issued tickets, free claim/release, callback retry/redrive,
and authorized check-in returning `already-checked-in` on repeat. Verify revoked
tickets cannot enter. Confirm capacity under concurrent holds and use the
[launch checklist](https://atmosphere.tickets/docs/LAUNCH_CHECKLIST.md).

The docs link is sufficient to start building. Real test transactions require
configured ATM access; live release follows the app's separate approval process.