addtowallet/README.md

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

# AddToWallet

Easily create and manage Google Wallet and Apple Wallet passes with the official AddToWallet.co API client for Node.js and browsers.

- Homepage: [AddToWallet.co](https://addtowallet.co)
- Wallet pass builder:[app.addtowallet.co](https://app.addtowallet.co)
- API Docs: [AddToWallet API Docs](https://app.addtowallet.co/api-docs)
- Live Demo: [Wallet Pass Playground](https://addtowallet-npm-demo.netlify.app)

## Install

```bash
npm i addtowallet
```

## Quick start (Node / server)

```ts
import { AddToWalletClient } from 'addtowallet';

const client = new AddToWalletClient({ apiKey: process.env.ADDTOWALLET_API_KEY! });

// Create a pass (example mirrors example_apps/wallet-pass-app/src/app/page.tsx)
const { cardId, passUrl } = await client.createPass({
  logoUrl: 'https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png',
  cardTitle: 'Your Business Name',
  header: 'Amy Jane',
  textModulesData: [
    { id: 'r1start', header: 'Phone', body: '+1 8888888888' },
    { id: 'r1end', header: 'Email', body: 'amy@gmail.com' }
  ],
  linksModuleData: [
    { id: 'r1', description: 'Call Us', uri: 'tel:+1 8287489293' },
    { id: 'r2', description: 'Email Us', uri: 'mailto:support@addtowallet.co' },
    { id: 'r3', description: 'Visit our website', uri: 'https://app.addtowallet.co' },
    { id: 'r4', description: 'Visit our office', uri: 'geo:https://maps.google.com/?q=123+Main+Street,+Anytown,+CA' }
  ],
  barcodeType: 'QR_CODE',
  barcodeValue: '',
  barcodeAltText: '',
  hexBackgroundColor: '#141f31',
  appleFontColor: '#FFFFFF',
  heroImage: 'https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png'
});

console.log('Created pass:', cardId);
console.log('Shareable URL:', passUrl);
```

## Core API (no UI)

```ts
import { AddToWalletClient } from 'addtowallet';

const client = new AddToWalletClient({ apiKey: process.env.ADDTOWALLET_API_KEY! });

// Create a pass (example mirrors example_apps/wallet-pass-app/src/app/page.tsx)
const { cardId, passUrl } = await client.createPass({
  logoUrl: 'https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png',
  cardTitle: 'Your Business Name',
  header: 'Amy Jane',
  textModulesData: [
    { id: 'r1start', header: 'Phone', body: '+1 8888888888' },
    { id: 'r1end', header: 'Email', body: 'amy@gmail.com' }
  ],
  linksModuleData: [
    { id: 'r1', description: 'Call Us', uri: 'tel:+1 8287489293' },
    { id: 'r2', description: 'Email Us', uri: 'mailto:support@addtowallet.co' },
    { id: 'r3', description: 'Visit our website', uri: 'https://app.addtowallet.co' },
    { id: 'r4', description: 'Visit our office', uri: 'geo:https://maps.google.com/?q=123+Main+Street,+Anytown,+CA' }
  ],
  barcodeType: 'QR_CODE',
  barcodeValue: '',
  barcodeAltText: '',
  hexBackgroundColor: '#141f31',
  appleFontColor: '#FFFFFF',
  heroImage: 'https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png'
});
// Create a pass (example mirrors example_apps/wallet-pass-app/src/app/page.tsx)
const { cardId, passUrl } = await client.createPass({
  logoUrl: 'https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png',
  cardTitle: 'Your Business Name',
  header: 'Amy Jane',
  textModulesData: [
    { id: 'r1start', header: 'Phone', body: '+1 8888888888' },
    { id: 'r1end', header: 'Email', body: 'amy@gmail.com' }
  ],
  linksModuleData: [
    { id: 'r1', description: 'Call Us', uri: 'tel:+1 8287489293' },
    { id: 'r2', description: 'Email Us', uri: 'mailto:support@addtowallet.co' },
    { id: 'r3', description: 'Visit our website', uri: 'https://app.addtowallet.co' },
    { id: 'r4', description: 'Visit our office', uri: 'geo:https://maps.google.com/?q=123+Main+Street,+Anytown,+CA' }
  ],
  barcodeType: 'QR_CODE',
  barcodeValue: '',
  barcodeAltText: '',
  hexBackgroundColor: '#141f31',
  appleFontColor: '#FFFFFF',
  heroImage: 'https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png'
});

// Update pass
await client.updatePass(cardId, {
  cardTitle: 'Updated Card Title',
  header: 'Updated Header',
  hexBackgroundColor: '#33FF57'
});

// Get credits
const { premiumCredits, freeCredits } = await client.getCredits();
console.log('Premium credits:', premiumCredits);
console.log('Free credits:', freeCredits);

// Get pass details
const pass = await client.getPass(cardId);
console.log('Pass title:', pass.cardTitle);


// Delete pass
const { msg } = await client.deletePass(cardId);
console.log('Pass deleted:', msg);
```

## Secure frontend auth with short‑lived tokens

Never ship your AddToWallet secret in the browser. Instead, mint a short‑lived token on your server and use `getAuthToken` when constructing the client in browser code.

```ts
// Server route example: issue a short‑lived token your frontend can fetch
// Return JSON: { token: string }
```

## Configuration

- baseUrl: defaults to `https://app.addtowallet.co`
- apiKey: server‑side secret key (do not use in browsers)
- getAuthToken: async function returning a short‑lived token for frontend use
- timeoutMs: optional request timeout

## API Methods

- `createPass(payload)` → `{ msg: string, cardId: string, passUrl?: string }`
- `updatePass(cardId, payload)` → `{ msg: string, updateStatus: UpdateStatus }`
- `deletePass(cardId)` → `{ msg: string, deleteStatus: UpdateStatus }`
- `getCredits()` → `{ premiumCredits: number, freeCredits: number }`
- `getPass(cardId)` → `PassDetails`

## Pass Data Structure

When creating or updating passes, use the following structure:

```ts
{
  cardTitle: 'My Loyalty Card',
  header: 'Welcome to Our Store',
  logoUrl: 'https://example.com/logo.png',
  rectangleLogo: 'https://example.com/rectangle-logo.png',
  heroImage: 'https://example.com/hero.png',
  googleHeroImage: 'https://example.com/google-hero.png',
  appleHeroImage: 'https://example.com/apple-hero.png',
  hexBackgroundColor: '#FF5733',
  appleFontColor: '#FFFFFF',
  textModulesData: [
    {
      id: 'phone',
      header: 'Phone',
      body: '+1 555-0123'
    }
  ],
  linksModuleData: [
    {
      id: 'website',
      description: 'Visit Website',
      uri: 'https://example.com'
    }
  ],
  barcodeType: 'QR_CODE',
  barcodeValue: 'https://example.com',
  barcodeAltText: 'Scan for more info'
}
```

## Examples

This package includes complete example applications to help you get started:

- **Next.js Example** (`example_apps/wallet-pass-app/`) - A modern React/Next.js web application with a beautiful UI for creating and managing wallet passes
- **Node.js Server Example** (`example_apps/node-server-example/`) - A simple Express.js server with a web interface demonstrating all API operations

Both examples include:
- Complete setup instructions
- API key configuration
- Web-based UI for testing
- Real-time credit monitoring
- Comprehensive error handling

## Notes

- Do not embed your secret API key in client code. Use `getAuthToken`.
- Pass URLs follow the format: `https://app.addtowallet.co/card/{cardId}`
- For complete API documentation and response shapes, refer to the official docs: [AddToWallet API Docs](https://app.addtowallet.co/api-docs).
- All API requests require authentication using an API key in the `apikey` header.
- Image uploads support JPG, PNG, and WebP formats with a maximum file size of 5MB.