@coworkee/client 0.0.0-stage → 0.0.1024

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# @coworkee/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed TypeScript client for the API of apps built on [Coworkee](https://fgilde.github.io/CoworkeeLib/): types generated from the OpenAPI description of the library endpoints, `createCoworkeeClient()` (openapi-fetch), `apiRequest`, `ApiError` with problem details, the realtime hub (`createRealtime()`, SignalR), streamed answers (`postNdjson`), and helpers for the BFF session, theme, texts and OData.
+
+```bash
+npm install @coworkee/client
+```
+
+```ts
+import { createCoworkeeClient, createRealtime, unwrap } from '@coworkee/client';
+
+const api = createCoworkeeClient();               // in a page served by the app's BFF: session cookie + CSRF header
+const me = unwrap(await api.GET('/api/v1/identity/me'));
+const stop = createRealtime().subscribe(`user:${userId}`, ({ type, payload }) => console.log(type, payload));
+```
+
+- Every Coworkee release publishes it in the version of the release (`a.b.c.d` becomes `a.b.(c*1000+d)`, npm knows no fourth part).
+- `npm run openapi -- <url of /openapi/v1.json> [more documents]` refreshes `openapi.json`, `npm run generate` the types.
+- Documentation: [SDKs](https://fgilde.github.io/CoworkeeLib/web/sdk/)
+
+License: MIT

package/dist/bff.d.ts

@@ -0,0 +1,17 @@
+import { type CoworkeeClientOptions } from './client.ts';
+/** The signed-in user as the BFF of a Coworkee app reports it (GET /bff/user). */
+export type BffUser = {
+    isAuthenticated: boolean;
+    name?: string | null;
+    email?: string | null;
+    userId?: string | null;
+    tenantId?: string | null;
+    roles: string[];
+    manageUrl?: string | null;
+    systemTenant?: boolean | null;
+};
+export declare const getUser: (options?: CoworkeeClientOptions) => Promise<BffUser>;
+/** The address that starts the sign-in at the auth server and comes back to returnUrl (a local path). */
+export declare function loginUrl(returnUrl?: string, loginHint?: string): string;
+/** Ends the session and returns where the browser goes next (the end-session page of the auth server). */
+export declare function logout(options?: CoworkeeClientOptions): Promise<string>;

package/dist/bff.js

@@ -0,0 +1,14 @@
+import { apiRequest } from "./client.js";
+export const getUser = (options) => apiRequest('/bff/user', {}, options);
+/** The address that starts the sign-in at the auth server and comes back to returnUrl (a local path). */
+export function loginUrl(returnUrl = '/', loginHint) {
+    const query = new URLSearchParams({ returnUrl: returnUrl.startsWith('/') && !returnUrl.startsWith('//') ? returnUrl : '/' });
+    if (loginHint)
+        query.set('loginHint', loginHint);
+    return `/bff/login?${query}`;
+}
+/** Ends the session and returns where the browser goes next (the end-session page of the auth server). */
+export async function logout(options) {
+    const result = await apiRequest('/bff/logout', { method: 'POST' }, options);
+    return result?.redirect || '/';
+}

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import { type Client } from 'openapi-fetch';
+import type { paths } from './schema.ts';
+export type CoworkeeClient = Client<paths>;
+export type CoworkeeClientOptions = {
+    /** Address of the app (its BFF) or the API; empty for the page's own origin. */
+    baseUrl?: string;
+    /** A bearer token of the API (an API key or an access token); without one the browser's session cookie and the CSRF header of the BFF are used. */
+    token?: () => string | Promise<string>;
+    fetch?: typeof fetch;
+};
+/** Header the BFF demands on every unsafe request, so other sites cannot send them with the session cookie. */
+export declare const csrfHeader: {
+    readonly name: "X-CSRF";
+    readonly value: "1";
+};
+/** Typed client over the OpenAPI document of the library: paths, parameters, bodies and answers are checked by the compiler. */
+export declare function createCoworkeeClient(options?: CoworkeeClientOptions): CoworkeeClient;
+/**
+ * Untyped request for any endpoint, the app's own included: JSON in and out, text for other answers, nothing for 204.
+ * Bodies that are strings go as JSON, others (Blob, File, FormData) as they are. Failures throw an ApiError.
+ */
+export declare function apiRequest<T = unknown>(path: string, init?: RequestInit, options?: CoworkeeClientOptions): Promise<T>;

package/dist/client.js

@@ -0,0 +1,37 @@
+import createClient, {} from 'openapi-fetch';
+import { ApiError, problemOf } from "./errors.js";
+/** Header the BFF demands on every unsafe request, so other sites cannot send them with the session cookie. */
+export const csrfHeader = { name: 'X-CSRF', value: '1' };
+async function authorize(headers, options) {
+    if (options.token)
+        headers.set('Authorization', `Bearer ${await options.token()}`);
+    else
+        headers.set(csrfHeader.name, csrfHeader.value);
+}
+/** Typed client over the OpenAPI document of the library: paths, parameters, bodies and answers are checked by the compiler. */
+export function createCoworkeeClient(options = {}) {
+    const client = createClient({ baseUrl: options.baseUrl ?? '', fetch: options.fetch, credentials: 'same-origin' });
+    client.use({
+        async onRequest({ request }) {
+            await authorize(request.headers, options);
+            return request;
+        },
+    });
+    return client;
+}
+/**
+ * Untyped request for any endpoint, the app's own included: JSON in and out, text for other answers, nothing for 204.
+ * Bodies that are strings go as JSON, others (Blob, File, FormData) as they are. Failures throw an ApiError.
+ */
+export async function apiRequest(path, init = {}, options = {}) {
+    const headers = new Headers(init.headers);
+    await authorize(headers, options);
+    if (typeof init.body === 'string' && !headers.has('Content-Type'))
+        headers.set('Content-Type', 'application/json');
+    const response = await (options.fetch ?? fetch)(`${options.baseUrl ?? ''}${path}`, { credentials: 'same-origin', ...init, headers });
+    if (!response.ok)
+        throw new ApiError(response.status, await problemOf(response));
+    if (response.status === 204)
+        return undefined;
+    return ((response.headers.get('content-type') ?? '').includes('json') ? await response.json() : await response.text());
+}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/** The problem details a Coworkee API answers with: title, the error code of the result and validation messages per field. */
+export type Problem = {
+    title?: string;
+    detail?: string;
+    status?: number;
+    code?: string;
+    errors?: Record<string, string[]>;
+};
+/** A failed API call. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly problem?: Problem;
+    constructor(status: number, problem?: Problem);
+    get code(): string | undefined;
+}
+/** One line for the user: the validation messages, else the detail or title, else the status. */
+export declare function problemMessage(status: number, problem?: Problem): string;
+/** Reads the problem of a failed response; bodies that are no JSON give none. */
+export declare function problemOf(response: Response): Promise<Problem | undefined>;
+/** The data of an openapi-fetch result, or an ApiError. */
+export declare function unwrap<T>(result: {
+    data?: T;
+    error?: unknown;
+    response: Response;
+}): T;

package/dist/errors.js

@@ -0,0 +1,35 @@
+/** A failed API call. */
+export class ApiError extends Error {
+    status;
+    problem;
+    constructor(status, problem) {
+        super(problemMessage(status, problem));
+        this.name = 'ApiError';
+        this.status = status;
+        this.problem = problem;
+    }
+    get code() { return this.problem?.code; }
+}
+/** One line for the user: the validation messages, else the detail or title, else the status. */
+export function problemMessage(status, problem) {
+    const validation = Object.values(problem?.errors ?? {}).flat().filter(Boolean);
+    if (validation.length > 0)
+        return validation.join(' ');
+    return problem?.detail || problem?.title || `The API answered ${status}.`;
+}
+/** Reads the problem of a failed response; bodies that are no JSON give none. */
+export async function problemOf(response) {
+    try {
+        const text = await response.text();
+        return text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The data of an openapi-fetch result, or an ApiError. */
+export function unwrap(result) {
+    if (result.response.ok)
+        return result.data;
+    throw new ApiError(result.response.status, typeof result.error === 'object' && result.error ? result.error : undefined);
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import type { components } from './schema.ts';
+export type { paths, components, operations } from './schema.ts';
+export type Schemas = components['schemas'];
+export { apiRequest, createCoworkeeClient, csrfHeader, type CoworkeeClient, type CoworkeeClientOptions } from './client.ts';
+export { ApiError, problemMessage, problemOf, unwrap, type Problem } from './errors.ts';
+export { getUser, loginUrl, logout, type BffUser } from './bff.ts';
+export { applyTheme, cssVariables, getCurrentTheme, logoUrl, palette, resolveMode, type ColorMode, type Theme } from './theme.ts';
+export { format, getTexts, pickCulture, translator, type Texts, type Translate } from './texts.ts';
+export { createRealtime, realtimeEvents, realtimeTopics, type EntityChanged, type Realtime, type RealtimeEnvelope, type RealtimeHandler } from './realtime.ts';
+export { lineSplitter, postNdjson } from './stream.ts';
+export { entitySets, literal, odataPage, odataQuery, searchFilter, type EntitySetInfo, type ODataPage, type ODataQuery } from './odata.ts';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { apiRequest, createCoworkeeClient, csrfHeader } from "./client.js";
+export { ApiError, problemMessage, problemOf, unwrap } from "./errors.js";
+export { getUser, loginUrl, logout } from "./bff.js";
+export { applyTheme, cssVariables, getCurrentTheme, logoUrl, palette, resolveMode } from "./theme.js";
+export { format, getTexts, pickCulture, translator } from "./texts.js";
+export { createRealtime, realtimeEvents, realtimeTopics } from "./realtime.js";
+export { lineSplitter, postNdjson } from "./stream.js";
+export { entitySets, literal, odataPage, odataQuery, searchFilter } from "./odata.js";

package/dist/odata.d.ts

@@ -0,0 +1,26 @@
+import { type CoworkeeClientOptions } from './client.ts';
+export type ODataQuery = {
+    filter?: string;
+    orderBy?: string;
+    top?: number;
+    skip?: number;
+    select?: readonly string[];
+    expand?: string;
+    count?: boolean;
+};
+export type ODataPage<T> = {
+    items: T[];
+    count?: number;
+};
+export type EntitySetInfo = {
+    name: string;
+    url: string;
+};
+export declare function odataQuery(query: ODataQuery): string;
+/** An OData string literal: single quotes doubled. */
+export declare const literal: (text: string) => string;
+/** Rows whose text fields contain the words, case-insensitive: every word in one of the fields. */
+export declare function searchFilter(fields: readonly string[], text: string): string | undefined;
+export declare function odataPage<T = Record<string, unknown>>(entitySet: string, query?: ODataQuery, options?: CoworkeeClientOptions): Promise<ODataPage<T>>;
+/** The entity sets the OData service document lists. */
+export declare function entitySets(options?: CoworkeeClientOptions): Promise<EntitySetInfo[]>;

package/dist/odata.js

@@ -0,0 +1,27 @@
+import { apiRequest } from "./client.js";
+export function odataQuery(query) {
+    const parts = [
+        ['$filter', query.filter], ['$orderby', query.orderBy], ['$select', query.select?.join(',')], ['$expand', query.expand],
+        ['$top', query.top?.toString()], ['$skip', query.skip ? query.skip.toString() : undefined], ['$count', query.count ? 'true' : undefined],
+    ];
+    const text = parts.filter(([, value]) => value).map(([name, value]) => `${name}=${encodeURIComponent(value)}`).join('&');
+    return text ? `?${text}` : '';
+}
+/** An OData string literal: single quotes doubled. */
+export const literal = (text) => `'${text.replace(/'/g, "''")}'`;
+/** Rows whose text fields contain the words, case-insensitive: every word in one of the fields. */
+export function searchFilter(fields, text) {
+    const words = text.trim().toLowerCase().split(/\s+/).filter(Boolean);
+    if (fields.length === 0 || words.length === 0)
+        return undefined;
+    return words.map((word) => `(${fields.map((field) => `contains(tolower(${field}),${literal(word)})`).join(' or ')})`).join(' and ');
+}
+export async function odataPage(entitySet, query = {}, options) {
+    const page = await apiRequest(`/odata/${encodeURIComponent(entitySet)}${odataQuery(query)}`, {}, options);
+    return { items: page?.value ?? [], count: page?.['@odata.count'] };
+}
+/** The entity sets the OData service document lists. */
+export async function entitySets(options) {
+    const document = await apiRequest('/odata', {}, options);
+    return (document?.value ?? []).filter((item) => (item.kind ?? 'EntitySet') === 'EntitySet').map(({ name, url }) => ({ name, url }));
+}

package/dist/realtime.d.ts

@@ -0,0 +1,43 @@
+import { type HubConnection } from '@microsoft/signalr';
+/** What the realtime hub of a Coworkee app sends: an event of a type on a topic (user:{id}, tenant:presence, type:{Entity}, ...). */
+export type RealtimeEnvelope<T = unknown> = {
+    topic: string;
+    type: string;
+    payload: T;
+};
+export type EntityChanged = {
+    entityType: string;
+    entityId: string;
+    action: 'Created' | 'Updated' | 'Deleted';
+    changedProperties: string[];
+};
+export type RealtimeHandler = (envelope: RealtimeEnvelope) => void;
+export type Realtime = {
+    /** Follows a topic; the returned function stops it. Topics the server refuses are left out silently. */
+    subscribe: (topic: string, handler: RealtimeHandler) => () => void;
+    stop: () => Promise<void>;
+};
+export declare const realtimeTopics: {
+    readonly hub: "/hubs/realtime";
+    readonly user: (userId: string) => string;
+    readonly type: (entityType: string) => string;
+    readonly entity: (entityType: string, id: string) => string;
+    readonly presence: "tenant:presence";
+    readonly tenantPermissions: "tenant:permissions";
+    readonly globalPermissions: "global:permissions";
+};
+export declare const realtimeEvents: {
+    readonly entityChanged: "EntityChanged";
+    readonly sessionRevoked: "SessionRevoked";
+    readonly presenceChanged: "presence.changed";
+    readonly chatMessage: "chat.message";
+    readonly chatRead: "chat.read";
+};
+/**
+ * The realtime hub of the app (SignalR through the BFF, which adds the token). Connects on the first subscription and subscribes every
+ * followed topic again after a reconnect.
+ */
+export declare function createRealtime(options?: {
+    baseUrl?: string;
+    connection?: HubConnection;
+}): Realtime;

package/dist/realtime.js

@@ -0,0 +1,64 @@
+import { HubConnectionBuilder, HubConnectionState } from '@microsoft/signalr';
+export const realtimeTopics = {
+    hub: '/hubs/realtime',
+    user: (userId) => `user:${userId}`,
+    type: (entityType) => `type:${entityType}`,
+    entity: (entityType, id) => `entity:${entityType}:${id}`,
+    presence: 'tenant:presence',
+    tenantPermissions: 'tenant:permissions',
+    globalPermissions: 'global:permissions',
+};
+export const realtimeEvents = { entityChanged: 'EntityChanged', sessionRevoked: 'SessionRevoked', presenceChanged: 'presence.changed', chatMessage: 'chat.message', chatRead: 'chat.read' };
+/** Every retry after 0, 2, 10, then 30 seconds, forever - like the Blazor client. */
+const delays = [0, 2000, 10000, 30000];
+/**
+ * The realtime hub of the app (SignalR through the BFF, which adds the token). Connects on the first subscription and subscribes every
+ * followed topic again after a reconnect.
+ */
+export function createRealtime(options = {}) {
+    const handlers = new Map();
+    let connection = options.connection;
+    let started;
+    let wired = false;
+    const connect = () => {
+        connection ??= new HubConnectionBuilder()
+            .withUrl(`${options.baseUrl ?? ''}${realtimeTopics.hub}`, { withCredentials: true })
+            .withAutomaticReconnect({ nextRetryDelayInMilliseconds: (context) => delays[Math.min(context.previousRetryCount, delays.length - 1)] })
+            .build();
+        if (!wired) {
+            wired = true;
+            connection.on('OnEvent', (envelope) => handlers.get(envelope.topic)?.forEach((handler) => handler(envelope)));
+            connection.onreconnected(() => { for (const topic of handlers.keys())
+                void invoke('Subscribe', topic); });
+        }
+        started = connection.state === HubConnectionState.Disconnected
+            ? connection.start().then(() => true, () => { started = undefined; return false; })
+            : started ?? Promise.resolve(true);
+        return started;
+    };
+    const invoke = async (method, topic) => {
+        try {
+            await connection?.invoke(method, topic);
+        }
+        catch { /* not allowed or not connected: the topic stays quiet */ }
+    };
+    return {
+        subscribe(topic, handler) {
+            let set = handlers.get(topic);
+            const first = !set;
+            if (!set)
+                handlers.set(topic, set = new Set());
+            set.add(handler);
+            if (first)
+                void connect().then((ok) => ok && handlers.has(topic) ? invoke('Subscribe', topic) : undefined);
+            return () => {
+                if (!set.delete(handler) || set.size > 0)
+                    return;
+                handlers.delete(topic);
+                if (connection?.state === HubConnectionState.Connected)
+                    void invoke('Unsubscribe', topic);
+            };
+        },
+        stop: async () => { handlers.clear(); started = undefined; await connection?.stop(); },
+    };
+}