@prismer/sdk 1.1.0 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @prismer/sdk
 
-Official TypeScript/JavaScript SDK for the Prismer Cloud API (v1.0.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:
+
+**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):**
 
-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:
+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
@@ -488,7 +517,76 @@ const history = await client.im.direct.getMessages('user-123', {
 });
 ```
 
-Message types: `text`, `markdown`, `code`, `system_event`.
+Message types: `text`, `markdown`, `code`, `system_event`, `tool_call`, `tool_result`, `thinking`, `image`, `file`.
+
+#### Message Threading (v3.4.0)
+
+Reply to a specific message by passing `parentId`:
+
+```typescript
+// Send a threaded reply in a DM
+await client.im.direct.send('user-123', 'Replying to your message', {
+  parentId: 'msg-456',
+});
+
+// Threaded reply in a group
+await client.im.groups.send('group-123', 'Thread reply', {
+  parentId: 'msg-789',
+});
+
+// Low-level threaded reply
+await client.im.messages.send('conv-123', 'Thread reply', {
+  parentId: 'msg-789',
+});
+```
+
+#### Advanced Message Types (v3.4.0)
+
+```typescript
+// Tool call (for agent-to-agent tool invocation)
+await client.im.direct.send('agent-456', '{"tool":"search","query":"quantum computing"}', {
+  type: 'tool_call',
+  metadata: { toolName: 'search', toolCallId: 'tc-001' },
+});
+
+// Tool result (response to a tool call)
+await client.im.direct.send('agent-456', '{"results":[...]}', {
+  type: 'tool_result',
+  metadata: { toolCallId: 'tc-001', status: 'success' },
+});
+
+// Thinking (chain-of-thought)
+await client.im.direct.send('user-123', 'Analyzing the data...', {
+  type: 'thinking',
+});
+
+// Image
+await client.im.direct.send('user-123', 'https://example.com/chart.png', {
+  type: 'image',
+  metadata: { alt: 'Sales chart Q4' },
+});
+
+// File
+await client.im.direct.send('user-123', 'https://example.com/report.pdf', {
+  type: 'file',
+  metadata: { filename: 'report.pdf', mimeType: 'application/pdf' },
+});
+```
+
+#### Structured Metadata (v3.4.0)
+
+Attach arbitrary metadata to any message:
+
+```typescript
+await client.im.direct.send('user-123', 'Analysis complete', {
+  metadata: {
+    source: 'research-agent',
+    priority: 'high',
+    tags: ['analysis', 'completed'],
+    model: 'gpt-4',
+  },
+});
+```
 
 ---
 
@@ -779,7 +877,7 @@ npx prismer status
 npx prismer config show
 
 # Set a config value
-npx prismer config set default.environment testing
+npx prismer config set default.base_url https://custom.api.com
 npx prismer config set default.api_key sk-prismer-new-key
 ```
 

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
@@ -717,14 +716,11 @@ var IMClient = class {
   }
 };
 var PrismerClient = class {
-  constructor(config) {
-    if (!config.apiKey) {
-      throw new Error("apiKey is required");
-    }
-    if (!config.apiKey.startsWith("sk-prismer-") && !config.apiKey.startsWith("eyJ")) {
+  constructor(config = {}) {
+    if (config.apiKey && !config.apiKey.startsWith("sk-prismer-") && !config.apiKey.startsWith("eyJ")) {
       console.warn('Warning: API key should start with "sk-prismer-" (or "eyJ" for IM JWT)');
     }
-    this.apiKey = config.apiKey;
+    this.apiKey = config.apiKey || "";
     const envUrl = ENVIRONMENTS[config.environment || "production"];
     this.baseUrl = (config.baseUrl || envUrl).replace(/\/$/, "");
     this.timeout = config.timeout || 3e4;
@@ -735,6 +731,13 @@ var PrismerClient = class {
       this.baseUrl
     );
   }
+  /**
+   * Set or update the auth token (API key or IM JWT).
+   * Useful after anonymous registration to set the returned JWT.
+   */
+  setToken(token) {
+    this.apiKey = token;
+  }
   // --------------------------------------------------------------------------
   // Internal request helper
   // --------------------------------------------------------------------------
@@ -746,9 +749,10 @@ var PrismerClient = class {
       if (query && Object.keys(query).length > 0) {
         url += "?" + new URLSearchParams(query).toString();
       }
-      const headers = {
-        "Authorization": `Bearer ${this.apiKey}`
-      };
+      const headers = {};
+      if (this.apiKey) {
+        headers["Authorization"] = `Bearer ${this.apiKey}`;
+      }
       if (this.imAgent) {
         headers["X-IM-Agent"] = this.imAgent;
       }

package/dist/index.d.mts

@@ -162,11 +162,11 @@ 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 */
-    apiKey: string;
+    /** API Key (starts with sk-prismer-) or IM JWT token. Optional for anonymous IM registration. */
+    apiKey?: string;
     /** Environment preset (default: 'production'). Sets the base URL automatically. */
     environment?: Environment;
     /** Base URL override. Takes priority over `environment` if both are set. */
@@ -716,14 +716,19 @@ declare class IMClient {
     health(): Promise<IMResult<void>>;
 }
 declare class PrismerClient {
-    private readonly apiKey;
+    private apiKey;
     private readonly baseUrl;
     private readonly timeout;
     private readonly fetchFn;
     private readonly imAgent?;
     /** IM API sub-client */
     readonly im: IMClient;
-    constructor(config: PrismerConfig);
+    constructor(config?: PrismerConfig);
+    /**
+     * Set or update the auth token (API key or IM JWT).
+     * Useful after anonymous registration to set the returned JWT.
+     */
+    setToken(token: string): void;
     private _request;
     /** Load content from URL(s) or search query */
     load(input: string | string[], options?: LoadOptions): Promise<LoadResult>;

package/dist/index.d.ts

@@ -162,11 +162,11 @@ 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 */
-    apiKey: string;
+    /** API Key (starts with sk-prismer-) or IM JWT token. Optional for anonymous IM registration. */
+    apiKey?: string;
     /** Environment preset (default: 'production'). Sets the base URL automatically. */
     environment?: Environment;
     /** Base URL override. Takes priority over `environment` if both are set. */
@@ -716,14 +716,19 @@ declare class IMClient {
     health(): Promise<IMResult<void>>;
 }
 declare class PrismerClient {
-    private readonly apiKey;
+    private apiKey;
     private readonly baseUrl;
     private readonly timeout;
     private readonly fetchFn;
     private readonly imAgent?;
     /** IM API sub-client */
     readonly im: IMClient;
-    constructor(config: PrismerConfig);
+    constructor(config?: PrismerConfig);
+    /**
+     * Set or update the auth token (API key or IM JWT).
+     * Useful after anonymous registration to set the returned JWT.
+     */
+    setToken(token: string): void;
     private _request;
     /** Load content from URL(s) or search query */
     load(input: string | string[], options?: LoadOptions): Promise<LoadResult>;

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
@@ -727,14 +726,11 @@ var IMClient = class {
   }
 };
 var PrismerClient = class {
-  constructor(config) {
-    if (!config.apiKey) {
-      throw new Error("apiKey is required");
-    }
-    if (!config.apiKey.startsWith("sk-prismer-") && !config.apiKey.startsWith("eyJ")) {
+  constructor(config = {}) {
+    if (config.apiKey && !config.apiKey.startsWith("sk-prismer-") && !config.apiKey.startsWith("eyJ")) {
       console.warn('Warning: API key should start with "sk-prismer-" (or "eyJ" for IM JWT)');
     }
-    this.apiKey = config.apiKey;
+    this.apiKey = config.apiKey || "";
     const envUrl = ENVIRONMENTS[config.environment || "production"];
     this.baseUrl = (config.baseUrl || envUrl).replace(/\/$/, "");
     this.timeout = config.timeout || 3e4;
@@ -745,6 +741,13 @@ var PrismerClient = class {
       this.baseUrl
     );
   }
+  /**
+   * Set or update the auth token (API key or IM JWT).
+   * Useful after anonymous registration to set the returned JWT.
+   */
+  setToken(token) {
+    this.apiKey = token;
+  }
   // --------------------------------------------------------------------------
   // Internal request helper
   // --------------------------------------------------------------------------
@@ -756,9 +759,10 @@ var PrismerClient = class {
       if (query && Object.keys(query).length > 0) {
         url += "?" + new URLSearchParams(query).toString();
       }
-      const headers = {
-        "Authorization": `Bearer ${this.apiKey}`
-      };
+      const headers = {};
+      if (this.apiKey) {
+        headers["Authorization"] = `Bearer ${this.apiKey}`;
+      }
       if (this.imAgent) {
         headers["X-IM-Agent"] = this.imAgent;
       }

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
@@ -685,14 +684,11 @@ var IMClient = class {
   }
 };
 var PrismerClient = class {
-  constructor(config) {
-    if (!config.apiKey) {
-      throw new Error("apiKey is required");
-    }
-    if (!config.apiKey.startsWith("sk-prismer-") && !config.apiKey.startsWith("eyJ")) {
+  constructor(config = {}) {
+    if (config.apiKey && !config.apiKey.startsWith("sk-prismer-") && !config.apiKey.startsWith("eyJ")) {
       console.warn('Warning: API key should start with "sk-prismer-" (or "eyJ" for IM JWT)');
     }
-    this.apiKey = config.apiKey;
+    this.apiKey = config.apiKey || "";
     const envUrl = ENVIRONMENTS[config.environment || "production"];
     this.baseUrl = (config.baseUrl || envUrl).replace(/\/$/, "");
     this.timeout = config.timeout || 3e4;
@@ -703,6 +699,13 @@ var PrismerClient = class {
       this.baseUrl
     );
   }
+  /**
+   * Set or update the auth token (API key or IM JWT).
+   * Useful after anonymous registration to set the returned JWT.
+   */
+  setToken(token) {
+    this.apiKey = token;
+  }
   // --------------------------------------------------------------------------
   // Internal request helper
   // --------------------------------------------------------------------------
@@ -714,9 +717,10 @@ var PrismerClient = class {
       if (query && Object.keys(query).length > 0) {
         url += "?" + new URLSearchParams(query).toString();
       }
-      const headers = {
-        "Authorization": `Bearer ${this.apiKey}`
-      };
+      const headers = {};
+      if (this.apiKey) {
+        headers["Authorization"] = `Bearer ${this.apiKey}`;
+      }
       if (this.imAgent) {
         headers["X-IM-Agent"] = this.imAgent;
       }

package/package.json

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