@applica-software-guru/persona-sdk 0.1.3 → 0.1.5

package/README.md

@@ -20,29 +20,70 @@ const sdk = new PersonaSdk(
   'https://persona.applica.guru/workflows'
 );
 
-// Authenticate with API key
-const agents = await sdk.agents('your-api-key').list(null, 1, 20);
+// Authenticate with a project API key
+const agents = await sdk.agents('prs_your_project_api_key').list(null, 1, 20);
+console.log(`Total agents: ${agents.total}`);
 ```
 
+The `PersonaSdk` constructor takes the base URL of persona-core and (optionally)
+the base URL of the workflows service. Each resource is exposed as a factory
+method that requires authentication credentials.
+
 ## Authentication
 
-The SDK supports two authentication methods:
+The SDK supports two authentication methods. Pass either a string (API key) or
+an `AuthenticationProvider` instance to any resource factory.
+
+### API Key
+
+The simplest method — pass the API key string directly. The SDK wraps it in an
+`ApiKeyAuthenticationProvider` and sends it as the `x-persona-apikey` header.
+
+Accepts:
 
-### API Key (default)
+- **Master key** — full admin access (server-to-server only)
+- **Project API key** (`prs_...`) — scoped to a single project
+- **Agent API key** (`prs_ag_...`) — scoped to a single agent
 
 ```typescript
-const projects = await sdk.projects('your-api-key').getMine();
+const projects = await sdk.projects('prs_your_project_api_key').getMine();
 ```
 
-### Bearer Token (IAM)
+### IAM Bearer Token
+
+For applications that authenticate end users via IAM, pass a
+`BearerTokenAuthenticationProvider` with a valid JWT:
 
 ```typescript
 import { BearerTokenAuthenticationProvider } from '@applica-software-guru/persona-sdk';
 
-const auth = new BearerTokenAuthenticationProvider('your-iam-token');
+const auth = new BearerTokenAuthenticationProvider(iamJwtToken);
 const projects = await sdk.projects(auth).getMine();
 ```
 
+The token is sent as the `Authorization: Bearer <token>` header. The server
+validates it via the IAM service and resolves the user's project automatically.
+Use this method when building user-facing apps (e.g. control panels) where the
+user logs in through IAM.
+
+### Custom provider
+
+Implement your own provider via the `AuthenticationProvider` interface:
+
+```typescript
+import { AuthenticationProvider } from '@applica-software-guru/persona-sdk';
+
+class MyProvider implements AuthenticationProvider {
+  applyHeaders(headers: Headers): void {
+    headers.set('x-custom-header', 'value');
+  }
+
+  getCredentials(): string {
+    return 'my-credentials';
+  }
+}
+```
+
 ## Usage Examples
 
 ### Agents
@@ -201,6 +242,54 @@ const mission = await missionsApi.create({ name: 'My Mission' });
 await missionsApi.execute(mission.id);
 ```
 
+### Billing
+
+The `BillingClient` manages customers, subscriptions, credits and invoices. It uses a separate base URL and can be instantiated directly or via `PersonaSdk`.
+
+```typescript
+import { BillingClient } from '@applica-software-guru/persona-sdk';
+
+// Standalone usage
+const billing = new BillingClient('https://persona.applica.guru/billing', 'your-api-key');
+
+// Or via PersonaSdk
+const billing = sdk.billing('your-api-key');
+
+// Customer management
+const customer = await billing.createCustomer({
+  owner: 'user-123',
+  name: 'Acme Corp',
+  email: 'billing@acme.com',
+});
+const existing = await billing.getCustomer('user-123');
+await billing.updateCustomer('user-123', { name: 'Acme Inc.' });
+await billing.deleteCustomer('user-123');
+
+// Subscription management
+const subscription = await billing.createSubscription({ owner: 'user-123' });
+const current = await billing.getSubscription('user-123');
+await billing.cancelSubscription('user-123');
+
+// Plan changes
+await billing.beginUpgrade('user-123', { toPlanType: 'pro' });
+await billing.downgrade('user-123', { toPlanType: 'starter' });
+await billing.mentorize('user-123', { endDate: '2026-12-31' });
+
+// Credits
+await billing.addCredits('user-123', 100);
+await billing.useCredits('user-123', 10, ['chat', 'voice'], 'reference-id');
+const credits = await billing.getCredits('user-123');
+const valid = await billing.isValid('user-123');
+
+// Invoices
+const invoices = await billing.listInvoices('user-123', '2026-01-01', '2026-12-31');
+
+// Project-level billing
+const projectSub = await billing.getProjectSubscription('project-id');
+await billing.changeProjectSubscriptionPlan('project-id', { toPlanType: 'pro' });
+await billing.addProjectSubscriptionCredits('project-id', { credits: 50 });
+```
+
 ## Error Handling
 
 ```typescript
@@ -235,6 +324,7 @@ try {
 | **FeatureTemplatesApi** | `list`, `get`, `create`, `update`, `patch`, `remove`, `getMcpAvailableTools` |
 | **MissionsApi** | `list`, `get`, `create`, `update`, `remove`, `generate`, `execute`, `retry`, `replan`, `sendInstruction`, `stop`, `resume` |
 | **ServicePricesApi** | `list`, `get`, `create`, `update`, `remove` |
+| **BillingClient** | `createCustomer`, `updateCustomer`, `getCustomer`, `saveCustomer`, `deleteCustomer`, `createSubscription`, `getSubscription`, `cancelSubscription`, `beginUpgrade`, `downgrade`, `mentorize`, `addCredits`, `useCredits`, `getCredits`, `isValid`, `listInvoices`, `getProjectSubscription`, `changeProjectSubscriptionPlan`, `addProjectSubscriptionCredits` |
 
 ## Compatibility
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@applica-software-guru/persona-sdk",
   "description": "Official TypeScript SDK for the Persona API — manage agents, sessions, projects, knowledge bases, workflows, triggers and more.",
   "private": false,
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "scripts": {
     "dev": "vite",