Docs
SDK reference
Generated reference for @atmosphere-money/app-node exports, client methods, errors, and event helpers.
Compatible with the closed-beta ATM app APIs and versioned ATM event headers. Check atm-api-version on every webhook or XRPC receiver event.
Generated source
This page is generated from packages/app-node/src/index.ts so app developers can trust that the docs match the package export surface. The App Node SDK is server-side, dependency-free at runtime, and MIT licensed as a package.
- Package
- @atmosphere-money/app-node
- Runtime
- Node 22+, ESM, TypeScript declarations from dist/index.d.ts.
- License
- MIT for the package only. The ATM monorepo and hosted platform remain private.
- Generated exports
- 101
- Generated client methods
- 17
Install shape
sh
npm install @atmosphere-money/app-node@betaClient methods
Client methods are grouped by the app surface they help with. Payments methods are the smallest checkout path; Tickets methods are for scarce inventory and scanner flows.
| Group | Method | Purpose |
|---|---|---|
| tickets | archiveTicketTier | Archive a ticket tier while preserving purchase history. |
| tickets | checkInTicket | Idempotently check in a verified ticket token. |
| tickets | claimFreeTicket | Issue a limited free ticket with app auth plus buyer assertion. |
| tickets | createCapacityGroup | Create a private event capacity group. |
| tickets | createTicketHold | Reserve scarce ticket capacity and return an ATM checkout token/url. |
| tickets | createTicketTier | Create an app-scoped ticket tier for an event. |
| tickets | getTicketAvailability | Read private ATM ticket availability derived from holds and issued tickets. |
| tickets | listBuyerTickets | List app-scoped tickets for a buyer or payment. |
| tickets | listOrganizerTickets | List tickets for an organizer or event. |
| tickets | releaseTicketHold | Release an unused ticket hold. |
| tickets | updateCapacityGroup | Update capacity group metadata or capacity. |
| tickets | updateTicketTier | Update mutable ticket tier fields. |
| tickets | verifyTicket | Verify an opaque QR/pass ticket token without checking in. |
| payments | getPaymentStatus | Poll checkout/payment status for browser return UI. |
| payments | getPayoutStatus | Check if a recipient DID can currently receive payments before showing checkout. |
| profiles | getProfile | Read an ATM profile through the AppView. |
| payments | initiatePayment | Start ATM-hosted checkout through strict network.attested.payment.initiate. |
Exported helpers
The generated export list stays accurate to the package source, but the largest shared type section is collapsed by default so the practical helpers remain easy to scan.
core checkout10 exports
| Export | Kind | Description |
|---|---|---|
| AtmCheckoutEnvelope | type | Server-only checkout envelope input. May contain private session context. |
| AtmInitiatePaymentResult | type | Exported TypeScript contract for ATM app integrations. |
| AtmPaymentStatus | type | Status response used for browser return polling and support tooling. |
| AtmPaymentSummary | type | App-visible payment summary used in events and status responses. |
| AtmPaymentType | type | ATM payment classification used for dashboard, events, and app policy. |
| AtmPayoutStatus | type | Payability response used before showing checkout buttons. |
| AtmProfile | type | ATM profile summary returned by the public AppView profile lookup. |
| createAtmAppClient | function | Create a server-side ATM client for app XRPC methods, checkout, status, profile, and Tickets calls. |
| createAtmCheckoutProduct | function | Build the private atm.checkout.v1 envelope used by strict attested.network initiation. |
| createPaymentInitiateBody | function | Build the strict { product } request body for network.attested.payment.initiate. |
webhooks and events33 exports
| Export | Kind | Description |
|---|---|---|
| AtmCloudflareWorkerWebhookHandler | type | Exported TypeScript contract for ATM app integrations. |
| AtmEventDataByType | type | Map from known ATM event type to typed event data shape. |
| AtmEventDataFor | type | Conditional type that resolves event data for a known ATM event type. |
| AtmExpressWebhookHandlerOptions | type | Options for creating Express-style webhook handlers. |
| AtmPaymentCompletedEvent | type | Exported TypeScript contract for ATM app integrations. |
| AtmPaymentEventData | type | Event data shape for payment events. |
| AtmProductEventData | type | Event data shape for product/catalog events. |
| AtmSubscriptionEventData | type | Event data shape for subscription events. |
| AtmTypedEvent | type | Typed ATM event envelope for a known event type. |
| AtmTypedWebhookEnvelope | type | Exported TypeScript contract for ATM app integrations. |
| AtmWebhookEnvelope | type | Canonical ATM event envelope used by HTTP webhooks and optional XRPC receivers. |
| AtmWebhookEventType | type | Known ATM event type union for typed webhook and XRPC receiver events. |
| AtmWebhookHandlerEvent | type | Event type passed into middleware-style webhook handlers. |
| AtmWebhookHandlerOptions | type | Options for creating Request/Response webhook handlers. |
| AtmWebhookHandlerResult | type | Return shape for middleware-style webhook handlers. |
| AtmWebhookHeaders | type | Headers required to verify an ATM HTTP webhook. |
| AtmXrpcMethod | type | Exported TypeScript contract for ATM app integrations. |
| AtmXrpcReceiverHeaders | type | Headers used by optional ATM-to-app XRPC receiver delivery. |
| constructAtmWebhookEvent | function | Verify an HTTP webhook signature over the raw body and parse the ATM event envelope. |
| ConstructAtmWebhookOptions | type | Options for verifying and parsing an ATM HTTP webhook event. |
| constructAtmXrpcReceiverEvent | function | Verify optional XRPC receiver service-auth and parse the ATM event envelope. |
| ConstructAtmXrpcReceiverOptions | type | Options for verifying and parsing optional ATM XRPC receiver events. |
| constructTypedAtmWebhookEvent | function | Verify an HTTP webhook and narrow event.data for a known ATM event type. |
| constructTypedAtmXrpcReceiverEvent | function | Verify an XRPC receiver event and narrow event.data for a known ATM event type. |
| createAtmXrpcReceiverAudience | function | Build the service-auth audience for an app-hosted ATM XRPC receiver service. |
| createCloudflareWorkerWebhookHandler | function | Exported App Node SDK helper. |
| createExpressWebhookHandler | function | Create an Express-style ATM webhook handler with raw-body verification. |
| createHonoWebhookHandler | function | Exported App Node SDK helper. |
| createNextWebhookRoute | const | Alias for Request/Response ATM webhook route handlers in Next route handlers. |
| createNodeWebhookHandler | function | Create a Request/Response ATM webhook route handler for Node-compatible runtimes. |
| signAtmWebhookPayload | function | Create a local ATM webhook signature for tests and fixture generation. |
| VerifyAtmWebhookOptions | type | Options for raw ATM webhook HMAC verification. |
| verifyAtmWebhookSignature | function | Check an ATM HTTP webhook HMAC signature with timestamp tolerance and secret rotation support. |
tickets33 exports
| Export | Kind | Description |
|---|---|---|
| AtmArchiveTicketTierInput | type | Input for archiving a ticket tier. |
| AtmArchiveTicketTierResult | type | Exported TypeScript contract for ATM app integrations. |
| AtmCapacityGroupResult | type | Exported TypeScript contract for ATM app integrations. |
| AtmCapacityGroupSummary | type | Exported TypeScript contract for ATM app integrations. |
| AtmCreateCapacityGroupInput | type | Input for creating a private capacity group. |
| AtmCreateTicketTierInput | type | Input for creating a ticket tier for an event. |
| AtmFreeTicketClaimInput | type | Input for claiming a limited free ticket without checkout. |
| AtmFreeTicketClaimResult | type | Result from claiming a limited free ticket without checkout. |
| AtmListBuyerTicketsParams | type | Query parameters for app-scoped buyer ticket lists. |
| AtmListOrganizerTicketsParams | type | Query parameters for organizer or event ticket lists. |
| AtmListTicketsResult | type | Exported TypeScript contract for ATM app integrations. |
| AtmReleaseTicketHoldInput | type | Input for releasing an unused ticket hold. |
| AtmReleaseTicketHoldResult | type | Exported TypeScript contract for ATM app integrations. |
| AtmTicketAvailability | type | Availability response derived from private ATM holds and issued tickets. |
| AtmTicketAvailabilityParams | type | Query parameters for reading app-scoped ticket availability. |
| AtmTicketCheckedInEvent | type | Exported TypeScript contract for ATM app integrations. |
| AtmTicketCheckInInput | type | Input for idempotent ticket check-in by opaque scan token. |
| AtmTicketCheckInResult | type | Check-in result for scanner apps. |
| AtmTicketEventData | type | Event data shape for ticket hold, issuance, refund, void, and check-in events. |
| AtmTicketEventInput | type | Event metadata supplied by a ticketing app when configuring tiers or capacity. |
| AtmTicketEventSummary | type | Exported TypeScript contract for ATM app integrations. |
| AtmTicketHoldInput | type | Input for creating a paid ticket hold before checkout. |
| AtmTicketHoldResult | type | Result from creating a ticket hold, including hold id, token, url, and expiry. |
| AtmTicketsIssuedEvent | type | Exported TypeScript contract for ATM app integrations. |
| AtmTicketSummary | type | Exported TypeScript contract for ATM app integrations. |
| AtmTicketTierResult | type | Exported TypeScript contract for ATM app integrations. |
| AtmTicketTierSummary | type | Exported TypeScript contract for ATM app integrations. |
| AtmUpdateCapacityGroupInput | type | Input for updating a private capacity group. |
| AtmUpdateTicketTierInput | type | Input for updating mutable ticket tier fields. |
| AtmVerifyTicketInput | type | Input for verifying an opaque ticket token without mutating check-in state. |
| AtmVerifyTicketResult | type | Verification result for QR/pass ticket presentation. |
| createFreeTicketClaimBody | function | Exported App Node SDK helper. |
| createTicketHoldBody | function | Exported App Node SDK helper. |
errors3 exports
| Export | Kind | Description |
|---|---|---|
| AtmApiError | class | Structured ATM request error with code, HTTP status, and parsed response body. |
| AtmWebhookSignatureError | class | Error thrown when HTTP webhook signature or event-header validation fails. |
| AtmXrpcReceiverAuthError | class | Error thrown when optional XRPC receiver auth or envelope validation fails. |
constants9 exports
| Export | Kind | Description |
|---|---|---|
| ATM_BROKER_DID | const | ATM broker DID used for broker service-auth and attested.network context. |
| ATM_BROKER_SERVICE_AUDIENCE | const | Default service-auth audience for ATM broker XRPC methods. |
| ATM_CHECKOUT_PRODUCT_PREFIX | const | Prefix for ATM's launch checkout envelope token. |
| ATM_EVENT_RECEIVE_NSID | const | Optional app XRPC receiver method used for ATM event delivery. |
| ATM_XRPC_METHODS | const | Grouped NSID constants for ATM app-facing XRPC methods. |
| DEFAULT_ATM_APPVIEW_URL | const | Default production AppView XRPC base URL. |
| DEFAULT_ATM_BROKER_URL | const | Default production broker and checkout XRPC base URL. |
| DEFAULT_ATM_WEBHOOK_TOLERANCE_SECONDS | const | Default timestamp tolerance for verifying ATM HTTP webhook signatures. |
| DEFAULT_ATM_XRPC_RECEIVER_SERVICE | const | Default DID service id for app-hosted ATM event receivers. |
shared types13 exports
| Export | Kind | Description |
|---|---|---|
| AtmAppClientOptions | type | Exported TypeScript contract for ATM app integrations. |
| AtmEnvironment | type | ATM app environment selector: test or live. |
| AtmExpressLikeRequest | type | Minimal Express-compatible request shape used by the SDK without depending on Express. |
| AtmExpressLikeResponse | type | Minimal Express-compatible response shape used by the SDK without depending on Express. |
| AtmHonoLikeContext | type | Exported TypeScript contract for ATM app integrations. |
| AtmReceiverServiceAuthVerifier | type | Callback type for app code that verifies ATM service-auth JWT signatures. |
| AtmServiceAuthTokenProvider | type | Exported TypeScript contract for ATM app integrations. |
| AtmStrongRef | type | AT Protocol strongRef shape for public catalog and entitlement references. |
| AtmSubscriptionSummary | type | Exported TypeScript contract for ATM app integrations. |
| AtmVerifiedServiceAuthClaims | type | Minimal verified service-auth claims ATM receiver helpers need after JWT verification. |
| verifyAtmReceiverServiceAuthClaims | function | Validate iss, aud, and lxm claims for an ATM-to-app XRPC receiver JWT after signature verification. |
| verifyServiceAuthRequest | function | Exported App Node SDK helper. |
| VerifyServiceAuthRequestOptions | type | Exported TypeScript contract for ATM app integrations. |
Errors
| AtmApiError | Thrown when an ATM XRPC/API response is non-2xx. Carries code, status, and parsed body. |
|---|---|
| AtmWebhookSignatureError | Thrown when webhook signature, delivery id, event type, API version, or environment validation fails. |
| AtmXrpcReceiverAuthError | Thrown when optional XRPC receiver authorization or event envelope validation fails. |
ts
import { AtmApiError } from "@atmosphere-money/app-node";
try {
await atm.initiatePayment(input);
} catch (error) {
if (error instanceof AtmApiError && error.code === "RecipientNotPayable") {
return showSetupRequiredState();
}
throw error;
}Release checks
- Run npm run sdk:app-node:check from the repo root.
- Run npm run publish:check from packages/app-node before public release.
- Inspect npm pack --dry-run output and confirm README, CHANGELOG, LICENSE, dist/index.js, and dist/index.d.ts are included.
- Update packages/app-node/CHANGELOG.md for every version.
- Keep docs/developer/sdk/atm-app.ts aligned until the npm package is public.
- Do not add browser checkout code or Supper widgets to this Node package.