@thisispamela/sdk 1.0.1 → 1.0.2

package/README.md

@@ -76,7 +76,7 @@ API keys are created and managed through the Pamela Partner Portal or via the Pa
        -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_` or `pk_test_`) to identify keys in your account
+4. **Use the key prefix** (`pk_live_`) to identify keys in your account
 
 ### Managing API Keys
 
@@ -86,8 +86,7 @@ API keys are created and managed through the Pamela Partner Portal or via the Pa
 
 ### API Key Format
 
-- **Live keys**: Start with `pk_live_` (for production use)
-- **Test keys**: Start with `pk_test_` (for development/testing)
+- **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
@@ -112,29 +111,116 @@ Check subscription status using the Enterprise Partner API:
 - `POST /api/b2b/v1/partner/subscription/checkout` - Create checkout session
 - `POST /api/b2b/v1/partner/subscription/portal` - Access Customer Portal
 
-## Error Codes
+## Error Handling
 
-### Authentication Errors
+The SDK provides typed exceptions for all API errors:
 
-- `401 Unauthorized`: Invalid or missing API key
-- `403 Forbidden`: Subscription inactive or expired
-  - Check subscription status: `subscription_status` must be `"active"`
-  - For `past_due`: Check `grace_period_ends_at` - access allowed during grace period
+```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
+### Validation Errors (400)
 
-- `400 Bad Request`: Invalid request parameters
-- `404 Not Found`: Resource not found (call, partner, etc.)
+| Code | Description |
+|------|-------------|
+| 2001 | Validation error |
+| 2002 | Invalid phone number format |
 
-### Quota/Limit Errors
+### Enterprise Errors (7xxx)
 
-- `429 Too Many Requests`: Quota exceeded (if quota limits are set)
-- Note: Enterprise subscriptions have no quota limits for API calls (all usage is billed per-minute)
+| Code | Description |
+|------|-------------|
+| 7001 | Partner not found |
+| 7002 | Project not found |
+| 7003 | Call not found |
+| 7004 | No phone number for country |
+| 7005 | Unsupported country |
 
-### Rate Limit Errors
+### Rate Limiting (429)
 
-- `429 Too Many Requests`: Rate limit exceeded
-- Retry after the time specified in `Retry-After` header
+| Code | Description |
+|------|-------------|
+| 6001 | Rate limit exceeded |
+| 6002 | Quota exceeded |
 
 ## Usage Limits & Billing
 

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

@@ -2,6 +2,7 @@
  * 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;
@@ -150,3 +151,4 @@ export declare class PamelaClient {
 }
 export default PamelaClient;
 export { PamelaClient as Pamela };
+export { PamelaError, AuthenticationError, SubscriptionError, RateLimitError, ValidationError, CallError, };

package/dist/index.js

@@ -39,9 +39,52 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Pamela = exports.PamelaClient = exports.UsageClient = 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;
@@ -81,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));
         });
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thisispamela/sdk",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Pamela Enterprise Voice API SDK for JavaScript/TypeScript",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -4,6 +4,14 @@
 
 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,6 +72,43 @@ 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;
 
@@ -127,7 +172,7 @@ export class PamelaClient {
           return this.client.request(config);
         }
 
-        return Promise.reject(error);
+        return Promise.reject(mapAxiosError(error, config?.url));
       }
     );
   }
@@ -225,4 +270,12 @@ 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,20 +1,171 @@
 /**
- * Integration tests for Pamela JavaScript SDK.
+ * Tests for Pamela JavaScript/TypeScript SDK.
  *
- * These tests run against staging only when env vars are provided.
+ * Includes unit tests (no network) and integration tests (require env vars).
  */
 
-import PamelaClient 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);
+  });
+
+  it("rejects invalid signature", () => {
+    const payload = { event: "call.completed" };
+    expect(
+      PamelaClient.verifyWebhookSignature(payload, "invalid_sig", secret)
+    ).toBe(false);
+  });
+
+  it("handles string payload", () => {
+    const payloadStr = '{"test":"value"}';
+    const signature = crypto
+      .createHmac("sha256", secret)
+      .update(payloadStr)
+      .digest("hex");
+
+    expect(
+      PamelaClient.verifyWebhookSignature(payloadStr, signature, secret)
+    ).toBe(true);
+  });
+});
+
+describe("Exception Classes", () => {
+  it("PamelaError has correct properties", () => {
+    const error = new PamelaError("Test error", {
+      errorCode: 1001,
+      details: { key: "value" },
+      statusCode: 403,
+    });
+
+    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");
+  });
+
+  it("AuthenticationError has correct name", () => {
+    const error = new AuthenticationError("Invalid API key");
+    expect(error.name).toBe("AuthenticationError");
+    expect(error instanceof PamelaError).toBe(true);
+  });
+
+  it("SubscriptionError has correct name", () => {
+    const error = new SubscriptionError("Subscription expired", {
+      errorCode: 7008,
+    });
+    expect(error.name).toBe("SubscriptionError");
+    expect(error.errorCode).toBe(7008);
+  });
+
+  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" });
+  });
+
+  it("CallError has correct name", () => {
+    const error = new CallError("Call failed");
+    expect(error.name).toBe("CallError");
+    expect(error instanceof PamelaError).toBe(true);
+  });
+
+  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();
+  });
+});
+
+describe("Client Initialization", () => {
+  it("initializes with API key", () => {
+    const client = new PamelaClient({
+      apiKey: "pk_live_test",
+    });
+    expect(client).toBeDefined();
+    expect(client.usage).toBeDefined();
+  });
+
+  it("uses default base URL", () => {
+    const client = new PamelaClient({
+      apiKey: "pk_live_test",
+    });
+    // Client is created successfully with default URL
+    expect(client).toBeDefined();
+  });
+
+  it("accepts custom base URL", () => {
+    const client = new PamelaClient({
+      apiKey: "pk_live_test",
+      baseUrl: "https://custom.api.com",
+    });
+    expect(client).toBeDefined();
+  });
+});
+
+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);
+  });
+
+  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)
+// =============================================================================
+
 describe("PamelaClient SDK", () => {
   it("initializes with API key", () => {
     const client = new PamelaClient({
-      apiKey: TEST_API_KEY || "pk_test_placeholder",
+      apiKey: TEST_API_KEY || "pk_live_placeholder",
       baseUrl: TEST_API_URL,
     });
     expect(client).toBeDefined();
@@ -42,5 +193,10 @@ describe("PamelaClient SDK", () => {
     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 = {