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

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

@@ -0,0 +1,194 @@
+"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.createOrderWithDefaults = createOrderWithDefaults;
+exports.createOrder = createOrder;
+exports.createOrdersHandler = createOrdersHandler;
+const base_handler_js_1 = require("../utils/base-handler.js");
+/**
+ * Generate default values for missing order fields
+ */
+function generateOrderDefaults(config, options = {}) {
+    var _a;
+    const { defaultDurationDays = 365 } = options;
+    const startDate = config.startDate || new Date().toISOString().split("T")[0];
+    const endDate = config.endDate ||
+        new Date(Date.now() + defaultDurationDays * 24 * 60 * 60 * 1000)
+            .toISOString()
+            .split("T")[0];
+    const name = config.name || "Subscription Order";
+    const description = config.description || "Annual subscription";
+    const currency = config.currency || "USD";
+    const orderLines = ((_a = config.orderLines) === null || _a === void 0 ? void 0 : _a.map(line => ({
+        agentExternalId: line.agentExternalId,
+        name: line.name || name,
+        description: line.description || description,
+    }))) || [{
+            agentExternalId: config.agentExternalId,
+            name,
+            description,
+        }];
+    return {
+        customerId: config.customerId,
+        customerExternalId: config.customerExternalId,
+        billingContactId: config.billingContactId,
+        agentExternalId: config.agentExternalId,
+        name,
+        description,
+        startDate,
+        endDate,
+        currency,
+        orderLines,
+    };
+}
+/**
+ * Internal helper to create and optionally activate an order
+ */
+function createAndActivateOrder(client, config, autoActivate) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const order = yield client.orders.create({
+            customerId: config.customerId,
+            customerExternalId: config.customerExternalId,
+            billingContactId: config.billingContactId,
+            name: config.name,
+            description: config.description,
+            startDate: config.startDate,
+            endDate: config.endDate,
+            currency: config.currency,
+            orderLines: config.orderLines.map(line => {
+                const orderLine = { agentExternalId: line.agentExternalId };
+                if (line.name)
+                    orderLine.name = line.name;
+                if (line.description)
+                    orderLine.description = line.description;
+                return orderLine;
+            }),
+        });
+        if (!order.id) {
+            throw new Error("Order created but missing ID");
+        }
+        if (autoActivate && order.creationState === "draft") {
+            try {
+                yield client.orders.activate(order.id);
+                return {
+                    id: order.id,
+                    creationState: "active",
+                };
+            }
+            catch (activationError) {
+                console.error(`Error activating order ${order.id}:`, activationError instanceof Error
+                    ? activationError.message
+                    : "Unknown error");
+                return {
+                    id: order.id,
+                    creationState: order.creationState,
+                };
+            }
+        }
+        return {
+            id: order.id,
+            creationState: order.creationState,
+        };
+    });
+}
+/**
+ * Create an order with defaults for missing fields
+ *
+ * This helper generates reasonable defaults for dates, names, and other fields,
+ * making it easy to create orders for prototyping and development.
+ *
+ * @param client - PaidClient instance
+ * @param config - Order configuration (customerId, customerExternalId, agentExternalId required)
+ * @param options - Additional options for order creation
+ * @returns Created order with ID
+ *
+ * @example
+ * ```typescript
+ * const order = await createOrderWithDefaults(client, {
+ *   customerId: 'cus_123',
+ *   customerExternalId: 'user-123',
+ *   agentExternalId: 'agent-prod'
+ * });
+ * // Generates: startDate, endDate (1 year), name, description, currency (USD)
+ * ```
+ */
+function createOrderWithDefaults(client_1, config_1) {
+    return __awaiter(this, arguments, void 0, function* (client, config, options = {}) {
+        const { autoActivate = true } = options;
+        const completeConfig = generateOrderDefaults(config, options);
+        return createAndActivateOrder(client, completeConfig, autoActivate);
+    });
+}
+/**
+ * Create an order with explicit configuration (NO defaults applied)
+ *
+ * Required fields: customerId, customerExternalId, agentExternalId, name, description,
+ * startDate, endDate, currency, orderLines
+ *
+ * Use createOrderWithDefaults() if you want automatic default values for missing fields.
+ *
+ * @param client - PaidClient instance
+ * @param config - Complete order configuration with ALL required fields
+ * @param options - Additional options for order creation
+ * @returns Created order with ID
+ * @throws Error if any required fields are missing
+ *
+ * @example
+ * ```typescript
+ * const order = await createOrder(client, {
+ *   customerId: 'cus_123',
+ *   customerExternalId: 'user-123',
+ *   billingContactId: 'contact_123',
+ *   agentExternalId: 'agent-prod',
+ *   name: 'Pro Plan Subscription',
+ *   description: 'Monthly subscription to Pro plan',
+ *   startDate: '2024-01-01',
+ *   endDate: '2025-01-01',
+ *   currency: 'USD',
+ *   orderLines: [{
+ *     agentExternalId: 'agent-prod',
+ *     name: 'Pro Plan',
+ *     description: 'Pro plan features'
+ *   }]
+ * }, { autoActivate: true });
+ * ```
+ */
+function createOrder(client_1, config_1) {
+    return __awaiter(this, arguments, void 0, function* (client, config, options = {}) {
+        const { autoActivate = true } = options;
+        return createAndActivateOrder(client, config, autoActivate);
+    });
+}
+/**
+ * Create a framework-agnostic handler for order creation
+ *
+ * This handler can be used with any framework adapter.
+ *
+ * @param helperOptions - Default options for order creation
+ * @returns Handler function
+ */
+function createOrdersHandler(helperOptions) {
+    return (0, base_handler_js_1.createHandler)((client, body) => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        if (!body.customerId) {
+            throw new Error("customerId is required");
+        }
+        if (!body.customerExternalId) {
+            throw new Error("customerExternalId is required");
+        }
+        if (!body.agentExternalId) {
+            throw new Error("agentExternalId is required");
+        }
+        const orderOptions = Object.assign(Object.assign({}, helperOptions), { autoActivate: (_b = (_a = body.autoActivate) !== null && _a !== void 0 ? _a : helperOptions === null || helperOptions === void 0 ? void 0 : helperOptions.autoActivate) !== null && _b !== void 0 ? _b : true });
+        const order = yield createOrderWithDefaults(client, body, orderOptions);
+        return { success: true, data: order };
+    }), { requiredFields: ['customerId', 'customerExternalId', 'agentExternalId'] });
+}

package/dist/cjs/integrations/controllers/provision-users.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Provisioning helpers for Paid SDK
+ * Orchestrates customer + contact + order creation in one operation
+ */
+import type { PaidClient } from "../../Client.js";
+import type { OrderOptions, ProvisioningConfig, ProvisioningResult } from "../types.js";
+/**
+ * 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 declare function provisionNewUser(client: PaidClient, config: ProvisioningConfig): Promise<ProvisioningResult>;
+/**
+ * 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 declare function createProvisioningHandler(orderOptions?: OrderOptions, defaultAgentExternalId?: string): (request: import("../utils/base-handler.js").BaseRequestContext<Partial<ProvisioningConfig>, Record<string, string>>, response: import("../utils/base-handler.js").BaseResponseContext, config?: import("../utils/base-handler.js").BaseHandlerConfig) => Promise<any>;

package/dist/cjs/integrations/controllers/provision-users.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * 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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.provisionNewUser = provisionNewUser;
+exports.createProvisioningHandler = createProvisioningHandler;
+const customers_js_1 = require("./customers.js");
+const contacts_js_1 = require("./contacts.js");
+const orders_js_1 = require("./orders.js");
+const base_handler_js_1 = require("../utils/base-handler.js");
+/**
+ * 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
+ * ```
+ */
+function provisionNewUser(client, config) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e, _f;
+        const customer = yield (0, customers_js_1.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 (0, contacts_js_1.createContactWithDefaults)(client, contactData);
+        let order;
+        if (config.agentExternalId) {
+            order = yield (0, orders_js_1.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'
+ *   }
+ * }
+ * ```
+ */
+function createProvisioningHandler(orderOptions, defaultAgentExternalId) {
+    return (0, base_handler_js_1.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/cjs/integrations/index.d.ts

@@ -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.js";
+export type { Address, CustomerData, CompleteCustomerData, ContactData, OrderConfig, CompleteOrderConfig, OrderLineConfig, OrderOptions as HelperOptions, CustomerCreationResult, ContactCreationResult, OrderCreationResult, ProvisioningConfig, ProvisioningResult, } from "./types.js";

package/dist/cjs/integrations/index.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * 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'
+ * });
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./controllers/index.js"), exports);

package/dist/cjs/integrations/types.d.ts

@@ -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/cjs/integrations/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/integrations/utils/api-fetch.d.ts

@@ -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/cjs/integrations/utils/api-fetch.js

@@ -0,0 +1,53 @@
+"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.paidApiFetch = paidApiFetch;
+/**
+ * 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
+ */
+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;
+        }
+    });
+}