@erdoai/server 0.1.6 → 0.1.7

package/README.md

@@ -17,7 +17,7 @@ import { ErdoClient } from '@erdoai/server';
 
 const client = new ErdoClient({
   endpoint: 'https://api.erdo.ai',
-  authToken: process.env.ERDO_API_KEY,
+  authToken: process.env.ERDO_AUTH_TOKEN,
 });
 
 // Get final result
@@ -48,6 +48,63 @@ for await (const event of client.invokeStream('data-analyst', {
 }
 ```
 
+### Token Authentication (B2B)
+
+For B2B applications, create scoped tokens for your users:
+
+```typescript
+// Server-side: Create a scoped token
+const serverClient = new ErdoClient({
+  authToken: process.env.ERDO_AUTH_TOKEN,
+});
+
+const { token, expiresAt } = await serverClient.createToken({
+  botKeys: ['my-org.data-analyst'],
+  externalUserId: 'user_123',
+  expiresInSeconds: 3600,
+});
+
+// Client-side: Use the scoped token
+const clientClient = new ErdoClient({
+  endpoint: 'https://api.erdo.ai',
+  token: token,  // Scoped token instead of authToken
+});
+
+const result = await clientClient.invoke('my-org.data-analyst', {
+  messages: [{ role: 'user', content: 'Analyze my data' }],
+});
+```
+
+### Thread Management
+
+Threads provide persistent conversations. Requires token authentication with `externalUserId`:
+
+```typescript
+const client = new ErdoClient({
+  endpoint: 'https://api.erdo.ai',
+  token: scopedToken,
+});
+
+// Create a thread
+const thread = await client.createThread({ name: 'Data Analysis' });
+
+// List user's threads
+const { threads } = await client.listThreads();
+
+// Send a message and stream the response
+for await (const event of client.sendMessage(thread.id, {
+  content: 'What insights can you find?',
+  botKey: 'my-org.data-analyst',
+})) {
+  console.log(event.type, event.payload);
+}
+
+// Or wait for the complete response
+const events = await client.sendMessageAndWait(thread.id, {
+  content: 'Summarize recent trends',
+});
+```
+
 ### Environment Variables
 
 The client can be configured via environment variables:
@@ -70,11 +127,34 @@ const client = new ErdoClient();
 class ErdoClient {
   constructor(options?: {
     endpoint?: string;   // API endpoint (default: env or https://api.erdo.ai)
-    authToken?: string;  // API key (default: env ERDO_AUTH_TOKEN)
+    authToken?: string;  // API key for server-side (default: env ERDO_AUTH_TOKEN)
+    token?: string;      // Scoped token for client-side
   });
 
+  // Token creation (requires authToken)
+  createToken(params: CreateTokenParams): Promise<TokenResponse>;
+
+  // Agent invocation
   invoke(botKey: string, params: InvokeParams): Promise<InvokeResult>;
   invokeStream(botKey: string, params: InvokeParams): AsyncGenerator<SSEEvent>;
+
+  // Thread management (requires token with externalUserId)
+  createThread(params?: CreateThreadParams): Promise<Thread>;
+  listThreads(): Promise<ListThreadsResponse>;
+  getThread(threadId: string): Promise<Thread>;
+  sendMessage(threadId: string, params: SendMessageParams): AsyncGenerator<SSEEvent>;
+  sendMessageAndWait(threadId: string, params: SendMessageParams): Promise<SSEEvent[]>;
+}
+```
+
+### `CreateTokenParams`
+
+```typescript
+interface CreateTokenParams {
+  botKeys?: string[];        // Bot keys the token can access
+  datasetIds?: string[];     // Dataset IDs the token can access
+  externalUserId?: string;   // External user ID for RBAC (enables thread access)
+  expiresInSeconds?: number; // Token lifetime (default: 3600)
 }
 ```
 
@@ -89,6 +169,15 @@ interface InvokeParams {
 }
 ```
 
+### `SendMessageParams`
+
+```typescript
+interface SendMessageParams {
+  content: string;    // Message content
+  botKey?: string;    // Optional bot to use
+}
+```
+
 ### `SSEEvent`
 
 ```typescript

package/dist/index.d.ts

@@ -1,15 +1,110 @@
-import { ErdoClientConfig, InvokeParams, InvokeResult, SSEEvent } from '@erdoai/types';
+import { ErdoClientConfig, CreateTokenParams, TokenResponse, CreateThreadParams, Thread, ListThreadsResponse, SendMessageParams, SSEEvent, InvokeParams, InvokeResult } from '@erdoai/types';
 
 /**
  * Erdo Client for invoking agents
  *
+ * Supports two authentication modes:
+ * 1. authToken (API key) - for server-side requests, can create tokens
+ * 2. token (scoped token) - for client-side requests, limited to token scope
+ *
  * Ported from: erdo-python-sdk/erdo/invoke/client.py and invoke.py
  */
 
 declare class ErdoClient {
     private readonly endpoint;
-    private readonly authToken;
+    private readonly authToken?;
+    private readonly token?;
     constructor(config?: Partial<ErdoClientConfig>);
+    /**
+     * Create a scoped token for client-side use
+     *
+     * Requires authToken (API key) authentication.
+     * The returned token can be passed to a client-side ErdoClient for
+     * scoped access to specific bots.
+     *
+     * @example
+     * ```typescript
+     * // Server-side: Create a token for the frontend
+     * const serverClient = new ErdoClient({ authToken: process.env.ERDO_AUTH_TOKEN });
+     * const { token, expiresAt } = await serverClient.createToken({
+     *   botKeys: ['my-org.data-analyst'],
+     *   expiresInSeconds: 3600,
+     * });
+     *
+     * // Client-side: Use the token
+     * const clientClient = new ErdoClient({ endpoint: 'https://api.erdo.ai', token });
+     * const result = await clientClient.invoke('my-org.data-analyst', { messages: [...] });
+     * ```
+     */
+    createToken(params: CreateTokenParams): Promise<TokenResponse>;
+    /**
+     * Create a new thread for the external user
+     *
+     * Requires token authentication with external_user_id.
+     * The thread is automatically associated with the external user.
+     *
+     * @example
+     * ```typescript
+     * const thread = await client.createThread({ name: 'Support Chat' });
+     * console.log(thread.id, thread.name);
+     * ```
+     */
+    createThread(params?: CreateThreadParams): Promise<Thread>;
+    /**
+     * List threads for the external user
+     *
+     * Requires token authentication with external_user_id.
+     * Returns threads that the external user has access to via RBAC.
+     *
+     * @example
+     * ```typescript
+     * const { threads } = await client.listThreads();
+     * for (const thread of threads) {
+     *   console.log(thread.id, thread.name);
+     * }
+     * ```
+     */
+    listThreads(): Promise<ListThreadsResponse>;
+    /**
+     * Get a specific thread by ID
+     *
+     * Requires token authentication.
+     * Access is granted via RBAC external_user or explicit thread scope.
+     *
+     * @example
+     * ```typescript
+     * const thread = await client.getThread(threadId);
+     * console.log(thread.name, thread.createdAt);
+     * ```
+     */
+    getThread(threadId: string): Promise<Thread>;
+    /**
+     * Send a message to a thread and stream the bot response
+     *
+     * Requires token authentication.
+     * Access is granted via RBAC external_user or explicit thread scope.
+     *
+     * @example
+     * ```typescript
+     * for await (const event of client.sendMessage(threadId, { content: 'Hello!' })) {
+     *   console.log(event.type, event.payload);
+     * }
+     * ```
+     */
+    sendMessage(threadId: string, params: SendMessageParams): AsyncGenerator<SSEEvent, void, unknown>;
+    /**
+     * Send a message to a thread and wait for the complete response
+     *
+     * Requires token authentication.
+     * Returns all SSE events collected from the stream.
+     *
+     * @example
+     * ```typescript
+     * const events = await client.sendMessageAndWait(threadId, { content: 'Hello!' });
+     * console.log('Received', events.length, 'events');
+     * ```
+     */
+    sendMessageAndWait(threadId: string, params: SendMessageParams): Promise<SSEEvent[]>;
     /**
      * Invoke an agent and wait for the complete result
      */
@@ -67,14 +162,28 @@ declare function invokeStream(botKey: string, params?: InvokeParams): AsyncGener
  * Ported from: erdo-python-sdk/erdo/config/config.py
  */
 
+/**
+ * Resolved configuration - authToken is optional when using token
+ */
+interface ResolvedConfig {
+    endpoint: string;
+    authToken?: string;
+    token?: string;
+}
 /**
  * Get configuration from environment variables
  */
 declare function getConfigFromEnv(): ErdoClientConfig;
 /**
  * Merge user config with environment config
+ *
+ * Auth can be provided via:
+ * - authToken: API key for server-side use (can create tokens, full access)
+ * - token: Scoped token for client-side use (limited to token scope)
+ *
+ * At least one of authToken or token must be provided.
  */
-declare function resolveConfig(userConfig?: Partial<ErdoClientConfig>): Required<ErdoClientConfig>;
+declare function resolveConfig(userConfig?: Partial<ErdoClientConfig>): ResolvedConfig;
 
 /**
  * SSE Client for Server-Sent Events streaming
@@ -84,6 +193,13 @@ declare function resolveConfig(userConfig?: Partial<ErdoClientConfig>): Required
 
 /**
  * Parse SSE events from a ReadableStream
+ *
+ * SSE format:
+ *   event: <event-type>
+ *   data: <json-data>
+ *   <blank line>
+ *
+ * The event type is extracted from the "event:" line and added to the parsed data.
  */
 declare function parseSSEStream(response: Response): AsyncGenerator<SSEEvent, void, unknown>;
 /**

package/dist/index.js

@@ -1,2 +1,3 @@
-var y="https://api.erdo.ai";function S(){let o=typeof process<"u"?process.env:{};return {endpoint:o.ERDO_ENDPOINT||o.NEXT_PUBLIC_ERDO_ENDPOINT||y,authToken:o.ERDO_AUTH_TOKEN||o.NEXT_PUBLIC_ERDO_API_KEY}}function p(o){let t=S(),e=o?.endpoint||t.endpoint||y,s=o?.authToken||t.authToken;if(!s)throw new Error("No auth token configured. Set ERDO_AUTH_TOKEN environment variable or pass authToken to ErdoClient.");return {endpoint:e,authToken:s}}async function*d(o){if(!o.body)throw new Error("Response body is null");let t=o.body.getReader(),e=new TextDecoder,s="";try{for(;;){let{done:r,value:i}=await t.read();if(r){if(s.trim()){let a=h(s);a&&(yield a);}break}s+=e.decode(i,{stream:!0});let u=s.split(`
-`);s=u.pop()||"";for(let a of u){let l=h(a);l&&(yield l);}}}finally{t.releaseLock();}}function h(o){let t=o.trim();if(!t)return null;if(t.startsWith("data: ")){let e=t.slice(6);if(!e.trim())return null;try{return JSON.parse(e)}catch{return {raw:e}}}return null}async function v(o){let t=[];for await(let e of d(o))t.push(e);return t}var f=class{endpoint;authToken;constructor(t){let e=p(t);this.endpoint=e.endpoint,this.authToken=e.authToken;}async invoke(t,e={}){let s=await this.collectEvents(t,e);return this.extractResult(t,s)}async*invokeStream(t,e={}){let s=await this.makeRequest(t,e);yield*d(s);}async collectEvents(t,e){let s=await this.makeRequest(t,e);return v(s)}async makeRequest(t,e){let s=`${this.endpoint}/bots/${t}/invoke`,r={};e.messages&&(r.messages=e.messages),e.parameters&&(r.parameters=e.parameters),e.datasets&&(r.dataset_slugs=e.datasets),e.mode&&(r.mode=e.mode),e.manualMocks&&(r.manual_mocks=e.manualMocks);let i=await fetch(s,{method:"POST",headers:{Authorization:`Bearer ${this.authToken}`,"Content-Type":"application/json",Accept:"text/event-stream"},body:JSON.stringify(r)});if(!i.ok){let u=await i.text();throw new Error(`API request failed with status ${i.status}: ${u}`)}return i}extractResult(t,e){let s=[],r=[],i=new Set,u,a;for(let l of e){if(!l)continue;let n=l.payload,m=l.metadata;if(n&&typeof n=="object"&&"invocation_id"in n&&!a&&(a=n.invocation_id),n&&typeof n=="object"&&"action_type"in n&&"key"in n){let c=n.key;i.has(c)||(i.add(c),r.push({key:c,action:n.action_type,status:"completed"}));}if(n&&typeof n=="object"&&"output"in n&&m?.user_visibility==="visible"){let c=n.output;if(c&&typeof c=="object"&&"content"in c){let g=c.content;if(Array.isArray(g)){for(let k of g)if(k.content_type==="text"){let w=m?.role||"assistant";s.push({role:w,content:k.content||""});}}}}n&&typeof n=="object"&&"status"in n&&"output"in n&&(u={status:n.status,parameters:n.parameters,output:n.output,message:n.message,error:n.error});}return {success:true,botId:t,invocationId:a,result:u,messages:s,events:e,steps:r}}},E=null;function R(){return E||(E=new f),E}async function C(o,t={}){return R().invoke(o,t)}async function*T(o,t={}){yield*R().invokeStream(o,t);}export{f as ErdoClient,v as collectSSEEvents,S as getConfigFromEnv,C as invoke,T as invokeStream,d as parseSSEStream,p as resolveConfig};
+var v="https://api.erdo.ai";function E(){let i=typeof process<"u"?process.env:{};return {endpoint:i.ERDO_ENDPOINT||v,authToken:i.ERDO_AUTH_TOKEN}}function k(i){let e=E(),t=i?.endpoint||e.endpoint||v,o=i?.authToken||e.authToken,n=i?.token;return {endpoint:t,authToken:o,token:n}}async function*f(i){if(!i.body)throw new Error("Response body is null");let e=i.body.getReader(),t=new TextDecoder,o="",n,s;try{for(;;){let{done:a,value:u}=await e.read();if(a){if(s!==void 0){let r=w(n,s);r&&(yield r);}break}o+=t.decode(u,{stream:!0});let h=o.split(`
+`);o=h.pop()||"";for(let r of h){let c=r.trim();if(!c){if(s!==void 0){let d=w(n,s);d&&(yield d),n=void 0,s=void 0;}continue}if(c.startsWith("event:"))n=c.slice(6).trim();else if(c.startsWith("data:")){let d=c.slice(5).trim();s===void 0?s=d:s+=`
+`+d;}}}}finally{e.releaseLock();}}function w(i,e){if(!e)return null;try{let t=JSON.parse(e);return i&&(t.type=i),t}catch{return {type:i,raw:e}}}async function p(i){let e=[];for await(let t of f(i))e.push(t);return e}var l=class{endpoint;authToken;token;constructor(e){let t=k(e);if(this.endpoint=t.endpoint,this.authToken=t.authToken,this.token=t.token,!this.authToken&&!this.token)throw new Error("Either authToken or token is required")}async createToken(e){if(!this.authToken)throw new Error("createToken requires authToken (API key) authentication");let t=`${this.endpoint}/tokens`,o={};e.botKeys&&(o.bot_keys=e.botKeys),e.datasetIds&&(o.dataset_ids=e.datasetIds),e.externalUserId&&(o.external_user_id=e.externalUserId),e.expiresInSeconds&&(o.expires_in_seconds=e.expiresInSeconds);let n=await fetch(t,{method:"POST",headers:{Authorization:`Bearer ${this.authToken}`,"Content-Type":"application/json"},body:JSON.stringify(o)});if(!n.ok){let a=await n.text();throw new Error(`Failed to create token: ${n.status}: ${a}`)}let s=await n.json();return {token:s.token,expiresAt:s.expires_at}}async createThread(e={}){if(!this.token)throw new Error("createThread requires token authentication");let t=`${this.endpoint}/threads`,o={};e.name&&(o.name=e.name),e.datasetIds&&(o.dataset_ids=e.datasetIds);let n=await fetch(t,{method:"POST",headers:{Authorization:`Bearer ${this.token}`,"Content-Type":"application/json"},body:JSON.stringify(o)});if(!n.ok){let a=await n.text();throw new Error(`Failed to create thread: ${n.status}: ${a}`)}let s=await n.json();return {id:s.id,name:s.name,createdAt:s.created_at,updatedAt:s.updated_at}}async listThreads(){if(!this.token)throw new Error("listThreads requires token authentication");let e=`${this.endpoint}/threads-user`,t=await fetch(e,{method:"GET",headers:{Authorization:`Bearer ${this.token}`}});if(!t.ok){let n=await t.text();throw new Error(`Failed to list threads: ${t.status}: ${n}`)}return {threads:(await t.json()).threads.map(n=>({id:n.id,name:n.name,createdAt:n.created_at,updatedAt:n.updated_at}))}}async getThread(e){if(!this.token)throw new Error("getThread requires token authentication");let t=`${this.endpoint}/threads/${e}`,o=await fetch(t,{method:"GET",headers:{Authorization:`Bearer ${this.token}`}});if(!o.ok){let s=await o.text();throw new Error(`Failed to get thread: ${o.status}: ${s}`)}let n=await o.json();return {id:n.id,name:n.name,createdAt:n.created_at,updatedAt:n.updated_at}}async*sendMessage(e,t){if(!this.token)throw new Error("sendMessage requires token authentication");let o=`${this.endpoint}/threads/${e}/message`,n={content:t.content};t.botKey&&(n.bot_key=t.botKey);let s=await fetch(o,{method:"POST",headers:{Authorization:`Bearer ${this.token}`,"Content-Type":"application/json",Accept:"text/event-stream"},body:JSON.stringify(n)});if(!s.ok){let a=await s.text();throw new Error(`Failed to send message: ${s.status}: ${a}`)}yield*f(s);}async sendMessageAndWait(e,t){if(!this.token)throw new Error("sendMessageAndWait requires token authentication");let o=`${this.endpoint}/threads/${e}/message`,n={content:t.content};t.botKey&&(n.bot_key=t.botKey);let s=await fetch(o,{method:"POST",headers:{Authorization:`Bearer ${this.token}`,"Content-Type":"application/json",Accept:"text/event-stream"},body:JSON.stringify(n)});if(!s.ok){let a=await s.text();throw new Error(`Failed to send message: ${s.status}: ${a}`)}return p(s)}async invoke(e,t={}){let o=await this.collectEvents(e,t);return this.extractResult(e,o)}async*invokeStream(e,t={}){let o=await this.makeRequest(e,t);yield*f(o);}async collectEvents(e,t){let o=await this.makeRequest(e,t);return p(o)}async makeRequest(e,t){let o=`${this.endpoint}/bots/${e}/invoke`,n={};t.messages&&(n.messages=t.messages),t.parameters&&(n.parameters=t.parameters),t.datasets&&(n.dataset_slugs=t.datasets),t.mode&&(n.mode=t.mode),t.manualMocks&&(n.manual_mocks=t.manualMocks);let s=this.token||this.authToken,a=await fetch(o,{method:"POST",headers:{Authorization:`Bearer ${s}`,"Content-Type":"application/json",Accept:"text/event-stream"},body:JSON.stringify(n)});if(!a.ok){let u=await a.text();throw new Error(`API request failed with status ${a.status}: ${u}`)}return a}extractResult(e,t){let o=[],n=[],s=new Set,a,u;for(let h of t){if(!h)continue;let r=h.payload,c=h.metadata;if(r&&typeof r=="object"&&"invocation_id"in r&&!u&&(u=r.invocation_id),r&&typeof r=="object"&&"action_type"in r&&"key"in r){let d=r.key;s.has(d)||(s.add(d),n.push({key:d,action:r.action_type,status:"completed"}));}if(r&&typeof r=="object"&&"output"in r&&c?.user_visibility==="visible"){let d=r.output;if(d&&typeof d=="object"&&"content"in d){let y=d.content;if(Array.isArray(y)){for(let m of y)if(m.content_type==="text"){let T=c?.role||"assistant";o.push({role:T,content:m.content||""});}}}}r&&typeof r=="object"&&"status"in r&&"output"in r&&(a={status:r.status,parameters:r.parameters,output:r.output,message:r.message,error:r.error});}return {success:true,botKey:e,invocationId:u,result:a,messages:o,events:t,steps:n}}},g=null;function S(){return g||(g=new l),g}async function x(i,e={}){return S().invoke(i,e)}async function*P(i,e={}){yield*S().invokeStream(i,e);}export{l as ErdoClient,p as collectSSEEvents,E as getConfigFromEnv,x as invoke,P as invokeStream,f as parseSSEStream,k as resolveConfig};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erdoai/server",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Erdo server SDK for invoking agents",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,7 +39,7 @@
     "directory": "packages/server"
   },
   "dependencies": {
-    "@erdoai/types": "^0.1.5"
+    "@erdoai/types": "^0.1.6"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",