passlet 0.2.1 → 0.2.3

package/dist/index.d.cts

@@ -25,38 +25,42 @@ declare class WalletError extends Error {
     constructor(code: WalletErrorCode, message?: string, options?: ErrorOptions);
 }
 
+/** Credentials for signing Apple Wallet `.pkpass` files. */
 interface AppleCredentials {
-    /** @example "pass.com.yourcompany.yourapp" */
+    /** Pass type identifier registered in your Apple Developer account. @example "pass.com.yourcompany.app" */
     passTypeIdentifier: string;
-    /** PEM-encoded pass signing certificate. */
+    /** PEM-encoded pass signing certificate from Apple Developer. */
     signerCert: string;
-    /** PEM-encoded private key paired with the signing certificate. */
+    /** PEM-encoded private key paired with `signerCert`. */
     signerKey: string;
     /** Your 10-character Apple Team ID. @example "ABCD1234EF" */
     teamId: string;
     /** PEM-encoded Apple WWDR intermediate certificate. */
     wwdr: string;
 }
+/** Credentials for signing Google Wallet JWTs and calling the Wallet REST API. */
 interface GoogleCredentials {
-    /** client_email from your Google Cloud service account JSON key. */
+    /** `client_email` from your Google Cloud service account JSON key. */
     clientEmail: string;
-    /** Your Google Wallet issuer ID from the Google Pay & Wallet Console. */
+    /** Issuer ID from the Google Pay & Wallet Console. */
     issuerId: string;
-    /** private_key from your Google Cloud service account JSON key (PKCS#8 PEM). */
+    /** `private_key` from your Google Cloud service account JSON key (PKCS#8 PEM). */
     privateKey: string;
 }
+/** Credentials passed to {@link Wallet}. Omit a provider to skip that platform. */
 interface WalletCredentials {
-    /** Apple Wallet credentials. Omit to skip Apple pass generation. */
+    /** Apple Wallet credentials. Required to generate `.pkpass` files. */
     apple?: AppleCredentials;
-    /** Google Wallet credentials. Omit to skip Google pass generation. */
+    /** Google Wallet credentials. Required to generate Google Wallet JWTs. */
     google?: GoogleCredentials;
 }
+/** Result of {@link Pass.create}. */
 interface IssuedPass {
-    /** The .pkpass file as Uint8Array, ready to serve. null when Apple credentials were not provided. */
+    /** Signed `.pkpass` archive ready to serve, or `null` if Apple credentials were omitted. */
     apple: Uint8Array | null;
-    /** Signed Google Wallet JWT for the save link. null when Google credentials were not provided. */
+    /** Signed JWT for a Google Wallet save link (`pay.google.com/gp/v/save/<jwt>`), or `null` if Google credentials were omitted. */
     google: string | null;
-    /** Non-fatal warnings (e.g. optional image fetch failures). */
+    /** Non-fatal notices — e.g. a missing optional image or an unset recommended field. */
     warnings: string[];
 }
 
@@ -2376,36 +2380,133 @@ type AppLinkData = z.infer<typeof googleAppLinkDataSchema>;
 
 type FieldOptions = Omit<FieldDef, "slot" | "key" | "label">;
 type FieldArg = string | FieldOptions;
+/**
+ * Builders for pass display fields. Pass the result into the `fields` array
+ * of any pass config.
+ *
+ * The third argument is either a string (shorthand for `value`) or a full
+ * {@link FieldDef} options object for formatting, alignment, and more.
+ *
+ * @example
+ * fields: [
+ *   field.primary("points", "Points", "1 250"),
+ *   field.secondary("tier", "Tier", "Gold"),
+ *   field.back("terms", "Terms", { value: "No refunds." }),
+ * ]
+ */
 declare const 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: string, label: string, arg?: FieldArg) => FieldDef;
-    /** 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: string, label: string, arg?: FieldArg) => FieldDef;
-    /** Below primary. Apple: secondaryFields. Google: textModulesData. */
+    /**
+     * Row below the primary area.
+     *
+     * Apple → `secondaryFields`. Google → `textModulesData`.
+     */
     secondary: (key: string, label: string, arg?: FieldArg) => FieldDef;
-    /** 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: string, label: string, arg?: FieldArg) => FieldDef;
-    /** 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: string, label: string, arg?: FieldArg) => FieldDef;
 };
+/**
+ * A configured pass template. Obtain one from {@link Wallet} rather than
+ * constructing directly.
+ *
+ * Config is validated at construction time — a {@link WalletError} with code
+ * `PASS_CONFIG_INVALID` is thrown immediately if anything is wrong.
+ */
 declare class Pass {
     private readonly config;
     private readonly credentials;
     constructor(config: PassConfig, credentials: WalletCredentials);
+    /**
+     * 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.
+     */
     create(createConfig: CreateConfig): Promise<IssuedPass>;
+    /**
+     * 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.
+     */
     update(createConfig: CreateConfig): Promise<void>;
+    /**
+     * 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.
+     */
     delete(serialNumber: string): Promise<void>;
+    /**
+     * 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}.
+     */
     expire(serialNumber: string): Promise<void>;
 }
 
+/**
+ * Entry point for building passes. Construct once with your credentials,
+ * then call the pass-type methods to get a {@link Pass} you can issue.
+ *
+ * Omit a provider's credentials to skip that platform entirely —
+ * `apple` and `google` are both optional.
+ *
+ * @example
+ * const wallet = new Wallet({ apple: appleCredentials, google: googleCredentials });
+ * const result = await wallet.loyalty({ id: "rewards", name: "Rewards Card", fields: [] })
+ *   .create({ serialNumber: "user-123" });
+ */
 declare class Wallet {
     private readonly credentials;
     constructor(credentials: WalletCredentials);
+    /** Create a loyalty / rewards card pass. */
     loyalty(config: Omit<LoyaltyPassConfig, "type">): Pass;
+    /** Create an event ticket pass. */
     event(config: Omit<EventPassConfig, "type">): Pass;
+    /**
+     * 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: Omit<FlightPassConfig, "type">): Pass;
+    /** Create a coupon / offer pass. */
     coupon(config: Omit<CouponPassConfig, "type">): Pass;
+    /** Create a gift card pass. */
     giftCard(config: Omit<GiftCardPassConfig, "type">): Pass;
+    /** Create a generic pass for anything that doesn't fit the other types. */
     generic(config: Omit<GenericPassConfig, "type">): Pass;
 }
 

package/dist/index.d.ts

@@ -25,38 +25,42 @@ declare class WalletError extends Error {
     constructor(code: WalletErrorCode, message?: string, options?: ErrorOptions);
 }
 
+/** Credentials for signing Apple Wallet `.pkpass` files. */
 interface AppleCredentials {
-    /** @example "pass.com.yourcompany.yourapp" */
+    /** Pass type identifier registered in your Apple Developer account. @example "pass.com.yourcompany.app" */
     passTypeIdentifier: string;
-    /** PEM-encoded pass signing certificate. */
+    /** PEM-encoded pass signing certificate from Apple Developer. */
     signerCert: string;
-    /** PEM-encoded private key paired with the signing certificate. */
+    /** PEM-encoded private key paired with `signerCert`. */
     signerKey: string;
     /** Your 10-character Apple Team ID. @example "ABCD1234EF" */
     teamId: string;
     /** PEM-encoded Apple WWDR intermediate certificate. */
     wwdr: string;
 }
+/** Credentials for signing Google Wallet JWTs and calling the Wallet REST API. */
 interface GoogleCredentials {
-    /** client_email from your Google Cloud service account JSON key. */
+    /** `client_email` from your Google Cloud service account JSON key. */
     clientEmail: string;
-    /** Your Google Wallet issuer ID from the Google Pay & Wallet Console. */
+    /** Issuer ID from the Google Pay & Wallet Console. */
     issuerId: string;
-    /** private_key from your Google Cloud service account JSON key (PKCS#8 PEM). */
+    /** `private_key` from your Google Cloud service account JSON key (PKCS#8 PEM). */
     privateKey: string;
 }
+/** Credentials passed to {@link Wallet}. Omit a provider to skip that platform. */
 interface WalletCredentials {
-    /** Apple Wallet credentials. Omit to skip Apple pass generation. */
+    /** Apple Wallet credentials. Required to generate `.pkpass` files. */
     apple?: AppleCredentials;
-    /** Google Wallet credentials. Omit to skip Google pass generation. */
+    /** Google Wallet credentials. Required to generate Google Wallet JWTs. */
     google?: GoogleCredentials;
 }
+/** Result of {@link Pass.create}. */
 interface IssuedPass {
-    /** The .pkpass file as Uint8Array, ready to serve. null when Apple credentials were not provided. */
+    /** Signed `.pkpass` archive ready to serve, or `null` if Apple credentials were omitted. */
     apple: Uint8Array | null;
-    /** Signed Google Wallet JWT for the save link. null when Google credentials were not provided. */
+    /** Signed JWT for a Google Wallet save link (`pay.google.com/gp/v/save/<jwt>`), or `null` if Google credentials were omitted. */
     google: string | null;
-    /** Non-fatal warnings (e.g. optional image fetch failures). */
+    /** Non-fatal notices — e.g. a missing optional image or an unset recommended field. */
     warnings: string[];
 }
 
@@ -2376,36 +2380,133 @@ type AppLinkData = z.infer<typeof googleAppLinkDataSchema>;
 
 type FieldOptions = Omit<FieldDef, "slot" | "key" | "label">;
 type FieldArg = string | FieldOptions;
+/**
+ * Builders for pass display fields. Pass the result into the `fields` array
+ * of any pass config.
+ *
+ * The third argument is either a string (shorthand for `value`) or a full
+ * {@link FieldDef} options object for formatting, alignment, and more.
+ *
+ * @example
+ * fields: [
+ *   field.primary("points", "Points", "1 250"),
+ *   field.secondary("tier", "Tier", "Gold"),
+ *   field.back("terms", "Terms", { value: "No refunds." }),
+ * ]
+ */
 declare const 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: string, label: string, arg?: FieldArg) => FieldDef;
-    /** 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: string, label: string, arg?: FieldArg) => FieldDef;
-    /** Below primary. Apple: secondaryFields. Google: textModulesData. */
+    /**
+     * Row below the primary area.
+     *
+     * Apple → `secondaryFields`. Google → `textModulesData`.
+     */
     secondary: (key: string, label: string, arg?: FieldArg) => FieldDef;
-    /** 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: string, label: string, arg?: FieldArg) => FieldDef;
-    /** 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: string, label: string, arg?: FieldArg) => FieldDef;
 };
+/**
+ * A configured pass template. Obtain one from {@link Wallet} rather than
+ * constructing directly.
+ *
+ * Config is validated at construction time — a {@link WalletError} with code
+ * `PASS_CONFIG_INVALID` is thrown immediately if anything is wrong.
+ */
 declare class Pass {
     private readonly config;
     private readonly credentials;
     constructor(config: PassConfig, credentials: WalletCredentials);
+    /**
+     * 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.
+     */
     create(createConfig: CreateConfig): Promise<IssuedPass>;
+    /**
+     * 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.
+     */
     update(createConfig: CreateConfig): Promise<void>;
+    /**
+     * 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.
+     */
     delete(serialNumber: string): Promise<void>;
+    /**
+     * 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}.
+     */
     expire(serialNumber: string): Promise<void>;
 }
 
+/**
+ * Entry point for building passes. Construct once with your credentials,
+ * then call the pass-type methods to get a {@link Pass} you can issue.
+ *
+ * Omit a provider's credentials to skip that platform entirely —
+ * `apple` and `google` are both optional.
+ *
+ * @example
+ * const wallet = new Wallet({ apple: appleCredentials, google: googleCredentials });
+ * const result = await wallet.loyalty({ id: "rewards", name: "Rewards Card", fields: [] })
+ *   .create({ serialNumber: "user-123" });
+ */
 declare class Wallet {
     private readonly credentials;
     constructor(credentials: WalletCredentials);
+    /** Create a loyalty / rewards card pass. */
     loyalty(config: Omit<LoyaltyPassConfig, "type">): Pass;
+    /** Create an event ticket pass. */
     event(config: Omit<EventPassConfig, "type">): Pass;
+    /**
+     * 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: Omit<FlightPassConfig, "type">): Pass;
+    /** Create a coupon / offer pass. */
     coupon(config: Omit<CouponPassConfig, "type">): Pass;
+    /** Create a gift card pass. */
     giftCard(config: Omit<GiftCardPassConfig, "type">): Pass;
+    /** Create a generic pass for anything that doesn't fit the other types. */
     generic(config: Omit<GenericPassConfig, "type">): Pass;
 }
 

package/dist/index.js

@@ -574,6 +574,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)) {
@@ -1232,35 +1238,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,
@@ -1294,6 +1323,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([
@@ -1312,7 +1351,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) {
@@ -1323,8 +1368,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(
@@ -1334,8 +1383,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(
@@ -1353,21 +1407,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);
   }