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

package/dist/types/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ozura/elements",
-  "version": "1.2.4-next.48",
+  "version": "1.2.4-next.50",
   "description": "PCI-compliant card tokenization SDK for the Ozura Vault — collect card data in iframe-isolated fields and tokenize without PCI scope",
   "main": "dist/oz-elements.umd.js",
   "module": "dist/oz-elements.esm.js",