@thisispamela/sdk 1.0.0

package/README.md

@@ -0,0 +1,65 @@
+# Pamela SDK for JavaScript/TypeScript
+
+Official SDK for the Pamela Voice API.
+
+## Installation
+
+```bash
+npm install @pamela/sdk
+```
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { PamelaClient } from '@pamela/sdk';
+
+const client = new PamelaClient({
+  apiKey: 'pk_live_your_api_key_here',
+  baseUrl: 'https://api.thisispamela.com', // Optional
+});
+
+// Create a call
+const call = await client.createCall({
+  to: '+1234567890',
+  task: 'Order a large pizza for delivery',
+  locale: 'en-US',
+});
+
+console.log('Call created:', call.id);
+
+// Get call status
+const status = await client.getCall(call.id);
+console.log('Call status:', status.status);
+```
+
+### Webhook Verification
+
+```typescript
+import { PamelaClient } from '@pamela/b2b-sdk';
+import express from 'express';
+
+const app = express();
+const WEBHOOK_SECRET = 'your_webhook_secret';
+
+app.post('/webhooks/pamela', express.json(), (req, res) => {
+  const signature = req.headers['x-pamela-signature'] as string;
+  const payload = req.body;
+
+  if (!PamelaClient.verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
+    return res.status(401).send('Invalid signature');
+  }
+
+  // Handle webhook event
+  console.log('Webhook event:', payload.event);
+  console.log('Call ID:', payload.call_id);
+
+  res.status(200).send('OK');
+});
+```
+
+## API Reference
+
+See the [Pamela B2B API Documentation](https://docs.thisispamela.com/b2b) for full API reference.
+

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Pamela B2B Voice API SDK for JavaScript/TypeScript
+ */
+export interface PamelaClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+export interface CreateCallRequest {
+    to: string;
+    country?: string;
+    locale?: string;
+    task: string;
+    instructions?: string;
+    end_user_id?: string;
+    metadata?: Record<string, any>;
+    tools?: Array<Record<string, any>>;
+    webhooks?: {
+        webhook_url?: string;
+        tool_webhook_url?: string;
+    };
+}
+export interface CallResponse {
+    id: string;
+    status: string;
+    call_session_id: string;
+    created_at: string;
+}
+export interface CallStatus {
+    id: string;
+    status: string;
+    to: string;
+    from_: string;
+    country: string;
+    created_at: string;
+    started_at?: string;
+    completed_at?: string;
+    duration_seconds?: number;
+    transcript?: Array<Record<string, any>>;
+    summary?: string;
+    metadata: Record<string, any>;
+    end_user_id?: string;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    input_schema: Record<string, any>;
+    output_schema?: Record<string, any>;
+    timeout_ms?: number;
+}
+export interface WebhookPayload {
+    event: string;
+    call_id: string;
+    call_session_id: string;
+    timestamp: string;
+    data: Record<string, any>;
+}
+export declare class PamelaClient {
+    private client;
+    private apiKey;
+    constructor(config: PamelaClientConfig);
+    /**
+     * Create a new call.
+     */
+    createCall(request: CreateCallRequest): Promise<CallResponse>;
+    /**
+     * Get call status and details.
+     */
+    getCall(callId: string): Promise<CallStatus>;
+    /**
+     * List calls for the authenticated partner/project.
+     */
+    listCalls(params?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+        start_date?: string;
+        end_date?: string;
+    }): Promise<{
+        items: CallStatus[];
+        total: number;
+        limit: number;
+        offset: number;
+    }>;
+    /**
+     * Cancel an in-progress call.
+     */
+    cancelCall(callId: string): Promise<{
+        success: boolean;
+        call_id: string;
+        status: string;
+    }>;
+    /**
+     * Register a tool.
+     */
+    registerTool(tool: ToolDefinition): Promise<{
+        id: string;
+        project_id: string;
+        name: string;
+        description: string;
+        input_schema: Record<string, any>;
+        output_schema: Record<string, any>;
+        timeout_ms: number;
+        created_at: string;
+    }>;
+    /**
+     * List all tools for the project.
+     */
+    listTools(): Promise<Array<{
+        id: string;
+        project_id: string;
+        name: string;
+        description: string;
+        input_schema: Record<string, any>;
+        output_schema: Record<string, any>;
+        timeout_ms: number;
+        created_at: string;
+    }>>;
+    /**
+     * Delete a tool.
+     */
+    deleteTool(toolId: string): Promise<{
+        success: boolean;
+        tool_id: string;
+    }>;
+    /**
+     * Verify webhook signature.
+     */
+    static verifyWebhookSignature(payload: string | object, signature: string, secret: string): boolean;
+}
+export default PamelaClient;

package/dist/index.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Pamela B2B Voice API SDK for JavaScript/TypeScript
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PamelaClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+const crypto = __importStar(require("crypto"));
+class PamelaClient {
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        const baseURL = config.baseUrl || 'https://api.thisispamela.com';
+        this.client = axios_1.default.create({
+            baseURL: `${baseURL}/api/b2b/v1`,
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            timeout: 30000,
+        });
+        // Add retry logic
+        this.client.interceptors.response.use((response) => response, async (error) => {
+            const config = error.config;
+            if (!config || !config.retry) {
+                config.retry = 0;
+            }
+            config.retry += 1;
+            if (config.retry <= 3 && error.response?.status && error.response.status >= 500) {
+                await new Promise(resolve => setTimeout(resolve, 1000 * config.retry));
+                return this.client.request(config);
+            }
+            return Promise.reject(error);
+        });
+    }
+    /**
+     * Create a new call.
+     */
+    async createCall(request) {
+        const response = await this.client.post('/calls', request);
+        return response.data;
+    }
+    /**
+     * Get call status and details.
+     */
+    async getCall(callId) {
+        const response = await this.client.get(`/calls/${callId}`);
+        return response.data;
+    }
+    /**
+     * List calls for the authenticated partner/project.
+     */
+    async listCalls(params) {
+        const response = await this.client.get('/calls', { params });
+        // Backend returns { items: [...], total, limit, offset }
+        return response.data;
+    }
+    /**
+     * Cancel an in-progress call.
+     */
+    async cancelCall(callId) {
+        const response = await this.client.post(`/calls/${callId}/cancel`);
+        return response.data;
+    }
+    /**
+     * Register a tool.
+     */
+    async registerTool(tool) {
+        const response = await this.client.post('/tools', { tool });
+        return response.data;
+    }
+    /**
+     * List all tools for the project.
+     */
+    async listTools() {
+        const response = await this.client.get('/tools');
+        return response.data;
+    }
+    /**
+     * Delete a tool.
+     */
+    async deleteTool(toolId) {
+        const response = await this.client.delete(`/tools/${toolId}`);
+        return response.data;
+    }
+    /**
+     * Verify webhook signature.
+     */
+    static verifyWebhookSignature(payload, signature, secret) {
+        const payloadString = typeof payload === 'string' ? payload : JSON.stringify(payload);
+        const expectedSignature = crypto
+            .createHmac('sha256', secret)
+            .update(payloadString)
+            .digest('hex');
+        return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
+    }
+}
+exports.PamelaClient = PamelaClient;
+exports.default = PamelaClient;

package/jest.config.js

@@ -0,0 +1,13 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  testMatch: ['**/*.test.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+};
+

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@thisispamela/sdk",
+  "version": "1.0.0",
+  "description": "Pamela B2B Voice API SDK for JavaScript/TypeScript",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "pamela",
+    "voice",
+    "api",
+    "b2b",
+    "phone",
+    "calling"
+  ],
+  "author": "Pamela",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/jest": "^29.5.0",
+    "typescript": "^5.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,189 @@
+/**
+ * Pamela B2B Voice API SDK for JavaScript/TypeScript
+ */
+
+import axios, { AxiosInstance, AxiosError } from 'axios';
+import * as crypto from 'crypto';
+
+export interface PamelaClientConfig {
+  apiKey: string;
+  baseUrl?: string;
+}
+
+export interface CreateCallRequest {
+  to: string;
+  country?: string;
+  locale?: string;
+  task: string;
+  instructions?: string;
+  end_user_id?: string;
+  metadata?: Record<string, any>;
+  tools?: Array<Record<string, any>>;
+  webhooks?: {
+    webhook_url?: string;
+    tool_webhook_url?: string;
+  };
+}
+
+export interface CallResponse {
+  id: string;
+  status: string;
+  call_session_id: string;
+  created_at: string;
+}
+
+export interface CallStatus {
+  id: string;
+  status: string;
+  to: string;
+  from_: string;  // Backend uses from_ (Python keyword)
+  country: string;
+  created_at: string;
+  started_at?: string;
+  completed_at?: string;
+  duration_seconds?: number;
+  transcript?: Array<Record<string, any>>;
+  summary?: string;
+  metadata: Record<string, any>;
+  end_user_id?: string;  // Marketplace end-user ID for privacy isolation
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  input_schema: Record<string, any>;
+  output_schema?: Record<string, any>;
+  timeout_ms?: number;
+}
+
+export interface WebhookPayload {
+  event: string;
+  call_id: string;
+  call_session_id: string;
+  timestamp: string;
+  data: Record<string, any>;
+}
+
+export class PamelaClient {
+  private client: AxiosInstance;
+  private apiKey: string;
+
+  constructor(config: PamelaClientConfig) {
+    this.apiKey = config.apiKey;
+    const baseURL = config.baseUrl || 'https://api.thisispamela.com';
+    
+    this.client = axios.create({
+      baseURL: `${baseURL}/api/b2b/v1`,
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      timeout: 30000,
+    });
+
+    // Add retry logic
+    this.client.interceptors.response.use(
+      (response) => response,
+      async (error: AxiosError) => {
+        const config = error.config as any;
+        if (!config || !config.retry) {
+          config.retry = 0;
+        }
+        config.retry += 1;
+
+        if (config.retry <= 3 && error.response?.status && error.response.status >= 500) {
+          await new Promise(resolve => setTimeout(resolve, 1000 * config.retry));
+          return this.client.request(config);
+        }
+
+        return Promise.reject(error);
+      }
+    );
+  }
+
+  /**
+   * Create a new call.
+   */
+  async createCall(request: CreateCallRequest): Promise<CallResponse> {
+    const response = await this.client.post<CallResponse>('/calls', request);
+    return response.data;
+  }
+
+  /**
+   * Get call status and details.
+   */
+  async getCall(callId: string): Promise<CallStatus> {
+    const response = await this.client.get<CallStatus>(`/calls/${callId}`);
+    return response.data;
+  }
+
+  /**
+   * List calls for the authenticated partner/project.
+   */
+  async listCalls(params?: {
+    status?: string;
+    limit?: number;
+    offset?: number;
+    start_date?: string;
+    end_date?: string;
+  }): Promise<{ items: CallStatus[]; total: number; limit: number; offset: number }> {
+    const response = await this.client.get('/calls', { params });
+    // Backend returns { items: [...], total, limit, offset }
+    return response.data;
+  }
+
+  /**
+   * Cancel an in-progress call.
+   */
+  async cancelCall(callId: string): Promise<{ success: boolean; call_id: string; status: string }> {
+    const response = await this.client.post(`/calls/${callId}/cancel`);
+    return response.data;
+  }
+
+  /**
+   * Register a tool.
+   */
+  async registerTool(tool: ToolDefinition): Promise<{ id: string; project_id: string; name: string; description: string; input_schema: Record<string, any>; output_schema: Record<string, any>; timeout_ms: number; created_at: string }> {
+    const response = await this.client.post('/tools', { tool });
+    return response.data;
+  }
+
+  /**
+   * List all tools for the project.
+   */
+  async listTools(): Promise<Array<{ id: string; project_id: string; name: string; description: string; input_schema: Record<string, any>; output_schema: Record<string, any>; timeout_ms: number; created_at: string }>> {
+    const response = await this.client.get('/tools');
+    return response.data;
+  }
+
+  /**
+   * Delete a tool.
+   */
+  async deleteTool(toolId: string): Promise<{ success: boolean; tool_id: string }> {
+    const response = await this.client.delete(`/tools/${toolId}`);
+    return response.data;
+  }
+
+  /**
+   * Verify webhook signature.
+   */
+  static verifyWebhookSignature(
+    payload: string | object,
+    signature: string,
+    secret: string
+  ): boolean {
+    const payloadString = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    const expectedSignature = crypto
+      .createHmac('sha256', secret)
+      .update(payloadString)
+      .digest('hex');
+    
+    return crypto.timingSafeEqual(
+      Buffer.from(signature),
+      Buffer.from(expectedSignature)
+    );
+  }
+}
+
+export default PamelaClient;
+

package/tests/pamela.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Integration tests for Pamela JavaScript SDK.
+ * 
+ * Tests against staging API or mocked responses.
+ */
+
+import { Pamela } from "../src/index";
+
+const TEST_API_URL = process.env.TEST_API_URL || "https://pamela-dev.up.railway.app";
+const TEST_API_KEY = process.env.TEST_API_KEY || "pk_test_placeholder";
+
+describe("Pamela SDK", () => {
+  let sdk: Pamela;
+
+  beforeEach(() => {
+    sdk = new Pamela({
+      apiKey: TEST_API_KEY,
+      apiUrl: TEST_API_URL,
+    });
+  });
+
+  describe("Initialization", () => {
+    it("should initialize with API key", () => {
+      expect(sdk).toBeDefined();
+    });
+
+    it("should throw error without API key", () => {
+      expect(() => {
+        new Pamela({ apiKey: "" });
+      }).toThrow();
+    });
+  });
+
+  describe("Call Creation", () => {
+    it("should create a call with required parameters", async () => {
+      // Mock or use staging API
+      const call = await sdk.calls.create({
+        to: "+1234567890",
+        from_: "+1987654321",
+        country: "US",
+      });
+
+      expect(call).toBeDefined();
+      expect(call.id).toBeDefined();
+      expect(call.status).toBeDefined();
+    });
+
+    it("should handle invalid phone numbers", async () => {
+      await expect(
+        sdk.calls.create({
+          to: "invalid",
+          from_: "+1987654321",
+          country: "US",
+        })
+      ).rejects.toThrow();
+    });
+  });
+
+  describe("Call Status", () => {
+    it("should get call status by ID", async () => {
+      const callId = "test_call_id";
+      const status = await sdk.calls.getStatus(callId);
+
+      expect(status).toBeDefined();
+      expect(status.id).toBe(callId);
+      expect(status.status).toBeDefined();
+    });
+
+    it("should handle non-existent call ID", async () => {
+      await expect(sdk.calls.getStatus("nonexistent")).rejects.toThrow();
+    });
+  });
+
+  describe("Call Cancellation", () => {
+    it("should cancel an in-progress call", async () => {
+      const callId = "test_call_id";
+      const result = await sdk.calls.cancel(callId);
+
+      expect(result).toBeDefined();
+      expect(result.success).toBe(true);
+    });
+
+    it("should handle cancelling already completed call", async () => {
+      await expect(sdk.calls.cancel("completed_call")).rejects.toThrow();
+    });
+  });
+
+  describe("Usage", () => {
+    it("should get usage statistics", async () => {
+      const usage = await sdk.usage.get("2024-01");
+
+      expect(usage).toBeDefined();
+      expect(usage.call_count).toBeDefined();
+      expect(usage.quota).toBeDefined();
+    });
+
+    it("should handle invalid period format", async () => {
+      await expect(sdk.usage.get("invalid")).rejects.toThrow();
+    });
+  });
+
+  describe("Error Handling", () => {
+    it("should handle network errors", async () => {
+      // Test with invalid API URL
+      const badSdk = new Pamela({
+        apiKey: TEST_API_KEY,
+        apiUrl: "https://invalid-url.example.com",
+      });
+
+      await expect(
+        badSdk.calls.create({
+          to: "+1234567890",
+          from_: "+1987654321",
+          country: "US",
+        })
+      ).rejects.toThrow();
+    });
+
+    it("should handle API errors (400, 401, 403, 500)", async () => {
+      // Test with invalid API key
+      const badSdk = new Pamela({
+        apiKey: "invalid_key",
+        apiUrl: TEST_API_URL,
+      });
+
+      await expect(
+        badSdk.calls.create({
+          to: "+1234567890",
+          from_: "+1987654321",
+          country: "US",
+        })
+      ).rejects.toThrow();
+    });
+  });
+});
+

package/tests/setup.ts

@@ -0,0 +1,31 @@
+/**
+ * Test setup for JavaScript SDK tests.
+ * 
+ * Configure test environment, mock API responses, etc.
+ */
+
+// Set test API URL (use staging or mock server)
+export const TEST_API_URL = process.env.TEST_API_URL || "https://pamela-dev.up.railway.app";
+
+// Test API key (use test keys from staging environment)
+export const TEST_API_KEY = process.env.TEST_API_KEY || "pk_test_placeholder";
+
+// Mock data helpers
+export const mockCallResponse = {
+  id: "call_test_123",
+  status: "queued",
+  to: "+1234567890",
+  from_: "+1987654321",
+  created_at: new Date().toISOString(),
+};
+
+export const mockCallStatusResponse = {
+  id: "call_test_123",
+  status: "completed",
+  to: "+1234567890",
+  from_: "+1987654321",
+  duration_seconds: 120,
+  created_at: new Date().toISOString(),
+  completed_at: new Date().toISOString(),
+};
+

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+