@wtfalch/payments 0.1.0 → 0.3.0

package/dist/vipps.d.ts

@@ -6,14 +6,37 @@ export interface VippsProviderOptions {
     readonly subscriptionKey: string;
     /** `Merchant-Serial-Number`: the sales unit's MSN. */
     readonly merchantSerialNumber: string;
-    /** A valid OAuth access token. The caller obtains and refreshes this
-     * (`POST /accesstoken/get`); this package never does, the same as it
-     * never resolves a Stripe secret key on its own -- see the module doc
-     * comment. */
-    readonly accessToken: string;
+    /**
+     * A valid OAuth access token, already fetched. Given this, the adapter
+     * never calls `POST /accesstoken/get` itself and never refreshes it --
+     * the caller must, on its own schedule. This is v1's shape (0.2.x and
+     * earlier), kept so an existing caller migrates by adding
+     * `clientId`/`clientSecret` on its own timeline rather than in lockstep
+     * with a version bump.
+     *
+     * Exactly one of `accessToken` or `clientId`+`clientSecret` must be given.
+     */
+    readonly accessToken?: string;
+    /** The sales unit's OAuth client id, for this adapter to fetch and cache
+     * its own access token. Requires `clientSecret`. See
+     * docs/adr/0007-vipps-access-token-caching.md. */
+    readonly clientId?: string;
+    /** The sales unit's OAuth client secret. Requires `clientId`. */
+    readonly clientSecret?: string;
+    /** Seconds of safety margin before a cached token's real expiry at which
+     * this adapter fetches a new one instead of reusing it, so a request that
+     * starts just under the deadline does not race the token's own expiry.
+     * Default: 60. */
+    readonly tokenRefreshMarginSeconds?: number;
     readonly fetch?: FetchLike;
     /** Override for testing. Defaults to `https://api.vipps.no`. */
     readonly baseUrl?: string;
+    /** Override for testing. Defaults to `https://api.vipps.no/accesstoken/get`. */
+    readonly tokenUrl?: string;
+    /** Aborts any request (including the token fetch) still pending after
+     * this many milliseconds, via `AbortSignal.timeout`. Default: 10 000
+     * (10s). A provider that never responds must not hang its caller forever. */
+    readonly timeoutMs?: number;
 }
 export declare function createVippsProvider(options: VippsProviderOptions): PaymentProvider;
 export interface VippsWebhookHeaders {

package/dist/vipps.js

@@ -5,22 +5,41 @@ import { PaymentProviderError, WebhookVerificationError, } from './types.js';
  * REST APIs -- no Vipps SDK (there is no single official Node one). See
  * docs/adr/0003-plain-http-no-provider-sdks.md.
  *
- * Sources (fetched 2026-09-23, primary docs, no live calls):
+ * Sources (fetched 2026-09-23/24, primary docs, no live calls):
  *   - https://developer.vippsmobilepay.com/api/epayment/ (create, capture, cancel, refund)
- *   - https://developer.vippsmobilepay.com/api/recurring/ (agreements, charges)
+ *   - https://developer.vippsmobilepay.com/api/recurring/ (agreements, charges, status enum)
  *   - https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/request-authentication/
+ *   - https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events/ (event catalogue)
+ *   - https://developer.vippsmobilepay.com/docs/knowledge-base/across-borders/ (Nordic markets)
+ *   - https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/
  *
- * Two things v1 deliberately leaves to the caller, recorded here and in the
- * ledger's Fog rather than guessed at:
- *   - the OAuth access token (`POST /accesstoken/get`): this adapter takes
- *     an already-valid `accessToken` and never fetches or refreshes one
- *     itself, the same "caller resolves the credential" shape as `stripe.ts`.
- *   - the exact `state` enum on a payment/capture/refund response: the
- *     fetched docs were not fully explicit about it, so `derivePaymentStatus`
- *     below falls back to the `aggregate.*Amount` fields, which the docs did
- *     confirm, whenever `state` is absent or unrecognised.
+ * One Recurring/ePayment API serves all three Nordic markets (see
+ * docs/adr/0006-payment-store.md's "MobilePay" section and this package's
+ * README, "MobilePay (Denmark, Finland)"): same base URL, same headers, same
+ * request/response shapes. What differs is the sales unit's own currency
+ * (NOK/DKK/EUR) and per-market amount ceiling, both the caller's concern
+ * (`Money.currency`, `CreateRecurringAgreementInput.amount`), never this
+ * adapter's -- `createVippsProvider` needs no market-specific option.
+ *
+ * `docs/adr/0007-vipps-access-token-caching.md` covers this adapter now
+ * fetching and caching its own OAuth access token (`POST /accesstoken/get`),
+ * superseding v1's "the caller resolves it" stance (see that ADR for why
+ * this does not force the service shape -- docs/adr/0001).
+ *
+ * Still not confirmed from primary docs: the exact `state` enum on an
+ * ePayment payment/capture/refund response (`derivePaymentStatus` below
+ * falls back to the `aggregate.*Amount` fields whenever `state` is absent
+ * or unrecognised), and the exact field carrying a Recurring webhook
+ * event's own id (`normalizeRecurringEvent` below synthesizes one the same
+ * way the ePayment side already did, for the same reason).
  */
 import { hmacSha256Base64, safeEqual, sha256Base64 } from './webhook-crypto.js';
+const AGREEMENT_STATUS = {
+    PENDING: 'pending',
+    ACTIVE: 'active',
+    STOPPED: 'stopped',
+    EXPIRED: 'expired',
+};
 const PAYMENT_STATE = {
     CREATED: 'pending',
     AUTHORIZED: 'authorized',
@@ -80,14 +99,80 @@ function tomorrowIsoDate() {
     return d.toISOString().slice(0, 10);
 }
 export function createVippsProvider(options) {
+    if (!options.accessToken && !(options.clientId && options.clientSecret)) {
+        throw new PaymentProviderError('vipps', 'createVippsProvider needs either accessToken, or both clientId and clientSecret');
+    }
     const fetchImpl = options.fetch ?? defaultFetch();
     const baseUrl = options.baseUrl ?? 'https://api.vipps.no';
-    function headers(idempotencyKey) {
+    const tokenUrl = options.tokenUrl ?? 'https://api.vipps.no/accesstoken/get';
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const refreshMarginMs = (options.tokenRefreshMarginSeconds ?? 60) * 1000;
+    // Token cache, scoped to this provider instance (one per `subscriptionKey`
+    // + `merchantSerialNumber` pair, ordinarily). `inFlight` is the one thing
+    // that makes this concurrency-safe: N callers racing `resolveAccessToken`
+    // while the cache is empty or expired share the same `POST
+    // /accesstoken/get` promise instead of each firing their own -- assigned
+    // before any `await`, so there is no gap between "check the cache" and
+    // "start a refresh" for a second caller to land in. Cleared in `finally`,
+    // on success and on failure alike: a failed refresh must not wedge every
+    // later call behind a promise that has already rejected.
+    let cached = null;
+    let inFlight = null;
+    async function fetchAccessToken() {
+        const response = await fetchImpl(tokenUrl, {
+            method: 'POST',
+            headers: {
+                client_id: options.clientId,
+                client_secret: options.clientSecret,
+                'Ocp-Apim-Subscription-Key': options.subscriptionKey,
+                'Merchant-Serial-Number': options.merchantSerialNumber,
+            },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const parsed = await response.json();
+        if (!response.ok) {
+            throw new PaymentProviderError('vipps', `access token request failed: HTTP ${response.status}`, {
+                status: response.status,
+                raw: parsed,
+            });
+        }
+        const body = parsed;
+        if (!body.access_token) {
+            throw new PaymentProviderError('vipps', 'access token response has no "access_token" field', {
+                raw: parsed,
+            });
+        }
+        const expiresInSeconds = Number(body.expires_in ?? 0);
+        cached = {
+            token: body.access_token,
+            // A missing/unparsable expires_in caches nothing usable: expiresAtMs
+            // stays in the past, so the very next call refreshes again rather
+            // than reusing a token whose real lifetime is unknown.
+            expiresAtMs: Number.isFinite(expiresInSeconds) && expiresInSeconds > 0
+                ? Date.now() + expiresInSeconds * 1000
+                : 0,
+        };
+        return cached.token;
+    }
+    async function resolveAccessToken() {
+        if (options.accessToken)
+            return options.accessToken; // v1 shape: caller-managed, never cached/refreshed here
+        if (cached && cached.expiresAtMs - refreshMarginMs > Date.now())
+            return cached.token;
+        if (!inFlight) {
+            inFlight = fetchAccessToken().finally(() => {
+                inFlight = null;
+            });
+        }
+        return inFlight;
+    }
+    async function resolveHeaders(idempotencyKey) {
+        const token = await resolveAccessToken();
         const h = {
             'Content-Type': 'application/json',
             'Ocp-Apim-Subscription-Key': options.subscriptionKey,
             'Merchant-Serial-Number': options.merchantSerialNumber,
-            Authorization: `Bearer ${options.accessToken}`,
+            Authorization: `Bearer ${token}`,
         };
         if (idempotencyKey)
             h['Idempotency-Key'] = idempotencyKey;
@@ -96,8 +181,9 @@ export function createVippsProvider(options) {
     async function post(path, body, idempotencyKey) {
         const response = await fetchImpl(`${baseUrl}${path}`, {
             method: 'POST',
-            headers: headers(idempotencyKey),
+            headers: await resolveHeaders(idempotencyKey),
             body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
         });
         const parsed = await response.json();
         if (!response.ok) {
@@ -111,7 +197,8 @@ export function createVippsProvider(options) {
     async function get(path) {
         const response = await fetchImpl(`${baseUrl}${path}`, {
             method: 'GET',
-            headers: headers(undefined),
+            headers: await resolveHeaders(undefined),
+            signal: AbortSignal.timeout(timeoutMs),
         });
         const parsed = await response.json();
         if (!response.ok) {
@@ -187,12 +274,21 @@ export function createVippsProvider(options) {
             };
         },
         async createRecurringAgreement(input) {
-            const agreement = await post('/recurring/v3/agreements', {
-                pricing: {
+            // pricing.type LEGACY (fixed amount) vs VARIABLE (suggestedMaxAmount,
+            // no fixed amount): https://developer.vippsmobilepay.com/api/recurring/
+            const pricing = input.variablePricing
+                ? {
+                    type: 'VARIABLE',
+                    currency: input.amount.currency.toUpperCase(),
+                    suggestedMaxAmount: input.variablePricing.suggestedMaxAmount,
+                }
+                : {
                     type: 'LEGACY',
                     amount: input.amount.value,
                     currency: input.amount.currency.toUpperCase(),
-                },
+                };
+            const agreement = await post('/recurring/v3/agreements', {
+                pricing,
                 interval: {
                     unit: (input.interval?.unit ?? 'month').toUpperCase(),
                     count: input.interval?.count ?? 1,
@@ -212,9 +308,16 @@ export function createVippsProvider(options) {
             };
         },
         async chargeRecurringAgreement(agreementReference, input) {
+            // No `currency` field here: the charge schema at
+            // https://developer.vippsmobilepay.com/api/recurring/ has no such
+            // property -- the charge always uses the agreement's own currency, so
+            // sending one was a mismatch with the documented request body (fixed
+            // here, not merely renamed). For a VARIABLE agreement, Vipps enforces
+            // amount <= the payer's accepted max itself: a charge above it is
+            // held `DUE`, not rejected synchronously here, so this adapter does
+            // not duplicate that check.
             const charge = await post(`/recurring/v3/agreements/${agreementReference}/charges`, {
                 amount: input.amount.value,
-                currency: input.amount.currency.toUpperCase(),
                 transactionType: 'DIRECT_CAPTURE',
                 due: input.dueDate ?? tomorrowIsoDate(),
                 retryDays: 0,
@@ -231,6 +334,16 @@ export function createVippsProvider(options) {
                 raw: charge,
             };
         },
+        async getRecurringAgreement(agreementReference) {
+            const agreement = await get(`/recurring/v3/agreements/${agreementReference}`);
+            return {
+                provider: 'vipps',
+                agreementReference: agreement.agreementId,
+                status: (agreement.status ? AGREEMENT_STATUS[agreement.status] : undefined) ?? 'pending',
+                confirmationUrl: agreement.vippsConfirmationUrl,
+                raw: agreement,
+            };
+        },
     };
 }
 const WEBHOOK_EVENT_NAME = {
@@ -243,6 +356,42 @@ const WEBHOOK_EVENT_NAME = {
     EXPIRED: 'payment.expired',
     ABORTED: 'payment.cancelled',
 };
+/** The Recurring API's own webhook event catalogue -- a different namespace
+ * from the ePayment `name` field `WEBHOOK_EVENT_NAME` above maps.
+ * https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events/
+ * (fetched 2026-09-24 via a documentation-summarizing tool, the same
+ * caveat docs/adr/0004 already carries for the ePayment side -- not
+ * checked against one real signed Vipps delivery). */
+const RECURRING_EVENT_TYPE = {
+    'recurring.agreement-activated.v1': 'agreement.activated',
+    'recurring.agreement-rejected.v1': 'agreement.rejected',
+    'recurring.agreement-stopped.v1': 'agreement.stopped',
+    'recurring.agreement-expired.v1': 'agreement.expired',
+    'recurring.charge-reserved.v1': 'charge.reserved',
+    'recurring.charge-captured.v1': 'charge.captured',
+    'recurring.charge-canceled.v1': 'charge.canceled',
+    'recurring.charge-refunded.v1': 'charge.refunded',
+    'recurring.charge-failed.v1': 'charge.failed',
+    'recurring.charge-creation-failed.v1': 'charge.failed',
+};
+/** A Recurring event names one agreement always, and a charge only for a
+ * `charge.*` type -- `paymentReference` (which `store.ts` matches against
+ * `payment_charges.provider_charge_id`) is empty for an `agreement.*` event,
+ * which has none. No documented event id field (unlike the ePayment side's
+ * `idempotencyKey`), so `eventId` is synthesized from what is documented,
+ * the same fallback shape the ePayment path below already uses. */
+function normalizeRecurringEvent(event) {
+    const amount = event.amountCaptured ?? event.amountCanceled ?? event.amountRefunded ?? event.amount;
+    return {
+        provider: 'vipps',
+        type: RECURRING_EVENT_TYPE[event.eventType] ?? 'unknown',
+        eventId: `${event.agreementId ?? 'unknown'}:${event.chargeId ?? ''}:${event.eventType}:${event.occurred ?? ''}`,
+        paymentReference: event.chargeId ?? '',
+        agreementReference: event.agreementId,
+        amount: amount ? { value: amount.value, currency: amount.currency.toUpperCase() } : undefined,
+        raw: event,
+    };
+}
 /**
  * Verifies a Vipps MobilePay webhook request, by hand, against the
  * Azure-API-Management-style HMAC scheme documented at
@@ -298,6 +447,12 @@ export function verifyVippsWebhook(rawBody, requestHeaders, webhookSecret, metho
     catch {
         throw new WebhookVerificationError('vipps', 'payload is not valid JSON');
     }
+    // Two payload shapes share this endpoint's signature scheme: ePayment's
+    // (`name`/`success`, handled below) and the Recurring API's (`eventType`,
+    // agreement/charge events -- see normalizeRecurringEvent's doc comment).
+    if (event.eventType) {
+        return normalizeRecurringEvent(event);
+    }
     const mapped = event.name ? WEBHOOK_EVENT_NAME[event.name] : undefined;
     const type = event.success === false ? 'payment.failed' : (mapped ?? 'unknown');
     return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wtfalch/payments",
-  "version": "0.1.0",
-  "description": "One PaymentProvider interface -- create a payment, capture, refund, set up and charge a recurring agreement, verify a webhook -- over Stripe and Vipps MobilePay. Holds no card data.",
+  "version": "0.3.0",
+  "description": "One PaymentProvider interface -- create a payment, capture, refund, set up and charge a recurring agreement, verify a webhook -- over Stripe and Vipps MobilePay, plus a provider-neutral Postgres store for agreements and charges. Holds no card data.",
   "repository": {
     "type": "git",
     "url": "https://github.com/wtfalch/payments",
@@ -9,16 +9,13 @@
   },
   "license": "MIT",
   "type": "module",
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": ["dist", "README.md", "LICENSE"],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./migrations/*.sql": "./dist/migrations/*.sql",
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -28,14 +25,17 @@
   "engines": {
     "node": ">=22.0.0"
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-migrations.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "pnpm build"
+  },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.5.8",
     "@types/node": "^22",
+    "postgres": "^3.4.5",
     "typescript": "^5.9.0",
     "vitest": "^4.1.6"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
   }
-}
+}