@vandenberghinc/volt 1.2.4 → 1.2.6

package/backend/dist/esm/backend/src/payments/stripe/utils.d.ts

@@ -1,63 +0,0 @@
-/**
- * @author Daan van den Bergh
- * @copyright © 2026 - 2026 Daan van den Bergh. All rights reserved
- */
-import { StripeErrorCode } from "./error.js";
-/**
- * Wrap a Stripe API call to consistently attach safe context and preserve cause.
- */
-export declare function stripe_api_call<T>(fn: () => Promise<T>, context: Record<string, unknown>): Promise<T>;
-/**
- * Ensure a condition is true, otherwise throw a typed InternalStripeError.
- * Throwing internal errors not presented to the user.
- */
-export declare function assert(condition: unknown, error_code: StripeErrorCode, message: string, context?: Record<string, unknown>, cause?: unknown): asserts condition;
-/**
- * Ensure a condition is true, otherwise throw a typed ExternalStripeError.
- * Throwing external errors presented to the user.
- */
-export declare function public_assert(condition: unknown, error_code: StripeErrorCode, message: string, context?: Record<string, unknown>, cause?: unknown): asserts condition;
-/**
- * Exhaustive check helper for discriminated unions.
- * Throwing internal errors not presented to the user.
- */
-export declare function assert_never(value: never, message: string): never;
-/**
- * Exhaustive check helper for discriminated unions.
- * Throwing external errors presented to the user.
- */
-export declare function public_assert_never(value: never, message: string): never;
-/**
- * Type-guard: checks whether a value is a non-empty string.
- */
-export declare function is_non_empty_string(value: unknown): value is string;
-/**
- * Generate a random Stripe idempotency key.
- *
- * Stripe suggests using a UUID v4 as idempotency keys are best treated as opaque unique tokens.
- * Stripe docs: https://docs.stripe.com/api/idempotent_requests
- *
- * @param prefix A string prefix for observability and to avoid collisions with other idempotency domains in logs.
- *               This is still suffixed with a `_${randomUUID()}`.
- */
-export declare function generate_random_idempotency_key(prefix: string, max_length?: number): string;
-/**
- * Generate a stable idempotency key by hashing a seed string if it exceeds the max length.
- * This is useful when you want idempotency based on a natural key that may be too long for Stripe's limits.
- * The seed should be unique for each distinct operation you want to dedupe.
- */
-export declare function stable_idempotency_key(seed: string, max_length?: number): string;
-/**
- * Convert a Date into a unix timestamp (seconds).
- */
-export declare function to_unix_seconds(date: Date): number;
-/**
- * Compute the first day of the next month at 00:00:00 UTC.
- *
- * This is used for subscription billing anchors like "first_of_month".
- */
-export declare function first_day_of_next_month_utc(now: Date): Date;
-/**
- * Add N days to a date using UTC fields to avoid DST/local-time surprises.
- */
-export declare function add_days_utc(date: Date, days: number): Date;

package/backend/dist/esm/backend/src/payments/stripe/utils.js

@@ -1,131 +0,0 @@
-/**
- * @author Daan van den Bergh
- * @copyright © 2026 - 2026 Daan van den Bergh. All rights reserved
- */
-import { createHash, randomUUID } from "node:crypto";
-import { ExternalStripeError, InternalStripeError } from "./error.js";
-/**
- * Wrap a Stripe API call to consistently attach safe context and preserve cause.
- */
-export async function stripe_api_call(fn, context) {
-    try {
-        return await fn();
-    }
-    catch (error) {
-        if (error instanceof ExternalStripeError || error instanceof InternalStripeError) {
-            throw error;
-        }
-        throw new InternalStripeError("api_error", "Stripe API request failed.", context, error);
-    }
-}
-/**
- * Ensure a condition is true, otherwise throw a typed InternalStripeError.
- * Throwing internal errors not presented to the user.
- */
-export function assert(condition, error_code, message, context, cause) {
-    if (!condition) {
-        const normalized_message = message.endsWith(".") ? message : `${message}.`;
-        throw new InternalStripeError(error_code, normalized_message, context, cause);
-    }
-}
-/**
- * Ensure a condition is true, otherwise throw a typed ExternalStripeError.
- * Throwing external errors presented to the user.
- */
-export function public_assert(condition, error_code, message, context, cause) {
-    if (!condition) {
-        const normalized_message = message.endsWith(".") ? message : `${message}.`;
-        throw new ExternalStripeError(error_code, normalized_message, context, cause);
-    }
-}
-/**
- * Exhaustive check helper for discriminated unions.
- * Throwing internal errors not presented to the user.
- */
-export function assert_never(value, message) {
-    throw new InternalStripeError("invalid_argument", message, { value });
-}
-/**
- * Exhaustive check helper for discriminated unions.
- * Throwing external errors presented to the user.
- */
-export function public_assert_never(value, message) {
-    throw new ExternalStripeError("invalid_argument", message, { value });
-}
-/**
- * Type-guard: checks whether a value is a non-empty string.
- */
-export function is_non_empty_string(value) {
-    return typeof value === "string" && value.trim().length > 0;
-}
-/**
- * Generate a random Stripe idempotency key.
- *
- * Stripe suggests using a UUID v4 as idempotency keys are best treated as opaque unique tokens.
- * Stripe docs: https://docs.stripe.com/api/idempotent_requests
- *
- * @param prefix A string prefix for observability and to avoid collisions with other idempotency domains in logs.
- *               This is still suffixed with a `_${randomUUID()}`.
- */
-export function generate_random_idempotency_key(prefix, max_length = 255) {
-    if (!Number.isInteger(max_length) || max_length < 1 || max_length > 255) {
-        throw new Error(`generate_random_idempotency_key: max_length must be an integer between 1 and 255 (got ${max_length})`);
-    }
-    const p = prefix.trim();
-    if (p.length === 0) {
-        throw new Error("generate_random_idempotency_key: prefix must be non-empty");
-    }
-    const key = `${p}_${randomUUID()}`;
-    if (key.length > max_length) {
-        const digest = createHash("sha256").update(key).digest("hex");
-        return digest.slice(0, Math.min(max_length, digest.length));
-    }
-    return key;
-}
-/**
- * Generate a stable idempotency key by hashing a seed string if it exceeds the max length.
- * This is useful when you want idempotency based on a natural key that may be too long for Stripe's limits.
- * The seed should be unique for each distinct operation you want to dedupe.
- */
-export function stable_idempotency_key(seed, max_length = 255) {
-    assert(Number.isInteger(max_length) && max_length >= 1 && max_length <= 255, "invalid_argument", "Idempotency max_length must be an integer between 1 and 255.", { max_length });
-    const s = seed.trim();
-    assert(s.length > 0, "invalid_argument", "Idempotency seed must be non-empty.", {});
-    if (s.length <= max_length)
-        return s;
-    // Deterministic truncation via hash.
-    const digest = createHash("sha256").update(s).digest("hex"); // 64 chars
-    // Respect max_length even if caller sets it < 64.
-    // (Stripe max is 255, but we keep this function correct for any valid max_length.)
-    return digest.slice(0, Math.min(max_length, digest.length));
-}
-/**
- * Convert a Date into a unix timestamp (seconds).
- */
-export function to_unix_seconds(date) {
-    // Stripe APIs typically use unix timestamps in seconds.
-    return Math.floor(date.getTime() / 1000);
-}
-/**
- * Compute the first day of the next month at 00:00:00 UTC.
- *
- * This is used for subscription billing anchors like "first_of_month".
- */
-export function first_day_of_next_month_utc(now) {
-    const year = now.getUTCFullYear();
-    const month = now.getUTCMonth();
-    // Move to the first day of the next month in UTC.
-    // Date constructor with UTC fields avoids local timezone surprises.
-    return new Date(Date.UTC(year, month + 1, 1, 0, 0, 0, 0));
-}
-/**
- * Add N days to a date using UTC fields to avoid DST/local-time surprises.
- */
-export function add_days_utc(date, days) {
-    // Defensive validation: caller-side bugs should never cause silent time drift.
-    assert(Number.isInteger(days), "invalid_argument", "Days must be an integer.", { days });
-    const year = date.getUTCFullYear();
-    const month = date.getUTCMonth();
-    const day = date.getUTCDate();
-    return new Date(Date.UTC(year, month, day + days, date.getUTCHours(), date.getUTCMinutes(), date.getUTCSeconds(), date.getUTCMilliseconds()));
-}

package/backend/dist/esm/backend/src/payments/stripe/webhooks.d.ts

@@ -1,105 +0,0 @@
-/**
- * @author Daan van den Bergh
- * @copyright © 2026 - 2026 Daan van den Bergh. All rights reserved
- *
- * Stripe webhook entrypoint:
- * - Verifies webhook signatures (security-critical).
- * - Handles lifecycle events emitted by our billing flows (Checkout, Subscriptions, Invoices, SetupIntents, PaymentIntents).
- * - Invalidates local entitlement caches after Stripe-side mutations.
- * - Triggers server events for application-level reactions.
- *
- * Stripe docs:
- * - Webhooks: https://docs.stripe.com/webhooks
- * - Verify signatures: https://docs.stripe.com/webhooks/signatures
- */
-import Stripe from "stripe";
-import { Server } from "../../server.js";
-import { Stream } from "../../stream.js";
-import type { InitializedMeterProduct, InitializedProduct, InitializedSubscriptionPlan, InitializedSubscriptionProduct } from "./products.js";
-/**
- * A resolved subscription item mapping that we expose to event consumers.
- */
-export type StripeResolvedSubscriptionItem = {
-    /** The Stripe price id on the subscription item. */
-    stripe_price_id: string;
-} | {
-    /** The Stripe price id on the subscription item. */
-    stripe_price_id: string;
-    /** The resolved subscription product (when price maps to a known plan). */
-    product: InitializedSubscriptionProduct;
-    /** The resolved subscription plan (licensed) when applicable. */
-    plan: InitializedSubscriptionPlan;
-} | {
-    /** The Stripe price id on the subscription item. */
-    stripe_price_id: string;
-    /** The resolved subscription product (when price maps to a known plan). */
-    product: InitializedMeterProduct;
-};
-/**
- * Register or update the Stripe Webhook Endpoint for our billing system.
- *
- * - Creates a webhook endpoint if it does not exist.
- * - Ensures all required billing events are enabled.
- * - Persists endpoint id + signing secret in our DB for later signature verification config.
- *
- * Stripe docs:
- * - Create: https://docs.stripe.com/api/webhook_endpoints/create
- * - Update: https://docs.stripe.com/api/webhook_endpoints/update
- */
-export declare function register_or_update_stripe_webhook_endpoint(client: Stripe, server: Server, opts: {
-    /** An internal identifier for the webhook endpoint, stored in the webhook's metadata. */
-    webhook_app_id: string;
-    /** The public HTTPS URL Stripe should POST webhooks to. */
-    webhook_url: string;
-    /**
-     * A human-readable description shown in Stripe Dashboard.
-     * Keep it non-sensitive (no secrets).
-     */
-    description?: string;
-    /**
-     * Whether to force-enable the endpoint if it is disabled in Stripe.
-     * Defaults to true.
-     */
-    ensure_enabled?: boolean;
-}): Promise<{
-    /** The Stripe Webhook Endpoint id (we_...). */
-    stripe_webhook_endpoint_id: string;
-    /** The webhook signing secret used to verify signatures (whsec_...). */
-    webhook_signing_secret: string;
-    /** The enabled event types we configured on the endpoint. */
-    enabled_events: Stripe.WebhookEndpointUpdateParams.EnabledEvent[];
-}>;
-/**
- * Handle a Stripe webhook call:
- * - verifies signature
- * - deduplicates event ids briefly
- * - routes event types to handlers
- * - emits application events via `server.events.trigger`
- *
- * Sending a response through the stream automatically.
- *
- * @note This function expects the caller to provide the raw body and Stripe-Signature header.
- */
-export declare function handle_stripe_webhook(client: Stripe, opts: {
-    /** The running server instance (used for event emission). */
-    server: Server;
-    /** The current request stream. */
-    stream: Stream;
-    /** The Stripe webhook signing secret for this endpoint. */
-    webhook_signing_secret: string;
-    /**
-     * The raw request body (unparsed) as received from Stripe.
-     * Security: signature verification requires the exact raw bytes.
-     */
-    raw_body: Buffer;
-    /**
-     * The `Stripe-Signature` request header.
-     * Docs: https://docs.stripe.com/webhooks/signatures#verify-signatures
-     */
-    stripe_signature_header: string;
-    /**
-     * The initialized products list (for mapping price ids back to user-exposed products/plans).
-     * Pass the same list you use in checkout/subscriptions logic.
-     */
-    all_products: InitializedProduct[];
-}): Promise<void>;