@qelos/sdk 3.11.10 → 4.0.0

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

@@ -0,0 +1,49 @@
+// 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`.
+
+import QlBlueprints from '../blueprints';
+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 blueprints: QlBlueprints;
+
+// 1. Registry-keyed lookup resolves to the augmented entity type.
+const todos = blueprints.entitiesOf('todo');
+type TodosCheck = Expect<Equal<typeof todos, QlBlueprintEntities<TodoEntity>>>;
+
+// `find()` returns the merged entity shape from the registry.
+declare const found: Awaited<ReturnType<typeof todos.find>>;
+type FoundCheck = Expect<Equal<typeof found, (IBaseBlueprintEntity & TodoEntity)[]>>;
+
+// 2. Explicit-generic fallback still compiles for unregistered keys.
+interface AdHoc {
+  name: string;
+}
+const adhoc = blueprints.entitiesOf<AdHoc>('not-in-registry');
+type AdHocCheck = Expect<Equal<typeof adhoc, QlBlueprintEntities<AdHoc>>>;
+
+// 3. Plain string key with no generic falls back to `any` (legacy behavior).
+const dynamicKey: string = 'todo';
+const loose = blueprints.entitiesOf(dynamicKey);
+type LooseCheck = Expect<Equal<typeof loose, QlBlueprintEntities<any>>>;
+
+// Mark generated checks as used so the file remains a valid module.
+export type _Checks = [TodosCheck, FoundCheck, AdHocCheck, LooseCheck];

package/src/administrator/events.ts

@@ -4,6 +4,7 @@ import BaseSDK from '../base-sdk';
 export interface IQelosEvent {
   tenant: string;
   user?: string;
+  workspace?: string;
   source: string;
   kind: string;
   eventName: string;
@@ -19,15 +20,19 @@ export default class QlEvents extends BaseSDK {
     super(options)
   }
 
-  getList(params?: { page?: number; kind?: string; eventName?: string; source?: string; user?: string; workspace?: string; period?: string }) {
+  getList(params?: { page?: number; limit?: number; kind?: string; eventName?: string; source?: string; user?: string; workspace?: string; search?: string; period?: string; from?: string; to?: string }) {
     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) queryParams.append('eventName', params.eventName);
     if (params?.source) queryParams.append('source', params.source);
     if (params?.user) 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<IQelosEvent[]>(this.relativePath + (queryString ? '?' + queryString : ''));

package/src/administrator/workspaces.ts

@@ -9,8 +9,16 @@ export default class QlAdminWorkspaces extends BaseSDK {
     super(options)
   }
 
-  getList() {
-    return this.callJsonApi<IWorkspace[]>(this.relativePath + '/all');
+  getList(filters?: { 'members.user'?: string; labels?: string[]; name?: string; q?: string; _id?: string[]; select?: string }) {
+    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<IWorkspace[]>(this.relativePath + '/all' + queryParams);
   }
 
   getEncryptedData<Z = any>(workspaceId: string, encryptedId: string = '') {

package/src/ai/agents.ts

@@ -0,0 +1,171 @@
+import BaseSDK from '../base-sdk';
+import { QelosSDKOptions } from '../types';
+import ChatSDK from './chat';
+import {
+  IAgent,
+  IAgentChatOptions,
+  IChatCompletionResponse,
+  ICreateAgentRequest,
+  IMessage,
+  ISSEStreamProcessor,
+  IUpdateAgentRequest,
+} from '.';
+
+export default class AgentsSDK extends BaseSDK {
+  private relativePath = '/api/ai/agents';
+
+  constructor(
+    options: QelosSDKOptions,
+    private chatSdk: ChatSDK,
+  ) {
+    super(options);
+  }
+
+  /**
+   * 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[]> {
+    return this.callJsonApi<IAgent[]>(`${this.relativePath}${this.getQueryParams(query)}`);
+  }
+
+  /**
+   * Get a specific agent by ID (model, tools, system prompt, etc.)
+   */
+  get(agentId: string): Promise<IAgent> {
+    return this.callJsonApi<IAgent>(`${this.relativePath}/${agentId}${this.getQueryParams({})}`);
+  }
+
+  /**
+   * Create a new agent (chat-completion integration)
+   */
+  create(data: ICreateAgentRequest): Promise<IAgent> {
+    return this.callJsonApi<IAgent>(`${this.relativePath}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+  }
+
+  /**
+   * Update agent configuration
+   */
+  update(agentId: string, data: IUpdateAgentRequest): Promise<IAgent> {
+    return this.callJsonApi<IAgent>(`${this.relativePath}/${agentId}`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+  }
+
+  /**
+   * Delete an agent
+   */
+  remove(agentId: string): Promise<{ success: boolean; message?: string }> {
+    return this.callJsonApi<{ success: boolean; message?: string }>(`${this.relativePath}/${agentId}`, {
+      method: 'DELETE',
+    });
+  }
+
+  /**
+   * 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> {
+    const { history, threadId, ...rest } = options;
+    const messages: IMessage[] = [...(history || []), { role: 'user', content: message }];
+    return this.callJsonApi<IChatCompletionResponse>(`${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: string,
+    message: string,
+    options: IAgentChatOptions = {},
+  ): Promise<ISSEStreamProcessor> {
+    const stream = await this.openAgentChatStream(agentId, message, options);
+    return this.chatSdk.parseSSEStream(stream);
+  }
+
+  /**
+   * Continue in an existing thread (non-streaming)
+   */
+  chatInThread(
+    agentId: string,
+    threadId: string,
+    message: string,
+    options: IAgentChatOptions = {},
+  ): Promise<IChatCompletionResponse> {
+    return this.chat(agentId, message, { ...options, threadId });
+  }
+
+  /**
+   * Stream within an existing thread (GET + SSE)
+   */
+  async streamChatInThread(
+    agentId: string,
+    threadId: string,
+    message: string,
+    options: IAgentChatOptions = {},
+  ): Promise<ISSEStreamProcessor> {
+    const stream = await this.openAgentChatStream(agentId, message, { ...options, threadId });
+    return this.chatSdk.parseSSEStream(stream);
+  }
+
+  private async openAgentChatStream(
+    agentId: string,
+    message: string,
+    options: IAgentChatOptions,
+  ): Promise<ReadableStream<Uint8Array>> {
+    const { history, threadId, queryParams } = options;
+    const messages: IMessage[] = [...(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;
+  }
+}

package/src/ai/index.ts

@@ -3,6 +3,7 @@ import BaseSDK from '../base-sdk';
 import ThreadsSDK from './threads';
 import ChatSDK from './chat';
 import RagSDK from './rag';
+import AgentsSDK from './agents';
 import {
   IMessage,
   IMessageSummary,
@@ -14,7 +15,12 @@ import {
   ICreateVectorStorageRequest,
   IUploadContentRequest,
   IClearStorageRequest,
-  IVectorStore
+  IVectorStore,
+  IAgent,
+  IAgentChatOptions,
+  IAgentTool,
+  ICreateAgentRequest,
+  IUpdateAgentRequest,
 } from './types';
 
 export * from './types';
@@ -31,13 +37,19 @@ export {
   ICreateVectorStorageRequest,
   IUploadContentRequest,
   IClearStorageRequest,
-  IVectorStore
+  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
@@ -80,9 +92,14 @@ export default class QlAI extends BaseSDK {
    */
   public rag: RagSDK;
 
+  /**
+   * Agents sub-SDK for managing AI agents and agent-centric chat
+   */
+  public agents: AgentsSDK;
+
   /**
    * Initialize the AI SDK with sub-SDKs
-   * 
+   *
    * @param options - SDK configuration options
    */
   constructor(options: QelosSDKOptions) {
@@ -90,6 +107,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/src/ai/types.ts

@@ -107,3 +107,69 @@ 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/src/authentication.ts

@@ -43,10 +43,97 @@ 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>;
+
+function collectSetCookieHeaders(res: Response): string[] | undefined {
+  const h = res.headers as Headers & { getSetCookie?: () => string[] };
+  if (typeof h.getSetCookie === 'function') {
+    const list = h.getSetCookie();
+    return list.length ? list : undefined;
+  }
+  const single = res.headers.get('set-cookie');
+  return single ? [single] : 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 function parseSocialCallbackRefreshToken(input: SocialCallbackInput): string | undefined {
+  if (input instanceof URL) {
+    return input.searchParams.get('rt') ?? undefined;
+  }
+  if (typeof input === 'string') {
+    try {
+      const u = new URL(input, 'http://qelos.social-callback.invalid');
+      return u.searchParams.get('rt') ?? undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  if (input instanceof URLSearchParams) {
+    return input.get('rt') ?? undefined;
+  }
+  const raw = input['rt'];
+  if (Array.isArray(raw)) {
+    return raw[0] && typeof raw[0] === 'string' ? raw[0] : undefined;
+  }
+  return typeof raw === 'string' ? raw : undefined;
+}
+
+/** Lists individual `Set-Cookie` values from an exchange result for writing to a response. */
+export function getSocialAuthSetCookieParts(result: SocialAuthCallbackPayload): string[] {
+  if (result.setCookieHeaders?.length) {
+    return result.setCookieHeaders;
+  }
+  const h = result.headers['set-cookie'];
+  return h ? [h] : [];
+}
+
+/**
+ * Copies session cookies from {@link QlAuthentication.exchangeAuthCallback} /
+ * {@link QlAuthentication.socialCallback} onto an HTTP response (Express,
+ * Next.js Pages `NextApiResponse`, Node `ServerResponse`, etc.).
+ */
+export function applySocialAuthCookiesToServerResponse(
+  res: { setHeader(name: string, value: string | string[]): void },
+  result: SocialAuthCallbackPayload,
+): void {
+  const parts = getSocialAuthSetCookieParts(result);
+  if (!parts.length) return;
+  res.setHeader('Set-Cookie', parts.length === 1 ? parts[0]! : parts);
+}
+
 export default class QlAuthentication extends BaseSDK {
 
   #refreshToken: string;
@@ -155,6 +242,32 @@ export default class QlAuthentication extends BaseSDK {
       })
   }
 
+  async refreshCookieToken(cookieToken?: string) {
+    const headers: Record<string, string> = {};
+    if (cookieToken) {
+      headers.authorization = 'Bearer ' + cookieToken;
+    }
+    const res = await this.callApi('/api/cookie/refresh', {
+      method: 'post',
+      headers,
+    });
+    if (!res.ok) {
+      throw new Error('failed to refresh cookie token');
+    }
+    const body = (await res.json()) as {
+      payload: BasicPayload & {
+        cookieToken: string;
+        workspace?: { _id: string } | null;
+      };
+    };
+    return {
+      ...body,
+      headers: {
+        'set-cookie': res.headers?.get('set-cookie'),
+      },
+    };
+  }
+
   async apiTokenSignin(apiToken: string): Promise<IUser> {
     this.#apiToken = apiToken;
     this.qlOptions.apiToken = apiToken;
@@ -183,6 +296,73 @@ export default class QlAuthentication extends BaseSDK {
     return this.callApi('/api/logout', { method: 'post' })
   }
 
+  getSocialLoginUrl(provider: SocialProvider, options: SocialLoginOptions = {}): string {
+    const params: Record<string, string> = {};
+    if (options.state) params.state = options.state;
+    if (options.returnUrl) params.returnUrl = options.returnUrl;
+    const qs = Object.keys(params).length ? `?${new URLSearchParams(params)}` : '';
+    return this.buildUrl(`/api/auth/${provider}${qs}`);
+  }
+
+  getSocialCallbackUrl(provider: SocialProvider): string {
+    return this.buildUrl(`/api/auth/${provider}/callback`);
+  }
+
+  startSocialLogin(provider: SocialProvider, options?: SocialLoginOptions): void {
+    const location = (globalThis as any).location;
+    if (!location) {
+      throw new Error('startSocialLogin requires a browser environment');
+    }
+    location.href = this.getSocialLoginUrl(provider, options);
+  }
+
+  async exchangeAuthCallback(refreshToken: string): Promise<SocialAuthCallbackPayload> {
+    if (!refreshToken) {
+      throw new Error('refresh token is required');
+    }
+    const res = await this.callApi(`/api/auth/callback?rt=${encodeURIComponent(refreshToken)}`, {
+      method: 'post',
+      cache: 'no-store',
+    });
+    if (!res.ok) {
+      let detail = '';
+      try {
+        detail = (await res.text()).slice(0, 512);
+      } catch {
+        /* ignore */
+      }
+      throw new Error(
+        `failed to exchange refresh token: HTTP ${res.status}${detail ? ` — ${detail}` : ''}`,
+      );
+    }
+    const body = (await res.json()) as { payload: BasicPayload & { workspace?: any } };
+    const cookieParts = collectSetCookieHeaders(res);
+    const legacyCookie =
+      cookieParts?.[0] ?? res.headers?.get('set-cookie');
+    return {
+      ...body,
+      headers: {
+        'set-cookie': legacyCookie ?? null,
+      },
+      ...(cookieParts && cookieParts.length > 1
+        ? { setCookieHeaders: cookieParts }
+        : {}),
+    };
+  }
+
+  /**
+   * 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.
+   */
+  async socialCallback(input: SocialCallbackInput): Promise<SocialAuthCallbackPayload> {
+    const refreshToken = parseSocialCallbackRefreshToken(input);
+    if (!refreshToken) {
+      throw new Error('missing rt query parameter');
+    }
+    return this.exchangeAuthCallback(refreshToken);
+  }
+
   getLoggedInUser() {
     return this.callJsonApi<IUser>('/api/me')
   }

package/src/base-sdk.ts

@@ -1,5 +1,15 @@
 import { FetchLike, QelosSDKOptions } from './types';
 
+/** Path segment of a relative URL, without query or hash — used for auth routing in extraHeaders. */
+export function relativeUrlPath(relativeUrl: string): string {
+  const q = relativeUrl.indexOf('?');
+  const h = relativeUrl.indexOf('#');
+  let end = relativeUrl.length;
+  if (q !== -1) end = Math.min(end, q);
+  if (h !== -1) end = Math.min(end, h);
+  return end === relativeUrl.length ? relativeUrl : relativeUrl.slice(0, end);
+}
+
 const ERRORS = {
   EXTRA_HEADERS: 'could not get extra headers',
   FAILED_REFRESH_TOKEN: 'could not handle failed refresh token',
@@ -15,13 +25,17 @@ export default class BaseSDK {
     this.#fetch = qlOptions.fetch || globalThis.fetch;
   }
 
+  protected buildUrl(relativeUrl: string): string {
+    return (this.#appUrl || '') + relativeUrl;
+  }
+
   async callApi(relativeUrl: string, data?: RequestInit) {
     data = data || {};
     data.headers = data.headers || {};
     
     if (this.qlOptions.extraHeaders) {
       try {
-        const extraHeaders = await this.qlOptions.extraHeaders(relativeUrl);
+        const extraHeaders = await this.qlOptions.extraHeaders(relativeUrlPath(relativeUrl));
         Object.assign(data.headers, extraHeaders);
       } catch (e) {
         throw new Error(ERRORS.EXTRA_HEADERS);
@@ -81,7 +95,7 @@ export default class BaseSDK {
         
         if (this.qlOptions.extraHeaders) {
           try {
-            headers = await this.qlOptions.extraHeaders(relativeUrl, true);
+            headers = await this.qlOptions.extraHeaders(relativeUrlPath(relativeUrl), true);
           } catch {
             // Ignore error during refresh attempt
           }