What is this?

Apple and Google both put cards in a phone's wallet: loyalty cards, tickets, boarding passes. They agree on nothing else. Apple wants a signed .pkpass archive; Google wants a JWT backed by a REST API, with different field names, layouts and rules.

Passlet lets you describe a pass once. One call returns a signed .pkpass for Apple and a save link for Google, and one more keeps both up to date on the holder's phone.

Quick start

npm install passlet

import { field, Wallet } from "passlet";

const wallet = new Wallet({ apple: appleCredentials, google: googleCredentials });

const rewards = wallet.loyalty({
  id: "rewards",
  name: "Coffee Club",
  apple: { icon: "https://example.com/icon.png" },
  google: { logo: "https://example.com/logo.png" },
  fields: [field.primary("points", "Points")],
});

const pass = await rewards.create({ serialNumber: "member-123", values: { points: "1250" } });
// pass.apple → .pkpass bytes · pass.google → JWT for googleSaveUrl()

Runs on the server, Node.js 20.19+ or 22.12+, with no dependencies. Leave out either wallet to use just one. Getting credentials: Credentials.

Pass types

| Method | For | Apple | Google | |---|---|---|---| | loyalty() | Rewards and memberships | Store card | Loyalty | | eventTicket() | Concerts, matches, conferences | Event ticket | Event ticket | | boardingPass() | Flights, trains, buses, ferries | Boarding pass | Flight or transit | | coupon() | Offers and discounts | Coupon | Offer | | giftCard() | Prepaid balances | Store card | Gift card | | generic() | Anything else | Generic | Generic |

Features

• Apple and Google from one definition: a signed .pkpass and a Google save link from the same call
• Fields on the front and back, with date, number and currency formatting
• Barcodes: QR, PDF417, Aztec, Code 128 and more, plus rotating codes on Google
• Images from URLs or bytes: icons, logos, strips, thumbnails and Google hero images
• Translations for every field, in both wallets
• Lock-screen relevance by date and location, and NFC (Apple NFC passes, Google Smart Tap)
• Updates after issue, with a notification on the holder's phone when a value changes
• Several passes in one download, like a family's tickets or every leg of a trip

Documentation

• Getting started: first pass for both wallets
• Credentials: Apple certificates and Google service accounts
• Pass types: what each type supports on each wallet
• Fields and layout: slots, formatting, change messages
• Images, barcodes and localization
• Serving passes: headers, save links, caching
• Several passes at once: bundles and grouping
• Updating passes: load, the web service, notifications
• Deploying and External signers
• Errors and FAQ
• Examples: Express, Hono and Next.js servers
• Upgrading: to v4 · to v3
• For agents: llms.txt and the skill

Contributing

Issues and PRs welcome. Setup, tests and releases are in CONTRIBUTING.md; report security issues as described in SECURITY.md.

License

MIT

Built by Oscar Treviño