@qelos/sdk 3.11.10 → 4.0.0

package/README.md

@@ -86,4 +86,35 @@ function MyPostsList() {
 }
 ```
 
+### Authentication
+
+The `sdk.authentication` namespace exposes signin/signup, token refresh,
+social-auth, and the current-user accessor.
+
+```typescript
+// Username + password
+const { payload, headers } = await sdk.authentication.signin({
+  username: 'jane',
+  password: 'secret',
+});
+// headers['set-cookie'] — auth cookie issued by Qelos
+
+// Refresh an access + refresh token pair (oauth-style)
+await sdk.authentication.refreshToken();
+
+// Refresh a cookie-token session (used by integrator-hosted apps that keep
+// the user signed in via an HttpOnly cookie). Returns the rotated cookie
+// and the refreshed user — forward `set-cookie` to your downstream response.
+const result = await sdk.authentication.refreshCookieToken();
+// result.headers['set-cookie'] — new cookie value to forward
+// result.payload.user           — refreshed user
+// result.payload.cookieToken    — raw token (also embedded in set-cookie)
+```
+
+When a server-side host (`integrator-express`, `-next`, `-nuxt`, `-fastify`,
+`-nest`) wraps the SDK, `refreshCookieToken()` is called automatically on
+expired cookie-only sessions and the rotated cookie is written back to the
+outbound response. Call it directly only when you need to refresh
+proactively — e.g. before handing the session off to another service.
+
 Enjoy!

package/dist/__tests__/blueprints.types.test-d.d.ts

@@ -0,0 +1,28 @@
+import type { IBaseBlueprintEntity } from '../blueprints-entities';
+import type QlBlueprintEntities from '../blueprints-entities';
+interface TodoProperties {
+    title: string;
+    done: boolean;
+}
+interface TodoEntity extends IBaseBlueprintEntity, TodoProperties {
+}
+declare module '../blueprints' {
+    interface BlueprintEntitiesRegistry {
+        todo: TodoEntity;
+    }
+}
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+type Expect<T extends true> = T;
+declare const todos: QlBlueprintEntities<TodoEntity>;
+type TodosCheck = Expect<Equal<typeof todos, QlBlueprintEntities<TodoEntity>>>;
+declare const found: Awaited<ReturnType<typeof todos.find>>;
+type FoundCheck = Expect<Equal<typeof found, (IBaseBlueprintEntity & TodoEntity)[]>>;
+interface AdHoc {
+    name: string;
+}
+declare const adhoc: QlBlueprintEntities<AdHoc>;
+type AdHocCheck = Expect<Equal<typeof adhoc, QlBlueprintEntities<AdHoc>>>;
+declare const loose: QlBlueprintEntities<any>;
+type LooseCheck = Expect<Equal<typeof loose, QlBlueprintEntities<any>>>;
+export type _Checks = [TodosCheck, FoundCheck, AdHocCheck, LooseCheck];
+export {};

package/dist/__tests__/blueprints.types.test-d.js

@@ -0,0 +1,11 @@
+// Compile-only type test for `BlueprintEntitiesRegistry` augmentation
+// and the overloaded `entitiesOf` signatures. Runs as part of `tsc --noEmit`
+// (type-check / build); not executed by `node --test`.
+// 1. Registry-keyed lookup resolves to the augmented entity type.
+const todos = blueprints.entitiesOf('todo');
+const adhoc = blueprints.entitiesOf('not-in-registry');
+// 3. Plain string key with no generic falls back to `any` (legacy behavior).
+const dynamicKey = 'todo';
+const loose = blueprints.entitiesOf(dynamicKey);
+export {};
+//# sourceMappingURL=blueprints.types.test-d.js.map

package/dist/__tests__/blueprints.types.test-d.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blueprints.types.test-d.js","sourceRoot":"","sources":["../../src/__tests__/blueprints.types.test-d.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,6EAA6E;AAC7E,uDAAuD;AAyBvD,kEAAkE;AAClE,MAAM,KAAK,GAAG,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AAW5C,MAAM,KAAK,GAAG,UAAU,CAAC,UAAU,CAAQ,iBAAiB,CAAC,CAAC;AAG9D,6EAA6E;AAC7E,MAAM,UAAU,GAAW,MAAM,CAAC;AAClC,MAAM,KAAK,GAAG,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC"}

package/dist/administrator/events.d.ts

@@ -3,6 +3,7 @@ import BaseSDK from '../base-sdk';
 export interface IQelosEvent {
     tenant: string;
     user?: string;
+    workspace?: string;
     source: string;
     kind: string;
     eventName: string;
@@ -15,12 +16,16 @@ export default class QlEvents extends BaseSDK {
     constructor(options: QelosSDKOptions);
     getList(params?: {
         page?: number;
+        limit?: number;
         kind?: string;
         eventName?: string;
         source?: string;
         user?: string;
         workspace?: string;
+        search?: string;
         period?: string;
+        from?: string;
+        to?: string;
     }): Promise<IQelosEvent[]>;
     getEvent(eventId: string): Promise<IQelosEvent>;
     dispatch(payload: Partial<IQelosEvent>): Promise<void>;

package/dist/administrator/events.js

@@ -8,6 +8,8 @@ export default class QlEvents extends BaseSDK {
         const queryParams = new URLSearchParams();
         if (params?.page !== undefined)
             queryParams.append('page', params.page.toString());
+        if (params?.limit !== undefined)
+            queryParams.append('limit', params.limit.toString());
         if (params?.kind)
             queryParams.append('kind', params.kind);
         if (params?.eventName)
@@ -18,8 +20,14 @@ export default class QlEvents extends BaseSDK {
             queryParams.append('user', params.user);
         if (params?.workspace)
             queryParams.append('workspace', params.workspace);
+        if (params?.search)
+            queryParams.append('search', params.search);
         if (params?.period)
             queryParams.append('period', params.period);
+        if (params?.from)
+            queryParams.append('from', params.from);
+        if (params?.to)
+            queryParams.append('to', params.to);
         const queryString = queryParams.toString();
         return this.callJsonApi(this.relativePath + (queryString ? '?' + queryString : ''));
     }

package/dist/administrator/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/administrator/events.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,aAAa,CAAC;AAalC,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,OAAO;IACnC,YAAY,GAAG,aAAa,CAAC;IAErC,YAAY,OAAwB;QAClC,KAAK,CAAC,OAAO,CAAC,CAAA;IAChB,CAAC;IAED,OAAO,CAAC,MAAkI;QACxI,MAAM,WAAW,GAAG,IAAI,eAAe,EAAE,CAAC;QAC1C,IAAI,MAAM,EAAE,IAAI,KAAK,SAAS;YAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACnF,IAAI,MAAM,EAAE,IAAI;YAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1D,IAAI,MAAM,EAAE,SAAS;YAAE,WAAW,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACzE,IAAI,MAAM,EAAE,MAAM;YAAE,WAAW,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAChE,IAAI,MAAM,EAAE,IAAI;YAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1D,IAAI,MAAM,EAAE,SAAS;YAAE,WAAW,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACzE,IAAI,MAAM,EAAE,MAAM;YAAE,WAAW,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAEhE,MAAM,WAAW,GAAG,WAAW,CAAC,QAAQ,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAC,WAAW,CAAgB,IAAI,CAAC,YAAY,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrG,CAAC;IAED,QAAQ,CAAC,OAAe;QACtB,OAAO,IAAI,CAAC,WAAW,CAAc,IAAI,CAAC,YAAY,GAAG,GAAG,GAAG,OAAO,CAAC,CAAA;IACzE,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,OAA6B;QAC1C,MAAM,IAAI,CAAC,OAAO,CAChB,IAAI,CAAC,YAAY,EACjB;YACE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAC,cAAc,EAAE,kBAAkB,EAAC;YAC7C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;SAC9B,CACF,CAAA;IACH,CAAC;CACF"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/administrator/events.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,aAAa,CAAC;AAclC,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,OAAO;IACnC,YAAY,GAAG,aAAa,CAAC;IAErC,YAAY,OAAwB;QAClC,KAAK,CAAC,OAAO,CAAC,CAAA;IAChB,CAAC;IAED,OAAO,CAAC,MAA+L;QACrM,MAAM,WAAW,GAAG,IAAI,eAAe,EAAE,CAAC;QAC1C,IAAI,MAAM,EAAE,IAAI,KAAK,SAAS;YAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACnF,IAAI,MAAM,EAAE,KAAK,KAAK,SAAS;YAAE,WAAW,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QACtF,IAAI,MAAM,EAAE,IAAI;YAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1D,IAAI,MAAM,EAAE,SAAS;YAAE,WAAW,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACzE,IAAI,MAAM,EAAE,MAAM;YAAE,WAAW,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAChE,IAAI,MAAM,EAAE,IAAI;YAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1D,IAAI,MAAM,EAAE,SAAS;YAAE,WAAW,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACzE,IAAI,MAAM,EAAE,MAAM;YAAE,WAAW,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAChE,IAAI,MAAM,EAAE,MAAM;YAAE,WAAW,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAChE,IAAI,MAAM,EAAE,IAAI;YAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1D,IAAI,MAAM,EAAE,EAAE;YAAE,WAAW,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAEpD,MAAM,WAAW,GAAG,WAAW,CAAC,QAAQ,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAC,WAAW,CAAgB,IAAI,CAAC,YAAY,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrG,CAAC;IAED,QAAQ,CAAC,OAAe;QACtB,OAAO,IAAI,CAAC,WAAW,CAAc,IAAI,CAAC,YAAY,GAAG,GAAG,GAAG,OAAO,CAAC,CAAA;IACzE,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,OAA6B;QAC1C,MAAM,IAAI,CAAC,OAAO,CAChB,IAAI,CAAC,YAAY,EACjB;YACE,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAC,cAAc,EAAE,kBAAkB,EAAC;YAC7C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;SAC9B,CACF,CAAA;IACH,CAAC;CACF"}

package/dist/administrator/workspaces.d.ts

@@ -5,7 +5,14 @@ export default class QlAdminWorkspaces extends BaseSDK {
     private options;
     private relativePath;
     constructor(options: QelosSDKOptions);
-    getList(): Promise<IWorkspace[]>;
+    getList(filters?: {
+        'members.user'?: string;
+        labels?: string[];
+        name?: string;
+        q?: string;
+        _id?: string[];
+        select?: string;
+    }): Promise<IWorkspace[]>;
     getEncryptedData<Z = any>(workspaceId: string, encryptedId?: string): Promise<Z>;
     setEncryptedData<Z = any>(workspaceId: string, encryptedId: string, data: Z): Promise<void>;
 }

package/dist/administrator/workspaces.js

@@ -6,8 +6,13 @@ export default class QlAdminWorkspaces extends BaseSDK {
         super(options);
         this.options = options;
     }
-    getList() {
-        return this.callJsonApi(this.relativePath + '/all');
+    getList(filters) {
+        const queryParams = filters
+            ? `?${Object.entries(filters)
+                .filter(([, value]) => value !== undefined)
+                .map(([key, value]) => Array.isArray(value) ? `${key}=${value.join(',')}` : `${key}=${value}`).join('&')}`
+            : '';
+        return this.callJsonApi(this.relativePath + '/all' + queryParams);
     }
     getEncryptedData(workspaceId, encryptedId = '') {
         return this.callJsonApi(`${this.relativePath}/${workspaceId}/encrypted`, {

package/dist/administrator/workspaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspaces.js","sourceRoot":"","sources":["../../src/administrator/workspaces.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,aAAa,CAAC;AAGlC,MAAM,CAAC,OAAO,OAAO,iBAAkB,SAAQ,OAAO;IAGhC;IAFZ,YAAY,GAAG,iBAAiB,CAAC;IAEzC,YAAoB,OAAwB;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAA;QADI,YAAO,GAAP,OAAO,CAAiB;IAE5C,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,WAAW,CAAe,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,CAAC;IACpE,CAAC;IAED,gBAAgB,CAAU,WAAmB,EAAE,cAAsB,EAAE;QACrE,OAAO,IAAI,CAAC,WAAW,CAAI,GAAG,IAAI,CAAC,YAAY,IAAI,WAAW,YAAY,EAAE;YAC1E,OAAO,EAAE;gBACP,gBAAgB,EAAE,WAAW;aAC9B;SACF,CAAC,CAAA;IACJ,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAU,WAAmB,EAAE,cAAsB,EAAE,EAAE,IAAO;QACpF,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,YAAY,IAAI,WAAW,YAAY,EAAE;YAC9E,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,WAAW,EAAE;YAC9E,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAA;QACF,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,EAAE;YACrB,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAA;SAChD;IACH,CAAC;CACF"}
+{"version":3,"file":"workspaces.js","sourceRoot":"","sources":["../../src/administrator/workspaces.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,aAAa,CAAC;AAGlC,MAAM,CAAC,OAAO,OAAO,iBAAkB,SAAQ,OAAO;IAGhC;IAFZ,YAAY,GAAG,iBAAiB,CAAC;IAEzC,YAAoB,OAAwB;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAA;QADI,YAAO,GAAP,OAAO,CAAiB;IAE5C,CAAC;IAED,OAAO,CAAC,OAAoH;QAC1H,MAAM,WAAW,GAAG,OAAO;YACzB,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;iBAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC;iBAC1C,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CACpB,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,KAAK,EAAE,CACvE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;YACf,CAAC,CAAC,EAAE,CAAC;QAEP,OAAO,IAAI,CAAC,WAAW,CAAe,IAAI,CAAC,YAAY,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;IAClF,CAAC;IAED,gBAAgB,CAAU,WAAmB,EAAE,cAAsB,EAAE;QACrE,OAAO,IAAI,CAAC,WAAW,CAAI,GAAG,IAAI,CAAC,YAAY,IAAI,WAAW,YAAY,EAAE;YAC1E,OAAO,EAAE;gBACP,gBAAgB,EAAE,WAAW;aAC9B;SACF,CAAC,CAAA;IACJ,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAU,WAAmB,EAAE,cAAsB,EAAE,EAAE,IAAO;QACpF,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,YAAY,IAAI,WAAW,YAAY,EAAE;YAC9E,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,WAAW,EAAE;YAC9E,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAA;QACF,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,EAAE;YACrB,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAA;SAChD;IACH,CAAC;CACF"}

package/dist/ai/agents.d.ts

@@ -0,0 +1,56 @@
+import BaseSDK from '../base-sdk';
+import { QelosSDKOptions } from '../types';
+import ChatSDK from './chat';
+import { IAgent, IAgentChatOptions, IChatCompletionResponse, ICreateAgentRequest, ISSEStreamProcessor, IUpdateAgentRequest } from '.';
+export default class AgentsSDK extends BaseSDK {
+    private chatSdk;
+    private relativePath;
+    constructor(options: QelosSDKOptions, chatSdk: ChatSDK);
+    /**
+     * List available AI agents for the current tenant
+     */
+    list(query?: {
+        active?: boolean;
+        kind?: string;
+        limit?: number;
+        page?: number;
+        sort?: string;
+        [key: string]: string | number | boolean;
+    }): Promise<IAgent[]>;
+    /**
+     * Get a specific agent by ID (model, tools, system prompt, etc.)
+     */
+    get(agentId: string): Promise<IAgent>;
+    /**
+     * Create a new agent (chat-completion integration)
+     */
+    create(data: ICreateAgentRequest): Promise<IAgent>;
+    /**
+     * Update agent configuration
+     */
+    update(agentId: string, data: IUpdateAgentRequest): Promise<IAgent>;
+    /**
+     * Delete an agent
+     */
+    remove(agentId: string): Promise<{
+        success: boolean;
+        message?: string;
+    }>;
+    /**
+     * Send messages to an agent (non-streaming). The service creates a thread unless `threadId` is passed.
+     */
+    chat(agentId: string, message: string, options?: IAgentChatOptions): Promise<IChatCompletionResponse>;
+    /**
+     * Stream a response via GET + SSE (`/api/ai/agents/:id/chat`).
+     */
+    streamChat(agentId: string, message: string, options?: IAgentChatOptions): Promise<ISSEStreamProcessor>;
+    /**
+     * Continue in an existing thread (non-streaming)
+     */
+    chatInThread(agentId: string, threadId: string, message: string, options?: IAgentChatOptions): Promise<IChatCompletionResponse>;
+    /**
+     * Stream within an existing thread (GET + SSE)
+     */
+    streamChatInThread(agentId: string, threadId: string, message: string, options?: IAgentChatOptions): Promise<ISSEStreamProcessor>;
+    private openAgentChatStream;
+}

package/dist/ai/agents.js

@@ -0,0 +1,116 @@
+import BaseSDK from '../base-sdk';
+export default class AgentsSDK extends BaseSDK {
+    chatSdk;
+    relativePath = '/api/ai/agents';
+    constructor(options, chatSdk) {
+        super(options);
+        this.chatSdk = chatSdk;
+    }
+    /**
+     * List available AI agents for the current tenant
+     */
+    list(query) {
+        return this.callJsonApi(`${this.relativePath}${this.getQueryParams(query)}`);
+    }
+    /**
+     * Get a specific agent by ID (model, tools, system prompt, etc.)
+     */
+    get(agentId) {
+        return this.callJsonApi(`${this.relativePath}/${agentId}${this.getQueryParams({})}`);
+    }
+    /**
+     * Create a new agent (chat-completion integration)
+     */
+    create(data) {
+        return this.callJsonApi(`${this.relativePath}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(data),
+        });
+    }
+    /**
+     * Update agent configuration
+     */
+    update(agentId, data) {
+        return this.callJsonApi(`${this.relativePath}/${agentId}`, {
+            method: 'PUT',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(data),
+        });
+    }
+    /**
+     * Delete an agent
+     */
+    remove(agentId) {
+        return this.callJsonApi(`${this.relativePath}/${agentId}`, {
+            method: 'DELETE',
+        });
+    }
+    /**
+     * Send messages to an agent (non-streaming). The service creates a thread unless `threadId` is passed.
+     */
+    chat(agentId, message, options = {}) {
+        const { history, threadId, ...rest } = options;
+        const messages = [...(history || []), { role: 'user', content: message }];
+        return this.callJsonApi(`${this.relativePath}/${agentId}/chat`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                ...rest,
+                messages,
+                ...(threadId ? { threadId } : {}),
+            }),
+        });
+    }
+    /**
+     * Stream a response via GET + SSE (`/api/ai/agents/:id/chat`).
+     */
+    async streamChat(agentId, message, options = {}) {
+        const stream = await this.openAgentChatStream(agentId, message, options);
+        return this.chatSdk.parseSSEStream(stream);
+    }
+    /**
+     * Continue in an existing thread (non-streaming)
+     */
+    chatInThread(agentId, threadId, message, options = {}) {
+        return this.chat(agentId, message, { ...options, threadId });
+    }
+    /**
+     * Stream within an existing thread (GET + SSE)
+     */
+    async streamChatInThread(agentId, threadId, message, options = {}) {
+        const stream = await this.openAgentChatStream(agentId, message, { ...options, threadId });
+        return this.chatSdk.parseSSEStream(stream);
+    }
+    async openAgentChatStream(agentId, message, options) {
+        const { history, threadId, queryParams } = options;
+        const messages = [...(history || []), { role: 'user', content: message }];
+        const params = new URLSearchParams();
+        params.set('messages', JSON.stringify(messages));
+        if (threadId) {
+            params.set('threadId', threadId);
+        }
+        if (queryParams) {
+            for (const [key, value] of Object.entries(queryParams)) {
+                if (value !== undefined && value !== null) {
+                    params.set(key, String(value));
+                }
+            }
+        }
+        const q = params.toString();
+        const response = await this.callApi(`${this.relativePath}/${agentId}/chat?${q}`, {
+            method: 'GET',
+            headers: {
+                accept: 'text/event-stream',
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        if (!response.body) {
+            throw new Error('No response body for agent chat stream');
+        }
+        return response.body;
+    }
+}
+//# sourceMappingURL=agents.js.map

package/dist/ai/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../src/ai/agents.ts"],"names":[],"mappings":"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"}

package/dist/ai/index.d.ts

@@ -3,13 +3,15 @@ import BaseSDK from '../base-sdk';
 import ThreadsSDK from './threads';
 import ChatSDK from './chat';
 import RagSDK from './rag';
-import { IMessage, IMessageSummary, IThread, IChatCompletionOptions, ISSEStreamProcessor, IChatCompletionResponse, ICreateThreadRequest, ICreateVectorStorageRequest, IUploadContentRequest, IClearStorageRequest, IVectorStore } from './types';
+import AgentsSDK from './agents';
+import { IMessage, IMessageSummary, IThread, IChatCompletionOptions, ISSEStreamProcessor, IChatCompletionResponse, ICreateThreadRequest, ICreateVectorStorageRequest, IUploadContentRequest, IClearStorageRequest, IVectorStore, IAgent, IAgentChatOptions, IAgentTool, ICreateAgentRequest, IUpdateAgentRequest } from './types';
 export * from './types';
-export { IMessage, IMessageSummary, IThread, IChatCompletionOptions, ISSEStreamProcessor, IChatCompletionResponse, ICreateThreadRequest, ICreateVectorStorageRequest, IUploadContentRequest, IClearStorageRequest, IVectorStore };
+export { IMessage, IMessageSummary, IThread, IChatCompletionOptions, ISSEStreamProcessor, IChatCompletionResponse, ICreateThreadRequest, ICreateVectorStorageRequest, IUploadContentRequest, IClearStorageRequest, IVectorStore, IAgent, IAgentChatOptions, IAgentTool, ICreateAgentRequest, IUpdateAgentRequest, };
 /**
  * Qelos AI SDK - Main SDK class with three sub-SDKs
  *
- * This class provides access to AI functionality through three sub-SDKs:
+ * This class provides access to AI functionality through sub-SDKs:
+ * - `agents`: Agent management and agent-centric chat (recommended entry point)
  * - `threads`: Thread CRUD operations for managing conversation threads
  * - `chat`: Chat completion operations (streaming and non-streaming)
  * - `rag`: Vector storage management for Retrieval-Augmented Generation
@@ -48,6 +50,10 @@ export default class QlAI extends BaseSDK {
      * RAG sub-SDK for vector storage management
      */
     rag: RagSDK;
+    /**
+     * Agents sub-SDK for managing AI agents and agent-centric chat
+     */
+    agents: AgentsSDK;
     /**
      * Initialize the AI SDK with sub-SDKs
      *

package/dist/ai/index.js

@@ -2,11 +2,13 @@ import BaseSDK from '../base-sdk';
 import ThreadsSDK from './threads';
 import ChatSDK from './chat';
 import RagSDK from './rag';
+import AgentsSDK from './agents';
 export * from './types';
 /**
  * Qelos AI SDK - Main SDK class with three sub-SDKs
  *
- * This class provides access to AI functionality through three sub-SDKs:
+ * This class provides access to AI functionality through sub-SDKs:
+ * - `agents`: Agent management and agent-centric chat (recommended entry point)
  * - `threads`: Thread CRUD operations for managing conversation threads
  * - `chat`: Chat completion operations (streaming and non-streaming)
  * - `rag`: Vector storage management for Retrieval-Augmented Generation
@@ -46,6 +48,10 @@ export default class QlAI extends BaseSDK {
      * RAG sub-SDK for vector storage management
      */
     rag;
+    /**
+     * Agents sub-SDK for managing AI agents and agent-centric chat
+     */
+    agents;
     /**
      * Initialize the AI SDK with sub-SDKs
      *
@@ -56,6 +62,7 @@ export default class QlAI extends BaseSDK {
         this.threads = new ThreadsSDK(options);
         this.chat = new ChatSDK(options);
         this.rag = new RagSDK(options);
+        this.agents = new AgentsSDK(options, this.chat);
     }
     // Legacy methods for backward compatibility
     /**

package/dist/ai/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,aAAa,CAAC;AAClC,OAAO,UAAU,MAAM,WAAW,CAAC;AACnC,OAAO,OAAO,MAAM,QAAQ,CAAC;AAC7B,OAAO,MAAM,MAAM,OAAO,CAAC;AAe3B,cAAc,SAAS,CAAC;AAiBxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,4BAA4B;AAC5B,MAAM,CAAC,OAAO,OAAO,IAAK,SAAQ,OAAO;IACvC;;OAEG;IACI,OAAO,CAAa;IAE3B;;OAEG;IACI,IAAI,CAAU;IAErB;;OAEG;IACI,GAAG,CAAS;IAEnB;;;;OAIG;IACH,YAAY,OAAwB;QAClC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,OAAO,GAAG,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,4CAA4C;IAE5C;;OAEG;IACH,YAAY,CAAC,IAA0B;QACrC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,QAAgB;QACxB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,OAQX;QACC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,QAAgB;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,cAAc,CACZ,aAAqB,EACrB,OAA+B;QAE/B,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;IAED;;OAEG;IACH,sBAAsB,CACpB,aAAqB,EACrB,QAAgB,EAChB,OAA+B;QAE/B,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,aAAa,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAClE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CACd,aAAqB,EACrB,OAA+B;QAE/B,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,kBAAkB,CACtB,aAAqB,EACrB,QAAgB,EAChB,OAA+B;QAE/B,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,aAAa,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,MAAkC;QAC/C,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;CACF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,aAAa,CAAC;AAClC,OAAO,UAAU,MAAM,WAAW,CAAC;AACnC,OAAO,OAAO,MAAM,QAAQ,CAAC;AAC7B,OAAO,MAAM,MAAM,OAAO,CAAC;AAC3B,OAAO,SAAS,MAAM,UAAU,CAAC;AAoBjC,cAAc,SAAS,CAAC;AAsBxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,4BAA4B;AAC5B,MAAM,CAAC,OAAO,OAAO,IAAK,SAAQ,OAAO;IACvC;;OAEG;IACI,OAAO,CAAa;IAE3B;;OAEG;IACI,IAAI,CAAU;IAErB;;OAEG;IACI,GAAG,CAAS;IAEnB;;OAEG;IACI,MAAM,CAAY;IAEzB;;;;OAIG;IACH,YAAY,OAAwB;QAClC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,OAAO,GAAG,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,IAAI,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,4CAA4C;IAE5C;;OAEG;IACH,YAAY,CAAC,IAA0B;QACrC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,QAAgB;QACxB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,OAQX;QACC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,QAAgB;QAC3B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,cAAc,CACZ,aAAqB,EACrB,OAA+B;QAE/B,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;IAED;;OAEG;IACH,sBAAsB,CACpB,aAAqB,EACrB,QAAgB,EAChB,OAA+B;QAE/B,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,aAAa,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAClE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CACd,aAAqB,EACrB,OAA+B;QAE/B,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,kBAAkB,CACtB,aAAqB,EACrB,QAAgB,EAChB,OAA+B;QAE/B,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,aAAa,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,MAAkC;QAC/C,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;CACF"}

package/dist/ai/types.d.ts

@@ -96,3 +96,64 @@ export interface IVectorStore {
     expirationAfterDays?: number;
     created: Date;
 }
+export interface IAgentTool {
+    name: string;
+    description: string;
+    schema?: object;
+}
+export interface IAgent {
+    _id: string;
+    name: string;
+    description?: string;
+    model?: string;
+    kind?: string[];
+    active?: boolean;
+    tenant?: string;
+    user?: string;
+    workspace?: string;
+    systemPrompt?: string;
+    tools?: IAgentTool[];
+    temperature?: number;
+    maxTokens?: number;
+    triggerSource?: string;
+    targetSource?: string;
+    created?: Date;
+    updated?: Date;
+}
+/** Payload for `sdk.ai.agents.create()` — maps to a chat-completion integration */
+export interface ICreateAgentRequest {
+    name: string;
+    model: string;
+    triggerSource: string;
+    targetSource: string;
+    systemPrompt?: string;
+    tools?: IAgentTool[];
+    temperature?: number;
+    maxTokens?: number;
+    workspace?: string;
+    active?: boolean;
+}
+/** Partial update for `sdk.ai.agents.update()` */
+export interface IUpdateAgentRequest {
+    name?: string;
+    model?: string;
+    triggerSource?: string;
+    targetSource?: string;
+    systemPrompt?: string;
+    tools?: IAgentTool[];
+    temperature?: number;
+    maxTokens?: number;
+    workspace?: string;
+    active?: boolean;
+}
+export interface IAgentChatOptions extends Partial<Omit<IChatCompletionOptions, 'messages'>> {
+    /**
+     * Additional messages to prepend before the user message
+     * (e.g. system prompt overrides, prior context)
+     */
+    history?: IMessage[];
+    /**
+     * When set, reuses an existing thread created by a prior agent chat call.
+     */
+    threadId?: string;
+}

package/dist/authentication.d.ts

@@ -37,9 +37,51 @@ export interface IApiToken {
     tokenPrefix: string;
     expiresAt: string;
     lastUsedAt?: string;
-    workspace?: string;
+    /** Workspace scope when set; may be an id string or a populated `{ _id, name }` from list responses */
+    workspace?: string | {
+        _id: string;
+        name?: string;
+    } | null;
+    /** Successful API-token authentications (server-maintained). */
+    usageCount?: number;
     created: string;
 }
+export type SocialProvider = 'linkedin' | 'facebook' | 'google' | 'github';
+export interface SocialLoginOptions {
+    state?: string;
+    returnUrl?: string;
+}
+export interface SocialAuthCallbackPayload {
+    payload: BasicPayload & {
+        workspace?: any;
+    };
+    headers: {
+        'set-cookie': string | null;
+    };
+    /**
+     * Present when the runtime exposes multiple `Set-Cookie` headers (Node fetch
+     * `getSetCookie()`). Use {@link getSocialAuthSetCookieParts} to apply cookies.
+     */
+    setCookieHeaders?: string[];
+}
+/** Callback URL or query bag carrying `rt` from `GET …/callback?rt=…`. */
+export type SocialCallbackInput = string | URL | URLSearchParams | Record<string, string | string[] | undefined>;
+/**
+ * Read the OAuth refresh token from a social callback request (query `rt`).
+ * Accepts a full URL, a {@link URL}, `URLSearchParams`, or a query object such
+ * as `req.query` from Next.js or Express.
+ */
+export declare function parseSocialCallbackRefreshToken(input: SocialCallbackInput): string | undefined;
+/** Lists individual `Set-Cookie` values from an exchange result for writing to a response. */
+export declare function getSocialAuthSetCookieParts(result: SocialAuthCallbackPayload): string[];
+/**
+ * Copies session cookies from {@link QlAuthentication.exchangeAuthCallback} /
+ * {@link QlAuthentication.socialCallback} onto an HTTP response (Express,
+ * Next.js Pages `NextApiResponse`, Node `ServerResponse`, etc.).
+ */
+export declare function applySocialAuthCookiesToServerResponse(res: {
+    setHeader(name: string, value: string | string[]): void;
+}, result: SocialAuthCallbackPayload): void;
 export default class QlAuthentication extends BaseSDK {
     #private;
     get accessToken(): string;
@@ -72,6 +114,17 @@ export default class QlAuthentication extends BaseSDK {
             refreshToken: string;
         };
     }>;
+    refreshCookieToken(cookieToken?: string): Promise<{
+        headers: {
+            'set-cookie': string;
+        };
+        payload: BasicPayload & {
+            cookieToken: string;
+            workspace?: {
+                _id: string;
+            } | null;
+        };
+    }>;
     apiTokenSignin(apiToken: string): Promise<IUser>;
     listApiTokens(): Promise<IApiToken[]>;
     createApiToken(data: {
@@ -84,6 +137,16 @@ export default class QlAuthentication extends BaseSDK {
     }>;
     deleteApiToken(tokenId: string): Promise<void>;
     logout(): Promise<Response>;
+    getSocialLoginUrl(provider: SocialProvider, options?: SocialLoginOptions): string;
+    getSocialCallbackUrl(provider: SocialProvider): string;
+    startSocialLogin(provider: SocialProvider, options?: SocialLoginOptions): void;
+    exchangeAuthCallback(refreshToken: string): Promise<SocialAuthCallbackPayload>;
+    /**
+     * Full social callback: read `rt` from the request URL or query and exchange
+     * it for a session. Use with integrator routes that receive the provider
+     * callback with `?rt=` (refresh token) after OAuth.
+     */
+    socialCallback(input: SocialCallbackInput): Promise<SocialAuthCallbackPayload>;
     getLoggedInUser(): Promise<IUser>;
     updateLoggedInUser(changes: Partial<IUser & {
         password?: string;