@vandenberghinc/volt 1.2.4 → 1.2.6

package/backend/dist/cjs/backend/src/payments/stripe/payment_methods.js

@@ -1,109 +0,0 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var stdin_exports = {};
-__export(stdin_exports, {
-  create_payment_method_setup_intent: () => create_payment_method_setup_intent,
-  finalize_payment_method_setup: () => finalize_payment_method_setup
-});
-module.exports = __toCommonJS(stdin_exports);
-var import_customers = require("./customers.js");
-var import_error = require("./error.js");
-var import_utils = require("./utils.js");
-function resolve_payment_method_id_from_setup_intent(setup_intent) {
-  const payment_method = setup_intent.payment_method;
-  if (!payment_method) {
-    throw new import_error.ExternalStripeError("payment_method_missing", "No payment method was provided. Please try again.", { setup_intent_id: setup_intent.id, status: setup_intent.status });
-  }
-  if (typeof payment_method === "string") {
-    return payment_method;
-  }
-  const id = payment_method.id;
-  if (!(0, import_utils.is_non_empty_string)(id)) {
-    throw new import_error.ExternalStripeError("payment_method_missing", "No payment method was provided. Please try again.", { setup_intent_id: setup_intent.id, status: setup_intent.status });
-  }
-  return id;
-}
-function assert_setup_intent_belongs_to_customer(opts) {
-  const { setup_intent, expected_customer_id, uid } = opts;
-  const setup_intent_customer = setup_intent.customer;
-  (0, import_utils.public_assert)(setup_intent_customer !== null, "invalid_argument", "Setup intent is missing a customer association.", { uid, setup_intent_id: setup_intent.id });
-  const setup_customer_id = typeof setup_intent_customer === "string" ? setup_intent_customer : setup_intent_customer.id;
-  (0, import_utils.public_assert)(setup_customer_id === expected_customer_id, "invalid_argument", "Setup intent does not belong to this customer.", { uid, setup_intent_id: setup_intent.id, expected_customer_id, setup_customer_id });
-}
-async function create_payment_method_setup_intent(client, server, opts) {
-  (0, import_utils.public_assert)((0, import_utils.is_non_empty_string)(opts.uid), "invalid_argument", "Property 'uid' must be a non-empty string.");
-  const stripe_customer_id = await (0, import_customers.ensure_stripe_customer)(client, server, opts.uid);
-  let setup_intent;
-  try {
-    setup_intent = await (0, import_utils.stripe_api_call)(() => client.setupIntents.create({
-      customer: stripe_customer_id,
-      // off_session indicates we plan to charge when the customer is not actively in-session.
-      usage: "off_session"
-    }, {
-      idempotencyKey: opts.idempotency_key
-    }), { operation: "setupIntents.create", uid: opts.uid, stripe_customer_id });
-  } catch (error) {
-    throw new import_error.InternalStripeError("api_error", "Failed to create a payment method setup intent.", { uid: opts.uid, stripe_customer_id }, error);
-  }
-  const client_secret = setup_intent.client_secret;
-  (0, import_utils.assert)((0, import_utils.is_non_empty_string)(client_secret), "api_error", "Stripe did not return a SetupIntent client_secret.", { uid: opts.uid, stripe_customer_id, setup_intent_id: setup_intent.id });
-  return {
-    id: setup_intent.id,
-    client_secret,
-    stripe_customer_id
-  };
-}
-async function finalize_payment_method_setup(client, server, opts) {
-  (0, import_utils.public_assert)((0, import_utils.is_non_empty_string)(opts.uid), "invalid_argument", "Property 'uid' must be a non-empty string.");
-  (0, import_utils.public_assert)((0, import_utils.is_non_empty_string)(opts.setup_intent_id), "invalid_argument", "Property 'setup_intent_id' must be a non-empty string.");
-  const stripe_customer_id = await (0, import_customers.ensure_stripe_customer)(client, server, opts.uid);
-  const setup_intent = await (0, import_utils.stripe_api_call)(() => client.setupIntents.retrieve(opts.setup_intent_id, {
-    expand: ["payment_method"]
-  }), { operation: "setupIntents.retrieve", uid: opts.uid, setup_intent_id: opts.setup_intent_id });
-  assert_setup_intent_belongs_to_customer({
-    setup_intent,
-    expected_customer_id: stripe_customer_id,
-    uid: opts.uid
-  });
-  (0, import_utils.public_assert)(setup_intent.status === "succeeded", "invalid_argument", "Payment method setup is not complete. Please finish adding your payment method.", { uid: opts.uid, setup_intent_id: setup_intent.id, status: setup_intent.status });
-  const payment_method_id = resolve_payment_method_id_from_setup_intent(setup_intent);
-  await (0, import_utils.stripe_api_call)(() => client.customers.update(stripe_customer_id, {
-    invoice_settings: {
-      default_payment_method: payment_method_id
-    }
-  }, {
-    idempotencyKey: opts.idempotency_key ?? (0, import_utils.stable_idempotency_key)(`finalize_payment_method_setup:${opts.uid}:${setup_intent.id}`)
-  }), {
-    operation: "customers.update",
-    uid: opts.uid,
-    stripe_customer_id,
-    setup_intent_id: setup_intent.id,
-    payment_method_id,
-    action: "set_default_payment_method"
-  });
-  return {
-    stripe_customer_id,
-    payment_method_id,
-    setup_intent_id: setup_intent.id
-  };
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  create_payment_method_setup_intent,
-  finalize_payment_method_setup
-});

package/backend/dist/cjs/backend/src/payments/stripe/products.d.ts

@@ -1,519 +0,0 @@
-/**
- * @author Daan van den Bergh
- * @copyright © 2026 - 2026 Daan van den Bergh. All rights reserved
- */
-import Stripe from "stripe";
-import { Server } from "../../server.js";
-/**
- * The recurring billing interval for subscription products.
- */
-export type RecurringInterval = "day" | "week" | "month" | "year";
-/**
- * The tax behaviour for a product or price.
- */
-export type TaxBehavior = "inclusive" | "exclusive" | "unspecified";
-/**
- * An internal product id, simple type alias for clarity.
- *
- * @docs
- */
-export type ProductId = string;
-/**
- * An internal subscription plan id, simple type alias for clarity.
- *
- * @docs
- */
-export type SubscriptionPlanId = string;
-/**
- * The base product interface.
- */
-interface BaseProduct {
-    /**
-     * A unique product identifier.
-     * This identifier should not be changed once set, as it is used to link the product to existing Stripe products and prices.
-     * This identifier should be unique accross all products and subscription plans.
-     */
-    id: ProductId;
-    /** The name of the product, meant to be displayable to the user. */
-    name: string;
-    /** The description of the product. */
-    description: string;
-    /** The three-letter ISO currency code (e.g., "usd", "eur"). */
-    currency: string;
-    /**
-     * A tax code for this product.
-     * See https://docs.stripe.com/tax/tax-codes for more details and to find the right tax code for your product.
-     */
-    tax_code: string;
-    /** The tax behaviour. */
-    tax_behavior: TaxBehavior;
-    /** Optional product images (public URLs). */
-    images?: string[];
-}
-/**
- * The one-time payment product interface.
- * @warning
- * A product is a public type and is accessible in the frontend,
- * through the default Volt Rest API.
- * @docs
- */
-export interface OneTimePaymentProduct extends BaseProduct {
-    /** The product type. */
-    type: "one_time";
-    /** The price for this product in cents. */
-    price: number;
-    /** Quantity limits for one-time purchases. */
-    quantity_rules?: {
-        /** Minimum quantity allowed. */
-        min?: number;
-        /** Maximum quantity allowed. */
-        max?: number;
-    };
-}
-/**
- * A subscription plan.
- *
- * @warning
- * A subscription plan is a public type and is accessible in the frontend,
- * through the default Volt Rest API.
- *
- * @docs
- */
-export interface SubscriptionPlan {
-    /**
-     * The plan identifier.
-     * This identifier should not be changed once set, as it is used to link the plan to existing Stripe prices.
-     * This identifier should be unique accross all products and subscription plans.
-     */
-    id: SubscriptionPlanId;
-    /** The name of the plan, meant to be displayable to the user. */
-    name: string;
-    /** The description of the plan. */
-    description: string;
-    /** The price in cents. */
-    price: number;
-    /** The billing interval (e.g., "month", "year"). */
-    interval: RecurringInterval;
-    /** The recurring interval count. */
-    interval_count: number;
-}
-/**
- * A subscription based product interface.
- *
- * @warning
- * A subscription product is a public type and is accessible in the frontend,
- * through the default Volt Rest API.
- *
- * @docs
- */
-export interface SubscriptionProduct extends BaseProduct {
-    /** The product type. */
-    type: "subscription";
-    /** Integer representing the number of trial period days before the customer is charged for the first time. Has to be at least 1. */
-    trial_days?: number;
-    /**
-     * Optional billing anchor strategy for subscriptions.
-     * @default "immediately"
-     */
-    billing_anchor?: "immediately" | "first_of_month";
-    /**
-     * The subscription plans.
-     * @warning
-     * A user can only be subscribed to a single plan per subscription product,
-     * even if multiple plans are defined here.
-     * When a user subscribes to a subscription plan while it is already subscribed to another
-     * plan of the same product, then the old plan is cancelled.
-     */
-    plans: SubscriptionPlan[];
-}
-/**
- * Supported aggregation formulas for Stripe Billing meters.
- * @see https://docs.stripe.com/api/billing/meter/create
- */
-export type MeterAggregationFormula = "count" | "sum" | "last";
-/**
- * Nested types for the meter product definition.
- *
- * A meter product defines:
- * - a Stripe Billing Meter (usage aggregation definition)
- * - a Stripe Product + recurring metered Price attached to that meter
- *
- * Stripe docs:
- * - Meters: https://docs.stripe.com/api/billing/meter
- * - Create meter: https://docs.stripe.com/api/billing/meter/create
- * - Prices (recurring.meter): https://docs.stripe.com/api/prices/create
- */
-export declare namespace MeterProduct {
-    /**
-     * The meter product kind.
-     */
-    type Kind = "units" | "money";
-    /** Unit price, either by integer (smallest currency unit) or decimal string. */
-    type UnitPrice = number | {
-        decimals: string;
-    };
-    /**
-     * A **unit-based** metered billing product backed by a Stripe Billing Meter and a **metered recurring Price**.
-     *
-     * Use this when:
-     * - you measure usage as **integer units** (requests, tokens, bytes, seconds, etc.)
-     * - and you want Stripe to bill based on aggregated usage over a billing interval
-     *
-     * Pricing:
-     * - `price: number` uses Stripe Price `unit_amount` (integer, smallest currency unit — e.g., cents)
-     * - `price: { decimals: string }` uses Stripe Price `unit_amount_decimal` (string, smallest currency unit — up to 12 decimals)
-     *
-     * Recording usage:
-     * - Call `record_meter_usage(..., { value })` with an **integer** `value`.
-     * - The meter's `aggregation_formula` controls how events are aggregated (e.g., `"sum"`, `"count"`, `"last"`).
-     *
-     * Stripe docs:
-     * - Meters: https://docs.stripe.com/api/billing/meter
-     * - Create meter: https://docs.stripe.com/api/billing/meter/create
-     * - Create price (recurring.meter): https://docs.stripe.com/api/prices/create
-     *
-     * @warning
-     * A meter product is a public type and is accessible in the frontend,
-     * through the default Volt Rest API.
-     *
-     * @example
-     * {Charge 1 cent per request}
-     * ```ts
-     * const products: Product[] = [{
-     *   id: "api_requests",
-     *   type: "meter",
-     *   kind: "units",
-     *   name: "API Requests",
-     *   description: "Usage-based billing per request.",
-     *   currency: "usd",
-     *   tax_code: "txcd_10103000",
-     *   tax_behavior: "unspecified",
-     *   interval: "month",
-     *   interval_count: 1,
-     *   meter_event_name: "api_requests_v1",
-     *   price: 1, // 1 cent per unit
-     * }];
-     *
-     * await record_meter_usage(stripe, {
-     *   uid,
-     *   product: initialized.api_requests,
-     *   value: 1,
-     *   all_products: initialized_all,
-     * });
-     * ```
-     *
-     * @example
-     * {Charge fractional cents per token}
-     * ```ts
-     * const products: Product[] = [{
-     *   id: "tokens",
-     *   type: "meter",
-     *   kind: "units",
-     *   name: "Tokens",
-     *   description: "Charged per token with fractional cents.",
-     *   currency: "usd",
-     *   tax_code: "txcd_10103000",
-     *   tax_behavior: "unspecified",
-     *   interval: "month",
-     *   interval_count: 1,
-     *   meter_event_name: "tokens_v1",
-     *   price: { decimals: "0.000001" }, // cents; $0.00000001 per token
-     * }];
-     * ```
-     *
-     * @docs
-     */
-    interface UnitsMeter extends BaseProduct {
-        /** The product type. */
-        type: "meter";
-        /**
-         * Meter kind:
-         * - `"units"` means you report integer usage units with `value`,
-         *   and configure the price per unit here.
-         * @dev_note Keep this required and not defaulted to "units"
-         *           this makes code easier to maintain and avoids type casting / runtime code mistakes.
-         */
-        kind: "units";
-        /**
-         * Unit price in the smallest currency unit (e.g., cents).
-         * - If number: must be an integer (Stripe `unit_amount`).
-         * - If object: decimals string up to 12 decimals (Stripe `unit_amount_decimal`).
-         */
-        price: UnitPrice;
-        /** The billing interval for the usage price (typically `"month"`). */
-        interval: RecurringInterval;
-        /** The recurring interval count. */
-        interval_count: number;
-        /**
-         * The Stripe meter event name.
-         * This must be stable and unique across your Stripe account.
-         * @see https://docs.stripe.com/api/billing/meter/create
-         */
-        meter_event_name: string;
-        /**
-         * The meter's default aggregation formula.
-         * @default "sum"
-         * @see https://docs.stripe.com/api/billing/meter/create
-         */
-        aggregation_formula?: MeterAggregationFormula;
-        /**
-         * The payload key used to map usage events to a Stripe customer id.
-         * Stripe currently requires customer_mapping.type="by_id".
-         * @default "stripe_customer_id"
-         * @see https://docs.stripe.com/api/billing/meter/create
-         */
-        customer_mapping_event_payload_key?: string;
-        /**
-         * The payload key used as the numeric value for the meter.
-         * @default "value"
-         * @see https://docs.stripe.com/api/billing/meter/create
-         */
-        value_settings_event_payload_key?: string;
-        /**
-         * Optional pre-aggregation time window.
-         * @see https://docs.stripe.com/api/billing/meter/create
-         */
-        event_time_window?: "hour" | "day";
-    }
-    /**
-     * A **money-based** meter product for charging *arbitrary per-event currency amounts*.
-     *
-     * Use this when:
-     * - you compute a currency cost per request (e.g. OpenAI usage cost),
-     * - and you want to record **that exact amount** (to supported precision) per event,
-     * - without maintaining token pricing tables in Stripe.
-     *
-     * How it works internally:
-     * - The Stripe recurring Price is created with a **fixed** `unit_amount_decimal`:
-     *   `"0.000000000001"` **in cents** (10^-12 cents per unit).
-     * - When you call `record_meter_usage(..., { amount })`, your library converts the
-     *   major-unit amount (e.g. USD) into an integer number of these pico-cent units
-     *   and records that integer as the meter event value.
-     *
-     * Important constraints:
-     * - You must NOT set `price` on this meter.
-     * - Amounts can be passed as string or number.
-     * - Conversion supports up to 14 decimals in major units (because we convert to 10^14 units),
-     *   and you can choose rounding behavior via `round`.
-     *
-     * @warning
-     * A meter product is a public type and is accessible in the frontend,
-     * through the default Volt Rest API.
-     *
-     * @example
-     * {Charge exact per-request OpenAI spend}
-     * You compute the request cost in USD and report it directly.
-     * ```ts
-     * const products: Product[] = [{
-     *   id: "ai_usage",
-     *   type: "meter",
-     *   kind: "money",
-     *   name: "AI Usage",
-     *   description: "Billed by actual AI spend per request.",
-     *   currency: "usd",
-     *   tax_code: "txcd_10103000",
-     *   tax_behavior: "unspecified",
-     *   interval: "month",
-     *   interval_count: 1,
-     *   meter_event_name: "ai_usage_v1",
-     * }];
-     *
-     * // Later, when a request costs $0.007463:
-     * await record_meter_usage(stripe, {
-     *   uid,
-     *   product: initialized.ai_usage,
-     *   amount: "0.007463",
-     *   round: "exact",
-     *   all_products: initialized_all,
-     * });
-     * ```
-     *
-     * @example
-     * {Charge using a float with rounding}
-     * If you have a float, pass it and choose a rounding mode.
-     * ```ts
-     * await record_meter_usage(stripe, {
-     *   uid,
-     *   product: initialized.ai_usage,
-     *   amount: 0.007463,
-     *   round: "round",
-     *   all_products: initialized_all,
-     * });
-     * ```
-     *
-     * @docs
-     */
-    interface MoneyMeter extends BaseProduct {
-        /** The product type. */
-        type: "meter";
-        /**
-         * Money meters fix the unit price internally; callers report arbitrary amounts.
-         */
-        kind: "money";
-        /** No integer price is allowed for money meters. */
-        price?: never;
-        /** The billing interval for the usage price (typically `"month"`). */
-        interval: RecurringInterval;
-        /** The recurring interval count. */
-        interval_count: number;
-        /**
-         * The Stripe meter event name.
-         * This must be stable and unique across your Stripe account.
-         * @see https://docs.stripe.com/api/billing/meter/create
-         */
-        meter_event_name: string;
-        /**
-         * The meter's default aggregation formula.
-         * @default "sum"
-         * @see https://docs.stripe.com/api/billing/meter/create
-         */
-        aggregation_formula?: MeterAggregationFormula;
-        /**
-         * The payload key used to map usage events to a Stripe customer id.
-         * Stripe currently requires customer_mapping.type="by_id".
-         * @default "stripe_customer_id"
-         * @see https://docs.stripe.com/api/billing/meter/create
-         */
-        customer_mapping_event_payload_key?: string;
-        /**
-         * The payload key used as the numeric value for the meter.
-         * @default "value"
-         * @see https://docs.stripe.com/api/billing/meter/create
-         */
-        value_settings_event_payload_key?: string;
-        /**
-         * Optional pre-aggregation time window.
-         * @see https://docs.stripe.com/api/billing/meter/create
-         */
-        event_time_window?: "hour" | "day";
-    }
-    /** Multiplier from major units to pico-cent units: 100 * 10^12 = 10^14. */
-    const MONEY_METER_MAJOR_TO_PICO_CENTS_SHIFT = 14;
-    /** Fixed Stripe unit_amount_decimal for money meters, in cents. */
-    const MONEY_METER_UNIT_AMOUNT_DECIMAL_CENTS = "0.000000000001";
-}
-/**
- * A Stripe usage-based billing product backed by a Stripe Billing Meter and a metered recurring Price.
- *
- * This union offers two easy-to-understand variants:
- * - `UnitsMeter`: unit-based pricing where usage is recorded as integer `value` events, and the unit price is either:
- *   - integer smallest-currency pricing (`unit_amount`) via `price: number`, or
- *   - decimal smallest-currency pricing (`unit_amount_decimal`) via `price: { decimals: string }`
- * - `MoneyMeter`: fixed internal unit price with caller-specified per-event currency amounts recorded via `amount`
- *
- * @warning
- * A meter product is a public type and is accessible in the frontend,
- * through the default Volt Rest API.
- *
- * @example
- * {Choose a meter type}
- * Pick the variant that matches how you want to report usage:
- * ```ts
- * const by_requests: MeterProduct = {
- *   type: "meter",
- *   kind: "units",
- *   id: "requests",
- *   name: "Requests",
- *   description: "Charged per request.",
- *   currency: "usd",
- *   tax_code: "txcd_10103000",
- *   tax_behavior: "unspecified",
- *   interval: "month",
- *   interval_count: 1,
- *   meter_event_name: "requests_v1",
- *   price: 1,
- * };
- *
- * const by_tokens_small_price: MeterProduct = {
- *   type: "meter",
- *   kind: "units",
- *   id: "tokens",
- *   name: "Tokens",
- *   description: "Charged per token with fractional cents.",
- *   currency: "usd",
- *   tax_code: "txcd_10103000",
- *   tax_behavior: "unspecified",
- *   interval: "month",
- *   interval_count: 1,
- *   meter_event_name: "tokens_v1",
- *   price: { decimals: "0.000001" },
- * };
- *
- * const by_actual_spend: MeterProduct = {
- *   type: "meter",
- *   kind: "money",
- *   id: "ai_spend",
- *   name: "AI Spend",
- *   description: "Charged by actual spend per request.",
- *   currency: "usd",
- *   tax_code: "txcd_10103000",
- *   tax_behavior: "unspecified",
- *   interval: "month",
- *   interval_count: 1,
- *   meter_event_name: "ai_spend_v1",
- * };
- * ```
- *
- * @see {@link MeterProduct.UnitsMeter} for unit-based pricing (integer or decimal unit price).
- * @see {@link MeterProduct.MoneyMeter} for arbitrary per-event currency amounts.
- *
- * @docs
- */
-export type MeterProduct = MeterProduct.UnitsMeter | MeterProduct.MoneyMeter;
-/** A union type of all products. */
-export type Product = OneTimePaymentProduct | SubscriptionProduct | MeterProduct;
-/** An initialized one-time product. */
-export interface InitializedOneTimeProduct extends OneTimePaymentProduct {
-    /** The product type. */
-    type: "one_time";
-    /** The Stripe product id. */
-    stripe_product_id: string;
-    /** The Stripe price id. */
-    stripe_price_id: string;
-}
-/** An initialized subscription plan. */
-export interface InitializedSubscriptionPlan extends SubscriptionPlan {
-    /** The type. */
-    type: "subscription_plan";
-    /** The id of the parent subscription. */
-    subscription_id: string;
-    /** The Stripe price id for this plan. */
-    stripe_price_id: string;
-}
-/** An initialized subscription product with its plans. */
-export interface InitializedSubscriptionProduct extends SubscriptionProduct {
-    /** The product type. */
-    type: "subscription";
-    /** The Stripe product id. */
-    stripe_product_id: string;
-    /** The Stripe price ids for the plans. */
-    plans: InitializedSubscriptionPlan[];
-}
-/**
- * An initialized meter product.
- */
-export type InitializedMeterProduct<T extends MeterProduct = MeterProduct> = T & {
-    /** The product type. */
-    type: "meter";
-    /** The Stripe meter id. */
-    stripe_meter_id: string;
-    /** The Stripe product id. */
-    stripe_product_id: string;
-    /** The Stripe price id (metered recurring price). */
-    stripe_price_id: string;
-};
-/** A union type of all initialized products. */
-export type InitializedProduct = InitializedOneTimeProduct | InitializedSubscriptionProduct | InitializedMeterProduct;
-/**
- * Resolve the subscription product (InitializedSubscriptionProduct) that owns a given plan.
- */
-export declare function resolve_plan_to_parent_subscription(opts: {
-    plan: InitializedSubscriptionPlan;
-    all_products: InitializedProduct[];
-}): InitializedSubscriptionProduct;
-/**
- * Initialize a list of products through the internal initializer, using a single paginated scan
- * of Stripe products and prices which is then reused for all initializations.
- */
-export declare function initialize_products(client: Stripe, server: Server, products: Product[]): Promise<InitializedProduct[]>;
-export {};