addtowallet/dist/types.d.ts

Create and manage Google Wallet and Apple Wallet passes with an easy-to-use API client for Node.js and browsers.

/**
 * Configuration options for the AddToWallet client
 */
export interface AddToWalletClientOptions {
    /** Base URL for the AddToWallet API, e.g. https://app.addtowallet.co */
    baseUrl?: string;
    /** Secret API key from AddToWallet dashboard (avoid in browsers) */
    apiKey?: string;
    /** Function that returns a short-lived auth token for browser use */
    getAuthToken?: () => Promise<string> | string;
    /** Optional fetch implementation override (for Node < 18 or custom) */
    fetchFn?: typeof fetch;
    /** Optional default timeout in milliseconds for requests */
    timeoutMs?: number;
    /** Default tracking parameters to include with all pass creation requests */
    defaultTracking?: TrackingParams;
}
/**
 * Common metadata included in API responses
 */
export interface ApiResponseMeta {
    requestId?: string;
}
/**
 * Text module data for wallet passes
 */
export interface TextModuleData {
    /** Unique identifier for the text module */
    id: string;
    /** Header text for the module */
    header: string;
    /** Body text for the module */
    body: string;
}
/**
 * Link module data for wallet passes
 */
export interface LinkModuleData {
    /** Unique identifier for the link module */
    id: string;
    /** Description text for the link */
    description: string;
    /** URI for the link */
    uri: string;
}
/**
 * Tracking parameters for analytics and attribution
 */
export interface TrackingParams {
    /** Traffic source (e.g., 'npm', 'website', 'referral') */
    utm_source?: string;
    /** Traffic medium (e.g., 'api', 'integration', 'direct') */
    utm_medium?: string;
    /** Campaign name or identifier */
    utm_campaign?: string;
    /** Additional tracking identifier */
    utm_content?: string;
    /** Traffic term (for paid search) */
    utm_term?: string;
    /** Custom tracking identifier for your internal use */
    tracking_id?: string;
    /** User agent or client information */
    user_agent?: string;
    /** Referrer information */
    referrer?: string;
}
/**
 * Request payload for creating a new wallet pass
 * Based on AddToWallet API documentation
 */
export interface CreatePassRequest {
    /** Title of the card */
    cardTitle: string;
    /** Header text for the card */
    header: string;
    /** Logo URL for the card */
    logoUrl?: string;
    /** Rectangle logo URL for the card */
    rectangleLogo?: string;
    /** Hero image URL for the card */
    heroImage?: string;
    /** Google-optimized hero image URL */
    googleHeroImage?: string;
    /** Apple-optimized hero image URL */
    appleHeroImage?: string;
    /** Background color in hex format */
    hexBackgroundColor: string;
    /** Apple font color in hex format */
    appleFontColor: string;
    /** Text modules data */
    textModulesData?: TextModuleData[];
    /** Link modules data */
    linksModuleData?: LinkModuleData[];
    /** Barcode type (QR_CODE, etc.) */
    barcodeType?: string;
    /** Barcode value */
    barcodeValue?: string;
    /** Barcode alt text */
    barcodeAltText?: string;
    /** Tracking parameters for analytics and attribution */
    tracking?: TrackingParams;
}
/**
 * Summary information about a wallet pass
 */
export interface PassSummary {
    /** Unique identifier for the pass */
    id: string;
    /** Current status of the pass */
    status: 'draft' | 'active' | 'archived' | 'deleted' | string;
    /** ISO timestamp when the pass was created */
    createdAt: string;
    /** ISO timestamp when the pass was last updated */
    updatedAt?: string;
}
/**
 * Response from creating a new wallet pass
 * Based on AddToWallet API documentation
 */
export interface CreatePassResponse {
    /** Success message */
    msg: string;
    /** Card ID of the created pass */
    cardId: string;
    /** Direct URL to view/share the created pass */
    passUrl?: string;
    /** Tracking information included in the request */
    tracking?: TrackingParams;
}
/**
 * MongoDB update status
 */
export interface UpdateStatus {
    /** Whether the operation was acknowledged */
    acknowledged: boolean;
    /** Number of documents modified */
    modifiedCount: number;
    /** ID of upserted document */
    upsertedId: string | null;
    /** Number of documents upserted */
    upsertedCount: number;
    /** Number of documents matched */
    matchedCount: number;
}
/**
 * Response from updating a wallet pass
 * Based on AddToWallet API documentation
 */
export interface UpdatePassResponse {
    /** Success message */
    msg: string;
    /** Update status information */
    updateStatus: UpdateStatus;
}
/**
 * Response from deleting a wallet pass
 * Based on AddToWallet API documentation
 */
export interface DeletePassResponse {
    /** Success message */
    msg: string;
    /** Delete status information */
    deleteStatus: UpdateStatus;
}
/**
 * Request payload for updating an existing wallet pass
 * Based on AddToWallet API documentation
 */
export interface UpdatePassRequest {
    /** Title of the card */
    cardTitle?: string;
    /** Header text for the card */
    header?: string;
    /** Logo URL for the card */
    logoUrl?: string;
    /** Rectangle logo URL for the card */
    rectangleLogo?: string;
    /** Hero image URL for the card */
    heroImage?: string;
    /** Google-optimized hero image URL */
    googleHeroImage?: string;
    /** Apple-optimized hero image URL */
    appleHeroImage?: string;
    /** Background color in hex format */
    hexBackgroundColor?: string;
    /** Apple font color in hex format */
    appleFontColor?: string;
    /** Text modules data */
    textModulesData?: TextModuleData[];
    /** Link modules data */
    linksModuleData?: LinkModuleData[];
    /** Barcode type (QR_CODE, etc.) */
    barcodeType?: string;
    /** Barcode value */
    barcodeValue?: string;
    /** Barcode alt text */
    barcodeAltText?: string;
}
/**
 * Response from getting credit information
 * Based on AddToWallet API documentation
 */
export interface GetCreditsResponse {
    /** Number of premium credits remaining */
    premiumCredits: number;
    /** Number of free credits remaining */
    freeCredits: number;
}
/**
 * Pass details response
 */
export interface PassDetails {
    /** Card ID */
    cardId: string;
    /** Title of the card */
    cardTitle: string;
    /** Header text for the card */
    header: string;
    /** Logo URL for the card */
    logoUrl?: string;
    /** Rectangle logo URL for the card */
    rectangleLogo?: string;
    /** Hero image URL for the card */
    heroImage?: string;
    /** Google-optimized hero image URL */
    googleHeroImage?: string;
    /** Apple-optimized hero image URL */
    appleHeroImage?: string;
    /** Background color in hex format */
    hexBackgroundColor?: string;
    /** Apple font color in hex format */
    appleFontColor?: string;
    /** Text modules data */
    textModulesData?: TextModuleData[];
    /** Link modules data */
    linksModuleData?: LinkModuleData[];
    /** Barcode type (QR_CODE, etc.) */
    barcodeType?: string;
    /** Barcode value */
    barcodeValue?: string;
    /** Barcode alt text */
    barcodeAltText?: string;
    /** ISO timestamp when the pass was created */
    createdAt: string;
    /** ISO timestamp when the pass was last updated */
    updatedAt?: string;
}
/**
 * Response from getting a pass by ID
 */
export interface GetPassResponse extends PassDetails {
}
/**
 * Response from getting user's passes
 */
export interface GetUserPassesResponse {
    /** Array of passes */
    passes: PassSummary[];
    /** Total number of passes */
    total: number;
    /** Limit applied to the query */
    limit: number;
    /** Offset applied to the query */
    offset: number;
}
/**
 * Image upload response
 */
export interface ImageUploadResponse {
    /** URL of the uploaded image */
    url: string;
    /** Success message */
    message: string;
}
/**
 * Image upload request options
 */
export interface ImageUploadOptions {
    /** Image file to upload */
    file: File;
    /** Type of image being uploaded */
    type: 'heroImage' | 'googleHeroImage' | 'appleHeroImage' | 'logoUrl' | 'rectangleLogo' | 'barcodeImage';
}
/**
 * Public image upload response
 */
export interface PublicImageUploadResponse {
    /** URL of the uploaded image */
    url: string;
    /** Success message */
    message: string;
}
/**
 * Supported HTTP methods for API requests
 */
export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
/**
 * Internal request options for the HTTP client
 */
export interface RequestOptions {
    /** HTTP method to use */
    method: HttpMethod;
    /** API endpoint path */
    path: string;
    /** Query parameters to include in the URL */
    query?: Record<string, string | number | boolean | undefined>;
    /** Request body data */
    body?: unknown;
    /** Abort signal for request cancellation */
    signal?: AbortSignal;
}