@molecule/api-payments-stripe 1.0.0

package/dist/connect.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Stripe Connect support for the Stripe payment provider.
+ *
+ * Adds split-payment / payouts helpers on top of the existing
+ * `@molecule/api-payments-stripe` bond surface so multi-vendor / two-sided
+ * marketplace apps (course-marketplace, food-delivery, multi-vendor-marketplace,
+ * rental-marketplace, tutoring-marketplace, venue-booking, crowdfunding,
+ * pet-care, telemedicine, etc.) can:
+ *   - Onboard sellers / drivers / providers (`createConnectedAccount` + `createAccountLink`).
+ *   - Move funds into connected accounts (`createTransfer`).
+ *   - Trigger payouts (`createPayout`).
+ *   - Inspect onboarding/eligibility status (`getAccountStatus`).
+ *   - Handle Connect-specific webhooks (`processConnectWebhook`).
+ *
+ * @see https://stripe.com/docs/connect
+ *
+ * @module
+ */
+/**
+ * Connected account type.
+ *
+ * Stripe distinguishes three account types with different
+ * onboarding / dashboard responsibilities. See
+ * https://stripe.com/docs/connect/accounts.
+ */
+export type ConnectedAccountType = 'standard' | 'express' | 'custom';
+/**
+ * Subset of Stripe `business_profile` fields commonly set during marketplace
+ * onboarding.
+ */
+export interface ConnectedAccountBusinessProfile {
+    name?: string;
+    url?: string;
+    productDescription?: string;
+    supportEmail?: string;
+    supportPhone?: string;
+    mcc?: string;
+}
+/**
+ * Parameters for creating a connected account.
+ */
+export interface CreateConnectedAccountParams {
+    /** Stripe account type — `standard`, `express`, or `custom`. */
+    type: ConnectedAccountType;
+    /** Two-letter ISO country code for the account holder (e.g. `US`, `GB`). */
+    country: string;
+    /** Email address of the account holder. */
+    email: string;
+    /** Optional business profile fields (display name, website, MCC, etc.). */
+    businessProfile?: ConnectedAccountBusinessProfile;
+    /** Optional metadata to attach to the connected account. */
+    metadata?: Record<string, string>;
+    /** Optional idempotency key for safe retries. */
+    idempotencyKey?: string;
+}
+/**
+ * Result of creating a connected account.
+ */
+export interface CreateConnectedAccountResult {
+    /** Stripe connected account ID (`acct_...`). */
+    id: string;
+    /** Optional onboarding URL (only present when an account link is created in the same flow). */
+    accountLinkUrl?: string;
+}
+/**
+ * Account-link types — onboarding (first-time) vs update (returning).
+ */
+export type AccountLinkType = 'account_onboarding' | 'account_update';
+/**
+ * Parameters for creating an account link.
+ */
+export interface CreateAccountLinkParams {
+    /** Stripe connected account ID (`acct_...`). */
+    accountId: string;
+    /** URL Stripe redirects the user back to after onboarding completes. */
+    returnUrl: string;
+    /** URL Stripe redirects the user to if the link expires before completion. */
+    refreshUrl: string;
+    /** Whether this is a first-time onboarding link or an update link. */
+    type: AccountLinkType;
+    /** Optional idempotency key for safe retries. */
+    idempotencyKey?: string;
+}
+/**
+ * Result of creating an account link.
+ */
+export interface CreateAccountLinkResult {
+    /** Hosted onboarding URL the connected account holder should open. */
+    url: string;
+    /** Unix timestamp (seconds) when the link expires. */
+    expiresAt: number;
+}
+/**
+ * Parameters for creating a transfer to a connected account.
+ */
+export interface CreateTransferParams {
+    /** Amount in the smallest currency unit (e.g. cents for USD). */
+    amount: number;
+    /** Three-letter ISO currency code, lowercase (e.g. `usd`). */
+    currency: string;
+    /** Destination connected account ID (`acct_...`). */
+    destination: string;
+    /** Optional source charge to attach the transfer to (for separate-charges-and-transfers flow). */
+    sourceTransaction?: string;
+    /** Optional transfer group string (groups related transfers/charges together). */
+    transferGroup?: string;
+    /** Optional metadata. */
+    metadata?: Record<string, string>;
+    /** Optional idempotency key for safe retries. */
+    idempotencyKey?: string;
+}
+/**
+ * Result of creating a transfer.
+ */
+export interface CreateTransferResult {
+    /** Stripe transfer ID (`tr_...`). */
+    id: string;
+    /** Amount transferred (smallest currency unit). */
+    amount: number;
+    /** Three-letter ISO currency code. */
+    currency: string;
+    /** Destination connected account ID. */
+    destination: string;
+    /** Transfer group, if set. */
+    transferGroup?: string;
+}
+/**
+ * Parameters for creating a payout from a connected account's Stripe balance to its bank account.
+ */
+export interface CreatePayoutParams {
+    /** Connected account ID to issue the payout from (`acct_...`). */
+    accountId: string;
+    /** Amount in the smallest currency unit (e.g. cents for USD). */
+    amount: number;
+    /** Three-letter ISO currency code, lowercase (e.g. `usd`). */
+    currency: string;
+    /** Optional payout method — `standard` or `instant`. */
+    method?: 'standard' | 'instant';
+    /** Optional metadata. */
+    metadata?: Record<string, string>;
+    /** Optional idempotency key for safe retries. */
+    idempotencyKey?: string;
+}
+/**
+ * Result of creating a payout.
+ */
+export interface CreatePayoutResult {
+    /** Stripe payout ID (`po_...`). */
+    id: string;
+    /** Amount paid out (smallest currency unit). */
+    amount: number;
+    /** Three-letter ISO currency code. */
+    currency: string;
+    /** Payout status (e.g. `pending`, `paid`, `failed`). */
+    status: string;
+    /** Estimated arrival date (Unix timestamp in seconds). */
+    arrivalDate: number;
+}
+/**
+ * Connected-account onboarding / payout eligibility status.
+ */
+export interface AccountStatus {
+    /** Stripe connected account ID. */
+    id: string;
+    /** Whether the account can accept charges. */
+    chargesEnabled: boolean;
+    /** Whether the account can receive payouts. */
+    payoutsEnabled: boolean;
+    /** Whether there are any currently-due requirements (Stripe is blocked on something). */
+    requirementsCurrent: boolean;
+    /** Stripe connected-account type (`standard`, `express`, `custom`), if known. */
+    type?: ConnectedAccountType;
+    /** Currently-due requirement IDs from Stripe (empty when nothing is due). */
+    currentlyDue: readonly string[];
+}
+/**
+ * Connect webhook event types this provider knows how to interpret.
+ *
+ * `unknown` is returned for any other Stripe event so callers can fall
+ * through to the standard subscription webhook handler if needed.
+ */
+export type ConnectWebhookEventType = 'account.updated' | 'payout.created' | 'transfer.created' | 'application_fee.refunded' | 'unknown';
+/**
+ * Normalized Connect webhook event.
+ *
+ * Provider-agnostic shape so consumers don't have to import Stripe types
+ * to dispatch on event kind.
+ */
+export interface ConnectWebhookEvent {
+    /** Recognized Connect event type, or `unknown` for unrelated events. */
+    type: ConnectWebhookEventType;
+    /** Original Stripe event type string (e.g. `account.updated`). */
+    rawType: string;
+    /** The ID of the primary resource this event is about (account, payout, transfer, fee). */
+    resourceId?: string;
+    /** The connected account this event applies to, if Stripe sent one. */
+    accountId?: string;
+    /** Raw event-data object (plain JSON shape — never the live Stripe object). */
+    data: Record<string, unknown>;
+}
+/**
+ * Creates a Stripe connected account for a marketplace seller / driver / provider.
+ *
+ * @param params - Connected-account creation parameters.
+ * @returns The new account ID.
+ */
+export declare const createConnectedAccount: (params: CreateConnectedAccountParams) => Promise<CreateConnectedAccountResult>;
+/**
+ * Creates a Stripe account link the connected account holder uses to finish
+ * onboarding (or to update payout details).
+ *
+ * @param params - Account-link creation parameters.
+ * @returns The hosted onboarding/update URL and its expiry (Unix timestamp, seconds).
+ */
+export declare const createAccountLink: (params: CreateAccountLinkParams) => Promise<CreateAccountLinkResult>;
+/**
+ * Transfers funds from the platform balance to a connected account.
+ *
+ * @param params - Transfer parameters.
+ * @returns The created transfer.
+ */
+export declare const createTransfer: (params: CreateTransferParams) => Promise<CreateTransferResult>;
+/**
+ * Issues a payout from a connected account's Stripe balance to its bank account.
+ *
+ * Uses Stripe's `Stripe-Account` header to scope the call to the connected account.
+ *
+ * @param params - Payout parameters.
+ * @returns The created payout.
+ */
+export declare const createPayout: (params: CreatePayoutParams) => Promise<CreatePayoutResult>;
+/**
+ * Looks up a connected account's onboarding / payout status.
+ *
+ * @param accountId - Stripe connected account ID (`acct_...`).
+ * @returns Normalized account status.
+ */
+export declare const getAccountStatus: (accountId: string) => Promise<AccountStatus>;
+/**
+ * Verifies and normalizes a Stripe Connect webhook event.
+ *
+ * Reuses the same `STRIPE_WEBHOOK_SECRET` env var as the standard webhook
+ * pipeline (and the same signature verification logic) — Connect events
+ * arrive on the same webhook endpoint when the platform's webhook is
+ * configured to receive Connect events.
+ *
+ * @param headers - Request headers (looks up `stripe-signature`).
+ * @param body - The raw request body (string or Buffer).
+ * @returns The verified, normalized Connect webhook event.
+ */
+export declare const processConnectWebhook: (headers: Record<string, string | string[] | undefined>, body: string | Buffer) => ConnectWebhookEvent;
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"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"}

package/dist/connect.js

@@ -0,0 +1,229 @@
+/**
+ * Stripe Connect support for the Stripe payment provider.
+ *
+ * Adds split-payment / payouts helpers on top of the existing
+ * `@molecule/api-payments-stripe` bond surface so multi-vendor / two-sided
+ * marketplace apps (course-marketplace, food-delivery, multi-vendor-marketplace,
+ * rental-marketplace, tutoring-marketplace, venue-booking, crowdfunding,
+ * pet-care, telemedicine, etc.) can:
+ *   - Onboard sellers / drivers / providers (`createConnectedAccount` + `createAccountLink`).
+ *   - Move funds into connected accounts (`createTransfer`).
+ *   - Trigger payouts (`createPayout`).
+ *   - Inspect onboarding/eligibility status (`getAccountStatus`).
+ *   - Handle Connect-specific webhooks (`processConnectWebhook`).
+ *
+ * @see https://stripe.com/docs/connect
+ *
+ * @module
+ */
+import { getLogger } from '@molecule/api-bond';
+import { getClient, verifyWebhookSignature } from './provider.js';
+const logger = getLogger();
+/**
+ * Maps the in-bond business-profile shape to Stripe SDK params.
+ *
+ * @param profile - The optional business profile.
+ * @returns A Stripe-compatible business_profile object, or `undefined` if no profile was provided.
+ */
+const toStripeBusinessProfile = (profile) => {
+    if (!profile)
+        return undefined;
+    const out = {};
+    if (profile.name !== undefined)
+        out.name = profile.name;
+    if (profile.url !== undefined)
+        out.url = profile.url;
+    if (profile.productDescription !== undefined)
+        out.product_description = profile.productDescription;
+    if (profile.supportEmail !== undefined)
+        out.support_email = profile.supportEmail;
+    if (profile.supportPhone !== undefined)
+        out.support_phone = profile.supportPhone;
+    if (profile.mcc !== undefined)
+        out.mcc = profile.mcc;
+    return out;
+};
+/**
+ * Creates a Stripe connected account for a marketplace seller / driver / provider.
+ *
+ * @param params - Connected-account creation parameters.
+ * @returns The new account ID.
+ */
+export const createConnectedAccount = async (params) => {
+    try {
+        const account = await getClient().accounts.create({
+            type: params.type,
+            country: params.country,
+            email: params.email,
+            business_profile: toStripeBusinessProfile(params.businessProfile),
+            metadata: params.metadata,
+        }, params.idempotencyKey ? { idempotencyKey: params.idempotencyKey } : undefined);
+        return { id: account.id };
+    }
+    catch (error) {
+        logger.error('Error creating Stripe connected account:', error);
+        throw error;
+    }
+};
+/**
+ * Creates a Stripe account link the connected account holder uses to finish
+ * onboarding (or to update payout details).
+ *
+ * @param params - Account-link creation parameters.
+ * @returns The hosted onboarding/update URL and its expiry (Unix timestamp, seconds).
+ */
+export const createAccountLink = async (params) => {
+    try {
+        const link = await getClient().accountLinks.create({
+            account: params.accountId,
+            return_url: params.returnUrl,
+            refresh_url: params.refreshUrl,
+            type: params.type,
+        }, params.idempotencyKey ? { idempotencyKey: params.idempotencyKey } : undefined);
+        return { url: link.url, expiresAt: link.expires_at };
+    }
+    catch (error) {
+        logger.error('Error creating Stripe account link:', error);
+        throw error;
+    }
+};
+/**
+ * Transfers funds from the platform balance to a connected account.
+ *
+ * @param params - Transfer parameters.
+ * @returns The created transfer.
+ */
+export const createTransfer = async (params) => {
+    try {
+        const transfer = await getClient().transfers.create({
+            amount: params.amount,
+            currency: params.currency,
+            destination: params.destination,
+            source_transaction: params.sourceTransaction,
+            transfer_group: params.transferGroup,
+            metadata: params.metadata,
+        }, params.idempotencyKey ? { idempotencyKey: params.idempotencyKey } : undefined);
+        return {
+            id: transfer.id,
+            amount: transfer.amount,
+            currency: transfer.currency,
+            destination: typeof transfer.destination === 'string'
+                ? transfer.destination
+                : transfer.destination?.id || '',
+            transferGroup: transfer.transfer_group ?? undefined,
+        };
+    }
+    catch (error) {
+        logger.error('Error creating Stripe transfer:', error);
+        throw error;
+    }
+};
+/**
+ * Issues a payout from a connected account's Stripe balance to its bank account.
+ *
+ * Uses Stripe's `Stripe-Account` header to scope the call to the connected account.
+ *
+ * @param params - Payout parameters.
+ * @returns The created payout.
+ */
+export const createPayout = async (params) => {
+    try {
+        const requestOptions = { stripeAccount: params.accountId };
+        if (params.idempotencyKey)
+            requestOptions.idempotencyKey = params.idempotencyKey;
+        const payout = await getClient().payouts.create({
+            amount: params.amount,
+            currency: params.currency,
+            method: params.method,
+            metadata: params.metadata,
+        }, requestOptions);
+        return {
+            id: payout.id,
+            amount: payout.amount,
+            currency: payout.currency,
+            status: payout.status,
+            arrivalDate: payout.arrival_date,
+        };
+    }
+    catch (error) {
+        logger.error('Error creating Stripe payout:', error);
+        throw error;
+    }
+};
+/**
+ * Looks up a connected account's onboarding / payout status.
+ *
+ * @param accountId - Stripe connected account ID (`acct_...`).
+ * @returns Normalized account status.
+ */
+export const getAccountStatus = async (accountId) => {
+    try {
+        const account = await getClient().accounts.retrieve(accountId);
+        const currentlyDue = account.requirements?.currently_due ?? [];
+        return {
+            id: account.id,
+            chargesEnabled: account.charges_enabled === true,
+            payoutsEnabled: account.payouts_enabled === true,
+            requirementsCurrent: currentlyDue.length === 0,
+            type: account.type,
+            currentlyDue: [...currentlyDue],
+        };
+    }
+    catch (error) {
+        logger.error('Error retrieving Stripe connected account:', error);
+        throw error;
+    }
+};
+/**
+ * Maps a Stripe event type to the recognized Connect event type.
+ *
+ * @param raw - The raw Stripe event type.
+ * @returns The recognized event type, or `unknown`.
+ */
+const toConnectEventType = (raw) => {
+    switch (raw) {
+        case 'account.updated':
+        case 'payout.created':
+        case 'transfer.created':
+        case 'application_fee.refunded':
+            return raw;
+        default:
+            return 'unknown';
+    }
+};
+/**
+ * Verifies and normalizes a Stripe Connect webhook event.
+ *
+ * Reuses the same `STRIPE_WEBHOOK_SECRET` env var as the standard webhook
+ * pipeline (and the same signature verification logic) — Connect events
+ * arrive on the same webhook endpoint when the platform's webhook is
+ * configured to receive Connect events.
+ *
+ * @param headers - Request headers (looks up `stripe-signature`).
+ * @param body - The raw request body (string or Buffer).
+ * @returns The verified, normalized Connect webhook event.
+ */
+export const processConnectWebhook = (headers, body) => {
+    const sigHeader = headers['stripe-signature'];
+    const signature = Array.isArray(sigHeader) ? sigHeader[0] : sigHeader;
+    if (!signature) {
+        throw new Error('Missing stripe-signature header');
+    }
+    const verified = verifyWebhookSignature(body, signature);
+    const rawType = verified.type;
+    const data = verified.data.object;
+    const accountIdFromHeader = headers['stripe-account'];
+    const accountId = Array.isArray(accountIdFromHeader)
+        ? accountIdFromHeader[0]
+        : accountIdFromHeader;
+    const resourceId = typeof data.id === 'string' ? data.id : undefined;
+    const dataAccount = typeof data.account === 'string' ? data.account : undefined;
+    return {
+        type: toConnectEventType(rawType),
+        rawType,
+        resourceId,
+        accountId: accountId || dataAccount,
+        data,
+    };
+};
+//# sourceMappingURL=connect.js.map

package/dist/connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Stripe payment provider for molecule.dev.
+ *
+ * @see https://www.npmjs.com/package/stripe
+ *
+ * @remarks
+ * Bond this as the payments provider so `@molecule/api-payments`'s `verifySubscription` (and
+ * the payment resource) work server-side — don't call the Stripe SDK directly for
+ * verification. Env: `STRIPE_SECRET_KEY` + `STRIPE_WEBHOOK_SECRET` are SERVER-ONLY; only the
+ * publishable key (`pk_…`) is client-side.
+ *
+ * **You do NOT need molecule's Express app, the `bond()` wiring, or the UI packages to use
+ * this — the functions below are framework-agnostic.** On a non-Express / non-molecule host
+ * (Next.js App Router, serverless functions, Hono, Fastify), import them and call them from
+ * your OWN route handlers:
+ * `import { createCheckoutSession, verifyWebhookSignature, getSubscription } from '@molecule/api-payments-stripe'`.
+ * They cover the whole flow — {@link createCheckoutSession} (server-owned `priceId`, so you
+ * never take a price/amount from the client), {@link createPortalSession} (hosted Billing
+ * Portal for payment-method updates/cancellation/invoices), {@link verifyWebhookSignature},
+ * and the subscription getters/updaters — and carry the security contract (config-not-configured
+ * errors, normalized status) for free, so reach for these instead of hand-rolling raw
+ * `stripe` calls. In a Next.js App Router route, read the RAW webhook body with
+ * `await req.text()` and the header with `req.headers.get('stripe-signature')`, then
+ * `verifyWebhookSignature(rawBody, signature)` (the `express.raw(...)` note below is the
+ * Express-host equivalent). Only `@molecule/api-middleware-billing-routes` (Express glue) and
+ * `@molecule/app-billing-react` (molecule UI) are framework-coupled — skip THOSE on such a
+ * host, but still use these bond functions underneath.
+ *
+ * Two things a weak Stripe integration gets wrong:
+ *
+ * - **The webhook body MUST be RAW for signature verification.** {@link verifyWebhookSignature}
+ *   (Stripe's `constructEvent`) hashes the exact bytes, so a parsed-then-re-serialized body
+ *   ALWAYS fails. In a molecule app you need NO special middleware: the always-included
+ *   `@molecule/api-middleware-body-parser-express` already captures the unparsed body as
+ *   `req.rawBody` (a string) on EVERY request — just pass `req.rawBody` + the `stripe-signature`
+ *   header to {@link verifyWebhookSignature}. Do NOT add a route-specific `express.raw(...)` here —
+ *   it is redundant and fights the global JSON parser (which has already consumed the stream and
+ *   set `req.rawBody`). (ONLY on a NON-molecule Express host that lacks `req.rawBody` do you mount
+ *   `express.raw({ type: 'application/json' })` before the JSON parser; on Next.js App Router read
+ *   the raw body with `await req.text()`.) NEVER act on an unverified webhook body — it is
+ *   attacker-controlled.
+ * - **Webhooks are redelivered — be idempotent.** Stripe retries until it gets a 2xx, so the
+ *   same `event.id` can arrive twice. Dedupe on it (the payment record's
+ *   `UNIQUE(platformKey, transactionId)` already blocks a double-grant), and return 2xx once
+ *   handled so Stripe stops retrying.
+ *
+ * Create checkout with SERVER-configured price ids ({@link createCheckoutSession}) — never an
+ * amount sent by the client.
+ *
+ * **A missing `STRIPE_SECRET_KEY` is NOT the same as "no active subscription."**
+ * `getClient()` throws a tagged config-not-configured error; `verifySubscription`,
+ * `updateSubscription`, and `cancelSubscription` on {@link paymentProvider} detect
+ * that tag (`isConfigNotConfiguredError` from `@molecule/api-payments`) and
+ * RETHROW it instead of swallowing it into the same `null` / `{ updated: false }`
+ * / `false` a genuine verification/update failure returns — so a caller (or its
+ * own catch block) can tell "the operator forgot to set the secret" apart from
+ * "this subscription/card is invalid" and surface the actionable 503 instead of
+ * a generic 400/500.
+ *
+ * @module
+ */
+export * from './bondAdapter.js';
+export * from './browser-guard.js';
+export * from './connect.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,68 @@
+/**
+ * Stripe payment provider for molecule.dev.
+ *
+ * @see https://www.npmjs.com/package/stripe
+ *
+ * @remarks
+ * Bond this as the payments provider so `@molecule/api-payments`'s `verifySubscription` (and
+ * the payment resource) work server-side — don't call the Stripe SDK directly for
+ * verification. Env: `STRIPE_SECRET_KEY` + `STRIPE_WEBHOOK_SECRET` are SERVER-ONLY; only the
+ * publishable key (`pk_…`) is client-side.
+ *
+ * **You do NOT need molecule's Express app, the `bond()` wiring, or the UI packages to use
+ * this — the functions below are framework-agnostic.** On a non-Express / non-molecule host
+ * (Next.js App Router, serverless functions, Hono, Fastify), import them and call them from
+ * your OWN route handlers:
+ * `import { createCheckoutSession, verifyWebhookSignature, getSubscription } from '@molecule/api-payments-stripe'`.
+ * They cover the whole flow — {@link createCheckoutSession} (server-owned `priceId`, so you
+ * never take a price/amount from the client), {@link createPortalSession} (hosted Billing
+ * Portal for payment-method updates/cancellation/invoices), {@link verifyWebhookSignature},
+ * and the subscription getters/updaters — and carry the security contract (config-not-configured
+ * errors, normalized status) for free, so reach for these instead of hand-rolling raw
+ * `stripe` calls. In a Next.js App Router route, read the RAW webhook body with
+ * `await req.text()` and the header with `req.headers.get('stripe-signature')`, then
+ * `verifyWebhookSignature(rawBody, signature)` (the `express.raw(...)` note below is the
+ * Express-host equivalent). Only `@molecule/api-middleware-billing-routes` (Express glue) and
+ * `@molecule/app-billing-react` (molecule UI) are framework-coupled — skip THOSE on such a
+ * host, but still use these bond functions underneath.
+ *
+ * Two things a weak Stripe integration gets wrong:
+ *
+ * - **The webhook body MUST be RAW for signature verification.** {@link verifyWebhookSignature}
+ *   (Stripe's `constructEvent`) hashes the exact bytes, so a parsed-then-re-serialized body
+ *   ALWAYS fails. In a molecule app you need NO special middleware: the always-included
+ *   `@molecule/api-middleware-body-parser-express` already captures the unparsed body as
+ *   `req.rawBody` (a string) on EVERY request — just pass `req.rawBody` + the `stripe-signature`
+ *   header to {@link verifyWebhookSignature}. Do NOT add a route-specific `express.raw(...)` here —
+ *   it is redundant and fights the global JSON parser (which has already consumed the stream and
+ *   set `req.rawBody`). (ONLY on a NON-molecule Express host that lacks `req.rawBody` do you mount
+ *   `express.raw({ type: 'application/json' })` before the JSON parser; on Next.js App Router read
+ *   the raw body with `await req.text()`.) NEVER act on an unverified webhook body — it is
+ *   attacker-controlled.
+ * - **Webhooks are redelivered — be idempotent.** Stripe retries until it gets a 2xx, so the
+ *   same `event.id` can arrive twice. Dedupe on it (the payment record's
+ *   `UNIQUE(platformKey, transactionId)` already blocks a double-grant), and return 2xx once
+ *   handled so Stripe stops retrying.
+ *
+ * Create checkout with SERVER-configured price ids ({@link createCheckoutSession}) — never an
+ * amount sent by the client.
+ *
+ * **A missing `STRIPE_SECRET_KEY` is NOT the same as "no active subscription."**
+ * `getClient()` throws a tagged config-not-configured error; `verifySubscription`,
+ * `updateSubscription`, and `cancelSubscription` on {@link paymentProvider} detect
+ * that tag (`isConfigNotConfiguredError` from `@molecule/api-payments`) and
+ * RETHROW it instead of swallowing it into the same `null` / `{ updated: false }`
+ * / `false` a genuine verification/update failure returns — so a caller (or its
+ * own catch block) can tell "the operator forgot to set the secret" apart from
+ * "this subscription/card is invalid" and surface the actionable 503 instead of
+ * a generic 400/500.
+ *
+ * @module
+ */
+export * from './bondAdapter.js';
+export * from './browser-guard.js';
+export * from './connect.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}