@qelos/sdk 3.11.10 → 4.0.0

package/src/blueprints-entities.ts

@@ -12,6 +12,68 @@ export interface IBaseBlueprintEntity {
   metadata: any;
 }
 
+// Blueprint entity responses default to the flat shape. Pass $flat: false (or 0)
+// to opt back into the wrapped shape; this also keeps SDK behavior consistent
+// against older servers that defaulted to wrapped.
+function withFlatDefault<Q extends Record<string, any> | undefined>(query?: Q): Record<string, any> {
+  if (query && '$flat' in query) {
+    return query as Record<string, any>;
+  }
+  return { ...(query || {}), $flat: true };
+}
+
+export type BlueprintEntityFilters = Record<string, any>;
+
+export class QlBlueprintEntitiesQuery<T = any> {
+  #filters: BlueprintEntityFilters = {};
+  #options: Record<string, any> = {};
+
+  constructor(private entities: QlBlueprintEntities<T>) {}
+
+  where(filters: BlueprintEntityFilters): this {
+    Object.assign(this.#filters, filters);
+    return this;
+  }
+
+  limit(value: number): this {
+    this.#options.$limit = value;
+    return this;
+  }
+
+  skip(value: number): this {
+    this.#options.$skip = value;
+    return this;
+  }
+
+  sort(value: string): this {
+    this.#options.$sort = value;
+    return this;
+  }
+
+  select(fields: string | string[]): this {
+    this.#options.$select = Array.isArray(fields) ? fields.join(',') : fields;
+    return this;
+  }
+
+  toQuery(): ICommonQueryFilters & BlueprintEntityFilters {
+    return { ...this.#filters, ...this.#options };
+  }
+
+  find(extra?: RequestExtra): Promise<(IBaseBlueprintEntity & T)[]> {
+    return this.entities.getList(this.toQuery(), extra);
+  }
+
+  findOne(extra?: RequestExtra): Promise<(IBaseBlueprintEntity & T) | undefined> {
+    return this.entities
+      .getList({ ...this.toQuery(), $limit: 1 }, extra)
+      .then((results) => results?.[0]);
+  }
+
+  count(extra?: RequestExtra): Promise<number> {
+    return this.entities.count(this.toQuery(), extra);
+  }
+}
+
 export default class QlBlueprintEntities<T = any> extends BaseSDK {
   private relativePath = '/api/blueprints';
 
@@ -20,20 +82,20 @@ export default class QlBlueprintEntities<T = any> extends BaseSDK {
   }
 
   getEntity(identifier: string, extra?: RequestExtra) {
-    return this.callJsonApi<IBaseBlueprintEntity & T>(`${this.relativePath}/${this.blueprintKey}/entities/${identifier}${this.getQueryParams(extra?.query)}`, extra)
+    return this.callJsonApi<IBaseBlueprintEntity & T>(`${this.relativePath}/${this.blueprintKey}/entities/${identifier}${this.getQueryParams(withFlatDefault(extra?.query))}`, extra)
   }
 
   getList(query?: ICommonQueryFilters & Record<string, any>, extra?: RequestExtra) {
-    return this.callJsonApi<(IBaseBlueprintEntity & T)[]>(`${this.relativePath}/${this.blueprintKey}/entities${this.getQueryParams(query)}`, extra);
+    return this.callJsonApi<(IBaseBlueprintEntity & T)[]>(`${this.relativePath}/${this.blueprintKey}/entities${this.getQueryParams(withFlatDefault(query))}`, extra);
   }
 
   remove(identifier: string, extra?: RequestExtra): Promise<any> {
-    return this.callApi(`${this.relativePath}/${this.blueprintKey}/entities/${identifier}${this.getQueryParams(extra?.query)}`, { method: 'delete' });
+    return this.callApi(`${this.relativePath}/${this.blueprintKey}/entities/${identifier}${this.getQueryParams(withFlatDefault(extra?.query))}`, { method: 'delete' });
   }
 
   update(identifier: string, changes: Partial<T & IBaseBlueprintEntity>, extra?: RequestExtra): Promise<IBaseBlueprintEntity & T> {
     return this.callJsonApi<IBaseBlueprintEntity & T>(
-      `${this.relativePath}/${this.blueprintKey}/entities/${identifier}${this.getQueryParams(extra?.query)}`,
+      `${this.relativePath}/${this.blueprintKey}/entities/${identifier}${this.getQueryParams(withFlatDefault(extra?.query))}`,
       {
         method: 'put',
         headers: { 'content-type': 'application/json' },
@@ -44,11 +106,57 @@ export default class QlBlueprintEntities<T = any> extends BaseSDK {
   }
 
   create(entity: T & IBaseBlueprintEntity, extra?: RequestExtra): Promise<IBaseBlueprintEntity & T> {
-    return this.callJsonApi<IBaseBlueprintEntity & T>(`${this.relativePath}/${this.blueprintKey}/entities${this.getQueryParams(extra?.query)}`, {
+    return this.callJsonApi<IBaseBlueprintEntity & T>(`${this.relativePath}/${this.blueprintKey}/entities${this.getQueryParams(withFlatDefault(extra?.query))}`, {
       method: 'post',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify(entity),
       ...(extra || {}),
     })
   }
+
+  query(): QlBlueprintEntitiesQuery<T> {
+    return new QlBlueprintEntitiesQuery<T>(this);
+  }
+
+  where(filters: BlueprintEntityFilters): QlBlueprintEntitiesQuery<T> {
+    return this.query().where(filters);
+  }
+
+  limit(value: number): QlBlueprintEntitiesQuery<T> {
+    return this.query().limit(value);
+  }
+
+  skip(value: number): QlBlueprintEntitiesQuery<T> {
+    return this.query().skip(value);
+  }
+
+  sort(value: string): QlBlueprintEntitiesQuery<T> {
+    return this.query().sort(value);
+  }
+
+  select(fields: string | string[]): QlBlueprintEntitiesQuery<T> {
+    return this.query().select(fields);
+  }
+
+  find(extra?: RequestExtra): Promise<(IBaseBlueprintEntity & T)[]> {
+    return this.getList(undefined, extra);
+  }
+
+  findOne(identifier: string, extra?: RequestExtra): Promise<IBaseBlueprintEntity & T> {
+    return this.getEntity(identifier, extra);
+  }
+
+  count(query?: BlueprintEntityFilters, extra?: RequestExtra): Promise<number> {
+    return this
+      .callJsonApi<{ count: number }>(`${this.relativePath}/${this.blueprintKey}/charts/count${this.getQueryParams(query)}`, extra)
+      .then((res) => res?.count ?? 0);
+  }
+
+  updateOne(identifier: string, changes: Partial<T & IBaseBlueprintEntity>, extra?: RequestExtra): Promise<IBaseBlueprintEntity & T> {
+    return this.update(identifier, changes, extra);
+  }
+
+  deleteOne(identifier: string, extra?: RequestExtra): Promise<any> {
+    return this.remove(identifier, extra);
+  }
 }

package/src/blueprints.ts

@@ -3,6 +3,11 @@ import BaseSDK from './base-sdk';
 import type { IBlueprint } from '@qelos/global-types';
 import QlBlueprintEntities from './blueprints-entities';
 
+// Empty by design — extended via TypeScript declaration merging from
+// generated `.d.ts` files (`qelos interfaces build`) so `entitiesOf("todo")`
+// resolves to the typed entity without callers passing a generic.
+export interface BlueprintEntitiesRegistry {}
+
 export default class QlBlueprints extends BaseSDK {
   private relativePath = '/api/blueprints';
 
@@ -20,9 +25,11 @@ export default class QlBlueprints extends BaseSDK {
     return this.callJsonApi<IBlueprint[]>(this.relativePath);
   }
 
-  entitiesOf<T = any>(blueprintKey: string): QlBlueprintEntities<T> {
+  entitiesOf<K extends keyof BlueprintEntitiesRegistry>(blueprintKey: K): QlBlueprintEntities<BlueprintEntitiesRegistry[K]>;
+  entitiesOf<T = any>(blueprintKey: string): QlBlueprintEntities<T>;
+  entitiesOf(blueprintKey: string): QlBlueprintEntities {
     if (!this.#entities.has(blueprintKey)) {
-      this.#entities.set(blueprintKey, new QlBlueprintEntities<T>(this.options, blueprintKey));
+      this.#entities.set(blueprintKey, new QlBlueprintEntities(this.options, blueprintKey));
     }
     return this.#entities.get(blueprintKey);
   }

package/src/index.ts

@@ -6,11 +6,32 @@ import QlAuthentication from './authentication';
 import QlWorkspaces from './workspaces';
 import QlInvites from './invites';
 import QlBlueprints from './blueprints';
+import QlBlueprintEntities from './blueprints-entities';
 import QlAI from './ai';
 import QlLambdas from './lambdas';
 import QlPayments from './payments';
 
-const noExtraHeadersUrls = new Set(['/api/token/refresh', '/api/signin', '/api/signup'])
+const noExtraHeadersUrls = new Set([
+  '/api/token/refresh',
+  '/api/signin',
+  '/api/signup',
+  '/api/auth/callback',
+])
+
+export type {
+  SocialCallbackInput,
+  SocialAuthCallbackPayload,
+  SocialProvider,
+  SocialLoginOptions,
+} from './authentication';
+
+export type { BlueprintEntitiesRegistry } from './blueprints';
+
+export {
+  parseSocialCallbackRefreshToken,
+  getSocialAuthSetCookieParts,
+  applySocialAuthCookiesToServerResponse,
+} from './authentication';
 
 export default class QelosSDK extends BaseSDK {
   #customHeaders = {}
@@ -64,6 +85,10 @@ export default class QelosSDK extends BaseSDK {
     }
   }
 
+  entities<T = any>(blueprintKey: string): QlBlueprintEntities<T> {
+    return this.blueprints.entitiesOf<T>(blueprintKey);
+  }
+
   setCustomHeader(key: string, value: string) {
     this.#customHeaders[key] = value;
   }

package/src/workspaces.ts

@@ -8,8 +8,11 @@ export interface IWorkspaceMember {
 }
 
 export interface IInvite {
+  _id?: string;
   name?: string;
   email: string;
+  phone?: string;
+  roles?: string[];
   created?: string | Date;
 }
 
@@ -76,4 +79,64 @@ export default class QlWorkspaces extends BaseSDK {
       }
     )
   }
+
+  async inviteUser(
+    workspaceId: string,
+    email: string,
+    roles?: string[]
+  ): Promise<IWorkspace> {
+    const ws = await this.getWorkspace(workspaceId);
+    const inviteRoles = roles && roles.length > 0 ? roles : ['member'];
+    const invites: IInvite[] = [...(ws.invites || [])];
+    const normalized = email.trim().toLowerCase();
+    const index = invites.findIndex((i) => (i.email || '').trim().toLowerCase() === normalized);
+    if (index >= 0) {
+      invites[index] = {...invites[index], email: invites[index].email || email, roles: inviteRoles};
+    } else {
+      invites.push({email, roles: inviteRoles});
+    }
+    return this.update(workspaceId, {invites});
+  }
+
+  removeMember(workspaceId: string, userId: string): Promise<{
+    message: string;
+    removedMemberId?: string;
+    userId?: string;
+  }> {
+    const path = `${this.relativePath}/${workspaceId}/members/${encodeURIComponent(userId)}`;
+    return this.callJsonApi(path, {method: 'delete'});
+  }
+
+  updateMemberRoles(
+    workspaceId: string,
+    userId: string,
+    roles: string[]
+  ): Promise<{
+    message: string;
+    updatedMember?: IWorkspaceMember;
+    workspaceId?: string;
+  }> {
+    const path = `${this.relativePath}/${workspaceId}/members/${encodeURIComponent(userId)}`;
+    return this.callJsonApi(path, {
+      method: 'put',
+      headers: {'content-type': 'application/json'},
+      body: JSON.stringify({roles}),
+    });
+  }
+
+  async listInvites(workspaceId: string): Promise<IInvite[]> {
+    const ws = await this.getWorkspace(workspaceId);
+    return ws.invites ?? [];
+  }
+
+  async revokeInvite(workspaceId: string, inviteId: string): Promise<IWorkspace> {
+    const ws = await this.getWorkspace(workspaceId);
+    const prev = ws.invites || [];
+    const idStr = String(inviteId);
+    const invites = prev.filter((inv) => String(inv._id ?? '') !== idStr);
+    if (invites.length === prev.length) {
+      throw new Error('Invitation not found');
+    }
+    return this.update(workspaceId, {invites});
+  }
 }

package/test/authentication-social.test.ts

@@ -0,0 +1,48 @@
+import * as assert from 'node:assert/strict';
+import { test } from 'node:test';
+import type { SocialAuthCallbackPayload } from '../src/authentication';
+import {
+  parseSocialCallbackRefreshToken,
+  getSocialAuthSetCookieParts,
+} from '../src/authentication';
+
+test('parseSocialCallbackRefreshToken', async (t) => {
+  await t.test('parses full URL and path-only string', () => {
+    assert.equal(
+      parseSocialCallbackRefreshToken('https://app.example/api/cb?rt=abc&x=1'),
+      'abc',
+    );
+    assert.equal(parseSocialCallbackRefreshToken('/cb?rt=xyz'), 'xyz');
+  });
+
+  await t.test('parses URL / URLSearchParams / query objects', () => {
+    assert.equal(parseSocialCallbackRefreshToken(new URL('http://_/p?rt=u')), 'u');
+    assert.equal(parseSocialCallbackRefreshToken(new URLSearchParams('rt=v')), 'v');
+    assert.equal(parseSocialCallbackRefreshToken({ rt: 'w' }), 'w');
+    assert.equal(parseSocialCallbackRefreshToken({ rt: ['z'] }), 'z');
+  });
+
+  await t.test('returns undefined when rt missing', () => {
+    assert.equal(parseSocialCallbackRefreshToken('/no-query'), undefined);
+    assert.equal(parseSocialCallbackRefreshToken({}), undefined);
+  });
+});
+
+test('getSocialAuthSetCookieParts', async (t) => {
+  await t.test('prefers setCookieHeaders array', () => {
+    const r = {
+      payload: { user: {} },
+      headers: { 'set-cookie': 'a=1' },
+      setCookieHeaders: ['a=1', 'b=2'],
+    } as SocialAuthCallbackPayload;
+    assert.deepEqual(getSocialAuthSetCookieParts(r), ['a=1', 'b=2']);
+  });
+
+  await t.test('falls back to single header', () => {
+    const r = {
+      payload: { user: {} },
+      headers: { 'set-cookie': 'x=9' },
+    } as SocialAuthCallbackPayload;
+    assert.deepEqual(getSocialAuthSetCookieParts(r), ['x=9']);
+  });
+});

package/test/base-sdk.test.ts

@@ -1,6 +1,6 @@
 import * as assert from 'node:assert/strict';
 import { test } from 'node:test';
-import BaseSDK from '../src/base-sdk';
+import BaseSDK, { relativeUrlPath } from '../src/base-sdk';
 import { QelosSDKOptions } from '../src/types';
 
 test('BaseSDK', async (t) => {
@@ -77,4 +77,29 @@ test('BaseSDK', async (t) => {
     const queryString = sdkWithExtraParams.getQueryParams({ local: 'param' });
     assert.equal(queryString, '?global=param&local=param');
   });
+
+  await t.test('relativeUrlPath strips query and hash', () => {
+    assert.equal(relativeUrlPath('/api/auth/callback?rt=x'), '/api/auth/callback');
+    assert.equal(relativeUrlPath('/path#frag'), '/path');
+    assert.equal(relativeUrlPath('/plain'), '/plain');
+  });
+
+  await t.test('extraHeaders receives path without query string', async () => {
+    const seen: string[] = [];
+    options = {
+      appUrl: 'http://localhost:3000',
+      fetch: async (url) => {
+        const res = new Response(JSON.stringify({ ok: true }));
+        res.headers.set('Content-Type', 'application/json');
+        return res;
+      },
+      extraHeaders: async (relativeUrl) => {
+        seen.push(relativeUrl);
+        return {};
+      },
+    };
+    const s = new BaseSDK(options);
+    await s.callApi('/api/auth/callback?rt=tok');
+    assert.deepEqual(seen, ['/api/auth/callback']);
+  });
 });

package/test/index.test.ts

@@ -62,7 +62,8 @@ test('QelosSDK', async (t) => {
     const noAuthUrls = [
       '/api/token/refresh',
       '/api/signin',
-      '/api/signup'
+      '/api/signup',
+      '/api/auth/callback',
     ];
 
     for (const url of noAuthUrls) {

package/test/qelos-sdk-refresh.test.ts

@@ -127,7 +127,8 @@ test('QelosSDK token refresh functionality', async (t) => {
     const noAuthUrls = [
       '/api/token/refresh',
       '/api/signin',
-      '/api/signup'
+      '/api/signup',
+      '/api/auth/callback',
     ];
 
     for (const url of noAuthUrls) {

package/test/workspaces.test.ts

@@ -0,0 +1,170 @@
+import * as assert from 'node:assert/strict';
+import {test} from 'node:test';
+import QlWorkspaces from '../src/workspaces';
+import {QelosSDKOptions} from '../src/types';
+
+function jsonResponse(body: unknown, ok = true) {
+  const res = new Response(JSON.stringify(body));
+  res.headers.set('Content-Type', 'application/json');
+  if (!ok) {
+    Object.defineProperty(res, 'ok', {value: false});
+    Object.defineProperty(res, 'status', {value: 400});
+  }
+  return res;
+}
+
+test('QlWorkspaces', async (t) => {
+  await t.test('removeMember sends DELETE to members path', async () => {
+    const calls: string[] = [];
+    const options: QelosSDKOptions = {
+      appUrl: 'http://localhost:3000',
+      fetch: async (url) => {
+        calls.push(url.toString());
+        return jsonResponse({message: 'Member removed from workspace.', userId: 'u1'});
+      },
+    };
+    const ws = new QlWorkspaces(options);
+    await ws.removeMember('ws-1', 'user-456');
+    assert.equal(calls[0], 'http://localhost:3000/api/workspaces/ws-1/members/user-456');
+  });
+
+  await t.test('updateMemberRoles sends PUT with roles body', async () => {
+    let init: RequestInit | undefined;
+    const options: QelosSDKOptions = {
+      appUrl: 'http://localhost:3000',
+      fetch: async (_url, requestInit) => {
+        init = requestInit;
+        return jsonResponse({
+          message: 'Member roles updated successfully.',
+          workspaceId: 'ws-1',
+        });
+      },
+    };
+    const ws = new QlWorkspaces(options);
+    await ws.updateMemberRoles('ws-1', 'user-456', ['admin']);
+    assert.equal(init?.method, 'put');
+    assert.equal((init?.headers as Record<string, string>)['content-type'], 'application/json');
+    assert.deepEqual(JSON.parse(init?.body as string), {roles: ['admin']});
+  });
+
+  await t.test('inviteUser merges invites then updates workspace', async () => {
+    const bodies: unknown[] = [];
+    let step = 0;
+    const options: QelosSDKOptions = {
+      appUrl: 'http://localhost:3000',
+      fetch: async (_url, requestInit) => {
+        if (step === 0) {
+          step++;
+          assert.equal(requestInit?.method, undefined);
+          return jsonResponse({
+            name: 'W',
+            labels: [],
+            invites: [{email: 'old@x.com', roles: ['member'], _id: 'i1'}],
+          });
+        }
+        bodies.push(JSON.parse(requestInit?.body as string));
+        return jsonResponse({name: 'W', labels: [], invites: []});
+      },
+    };
+    const ws = new QlWorkspaces(options);
+    await ws.inviteUser('ws-1', 'newdev@company.com', ['editor']);
+    assert.equal(step, 1);
+    assert.deepEqual(bodies[0], {
+      invites: [
+        {email: 'old@x.com', roles: ['member'], _id: 'i1'},
+        {email: 'newdev@company.com', roles: ['editor']},
+      ],
+    });
+  });
+
+  await t.test('inviteUser updates roles for existing email (case-insensitive)', async () => {
+    let putBody: unknown;
+    let step = 0;
+    const options: QelosSDKOptions = {
+      appUrl: 'http://localhost:3000',
+      fetch: async (_url, requestInit) => {
+        if (step === 0) {
+          step++;
+          return jsonResponse({
+            name: 'W',
+            labels: [],
+            invites: [{email: 'A@X.COM', roles: ['member'], _id: 'i1'}],
+          });
+        }
+        putBody = JSON.parse(requestInit?.body as string);
+        return jsonResponse({name: 'W', labels: []});
+      },
+    };
+    const ws = new QlWorkspaces(options);
+    await ws.inviteUser('ws-1', 'a@x.com', ['admin']);
+    assert.deepEqual(putBody, {
+      invites: [{email: 'A@X.COM', roles: ['admin'], _id: 'i1'}],
+    });
+  });
+
+  await t.test('listInvites returns invites from getWorkspace', async () => {
+    const options: QelosSDKOptions = {
+      appUrl: 'http://localhost:3000',
+      fetch: async () =>
+        jsonResponse({
+          name: 'W',
+          labels: [],
+          invites: [{email: 'x@y.com', roles: ['editor'], _id: 'inv1'}],
+        }),
+    };
+    const ws = new QlWorkspaces(options);
+    const list = await ws.listInvites('ws-1');
+    assert.equal(list.length, 1);
+    assert.equal(list[0].email, 'x@y.com');
+    assert.equal(list[0]._id, 'inv1');
+  });
+
+  await t.test('revokeInvite filters invite and updates workspace', async () => {
+    let putBody: unknown;
+    let step = 0;
+    const options: QelosSDKOptions = {
+      appUrl: 'http://localhost:3000',
+      fetch: async (_url, requestInit) => {
+        if (step === 0) {
+          step++;
+          return jsonResponse({
+            name: 'W',
+            labels: [],
+            invites: [
+              {_id: 'keep', email: 'a@b.com', roles: ['member']},
+              {_id: 'drop', email: 'c@d.com', roles: ['member']},
+            ],
+          });
+        }
+        putBody = JSON.parse(requestInit?.body as string);
+        return jsonResponse({name: 'W', labels: []});
+      },
+    };
+    const ws = new QlWorkspaces(options);
+    await ws.revokeInvite('ws-1', 'drop');
+    assert.deepEqual(putBody, {
+      invites: [{_id: 'keep', email: 'a@b.com', roles: ['member']}],
+    });
+  });
+
+  await t.test('revokeInvite throws when id is not found', async () => {
+    let step = 0;
+    const options: QelosSDKOptions = {
+      appUrl: 'http://localhost:3000',
+      fetch: async () => {
+        if (step === 0) {
+          step++;
+          return jsonResponse({
+            name: 'W',
+            labels: [],
+            invites: [{_id: 'x', email: 'a@b.com', roles: ['member']}],
+          });
+        }
+        return jsonResponse({});
+      },
+    };
+    const ws = new QlWorkspaces(options);
+    await assert.rejects(() => ws.revokeInvite('ws-1', 'missing'), /Invitation not found/);
+    assert.equal(step, 1);
+  });
+});