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

package/dist/esm/integrations/controllers/provision-users.mjs

@@ -0,0 +1,126 @@
+/**
+ * Provisioning helpers for Paid SDK
+ * Orchestrates customer + contact + order creation in one operation
+ */
+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());
+    });
+};
+import { createCustomerWithDefaults } from "./customers.mjs";
+import { createContactWithDefaults } from "./contacts.mjs";
+import { createOrderWithDefaults } from "./orders.mjs";
+import { createHandler } from "../utils/base-handler.mjs";
+/**
+ * Provision a new user with customer, contact, and optionally order
+ *
+ * This is a high-level helper that orchestrates the creation of all
+ * necessary Paid entities for a new user in one operation.
+ *
+ * @param client - PaidClient instance
+ * @param config - Provisioning configuration
+ * @returns Result with created customer, contact, and optional order
+ *
+ * @example
+ * ```typescript
+ * const result = await provisionNewUser(client, {
+ *   customer: {
+ *     externalId: 'user-123',
+ *     email: 'user@example.com'
+ *   },
+ *   agentExternalId: 'agent-prod'
+ * });
+ * // Creates customer, contact, and order with defaults
+ * ```
+ */
+export function provisionNewUser(client, config) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e, _f;
+        const customer = yield createCustomerWithDefaults(client, config.customer);
+        const contactData = {
+            customerExternalId: config.customer.externalId,
+            email: ((_a = config.contact) === null || _a === void 0 ? void 0 : _a.email) || config.customer.email,
+            firstName: (_b = config.contact) === null || _b === void 0 ? void 0 : _b.firstName,
+            lastName: (_c = config.contact) === null || _c === void 0 ? void 0 : _c.lastName,
+            phone: (_d = config.contact) === null || _d === void 0 ? void 0 : _d.phone,
+            billingAddress: (_e = config.contact) === null || _e === void 0 ? void 0 : _e.billingAddress,
+            salutation: (_f = config.contact) === null || _f === void 0 ? void 0 : _f.salutation,
+        };
+        const contact = yield createContactWithDefaults(client, contactData);
+        let order;
+        if (config.agentExternalId) {
+            order = yield createOrderWithDefaults(client, {
+                customerId: customer.id,
+                customerExternalId: config.customer.externalId,
+                agentExternalId: config.agentExternalId,
+                billingContactId: contact.id,
+            }, config.orderOptions);
+        }
+        return {
+            customer,
+            contact,
+            order,
+        };
+    });
+}
+/**
+ * Create a framework-agnostic handler for user provisioning
+ *
+ * This handler can be used with any framework adapter.
+ * Accepts partial provisioning configuration and fills in defaults for missing fields.
+ *
+ * @param orderOptions - Optional default order creation options
+ * @param defaultAgentExternalId - Optional default agent external ID
+ * @returns Handler function
+ *
+ * @example
+ * ```typescript
+ * // Minimal - just externalId and email
+ * {
+ *   customer: { externalId: 'org-123', email: 'user@example.com' }
+ * }
+ *
+ * // With full customer data
+ * {
+ *   customer: {
+ *     externalId: 'org-123',
+ *     email: 'user@example.com',
+ *     name: 'Acme Corp',
+ *     billingAddress: { line1: '123 Main St', city: 'NYC', ... }
+ *   },
+ *   contact: {
+ *     firstName: 'John',
+ *     lastName: 'Doe'
+ *   }
+ * }
+ * ```
+ */
+export function createProvisioningHandler(orderOptions, defaultAgentExternalId) {
+    return createHandler((client, body) => __awaiter(this, void 0, void 0, function* () {
+        if (!body.customer) {
+            return {
+                success: false,
+                error: "'customer' is required",
+                status: 400,
+            };
+        }
+        const effectiveAgentId = body.agentExternalId ||
+            defaultAgentExternalId ||
+            process.env.NEXT_PUBLIC_PAID_AGENT_ID ||
+            process.env.PAID_AGENT_ID;
+        const result = yield provisionNewUser(client, {
+            customer: body.customer,
+            contact: body.contact,
+            agentExternalId: effectiveAgentId,
+            orderOptions: body.orderOptions || orderOptions,
+        });
+        return {
+            success: true,
+            data: result,
+        };
+    }), { requiredFields: [] });
+}

package/dist/esm/integrations/index.d.mts

@@ -0,0 +1,29 @@
+/**
+ * Paid SDK Integrations
+ *
+ * This module provides simplified helpers for common Paid operations
+ * with defaults and reduced boilerplate.
+ *
+ * @module integrations
+ *
+ * @example
+ * ```typescript
+ * import { PaidClient } from '@paid-ai/paid-node';
+ * import { createCustomerWithDefaults, createOrderWithDefaults } from '@paid-ai/paid-node/integrations';
+ *
+ * const client = new PaidClient({ token: 'pk_xxx' });
+ *
+ * const customer = await createCustomerWithDefaults(client, {
+ *   externalId: 'user-123',
+ *   email: 'user@example.com'
+ * });
+ *
+ * const order = await createOrderWithDefaults(client, {
+ *   customerId: customer.id,
+ *   customerExternalId: 'user-123',
+ *   agentExternalId: 'agent-prod'
+ * });
+ * ```
+ */
+export * from "./controllers/index.mjs";
+export type { Address, CustomerData, CompleteCustomerData, ContactData, OrderConfig, CompleteOrderConfig, OrderLineConfig, OrderOptions as HelperOptions, CustomerCreationResult, ContactCreationResult, OrderCreationResult, ProvisioningConfig, ProvisioningResult, } from "./types.mjs";

package/dist/esm/integrations/index.mjs

@@ -0,0 +1,28 @@
+/**
+ * Paid SDK Integrations
+ *
+ * This module provides simplified helpers for common Paid operations
+ * with defaults and reduced boilerplate.
+ *
+ * @module integrations
+ *
+ * @example
+ * ```typescript
+ * import { PaidClient } from '@paid-ai/paid-node';
+ * import { createCustomerWithDefaults, createOrderWithDefaults } from '@paid-ai/paid-node/integrations';
+ *
+ * const client = new PaidClient({ token: 'pk_xxx' });
+ *
+ * const customer = await createCustomerWithDefaults(client, {
+ *   externalId: 'user-123',
+ *   email: 'user@example.com'
+ * });
+ *
+ * const order = await createOrderWithDefaults(client, {
+ *   customerId: customer.id,
+ *   customerExternalId: 'user-123',
+ *   agentExternalId: 'agent-prod'
+ * });
+ * ```
+ */
+export * from "./controllers/index.mjs";

package/dist/esm/integrations/types.d.mts

@@ -0,0 +1,119 @@
+export interface Address {
+    line1?: string;
+    line2?: string;
+    city?: string;
+    state?: string;
+    zipCode?: string;
+    country?: string;
+}
+export interface CustomerData {
+    externalId: string;
+    email?: string;
+    name?: string;
+    firstName?: string;
+    lastName?: string;
+    company?: string;
+    phone?: string;
+    billingAddress?: Address;
+    metadata?: Record<string, any>;
+}
+export interface CompleteCustomerData {
+    externalId: string;
+    email: string;
+    name: string;
+    firstName: string;
+    lastName: string;
+    company: string;
+    phone: string;
+    billingAddress: Required<Address>;
+    metadata: Record<string, any>;
+}
+export interface ContactData {
+    customerExternalId: string;
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    billingAddress?: Address;
+    salutation?: "Mr" | "Mrs" | "Ms" | "Dr" | "Prof";
+}
+export interface OrderConfig {
+    customerId: string;
+    customerExternalId: string;
+    billingContactId?: string;
+    agentExternalId: string;
+    name?: string;
+    description?: string;
+    startDate?: string;
+    endDate?: string;
+    currency?: string;
+    orderLines?: OrderLineConfig[];
+}
+export interface OrderLineConfig {
+    agentExternalId: string;
+    name?: string;
+    description?: string;
+}
+/**
+ * Note: orderLines is not required because if agentExternalId is provided,
+ * order lines can be derived from that agent.
+ */
+export interface CompleteOrderConfig {
+    customerId: string;
+    customerExternalId: string;
+    billingContactId?: string;
+    agentExternalId: string;
+    name: string;
+    description: string;
+    startDate: string;
+    endDate: string;
+    currency: string;
+    orderLines: OrderLineConfig[];
+}
+export interface OrderOptions {
+    /**
+     * Whether to auto-activate orders after creation
+     * @default true
+     */
+    autoActivate?: boolean;
+    /**
+     * Duration in days for order end date (if not specified)
+     * @default 365
+     */
+    defaultDurationDays?: number;
+}
+export interface CustomerCreationResult {
+    id: string;
+    externalId: string;
+}
+export interface ContactCreationResult {
+    id: string;
+}
+export interface OrderCreationResult {
+    id: string;
+    creationState?: string;
+}
+export interface ProvisioningConfig {
+    /**
+     * Customer data (externalId required)
+     */
+    customer: CustomerData;
+    /**
+     * Contact data (optional, will use customer email if not provided)
+     */
+    contact?: Partial<ContactData>;
+    /**
+     * Agent external ID for order creation (optional)
+     * If not provided, no order will be created
+     */
+    agentExternalId?: string;
+    /**
+     * Options for order creation
+     */
+    orderOptions?: OrderOptions;
+}
+export interface ProvisioningResult {
+    customer: CustomerCreationResult;
+    contact: ContactCreationResult;
+    order?: OrderCreationResult;
+}

package/dist/esm/integrations/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/esm/integrations/utils/api-fetch.d.mts

@@ -0,0 +1,18 @@
+export interface PaidApiConfig {
+    apiUrl: string;
+    apiKey: string;
+    organizationId: string;
+}
+/**
+ * Make a direct API call to ap-signals
+ *
+ * @param config - API configuration with organization context
+ * @param endpoint - API endpoint path (will be appended to apiUrl)
+ * @param options - Fetch options (method, body)
+ * @returns Parsed JSON response
+ * @throws Error if request fails
+ */
+export declare function paidApiFetch<T = any>(config: PaidApiConfig, endpoint: string, options?: {
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    body?: any;
+}): Promise<T>;

package/dist/esm/integrations/utils/api-fetch.mjs

@@ -0,0 +1,50 @@
+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());
+    });
+};
+/**
+ * Make a direct API call to ap-signals
+ *
+ * @param config - API configuration with organization context
+ * @param endpoint - API endpoint path (will be appended to apiUrl)
+ * @param options - Fetch options (method, body)
+ * @returns Parsed JSON response
+ * @throws Error if request fails
+ */
+export function paidApiFetch(config, endpoint, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!config.organizationId) {
+            throw new Error("organizationId is required");
+        }
+        if (!config.apiKey) {
+            throw new Error("apiKey is required");
+        }
+        if (!config.apiUrl) {
+            throw new Error("apiUrl is required");
+        }
+        try {
+            const response = yield fetch(`${config.apiUrl}${endpoint}`, {
+                method: (options === null || options === void 0 ? void 0 : options.method) || "GET",
+                headers: {
+                    Authorization: `Bearer ${config.apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: (options === null || options === void 0 ? void 0 : options.body) ? JSON.stringify(options.body) : undefined,
+            });
+            if (!response.ok) {
+                const errorText = yield response.text();
+                throw new Error(`API request failed: ${errorText}`);
+            }
+            return yield response.json();
+        }
+        catch (error) {
+            console.error("Error making Paid API request:", error);
+            throw error;
+        }
+    });
+}

package/dist/esm/integrations/utils/base-handler.d.mts

@@ -0,0 +1,79 @@
+/**
+ * Framework-agnostic base handler for Paid SDK integrations
+ * Provides consistent request handling, validation, and error handling
+ */
+import type { PaidClient } from "../../Client.mjs";
+import { type PaidClientConfig } from "../client.mjs";
+export interface BaseRequestContext<TBody = any, TParams = Record<string, string>> {
+    body: TBody;
+    headers: Record<string, string>;
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    params?: TParams;
+    query?: Record<string, string>;
+}
+export interface BaseResponseContext {
+    json: (data: any, status?: number) => any;
+    error: (message: string, status: number) => any;
+}
+export interface BaseHandlerConfig extends PaidClientConfig {
+    validate?: (body: any) => Promise<void> | void;
+    transformRequest?: (body: any) => any;
+    transformResponse?: (data: any) => any;
+}
+export type HandlerFunction<TRequest, TResponse> = (client: PaidClient, request: TRequest, params?: Record<string, string>, organizationId?: string) => Promise<{
+    success: boolean;
+    data?: TResponse;
+    error?: string;
+    status?: number;
+}>;
+/**
+ * Creates a framework-agnostic handler with automatic client initialization,
+ * validation, and error handling
+ *
+ * @param handler - Business logic handler function
+ * @param options - Handler configuration options
+ * @returns Framework-agnostic handler function
+ *
+ * @example
+ * ```typescript
+ * const customersHandler = createHandler(
+ *   async (client, body) => {
+ *     const customer = await createCustomerWithDefaults(client, body);
+ *     return { success: true, data: customer };
+ *   },
+ *   { requiredFields: ['externalId'] }
+ * );
+ * ```
+ */
+export declare function createHandler<TRequest = any, TResponse = any>(handler: HandlerFunction<TRequest, TResponse>, options?: {
+    requiredFields?: (keyof TRequest)[];
+    allowedMethods?: Array<"GET" | "POST" | "PUT" | "DELETE" | "PATCH">;
+    requireOrganizationId?: boolean;
+}): (request: BaseRequestContext<TRequest>, response: BaseResponseContext, config?: BaseHandlerConfig) => Promise<any>;
+/**
+ * Helper to create a fetch-based handler for simple API calls
+ *
+ * @param endpoint - Function that generates the endpoint URL from org ID and request body
+ * @param options - Optional method, request/response transformations
+ * @returns Handler function that makes the API call
+ *
+ * @example
+ * ```typescript
+ * const activateHandler = createHandler(
+ *   createFetchHandler(
+ *     (orgId, req) => `/api/organizations/${orgId}/orders/${req.orderId}/activate-sync`,
+ *     {
+ *       method: "POST",
+ *       transformRequest: (req) => ({ confirmationToken: req.confirmationToken }),
+ *       transformResponse: (data) => ({ order: data.order, billing: data.billing })
+ *     }
+ *   ),
+ *   { requireOrganizationId: true }
+ * );
+ * ```
+ */
+export declare function createFetchHandler<TRequest, TResponse>(endpoint: (orgId: string, body: TRequest, params?: Record<string, string>) => string, options?: {
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    transformRequest?: (body: TRequest) => any;
+    transformResponse?: (data: any) => TResponse;
+}): HandlerFunction<TRequest, TResponse>;

package/dist/esm/integrations/utils/base-handler.mjs

@@ -0,0 +1,164 @@
+/**
+ * Framework-agnostic base handler for Paid SDK integrations
+ * Provides consistent request handling, validation, and error handling
+ */
+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());
+    });
+};
+import { initializePaidClient, getOrganizationId } from "../client.mjs";
+/**
+ * Creates a framework-agnostic handler with automatic client initialization,
+ * validation, and error handling
+ *
+ * @param handler - Business logic handler function
+ * @param options - Handler configuration options
+ * @returns Framework-agnostic handler function
+ *
+ * @example
+ * ```typescript
+ * const customersHandler = createHandler(
+ *   async (client, body) => {
+ *     const customer = await createCustomerWithDefaults(client, body);
+ *     return { success: true, data: customer };
+ *   },
+ *   { requiredFields: ['externalId'] }
+ * );
+ * ```
+ */
+export function createHandler(handler, options = {}) {
+    const { requiredFields = [], allowedMethods = ["POST"], requireOrganizationId = false } = options;
+    return function (request_1, response_1) {
+        return __awaiter(this, arguments, void 0, function* (request, response, config = {}) {
+            if (!allowedMethods.includes(request.method)) {
+                return response.error("Method not allowed", 405);
+            }
+            for (const field of requiredFields) {
+                if (!request.body[field]) {
+                    return response.error(`${String(field)} is required`, 400);
+                }
+            }
+            if (config.validate) {
+                try {
+                    yield config.validate(request.body);
+                }
+                catch (error) {
+                    return response.error(error instanceof Error ? error.message : "Validation failed", 400);
+                }
+            }
+            try {
+                const client = initializePaidClient(config);
+                let organizationId;
+                if (requireOrganizationId) {
+                    const orgId = yield getOrganizationId(config);
+                    if (!orgId) {
+                        return response.error("Organization not found", 500);
+                    }
+                    organizationId = orgId;
+                }
+                const requestData = config.transformRequest
+                    ? config.transformRequest(request.body)
+                    : request.body;
+                const result = yield handler(client, requestData, request.params, organizationId);
+                if (!result.success) {
+                    return response.error(result.error || "Operation failed", result.status || 500);
+                }
+                const responseData = config.transformResponse
+                    ? config.transformResponse(result.data)
+                    : { data: result.data };
+                return response.json(responseData, 200);
+            }
+            catch (error) {
+                console.error("Handler error:", error);
+                if (error instanceof TypeError && error.message.includes("fetch")) {
+                    return response.error("Network error: Unable to reach Paid API", 503);
+                }
+                return response.error(error instanceof Error ? error.message : "Internal server error", 500);
+            }
+        });
+    };
+}
+/**
+ * Helper to create a fetch-based handler for simple API calls
+ *
+ * @param endpoint - Function that generates the endpoint URL from org ID and request body
+ * @param options - Optional method, request/response transformations
+ * @returns Handler function that makes the API call
+ *
+ * @example
+ * ```typescript
+ * const activateHandler = createHandler(
+ *   createFetchHandler(
+ *     (orgId, req) => `/api/organizations/${orgId}/orders/${req.orderId}/activate-sync`,
+ *     {
+ *       method: "POST",
+ *       transformRequest: (req) => ({ confirmationToken: req.confirmationToken }),
+ *       transformResponse: (data) => ({ order: data.order, billing: data.billing })
+ *     }
+ *   ),
+ *   { requireOrganizationId: true }
+ * );
+ * ```
+ */
+export function createFetchHandler(endpoint, options) {
+    return (client, requestBody, params, organizationId) => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        if (!organizationId) {
+            return {
+                success: false,
+                error: "Organization ID is required for this operation",
+                status: 500,
+            };
+        }
+        try {
+            const url = endpoint(organizationId, requestBody, params);
+            const body = (options === null || options === void 0 ? void 0 : options.transformRequest)
+                ? options.transformRequest(requestBody)
+                : requestBody;
+            const baseUrl = ((_a = client._options) === null || _a === void 0 ? void 0 : _a.baseUrl) || "https://api.agentpaid.io/api/v1";
+            const apiKey = (_b = client._options) === null || _b === void 0 ? void 0 : _b.token;
+            if (!apiKey) {
+                return {
+                    success: false,
+                    error: "API key not found in client",
+                    status: 500,
+                };
+            }
+            const fetchResponse = yield fetch(`${baseUrl}${url}`, {
+                method: (options === null || options === void 0 ? void 0 : options.method) || "POST",
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: (options === null || options === void 0 ? void 0 : options.method) !== "GET" ? JSON.stringify(body) : undefined,
+            });
+            if (!fetchResponse.ok) {
+                const errorText = yield fetchResponse.text();
+                console.error("API error:", errorText);
+                return {
+                    success: false,
+                    error: `API request failed: ${errorText}`,
+                    status: fetchResponse.status,
+                };
+            }
+            const data = yield fetchResponse.json();
+            const transformedData = (options === null || options === void 0 ? void 0 : options.transformResponse)
+                ? options.transformResponse(data)
+                : data;
+            return { success: true, data: transformedData };
+        }
+        catch (error) {
+            console.error("Fetch error:", error);
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : "Unknown error",
+                status: 500,
+            };
+        }
+    });
+}

package/dist/esm/integrations/utils/create-adapter.d.mts

@@ -0,0 +1,29 @@
+/**
+ * Generic adapter factory - eliminates repetitive adapter code
+ * Works with any framework (Express, Fastify, Hono, Next.js, etc.)
+ */
+/**
+ * Creates a framework adapter for any HTTP framework
+ * Automatically extracts headers and converts request/response
+ *
+ * @param extractors - Framework-specific extraction functions
+ * @returns Adapter function that wraps core handlers
+ *
+ * @example
+ * ```typescript
+ * const nextjsAdapter = createFrameworkAdapter({
+ *   getBody: async (req) => await req.json(),
+ *   getHeaders: (req) => Object.fromEntries(req.headers),
+ *   getMethod: (req) => req.method || "GET",
+ *   sendJson: (data, status) => NextResponse.json(data, { status })
+ * });
+ * ```
+ */
+export declare function createFrameworkAdapter<TFrameworkReq = any, TFrameworkRes = any>(extractors: {
+    getBody: (req: TFrameworkReq) => any | Promise<any>;
+    getHeaders: (req: TFrameworkReq) => Record<string, string>;
+    getMethod: (req: TFrameworkReq) => string;
+    getParams?: (req: TFrameworkReq, context?: any) => Record<string, string> | Promise<Record<string, string>>;
+    getQuery?: (req: TFrameworkReq) => Record<string, string>;
+    sendJson: (data: any, status: number) => TFrameworkRes;
+}): (innerHandler: Function) => (req: TFrameworkReq, context?: any, config?: any) => Promise<any>;