@ozura/elements 1.2.4-next.48 → 1.2.4-next.50

package/dist/react/server/index.d.ts

@@ -174,6 +174,93 @@ export interface CardSaleInput {
      */
     transactionChannel?: 'cardPresent' | 'ecommerce' | 'moto' | 'recurring';
 }
+/** Billing cadence for a recurring subscription plan. */
+export type RecurringInterval = 'daily' | 'weekly' | 'monthly' | 'yearly';
+export interface CreateRecurringPlanInput {
+    /** From TokenResponse.token (frontend SDK). */
+    token: string;
+    /** From TokenResponse.cvcSession (frontend SDK). */
+    cvcSession: string;
+    /** Decimal string — the base recurring charge amount, e.g. "19.99". */
+    amount: string;
+    /** ISO 4217, e.g. "USD". Default: "USD". */
+    currency?: string;
+    /**
+     * Customer billing details. All address fields are required by the Pay API
+     * for recurring plans (stricter than one-time card sales).
+     */
+    billing: BillingDetails;
+    /** Client IP address — always obtain server-side, never from the browser. */
+    clientIpAddress: string;
+    /** Display name for the subscription plan (shown on statements and receipts). */
+    planName: string;
+    /** Billing cadence. */
+    interval: RecurringInterval;
+    /** Optional plan description shown to customers (max 100 chars). */
+    planDescription?: string;
+    /**
+     * Amount for the initial trial period cycles. Requires `initialCycles`.
+     * Pass `"0.00"` for a free trial.
+     */
+    initialAmount?: string;
+    /** Number of cycles to charge `initialAmount` before switching to `amount`. */
+    initialCycles?: number;
+    /** One-time setup fee charged alongside the first cycle (additive). */
+    setupFee?: string;
+    /**
+     * Multiplier for the interval period. Default: 1.
+     * e.g. `interval: "monthly"` + `intervalCount: 3` → billed every 3 months.
+     */
+    intervalCount?: number;
+    /** ISO 8601 end date. Must be at least one full cycle after the enrollment date. */
+    endDate?: string;
+    /** Maximum number of billing cycles. Omit for indefinite. */
+    maxCycles?: number;
+    /** Payment retry attempts on failure. Default: 3. */
+    maxAttempts?: number;
+    /** Hours between retry attempts. Default: 24. */
+    retryIntervalHours?: number;
+    /** Your own internal subscription reference ID (max 50 chars). */
+    merchantRecurringReference?: string;
+    salesTaxExempt?: boolean;
+    /** Defaults to "0.00". */
+    surchargePercent?: string;
+    /** Processor to use. If omitted, the Pay API auto-selects. */
+    processor?: 'elavon' | 'nuvei' | 'worldpay';
+    /**
+     * Transaction channel. Default: `"ecommerce"`.
+     * Use `"moto"` for mail/telephone-order enrollment flows.
+     *
+     * Note: `transactionInitiationType` is always `"cit"` for recurring
+     * enrollment and is not configurable — the Pay API enforces this.
+     * Subsequent MIT charges are handled by Ozura's recurring queue worker.
+     */
+    transactionChannel?: 'ecommerce' | 'moto';
+}
+export interface CreateRecurringPlanResponseData {
+    /** Ozura's internal plan identifier. Store this to manage the subscription. */
+    planId: string;
+    planName: string;
+    planDescription?: string;
+    merchantRecurringReference?: string;
+    /** Base recurring charge amount as a decimal string. */
+    amount: string;
+    currency: string;
+    /** Transaction ID of the initial enrollment charge (Pay API's `citTransactionId`). */
+    transactionId: string;
+    /** Actual amount charged on enrollment (includes setup fee, initial amount, tax, surcharge). */
+    transactionAmount: string;
+    transactionSurchargeAmount?: string;
+    transactionSalesTaxAmount?: string;
+    /** ISO 8601 timestamp of the next scheduled billing cycle. */
+    nextCycleAt: string;
+    endDate?: string;
+    cardLastFour?: string;
+    cardBrand?: string;
+    cardExpMonth?: string;
+    cardExpYear?: string;
+    transDate?: string;
+}
 export interface ListTransactionsInput {
     /** Look up a single transaction by ID. When set, dateFrom/dateTo are not required. */
     transactionId?: string;
@@ -214,6 +301,32 @@ export declare class Ozura {
      * Rate limit: 100 requests/minute per merchant.
      */
     cardSale(input: CardSaleInput): Promise<CardSaleResponseData>;
+    /**
+     * Create a recurring subscription plan and execute the enrollment charge.
+     *
+     * The customer's card is charged immediately for the first billing cycle
+     * (at `initialAmount` if set, otherwise `amount`) and a subscription record
+     * is created in Ozura's billing engine for all future cycles.
+     *
+     * `transactionInitiationType` is always `"cit"` for enrollment — the Pay API
+     * enforces this. Subsequent MIT charges are processed automatically by Ozura's
+     * recurring queue worker; merchants do not need to trigger them.
+     *
+     * Rate limit: 100 requests/minute per merchant.
+     *
+     * @example
+     * const plan = await ozura.createRecurringPlan({
+     *   token:       tokenResponse.token,
+     *   cvcSession:  tokenResponse.cvcSession,
+     *   amount:      '19.99',
+     *   billing:     tokenResponse.billing,
+     *   clientIpAddress: req.ip,
+     *   planName:    'Pro Monthly',
+     *   interval:    'monthly',
+     * });
+     * console.log(plan.planId, plan.transactionId);
+     */
+    createRecurringPlan(input: CreateRecurringPlanInput): Promise<CreateRecurringPlanResponseData>;
     /**
      * List transactions by date range with pagination.
      *
@@ -478,5 +591,116 @@ export declare function createCardSaleMiddleware(ozura: Ozura, options: CardSale
     body?: unknown;
     headers?: unknown;
 }, res: NodeLikeResponse) => Promise<void>;
+/**
+ * Server-side recurring plan configuration resolved per-request.
+ * Source all plan details from your own database — never trust client-supplied values.
+ */
+export interface RecurringPlanConfig {
+    /** Display name for the subscription. */
+    planName: string;
+    /** Billing cadence. */
+    interval: RecurringInterval;
+    planDescription?: string;
+    initialAmount?: string;
+    initialCycles?: number;
+    setupFee?: string;
+    intervalCount?: number;
+    endDate?: string;
+    maxCycles?: number;
+    maxAttempts?: number;
+    retryIntervalHours?: number;
+    merchantRecurringReference?: string;
+    salesTaxExempt?: boolean;
+    surchargePercent?: string;
+    processor?: 'elavon' | 'nuvei' | 'worldpay';
+    /**
+     * Transaction channel. Default: `"ecommerce"`.
+     * Use `"moto"` for mail/telephone-order enrollment flows.
+     * Source from your database via `getPlanConfig` — do not read from the request body.
+     */
+    transactionChannel?: 'ecommerce' | 'moto';
+}
+/**
+ * Options for {@link createRecurringPlanHandler} and {@link createRecurringPlanMiddleware}.
+ *
+ * Both `getAmount` and `getPlanConfig` must source their values from your own
+ * records — never trust the request body for plan price or configuration.
+ */
+export interface RecurringPlanHandlerOptions {
+    /**
+     * Return the base recurring charge amount as a decimal string (e.g. `"19.99"`).
+     * Source from your database; never trust the value the client sends.
+     */
+    getAmount: (body: Record<string, unknown>) => string | Promise<string>;
+    /**
+     * Return the recurring plan configuration for this subscription.
+     * At minimum you must return `planName` and `interval`.
+     *
+     * @example
+     * getPlanConfig: async (body) => {
+     *   const plan = await db.plans.findById(body.planId as string);
+     *   return { planName: plan.name, interval: plan.interval };
+     * }
+     */
+    getPlanConfig: (body: Record<string, unknown>) => RecurringPlanConfig | Promise<RecurringPlanConfig>;
+    /** Return the ISO 4217 currency code. Default: `"USD"`. */
+    getCurrency?: (body: Record<string, unknown>) => string | Promise<string>;
+}
+/**
+ * Creates a ready-to-use Fetch API route handler for recurring subscription enrollment.
+ *
+ * Drop-in for Next.js App Router, Cloudflare Workers, Vercel Edge, and any runtime
+ * built on the standard Web API `Request` / `Response`.
+ *
+ * The handler reads `{ token, cvcSession, billing }` from the JSON request body,
+ * resolves the amount and plan configuration via your `options` callbacks (which
+ * must source data from your own database — never from the request body), calls
+ * `ozura.createRecurringPlan()`, and returns
+ * `{ planId, transactionId, transactionAmount, nextCycleAt }` on success.
+ *
+ * @example
+ * // app/api/subscribe/route.ts  (Next.js App Router)
+ * import { Ozura, createRecurringPlanHandler } from '@ozura/elements/server';
+ *
+ * const ozura = new Ozura({ merchantId: '...', apiKey: '...', vaultKey: '...' });
+ *
+ * export const POST = createRecurringPlanHandler(ozura, {
+ *   getAmount: async (body) => {
+ *     const plan = await db.plans.findById(body.planId as string);
+ *     return plan.price;
+ *   },
+ *   getPlanConfig: async (body) => {
+ *     const plan = await db.plans.findById(body.planId as string);
+ *     return { planName: plan.name, interval: plan.interval };
+ *   },
+ * });
+ */
+export declare function createRecurringPlanHandler(ozura: Ozura, options: RecurringPlanHandlerOptions): (req: Request) => Promise<Response>;
+/**
+ * Creates a ready-to-use Express / Connect middleware for recurring subscription enrollment.
+ *
+ * Requires `express.json()` (or equivalent body-parser) to be registered before
+ * this middleware so `req.body` is available.
+ *
+ * @example
+ * // Express
+ * import express from 'express';
+ * import { Ozura, createRecurringPlanMiddleware } from '@ozura/elements/server';
+ *
+ * const app = express();
+ * const ozura = new Ozura({ merchantId: '...', apiKey: '...', vaultKey: '...' });
+ *
+ * app.use(express.json());
+ * app.post('/api/subscribe', createRecurringPlanMiddleware(ozura, {
+ *   getAmount:    async (body) => db.plans.findById(body.planId).then(p => p.price),
+ *   getPlanConfig: async (body) => db.plans.findById(body.planId).then(p => ({
+ *     planName: p.name, interval: p.interval,
+ *   })),
+ * }));
+ */
+export declare function createRecurringPlanMiddleware(ozura: Ozura, options: RecurringPlanHandlerOptions): (req: {
+    body?: unknown;
+    headers?: unknown;
+}, res: NodeLikeResponse) => Promise<void>;
 export type { BillingDetails, CardSaleResponseData, TransactionQueryPagination, TransactionType, TransactionBase, CardTransactionData, AchTransactionData, CryptoTransactionData, TransactionData, } from '../types';
 export { normalizeCardSaleError } from '../sdk/errors';

package/dist/server/index.cjs.js

@@ -427,6 +427,113 @@ class Ozura {
         // a second charge. No idempotency key is in play, so one attempt only.
         return this.post('/api/v1/cardSale', body, true, 0);
     }
+    /**
+     * Create a recurring subscription plan and execute the enrollment charge.
+     *
+     * The customer's card is charged immediately for the first billing cycle
+     * (at `initialAmount` if set, otherwise `amount`) and a subscription record
+     * is created in Ozura's billing engine for all future cycles.
+     *
+     * `transactionInitiationType` is always `"cit"` for enrollment — the Pay API
+     * enforces this. Subsequent MIT charges are processed automatically by Ozura's
+     * recurring queue worker; merchants do not need to trigger them.
+     *
+     * Rate limit: 100 requests/minute per merchant.
+     *
+     * @example
+     * const plan = await ozura.createRecurringPlan({
+     *   token:       tokenResponse.token,
+     *   cvcSession:  tokenResponse.cvcSession,
+     *   amount:      '19.99',
+     *   billing:     tokenResponse.billing,
+     *   clientIpAddress: req.ip,
+     *   planName:    'Pro Monthly',
+     *   interval:    'monthly',
+     * });
+     * console.log(plan.planId, plan.transactionId);
+     */
+    async createRecurringPlan(input) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+        if (!this.merchantId)
+            throw new OzuraError('merchantId is required for createRecurringPlan(). Add it to the Ozura constructor config.', 0);
+        if (!this.apiKey)
+            throw new OzuraError('apiKey is required for createRecurringPlan(). Add it to the Ozura constructor config.', 0);
+        this.log('createRecurringPlan', { merchantId: this.merchantId, planName: input.planName, interval: input.interval, amount: input.amount });
+        const billing = input.billing;
+        // Build the Pay API body with required fields.
+        // transactionInitiationType is hardcoded to 'cit' — the Pay API rejects any
+        // other value for recurring plan creation (400 with explicit error message).
+        const body = {
+            merchantId: this.merchantId,
+            amount: input.amount,
+            currency: input.currency || 'USD',
+            transactionInitiationType: 'cit',
+            transactionChannel: (_a = input.transactionChannel) !== null && _a !== void 0 ? _a : 'ecommerce',
+            ozuraVaultToken: input.token,
+            ozuraCvcSession: input.cvcSession,
+            planName: input.planName,
+            interval: input.interval,
+            billingFirstName: billing.firstName,
+            billingLastName: billing.lastName,
+            clientIpAddress: input.clientIpAddress,
+            salesTaxExempt: (_b = input.salesTaxExempt) !== null && _b !== void 0 ? _b : false,
+            surchargePercent: (_c = input.surchargePercent) !== null && _c !== void 0 ? _c : '0.00',
+        };
+        // Billing — recurring plans require all address fields (stricter than cardSale).
+        if (billing.email)
+            body.billingEmail = billing.email;
+        if (billing.phone)
+            body.billingPhone = billing.phone;
+        if ((_d = billing.address) === null || _d === void 0 ? void 0 : _d.line1)
+            body.billingAddress1 = billing.address.line1;
+        if ((_e = billing.address) === null || _e === void 0 ? void 0 : _e.line2)
+            body.billingAddress2 = billing.address.line2;
+        if ((_f = billing.address) === null || _f === void 0 ? void 0 : _f.city)
+            body.billingCity = billing.address.city;
+        if ((_g = billing.address) === null || _g === void 0 ? void 0 : _g.state)
+            body.billingState = billing.address.state;
+        if ((_h = billing.address) === null || _h === void 0 ? void 0 : _h.zip)
+            body.billingZipcode = billing.address.zip;
+        body.billingCountry = ((_j = billing.address) === null || _j === void 0 ? void 0 : _j.country) || 'US';
+        // Optional recurring-specific fields — omit rather than send empty/null.
+        if (input.processor)
+            body.processor = input.processor;
+        if (input.planDescription)
+            body.planDescription = input.planDescription;
+        if (input.initialAmount != null)
+            body.initialAmount = input.initialAmount;
+        if (input.initialCycles != null)
+            body.initialCycles = input.initialCycles;
+        if (input.setupFee != null)
+            body.setupFee = input.setupFee;
+        if (input.intervalCount != null)
+            body.intervalCount = input.intervalCount;
+        if (input.endDate)
+            body.endDate = input.endDate;
+        if (input.maxCycles != null)
+            body.maxCycles = input.maxCycles;
+        if (input.maxAttempts != null)
+            body.maxAttempts = input.maxAttempts;
+        if (input.retryIntervalHours != null)
+            body.retryIntervalHours = input.retryIntervalHours;
+        if (input.merchantRecurringReference)
+            body.merchantRecurringReference = input.merchantRecurringReference;
+        // maxRetries: 0 — same reasoning as cardSale. The Pay API creates a subscription
+        // record on every successful request; retrying a 5xx would risk a duplicate plan.
+        const raw = await this.post('/api/v1/recurring/plans', body, true, 0);
+        // Guard against a malformed success response — a missing planId means the
+        // subscription cannot be managed, and a missing citTransactionId means the
+        // enrollment charge cannot be traced. Both are required by the Pay API contract.
+        if (!raw.planId) {
+            throw new OzuraError('createRecurringPlan: API response missing planId', 0, JSON.stringify(raw));
+        }
+        if (!raw.citTransactionId) {
+            throw new OzuraError('createRecurringPlan: API response missing citTransactionId', 0, JSON.stringify(raw));
+        }
+        // Map Pay API's 'citTransactionId' / 'citTransactionAmount' to the SDK-consistent
+        // 'transactionId' / 'transactionAmount' names that mirror cardSale's response shape.
+        return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ planId: String(raw.planId), planName: String((_k = raw.planName) !== null && _k !== void 0 ? _k : input.planName), amount: String((_l = raw.amount) !== null && _l !== void 0 ? _l : input.amount), currency: String((_o = (_m = raw.currency) !== null && _m !== void 0 ? _m : input.currency) !== null && _o !== void 0 ? _o : 'USD'), transactionId: String(raw.citTransactionId), transactionAmount: String((_p = raw.citTransactionAmount) !== null && _p !== void 0 ? _p : ''), nextCycleAt: String((_q = raw.nextCycleAt) !== null && _q !== void 0 ? _q : '') }, (raw.planDescription != null ? { planDescription: String(raw.planDescription) } : {})), (raw.merchantRecurringReference != null ? { merchantRecurringReference: String(raw.merchantRecurringReference) } : {})), (raw.citTransactionSurchargeAmount != null ? { transactionSurchargeAmount: String(raw.citTransactionSurchargeAmount) } : {})), (raw.citTransactionSalesTaxAmount != null ? { transactionSalesTaxAmount: String(raw.citTransactionSalesTaxAmount) } : {})), (raw.endDate != null ? { endDate: String(raw.endDate) } : {})), (raw.cardLastFour != null ? { cardLastFour: String(raw.cardLastFour) } : {})), (raw.cardBrand != null ? { cardBrand: String(raw.cardBrand) } : {})), (raw.cardExpMonth != null ? { cardExpMonth: String(raw.cardExpMonth) } : {})), (raw.cardExpYear != null ? { cardExpYear: String(raw.cardExpYear) } : {})), (raw.transDate != null ? { transDate: String(raw.transDate) } : {}));
+    }
     /**
      * List transactions by date range with pagination.
      *
@@ -733,13 +840,17 @@ async function readJsonBody(req) {
     if (raw.length > MAX_BODY_BYTES) {
         return { ok: false, response: Response.json({ error: 'Request body too large' }, { status: 413 }) };
     }
+    let parsed;
     try {
-        const body = JSON.parse(raw);
-        return { ok: true, body };
+        parsed = JSON.parse(raw);
     }
     catch (_b) {
         return { ok: false, response: Response.json({ error: 'Invalid JSON body' }, { status: 400 }) };
     }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, response: Response.json({ error: 'Request body must be a JSON object' }, { status: 400 }) };
+    }
+    return { ok: true, body: parsed };
 }
 /**
  * Creates a ready-to-use Fetch API route handler for payment session creation.
@@ -1188,6 +1299,205 @@ function createCardSaleMiddleware(ozura, options) {
         res.json(outcome.data);
     };
 }
+/**
+ * Validates the token/cvcSession/billing fields from a parsed request body.
+ */
+function parseRecurringPlanBody(body) {
+    const { token, cvcSession, billing } = body;
+    if (typeof token !== 'string' || !token) {
+        return { ok: false, error: 'token is required' };
+    }
+    if (typeof cvcSession !== 'string' || !cvcSession) {
+        return { ok: false, error: 'cvcSession is required' };
+    }
+    if (!billing || typeof billing.firstName !== 'string' || typeof billing.lastName !== 'string') {
+        return { ok: false, error: 'billing with firstName and lastName is required' };
+    }
+    const billingValidation = validateBilling(billing);
+    if (!billingValidation.valid) {
+        return { ok: false, error: `Invalid billing details: ${billingValidation.errors.join('; ')}` };
+    }
+    return { ok: true, token, cvcSession, billing: billingValidation.normalized };
+}
+/**
+ * Resolves amount, currency, and plan config then calls ozura.createRecurringPlan().
+ * Both the handler and middleware factories delegate to this shared implementation.
+ */
+async function executeRecurringPlan(ozura, options, token, cvcSession, billing, rawBody, clientIpAddress) {
+    let amount;
+    try {
+        amount = await options.getAmount(rawBody);
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : 'Failed to resolve amount', status: 500 };
+    }
+    if (typeof amount !== 'string' || !amount.trim()) {
+        return { ok: false, error: 'getAmount must return a non-empty decimal string', status: 500 };
+    }
+    if (!/^\d+(\.\d{1,2})?$/.test(amount.trim())) {
+        return {
+            ok: false,
+            error: `getAmount returned an invalid amount: "${amount}". Expected a positive decimal string, e.g. "19.99".`,
+            status: 500,
+        };
+    }
+    amount = amount.trim();
+    // Reject a zero base amount — a $0 recurring plan would charge nothing on every
+    // future cycle. Free trials should use initialAmount:"0.00" + initialCycles, not
+    // a zero base amount. A zero here almost always means a misconfigured getAmount().
+    if (parseFloat(amount) === 0) {
+        return {
+            ok: false,
+            error: 'getAmount returned "0" for a recurring plan base amount. For free trials use initialAmount + initialCycles in getPlanConfig.',
+            status: 500,
+        };
+    }
+    let currency = 'USD';
+    if (options.getCurrency) {
+        try {
+            currency = await options.getCurrency(rawBody);
+        }
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err.message : 'Failed to resolve currency', status: 500 };
+        }
+    }
+    let planConfig;
+    try {
+        planConfig = await options.getPlanConfig(rawBody);
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : 'Failed to resolve plan config', status: 500 };
+    }
+    if (!(planConfig === null || planConfig === void 0 ? void 0 : planConfig.planName) || !(planConfig === null || planConfig === void 0 ? void 0 : planConfig.interval)) {
+        return { ok: false, error: 'getPlanConfig must return an object with planName and interval', status: 500 };
+    }
+    try {
+        const result = await ozura.createRecurringPlan(Object.assign({ token, cvcSession, amount, currency, billing, clientIpAddress }, planConfig));
+        return {
+            ok: true,
+            data: Object.assign(Object.assign({ planId: result.planId, transactionId: result.transactionId, transactionAmount: result.transactionAmount, nextCycleAt: result.nextCycleAt }, (result.cardLastFour ? { cardLastFour: result.cardLastFour } : {})), (result.cardBrand ? { cardBrand: result.cardBrand } : {})),
+        };
+    }
+    catch (err) {
+        if (err instanceof OzuraError) {
+            if (err.statusCode === 429) {
+                return { ok: false, error: normalizeCardSaleError(err.message), status: 429, retryAfter: err.retryAfter };
+            }
+            const status = err.statusCode >= 400 && err.statusCode < 600 ? err.statusCode : 502;
+            return { ok: false, error: normalizeCardSaleError(err.message), status };
+        }
+        return { ok: false, error: 'Recurring plan creation failed', status: 500 };
+    }
+}
+/**
+ * Creates a ready-to-use Fetch API route handler for recurring subscription enrollment.
+ *
+ * Drop-in for Next.js App Router, Cloudflare Workers, Vercel Edge, and any runtime
+ * built on the standard Web API `Request` / `Response`.
+ *
+ * The handler reads `{ token, cvcSession, billing }` from the JSON request body,
+ * resolves the amount and plan configuration via your `options` callbacks (which
+ * must source data from your own database — never from the request body), calls
+ * `ozura.createRecurringPlan()`, and returns
+ * `{ planId, transactionId, transactionAmount, nextCycleAt }` on success.
+ *
+ * @example
+ * // app/api/subscribe/route.ts  (Next.js App Router)
+ * import { Ozura, createRecurringPlanHandler } from '@ozura/elements/server';
+ *
+ * const ozura = new Ozura({ merchantId: '...', apiKey: '...', vaultKey: '...' });
+ *
+ * export const POST = createRecurringPlanHandler(ozura, {
+ *   getAmount: async (body) => {
+ *     const plan = await db.plans.findById(body.planId as string);
+ *     return plan.price;
+ *   },
+ *   getPlanConfig: async (body) => {
+ *     const plan = await db.plans.findById(body.planId as string);
+ *     return { planName: plan.name, interval: plan.interval };
+ *   },
+ * });
+ */
+function createRecurringPlanHandler(ozura, options) {
+    return async (req) => {
+        var _a;
+        if (req.method !== 'POST') {
+            return Response.json({ error: 'Method Not Allowed' }, { status: 405 });
+        }
+        const contentType = (_a = req.headers.get('content-type')) !== null && _a !== void 0 ? _a : '';
+        if (!contentType.includes('application/json')) {
+            return Response.json({ error: 'Content-Type must be application/json' }, { status: 415 });
+        }
+        const bodyResult = await readJsonBody(req);
+        if (!bodyResult.ok)
+            return bodyResult.response;
+        const body = bodyResult.body;
+        const parsed = parseRecurringPlanBody(body);
+        if (!parsed.ok) {
+            return Response.json({ error: parsed.error }, { status: 400 });
+        }
+        const outcome = await executeRecurringPlan(ozura, options, parsed.token, parsed.cvcSession, parsed.billing, body, getClientIp(req));
+        if (!outcome.ok) {
+            const headers = outcome.retryAfter
+                ? { 'Retry-After': String(outcome.retryAfter) }
+                : {};
+            return Response.json({ error: outcome.error }, Object.assign({ status: outcome.status }, (Object.keys(headers).length > 0 ? { headers } : {})));
+        }
+        return Response.json(outcome.data);
+    };
+}
+/**
+ * Creates a ready-to-use Express / Connect middleware for recurring subscription enrollment.
+ *
+ * Requires `express.json()` (or equivalent body-parser) to be registered before
+ * this middleware so `req.body` is available.
+ *
+ * @example
+ * // Express
+ * import express from 'express';
+ * import { Ozura, createRecurringPlanMiddleware } from '@ozura/elements/server';
+ *
+ * const app = express();
+ * const ozura = new Ozura({ merchantId: '...', apiKey: '...', vaultKey: '...' });
+ *
+ * app.use(express.json());
+ * app.post('/api/subscribe', createRecurringPlanMiddleware(ozura, {
+ *   getAmount:    async (body) => db.plans.findById(body.planId).then(p => p.price),
+ *   getPlanConfig: async (body) => db.plans.findById(body.planId).then(p => ({
+ *     planName: p.name, interval: p.interval,
+ *   })),
+ * }));
+ */
+function createRecurringPlanMiddleware(ozura, options) {
+    return async (req, res) => {
+        var _a, _b, _c;
+        const method = req.method;
+        if (method && method !== 'POST') {
+            res.status(405).json({ error: 'Method Not Allowed' });
+            return;
+        }
+        const headers = req.headers;
+        const ct = (_a = (typeof (headers === null || headers === void 0 ? void 0 : headers['content-type']) === 'string' ? headers['content-type'] : '')) !== null && _a !== void 0 ? _a : '';
+        if (!ct.includes('application/json')) {
+            res.status(415).json({ error: 'Content-Type must be application/json' });
+            return;
+        }
+        const body = ((_b = req.body) !== null && _b !== void 0 ? _b : {});
+        const parsed = parseRecurringPlanBody(body);
+        if (!parsed.ok) {
+            res.status(400).json({ error: parsed.error });
+            return;
+        }
+        const outcome = await executeRecurringPlan(ozura, options, parsed.token, parsed.cvcSession, parsed.billing, body, getClientIp(req));
+        if (!outcome.ok) {
+            if (outcome.retryAfter)
+                (_c = res.setHeader) === null || _c === void 0 ? void 0 : _c.call(res, 'Retry-After', String(outcome.retryAfter));
+            res.status(outcome.status).json({ error: outcome.error });
+            return;
+        }
+        res.json(outcome.data);
+    };
+}
 
 exports.Ozura = Ozura;
 exports.OzuraError = OzuraError;
@@ -1195,6 +1505,8 @@ exports.createCardSaleHandler = createCardSaleHandler;
 exports.createCardSaleMiddleware = createCardSaleMiddleware;
 exports.createMintWaxHandler = createMintWaxHandler;
 exports.createMintWaxMiddleware = createMintWaxMiddleware;
+exports.createRecurringPlanHandler = createRecurringPlanHandler;
+exports.createRecurringPlanMiddleware = createRecurringPlanMiddleware;
 exports.createSessionHandler = createSessionHandler;
 exports.createSessionMiddleware = createSessionMiddleware;
 exports.getClientIp = getClientIp;