@vandenberghinc/volt 1.2.5 → 1.2.6

package/frontend/dist/backend/src/payments/stripe/customers.js

@@ -1,193 +0,0 @@
-/**
- * @author Daan van den Bergh
- * @copyright © 2026 - 2026 Daan van den Bergh. All rights reserved
- */
-import * as vlib from "@vandenberghinc/vlib";
-import { InternalStripeError } from "./error.js";
-import { stable_idempotency_key, stripe_api_call } from "./utils.js";
-import { Collection } from "../../database/collection.js";
-/**
- * A cache for resolving Stripe customer ids from our internal user IDs (`uid`).
- */
-const stripe_customer_cache = new vlib.Cache({
-    max_size: 100_000,
-    ttl: {
-        sliding: false,
-        duration: 60 * 60 * 1000, // 1 hour
-    },
-});
-/** The Stripe customer metadata key we use to link Stripe customers to our internal users. */
-const stripe_customer_uid_metadata_key = "__volt_uid";
-/**
- * Escape a value for safe usage inside a Stripe Search query string.
- * @see https://docs.stripe.com/search#search-query-language
- */
-function escape_stripe_search_value(value) {
-    // Stripe search values are typically embedded in single quotes; escape backslashes and single quotes defensively.
-    // This prevents query breaking and reduces risk of accidental query injection from unexpected uid formats.
-    return value
-        .replaceAll("\\", "\\\\")
-        .replaceAll("'", "\\'");
-}
-/**
- * Assert that a `uid` is valid for use in Stripe customer mapping.
- */
-function assert_uid(uid) {
-    if (typeof uid !== "string" || uid.length < 16 || uid.length > 128) {
-        throw new InternalStripeError("invalid_uid", "Invalid uid for Stripe customer mapping.", { uid_length: typeof uid === "string" ? uid.length : null });
-    }
-    // Fail closed on control characters instead of normalizing (normalizing can change identity).
-    if (/[\u0000-\u001F\u007F]/.test(uid)) {
-        throw new InternalStripeError("invalid_uid", "uid contains control characters.", {});
-    }
-}
-/**
- * Create the stripe customer session database collection.
- */
-function create_customer_db(server) {
-    // Initialize the database connection.
-    return server.db.collection({
-        name: "Volt.Stripe.Customers",
-        indexes: [
-            {
-                keys: { customer_id: 1 },
-                unique: true,
-            },
-            {
-                keys: { uid: 1 },
-                unique: true,
-            },
-        ],
-        // Ensure its not unique so we retrieve the cached collection if already created.
-        unique: false,
-    });
-}
-/**
- * Find an existing Stripe customer id for the given `uid` using Stripe's Search API.
- * Returns `null` when no customer is found.
- * @see https://docs.stripe.com/api/customers/search
- */
-async function find_stripe_customer_id(client, uid) {
-    assert_uid(uid);
-    // Search by metadata so we never rely on PII like email for identity mapping.
-    // Docs: https://docs.stripe.com/api/customers/search
-    const escaped_uid = escape_stripe_search_value(uid);
-    const query = `metadata['${stripe_customer_uid_metadata_key}']:'${escaped_uid}'`;
-    const search_result = await stripe_api_call(() => client.customers.search({
-        query,
-        limit: 1,
-    }), { uid, query });
-    const customer = search_result.data[0];
-    if (!customer) {
-        return null;
-    }
-    return customer.id;
-}
-// ----------------------------------------------------------------------------
-// Public API.
-/**
- * Ensure a Stripe customer exists for the given `uid`.
- * @returns The Stripe customer ID. If a customer already exists for the `uid`, it is returned. Otherwise, a new customer is created and its ID is returned.
- */
-export async function ensure_stripe_customer(client, server, uid) {
-    assert_uid(uid);
-    // Check cache first.
-    const cached_customer_id = stripe_customer_cache.get(uid);
-    if (cached_customer_id) {
-        return cached_customer_id;
-    }
-    // Create collection.
-    const db = create_customer_db(server);
-    // The fetched customer id.
-    let customer_id;
-    // Attempt to load from database.
-    const record = await db.load({ uid }, {
-        throw: false,
-        projection: { customer_id: 1 },
-        retry: 3,
-    });
-    // Found.
-    if (!(record instanceof Error)) {
-        customer_id = record.customer_id;
-    }
-    // Not found.
-    else if (record instanceof Collection.NotFoundError) {
-        // Attempt to find an existing customer by metadata (idempotent across services/processes).
-        const existing_customer_id = await find_stripe_customer_id(client, uid);
-        if (existing_customer_id) {
-            customer_id = existing_customer_id;
-        }
-        // If none exists, create a new customer and store uid in metadata for future lookups.
-        else {
-            const created_customer = await stripe_api_call(() => client.customers.create({
-                metadata: {
-                    [stripe_customer_uid_metadata_key]: uid,
-                },
-            }, {
-                // Prevent duplicates across concurrent calls / processes.
-                idempotencyKey: stable_idempotency_key(`customer_create_uid:${uid}`),
-            }), { uid, metadata_key: stripe_customer_uid_metadata_key });
-            customer_id = created_customer.id;
-        }
-        // Persist to database.
-        await db.set({ uid }, { customer_id }, {
-            upsert: true,
-            retry: 3,
-        });
-        // Load again in case we concurrently created the same customer in another process (should not error due to upsert, but ensures we have the correct customer_id).
-        const final_record = await db.load({ uid }, {
-            throw: false,
-            projection: { customer_id: 1 },
-            retry: 3,
-        });
-        if (final_record instanceof Error) {
-            throw new InternalStripeError("customer_not_found", "Failed to load Stripe customer from database after creation.", { uid, cause: final_record });
-        }
-        customer_id = final_record.customer_id;
-    }
-    // Error.
-    else {
-        throw new InternalStripeError("customer_not_found", "Failed to load Stripe customer from database.", { uid, cause: record });
-    }
-    // Save to cache.
-    stripe_customer_cache.set(uid, customer_id);
-    return customer_id;
-}
-/**
- * Delete a Stripe customer by their `uid`.
- * This operation is best-effort and idempotent: if no Stripe customer exists for the `uid`, it returns without error.
- * @see https://docs.stripe.com/api/customers/delete
- */
-export async function delete_stripe_customer(client, server, uid) {
-    assert_uid(uid);
-    // Clear cache after resolving to prevent stale ids being served.
-    stripe_customer_cache.delete(uid);
-    // Create collection.
-    const db = create_customer_db(server);
-    // Load from database.
-    const record = await db.load({ uid }, {
-        throw: false,
-        projection: { customer_id: 1 },
-    });
-    // Not found, consider delete successful (idempotent semantics).
-    if (record instanceof Collection.NotFoundError) {
-        return;
-    }
-    // Error.
-    else if (record instanceof Error) {
-        throw new InternalStripeError("customer_not_found", "Failed to load Stripe customer from database.", { uid, cause: record });
-    }
-    // If no customer exists, consider the delete successful (idempotent semantics).
-    if (!record.customer_id) {
-        return;
-    }
-    // Delete customer in Stripe.
-    // Docs: https://docs.stripe.com/api/customers/delete
-    const deleted_customer = await stripe_api_call(() => client.customers.del(record.customer_id), { uid, customer_id: record.customer_id });
-    // Stripe returns a DeletedCustomer object with `deleted: true` on success.
-    if (deleted_customer.deleted !== true) {
-        throw new InternalStripeError("customer_delete_error", "Stripe customer delete did not return a deleted confirmation.", { uid, customer_id: record.customer_id });
-    }
-    // Remove from database.
-    await db.delete({ uid });
-}

package/frontend/dist/backend/src/payments/stripe/error.d.ts

@@ -1,74 +0,0 @@
-/**
- * @author Daan van den Bergh
- * @copyright © 2026 - 2026 Daan van den Bergh. All rights reserved
- */
-import { ExternalError, InternalError } from "../../errors/internal_external.js";
-/** The available stripe error code. */
-export type StripeErrorCode = (
-/** An error code indicating an invalid uid for Stripe customer mapping. */
-"invalid_uid"
-/** An error code indicating a failure to delete a Stripe customer. */
- | "customer_delete_error"
-/** An error code indicating a Stripe customer was not found. */
- | "customer_not_found"
-/** Invalid argument error code. */
- | "invalid_argument"
-/** Error code for an invalid product. */
- | "invalid_product"
-/** An error code indicating a generic Stripe API failure. */
- | "api_error"
-/** An error code indicating a failure during checkout session creation. */
- | "checkout_create_error"
-/** An error code indicating an invalid product reference during checkout session creation. */
- | "checkout_invalid_product_ref"
-/** An error code indicating a mixed currency error during checkout session creation. */
- | "checkout_mixed_currency"
-/** An error code indicating an ambiguous subscription plan reference during checkout session creation. */
- | "checkout_subscription_plan_ambiguous"
-/** An error code indicating an invalid quantity during checkout session creation. */
- | "checkout_invalid_quantity"
-/** An error code indicating the user is already subscribed to the plan. */
- | "checkout_already_subscribed"
-/** An error code indicating a subscription is not active and can not be billed. */
- | "subscription_not_active"
-/** An error code indicating a failure during subscription creation. */
- | "subscription_create_error"
-/** An error code indicating a subscription payment action is required. */
- | "subscription_payment_action_required"
-/** An error code indicating a missing payment method. */
- | "payment_method_missing"
-/** An error code indicating a subscription resolution error */
- | "subscription_resolution_error"
-/** An error code indicating a missing webhook endpoint secret. */
- | "webhook_endpoint_secret_missing"
-/** An error code indicating a failure to load webhook endpoint configuration. */
- | "webhook_endpoint_load_error"
-/** An error code indicating a mismatch between the webhook event's app id and the expected app id. */
- | "webhook_endpoint_app_id_mismatch");
-/**
- * Custom error class to attach safe context while preserving the original cause.
- * Internal errors thrown in REST API calls will be presented to the user as
- * a generic internal server errog. Therefore the code, message and context
- * are never shown to the user.
- */
-export declare class InternalStripeError extends InternalError {
-    /** Stable error code for programmatic handling (never include secrets). */
-    readonly error_code: StripeErrorCode;
-    /** Optional safe context for debugging (never include secrets). */
-    readonly context?: Record<string, unknown>;
-    /** Constructs a StripeWrapperError. */
-    constructor(code: StripeErrorCode, message: string, context?: Record<string, unknown>, cause?: unknown);
-}
-/**
- * Custom error class to attach safe context while preserving the original cause.
- * External errors thrown in REST API calls will be presented to the user with the message and code,
- * but context is never shown to the user.
- */
-export declare class ExternalStripeError extends ExternalError {
-    /** Stable error code for programmatic handling (never include secrets). */
-    readonly error_code: StripeErrorCode;
-    /** Optional safe context for debugging (never include secrets). */
-    readonly context?: Record<string, unknown>;
-    /** Constructs a StripeWrapperError. */
-    constructor(code: StripeErrorCode, message: string, context?: Record<string, unknown>, cause?: unknown);
-}

package/frontend/dist/backend/src/payments/stripe/error.js

@@ -1,51 +0,0 @@
-/**
- * @author Daan van den Bergh
- * @copyright © 2026 - 2026 Daan van den Bergh. All rights reserved
- */
-import { ExternalError, InternalError } from "../../errors/internal_external.js";
-/**
- * Custom error class to attach safe context while preserving the original cause.
- * Internal errors thrown in REST API calls will be presented to the user as
- * a generic internal server errog. Therefore the code, message and context
- * are never shown to the user.
- */
-export class InternalStripeError extends InternalError {
-    /** Stable error code for programmatic handling (never include secrets). */
-    error_code;
-    /** Optional safe context for debugging (never include secrets). */
-    context;
-    /** Constructs a StripeWrapperError. */
-    constructor(code, message, context, cause) {
-        super({
-            message,
-            type: code,
-            cause,
-        });
-        this.name = "StripeError";
-        this.error_code = code;
-        this.context = context;
-        this.cause = cause;
-    }
-}
-/**
- * Custom error class to attach safe context while preserving the original cause.
- * External errors thrown in REST API calls will be presented to the user with the message and code,
- * but context is never shown to the user.
- */
-export class ExternalStripeError extends ExternalError {
-    /** Stable error code for programmatic handling (never include secrets). */
-    error_code;
-    /** Optional safe context for debugging (never include secrets). */
-    context;
-    /** Constructs a StripeWrapperError. */
-    constructor(code, message, context, cause) {
-        super({
-            message,
-            type: code,
-            cause,
-        });
-        this.name = "StripeError";
-        this.error_code = code;
-        this.context = context;
-    }
-}

package/frontend/dist/backend/src/payments/stripe/events.d.ts

@@ -1,155 +0,0 @@
-/**
- * @author Daan van den Bergh
- * @copyright © 2026 - 2026 Daan van den Bergh. All rights reserved
- */
-import Stripe from "stripe";
-import { StripeResolvedSubscriptionItem } from "./webhooks.js";
-/**
- * Stripe webhook-driven events emitted by this module.
- *
- * These event names are intentionally explicit and stable.
- * Consumers can subscribe via `server.on("<event-type>", cb)` if your Server supports it,
- * or you can route them via `server.events.trigger("<event-type>", args)` as done below.
- */
-export type StripeEvents = {
-    /**
-     * Fired when a Stripe Checkout Session is completed.
-     *
-     * Docs: https://docs.stripe.com/api/events/types#event_types-checkout.session.completed
-     *
-     * @note The defined events are executed in parallel and are awaited inside the webhook handler.
-     */
-    "stripe.checkout_session_completed": (opts: {
-        /** The internal user id resolved from metadata. */
-        uid: string;
-        /** Stripe checkout session id. */
-        stripe_session_id: string;
-        /** Stripe checkout mode. */
-        mode: "payment" | "subscription" | "setup";
-        /** Stripe customer id. */
-        stripe_customer_id: string;
-        /** Stripe subscription id (only for mode="subscription"). */
-        stripe_subscription_id?: string;
-        /** Currency if available on the session. */
-        currency?: string;
-        /** Session metadata (safe). */
-        metadata: Stripe.Metadata;
-    }) => void | Promise<void>;
-    /**
-     * Fired when a Stripe subscription is created.
-     * Docs: https://docs.stripe.com/api/events/types#event_types-customer.subscription.created
-     *
-     * @note The defined events are executed in parallel and are awaited inside the webhook handler.
-     */
-    "stripe.subscription_created": (opts: {
-        /** The internal user id. */
-        uid: string;
-        /** Stripe subscription id. */
-        stripe_subscription_id: string;
-        /** Stripe customer id. */
-        stripe_customer_id: string;
-        /** Stripe subscription status. */
-        status: Stripe.Subscription.Status;
-        /**
-         * Matched subscription items (price -> plan/product mapping when resolvable).
-         * This can contain multiple items if the subscription has multiple prices.
-         */
-        items: StripeResolvedSubscriptionItem[];
-    }) => void | Promise<void>;
-    /**
-     * Fired when a Stripe subscription is updated.
-     * Docs: https://docs.stripe.com/api/events/types#event_types-customer.subscription.updated
-     *
-     * @note The defined events are executed in parallel and are awaited inside the webhook handler.
-     */
-    "stripe.subscription_updated": (opts: {
-        uid: string;
-        stripe_subscription_id: string;
-        stripe_customer_id: string;
-        status: Stripe.Subscription.Status;
-        items: StripeResolvedSubscriptionItem[];
-        cancel_at_period_end?: boolean;
-    }) => void | Promise<void>;
-    /**
-     * Fired when a Stripe subscription is deleted/canceled.
-     * Docs: https://docs.stripe.com/api/events/types#event_types-customer.subscription.deleted
-     *
-     * @note The defined events are executed in parallel and are awaited inside the webhook handler.
-     */
-    "stripe.subscription_deleted": (opts: {
-        uid: string;
-        stripe_subscription_id: string;
-        stripe_customer_id: string;
-        status: Stripe.Subscription.Status;
-        items: StripeResolvedSubscriptionItem[];
-    }) => void | Promise<void>;
-    /**
-     * Fired when an invoice is paid successfully.
-     * Docs: https://docs.stripe.com/api/events/types#event_types-invoice.paid
-     *
-     * @note The defined events are executed in parallel and are awaited inside the webhook handler.
-     */
-    "stripe.invoice_paid": (opts: {
-        uid: string;
-        stripe_invoice_id: string;
-        stripe_customer_id: string;
-        amount_paid: number;
-        currency: string;
-        hosted_invoice_url?: string;
-    }) => void | Promise<void>;
-    /**
-     * Fired when an invoice payment fails.
-     * Docs: https://docs.stripe.com/api/events/types#event_types-invoice.payment_failed
-     *
-     * @note The defined events are executed in parallel and are awaited inside the webhook handler.
-     */
-    "stripe.invoice_payment_failed": (opts: {
-        uid: string;
-        stripe_invoice_id: string;
-        stripe_customer_id: string;
-        amount_due: number;
-        currency: string;
-        hosted_invoice_url?: string;
-    }) => void | Promise<void>;
-    /**
-     * Fired when a PaymentIntent succeeds (covers one-time and some subscription flows).
-     * Docs: https://docs.stripe.com/api/events/types#event_types-payment_intent.succeeded
-     *
-     * @note The defined events are executed in parallel and are awaited inside the webhook handler.
-     */
-    "stripe.payment_succeeded": (opts: {
-        uid: string;
-        stripe_payment_intent_id: string;
-        stripe_customer_id?: string;
-        amount_received: number;
-        currency: string;
-        metadata: Stripe.Metadata;
-    }) => void | Promise<void>;
-    /**
-     * Fired when a PaymentIntent fails.
-     * Docs: https://docs.stripe.com/api/events/types#event_types-payment_intent.payment_failed
-     *
-     * @note The defined events are executed in parallel and are awaited inside the webhook handler.
-     */
-    "stripe.payment_failed": (opts: {
-        uid: string;
-        stripe_payment_intent_id: string;
-        stripe_customer_id?: string;
-        amount: number;
-        currency: string;
-        last_payment_error_message?: string;
-        metadata: Stripe.Metadata;
-    }) => void | Promise<void>;
-    /**
-     * Fired when a SetupIntent succeeds and we (best-effort) set the default payment method.
-     * Docs: https://docs.stripe.com/api/events/types#event_types-setup_intent.succeeded
-     *
-     * @note The defined events are executed in parallel and are awaited inside the webhook handler.
-     */
-    "stripe.payment_method_ready": (opts: {
-        uid: string;
-        stripe_customer_id: string;
-        stripe_setup_intent_id: string;
-        stripe_payment_method_id: string;
-    }) => void | Promise<void>;
-};

package/frontend/dist/backend/src/payments/stripe/events.js

@@ -1,5 +0,0 @@
-/**
- * @author Daan van den Bergh
- * @copyright © 2026 - 2026 Daan van den Bergh. All rights reserved
- */
-export {};

package/frontend/dist/backend/src/payments/stripe/meters.d.ts

@@ -1,105 +0,0 @@
-/**
- * @author Daan van den Bergh
- * @copyright © 2026 - 2026 Daan van den Bergh. All rights reserved
- */
-import Stripe from "stripe";
-import { InitializedMeterProduct, InitializedProduct, MeterProduct } from "./products.js";
-import { Server } from "../../server.js";
-type AmountRounding = "exact" | "floor" | "ceil" | "round";
-/**
- * The options for recording meter usage.
- */
-export type RecordMeterUsageOpts<Kind extends MeterProduct.Kind> = {
-    /** The internal user id (uid) whose usage should be recorded. */
-    uid: string;
-    /** The initialized meter product to record usage for. */
-    product: InitializedMeterProduct<Kind extends "units" ? MeterProduct.UnitsMeter : Kind extends "money" ? MeterProduct.MoneyMeter : never>;
-    /**
-     * Optional event timestamp.
-     * Must be within the past 35 calendar days or up to 5 minutes in the future.
-     * @see https://docs.stripe.com/api/billing/meter-event/create
-     */
-    timestamp?: Date;
-    /**
-     * Event identifier to deduplicate accidental retries.
-     * Stripe enforces uniqueness within a rolling >=24h window.
-     * Must be non-empty, max 100 chars, and contain only letters, numbers, dots, underscores or hyphens.
-     * @see https://docs.stripe.com/api/billing/meter-event/create
-     */
-    identifier: string;
-} & (Kind extends "units" ? {
-    /**
-     * The numeric usage value to record (integer).
-     * For "sum"/"last" meters this is the numeric value.
-     * For "count" meters this can be 1 per event (but we still send a value).
-     */
-    value: number;
-} : Kind extends "money" ? {
-    /**
-     * Money amount in major units (e.g., "0.007463" USD), used only when product.kind === "money".
-     * Can be string or number (number is normalized to string).
-     */
-    amount: string | number;
-    /**
-     * Rounding mode used when converting amount to internal integer units.
-     * @default "exact"
-     * @warning When round is `exact`, amounts with more precision than supported will be rejected by a thrown error, to prevent silent rounding bugs. Use an explicit rounding mode to allow lossy conversions.
-     */
-    round?: AmountRounding;
-} : never);
-/**
- * The result of recording meter usage.
- */
-export interface RecordMeterUsageResult {
-    /** The Stripe billing meter event id. */
-    meter_event_identifier: string;
-    /** The meter event name used. */
-    event_name: string;
-    /** The unix timestamp (seconds) used for the event, if provided. */
-    timestamp: number;
-}
-/**
- * Record usage for a metered subscription by creating a Stripe Billing Meter Event.
- *
- * Security & correctness guarantees:
- * - Requires that the user has an active-ish subscription containing the meter product's price id.
- * - Uses the meter's configured payload keys for customer/value mapping.
- * - Allows caller-provided `identifier` to dedupe retries.
- *
- * Stripe docs:
- * - Create meter event: https://docs.stripe.com/api/billing/meter-event/create
- * - Record usage guide: https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage-api
- *
- * @throws {InternalStripeError} When round mode is `exact` and the amount has more precision than supported.
- * @throws {InternalStripeError} On internal errors.
- * @throws {ExternalStripeError} On external errors such as the customer not being entitled to record usage for the meter product.
- */
-export declare function record_meter_usage<Kind extends MeterProduct.Kind>(client: Stripe, server: Server, all_products: InitializedProduct[], opts: RecordMeterUsageOpts<Kind>): Promise<RecordMeterUsageResult>;
-/** The options for {@link cancel_meter_usage_event} */
-export interface CancelMeterUsageEventOpts {
-    /** The user id. */
-    uid: string;
-    /** The meter product whose event stream the event belongs to. */
-    product: InitializedMeterProduct;
-    /** The identifier of the meter event to cancel. */
-    meter_event_identifier: string;
-}
-/** The result type of {@link cancel_meter_usage_event} */
-export interface CancelMeterUsageEventResult {
-    /** The identifier of the canceled meter event. */
-    meter_event_identifier: string;
-    /** The status of the adjustment created to cancel the event. Typically "pending". */
-    status: string;
-}
-/**
- * Cancel a previously recorded meter event by identifier (best-effort within 24 hours).
- *
- * This is useful for:
- * - reverting accidental double-reporting
- * - compensating failed internal workflows
- *
- * Stripe docs:
- * - Create meter event adjustment: https://docs.stripe.com/api/billing/meter-event-adjustment/create
- */
-export declare function cancel_meter_usage_event(client: Stripe, server: Server, all_products: InitializedProduct[], opts: CancelMeterUsageEventOpts): Promise<CancelMeterUsageEventResult>;
-export {};