@stacksjs/payments 0.70.88 → 0.70.91

package/dist/billable/setup-products.js

@@ -0,0 +1,34 @@
+import { saas } from "@stacksjs/config";
+import { err, ok } from "@stacksjs/error-handling";
+import { log } from "@stacksjs/logging";
+import { stripe } from "@stacksjs/payments";
+export async function createStripeProduct() {
+  const plans = saas.plans;
+  try {
+    if (plans !== void 0 && plans.length)
+      for (const plan of plans) {
+        const product = await stripe.products.create({
+          name: plan.productName,
+          description: plan.description,
+          metadata: plan.metadata
+        });
+        for (const pricing of plan.pricing)
+          if (product) {
+            const priceParams = {
+              unit_amount: pricing.price,
+              currency: pricing.currency,
+              product: product.id,
+              lookup_key: pricing.key
+            };
+            if (pricing.interval)
+              priceParams.recurring = { interval: pricing.interval };
+            await stripe.prices.create(priceParams);
+          }
+      }
+    return ok("Migrations generated");
+  } catch (error) {
+    const e = error instanceof Error ? error : Error(String(error));
+    log.error(e);
+    return err(e);
+  }
+}

package/dist/billable/subscription.d.ts

@@ -0,0 +1,12 @@
+import type { UserModel } from '@stacksjs/orm';
+import type Stripe from 'stripe';
+export declare const manageSubscription: SubscriptionManager;
+export declare interface SubscriptionManager {
+  create: (user: UserModel, type: string, lookupKey: string, params: Partial<Stripe.SubscriptionCreateParams>) => Promise<Stripe.Response<Stripe.Subscription>>
+  update: (user: UserModel, type: string, lookupKey: string, params: Partial<Stripe.SubscriptionUpdateParams>) => Promise<Stripe.Response<Stripe.Subscription>>
+  cancel: (subscriptionId: string, params?: Partial<Stripe.SubscriptionCreateParams>) => Promise<Stripe.Response<Stripe.Subscription>>
+  retrieve: (user: UserModel, subscriptionId: string) => Promise<Stripe.Response<Stripe.Subscription>>
+  isValid: (user: UserModel, type: string) => Promise<boolean>
+  isIncomplete: (user: UserModel, type: string) => Promise<boolean>
+}
+declare type SubscriptionsTable = Record<string, unknown>;

package/dist/billable/subscription.js

@@ -0,0 +1,138 @@
+import { db } from "@stacksjs/database";
+import { HttpError } from "@stacksjs/error-handling";
+import { isUniqueViolation } from "@stacksjs/orm";
+import { manageCustomer, managePrice, stripe } from "..";
+import { stacksIdempotencyKey } from "../idempotency";
+export const manageSubscription = (() => {
+  async function create(user, type, lookupKey, params) {
+    const price = await managePrice.retrieveByLookupKey(lookupKey);
+    if (!price)
+      throw Error("Price does not exist in Stripe");
+    const subscriptionItems = [
+      {
+        price: price.id,
+        quantity: 1
+      }
+    ], mergedParams = { ...{
+      customer: await manageCustomer.createOrGetStripeUser(user, {}).then((customer) => {
+        if (!customer || !customer.id)
+          throw Error("Customer does not exist in Stripe");
+        return customer.id;
+      }),
+      payment_behavior: "allow_incomplete",
+      expand: ["latest_invoice.payment_intent"],
+      items: subscriptionItems
+    }, ...params }, subscription = await stripe.subscriptions.create(mergedParams, {
+      idempotencyKey: stacksIdempotencyKey("subscription.create", user.id, type, lookupKey)
+    });
+    await storeSubscription(user, type, lookupKey, subscription);
+    return subscription;
+  }
+  async function update(user, type, lookupKey, _params = {}) {
+    const newPrice = await managePrice.retrieveByLookupKey(lookupKey), activeSubscription = await user?.activeSubscription();
+    if (!newPrice)
+      throw Error("New price does not exist in Stripe");
+    if (!activeSubscription)
+      throw Error("No active subscription for user!");
+    const subscriptionId = activeSubscription.subscription?.provider_id;
+    if (!subscriptionId)
+      throw Error("Active subscription has no provider ID");
+    const subscription = await stripe.subscriptions.retrieve(subscriptionId);
+    if (!subscription)
+      throw Error("Subscription does not exist in Stripe");
+    const subscriptionItemId = subscription.items.data[0]?.id;
+    if (!subscriptionItemId)
+      throw Error("No subscription items found in the subscription");
+    await stripe.subscriptions.update(subscriptionId, {
+      items: [{ id: subscriptionItemId, price: newPrice.id, quantity: 1 }],
+      proration_behavior: "create_prorations"
+    }, {
+      idempotencyKey: stacksIdempotencyKey("subscription.update", subscriptionId, newPrice.id)
+    });
+    const updatedSubscription = await stripe.subscriptions.retrieve(subscriptionId);
+    if (!activeSubscription.subscription?.id)
+      throw Error("Active subscription has no database ID");
+    await updateSubscription(activeSubscription.subscription.id, type, updatedSubscription);
+    return updatedSubscription;
+  }
+  async function cancel(subscriptionId, params) {
+    if (!await stripe.subscriptions.retrieve(subscriptionId))
+      throw Error("Subscription does not exist or does not belong to the user");
+    const updatedSubscription = await stripe.subscriptions.cancel(subscriptionId, params, {
+      idempotencyKey: stacksIdempotencyKey("subscription.cancel", subscriptionId)
+    });
+    await updateStoredSubscription(subscriptionId);
+    return updatedSubscription;
+  }
+  async function retrieve(user, subscriptionId) {
+    if (!user.hasStripeId())
+      throw Error("Customer does not exist in Stripe");
+    return await stripe.subscriptions.retrieve(subscriptionId);
+  }
+  async function updateStoredSubscription(subscriptionId) {
+    await db.updateTable("subscriptions").set({ provider_status: "canceled" }).where("provider_id", "=", subscriptionId).executeTakeFirst();
+  }
+  function isActive(subscription) {
+    return subscription.provider_status === "active";
+  }
+  function isTrial(subscription) {
+    return subscription.provider_status === "trialing";
+  }
+  async function isIncomplete(user, type) {
+    const subscription = await db.selectFrom("subscriptions").where("user_id", "=", user.id).where("type", "=", type).selectAll().executeTakeFirst();
+    if (!subscription)
+      return !1;
+    return subscription.provider_status === "incomplete";
+  }
+  async function isValid(user, type) {
+    const subscription = await db.selectFrom("subscriptions").where("user_id", "=", user.id).where("type", "=", type).selectAll().executeTakeFirst();
+    if (!subscription)
+      return !1;
+    const active = await isActive(subscription), trial = await isTrial(subscription);
+    return active || trial;
+  }
+  async function storeSubscription(user, type, _lookupKey, options) {
+    const firstItem = options.items.data[0];
+    if (!firstItem)
+      throw Error("Stripe subscription contains no line items \u2014 cannot store subscription");
+    const data = removeNullValues({
+      user_id: user.id,
+      type,
+      unit_price: Number(firstItem.price.unit_amount),
+      provider_id: options.id,
+      provider_status: options.status,
+      provider_price_id: firstItem.price.id,
+      quantity: firstItem.quantity,
+      trial_ends_at: options.trial_end != null ? String(options.trial_end) : void 0,
+      ends_at: options.current_period_end != null ? String(options.current_period_end) : void 0,
+      provider_type: "stripe",
+      last_used_at: options.current_period_end != null ? String(options.current_period_end) : void 0
+    });
+    let subscriptionModelCreated;
+    try {
+      subscriptionModelCreated = await db.insertInto("subscriptions").values(data).executeTakeFirst();
+    } catch (error) {
+      if (isUniqueViolation(error))
+        throw new HttpError(409, "A subscription with this provider ID already exists");
+      throw error;
+    }
+    if (!subscriptionModelCreated)
+      throw Error("Failed to insert subscription record");
+    return await db.selectFrom("subscriptions").where("id", "=", Number(subscriptionModelCreated.insertId)).selectAll().executeTakeFirst();
+  }
+  async function updateSubscription(activeSubId, type, options) {
+    const subscription = await db.selectFrom("subscriptions").where("id", "=", activeSubId).selectAll().executeTakeFirst(), firstItem = options.items.data[0];
+    if (!firstItem)
+      throw Error("Stripe subscription contains no line items \u2014 cannot update subscription");
+    await db?.updateTable("subscriptions").set({
+      type,
+      provider_price_id: firstItem.price.id,
+      unit_price: Number(firstItem.price.unit_amount)
+    }).where("id", "=", activeSubId).executeTakeFirst();
+    return subscription;
+  }
+  function removeNullValues(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([_, value]) => value != null));
+  }
+  return { create, update, isValid, isIncomplete, cancel, retrieve };
+})();

package/dist/billable/transaction.d.ts

@@ -0,0 +1,14 @@
+import { PaymentTransaction } from '@stacksjs/orm';
+import type { ModelRow, UserModel } from '@stacksjs/orm';
+export declare const manageTransaction: ManageTransaction;
+export declare interface StoreTransactionOptions {
+  brand: string
+  provider_id: string
+  description?: string
+  type?: string
+}
+export declare interface ManageTransaction {
+  store: (user: UserModel, productId: number, options: StoreTransactionOptions) => Promise<PaymentTransactionsTable | undefined>
+  list: (user: UserModel) => Promise<PaymentTransactionsTable[]>
+}
+declare type PaymentTransactionsTable = ModelRow<typeof PaymentTransaction>;

package/dist/billable/transaction.js

@@ -0,0 +1,25 @@
+import { db } from "@stacksjs/database";
+import { PaymentTransaction } from "@stacksjs/orm";
+export const manageTransaction = (() => {
+  async function store(user, productId, options) {
+    const product = await db.selectFrom("payment_products").where("id", "=", productId).selectAll().executeTakeFirst();
+    if (!product)
+      throw Error(`Payment product with id ${productId} not found.`);
+    const data = {
+      name: product.name,
+      description: options.description ?? "",
+      amount: product.unit_price,
+      brand: options.brand,
+      type: options.type ?? "one-time",
+      provider_id: options.provider_id,
+      user_id: user.id
+    }, createdTransaction = await db.insertInto("payment_transactions").values(data).executeTakeFirst();
+    if (!createdTransaction)
+      throw Error("Failed to insert payment transaction");
+    return await db.selectFrom("payment_transactions").where("id", "=", Number(createdTransaction.insertId)).selectAll().executeTakeFirst();
+  }
+  async function list(user) {
+    return await db.selectFrom("payment_transactions").where("user_id", "=", user.id).selectAll().execute();
+  }
+  return { store, list };
+})();

package/dist/billable/webhook.d.ts

@@ -0,0 +1,155 @@
+import type Stripe from 'stripe';
+/**
+ * Register a webhook event handler
+ */
+export declare function onWebhookEvent(eventType: WebhookEventType, handler: WebhookHandler): void;
+/**
+ * Register multiple webhook handlers at once
+ */
+export declare function registerWebhookHandlers(handlerMap: Record<WebhookEventType, WebhookHandler>): void;
+/**
+ * Construct and verify a webhook event from the raw request.
+ *
+ * `tolerance` (in seconds) controls how much clock skew between Stripe and
+ * this server is acceptable before signatures are rejected. Stripe's SDK
+ * default is 300s; tightening this is recommended in production but the
+ * previous code dropped the value entirely, so a configured tolerance was
+ * silently ignored.
+ */
+export declare function constructEvent(payload: string | Buffer, signature: string, secret: string, tolerance?: number): Stripe.Event;
+/**
+ * Async variant of {@link constructEvent}. Some runtimes (notably Bun) resolve
+ * the Stripe SDK's crypto provider to WebCrypto's `SubtleCrypto`, which is
+ * async-only — the synchronous `constructEvent` then throws
+ * "SubtleCryptoProvider cannot be used in a synchronous context". Verifying via
+ * `constructEventAsync` works across Node and Bun, so webhook processing uses
+ * this path.
+ */
+export declare function constructEventAsync(payload: string | Buffer, signature: string, secret: string, tolerance?: number): Promise<Stripe.Event>;
+/**
+ * Handle an incoming webhook event
+ */
+export declare function handleWebhookEvent(event: Stripe.Event): Promise<{ handled: boolean, eventType: string, errors?: string[] }>;
+/**
+ * Process a webhook request
+ */
+export declare function processWebhook(payload: string | Buffer, signature: string, config: WebhookConfig): Promise<{ success: boolean, eventType?: string, error?: string }>;
+/**
+ * Register payment intent handlers
+ */
+export declare function onPaymentIntent(handlers: {
+  succeeded?: WebhookHandler
+  failed?: WebhookHandler
+  created?: WebhookHandler
+  canceled?: WebhookHandler
+}): void;
+/**
+ * Register subscription handlers
+ */
+export declare function onSubscription(handlers: {
+  created?: WebhookHandler
+  updated?: WebhookHandler
+  deleted?: WebhookHandler
+  trialWillEnd?: WebhookHandler
+}): void;
+/**
+ * Register invoice handlers
+ */
+export declare function onInvoice(handlers: {
+  paid?: WebhookHandler
+  paymentFailed?: WebhookHandler
+  created?: WebhookHandler
+  finalized?: WebhookHandler
+}): void;
+/**
+ * Register checkout session handlers
+ */
+export declare function onCheckout(handlers: {
+  completed?: WebhookHandler
+  expired?: WebhookHandler
+}): void;
+/**
+ * Register charge handlers
+ */
+export declare function onCharge(handlers: {
+  succeeded?: WebhookHandler
+  failed?: WebhookHandler
+  refunded?: WebhookHandler
+  disputed?: WebhookHandler
+}): void;
+/**
+ * Extract payment intent from event
+ */
+export declare function getPaymentIntent(event: Stripe.Event): Stripe.PaymentIntent | null;
+/**
+ * Extract subscription from event
+ */
+export declare function getSubscription(event: Stripe.Event): Stripe.Subscription | null;
+/**
+ * Extract invoice from event
+ */
+export declare function getInvoice(event: Stripe.Event): Stripe.Invoice | null;
+/**
+ * Extract checkout session from event
+ */
+export declare function getCheckoutSession(event: Stripe.Event): Stripe.Checkout.Session | null;
+/**
+ * Extract charge from event
+ */
+export declare function getCharge(event: Stripe.Event): Stripe.Charge | null;
+/**
+ * Extract customer from event
+ */
+export declare function getCustomer(event: Stripe.Event): Stripe.Customer | null;
+declare const handlers: Map<WebhookEventType, WebhookHandler[]>;
+export declare const manageWebhook: {
+  onWebhookEvent: typeof onWebhookEvent;
+  registerWebhookHandlers: typeof registerWebhookHandlers;
+  constructEvent: typeof constructEvent;
+  constructEventAsync: typeof constructEventAsync;
+  handleWebhookEvent: typeof handleWebhookEvent;
+  processWebhook: typeof processWebhook;
+  onPaymentIntent: typeof onPaymentIntent;
+  onSubscription: typeof onSubscription;
+  onInvoice: typeof onInvoice;
+  onCheckout: typeof onCheckout;
+  onCharge: typeof onCharge;
+  getPaymentIntent: typeof getPaymentIntent;
+  getSubscription: typeof getSubscription;
+  getInvoice: typeof getInvoice;
+  getCheckoutSession: typeof getCheckoutSession;
+  getCharge: typeof getCharge;
+  getCustomer: typeof getCustomer
+};
+export declare interface WebhookConfig {
+  secret: string
+  tolerance?: number
+}
+export type WebhookEventType = | 'payment_intent.succeeded'
+  | 'payment_intent.payment_failed'
+  | 'payment_intent.created'
+  | 'payment_intent.canceled'
+  | 'customer.subscription.created'
+  | 'customer.subscription.updated'
+  | 'customer.subscription.deleted'
+  | 'customer.subscription.trial_will_end'
+  | 'customer.created'
+  | 'customer.updated'
+  | 'customer.deleted'
+  | 'invoice.paid'
+  | 'invoice.payment_failed'
+  | 'invoice.finalized'
+  | 'invoice.created'
+  | 'checkout.session.completed'
+  | 'checkout.session.expired'
+  | 'charge.succeeded'
+  | 'charge.failed'
+  | 'charge.refunded'
+  | 'charge.dispute.created'
+  | 'charge.dispute.closed'
+  | 'payment_method.attached'
+  | 'payment_method.detached'
+  | 'setup_intent.succeeded'
+  | 'setup_intent.setup_failed'
+  | string;
+export type WebhookHandler = (_event: Stripe.Event) => Promise<void> | void;

package/dist/billable/webhook.js

@@ -0,0 +1,153 @@
+import { stripe } from "..";
+const handlers = new Map;
+export function onWebhookEvent(eventType, handler) {
+  const existing = handlers.get(eventType) || [];
+  existing.push(handler);
+  handlers.set(eventType, existing);
+}
+export function registerWebhookHandlers(handlerMap) {
+  for (const [eventType, handler] of Object.entries(handlerMap))
+    onWebhookEvent(eventType, handler);
+}
+export function constructEvent(payload, signature, secret, tolerance) {
+  if (tolerance != null && Number.isFinite(tolerance) && tolerance > 0)
+    return stripe.webhooks.constructEvent(payload, signature, secret, tolerance);
+  return stripe.webhooks.constructEvent(payload, signature, secret);
+}
+export async function constructEventAsync(payload, signature, secret, tolerance) {
+  if (tolerance != null && Number.isFinite(tolerance) && tolerance > 0)
+    return await stripe.webhooks.constructEventAsync(payload, signature, secret, tolerance);
+  return await stripe.webhooks.constructEventAsync(payload, signature, secret);
+}
+export async function handleWebhookEvent(event) {
+  const eventHandlers = handlers.get(event.type) || [];
+  if (eventHandlers.length === 0)
+    return { handled: !1, eventType: event.type };
+  const errors = [];
+  for (const handler of eventHandlers)
+    try {
+      await handler(event);
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+  return {
+    handled: !0,
+    eventType: event.type,
+    ...errors.length > 0 ? { errors } : {}
+  };
+}
+export async function processWebhook(payload, signature, config) {
+  try {
+    const event = await constructEventAsync(payload, signature, config.secret, config.tolerance), result = await handleWebhookEvent(event);
+    if (result.errors && result.errors.length > 0)
+      return {
+        success: !1,
+        eventType: result.eventType,
+        error: result.errors.join("; ")
+      };
+    return {
+      success: !0,
+      eventType: result.eventType
+    };
+  } catch (error) {
+    return {
+      success: !1,
+      error: error instanceof Error ? error.message : "Unknown error"
+    };
+  }
+}
+export function onPaymentIntent(handlers) {
+  if (handlers.succeeded)
+    onWebhookEvent("payment_intent.succeeded", handlers.succeeded);
+  if (handlers.failed)
+    onWebhookEvent("payment_intent.payment_failed", handlers.failed);
+  if (handlers.created)
+    onWebhookEvent("payment_intent.created", handlers.created);
+  if (handlers.canceled)
+    onWebhookEvent("payment_intent.canceled", handlers.canceled);
+}
+export function onSubscription(handlers) {
+  if (handlers.created)
+    onWebhookEvent("customer.subscription.created", handlers.created);
+  if (handlers.updated)
+    onWebhookEvent("customer.subscription.updated", handlers.updated);
+  if (handlers.deleted)
+    onWebhookEvent("customer.subscription.deleted", handlers.deleted);
+  if (handlers.trialWillEnd)
+    onWebhookEvent("customer.subscription.trial_will_end", handlers.trialWillEnd);
+}
+export function onInvoice(handlers) {
+  if (handlers.paid)
+    onWebhookEvent("invoice.paid", handlers.paid);
+  if (handlers.paymentFailed)
+    onWebhookEvent("invoice.payment_failed", handlers.paymentFailed);
+  if (handlers.created)
+    onWebhookEvent("invoice.created", handlers.created);
+  if (handlers.finalized)
+    onWebhookEvent("invoice.finalized", handlers.finalized);
+}
+export function onCheckout(handlers) {
+  if (handlers.completed)
+    onWebhookEvent("checkout.session.completed", handlers.completed);
+  if (handlers.expired)
+    onWebhookEvent("checkout.session.expired", handlers.expired);
+}
+export function onCharge(handlers) {
+  if (handlers.succeeded)
+    onWebhookEvent("charge.succeeded", handlers.succeeded);
+  if (handlers.failed)
+    onWebhookEvent("charge.failed", handlers.failed);
+  if (handlers.refunded)
+    onWebhookEvent("charge.refunded", handlers.refunded);
+  if (handlers.disputed)
+    onWebhookEvent("charge.dispute.created", handlers.disputed);
+}
+export function getPaymentIntent(event) {
+  if (event.type.startsWith("payment_intent."))
+    return event.data.object;
+  return null;
+}
+export function getSubscription(event) {
+  if (event.type.startsWith("customer.subscription."))
+    return event.data.object;
+  return null;
+}
+export function getInvoice(event) {
+  if (event.type.startsWith("invoice."))
+    return event.data.object;
+  return null;
+}
+export function getCheckoutSession(event) {
+  if (event.type.startsWith("checkout.session."))
+    return event.data.object;
+  return null;
+}
+export function getCharge(event) {
+  if (event.type.startsWith("charge."))
+    return event.data.object;
+  return null;
+}
+export function getCustomer(event) {
+  if (event.type.startsWith("customer.") && !event.type.includes("subscription"))
+    return event.data.object;
+  return null;
+}
+export const manageWebhook = {
+  onWebhookEvent,
+  registerWebhookHandlers,
+  constructEvent,
+  constructEventAsync,
+  handleWebhookEvent,
+  processWebhook,
+  onPaymentIntent,
+  onSubscription,
+  onInvoice,
+  onCheckout,
+  onCharge,
+  getPaymentIntent,
+  getSubscription,
+  getInvoice,
+  getCheckoutSession,
+  getCharge,
+  getCustomer
+};

package/dist/drivers/stripe.d.ts

@@ -0,0 +1,8 @@
+import type Stripe from 'stripe';
+/**
+ * Lazy-initialized Stripe instance.
+ * Only throws when you actually try to use Stripe, not at module load time.
+ * This allows the payments package to be imported without a configured key
+ * (e.g., in tests, CLI, or environments that don't use Stripe).
+ */
+export declare const stripe: Stripe;

package/dist/drivers/stripe.js

@@ -0,0 +1,25 @@
+import { createRequire } from "node:module";
+import { services } from "@stacksjs/config";
+const require = createRequire(import.meta.url);
+function StripeCtor() {
+  try {
+    return require("stripe");
+  } catch {
+    throw Error("Stripe payments are being used but the `stripe` package is not installed. " + "It is an opt-in dependency \u2014 run `bun add stripe` to enable server-side Stripe payments.");
+  }
+}
+let _stripe = null;
+export const stripe = new Proxy({}, {
+  get(_target, prop) {
+    if (!_stripe) {
+      const apiKey = services?.stripe?.secretKey;
+      if (!apiKey)
+        throw Error("Stripe secret key is not configured. Set STRIPE_SECRET_KEY in your .env file.");
+      const apiVersion = "2026-03-25.dahlia", configuredVersion = services?.stripe?.apiVersion;
+      if (configuredVersion && configuredVersion !== apiVersion)
+        throw Error(`Stripe API version ${configuredVersion} does not match the installed SDK version ${apiVersion}`);
+      _stripe = new (StripeCtor())(apiKey, { apiVersion });
+    }
+    return _stripe[prop];
+  }
+});

package/dist/idempotency.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Build a deterministic Stripe idempotency key for an operation.
+ * The `scope` should be a stable string identifying the call site
+ * (e.g. `'customer.create'`, `'subscription.create'`); `parts` are
+ * any extra identifying values (user id, lookup key, etc.) that
+ * uniquely scope the operation within that user's lifetime.
+ *
+ * @param scope - stable operation name; never user input
+ * @param parts - identifying values appended after scope (coerced
+ *                to string; nullish values are skipped)
+ */
+export declare function stacksIdempotencyKey(scope: string, ...parts: Array<string | number | null | undefined>): string;
+/**
+ * Build a one-shot idempotency key for operations that are NOT
+ * naturally retryable (a unique-per-attempt key that won't collide
+ * with anything). Used when the caller WANTS a fresh Stripe object
+ * each time but still wants the safety of a single network retry
+ * within a single attempt. The key includes a random suffix so
+ * sequential attempts produce different keys.
+ *
+ * Used for payment intents, checkout sessions — operations where
+ * "create another one" is the right semantic on a retry by the
+ * caller, but where a single network blip during a single attempt
+ * still benefits from in-flight idempotency.
+ */
+export declare function freshIdempotencyKey(scope: string, ...parts: Array<string | number | null | undefined>): string;

package/dist/idempotency.js

@@ -0,0 +1,13 @@
+import { createHash } from "node:crypto";
+const KEY_PREFIX = "stacks", KEY_VERSION = "v1", MAX_KEY_LENGTH = 255;
+export function stacksIdempotencyKey(scope, ...parts) {
+  const tail = parts.filter((p) => p !== null && p !== void 0 && p !== "").map((p) => String(p)).join(":"), raw = tail ? `${KEY_PREFIX}:${scope}:${tail}:${KEY_VERSION}` : `${KEY_PREFIX}:${scope}:${KEY_VERSION}`;
+  if (raw.length <= MAX_KEY_LENGTH)
+    return raw;
+  const hashed = createHash("sha256").update(tail).digest("hex").slice(0, 32);
+  return `${KEY_PREFIX}:${scope}:${hashed}:${KEY_VERSION}`;
+}
+export function freshIdempotencyKey(scope, ...parts) {
+  const random = createHash("sha256").update(`${Date.now()}:${Math.random()}`).digest("hex").slice(0, 16);
+  return stacksIdempotencyKey(scope, ...parts, random);
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export type * as Stripe from 'stripe';
+/**
+ * Payments Package
+ *
+ * Provides payment processing capabilities with Stripe integration.
+ */
+// Main Payment facade
+export * from './payment';
+export { default as Payment } from './payment';
+// Billable modules
+export * from './billable/index';
+// Stripe driver and SDK
+export * from './drivers/stripe';
+// Idempotency-key helpers — passed to every Stripe create/update so
+// retries don't produce duplicate objects (stacksjs/stacks#1876 X-1).
+export { freshIdempotencyKey, stacksIdempotencyKey } from './idempotency';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./payment";
+export { default as Payment } from "./payment";
+export * from "./billable";
+export * from "./drivers/stripe";
+export { freshIdempotencyKey, stacksIdempotencyKey } from "./idempotency";