@vandenberghinc/volt 1.2.6 → 1.2.8

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

@@ -0,0 +1,118 @@
+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, {
+  add_days_utc: () => add_days_utc,
+  assert: () => assert,
+  assert_never: () => assert_never,
+  first_day_of_next_month_utc: () => first_day_of_next_month_utc,
+  generate_random_idempotency_key: () => generate_random_idempotency_key,
+  is_non_empty_string: () => is_non_empty_string,
+  public_assert: () => public_assert,
+  public_assert_never: () => public_assert_never,
+  stable_idempotency_key: () => stable_idempotency_key,
+  stripe_api_call: () => stripe_api_call,
+  to_unix_seconds: () => to_unix_seconds
+});
+module.exports = __toCommonJS(stdin_exports);
+var import_node_crypto = require("node:crypto");
+var import_error = require("./error.js");
+async function stripe_api_call(fn, context) {
+  try {
+    return await fn();
+  } catch (error) {
+    if (error instanceof import_error.ExternalStripeError || error instanceof import_error.InternalStripeError) {
+      throw error;
+    }
+    throw new import_error.InternalStripeError("api_error", "Stripe API request failed.", context, error);
+  }
+}
+function assert(condition, error_code, message, context, cause) {
+  if (!condition) {
+    const normalized_message = message.endsWith(".") ? message : `${message}.`;
+    throw new import_error.InternalStripeError(error_code, normalized_message, context, cause);
+  }
+}
+function public_assert(condition, error_code, message, context, cause) {
+  if (!condition) {
+    const normalized_message = message.endsWith(".") ? message : `${message}.`;
+    throw new import_error.ExternalStripeError(error_code, normalized_message, context, cause);
+  }
+}
+function assert_never(value, message) {
+  throw new import_error.InternalStripeError("invalid_argument", message, { value });
+}
+function public_assert_never(value, message) {
+  throw new import_error.ExternalStripeError("invalid_argument", message, { value });
+}
+function is_non_empty_string(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+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}_${(0, import_node_crypto.randomUUID)()}`;
+  if (key.length > max_length) {
+    const digest = (0, import_node_crypto.createHash)("sha256").update(key).digest("hex");
+    return digest.slice(0, Math.min(max_length, digest.length));
+  }
+  return key;
+}
+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;
+  const digest = (0, import_node_crypto.createHash)("sha256").update(s).digest("hex");
+  return digest.slice(0, Math.min(max_length, digest.length));
+}
+function to_unix_seconds(date) {
+  return Math.floor(date.getTime() / 1e3);
+}
+function first_day_of_next_month_utc(now) {
+  const year = now.getUTCFullYear();
+  const month = now.getUTCMonth();
+  return new Date(Date.UTC(year, month + 1, 1, 0, 0, 0, 0));
+}
+function add_days_utc(date, days) {
+  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()));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  add_days_utc,
+  assert,
+  assert_never,
+  first_day_of_next_month_utc,
+  generate_random_idempotency_key,
+  is_non_empty_string,
+  public_assert,
+  public_assert_never,
+  stable_idempotency_key,
+  stripe_api_call,
+  to_unix_seconds
+});

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

@@ -0,0 +1,105 @@
+/**
+ * @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>;