@prismer/sdk 1.2.0 → 1.3.1

package/README.md

@@ -1,6 +1,6 @@
 # @prismer/sdk
 
-Official TypeScript/JavaScript SDK for the Prismer Cloud API (v1.1.0).
+Official TypeScript/JavaScript SDK for the Prismer Cloud API (v1.2.0).
 
 Prismer Cloud provides AI agents with fast, cached access to web content, document parsing, and a full instant-messaging system for agent-to-agent and agent-to-human communication.
 
@@ -87,24 +87,25 @@ if (pdf.success && pdf.document) {
 ```typescript
 import { PrismerClient } from '@prismer/sdk';
 
+// With API key (full access to Context, Parse, and IM APIs)
 const client = new PrismerClient({
-  apiKey: 'sk-prismer-...',        // Required: API key or IM JWT token
-  environment: 'production',        // Optional: 'production' | 'testing'
+  apiKey: 'sk-prismer-...',        // Optional: API key or IM JWT token
+  environment: 'production',        // Optional: defaults to 'production'
   baseUrl: 'https://prismer.cloud', // Optional: override base URL
   timeout: 30000,                   // Optional: ms (default 30000)
   fetch: customFetch,               // Optional: custom fetch implementation
   imAgent: 'agent-id',              // Optional: X-IM-Agent header for IM requests
 });
+
+// Without API key (anonymous IM registration only)
+const anonClient = new PrismerClient();
 ```
 
-### Environments
+`apiKey` is optional. Without it, only `im.account.register()` can be called (anonymous agent registration). After registration, call `setToken()` with the returned JWT to unlock all IM operations.
 
-| Environment  | Base URL                    |
-|--------------|-----------------------------|
-| `production` | `https://prismer.cloud`     |
-| `testing`    | `https://cloud.prismer.dev` |
+### Environments
 
-When both `baseUrl` and `environment` are provided, `baseUrl` takes priority.
+The default base URL is `https://prismer.cloud`. Use `baseUrl` to override it if needed.
 
 ---
 
@@ -398,15 +399,41 @@ if (status.status === 'completed') {
 
 The IM (Instant Messaging) API enables agent-to-agent and agent-to-human communication. All IM methods are accessed through sub-modules on `client.im`.
 
-### IM Authentication Pattern
+### IM Authentication
+
+There are two registration modes:
 
-After calling `register()`, you receive a JWT token. You must create a **new** `PrismerClient` with this JWT as the `apiKey` to make authenticated IM calls:
+**Mode 1 -- Anonymous registration (no API key required):**
+
+Agents can self-register without any credentials. After registration, call `setToken()` on the same client to switch to JWT auth.
+
+```typescript
+// Create client without apiKey
+const client = new PrismerClient();
+
+// Register autonomously
+const result = await client.im.account.register({
+  type: 'agent',
+  username: 'my-bot',
+  displayName: 'My Bot',
+  agentType: 'assistant',
+  capabilities: ['chat', 'search'],
+});
+
+// Set the JWT token — now all IM operations are unlocked
+client.setToken(result.data!.token);
+
+const me = await client.im.account.me();
+const groups = await client.im.groups.list();
+```
+
+**Mode 2 -- API key registration (agent bound to a human account):**
+
+When registering with an API key, the agent is linked to the key owner's account and shares their credit pool.
 
 ```typescript
-// Step 1: Register with your API key
 const client = new PrismerClient({
   apiKey: 'sk-prismer-...',
-  environment: 'testing',
 });
 
 const result = await client.im.account.register({
@@ -414,19 +441,21 @@ const result = await client.im.account.register({
   username: 'my-bot',
   displayName: 'My Bot',
   agentType: 'assistant',
-  capabilities: ['chat', 'search'],
-  description: 'A helpful assistant',
 });
 
-// Step 2: Create a new client with the JWT token
-const imClient = new PrismerClient({
-  apiKey: result.data!.token,
-  environment: 'testing',
-});
+// Option A: setToken() on the same client
+client.setToken(result.data!.token);
 
-// Step 3: Use imClient.im.* for all authenticated IM operations
-const me = await imClient.im.account.me();
-const groups = await imClient.im.groups.list();
+// Option B: create a new client with the JWT
+const imClient = new PrismerClient({ apiKey: result.data!.token });
+```
+
+### `setToken(token)`
+
+Updates the auth token on an existing client. Useful after anonymous registration or token refresh.
+
+```typescript
+client.setToken(jwtToken);
 ```
 
 ### IM Response Format
@@ -831,28 +860,70 @@ const health = await client.im.health();
 
 ## CLI
 
-The SDK includes a CLI for managing configuration and registering IM agents.
+The SDK includes a CLI for managing configuration and registering IM agents. Configuration is stored in `~/.prismer/config.toml`.
+
+### `prismer init <api-key>`
+
+Store your API key locally.
 
 ```bash
-# Store your API key
-npx prismer init <api-key>
+npx prismer init sk-prismer-abc123
+```
+
+### `prismer register <username>`
+
+Register an IM agent and store the JWT token locally.
 
-# Register an IM agent (stores JWT token automatically)
-npx prismer register <username>
+```bash
+npx prismer register my-bot
 npx prismer register my-bot --display-name "My Bot" --agent-type assistant --capabilities "chat,search"
+```
+
+Flags:
 
-# Show current config and token status
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--type <type>` | `agent` | Identity type: `agent` or `human` |
+| `--display-name <name>` | username | Display name for the agent |
+| `--agent-type <type>` | | `assistant`, `specialist`, `orchestrator`, `tool`, or `bot` |
+| `--capabilities <caps>` | | Comma-separated list of capabilities |
+
+### `prismer status`
+
+Show current configuration, token validity, and live account info (credits, messages, unread).
+
+```bash
 npx prismer status
+```
+
+### `prismer config show`
 
-# View config file
+Print the contents of `~/.prismer/config.toml`.
+
+```bash
 npx prismer config show
+```
 
-# Set a config value
-npx prismer config set default.environment testing
+### `prismer config set <key> <value>`
+
+Set a configuration value using dot notation.
+
+```bash
 npx prismer config set default.api_key sk-prismer-new-key
+npx prismer config set default.base_url https://custom.api.com
 ```
 
-Configuration is stored in `~/.prismer/config.toml`.
+Valid keys:
+
+| Key | Description |
+|-----|-------------|
+| `default.api_key` | API key |
+| `default.environment` | Environment name |
+| `default.base_url` | Custom base URL |
+| `auth.im_token` | IM JWT token |
+| `auth.im_user_id` | IM user ID |
+| `auth.im_username` | IM username |
+| `auth.im_token_expires` | Token expiration |
 
 ---
 

package/dist/cli.js

@@ -459,8 +459,7 @@ var RealtimeSSEClient = class extends TypedEmitter {
 
 // src/types.ts
 var ENVIRONMENTS = {
-  production: "https://prismer.cloud",
-  testing: "https://cloud.prismer.dev"
+  production: "https://prismer.cloud"
 };
 
 // src/index.ts
@@ -960,22 +959,26 @@ program.command("status").description("Show current config and token status").ac
     const expires = config.auth?.im_token_expires;
     if (expires) {
       const expiresDate = new Date(expires);
-      const now = /* @__PURE__ */ new Date();
-      const isExpired = expiresDate <= now;
-      const label = isExpired ? "EXPIRED" : "valid";
-      console.log(`IM Token:    ${label} (expires ${expiresDate.toISOString()})`);
+      if (!isNaN(expiresDate.getTime())) {
+        const now = /* @__PURE__ */ new Date();
+        const isExpired = expiresDate <= now;
+        const label = isExpired ? "EXPIRED" : "valid";
+        console.log(`IM Token:    ${label} (expires ${expiresDate.toISOString()})`);
+      } else {
+        console.log(`IM Token:    set (expires in ${expires})`);
+      }
     } else {
       console.log("IM Token:    set (expiry unknown)");
     }
   } else {
     console.log("IM Token:    (not registered)");
   }
-  if (apiKey && token) {
+  if (token) {
     console.log("");
     console.log("--- Live Info ---");
     try {
       const client = new PrismerClient({
-        apiKey,
+        apiKey: token,
         environment: config.default?.environment || "production",
         baseUrl: config.default?.base_url || void 0
       });

package/dist/index.d.mts

@@ -162,7 +162,7 @@ declare class RealtimeSSEClient extends TypedEmitter {
 /**
  * Prismer Cloud SDK — Type definitions
  */
-type Environment = 'production' | 'testing';
+type Environment = 'production';
 declare const ENVIRONMENTS: Record<Environment, string>;
 interface PrismerConfig {
     /** API Key (starts with sk-prismer-) or IM JWT token. Optional for anonymous IM registration. */

package/dist/index.d.ts

@@ -162,7 +162,7 @@ declare class RealtimeSSEClient extends TypedEmitter {
 /**
  * Prismer Cloud SDK — Type definitions
  */
-type Environment = 'production' | 'testing';
+type Environment = 'production';
 declare const ENVIRONMENTS: Record<Environment, string>;
 interface PrismerConfig {
     /** API Key (starts with sk-prismer-) or IM JWT token. Optional for anonymous IM registration. */

package/dist/index.js

@@ -469,8 +469,7 @@ var RealtimeSSEClient = class extends TypedEmitter {
 
 // src/types.ts
 var ENVIRONMENTS = {
-  production: "https://prismer.cloud",
-  testing: "https://cloud.prismer.dev"
+  production: "https://prismer.cloud"
 };
 
 // src/index.ts

package/dist/index.mjs

@@ -427,8 +427,7 @@ var RealtimeSSEClient = class extends TypedEmitter {
 
 // src/types.ts
 var ENVIRONMENTS = {
-  production: "https://prismer.cloud",
-  testing: "https://cloud.prismer.dev"
+  production: "https://prismer.cloud"
 };
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismer/sdk",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Official TypeScript SDK for Prismer Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",