@thisispamela/sdk 1.0.0 → 1.0.1

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,154 @@ 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_` or `pk_test_`) 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_` (for production use)
+- **Test keys**: Start with `pk_test_` (for development/testing)
+- **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 Codes
+
+### Authentication 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
+
+### Validation Errors
+
+- `400 Bad Request`: Invalid request parameters
+- `404 Not Found`: Resource not found (call, partner, etc.)
+
+### Quota/Limit Errors
+
+- `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)
+
+### Rate Limit Errors
+
+- `429 Too Many Requests`: Rate limit exceeded
+- Retry after the time specified in `Retry-After` header
+
+## 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/index.d.ts

@@ -1,6 +1,7 @@
 /**
- * Pamela B2B Voice API SDK for JavaScript/TypeScript
+ * Pamela Enterprise Voice API SDK for JavaScript/TypeScript
  */
+import { AxiosInstance } from 'axios';
 export interface PamelaClientConfig {
     apiKey: string;
     baseUrl?: string;
@@ -54,9 +55,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 +91,7 @@ export declare class PamelaClient {
      */
     listCalls(params?: {
         status?: string;
+        status_filter?: string;
         limit?: number;
         offset?: number;
         start_date?: string;
@@ -128,3 +149,4 @@ export declare class PamelaClient {
     static verifyWebhookSignature(payload: string | object, signature: string, secret: string): boolean;
 }
 export default PamelaClient;
+export { PamelaClient as Pamela };

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,23 @@ 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.Pamela = exports.PamelaClient = exports.UsageClient = void 0;
 const axios_1 = __importDefault(require("axios"));
 const crypto = __importStar(require("crypto"));
+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 +68,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;
@@ -86,7 +102,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 +152,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.1",
+  "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/index.ts

@@ -1,5 +1,5 @@
 /**
- * Pamela B2B Voice API SDK for JavaScript/TypeScript
+ * Pamela Enterprise Voice API SDK for JavaScript/TypeScript
  */
 
 import axios, { AxiosInstance, AxiosError } from 'axios';
@@ -64,9 +64,37 @@ export interface WebhookPayload {
   data: Record<string, any>;
 }
 
+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 +109,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,
@@ -122,12 +153,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 +222,7 @@ export class PamelaClient {
   }
 }
 
+// Export as both default and named export for flexibility
 export default PamelaClient;
+export { PamelaClient as Pamela };
 

package/tests/pamela.test.ts

@@ -1,136 +1,46 @@
 /**
  * Integration tests for Pamela JavaScript SDK.
- * 
- * Tests against staging API or mocked responses.
+ *
+ * These tests run against staging only when env vars are provided.
  */
 
-import { Pamela } from "../src/index";
+import PamelaClient 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";
+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);
 
-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("PamelaClient SDK", () => {
+  it("initializes with API key", () => {
+    const client = new PamelaClient({
+      apiKey: TEST_API_KEY || "pk_test_placeholder",
+      baseUrl: TEST_API_URL,
     });
+    expect(client).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);
-    });
+(SHOULD_RUN ? describe : describe.skip)("PamelaClient integration", () => {
+  let client: PamelaClient;
 
-    it("should handle cancelling already completed call", async () => {
-      await expect(sdk.calls.cancel("completed_call")).rejects.toThrow();
+  beforeAll(() => {
+    client = new PamelaClient({
+      apiKey: TEST_API_KEY as string,
+      baseUrl: TEST_API_URL,
     });
   });
 
-  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();
-    });
+  it("lists calls", async () => {
+    const result = await client.listCalls({ limit: 1 });
+    expect(result).toBeDefined();
+    expect(Array.isArray(result.items)).toBe(true);
   });
 
-  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();
-    });
+  it("gets usage", async () => {
+    const usage = await client.usage.get();
+    expect(usage).toBeDefined();
+    expect(usage.call_count).toBeDefined();
   });
 });