@paid-ai/paid-node 0.4.1 → 0.5.0-alpha2

package/dist/cjs/integrations/client.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Shared Paid client initialization utility
+ * Framework-agnostic
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializePaidClient = initializePaidClient;
+exports.getOrganizationId = getOrganizationId;
+const Client_js_1 = require("../Client.js");
+/**
+ * Initialize a Paid client with environment variable fallbacks
+ *
+ * @param config - Optional configuration overrides
+ * @returns Configured PaidClient instance
+ * @throws Error if API key is not provided or found in environment
+ *
+ * @example
+ * ```typescript
+ * const client = initializePaidClient();
+ * // Uses process.env.PAID_API_KEY
+ *
+ * const client = initializePaidClient({ apiKey: 'pk_xxx' });
+ * // Uses provided key
+ * ```
+ */
+function initializePaidClient(config = {}) {
+    const apiKey = config.apiKey || process.env.PAID_API_KEY;
+    if (!apiKey) {
+        throw new Error('PAID_API_KEY not configured. Set process.env.PAID_API_KEY or pass apiKey in config.');
+    }
+    return new Client_js_1.PaidClient({
+        token: apiKey,
+        baseUrl: config.apiUrl
+            ? `${config.apiUrl}/api/v1`
+            : process.env.PAID_API_URL
+                ? `${process.env.PAID_API_URL}/api/v1`
+                : undefined,
+    });
+}
+/**
+ * Get organization ID from API key
+ *
+ * Calls the Paid API to resolve the organization ID associated with the API key.
+ *
+ * @param config - API configuration
+ * @returns Organization ID or null if not found
+ *
+ * @example
+ * ```typescript
+ * const orgId = await getOrganizationId({
+ *   apiKey: process.env.PAID_API_KEY,
+ *   apiUrl: 'https://api.agentpaid.io'
+ * });
+ * ```
+ */
+function getOrganizationId() {
+    return __awaiter(this, arguments, void 0, function* (config = {}) {
+        var _a;
+        const apiKey = config.apiKey || process.env.PAID_API_KEY;
+        const apiUrl = config.apiUrl || process.env.PAID_API_URL || 'https://api.agentpaid.io';
+        if (!apiKey) {
+            throw new Error('PAID_API_KEY not configured');
+        }
+        try {
+            const response = yield fetch(`${apiUrl}/api/organizations/organizationId`, {
+                method: 'GET',
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+            });
+            if (!response.ok) {
+                console.error('Failed to get organization ID:', yield response.text());
+                return null;
+            }
+            const data = yield response.json();
+            return ((_a = data.data) === null || _a === void 0 ? void 0 : _a.organizationId) || null;
+        }
+        catch (error) {
+            console.error('Error fetching organization ID:', error);
+            return null;
+        }
+    });
+}

package/dist/cjs/integrations/controllers/billing.d.ts

@@ -0,0 +1,196 @@
+export interface PayInvoiceConfig {
+    apiUrl: string;
+    apiKey: string;
+    organizationId: string;
+}
+export interface PayInvoiceRequest {
+    invoiceId: string;
+    confirmationToken: string;
+    returnUrl?: string;
+}
+export interface PayInvoiceResult {
+    success: boolean;
+    data?: any;
+}
+/**
+ * Pay an invoice with a payment confirmation token
+ * This helper processes payment for an existing invoice using a Stripe confirmation token.
+ *
+ * @param config - API configuration with organization context
+ * @param request - Payment request details
+ * @returns Payment result
+ *
+ * @example
+ * ```typescript
+ * const result = await payInvoice(
+ *   {
+ *     apiUrl: 'https://api.agentpaid.io',
+ *     apiKey: process.env.PAID_API_KEY,
+ *     organizationId: 'org_123'
+ *   },
+ *   {
+ *     invoiceId: 'inv_123',
+ *     confirmationToken: 'pm_tok_xxx',
+ *     returnUrl: 'https://example.com/thanks'
+ *   }
+ * );
+ * ```
+ */
+export declare function payInvoice(config: PayInvoiceConfig, request: PayInvoiceRequest): Promise<PayInvoiceResult>;
+interface PayInvoiceRequestWithBody {
+    invoiceId?: string;
+    confirmationToken: string;
+    returnUrl?: string;
+}
+/**
+ * Create a framework-agnostic handler for invoice payment
+ *
+ * This handler can be used with any framework adapter.
+ * Organization ID is automatically fetched from the API key.
+ *
+ * @returns Handler function
+ */
+export declare function createPayInvoiceHandler(): (request: import("../utils/base-handler.js").BaseRequestContext<PayInvoiceRequestWithBody, Record<string, string>>, response: import("../utils/base-handler.js").BaseResponseContext, config?: import("../utils/base-handler.js").BaseHandlerConfig) => Promise<any>;
+export interface ActivateOrderSyncConfig {
+    apiUrl: string;
+    apiKey: string;
+    organizationId: string;
+}
+export interface ActivateOrderSyncRequest {
+    orderId: string;
+    confirmationToken: string;
+    returnUrl?: string;
+}
+export interface ActivateOrderSyncResult {
+    success: boolean;
+    order: any;
+    billing: any;
+}
+/**
+ * Activate an order synchronously with payment
+ *
+ * This operation activates an order and immediately charges the customer
+ * using the provided confirmation token (from Stripe or other payment provider).
+ *
+ * @param config - API configuration with organization context
+ * @param request - Activation request with order ID and confirmation token
+ * @returns Activation result with order and billing information
+ *
+ * @example
+ * ```typescript
+ * const result = await activateOrderSync(
+ *   {
+ *     apiUrl: 'https://api.agentpaid.io',
+ *     apiKey: process.env.PAID_API_KEY,
+ *     organizationId: 'org_123'
+ *   },
+ *   {
+ *     orderId: 'ord_123',
+ *     confirmationToken: 'pi_123_secret_456',
+ *     returnUrl: 'https://example.com/return'
+ *   }
+ * );
+ * ```
+ */
+export declare function activateOrderSync(config: ActivateOrderSyncConfig, request: ActivateOrderSyncRequest): Promise<ActivateOrderSyncResult>;
+/**
+ * Internal request body type for the handler
+ */
+interface ActivateOrderSyncRequestBody {
+    orderId?: string;
+    confirmationToken: string;
+    returnUrl?: string;
+}
+/**
+ * Create a framework-agnostic handler for synchronous order activation
+ *
+ * This handler can be used with any framework adapter.
+ *
+ * @param defaultReturnUrl - Optional default return URL
+ * @returns Handler function
+ */
+export declare function createActivateOrderSyncHandler(defaultReturnUrl?: string): (request: import("../utils/base-handler.js").BaseRequestContext<ActivateOrderSyncRequestBody, Record<string, string>>, response: import("../utils/base-handler.js").BaseResponseContext, config?: import("../utils/base-handler.js").BaseHandlerConfig) => Promise<any>;
+export interface SetupIntentRequest {
+    customerId: string;
+    confirmationToken: string;
+    returnUrl?: string;
+    metadata?: Record<string, any>;
+}
+export interface SetupIntentResponse {
+    setupIntent: {
+        id: string;
+        client_secret: string;
+        status: string;
+        usage: string;
+        customer: string;
+    };
+    message: string;
+}
+export interface SetupIntentConfig {
+    apiUrl: string;
+    apiKey: string;
+    organizationId: string;
+}
+/**
+ * Create a setup intent for adding payment methods without immediate charge
+ *
+ * Setup intents are used to save payment methods for future use without
+ * charging the customer immediately. This is useful for:
+ * - Adding payment methods for subscription billing
+ * - Updating payment methods
+ * - Pre-authorizing payment methods
+ *
+ * @param config - API configuration with organization context
+ * @param request - Setup intent request with customer ID and confirmation token
+ * @returns Setup intent result with payment method details
+ *
+ * @example
+ * ```typescript
+ * const result = await createSetupIntent(
+ *   {
+ *     apiUrl: 'https://api.agentpaid.io',
+ *     apiKey: process.env.PAID_API_KEY,
+ *     organizationId: 'org_123'
+ *   },
+ *   {
+ *     customerId: 'cus_123',
+ *     confirmationToken: 'seti_123_secret_456',
+ *     returnUrl: 'https://example.com/return',
+ *     metadata: { source: 'web' }
+ *   }
+ * );
+ * ```
+ */
+export declare function createSetupIntent(config: SetupIntentConfig, request: SetupIntentRequest): Promise<SetupIntentResponse>;
+/**
+ * Create a framework-agnostic handler for setup intent creation
+ *
+ * This handler can be used with any framework adapter.
+ *
+ * @param defaultReturnUrl - Optional default return URL
+ * @returns Handler function
+ *
+ * @example
+ * ```typescript
+ * // Next.js API route
+ * import { createSetupIntentHandler } from '@paid-ai/paid-node/integrations';
+ *
+ * const handler = createSetupIntentHandler('https://myapp.com/billing');
+ *
+ * export async function POST(req: Request) {
+ *   return handler(
+ *     {
+ *       body: await req.json(),
+ *       headers: Object.fromEntries(req.headers),
+ *       method: 'POST'
+ *     },
+ *     {
+ *       json: (data, status = 200) => Response.json(data, { status }),
+ *       error: (message, status) => Response.json({ error: message }, { status })
+ *     }
+ *   );
+ * }
+ * ```
+ */
+export declare function createSetupIntentHandler(defaultReturnUrl?: string): (request: import("../utils/base-handler.js").BaseRequestContext<SetupIntentRequest, Record<string, string>>, response: import("../utils/base-handler.js").BaseResponseContext, config?: import("../utils/base-handler.js").BaseHandlerConfig) => Promise<any>;
+export {};

package/dist/cjs/integrations/controllers/billing.js

@@ -0,0 +1,267 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.payInvoice = payInvoice;
+exports.createPayInvoiceHandler = createPayInvoiceHandler;
+exports.activateOrderSync = activateOrderSync;
+exports.createActivateOrderSyncHandler = createActivateOrderSyncHandler;
+exports.createSetupIntent = createSetupIntent;
+exports.createSetupIntentHandler = createSetupIntentHandler;
+const api_fetch_js_1 = require("../utils/api-fetch.js");
+const base_handler_js_1 = require("../utils/base-handler.js");
+/**
+ * Pay an invoice with a payment confirmation token
+ * This helper processes payment for an existing invoice using a Stripe confirmation token.
+ *
+ * @param config - API configuration with organization context
+ * @param request - Payment request details
+ * @returns Payment result
+ *
+ * @example
+ * ```typescript
+ * const result = await payInvoice(
+ *   {
+ *     apiUrl: 'https://api.agentpaid.io',
+ *     apiKey: process.env.PAID_API_KEY,
+ *     organizationId: 'org_123'
+ *   },
+ *   {
+ *     invoiceId: 'inv_123',
+ *     confirmationToken: 'pm_tok_xxx',
+ *     returnUrl: 'https://example.com/thanks'
+ *   }
+ * );
+ * ```
+ */
+function payInvoice(config, request) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { invoiceId, confirmationToken, returnUrl } = request;
+        if (!invoiceId || !confirmationToken) {
+            throw new Error("invoiceId and confirmationToken are required");
+        }
+        const data = yield (0, api_fetch_js_1.paidApiFetch)(config, `/api/organizations/${config.organizationId}/invoices/${invoiceId}/pay`, {
+            method: "PUT",
+            body: Object.assign({ confirmationToken }, (returnUrl && { returnUrl })),
+        });
+        return { success: true, data };
+    });
+}
+/**
+ * Create a framework-agnostic handler for invoice payment
+ *
+ * This handler can be used with any framework adapter.
+ * Organization ID is automatically fetched from the API key.
+ *
+ * @returns Handler function
+ */
+function createPayInvoiceHandler() {
+    return (0, base_handler_js_1.createHandler)((_client, body, params, organizationId) => __awaiter(this, void 0, void 0, function* () {
+        if (!organizationId) {
+            return { success: false, error: 'Organization ID not found', status: 500 };
+        }
+        const invoiceId = (params === null || params === void 0 ? void 0 : params.invoiceId) || body.invoiceId;
+        const { confirmationToken, returnUrl } = body;
+        if (!invoiceId) {
+            return { success: false, error: 'invoiceId is required', status: 400 };
+        }
+        if (!confirmationToken) {
+            return { success: false, error: 'confirmationToken is required', status: 400 };
+        }
+        const apiKey = process.env.PAID_API_KEY || '';
+        const apiUrl = process.env.PAID_API_URL || 'https://api.agentpaid.io';
+        const result = yield payInvoice({ apiUrl, apiKey, organizationId }, { invoiceId, confirmationToken, returnUrl });
+        return {
+            success: true,
+            data: result.data,
+        };
+    }), { requiredFields: ['confirmationToken'], requireOrganizationId: true });
+}
+/**
+ * Activate an order synchronously with payment
+ *
+ * This operation activates an order and immediately charges the customer
+ * using the provided confirmation token (from Stripe or other payment provider).
+ *
+ * @param config - API configuration with organization context
+ * @param request - Activation request with order ID and confirmation token
+ * @returns Activation result with order and billing information
+ *
+ * @example
+ * ```typescript
+ * const result = await activateOrderSync(
+ *   {
+ *     apiUrl: 'https://api.agentpaid.io',
+ *     apiKey: process.env.PAID_API_KEY,
+ *     organizationId: 'org_123'
+ *   },
+ *   {
+ *     orderId: 'ord_123',
+ *     confirmationToken: 'pi_123_secret_456',
+ *     returnUrl: 'https://example.com/return'
+ *   }
+ * );
+ * ```
+ */
+function activateOrderSync(config, request) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { orderId, confirmationToken, returnUrl } = request;
+        if (!orderId) {
+            throw new Error("orderId is required");
+        }
+        if (!confirmationToken) {
+            throw new Error("confirmationToken is required");
+        }
+        const data = yield (0, api_fetch_js_1.paidApiFetch)(config, `/api/organizations/${config.organizationId}/orders/${orderId}/activate-and-pay`, {
+            method: "POST",
+            body: Object.assign({ confirmationToken }, (returnUrl && { returnUrl })),
+        });
+        return {
+            success: true,
+            order: data.order,
+            billing: data.billing,
+        };
+    });
+}
+/**
+ * Create a framework-agnostic handler for synchronous order activation
+ *
+ * This handler can be used with any framework adapter.
+ *
+ * @param defaultReturnUrl - Optional default return URL
+ * @returns Handler function
+ */
+function createActivateOrderSyncHandler(defaultReturnUrl) {
+    return (0, base_handler_js_1.createHandler)((client, body, params, organizationId) => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const apiKey = (_a = client._options) === null || _a === void 0 ? void 0 : _a.token;
+        const baseUrl = ((_b = client._options) === null || _b === void 0 ? void 0 : _b.baseUrl) || 'https://api.agentpaid.io/api/v1';
+        const apiUrl = baseUrl.replace('/api/v1', '');
+        const orderId = (params === null || params === void 0 ? void 0 : params.orderId) || body.orderId;
+        const result = yield activateOrderSync({ apiUrl, apiKey, organizationId: organizationId }, {
+            orderId: orderId,
+            confirmationToken: body.confirmationToken,
+            returnUrl: body.returnUrl || defaultReturnUrl,
+        });
+        return {
+            success: true,
+            data: {
+                success: true,
+                order: result.order,
+                billing: result.billing,
+                message: 'Order activated and charged successfully',
+            },
+        };
+    }), {
+        requiredFields: ['confirmationToken'],
+        requireOrganizationId: true,
+    });
+}
+/**
+ * Create a setup intent for adding payment methods without immediate charge
+ *
+ * Setup intents are used to save payment methods for future use without
+ * charging the customer immediately. This is useful for:
+ * - Adding payment methods for subscription billing
+ * - Updating payment methods
+ * - Pre-authorizing payment methods
+ *
+ * @param config - API configuration with organization context
+ * @param request - Setup intent request with customer ID and confirmation token
+ * @returns Setup intent result with payment method details
+ *
+ * @example
+ * ```typescript
+ * const result = await createSetupIntent(
+ *   {
+ *     apiUrl: 'https://api.agentpaid.io',
+ *     apiKey: process.env.PAID_API_KEY,
+ *     organizationId: 'org_123'
+ *   },
+ *   {
+ *     customerId: 'cus_123',
+ *     confirmationToken: 'seti_123_secret_456',
+ *     returnUrl: 'https://example.com/return',
+ *     metadata: { source: 'web' }
+ *   }
+ * );
+ * ```
+ */
+function createSetupIntent(config, request) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { customerId, confirmationToken, returnUrl, metadata } = request;
+        if (!customerId) {
+            throw new Error("customerId is required");
+        }
+        if (!confirmationToken) {
+            throw new Error("confirmationToken is required");
+        }
+        const data = yield (0, api_fetch_js_1.paidApiFetch)(config, `/api/organizations/${config.organizationId}/payments/setup-intents-external`, {
+            method: "POST",
+            body: Object.assign(Object.assign({ customerId,
+                confirmationToken }, (returnUrl && { returnUrl })), (metadata && { metadata })),
+        });
+        return {
+            setupIntent: data.setupIntent || data,
+            message: "Setup intent created successfully",
+        };
+    });
+}
+/**
+ * Create a framework-agnostic handler for setup intent creation
+ *
+ * This handler can be used with any framework adapter.
+ *
+ * @param defaultReturnUrl - Optional default return URL
+ * @returns Handler function
+ *
+ * @example
+ * ```typescript
+ * // Next.js API route
+ * import { createSetupIntentHandler } from '@paid-ai/paid-node/integrations';
+ *
+ * const handler = createSetupIntentHandler('https://myapp.com/billing');
+ *
+ * export async function POST(req: Request) {
+ *   return handler(
+ *     {
+ *       body: await req.json(),
+ *       headers: Object.fromEntries(req.headers),
+ *       method: 'POST'
+ *     },
+ *     {
+ *       json: (data, status = 200) => Response.json(data, { status }),
+ *       error: (message, status) => Response.json({ error: message }, { status })
+ *     }
+ *   );
+ * }
+ * ```
+ */
+function createSetupIntentHandler(defaultReturnUrl) {
+    return (0, base_handler_js_1.createHandler)((client, body, _params, organizationId) => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const apiKey = (_a = client._options) === null || _a === void 0 ? void 0 : _a.token;
+        const baseUrl = ((_b = client._options) === null || _b === void 0 ? void 0 : _b.baseUrl) || 'https://api.agentpaid.io/api/v1';
+        const apiUrl = baseUrl.replace('/api/v1', '');
+        const result = yield createSetupIntent({ apiUrl, apiKey, organizationId: organizationId }, {
+            customerId: body.customerId,
+            confirmationToken: body.confirmationToken,
+            returnUrl: body.returnUrl || defaultReturnUrl,
+            metadata: body.metadata,
+        });
+        return {
+            success: true,
+            data: result,
+        };
+    }), {
+        requiredFields: ['customerId', 'confirmationToken'],
+        requireOrganizationId: true,
+    });
+}

package/dist/cjs/integrations/controllers/contacts.d.ts

@@ -0,0 +1,66 @@
+import type { PaidClient } from "../../Client.js";
+import type { ContactData, ContactCreationResult, Address } from "../types.js";
+/**
+ * Create a contact with defaults for missing fields
+ *
+ * This helper generates reasonable placeholder values for any missing data,
+ * making it easy to create contacts for prototyping and development.
+ *
+ * @param client - PaidClient instance
+ * @param data - Contact data (only customerExternalId is required)
+ * @returns Created contact with ID
+ *
+ * @example
+ * ```typescript
+ * const contact = await createContactWithDefaults(client, {
+ *   customerExternalId: 'user-123',
+ *   email: 'user@example.com'
+ * });
+ * // Generates: firstName, lastName, address, etc.
+ * ```
+ */
+export declare function createContactWithDefaults(client: PaidClient, data: ContactData): Promise<ContactCreationResult>;
+/**
+ * Create a contact with explicit data (NO defaults applied)
+ *
+ * Required fields: customerExternalId, email, firstName, lastName, phone, salutation,
+ * and complete billingAddress (line1, line2, city, state, zipCode, country)
+ *
+ * Use createContactWithDefaults() if you want automatic default values for missing fields.
+ *
+ * @param client - PaidClient instance
+ * @param data - Complete contact data with ALL required fields
+ * @returns Created contact with ID
+ * @throws Error if any required fields are missing
+ *
+ * @example
+ * ```typescript
+ * const contact = await createContact(client, {
+ *   customerExternalId: 'user-123',
+ *   email: 'john@example.com',
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   phone: '+1234567890',
+ *   salutation: 'Mr',
+ *   billingAddress: {
+ *     line1: '123 Main St',
+ *     line2: 'Suite 100',
+ *     city: 'San Francisco',
+ *     state: 'CA',
+ *     zipCode: '94105',
+ *     country: 'US'
+ *   }
+ * });
+ * ```
+ */
+export declare function createContact(client: PaidClient, data: Required<Omit<ContactData, 'billingAddress'>> & {
+    billingAddress: Required<Address>;
+}): Promise<ContactCreationResult>;
+/**
+ * Create a framework-agnostic handler for contact creation
+ *
+ * This handler can be used with any framework adapter.
+ *
+ * @returns Handler function
+ */
+export declare function createContactsHandler(): (request: import("../utils/base-handler.js").BaseRequestContext<ContactData, Record<string, string>>, response: import("../utils/base-handler.js").BaseResponseContext, config?: import("../utils/base-handler.js").BaseHandlerConfig) => Promise<any>;