From 3354a2c222d6f3232c974169f3ba095e4b5772eb Mon Sep 17 00:00:00 2001 From: Alex Pate Date: Wed, 8 Jul 2026 10:52:21 +0200 Subject: [PATCH] docs: document pass wallet URLs and build-your-own-buttons pattern Every pass carries url / download_url / google_wallet_url. Document what each points at (hosted page / direct Apple .pkpass / Google save link), the "null when that platform wasn't delivered" semantics, and the recommended `pass.download_url ?? pass.url` fallback for rendering your own wallet buttons. Clarify the JSDoc on those fields so they explain themselves in-editor. Co-Authored-By: Claude Opus 4.8 (1M context) --- .changeset/document-wallet-urls.md | 5 ++++ README.md | 42 ++++++++++++++++++++++++++++++ src/types.ts | 18 ++++++++++--- 3 files changed, 61 insertions(+), 4 deletions(-) create mode 100644 .changeset/document-wallet-urls.md diff --git a/.changeset/document-wallet-urls.md b/.changeset/document-wallet-urls.md new file mode 100644 index 0000000..b9da488 --- /dev/null +++ b/.changeset/document-wallet-urls.md @@ -0,0 +1,5 @@ +--- +'@passmint/node': patch +--- + +Document the wallet URLs carried on a pass (`url`, `download_url`, `google_wallet_url`) and the "build your own Apple/Google Wallet buttons" fallback pattern in the README, and clarify the JSDoc on those fields so they're self-explanatory in-editor. diff --git a/README.md b/README.md index 079f700..ae37ffc 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,48 @@ const { data } = await passmint.passes.list({ templateId: 'tmpl_123', limit: 20 await passmint.passes.void(pass.id) ``` +## Adding passes to a wallet + +Every created or retrieved pass carries three URLs. Use them to send users +straight into Apple Wallet / Google Wallet from your own UI, or hand off to the +Passmint-hosted page: + +| Field | Points at | Notes | +| --- | --- | --- | +| `url` | The Passmint-hosted pass page (`passmint.com/p/…`) | Always present. Detects the visitor's platform and shows the right "Add to Wallet" button(s) — plus a QR code on desktop. Use as your universal fallback. | +| `download_url` | The Apple `.pkpass` file, downloaded directly | Present once Apple issuance succeeded; `null` if Apple wasn't delivered (e.g. a Google-only template, or Apple failed). | +| `google_wallet_url` | The Google Wallet "Save" link (`pay.google.com/…`) | Present once Google issuance succeeded; `null` if Google wasn't delivered (e.g. no Google issuer configured). | + +Issuance is synchronous, so these are populated the moment `create()` resolves — +a URL is `null` only when that platform wasn't delivered for this pass. + +### Build your own wallet buttons + +Render your own branded "Add to Apple Wallet" / "Add to Google Wallet" buttons +and fall back to the hosted page when a direct link isn't available: + +```ts +const pass = await passmint.passes.create({ + templateId: 'tmpl_123', + fieldValues: { seat: '12A' }, +}) + +// Prefer the direct link; fall back to the hosted page, which platform-detects. +const appleHref = pass.download_url ?? pass.url +const googleHref = pass.google_wallet_url ?? pass.url +``` + +- **Apple** (`download_url`) — link an anchor to it, or trigger it in a hidden + iframe so Safari opens the Add-to-Wallet sheet without navigating away. +- **Google** (`google_wallet_url`) — link to it directly; it redirects into the + Google Wallet save flow. +- **Fallback** (`url`) — the hosted page inspects the visitor's platform and + shows the appropriate button(s). Always safe to link to when you just want + "add to wallet" to work everywhere. + +The direct URLs are guarded by an unguessable pass id (the same mechanism the +hosted page uses); voiding a pass disables all three. + ## Configuration ```ts diff --git a/src/types.ts b/src/types.ts index 1426806..674bab3 100644 --- a/src/types.ts +++ b/src/types.ts @@ -76,10 +76,19 @@ export interface Pass { created_via_api: boolean platforms: WalletPlatform[] platform_status: PassPlatformStatus | null + /** Passmint-hosted pass page; platform-detects and is always present. Use as your fallback. */ url: string - /** Only present once Apple has delivered the pass. */ + /** + * Direct download of the Apple `.pkpass`. Populated when Apple issuance + * succeeded; `null` when Apple wasn't delivered for this pass. Fall back to + * `url`. + */ download_url: string | null - /** Only present once Google has delivered the pass. */ + /** + * Google Wallet "Save" link. Populated when Google issuance succeeded; `null` + * when Google wasn't delivered (e.g. no Google issuer configured). Fall back + * to `url`. + */ google_wallet_url: string | null created_at: string } @@ -152,10 +161,11 @@ export interface EventPass { serial_number: string holder: MinimizedHolder voided: boolean + /** Passmint-hosted pass page; platform-detects and is always present. */ url: string - /** Only present once Apple has delivered the pass. */ + /** Direct Apple `.pkpass` download; `null` when Apple wasn't delivered. Falls back to `url`. */ download_url: string | null - /** Only present once Google has delivered the pass. */ + /** Google Wallet "Save" link; `null` when Google wasn't delivered. Falls back to `url`. */ google_wallet_url: string | null }