@thisispamela/sdk 1.0.0 → 1.0.2

package/README.md

@@ -1,11 +1,11 @@
 # Pamela SDK for JavaScript/TypeScript
 
-Official SDK for the Pamela Voice API.
+Official SDK for the Pamela Enterprise Voice API.
 
 ## Installation
 
 ```bash
-npm install @pamela/sdk
+npm install @thisispamela/sdk
 ```
 
 ## Usage
@@ -13,7 +13,7 @@ npm install @pamela/sdk
 ### Basic Example
 
 ```typescript
-import { PamelaClient } from '@pamela/sdk';
+import { PamelaClient } from '@thisispamela/sdk';
 
 const client = new PamelaClient({
   apiKey: 'pk_live_your_api_key_here',
@@ -37,7 +37,7 @@ console.log('Call status:', status.status);
 ### Webhook Verification
 
 ```typescript
-import { PamelaClient } from '@pamela/b2b-sdk';
+import { PamelaClient } from '@thisispamela/sdk';
 import express from 'express';
 
 const app = express();
@@ -59,7 +59,240 @@ app.post('/webhooks/pamela', express.json(), (req, res) => {
 });
 ```
 
+## Getting API Keys
+
+### Obtaining Your API Key
+
+API keys are created and managed through the Pamela Partner Portal or via the Partner API:
+
+1. **Sign up for an Enterprise subscription** (see Subscription Requirements below)
+2. **Create an API key** via one of these methods:
+   - Partner Portal: Log in to your account and navigate to the Enterprise panel
+   - Partner API: `POST /api/b2b/v1/partner/api-keys`
+     ```bash
+     curl -X POST https://api.thisispamela.com/api/b2b/v1/partner/api-keys \
+       -H "Authorization: Bearer YOUR_B2C_USER_TOKEN" \
+       -H "Content-Type: application/json" \
+       -d '{"project_id": "optional-project-id", "key_prefix": "pk_live_"}'
+     ```
+3. **Save your API key immediately** - the full key is only returned once during creation
+4. **Use the key prefix** (`pk_live_`) to identify keys in your account
+
+### Managing API Keys
+
+- **List API keys**: `GET /api/b2b/v1/partner/api-keys`
+- **Revoke API key**: `POST /api/b2b/v1/partner/api-keys/{key_id}/revoke`
+- **Associate with projects**: Optionally link API keys to specific projects for better organization
+
+### API Key Format
+
+- **Live keys**: Start with `pk_live_` (all API usage)
+- **Security**: Keys are hashed in the database. Store them securely and never commit them to version control.
+
+## Subscription Requirements
+
+### Enterprise Subscription Required
+
+**All API access requires an active Enterprise subscription.** API calls will return `403 Forbidden` if:
+- No Enterprise subscription is active
+- Subscription status is `past_due` and grace period has expired
+- Subscription status is `canceled`
+
+### Grace Period
+
+Enterprise subscriptions have a **1-week grace period** when payment fails:
+- During grace period: API access is allowed, but usage is still charged
+- After grace period expires: API access is blocked until payment is updated
+
+### Subscription Status Endpoints
+
+Check subscription status using the Enterprise Partner API:
+- `GET /api/b2b/v1/partner/subscription` - Get subscription status
+- `POST /api/b2b/v1/partner/subscription/checkout` - Create checkout session
+- `POST /api/b2b/v1/partner/subscription/portal` - Access Customer Portal
+
+## Error Handling
+
+The SDK provides typed exceptions for all API errors:
+
+```typescript
+import {
+  PamelaClient,
+  PamelaError,
+  AuthenticationError,
+  SubscriptionError,
+  RateLimitError,
+  ValidationError,
+  CallError,
+} from '@thisispamela/sdk';
+
+const client = new PamelaClient({ apiKey: 'pk_live_your_key' });
+
+try {
+  const call = await client.createCall({ to: '+1234567890', task: 'Test' });
+} catch (e) {
+  if (e instanceof AuthenticationError) {
+    // 401: Invalid or missing API key
+    console.log('Auth failed:', e.message);
+    console.log('Error code:', e.errorCode);
+  } else if (e instanceof SubscriptionError) {
+    // 403: Subscription inactive or expired
+    if (e.errorCode === 7008) {
+      console.log('Grace period expired - update payment method');
+    } else {
+      console.log('Subscription issue:', e.message);
+    }
+  } else if (e instanceof RateLimitError) {
+    // 429: Rate limit exceeded
+    const retryAfter = e.details?.retry_after ?? 30;
+    console.log(`Rate limited, retry after ${retryAfter}s`);
+  } else if (e instanceof ValidationError) {
+    // 400/422: Invalid request parameters
+    console.log('Invalid request:', e.message);
+    console.log('Details:', e.details);
+  } else if (e instanceof CallError) {
+    // Call-specific errors
+    console.log('Call error:', e.message);
+  } else if (e instanceof PamelaError) {
+    // All other API errors
+    console.log(`API error ${e.errorCode}: ${e.message}`);
+  }
+}
+```
+
+### Exception Hierarchy
+
+All exceptions extend `PamelaError`:
+
+```
+PamelaError (base)
+├── AuthenticationError  // 401 errors
+├── SubscriptionError    // 403 errors (subscription issues)
+├── RateLimitError       // 429 errors
+├── ValidationError      // 400/422 errors
+└── CallError            // Call-specific errors
+```
+
+### Exception Properties
+
+All exceptions have:
+- `message`: Human-readable error message
+- `errorCode?`: Numeric error code (e.g., 7008 for subscription expired)
+- `details?`: Object with additional context
+- `statusCode?`: HTTP status code
+
+## Error Codes Reference
+
+### Authentication Errors (401)
+
+| Code | Description |
+|------|-------------|
+| 1001 | API key required |
+| 1002 | Invalid API key |
+| 1003 | API key expired |
+
+### Subscription Errors (403)
+
+| Code | Description |
+|------|-------------|
+| 1005 | Enterprise subscription required |
+| 7008 | Subscription expired (grace period ended) |
+
+### Validation Errors (400)
+
+| Code | Description |
+|------|-------------|
+| 2001 | Validation error |
+| 2002 | Invalid phone number format |
+
+### Enterprise Errors (7xxx)
+
+| Code | Description |
+|------|-------------|
+| 7001 | Partner not found |
+| 7002 | Project not found |
+| 7003 | Call not found |
+| 7004 | No phone number for country |
+| 7005 | Unsupported country |
+
+### Rate Limiting (429)
+
+| Code | Description |
+|------|-------------|
+| 6001 | Rate limit exceeded |
+| 6002 | Quota exceeded |
+
+## Usage Limits & Billing
+
+### Enterprise API Usage
+
+- **Unlimited API calls** (no call count limits)
+- **All API usage billed at $0.10/minute** (10 cents per minute)
+- **Minimum billing: 1 minute per call** (even if call duration < 60 seconds)
+- **Billing calculation**: `billed_minutes = max(ceil(duration_seconds / 60), 1)`
+- **Only calls that connect** (have `started_at`) are billed
+
+### Usage Tracking
+
+- Usage is tracked in `b2b_usage` collection with `type: "api_usage"` (collection name stays `b2b_usage`)
+- Usage is synced to Stripe hourly (at :00 minutes)
+- Stripe meter name: `stripe_minutes`
+- Failed syncs are retried with exponential backoff (1s, 2s, 4s, 8s, 16s), max 5 retries
+
+### Billing Period
+
+- Billing is based on calendar months (UTC midnight on 1st of each month)
+- Calls are billed in the month where `started_at` occurred
+- Usage sync status: `pending`, `synced`, or `failed`
+
+## API Methods
+
+### Calls
+
+- `createCall(request)` - Create a new call
+- `getCall(callId)` - Get call status and details
+- `listCalls(params?)` - List calls with optional filters
+- `cancelCall(callId)` - Cancel an in-progress call
+
+### Tools
+
+- `registerTool(tool)` - Register a tool
+- `listTools()` - List all tools
+- `deleteTool(toolId)` - Delete a tool
+
+### Usage
+
+- `usage.get(period?)` - Get usage statistics
+
+**Example:**
+```typescript
+// Get current month usage
+const usage = await client.usage.get();
+
+// Get usage for specific period
+const janUsage = await client.usage.get("2024-01");
+
+console.log(`Usage: ${usage.call_count} calls, ${usage.api_minutes} minutes`);
+console.log(`Quota: ${usage.quota?.partner_limit || 'Unlimited'}`);
+```
+
+**Response:**
+```typescript
+{
+  partner_id: "partner_123",
+  project_id?: "project_456",
+  period: "2024-01",
+  call_count: 150,
+  quota?: {
+    partner_limit?: number,
+    project_limit?: number
+  }
+}
+```
+
+**Note:** Enterprise subscriptions have no quota limits - all usage is billed per-minute.
+
 ## API Reference
 
-See the [Pamela B2B API Documentation](https://docs.thisispamela.com/b2b) for full API reference.
+See the [Pamela Enterprise API Documentation](https://docs.thisispamela.com/enterprise) for full API reference.
 

package/dist/errors.d.ts

@@ -0,0 +1,45 @@
+export declare class PamelaError extends Error {
+    errorCode?: number;
+    details?: Record<string, any>;
+    statusCode?: number;
+    constructor(message: string, options?: {
+        errorCode?: number;
+        details?: Record<string, any>;
+        statusCode?: number;
+    });
+}
+export declare class AuthenticationError extends PamelaError {
+    constructor(message: string, options?: {
+        errorCode?: number;
+        details?: Record<string, any>;
+        statusCode?: number;
+    });
+}
+export declare class SubscriptionError extends PamelaError {
+    constructor(message: string, options?: {
+        errorCode?: number;
+        details?: Record<string, any>;
+        statusCode?: number;
+    });
+}
+export declare class RateLimitError extends PamelaError {
+    constructor(message: string, options?: {
+        errorCode?: number;
+        details?: Record<string, any>;
+        statusCode?: number;
+    });
+}
+export declare class ValidationError extends PamelaError {
+    constructor(message: string, options?: {
+        errorCode?: number;
+        details?: Record<string, any>;
+        statusCode?: number;
+    });
+}
+export declare class CallError extends PamelaError {
+    constructor(message: string, options?: {
+        errorCode?: number;
+        details?: Record<string, any>;
+        statusCode?: number;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallError = exports.ValidationError = exports.RateLimitError = exports.SubscriptionError = exports.AuthenticationError = exports.PamelaError = void 0;
+class PamelaError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = 'PamelaError';
+        this.errorCode = options?.errorCode;
+        this.details = options?.details;
+        this.statusCode = options?.statusCode;
+    }
+}
+exports.PamelaError = PamelaError;
+class AuthenticationError extends PamelaError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'AuthenticationError';
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class SubscriptionError extends PamelaError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'SubscriptionError';
+    }
+}
+exports.SubscriptionError = SubscriptionError;
+class RateLimitError extends PamelaError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'RateLimitError';
+    }
+}
+exports.RateLimitError = RateLimitError;
+class ValidationError extends PamelaError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+class CallError extends PamelaError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'CallError';
+    }
+}
+exports.CallError = CallError;

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 /**
- * Pamela B2B Voice API SDK for JavaScript/TypeScript
+ * Pamela Enterprise Voice API SDK for JavaScript/TypeScript
  */
+import { AxiosInstance } from 'axios';
+import { PamelaError, AuthenticationError, SubscriptionError, RateLimitError, ValidationError, CallError } from './errors';
 export interface PamelaClientConfig {
     apiKey: string;
     baseUrl?: string;
@@ -54,9 +56,28 @@ export interface WebhookPayload {
     timestamp: string;
     data: Record<string, any>;
 }
+export declare class UsageClient {
+    private client;
+    constructor(client: AxiosInstance);
+    /**
+     * Get usage statistics for partner/project.
+     */
+    get(period?: string): Promise<{
+        partner_id: string;
+        project_id?: string;
+        period: string;
+        call_count: number;
+        last_updated?: string;
+        quota?: {
+            partner_limit?: number;
+            project_limit?: number;
+        };
+    }>;
+}
 export declare class PamelaClient {
     private client;
     private apiKey;
+    usage: UsageClient;
     constructor(config: PamelaClientConfig);
     /**
      * Create a new call.
@@ -71,6 +92,7 @@ export declare class PamelaClient {
      */
     listCalls(params?: {
         status?: string;
+        status_filter?: string;
         limit?: number;
         offset?: number;
         start_date?: string;
@@ -128,3 +150,5 @@ export declare class PamelaClient {
     static verifyWebhookSignature(payload: string | object, signature: string, secret: string): boolean;
 }
 export default PamelaClient;
+export { PamelaClient as Pamela };
+export { PamelaError, AuthenticationError, SubscriptionError, RateLimitError, ValidationError, CallError, };

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * Pamela B2B Voice API SDK for JavaScript/TypeScript
+ * Pamela Enterprise Voice API SDK for JavaScript/TypeScript
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -39,9 +39,66 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PamelaClient = void 0;
+exports.CallError = exports.ValidationError = exports.RateLimitError = exports.SubscriptionError = exports.AuthenticationError = exports.PamelaError = exports.Pamela = exports.PamelaClient = exports.UsageClient = void 0;
 const axios_1 = __importDefault(require("axios"));
 const crypto = __importStar(require("crypto"));
+const errors_1 = require("./errors");
+Object.defineProperty(exports, "PamelaError", { enumerable: true, get: function () { return errors_1.PamelaError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_1.AuthenticationError; } });
+Object.defineProperty(exports, "SubscriptionError", { enumerable: true, get: function () { return errors_1.SubscriptionError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_1.RateLimitError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
+Object.defineProperty(exports, "CallError", { enumerable: true, get: function () { return errors_1.CallError; } });
+const mapAxiosError = (error, endpoint) => {
+    const statusCode = error.response?.status;
+    const data = error.response?.data;
+    let errorCode;
+    let message;
+    let details;
+    if (data && typeof data === 'object') {
+        const detail = data.detail;
+        if (detail && typeof detail === 'object') {
+            errorCode = detail.error_code ?? detail.error?.code;
+            message = detail.message ?? detail.error?.message;
+            details = detail.details ?? detail.error?.details;
+        }
+        else {
+            errorCode = data.error_code ?? data.error?.code;
+            message = data.message ?? data.detail;
+            details = data.details ?? data.error?.details;
+        }
+    }
+    if (!message) {
+        message = error.message || 'Request failed';
+    }
+    const options = { errorCode, details, statusCode };
+    if (statusCode === 401)
+        return new errors_1.AuthenticationError(message, options);
+    if (statusCode === 403)
+        return new errors_1.SubscriptionError(message, options);
+    if (statusCode === 429)
+        return new errors_1.RateLimitError(message, options);
+    if (statusCode === 400 || statusCode === 422)
+        return new errors_1.ValidationError(message, options);
+    if (endpoint?.startsWith('/calls')) {
+        return new errors_1.CallError(message, options);
+    }
+    return new errors_1.PamelaError(message, options);
+};
+class UsageClient {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get usage statistics for partner/project.
+     */
+    async get(period) {
+        const params = period ? { period } : {};
+        const response = await this.client.get('/usage', { params });
+        return response.data;
+    }
+}
+exports.UsageClient = UsageClient;
 class PamelaClient {
     constructor(config) {
         this.apiKey = config.apiKey;
@@ -54,6 +111,8 @@ class PamelaClient {
             },
             timeout: 30000,
         });
+        // Initialize usage client
+        this.usage = new UsageClient(this.client);
         // Add retry logic
         this.client.interceptors.response.use((response) => response, async (error) => {
             const config = error.config;
@@ -65,7 +124,7 @@ class PamelaClient {
                 await new Promise(resolve => setTimeout(resolve, 1000 * config.retry));
                 return this.client.request(config);
             }
-            return Promise.reject(error);
+            return Promise.reject(mapAxiosError(error, config?.url));
         });
     }
     /**
@@ -86,7 +145,12 @@ class PamelaClient {
      * List calls for the authenticated partner/project.
      */
     async listCalls(params) {
-        const response = await this.client.get('/calls', { params });
+        const normalizedParams = { ...params };
+        if (params?.status_filter || params?.status) {
+            normalizedParams.status_filter = params?.status_filter ?? params?.status;
+            delete normalizedParams.status;
+        }
+        const response = await this.client.get('/calls', { params: normalizedParams });
         // Backend returns { items: [...], total, limit, offset }
         return response.data;
     }
@@ -131,4 +195,6 @@ class PamelaClient {
     }
 }
 exports.PamelaClient = PamelaClient;
+exports.Pamela = PamelaClient;
+// Export as both default and named export for flexibility
 exports.default = PamelaClient;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thisispamela/sdk",
-  "version": "1.0.0",
-  "description": "Pamela B2B Voice API SDK for JavaScript/TypeScript",
+  "version": "1.0.2",
+  "description": "Pamela Enterprise Voice API SDK for JavaScript/TypeScript",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -14,7 +14,7 @@
     "pamela",
     "voice",
     "api",
-    "b2b",
+    "enterprise",
     "phone",
     "calling"
   ],

package/src/errors.ts

@@ -0,0 +1,48 @@
+export class PamelaError extends Error {
+  public errorCode?: number;
+  public details?: Record<string, any>;
+  public statusCode?: number;
+
+  constructor(message: string, options?: { errorCode?: number; details?: Record<string, any>; statusCode?: number }) {
+    super(message);
+    this.name = 'PamelaError';
+    this.errorCode = options?.errorCode;
+    this.details = options?.details;
+    this.statusCode = options?.statusCode;
+  }
+}
+
+export class AuthenticationError extends PamelaError {
+  constructor(message: string, options?: { errorCode?: number; details?: Record<string, any>; statusCode?: number }) {
+    super(message, options);
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class SubscriptionError extends PamelaError {
+  constructor(message: string, options?: { errorCode?: number; details?: Record<string, any>; statusCode?: number }) {
+    super(message, options);
+    this.name = 'SubscriptionError';
+  }
+}
+
+export class RateLimitError extends PamelaError {
+  constructor(message: string, options?: { errorCode?: number; details?: Record<string, any>; statusCode?: number }) {
+    super(message, options);
+    this.name = 'RateLimitError';
+  }
+}
+
+export class ValidationError extends PamelaError {
+  constructor(message: string, options?: { errorCode?: number; details?: Record<string, any>; statusCode?: number }) {
+    super(message, options);
+    this.name = 'ValidationError';
+  }
+}
+
+export class CallError extends PamelaError {
+  constructor(message: string, options?: { errorCode?: number; details?: Record<string, any>; statusCode?: number }) {
+    super(message, options);
+    this.name = 'CallError';
+  }
+}

package/src/index.ts

@@ -1,9 +1,17 @@
 /**
- * Pamela B2B Voice API SDK for JavaScript/TypeScript
+ * Pamela Enterprise Voice API SDK for JavaScript/TypeScript
  */
 
 import axios, { AxiosInstance, AxiosError } from 'axios';
 import * as crypto from 'crypto';
+import {
+  PamelaError,
+  AuthenticationError,
+  SubscriptionError,
+  RateLimitError,
+  ValidationError,
+  CallError,
+} from './errors';
 
 export interface PamelaClientConfig {
   apiKey: string;
@@ -64,9 +72,74 @@ export interface WebhookPayload {
   data: Record<string, any>;
 }
 
+const mapAxiosError = (error: AxiosError, endpoint?: string): PamelaError => {
+  const statusCode = error.response?.status;
+  const data = error.response?.data as any;
+  let errorCode: number | undefined;
+  let message: string | undefined;
+  let details: Record<string, any> | undefined;
+
+  if (data && typeof data === 'object') {
+    const detail = data.detail;
+    if (detail && typeof detail === 'object') {
+      errorCode = detail.error_code ?? detail.error?.code;
+      message = detail.message ?? detail.error?.message;
+      details = detail.details ?? detail.error?.details;
+    } else {
+      errorCode = data.error_code ?? data.error?.code;
+      message = data.message ?? data.detail;
+      details = data.details ?? data.error?.details;
+    }
+  }
+
+  if (!message) {
+    message = error.message || 'Request failed';
+  }
+
+  const options = { errorCode, details, statusCode };
+  if (statusCode === 401) return new AuthenticationError(message, options);
+  if (statusCode === 403) return new SubscriptionError(message, options);
+  if (statusCode === 429) return new RateLimitError(message, options);
+  if (statusCode === 400 || statusCode === 422) return new ValidationError(message, options);
+
+  if (endpoint?.startsWith('/calls')) {
+    return new CallError(message, options);
+  }
+
+  return new PamelaError(message, options);
+};
+
+export class UsageClient {
+  private client: AxiosInstance;
+
+  constructor(client: AxiosInstance) {
+    this.client = client;
+  }
+
+  /**
+   * Get usage statistics for partner/project.
+   */
+  async get(period?: string): Promise<{
+    partner_id: string;
+    project_id?: string;
+    period: string;
+    call_count: number;
+    last_updated?: string;
+    quota?: {
+      partner_limit?: number;
+      project_limit?: number;
+    };
+  }> {
+    const params = period ? { period } : {};
+    const response = await this.client.get('/usage', { params });
+    return response.data;
+  }
+}
+
 export class PamelaClient {
   private client: AxiosInstance;
   private apiKey: string;
+  public usage: UsageClient;
 
   constructor(config: PamelaClientConfig) {
     this.apiKey = config.apiKey;
@@ -81,6 +154,9 @@ export class PamelaClient {
       timeout: 30000,
     });
 
+    // Initialize usage client
+    this.usage = new UsageClient(this.client);
+
     // Add retry logic
     this.client.interceptors.response.use(
       (response) => response,
@@ -96,7 +172,7 @@ export class PamelaClient {
           return this.client.request(config);
         }
 
-        return Promise.reject(error);
+        return Promise.reject(mapAxiosError(error, config?.url));
       }
     );
   }
@@ -122,12 +198,18 @@ export class PamelaClient {
    */
   async listCalls(params?: {
     status?: string;
+    status_filter?: 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 });
+    const normalizedParams = { ...params };
+    if (params?.status_filter || params?.status) {
+      normalizedParams.status_filter = params?.status_filter ?? params?.status;
+      delete (normalizedParams as { status?: string }).status;
+    }
+    const response = await this.client.get('/calls', { params: normalizedParams });
     // Backend returns { items: [...], total, limit, offset }
     return response.data;
   }
@@ -185,5 +267,15 @@ export class PamelaClient {
   }
 }
 
+// Export as both default and named export for flexibility
 export default PamelaClient;
+export { PamelaClient as Pamela };
+export {
+  PamelaError,
+  AuthenticationError,
+  SubscriptionError,
+  RateLimitError,
+  ValidationError,
+  CallError,
+};
 

package/tests/pamela.test.ts

@@ -1,136 +1,202 @@
 /**
- * Integration tests for Pamela JavaScript SDK.
- * 
- * Tests against staging API or mocked responses.
+ * Tests for Pamela JavaScript/TypeScript SDK.
+ *
+ * Includes unit tests (no network) and integration tests (require env vars).
  */
 
-import { Pamela } from "../src/index";
+import PamelaClient, {
+  PamelaError,
+  AuthenticationError,
+  SubscriptionError,
+  RateLimitError,
+  ValidationError,
+  CallError,
+} from "../src/index";
+import * as crypto from "crypto";
+
+const TEST_API_URL =
+  process.env.PAMELA_API_URL || "https://pamela-dev.up.railway.app";
+const TEST_API_KEY = process.env.PAMELA_TEST_API_KEY;
+const SHOULD_RUN = Boolean(TEST_API_KEY);
+
+// =============================================================================
+// Unit Tests (No Network Required)
+// =============================================================================
+
+describe("Webhook Signature Verification", () => {
+  const secret = "test_secret_123";
+
+  it("verifies valid signature", () => {
+    const payload = { event: "call.completed", call_id: "call_123" };
+    const payloadStr = JSON.stringify(payload);
+    const signature = crypto
+      .createHmac("sha256", secret)
+      .update(payloadStr)
+      .digest("hex");
+
+    expect(
+      PamelaClient.verifyWebhookSignature(payload, signature, secret)
+    ).toBe(true);
+  });
 
-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";
+  it("rejects invalid signature", () => {
+    const payload = { event: "call.completed" };
+    expect(
+      PamelaClient.verifyWebhookSignature(payload, "invalid_sig", secret)
+    ).toBe(false);
+  });
 
-describe("Pamela SDK", () => {
-  let sdk: Pamela;
+  it("handles string payload", () => {
+    const payloadStr = '{"test":"value"}';
+    const signature = crypto
+      .createHmac("sha256", secret)
+      .update(payloadStr)
+      .digest("hex");
 
-  beforeEach(() => {
-    sdk = new Pamela({
-      apiKey: TEST_API_KEY,
-      apiUrl: TEST_API_URL,
-    });
+    expect(
+      PamelaClient.verifyWebhookSignature(payloadStr, signature, secret)
+    ).toBe(true);
   });
+});
 
-  describe("Initialization", () => {
-    it("should initialize with API key", () => {
-      expect(sdk).toBeDefined();
+describe("Exception Classes", () => {
+  it("PamelaError has correct properties", () => {
+    const error = new PamelaError("Test error", {
+      errorCode: 1001,
+      details: { key: "value" },
+      statusCode: 403,
     });
 
-    it("should throw error without API key", () => {
-      expect(() => {
-        new Pamela({ apiKey: "" });
-      }).toThrow();
-    });
+    expect(error.message).toBe("Test error");
+    expect(error.errorCode).toBe(1001);
+    expect(error.details).toEqual({ key: "value" });
+    expect(error.statusCode).toBe(403);
+    expect(error.name).toBe("PamelaError");
   });
 
-  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",
-      });
+  it("AuthenticationError has correct name", () => {
+    const error = new AuthenticationError("Invalid API key");
+    expect(error.name).toBe("AuthenticationError");
+    expect(error instanceof PamelaError).toBe(true);
+  });
 
-      expect(call).toBeDefined();
-      expect(call.id).toBeDefined();
-      expect(call.status).toBeDefined();
+  it("SubscriptionError has correct name", () => {
+    const error = new SubscriptionError("Subscription expired", {
+      errorCode: 7008,
     });
+    expect(error.name).toBe("SubscriptionError");
+    expect(error.errorCode).toBe(7008);
+  });
 
-    it("should handle invalid phone numbers", async () => {
-      await expect(
-        sdk.calls.create({
-          to: "invalid",
-          from_: "+1987654321",
-          country: "US",
-        })
-      ).rejects.toThrow();
+  it("RateLimitError has correct name", () => {
+    const error = new RateLimitError("Rate limit exceeded", { statusCode: 429 });
+    expect(error.name).toBe("RateLimitError");
+    expect(error.statusCode).toBe(429);
+  });
+
+  it("ValidationError has correct name", () => {
+    const error = new ValidationError("Invalid phone number", {
+      details: { field: "to" },
     });
+    expect(error.name).toBe("ValidationError");
+    expect(error.details).toEqual({ field: "to" });
   });
 
-  describe("Call Status", () => {
-    it("should get call status by ID", async () => {
-      const callId = "test_call_id";
-      const status = await sdk.calls.getStatus(callId);
+  it("CallError has correct name", () => {
+    const error = new CallError("Call failed");
+    expect(error.name).toBe("CallError");
+    expect(error instanceof PamelaError).toBe(true);
+  });
 
-      expect(status).toBeDefined();
-      expect(status.id).toBe(callId);
-      expect(status.status).toBeDefined();
-    });
+  it("exceptions can be created with minimal args", () => {
+    const error = new PamelaError("Simple error");
+    expect(error.message).toBe("Simple error");
+    expect(error.errorCode).toBeUndefined();
+    expect(error.details).toBeUndefined();
+  });
+});
 
-    it("should handle non-existent call ID", async () => {
-      await expect(sdk.calls.getStatus("nonexistent")).rejects.toThrow();
+describe("Client Initialization", () => {
+  it("initializes with API key", () => {
+    const client = new PamelaClient({
+      apiKey: "pk_live_test",
     });
+    expect(client).toBeDefined();
+    expect(client.usage).toBeDefined();
   });
 
-  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("uses default base URL", () => {
+    const client = new PamelaClient({
+      apiKey: "pk_live_test",
     });
+    // Client is created successfully with default URL
+    expect(client).toBeDefined();
+  });
 
-    it("should handle cancelling already completed call", async () => {
-      await expect(sdk.calls.cancel("completed_call")).rejects.toThrow();
+  it("accepts custom base URL", () => {
+    const client = new PamelaClient({
+      apiKey: "pk_live_test",
+      baseUrl: "https://custom.api.com",
     });
+    expect(client).toBeDefined();
   });
+});
 
-  describe("Usage", () => {
-    it("should get usage statistics", async () => {
-      const usage = await sdk.usage.get("2024-01");
+describe("Exception Hierarchy", () => {
+  it("all exceptions inherit from PamelaError", () => {
+    expect(new AuthenticationError("test") instanceof PamelaError).toBe(true);
+    expect(new SubscriptionError("test") instanceof PamelaError).toBe(true);
+    expect(new RateLimitError("test") instanceof PamelaError).toBe(true);
+    expect(new ValidationError("test") instanceof PamelaError).toBe(true);
+    expect(new CallError("test") instanceof PamelaError).toBe(true);
+  });
 
-      expect(usage).toBeDefined();
-      expect(usage.call_count).toBeDefined();
-      expect(usage.quota).toBeDefined();
-    });
+  it("all exceptions inherit from Error", () => {
+    expect(new PamelaError("test") instanceof Error).toBe(true);
+    expect(new AuthenticationError("test") instanceof Error).toBe(true);
+    expect(new SubscriptionError("test") instanceof Error).toBe(true);
+  });
+});
+
+// =============================================================================
+// Integration Tests (Require PAMELA_TEST_API_KEY)
+// =============================================================================
 
-    it("should handle invalid period format", async () => {
-      await expect(sdk.usage.get("invalid")).rejects.toThrow();
+describe("PamelaClient SDK", () => {
+  it("initializes with API key", () => {
+    const client = new PamelaClient({
+      apiKey: TEST_API_KEY || "pk_live_placeholder",
+      baseUrl: TEST_API_URL,
     });
+    expect(client).toBeDefined();
   });
+});
 
-  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();
-    });
+(SHOULD_RUN ? describe : describe.skip)("PamelaClient integration", () => {
+  let client: PamelaClient;
 
-    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();
+  beforeAll(() => {
+    client = new PamelaClient({
+      apiKey: TEST_API_KEY as string,
+      baseUrl: TEST_API_URL,
     });
   });
+
+  it("lists calls", async () => {
+    const result = await client.listCalls({ limit: 1 });
+    expect(result).toBeDefined();
+    expect(Array.isArray(result.items)).toBe(true);
+  });
+
+  it("gets usage", async () => {
+    const usage = await client.usage.get();
+    expect(usage).toBeDefined();
+    expect(usage.call_count).toBeDefined();
+  });
+
+  it("lists tools", async () => {
+    const tools = await client.listTools();
+    expect(Array.isArray(tools)).toBe(true);
+  });
 });
 

package/tests/setup.ts

@@ -7,8 +7,8 @@
 // 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";
+// API key for tests (use a staging key)
+export const TEST_API_KEY = process.env.TEST_API_KEY || "pk_live_placeholder";
 
 // Mock data helpers
 export const mockCallResponse = {