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
Generated from packages/app-node/src/index.ts. 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.
- Package browser
- https://npmx.dev/package/@atmosphere-money/app-node
- Generated exports
- 109
- Generated client methods
- 18
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. |
| payments | requestRecipientApproval | ATM App Node client method. |
Exported helpers
The export list follows the package source. Large shared type sections are collapsed by default; checkout, webhook, receiver, and ticket helpers stay near the top.
core checkout12 exports
| Export | Kind | Description |
|---|---|---|
| AtmCheckoutEnvelope | type | Server-only checkout envelope input. May contain private session context. |
| AtmCheckoutPublicRecords | type | Exported TypeScript contract for ATM app integrations. |
| 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. |
| AtmPublicRecordPaymentPolicy | type | Exported TypeScript contract for ATM app integrations. |
| 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 events34 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. |
| AtmLexiconTypedEventData | type | Exported TypeScript contract for ATM app integrations. |
| 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 types18 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. |
| AtmPublicRecordsPolicy | type | Exported TypeScript contract for ATM app integrations. |
| AtmPublicRecordVisibility | type | Exported TypeScript contract for ATM app integrations. |
| AtmReceiverServiceAuthVerifier | type | Callback type for app code that verifies ATM service-auth JWT signatures. |
| AtmRecipientApprovalStatus | type | Exported TypeScript contract for ATM app integrations. |
| AtmRequestRecipientApprovalInput | type | Exported TypeScript contract for ATM app integrations. |
| AtmRequestRecipientApprovalResult | type | Exported TypeScript contract for ATM app integrations. |
| 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 creator-site widgets to this Node package.