# Relai Access

> A platform for building apps that open compartments in shared Exchange Zones
> over Bluetooth. People drop off and pick up on their own time, without
> meeting. Your app owns the experience; Relai authorizes every open server-side
> and the SDK handles the hardware.

SDK: `@relai-team/access-sdk` (npm, current 0.18.1)

## Read this before writing code

- **The platform authorizes every open.** Your app never holds a key or composes
  a lock command. Do not model the lock; call `relai.unlock({ orderId, intent, transport })`.
- **One order is a drop-off and a pick-up.** Each is an "open". The second one
  completes the order and frees the compartment.
- **Publishable keys (`pk_`) go in the app. Secret keys (`sk_`) never do.**
  An `sk_` in a client binary is readable by anyone who downloads it. Server-only
  calls: the end-user directory, override links, Parent commissioning.
- **The environment comes from the key**, not from a mode flag or a setting. A
  sandbox key sees only simulated Exchange Zones; a production key sees only
  real ones. A session belongs to the environment that created it.
- **Branch on `error.code`, never on the message.** Codes are the contract;
  messages are not and will change.
- **`not_found` on a recipient is not proof they do not exist.** It also means
  they paused their access tag or blocked the sender. The two are deliberately
  indistinguishable.
- **Do not build a payment sheet before checking the app's payment mode.** On
  Relai checkout, the SDK presents the standard Stripe sheet and retries the
  open for you. This is the most common piece of wasted work.
- **Every app starts in sandbox with its own simulated Exchange Zones.** Get the
  whole flow working there before touching Bluetooth. Only the transport changes.

## Machine-readable API contract

- [OpenAPI 3.1 spec](https://access.relai.us/openapi.json): every endpoint, request and
  response the SDK uses, with the auth each one takes. **Public, no email gate,
  no session.** Prefer it over inferring shapes from prose: where this file and
  the spec disagree, the spec is generated from the same repository as the API
  and wins.

## Documentation

- [SDK changelog](https://access.relai.us/docs/changelog): Every released version of the SDK, what it added, changed, or fixed, and which upgrades need a code change.

## Documentation (email required)

The pages below ask for an email address once, then set a cookie. An automated
fetch will receive the gate form rather than the content, so a signed-in browser
session is needed to read them. They are listed here so you know what exists.

- [Portal setup checklist](https://access.relai.us/docs/setup): What to configure in the portal so your app behaves as expected: subscription, payment mode, prices, handoff modes, webhooks, test end-users.
- [Starting prompts](https://access.relai.us/docs/prompts): Two copy-paste prompts for AI coding tools: one for a new app from scratch, one for adding Relai to an existing mobile app.
- [Integration checklist](https://access.relai.us/docs/integrate): Phase-by-phase checklist for adding Relai Access to an app, with a verification step at the end of each phase. Written for AI coding assistants.
- [Build an app](https://access.relai.us/docs/build): Step-by-step for React Native, new or existing. The AI starting prompts live on their own page.
- [Drop-offs and pick-ups](https://access.relai.us/docs/handoff): Handoff modes (self, directed, open), access tags and links, pick-up windows, late fees, and override links.
- [Billing and pricing](https://access.relai.us/docs/pricing): The two things you pay for, the plans side by side, how opens are counted, the fees an order can carry, and how invoices work.
- [Dictionary](https://access.relai.us/docs/dictionary): The Relai vocabulary, footnoted with usage notes and common hiccups.
- [Error codes](https://access.relai.us/docs/errors): Every stable error code the API returns, and what to do about each.

## Notes

- The REST API lives under `https://access.relai.us/api/v1` and is not crawlable. Keys
  authenticate with the `X-Relai-Key` header.
- Webhooks are signed Stripe-style: `X-Relai-Signature: t=<unix>,v1=<hex>`,
  HMAC-SHA256 over `"<t>.<raw body>"`. Verify against the RAW body, before JSON
  parsing, and reject stale timestamps.
- Terminology: always write "Exchange Zone" in full, or "EZ". Never shorten it
  any other way, in copy or in comments.