passlet 0.2.2 → 0.2.3

package/README.md

@@ -3,10 +3,25 @@
   <img src="https://raw.githubusercontent.com/oscartrevio/passlet/main/.github/assets/header.svg" alt="Passlet" width="100%">
 </picture>
 
-**[Passlet](https://github.com/oscartrevio/passlet)** is a library for generating Apple Wallet and Google Wallet passes from a single TypeScript API.
+<p align="center">
+  <a href="https://img.shields.io/npm/v/passlet"><img src="https://img.shields.io/npm/v/passlet?style=flat-square&color=cb3837" alt="npm"></a>
+  <a href="https://img.shields.io/npm/l/passlet"><img src="https://img.shields.io/npm/l/passlet?style=flat-square" alt="license"></a>
+</p>
 
-[![npm version](https://img.shields.io/npm/v/passlet)](https://www.npmjs.com/package/passlet)
-[![license](https://img.shields.io/npm/l/passlet)](https://www.npmjs.com/package/passlet)
+---
+
+**[Passlet](https://github.com/oscartrevio/passlet)** is a library for generating Apple Wallet and Google Wallet passes from a single API.
+
+## The problem
+
+Creating wallet passes is painful.
+
+Apple Wallet and Google Wallet have nothing in common.
+Apple uses .pkpass files — a signed ZIP bundle with a JSON manifest, PKCS#7 certificates, and SHA hashes for every asset. Google uses a REST API with service accounts, JWTs, and a completely different data model. Different field names. Different auth flows. Different everything.
+
+If your app supports both, you're building two separate systems.
+
+Passlet fixes that. One API that handles the signing, formatting, and platform translation for you — whether you need one wallet or both.
 
 ## Install
 
@@ -44,28 +59,119 @@ const pass = wallet.loyalty({
 });
 
 const { apple, google } = await pass.create({ serialNumber: "user-123" });
-// apple → Uint8Array (.pkpass file, serve with Content-Type: application/vnd.apple.pkpass)
-// google → JWT string (save link: https://pay.google.com/gp/v/save/<jwt>)
 ```
 
-Omit `apple` or `google` from the credentials to skip that provider.
+`apple` is a `Uint8Array` — the `.pkpass` file, ready to serve with `Content-Type: application/vnd.apple.pkpass`.
+
+`google` is a JWT string — build the save link as `https://pay.google.com/gp/v/save/{jwt}`.
+
+Only need one platform? Omit `apple` or `google` from the wallet config and Passlet skips it.
 
 ## Pass types
 
 ```ts
-wallet.loyalty(config);
-wallet.event(config);
-wallet.flight(config);
-wallet.coupon(config);
-wallet.giftCard(config);
-wallet.generic(config);
+wallet.loyalty(config); // Rewards cards, memberships, point systems
+wallet.event(config); // Concerts, conferences, sports, any ticketed event
+wallet.flight(config); // Boarding passes with gate, seat, departure info
+wallet.coupon(config); // Discounts, promos, limited-time offers
+wallet.giftCard(config); // Prepaid cards with balance tracking
+wallet.generic(config); // Anything else — credentials, IDs, parking, keys
 ```
 
+Every type maps automatically to the correct Apple pass style and Google Wallet class. You don't touch platform-specific schemas.
+
+## Fields
+
+Fields define what shows on the pass. Passlet handles the translation to each platform's layout model.
+
+```ts
+import { field } from "passlet";
+
+const pass = wallet.event({
+  id: "summer-fest",
+  name: "Summer Fest",
+  fields: [
+    field.primary("event", "Event", "Summer Fest"),
+    field.secondary("date", "Date", "Aug 29, 2026"),
+    field.secondary("location", "Location", "Monterrey, MX"),
+    field.auxiliary("door", "Doors Open", "6:00 PM"),
+    field.auxiliary("seat", "Seat", "GA"),
+  ],
+  barcode: {
+    format: "QR",
+    value: "TICKET-2444",
+    altText: "TICKET-2444",
+  },
+});
+```
+
+Field groups (`primary`, `secondary`, `auxiliary`, `back`) map to Apple's layout zones and Google's equivalent row structure. Primary fields render large and prominent. Secondary and auxiliary fill the detail rows. Back fields go on the reverse side (Apple) or expandable section (Google).
+
+## Barcodes
+
+```ts
+barcode: {
+  format: "QR",        // "QR" | "PDF417" | "AZTEC" | "CODE128"
+  value: "ABC-12345",
+  altText: "ABC-12345", // Text shown below the barcode
+}
+```
+
+Passlet normalizes barcode formats across platforms. If a format isn't supported on one platform, it falls back to the closest equivalent.
+
+## Visual customization
+
+```ts
+wallet.loyalty({
+  id: "my-card",
+  name: "My Card",
+  backgroundColor: "#1c1917",
+  foregroundColor: "#fafaf9",
+  labelColor: "#a8a29e",
+  icon: readFileSync("./assets/icon.png"),
+  logo: readFileSync("./assets/logo.png"),
+  fields: [
+    /* ... */
+  ],
+});
+```
+
+Colors accept any hex value. Images accept `Uint8Array` or `Buffer`. Passlet handles the asset bundling for Apple and image hosting references for Google.
+
 ## Credentials
 
-**Apple** — requires an Apple Developer account with a Pass Type ID. [Create one in the Developer portal](https://developer.apple.com/account/resources/identifiers/list/passTypeId), then download your signing certificate and convert it to PEM.
+### Apple
+
+Requires an Apple Developer account with a Pass Type ID.
+
+1. [Create a Pass Type ID](https://developer.apple.com/account/resources/identifiers/list/passTypeId) in the Apple Developer portal
+2. Create and download the signing certificate
+3. Export as `.p12`, convert to PEM:
+
+```bash
+openssl pkcs12 -in certificate.p12 -clcerts -nokeys -out signerCert.pem
+openssl pkcs12 -in certificate.p12 -nocerts -out signerKey.pem
+```
+
+4. Download the [Apple WWDR certificate](https://www.apple.com/certificateauthority/) (G4)
+
+### Google
+
+Requires a Google Wallet issuer account.
+
+1. [Sign up for the Google Pay & Wallet Console](https://pay.google.com/business/console)
+2. Create a service account with the Google Wallet API enabled
+3. Download the JSON key — use `client_email` and `private_key` from the file
+
+## Roadmap
+
+- [ ] Pass updates and push notifications (APNs + Google API)
+- [ ] CLI for quick pass generation
+- [ ] Pass playground
+
+## Contributing
 
-**Google** — requires a Google Wallet issuer account. [Set one up in the Pay & Wallet Console](https://pay.google.com/business/console), create a service account, and download the JSON key.
+PRs welcome. If you've dealt with wallet pass APIs before, you know why this needs to exist.
 
 ## License
 

package/dist/index.cjs

@@ -581,6 +581,12 @@ function validateGoogleRequirements(pass) {
       "Google Wallet logo must be a URL string, not bytes"
     );
   }
+  if (pass.type === "loyalty" && !pass.logo) {
+    throw new WalletError(
+      "GOOGLE_MISSING_LOGO",
+      "Google Wallet loyalty passes require a logo URL (programLogo)"
+    );
+  }
   if (pass.type === "flight") {
     const { carrier, flightNumber, origin, destination } = pass;
     if (!(carrier && flightNumber && origin && destination)) {
@@ -1239,35 +1245,58 @@ function resolveOptions(arg) {
   return typeof arg === "string" ? { value: arg } : arg;
 }
 var field = {
-  /** Top-right of the pass. Compact — typically one field. */
+  /**
+   * Top-right corner of the pass. Space is limited — use at most one field.
+   *
+   * Apple → `headerFields`. Google → `textModulesData`.
+   */
   header: (key, label, arg) => ({
     slot: "header",
     key,
     label,
     ...resolveOptions(arg)
   }),
-  /** Large, prominent area. Apple: primaryFields. Google: subheader (label) + header (value). */
+  /**
+   * Large, prominent area below the logo.
+   *
+   * Apple → `primaryFields`. Google → `subheader` (label) + `header` (value).
+   * On boarding passes, Apple renders a transit icon between the two primary fields,
+   * so place departure on the left and arrival on the right.
+   */
   primary: (key, label, arg) => ({
     slot: "primary",
     key,
     label,
     ...resolveOptions(arg)
   }),
-  /** Below primary. Apple: secondaryFields. Google: textModulesData. */
+  /**
+   * Row below the primary area.
+   *
+   * Apple → `secondaryFields`. Google → `textModulesData`.
+   */
   secondary: (key, label, arg) => ({
     slot: "secondary",
     key,
     label,
     ...resolveOptions(arg)
   }),
-  /** Below secondary. Supports two rows via { row: 0 | 1 }. Apple: auxiliaryFields. Google: textModulesData. */
+  /**
+   * Row below secondary. Supports two rows — pass `{ row: 0 }` or `{ row: 1 }` to assign.
+   *
+   * Apple → `auxiliaryFields`. Google → `textModulesData`.
+   */
   auxiliary: (key, label, arg) => ({
     slot: "auxiliary",
     key,
     label,
     ...resolveOptions(arg)
   }),
-  /** Back of the pass — hidden by default. Apple: backFields. Google: infoModuleData. */
+  /**
+   * Back of the pass — visible only when the user flips it over.
+   * Good for terms, redemption instructions, or contact info.
+   *
+   * Apple → `backFields`. Google → `infoModuleData`.
+   */
   back: (key, label, arg) => ({
     slot: "back",
     key,
@@ -1301,6 +1330,16 @@ var Pass = class {
     this.config = config;
     this.credentials = credentials;
   }
+  /**
+   * Issue a pass to a recipient. Runs both providers in parallel.
+   *
+   * Returns an {@link IssuedPass} with:
+   * - `apple` — a `.pkpass` `Uint8Array` ready to serve, or `null` if Apple credentials were omitted.
+   * - `google` — a signed JWT for the Google Wallet save link, or `null` if Google credentials were omitted.
+   * - `warnings` — non-fatal notices (e.g. a missing optional image).
+   *
+   * @throws {WalletError} `CREATE_CONFIG_INVALID` if `createConfig` fails validation.
+   */
   async create(createConfig) {
     validateCreateConfig(createConfig);
     const [appleResult, googleResult] = await Promise.allSettled([
@@ -1319,7 +1358,13 @@ var Pass = class {
       warnings: [...appleResult.value.warnings, ...googleResult.value.warnings]
     };
   }
-  // Update an existing pass. For Google: PATCHes the object via the Wallet REST API.
+  /**
+   * Push updated field values to an already-issued pass.
+   *
+   * Google: PATCHes the object via the Wallet REST API (the pass must have been
+   * saved to a wallet first). Apple: no-op — Apple passes update when the holder
+   * re-downloads the pass via your web service.
+   */
   async update(createConfig) {
     validateCreateConfig(createConfig);
     if (this.credentials.google) {
@@ -1330,8 +1375,12 @@ var Pass = class {
       );
     }
   }
-  // Delete a pass. For Google: permanently removes the object via the Wallet REST API.
-  // Apple passes cannot be remotely deleted — use expire() to invalidate them instead.
+  /**
+   * Permanently delete a pass.
+   *
+   * Google: removes the object via the Wallet REST API.
+   * Apple: no-op — Apple passes cannot be remotely deleted; use {@link expire} to invalidate them.
+   */
   async delete(serialNumber) {
     if (this.credentials.google) {
       await deleteGooglePass(
@@ -1341,8 +1390,13 @@ var Pass = class {
       );
     }
   }
-  // Expire a pass. For Google: sets object state to EXPIRED via the Wallet REST API.
-  // Apple passes expire automatically when expiresAt is reached.
+  /**
+   * Mark a pass as expired / invalid.
+   *
+   * Google: transitions the object state to `EXPIRED` via the Wallet REST API.
+   * Apple: no-op — Apple passes expire automatically when `expiresAt` is reached,
+   * or you can set `apple.voided: true` at issue time via {@link create}.
+   */
   async expire(serialNumber) {
     if (this.credentials.google) {
       await expireGooglePass(
@@ -1360,21 +1414,32 @@ var Wallet = class {
   constructor(credentials) {
     this.credentials = credentials;
   }
+  /** Create a loyalty / rewards card pass. */
   loyalty(config) {
     return new Pass({ ...config, type: "loyalty" }, this.credentials);
   }
+  /** Create an event ticket pass. */
   event(config) {
     return new Pass({ ...config, type: "event" }, this.credentials);
   }
+  /**
+   * Create a boarding pass. Covers air, train, bus, and boat transit.
+   *
+   * Apple boarding passes render a transit icon between the two `primary` fields,
+   * so use `field.primary()` for the departure and arrival locations.
+   */
   flight(config) {
     return new Pass({ ...config, type: "flight" }, this.credentials);
   }
+  /** Create a coupon / offer pass. */
   coupon(config) {
     return new Pass({ ...config, type: "coupon" }, this.credentials);
   }
+  /** Create a gift card pass. */
   giftCard(config) {
     return new Pass({ ...config, type: "giftCard" }, this.credentials);
   }
+  /** Create a generic pass for anything that doesn't fit the other types. */
   generic(config) {
     return new Pass({ ...config, type: "generic" }, this.credentials);
   }