@nosslabs/iap

Thin Capacitor IAP orchestrator. Server-side validation via Attesto.

Status: 7.0.0 — GA on @latest (the Capacitor 7+ line, built on @capgo/native-purchases). The Capacitor 5 line (cordova-plugin-purchase) continues as 5.x from the 5.x branch — ^5 ranges still resolve to 5.x. See the CHANGELOG for the GA delta and Migration for upgrading from 5.x.

npm install @nosslabs/iap @capgo/native-purchases
npx cap sync

import { createIAP } from '@nosslabs/iap';

const iap = createIAP({
  products: [
    { id: 'premium_monthly', type: 'subscription', androidPlanId: 'monthly-plan' },
  ],
  backend: {
    baseUrl: 'https://api.your-app.com',
    endpoints: {
      verifyApple: '/api/iap/verify/apple',
      verifyGoogle: '/api/iap/verify/google',
      entitlements: '/api/iap/entitlements',
      restore: '/api/iap/restore',
    },
    getAuthHeaders: async () => ({
      Authorization: `Bearer ${await getAuthToken()}`,
    }),
  },
});

await iap.initialize();

const result = await iap.purchase({ productId: 'premium_monthly' });
if (result.status === 'success') {
  // backend has validated; entitlements are cached
}

// (optional) Pre-attach a UUID so it travels through StoreKit/Play Billing
// and reaches your backend on both the verify response and the eventual
// webhook — eliminates the verify/webhook race for purchases where the
// user is signed in. Either pass a string you already have or an async
// fetcher that hits your backend (which mints+saves on first call,
// returns the existing UUID on subsequent calls).
await iap.purchase({
  productId: 'premium_monthly',
  appUserId: async () => {
    const r = await fetch('/api/iap/uuid', { method: 'POST', headers: authHeaders() });
    return (await r.json()).uuid;
  },
});

Documentation

📘 iap.nossdev.com — installation, configuration, framework recipes, API reference.

• Getting started — first purchase in 30 minutes
• Backend contract — four endpoints your backend implements
• Architecture — three-tier model
• Vue + Quasar recipe / React recipe

Why this library

@nosslabs/iap does one thing: orchestrate the purchase flow on the client. It

• wraps @capgo/native-purchases for native purchase + restore,
• POSTs to your backend (which calls Attesto) for receipt validation,
• acknowledges native transactions only after the backend confirms — autoAcknowledgePurchases: false defers finishing on both iOS and Android, so there's no phantom grant and no iOS finish-before-verify race,
• caches entitlements locally for instant, reactive UI reads,
• recovers unfinished transactions across app launches.

It does not: talk to Attesto directly, define entitlement business logic, manage user auth, or ship paywall UI. Those belong to your app and your backend.

Capacitor support matrix

Optional peer dependency

If you want auto-refresh on app resume (default behavior):

npm install @capacitor/app
npx cap sync

Or disable the listener with options.refreshOnResume: false. See installation guide.

Development

mise install        # Node 22 + npm 11 (pinned in mise.toml)
npm install
npm run typecheck   # tsc --noEmit
npm run lint        # biome check
npm test            # vitest run
npm run build       # tsup → dist/index.{js,cjs,d.ts}
npm run docs:dev    # vitepress dev (http://localhost:5173)

License

MIT — see LICENSE.