@delightstack/stripe 0.1.0

package/dist/server/billing.routes.js

@@ -0,0 +1,441 @@
+import { DelightError } from '@delightstack/utilities';
+import { getStripe, stripeCall, formatPaymentMethod, formatInvoice, parseBody, getAppUrl, resolveReturnUrl, } from './billing.stripe';
+import { syncSubscription, fetchSubscriptionState, activePlanIds } from './billing.sync';
+function jsonResponse(data, status = 200) {
+    return new Response(JSON.stringify(data), {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+/** Get org_id from locals when billing_scope is 'org' */
+function getOrgId(event, config) {
+    if (config.billing_scope !== 'org')
+        return undefined;
+    const locals = event.locals;
+    const org_id = locals.org_id ?? undefined;
+    return org_id;
+}
+/** Get user_id from locals when billing_scope is 'user' */
+function getUserId(event) {
+    const locals = event.locals;
+    const user = locals.user;
+    return user?.id ?? undefined;
+}
+/** Get the org_state cookie writer from locals (org scope only) */
+function getSetOrgState(event, config) {
+    if (config.billing_scope !== 'org')
+        return undefined;
+    const locals = event.locals;
+    return locals.setOrgState;
+}
+/** Resolve customer_id from org_state or user metadata */
+function resolveCustomerId(event, config) {
+    const locals = event.locals;
+    if (config.billing_scope === 'org') {
+        const org_state = locals.org_state;
+        if (org_state?.customer_id)
+            return org_state.customer_id;
+    }
+    return null;
+}
+/** Resolve customer_id, checking org_state then Stripe (by metadata search) */
+async function resolveCustomerIdAsync(event, config) {
+    // First check cached customer_id
+    const cached = resolveCustomerId(event, config);
+    if (cached)
+        return cached;
+    // Search Stripe by org_id or user_id metadata
+    const stripe = getStripe(config);
+    const org_id = getOrgId(event, config);
+    const user_id = getUserId(event);
+    const search_key = config.billing_scope === 'org' ? 'org_id' : 'user_id';
+    const search_value = config.billing_scope === 'org' ? org_id : user_id;
+    if (!search_value)
+        return null;
+    // Guard against Stripe search query injection/breakage — ids from the auth
+    // system should never contain quotes or backslashes
+    if (/['"\\]/.test(search_value)) {
+        throw DelightError.badRequest('Invalid billing identifier');
+    }
+    const customers = await stripeCall(() => stripe.customers.search({
+        query: `metadata['${search_key}']:'${search_value}'`,
+        limit: 1,
+    }));
+    const customer = customers.data[0];
+    if (!customer)
+        return null;
+    // Cache in org_state for future requests
+    cacheCustomerId(event, config, customer.id);
+    return customer.id;
+}
+/** Create a Stripe customer and cache the customer_id */
+async function ensureCustomer(event, config, ctx) {
+    const existing = await resolveCustomerIdAsync(event, config);
+    if (existing)
+        return existing;
+    const stripe = getStripe(config);
+    const locals = event.locals;
+    const user = locals.user;
+    const org = locals.org;
+    const org_id = getOrgId(event, config);
+    const user_id = getUserId(event);
+    const metadata = {};
+    if (org_id)
+        metadata.org_id = org_id;
+    if (user_id)
+        metadata.user_id = user_id;
+    const customer = await stripeCall(() => stripe.customers.create({
+        email: user?.email,
+        name: config.billing_scope === 'org' ? org?.name : user?.name,
+        metadata,
+    }));
+    // Cache the customer_id
+    cacheCustomerId(event, config, customer.id);
+    // Store customer_id in auth org metadata (read-modify-write — never
+    // overwrite existing org JSON metadata from other features)
+    if (org_id && ctx.getAuthServer) {
+        const auth = ctx.getAuthServer(event);
+        if (auth) {
+            try {
+                const existing_record = auth.getOrg ? await auth.getOrg(org_id) : org;
+                let existing_json = {};
+                if (existing_record?.json) {
+                    try {
+                        const parsed = JSON.parse(existing_record.json);
+                        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                            existing_json = parsed;
+                        }
+                    }
+                    catch {
+                        // Unparseable existing json — keep it from being silently
+                        // destroyed by skipping the write entirely
+                        throw new Error('Existing org json is not valid JSON');
+                    }
+                }
+                await auth.updateOrg(org_id, {
+                    json: JSON.stringify({ ...existing_json, customer_id: customer.id }),
+                });
+            }
+            catch {
+                // Non-critical — customer_id is also discoverable via Stripe search
+            }
+        }
+    }
+    if (config.hooks?.onCustomerCreated) {
+        await config.hooks.onCustomerCreated({
+            customer_id: customer.id,
+            org_id,
+            user_id,
+        });
+    }
+    return customer.id;
+}
+/** Cache customer_id in org_state cookie */
+function cacheCustomerId(event, config, customer_id) {
+    if (config.billing_scope !== 'org')
+        return;
+    const locals = event.locals;
+    const setOrgState = locals.setOrgState;
+    if (setOrgState) {
+        setOrgState({ customer_id });
+    }
+}
+export async function handleBillingRoute(event, config, route_path, method, ctx) {
+    const stripe = getStripe(config);
+    // Handle parameterized routes (e.g., /payment-method/:id)
+    const payment_method_match = route_path.match(/^\/payment-method\/(.+)$/);
+    if (payment_method_match) {
+        const pm_id = payment_method_match[1];
+        if (method === 'DELETE' || method === 'PATCH') {
+            const customer_id = await resolveCustomerIdAsync(event, config);
+            if (!customer_id)
+                throw DelightError.badRequest('No customer found');
+            // Verify the payment method belongs to the caller's customer before
+            // acting on it — otherwise any authed user could detach others' cards
+            const pm = await stripeCall(() => stripe.paymentMethods.retrieve(pm_id));
+            const pm_customer = typeof pm.customer === 'string' ? pm.customer : pm.customer?.id;
+            if (pm_customer !== customer_id) {
+                throw DelightError.notFound('Payment method not found');
+            }
+            if (method === 'DELETE') {
+                await stripeCall(() => stripe.paymentMethods.detach(pm_id));
+                return new Response(null, { status: 204 });
+            }
+            await stripeCall(() => stripe.customers.update(customer_id, {
+                invoice_settings: { default_payment_method: pm_id },
+            }));
+            return jsonResponse({ ok: true });
+        }
+        throw DelightError.notFound('Route not found');
+    }
+    switch (`${method} ${route_path}`) {
+        // ── Subscription ───────────────────────────────────────────────
+        case 'GET /subscription': {
+            const customer_id = await resolveCustomerIdAsync(event, config);
+            if (!customer_id)
+                return jsonResponse({ subscription: null });
+            // Lightweight read — no entitlement writes or broadcasts here.
+            // Use POST /sync for a full sync.
+            const state = await fetchSubscriptionState(config, customer_id);
+            // Still cache active plan ids so requirePlan() guards stay fresh
+            getSetOrgState(event, config)?.({ billing_plan_ids: activePlanIds(state) });
+            return jsonResponse({ subscription: state });
+        }
+        case 'POST /subscription': {
+            const body = await parseBody(event.request);
+            const plan_id = body.plan_id;
+            const payment_method_id = body.payment_method_id;
+            const coupon = body.coupon;
+            if (!plan_id)
+                throw DelightError.badRequest('plan_id is required');
+            const plan = config.plans?.find((p) => p.id === plan_id);
+            if (!plan)
+                throw DelightError.badRequest(`Unknown plan: ${plan_id}`);
+            const customer_id = await ensureCustomer(event, config, ctx);
+            // Look up the price by lookup_key
+            const prices = await stripeCall(() => stripe.prices.list({
+                lookup_keys: [plan.lookup_key],
+                limit: 1,
+            }));
+            const price = prices.data[0];
+            if (!price)
+                throw DelightError.badRequest(`Price not found for plan: ${plan_id}`);
+            // Check for existing active subscription
+            const subs = await stripeCall(() => stripe.subscriptions.list({
+                customer: customer_id,
+                status: 'active',
+                limit: 1,
+            }));
+            if (subs.data.length > 0) {
+                // Update existing subscription
+                const existing = subs.data[0];
+                await stripeCall(() => stripe.subscriptions.update(existing.id, {
+                    items: [
+                        ...existing.items.data.map((item) => ({
+                            id: item.id,
+                            deleted: true,
+                        })),
+                        { price: price.id },
+                    ],
+                    ...(payment_method_id ? { default_payment_method: payment_method_id } : {}),
+                    proration_behavior: 'create_prorations',
+                    ...(coupon ? { coupon } : {}),
+                }));
+            }
+            else {
+                // Create new subscription
+                await stripeCall(() => stripe.subscriptions.create({
+                    customer: customer_id,
+                    items: [{ price: price.id }],
+                    ...(payment_method_id ? { default_payment_method: payment_method_id } : {}),
+                    ...(plan.trial_days ? { trial_period_days: plan.trial_days } : {}),
+                    ...(coupon ? { coupon } : {}),
+                }));
+            }
+            // Sync and return updated state
+            const state = await syncSubscription({
+                config,
+                customer_id,
+                org_id: getOrgId(event, config),
+                user_id: getUserId(event),
+                auth: ctx.getAuthServer?.(event),
+                ws: ctx.getWebsocket?.(event),
+                setOrgState: getSetOrgState(event, config),
+            });
+            if (config.hooks?.onSubscriptionChange && state) {
+                await config.hooks.onSubscriptionChange({
+                    customer_id,
+                    subscription_id: state.subscription_id,
+                    status: state.status,
+                    plan_id: state.plan_ids[0] ?? null,
+                    entitlements: state.entitlements,
+                    event,
+                });
+            }
+            return jsonResponse({ subscription: state });
+        }
+        case 'DELETE /subscription': {
+            const customer_id = await resolveCustomerIdAsync(event, config);
+            if (!customer_id)
+                throw DelightError.badRequest('No customer found');
+            // Optional body: { cancel_at_period_end?: boolean }
+            const body = await parseBody(event.request).catch(() => ({}));
+            const cancel_at_period_end = body.cancel_at_period_end === true;
+            // Default list excludes canceled — include trialing/past_due, not just active
+            const subs = await stripeCall(() => stripe.subscriptions.list({
+                customer: customer_id,
+                limit: 100,
+            }));
+            const cancellable = subs.data.find((s) => ['active', 'trialing', 'past_due', 'unpaid', 'incomplete'].includes(s.status));
+            if (cancellable) {
+                if (cancel_at_period_end) {
+                    await stripeCall(() => stripe.subscriptions.update(cancellable.id, {
+                        cancel_at_period_end: true,
+                    }));
+                }
+                else {
+                    await stripeCall(() => stripe.subscriptions.cancel(cancellable.id, {
+                        invoice_now: true,
+                        prorate: true,
+                    }));
+                }
+            }
+            // Sync to clear entitlements
+            const state = await syncSubscription({
+                config,
+                customer_id,
+                org_id: getOrgId(event, config),
+                user_id: getUserId(event),
+                auth: ctx.getAuthServer?.(event),
+                ws: ctx.getWebsocket?.(event),
+                setOrgState: getSetOrgState(event, config),
+            });
+            // Fire the lifecycle hook for cancellations too — when nothing remains,
+            // report the canceled subscription explicitly
+            if (config.hooks?.onSubscriptionChange && cancellable) {
+                await config.hooks.onSubscriptionChange({
+                    customer_id,
+                    subscription_id: state?.subscription_id ?? cancellable.id,
+                    status: state?.status ?? 'canceled',
+                    plan_id: state?.plan_ids[0] ?? null,
+                    entitlements: state?.entitlements ?? [],
+                    event,
+                });
+            }
+            return new Response(null, { status: 204 });
+        }
+        // ── Invoices ───────────────────────────────────────────────────
+        case 'GET /invoice': {
+            const customer_id = await resolveCustomerIdAsync(event, config);
+            if (!customer_id)
+                return jsonResponse({ invoices: [] });
+            const limit = parseInt(event.url.searchParams.get('limit') ?? '10', 10);
+            const invoices = await stripeCall(() => stripe.invoices.list({
+                customer: customer_id,
+                limit: Math.min(limit, 100),
+            }));
+            return jsonResponse({
+                invoices: invoices.data.map(formatInvoice),
+            });
+        }
+        // ── Payment Methods ────────────────────────────────────────────
+        case 'GET /payment-method': {
+            const customer_id = await resolveCustomerIdAsync(event, config);
+            if (!customer_id)
+                return jsonResponse({ payment_methods: [] });
+            const methods = await stripeCall(() => stripe.paymentMethods.list({ customer: customer_id }));
+            const customer = (await stripeCall(() => stripe.customers.retrieve(customer_id)));
+            const default_pm = customer.invoice_settings?.default_payment_method;
+            return jsonResponse({
+                payment_methods: methods.data.map((m) => formatPaymentMethod(m, default_pm)),
+            });
+        }
+        case 'POST /payment-method': {
+            const customer_id = await ensureCustomer(event, config, ctx);
+            const session = await stripeCall(() => stripe.checkout.sessions.create({
+                mode: 'setup',
+                customer: customer_id,
+                currency: 'usd',
+                ui_mode: 'embedded',
+                return_url: `${getAppUrl(event, config)}/billing/complete?session_id={CHECKOUT_SESSION_ID}`,
+            }));
+            return jsonResponse({ client_secret: session.client_secret }, 201);
+        }
+        // ── Billing Portal ─────────────────────────────────────────────
+        case 'POST /portal': {
+            if (!config.portal.enabled) {
+                throw DelightError.badRequest('Billing Portal is not enabled');
+            }
+            const customer_id = await resolveCustomerIdAsync(event, config);
+            if (!customer_id)
+                throw DelightError.badRequest('No customer found');
+            const body = await parseBody(event.request).catch(() => ({}));
+            // Validate the user-provided return_url (open-redirect protection)
+            const return_url = resolveReturnUrl(event, config, body.return_url) ?? getAppUrl(event, config);
+            const session = await stripeCall(() => stripe.billingPortal.sessions.create({
+                customer: customer_id,
+                return_url,
+            }));
+            return jsonResponse({ url: session.url });
+        }
+        // ── Checkout ───────────────────────────────────────────────────
+        case 'POST /checkout': {
+            const body = await parseBody(event.request);
+            const plan_id = body.plan_id;
+            if (!plan_id)
+                throw DelightError.badRequest('plan_id is required');
+            const plan = config.plans?.find((p) => p.id === plan_id);
+            if (!plan)
+                throw DelightError.badRequest(`Unknown plan: ${plan_id}`);
+            // Validate the user-provided return_url (open-redirect protection)
+            // before making any Stripe calls
+            const return_url = resolveReturnUrl(event, config, body.return_url) ??
+                `${getAppUrl(event, config)}/billing/complete?session_id={CHECKOUT_SESSION_ID}`;
+            const customer_id = await ensureCustomer(event, config, ctx);
+            const prices = await stripeCall(() => stripe.prices.list({
+                lookup_keys: [plan.lookup_key],
+                limit: 1,
+            }));
+            const price = prices.data[0];
+            if (!price)
+                throw DelightError.badRequest(`Price not found for plan: ${plan_id}`);
+            const session = await stripeCall(() => stripe.checkout.sessions.create({
+                mode: 'subscription',
+                customer: customer_id,
+                line_items: [{ price: price.id, quantity: 1 }],
+                ui_mode: 'embedded',
+                return_url,
+                ...(plan.trial_days
+                    ? {
+                        subscription_data: {
+                            trial_period_days: plan.trial_days,
+                        },
+                    }
+                    : {}),
+            }));
+            return jsonResponse({ client_secret: session.client_secret });
+        }
+        // ── Plans (public info) ────────────────────────────────────────
+        case 'GET /plan': {
+            const plans = (config.plans ?? [])
+                .filter((p) => !p.archived)
+                .map((p) => ({
+                id: p.id,
+                name: p.name,
+                description: p.description,
+                amount: p.amount,
+                currency: p.currency ?? 'usd',
+                interval: p.interval,
+                interval_count: p.interval_count ?? 1,
+                entitlements: p.entitlements ?? [],
+                trial_days: p.trial_days,
+            }));
+            return jsonResponse({ plans });
+        }
+        // ── Config (client-safe) ───────────────────────────────────────
+        case 'GET /config': {
+            return jsonResponse({
+                publishable_key: config.publishable_key,
+                portal_enabled: config.portal.enabled,
+            });
+        }
+        // ── Force sync ─────────────────────────────────────────────────
+        case 'POST /sync': {
+            const customer_id = await resolveCustomerIdAsync(event, config);
+            if (!customer_id)
+                return jsonResponse({ subscription: null });
+            const state = await syncSubscription({
+                config,
+                customer_id,
+                org_id: getOrgId(event, config),
+                user_id: getUserId(event),
+                auth: ctx.getAuthServer?.(event),
+                ws: ctx.getWebsocket?.(event),
+                setOrgState: getSetOrgState(event, config),
+            });
+            return jsonResponse({ subscription: state });
+        }
+        default:
+            throw DelightError.notFound('Route not found');
+    }
+}

package/dist/server/billing.stripe.d.ts

@@ -0,0 +1,34 @@
+import Stripe from 'stripe';
+import type { ResolvedBillingConfig } from './billing.config';
+import type { PaymentMethodInfo, InvoiceInfo } from '../types';
+/** Get or create a Stripe instance */
+export declare function getStripe(config: ResolvedBillingConfig): Stripe;
+/** Wraps a Stripe API call with consistent error handling */
+export declare function stripeCall<T>(fn: () => Promise<T>): Promise<T>;
+/** Format a Stripe PaymentMethod into a client-safe shape */
+export declare function formatPaymentMethod(method: Stripe.PaymentMethod, default_pm: string | Stripe.PaymentMethod | null | undefined): PaymentMethodInfo;
+/**
+ * Format a Stripe Invoice into a client-safe shape.
+ * All amounts are integers in the smallest currency unit (cents) — never floats.
+ */
+export declare function formatInvoice(invoice: Stripe.Invoice): InvoiceInfo;
+/** Parse JSON body from a request, returning {} on failure */
+export declare function parseBody(request: Request): Promise<Record<string, unknown>>;
+/** Get the app URL from config or request origin */
+export declare function getAppUrl(event: {
+    url: URL;
+}, config: ResolvedBillingConfig): string;
+/**
+ * Validates a client-provided return_url to prevent open-redirect/phishing.
+ *
+ * - `undefined`/non-string → returns `undefined` (caller falls back to a default)
+ * - Relative paths are resolved against the app URL
+ * - Absolute URLs must be http(s) and same-origin with the app URL, the
+ *   request origin, or one of `config.allowed_return_origins`
+ *
+ * @throws DelightError 400 when the URL is malformed or not an allowed origin
+ */
+export declare function resolveReturnUrl(event: {
+    url: URL;
+}, config: ResolvedBillingConfig, raw: unknown): string | undefined;
+//# sourceMappingURL=billing.stripe.d.ts.map

package/dist/server/billing.stripe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing.stripe.d.ts","sourceRoot":"","sources":["../../src/server/billing.stripe.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAK/D,sCAAsC;AACtC,wBAAgB,SAAS,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAa/D;AAED,6DAA6D;AAC7D,wBAAsB,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAcpE;AAED,6DAA6D;AAC7D,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,MAAM,CAAC,aAAa,EAC5B,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,aAAa,GAAG,IAAI,GAAG,SAAS,GAC1D,iBAAiB,CAqBnB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,GAAG,WAAW,CAyBlE;AAED,8DAA8D;AAC9D,wBAAsB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAMlF;AAED,oDAAoD;AACpD,wBAAgB,SAAS,CAAC,KAAK,EAAE;IAAE,GAAG,EAAE,GAAG,CAAA;CAAE,EAAE,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAEpF;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE;IAAE,GAAG,EAAE,GAAG,CAAA;CAAE,EACnB,MAAM,EAAE,qBAAqB,EAC7B,GAAG,EAAE,OAAO,GACV,MAAM,GAAG,SAAS,CA+BpB"}

package/dist/server/billing.stripe.js

@@ -0,0 +1,135 @@
+import Stripe from 'stripe';
+import { DelightError } from '@delightstack/utilities';
+/** Cached Stripe instance per secret key */
+const stripe_instances = new Map();
+/** Get or create a Stripe instance */
+export function getStripe(config) {
+    let instance = stripe_instances.get(config.secret_key);
+    if (!instance) {
+        instance = new Stripe(config.secret_key, {
+            typescript: true,
+            appInfo: {
+                name: 'delightstack',
+                version: '0.1.0',
+            },
+        });
+        stripe_instances.set(config.secret_key, instance);
+    }
+    return instance;
+}
+/** Wraps a Stripe API call with consistent error handling */
+export async function stripeCall(fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        if (error instanceof Stripe.errors.StripeError) {
+            throw new DelightError({
+                message: error.message,
+                status: error.statusCode ?? 500,
+                code: `stripe/${error.type}`,
+                detail: error.code ?? undefined,
+            });
+        }
+        throw DelightError.from(error);
+    }
+}
+/** Format a Stripe PaymentMethod into a client-safe shape */
+export function formatPaymentMethod(method, default_pm) {
+    const default_id = typeof default_pm === 'string' ? default_pm : default_pm?.id;
+    const card = method.card;
+    let display_name = method.type;
+    if (card) {
+        const brand = (card.brand || 'card').charAt(0).toUpperCase() + (card.brand || 'card').slice(1);
+        display_name = `${brand} •••• ${card.last4}`;
+    }
+    return {
+        id: method.id,
+        type: method.type,
+        brand: card?.brand ?? undefined,
+        last4: card?.last4 ?? undefined,
+        exp_month: card?.exp_month ?? undefined,
+        exp_year: card?.exp_year ?? undefined,
+        display_name,
+        is_default: method.id === default_id,
+    };
+}
+/**
+ * Format a Stripe Invoice into a client-safe shape.
+ * All amounts are integers in the smallest currency unit (cents) — never floats.
+ */
+export function formatInvoice(invoice) {
+    let period_start = null;
+    let period_end = null;
+    if (invoice.lines?.data?.[0]) {
+        const line = invoice.lines.data[0];
+        period_start = line.period.start * 1000;
+        period_end = line.period.end * 1000;
+    }
+    return {
+        id: invoice.id,
+        number: invoice.number,
+        status: invoice.status,
+        amount_paid: invoice.amount_paid ?? 0,
+        amount_due: invoice.amount_due ?? 0,
+        total: invoice.total ?? 0,
+        currency: invoice.currency,
+        created: invoice.created * 1000,
+        due_date: invoice.due_date ? invoice.due_date * 1000 : null,
+        period_start,
+        period_end,
+        pdf: invoice.invoice_pdf ?? null,
+        hosted_invoice_url: invoice.hosted_invoice_url ?? null,
+    };
+}
+/** Parse JSON body from a request, returning {} on failure */
+export async function parseBody(request) {
+    try {
+        return (await request.json());
+    }
+    catch {
+        throw DelightError.badRequest('Invalid JSON body');
+    }
+}
+/** Get the app URL from config or request origin */
+export function getAppUrl(event, config) {
+    return config.app_url ?? event.url.origin;
+}
+/**
+ * Validates a client-provided return_url to prevent open-redirect/phishing.
+ *
+ * - `undefined`/non-string → returns `undefined` (caller falls back to a default)
+ * - Relative paths are resolved against the app URL
+ * - Absolute URLs must be http(s) and same-origin with the app URL, the
+ *   request origin, or one of `config.allowed_return_origins`
+ *
+ * @throws DelightError 400 when the URL is malformed or not an allowed origin
+ */
+export function resolveReturnUrl(event, config, raw) {
+    if (typeof raw !== 'string' || !raw)
+        return undefined;
+    const app_url = getAppUrl(event, config);
+    let parsed;
+    try {
+        parsed = new URL(raw, app_url);
+    }
+    catch {
+        throw DelightError.badRequest('Invalid return_url');
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw DelightError.badRequest('return_url must be an http(s) URL');
+    }
+    const allowed = new Set([new URL(app_url).origin, event.url.origin]);
+    for (const origin of config.allowed_return_origins ?? []) {
+        try {
+            allowed.add(new URL(origin).origin);
+        }
+        catch {
+            // Ignore malformed allowlist entries
+        }
+    }
+    if (!allowed.has(parsed.origin)) {
+        throw DelightError.badRequest('return_url must be same-origin or one of allowed_return_origins');
+    }
+    return parsed.toString();
+}

package/dist/server/billing.sync.d.ts

@@ -0,0 +1,29 @@
+import type { ResolvedBillingConfig, AuthServerRpc, WebsocketRpc } from './billing.config';
+import type { SubscriptionState } from '../types';
+export interface SyncContext {
+    config: ResolvedBillingConfig;
+    customer_id: string;
+    org_id?: string;
+    user_id?: string;
+    auth?: AuthServerRpc;
+    ws?: WebsocketRpc;
+    /**
+     * Writes updates into the org_state cookie (from `event.locals.setOrgState`).
+     * Used to cache `billing_plan_ids` so `requirePlan()` guards work without
+     * hitting Stripe. Unavailable in webhook contexts (no user cookie).
+     */
+    setOrgState?: (updates: Record<string, unknown>) => void;
+}
+/**
+ * Lightweight read of the current subscription state from Stripe.
+ * Does NOT update auth entitlements or broadcast — use for GET endpoints.
+ */
+export declare function fetchSubscriptionState(config: ResolvedBillingConfig, customer_id: string): Promise<SubscriptionState | null>;
+/** The plan ids that should be cached in org_state for `requirePlan()` */
+export declare function activePlanIds(state: SubscriptionState | null): string[];
+/**
+ * Fetches the latest subscription state from Stripe and syncs entitlements
+ * to the auth package. Returns the current subscription state.
+ */
+export declare function syncSubscription(ctx: SyncContext): Promise<SubscriptionState | null>;
+//# sourceMappingURL=billing.sync.d.ts.map

package/dist/server/billing.sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing.sync.d.ts","sourceRoot":"","sources":["../../src/server/billing.sync.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAGlD,MAAM,WAAW,WAAW;IAC3B,MAAM,EAAE,qBAAqB,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,EAAE,CAAC,EAAE,YAAY,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CACzD;AA0FD;;;GAGG;AACH,wBAAsB,sBAAsB,CAC3C,MAAM,EAAE,qBAAqB,EAC7B,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAGnC;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,GAAG,MAAM,EAAE,CAEvE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACrC,GAAG,EAAE,WAAW,GACd,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAYnC"}