@wtfalch/payments 0.2.0 → 0.4.0

package/dist/stripe.js

@@ -10,6 +10,16 @@ import { PaymentProviderError, WebhookVerificationError, } from './types.js';
  *   - https://docs.stripe.com/api/refunds/create
  *   - https://docs.stripe.com/api/setup_intents
  *   - https://docs.stripe.com/webhooks (manual signature verification)
+ *
+ * Re-fetched 2026-09-28 (still primary docs, no live calls) for
+ * `stopRecurringAgreement`/`cancelPayment`/`cancelRecurringCharge`
+ * (https://docs.stripe.com/api/setup_intents/cancel,
+ * https://docs.stripe.com/api/payment_intents/cancel) and
+ * `updateRecurringAgreement` (https://docs.stripe.com/api/setup_intents/update).
+ * This adapter's "recurring agreement" is a SetupIntent, not a Subscription
+ * (see `createRecurringAgreement`'s doc comment below) -- there is no
+ * Subscription object anywhere in this file, so its cancel/update endpoints
+ * are never the ones used here.
  */
 import { hmacSha256Hex, safeEqual } from './webhook-crypto.js';
 /** Form-urlencodes Stripe's `/v1` request bodies, including one level of
@@ -159,6 +169,18 @@ export function createStripeProvider(options) {
                 raw: refund,
             };
         },
+        async cancelPayment(providerReference, input = {}) {
+            // https://docs.stripe.com/api/payment_intents/cancel (fetched
+            // 2026-09-28). Cancelable from requires_payment_method,
+            // requires_capture, requires_confirmation, requires_action, or (rarely)
+            // processing -- Stripe itself refuses any other status.
+            const pi = await call(`/payment_intents/${providerReference}/cancel`, {}, input.idempotencyKey ?? `cnc:${providerReference}`);
+            // Same integrity check as capturePayment/refundPayment.
+            if (pi.id !== providerReference) {
+                throw new PaymentProviderError('stripe', `cancel response id "${pi.id}" does not match the requested payment "${providerReference}"`, { raw: pi });
+            }
+            return toPaymentResult(pi);
+        },
         async createRecurringAgreement(input) {
             // Vipps-only: a SetupIntent has no pricing type or cap to declare up
             // front -- it only saves a payment method, and the amount for each
@@ -202,6 +224,74 @@ export function createStripeProvider(options) {
             }, input.idempotencyKey);
             return toPaymentResult(pi);
         },
+        async getRecurringAgreement(agreementReference) {
+            const si = await get(`/setup_intents/${agreementReference}`);
+            return {
+                provider: 'stripe',
+                agreementReference: si.id,
+                status: SETUP_INTENT_STATUS[si.status] ?? 'pending',
+                clientSecret: si.client_secret,
+                raw: si,
+            };
+        },
+        async stopRecurringAgreement(agreementReference, input = {}) {
+            // https://docs.stripe.com/api/setup_intents/cancel (fetched
+            // 2026-09-28). This adapter's "recurring agreement" is a SetupIntent,
+            // not a Subscription (module doc comment) -- stopping it is cancelling
+            // that SetupIntent, the same transition `WEBHOOK_EVENT_TYPE`'s
+            // `setup_intent.canceled` -> `agreement.stopped` mapping already
+            // assumes. Cancelable only from requires_payment_method,
+            // requires_confirmation or requires_action; Stripe refuses any other
+            // status (e.g. an already-`succeeded` SetupIntent) with an error this
+            // call surfaces as `PaymentProviderError`.
+            const si = await call(`/setup_intents/${agreementReference}/cancel`, {}, input.idempotencyKey ?? `stop:${agreementReference}`);
+            if (si.id !== agreementReference) {
+                throw new PaymentProviderError('stripe', `cancel response id "${si.id}" does not match the requested agreement "${agreementReference}"`, { raw: si });
+            }
+            return {
+                provider: 'stripe',
+                agreementReference: si.id,
+                status: SETUP_INTENT_STATUS[si.status] ?? 'pending',
+                clientSecret: si.client_secret,
+                raw: si,
+            };
+        },
+        async updateRecurringAgreement(agreementReference, input) {
+            // https://docs.stripe.com/api/setup_intents/update (fetched
+            // 2026-09-28). A SetupIntent has no price of its own to change (module
+            // doc comment) -- this keeps `metadata[amount]`/`metadata[currency]`
+            // (set at `createRecurringAgreement` time, for symmetry with Vipps) in
+            // sync with a caller's own plan/price change; `chargeRecurringAgreement`
+            // always reads its charge amount from its own caller, never from here,
+            // so this has no effect on what a later charge actually bills.
+            const si = await call(`/setup_intents/${agreementReference}`, {
+                'metadata[amount]': input.amount.value,
+                'metadata[currency]': input.amount.currency.toUpperCase(),
+            }, input.idempotencyKey ??
+                `upd:${agreementReference}:${input.amount.value}:${input.amount.currency.toUpperCase()}`);
+            if (si.id !== agreementReference) {
+                throw new PaymentProviderError('stripe', `update response id "${si.id}" does not match the requested agreement "${agreementReference}"`, { raw: si });
+            }
+            return {
+                provider: 'stripe',
+                agreementReference: si.id,
+                status: SETUP_INTENT_STATUS[si.status] ?? 'pending',
+                clientSecret: si.client_secret,
+                raw: si,
+            };
+        },
+        async cancelRecurringCharge(_agreementReference, chargeReference, input = {}) {
+            // A recurring charge is a PaymentIntent here (`chargeRecurringAgreement`'s
+            // doc comment) -- Stripe has no separate "recurring charge" resource
+            // the way Vipps' Recurring API does, so cancelling one is the same
+            // PaymentIntent cancel call `cancelPayment` makes.
+            // https://docs.stripe.com/api/payment_intents/cancel (fetched
+            // 2026-09-28).
+            const pi = await call(`/payment_intents/${chargeReference}/cancel`, {}, input.idempotencyKey ?? `dch:${chargeReference}`);
+            if (pi.id !== chargeReference) {
+                throw new PaymentProviderError('stripe', `cancel response id "${pi.id}" does not match the requested charge "${chargeReference}"`, { raw: pi });
+            }
+        },
     };
 }
 const WEBHOOK_EVENT_TYPE = {
@@ -213,6 +303,13 @@ const WEBHOOK_EVENT_TYPE = {
     'payment_intent.payment_failed': 'payment.failed',
     'charge.refunded': 'payment.refunded',
     'charge.refund.updated': 'payment.refunded',
+    // A SetupIntent is this adapter's recurring agreement (module doc
+    // comment): its own lifecycle events normalize to the same `agreement.*`
+    // names Vipps' Recurring API webhooks use, so `store.ts`'s
+    // `applyWebhookEvent` never branches on provider.
+    'setup_intent.succeeded': 'agreement.activated',
+    'setup_intent.canceled': 'agreement.stopped',
+    'setup_intent.setup_failed': 'agreement.rejected',
 };
 /**
  * Verifies a Stripe webhook's `Stripe-Signature` header against the raw
@@ -267,7 +364,13 @@ export function verifyStripeWebhook(rawBody, signatureHeader, webhookSecret, opt
         throw new WebhookVerificationError('stripe', 'payload is not valid JSON');
     }
     const object = event.data?.object;
-    const paymentReference = object?.payment_intent ?? object?.id ?? '';
+    // A `setup_intent.*` event is about the agreement itself, never a
+    // payment -- its object has neither a payment_intent nor anything this
+    // package would call a paymentReference. See `getRecurringAgreement`'s
+    // module doc comment and `WEBHOOK_EVENT_TYPE`'s `setup_intent.*` entries.
+    const isSetupIntentEvent = (event.type ?? '').startsWith('setup_intent.');
+    const paymentReference = isSetupIntentEvent ? '' : (object?.payment_intent ?? object?.id ?? '');
+    const agreementReference = isSetupIntentEvent ? object?.id : undefined;
     const amount = typeof object?.amount === 'number' && object.currency
         ? { value: object.amount, currency: object.currency.toUpperCase() }
         : undefined;
@@ -276,6 +379,7 @@ export function verifyStripeWebhook(rawBody, signatureHeader, webhookSecret, opt
         type: WEBHOOK_EVENT_TYPE[event.type ?? ''] ?? 'unknown',
         eventId: event.id ?? '',
         paymentReference,
+        agreementReference,
         amount,
         raw: event,
     };

package/dist/types.d.ts

@@ -37,6 +37,9 @@ export interface RefundInput {
     readonly reason?: 'duplicate' | 'fraudulent' | 'requested_by_customer';
     readonly idempotencyKey?: string;
 }
+export interface CancelPaymentInput {
+    readonly idempotencyKey?: string;
+}
 export interface PaymentResult {
     readonly provider: 'stripe' | 'vipps';
     /** The provider's own identifier for this payment (Stripe: PaymentIntent
@@ -114,17 +117,51 @@ export interface ChargeRecurringAgreementInput {
     readonly dueDate?: string;
     readonly idempotencyKey?: string;
 }
+export interface StopRecurringAgreementInput {
+    readonly idempotencyKey?: string;
+}
+/** A plan/price change to an existing agreement. Vipps: `PATCH
+ * /recurring/v3/agreements/{id}` with `pricing.amount` (the LEGACY fixed
+ * price) -- see `updateRecurringAgreement`'s doc comment on each adapter for
+ * why a VARIABLE or FLEXIBLE agreement's payer-driven cap is not covered by
+ * this input, and why Vipps refuses this update outright on either. Stripe:
+ * no price lives on a SetupIntent, so this keeps its
+ * `metadata[amount]`/`metadata[currency]` (set at `createRecurringAgreement`
+ * time, for symmetry with Vipps) in sync with a caller's own plan change. */
+export interface UpdateRecurringAgreementInput {
+    readonly amount: Money;
+    readonly idempotencyKey?: string;
+}
+export interface CancelRecurringChargeInput {
+    readonly idempotencyKey?: string;
+}
 /** A closed set, plus `unknown`. A provider event type this package does not
  * yet recognise normalizes to `unknown` rather than throwing, so a new
- * Stripe or Vipps event is forward-compatible, not a crash. */
-export type NormalizedWebhookEventType = 'payment.created' | 'payment.authorized' | 'payment.captured' | 'payment.refunded' | 'payment.cancelled' | 'payment.failed' | 'payment.expired' | 'unknown';
+ * Stripe or Vipps event is forward-compatible, not a crash.
+ *
+ * `payment.*` is a one-off ePayment/PaymentIntent event (`createPayment`,
+ * `capturePayment`, `refundPayment`). `agreement.*` and `charge.*` are the
+ * recurring-agreement lifecycle `store.ts`'s `applyWebhookEvent` acts on --
+ * Vipps' own Recurring API webhook catalogue (`recurring.agreement-*.v1`,
+ * `recurring.charge-*.v1`); Stripe's SetupIntent events are normalized into
+ * the same `agreement.*` names (`succeeded`->`activated`,
+ * `canceled`->`stopped`, `setup_failed`->`rejected`) and its off-session
+ * PaymentIntent charge into the same `charge.*` names, so a caller of
+ * `applyWebhookEvent` never branches on provider. */
+export type NormalizedWebhookEventType = 'payment.created' | 'payment.authorized' | 'payment.captured' | 'payment.refunded' | 'payment.cancelled' | 'payment.failed' | 'payment.expired' | 'agreement.activated' | 'agreement.rejected' | 'agreement.stopped' | 'agreement.expired' | 'charge.reserved' | 'charge.captured' | 'charge.canceled' | 'charge.refunded' | 'charge.failed' | 'unknown';
 export interface NormalizedWebhookEvent {
     readonly provider: 'stripe' | 'vipps';
     readonly type: NormalizedWebhookEventType;
     /** The provider's own event id, for de-duplicating retried deliveries. */
     readonly eventId: string;
-    /** Matches `PaymentResult.providerReference` / the payment this event is about. */
+    /** Matches `PaymentResult.providerReference` -- the one-off payment or
+     * recurring charge this event is about. Empty string for an
+     * `agreement.*` event, which is about the agreement alone. */
     readonly paymentReference: string;
+    /** Matches `RecurringAgreementResult.agreementReference`. Present on every
+     * `agreement.*` and `charge.*` event; absent on a one-off `payment.*` event,
+     * which has no agreement. */
+    readonly agreementReference?: string;
     readonly amount?: Money;
     /** The provider's own event payload, for anything this shape does not carry. */
     readonly raw: unknown;
@@ -136,9 +173,18 @@ export declare class PaymentProviderError extends Error {
     readonly provider: 'stripe' | 'vipps';
     readonly status?: number;
     readonly raw?: unknown;
+    /** A narrow, provider-adapter-defined tag for a failure a caller needs to
+     * distinguish from an ordinary provider-call failure -- e.g. Vipps'
+     * `cancelPayment` sets `'cancel_amount_unknown'` when a cancel went
+     * through but no amount could be read even after re-reading the payment,
+     * so a caller can tell that apart from "the cancel itself failed" instead
+     * of both looking like the same generic error. Absent on a plain HTTP/network
+     * failure. */
+    readonly code?: string;
     constructor(provider: 'stripe' | 'vipps', message: string, options?: {
         status?: number;
         raw?: unknown;
+        code?: string;
     });
 }
 /** A webhook payload failed to verify: missing/malformed signature header,

package/dist/types.js

@@ -10,12 +10,21 @@ export class PaymentProviderError extends Error {
     provider;
     status;
     raw;
+    /** A narrow, provider-adapter-defined tag for a failure a caller needs to
+     * distinguish from an ordinary provider-call failure -- e.g. Vipps'
+     * `cancelPayment` sets `'cancel_amount_unknown'` when a cancel went
+     * through but no amount could be read even after re-reading the payment,
+     * so a caller can tell that apart from "the cancel itself failed" instead
+     * of both looking like the same generic error. Absent on a plain HTTP/network
+     * failure. */
+    code;
     constructor(provider, message, options = {}) {
         super(`payments(${provider}): ${message}`);
         this.name = 'PaymentProviderError';
         this.provider = provider;
         this.status = options.status;
         this.raw = options.raw;
+        this.code = options.code;
     }
 }
 /** A webhook payload failed to verify: missing/malformed signature header,

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 {