@contello/sdk-client 8.21.0 → 8.22.0

package/README.md

@@ -0,0 +1,124 @@
+# @contello/sdk-client
+
+GraphQL SDK client for Contello CMS with WebSocket transport and connection pooling.
+
+## Installation
+
+```bash
+npm install @contello/sdk-client rxjs graphql graphql-ws
+```
+
+## Usage
+
+### Basic setup
+
+```ts
+import { ContelloSdkClient } from '@contello/sdk-client';
+import { getSdk } from './generated-sdk';
+
+const client = new ContelloSdkClient(getSdk, {
+  url: 'https://example.com',
+  project: 'myProjectId',
+  token: 'app-a123b456c7890d123456789',
+});
+
+await client.connect();
+
+const result = await client.sdk.someQuery({ id: '123' });
+```
+
+### Connection pooling
+
+By default, the client maintains a pool of 5 WebSocket connections and round-robins requests across them.
+
+```ts
+const client = new ContelloSdkClient(getSdk, {
+  url: 'https://example.com',
+  project: 'myProjectId',
+  token: 'token',
+  pooling: {
+    size: 10,
+  },
+});
+```
+
+To disable pooling:
+
+```ts
+pooling: {
+  enabled: false;
+}
+```
+
+### Middleware
+
+Middlewares can intercept requests and outgoing WebSocket messages.
+
+```ts
+import type { ContelloSdkClientMiddleware } from '@contello/sdk-client';
+
+const loggingMiddleware: ContelloSdkClientMiddleware = {
+  onRequest(request, next) {
+    console.log(`${request.kind}: ${request.operationName}`);
+
+    return next();
+  },
+};
+
+const client = new ContelloSdkClient(getSdk, {
+  url: 'https://example.com',
+  project: 'myProjectId',
+  token: 'token',
+  middlewares: [loggingMiddleware],
+});
+```
+
+### Client events
+
+```ts
+const client = new ContelloSdkClient(getSdk, {
+  url: 'https://example.com',
+  project: 'myProjectId',
+  token: 'token',
+  client: {
+    retryAttempts: 5,
+    onConnected: (ctx) => console.log(`connected: ${ctx.connectionId}`),
+    onError: (ctx, error) => console.error(`error on ${ctx.connectionId}:`, error),
+    onClosed: (ctx) => console.log(`closed: ${ctx.connectionId}`),
+  },
+});
+```
+
+### Disconnect
+
+```ts
+await client.disconnect();
+```
+
+> `connect()` resolves once all WebSocket connections in the pool have been acknowledged by the server. The underlying transport retries automatically on transient failures, so the promise will stay pending until every connection succeeds. If retries are exhausted the promise will remain unresolved.
+
+## API
+
+### `ContelloSdkClient`
+
+| Option                 | Type                            | Default | Description                          |
+| ---------------------- | ------------------------------- | ------- | ------------------------------------ |
+| `url`                  | `string`                        | —       | Base URL of the Contello server      |
+| `project`              | `string`                        | —       | Project identifier                   |
+| `token`                | `string`                        | —       | Authentication token                 |
+| `middlewares`          | `ContelloSdkClientMiddleware[]` | `[]`    | Request/message middlewares          |
+| `pooling.enabled`      | `boolean`                       | `true`  | Enable connection pooling            |
+| `pooling.size`         | `number`                        | `5`     | Number of WebSocket connections      |
+| `client.retryAttempts` | `number`                        | `3`     | Retry attempts on connection failure |
+
+### Methods
+
+| Method         | Returns         | Description                |
+| -------------- | --------------- | -------------------------- |
+| `sdk`          | `T`             | The generated SDK instance |
+| `connect()`    | `Promise<void>` | Open WebSocket connections |
+| `disconnect()` | `Promise<void>` | Close all connections      |
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,250 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ContelloSdkClient: () => ContelloSdkClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_graphql_ws = require("graphql-ws");
+var import_rxjs2 = require("rxjs");
+
+// src/diagnostics.ts
+var import_node_diagnostics_channel = __toESM(require("diagnostics_channel"), 1);
+var channels = {
+  start: "contello:sdk.start",
+  end: "contello:sdk.end",
+  error: "contello:sdk.error",
+  /** subscribe to decorate outgoing GraphQL WebSocket messages (e.g. inject traceparent) */
+  message: "contello:sdk.message"
+};
+var onStart = import_node_diagnostics_channel.default.channel(channels.start);
+var onEnd = import_node_diagnostics_channel.default.channel(channels.end);
+var onError = import_node_diagnostics_channel.default.channel(channels.error);
+var onMessage = import_node_diagnostics_channel.default.channel(channels.message);
+function hasOperationSubscribers() {
+  return onStart.hasSubscribers || onEnd.hasSubscribers || onError.hasSubscribers;
+}
+function getWrap() {
+  if (!hasOperationSubscribers()) {
+    return void 0;
+  }
+  return (name, fn) => {
+    const start = performance.now();
+    onStart.publish({ name });
+    let result;
+    try {
+      result = fn();
+    } catch (error) {
+      onError.publish({ name, error, durationMs: performance.now() - start });
+      throw error;
+    }
+    if (result instanceof Promise) {
+      return result.then(
+        (r) => {
+          onEnd.publish({ name, durationMs: performance.now() - start });
+          return r;
+        },
+        (error) => {
+          onError.publish({ name, error, durationMs: performance.now() - start });
+          throw error;
+        }
+      );
+    }
+    onEnd.publish({ name, durationMs: performance.now() - start });
+    return result;
+  };
+}
+function decorateMessage(message) {
+  if (!onMessage.hasSubscribers) {
+    return message;
+  }
+  const msg = { message };
+  onMessage.publish(msg);
+  return msg.message;
+}
+
+// src/pool.ts
+var ConnectionPool = class {
+  constructor(createClient2, poolSize) {
+    this.createClient = createClient2;
+    this.poolSize = poolSize;
+  }
+  clients = [];
+  currentIndex = 0;
+  async connect() {
+    const connected = [];
+    for (let i = 0; i < this.poolSize; i++) {
+      const client = this.createClient(`${i + 1}`);
+      this.clients.push(client);
+      connected.push(
+        new Promise((resolve) => {
+          const unsubscribe = client.on("connected", () => {
+            unsubscribe();
+            resolve();
+          });
+        })
+      );
+    }
+    await Promise.all(connected);
+  }
+  get() {
+    if (this.clients.length === 0) {
+      throw new Error("Connection pool is empty. Please call connect() first.");
+    }
+    const client = this.clients[this.currentIndex];
+    this.currentIndex = (this.currentIndex + 1) % this.poolSize;
+    if (!client) {
+      throw new Error("No available WebSocket client");
+    }
+    return client;
+  }
+  async disconnect() {
+    const closed = this.clients.map(
+      (client) => new Promise((resolve) => {
+        const unsubscribe = client.on("closed", () => {
+          unsubscribe();
+          resolve();
+        });
+        client.dispose();
+      })
+    );
+    this.clients = [];
+    await Promise.all(closed);
+  }
+};
+
+// src/sdk.ts
+var import_rxjs = require("rxjs");
+var createSdk = (client, getSdk) => {
+  return getSdk((doc, vars, options) => {
+    if (options) {
+      console.warn("options are not supported yet");
+    }
+    const query = doc.loc?.source.body;
+    if (!query) {
+      throw new Error("No query provided");
+    }
+    if (vars && typeof vars !== "object") {
+      throw new Error("Variables must be an object");
+    }
+    const operationDef = doc.definitions.find((def) => def.kind === "OperationDefinition");
+    if (!operationDef) {
+      throw new Error("No operation definition found");
+    }
+    const kind = operationDef.operation;
+    const execute = () => {
+      const wsClient = client();
+      const res = new import_rxjs.Observable((obs) => wsClient.subscribe({ query, variables: vars }, obs));
+      return kind !== "subscription" ? (0, import_rxjs.firstValueFrom)(res) : res;
+    };
+    const wrapFn = getWrap();
+    if (wrapFn && kind !== "subscription") {
+      return wrapFn(`sdk:${operationDef.name?.value ?? ""}`, execute);
+    }
+    return execute();
+  });
+};
+
+// src/client.ts
+var ContelloSdkClient = class {
+  _pool;
+  _sdk;
+  constructor(getSdk, params) {
+    const { url, project, token, client, pooling } = params;
+    const websocketUrl = `${url}/graphql/projects/${project}`.replace(/^http/i, "ws");
+    this._pool = new ConnectionPool(
+      (id) => {
+        const context = Object.freeze({ connectionId: id, websocketUrl });
+        return (0, import_graphql_ws.createClient)({
+          url: websocketUrl,
+          connectionParams: { authorization: `Bearer ${token}` },
+          lazy: false,
+          keepAlive: 3e4,
+          retryAttempts: client?.retryAttempts ?? 3,
+          shouldRetry: () => true,
+          jsonMessageReplacer: (key, value) => {
+            if (!key) {
+              return decorateMessage(value);
+            }
+            return value;
+          },
+          ...client?.onError ? { onNonLazyError: (e) => client.onError(context, e) } : {},
+          on: {
+            ...client?.onError ? { error: (e) => client.onError(context, e) } : {},
+            ...client?.onConnected ? { connected: () => client.onConnected(context) } : {},
+            ...client?.onClosed ? { closed: () => client.onClosed(context) } : {},
+            ...client?.onConnecting ? { connecting: () => client.onConnecting(context) } : {},
+            ...client?.onOpened ? { opened: () => client.onOpened(context) } : {},
+            ...client?.onMessage ? { message: (m) => client.onMessage(context, m) } : {},
+            ...client?.onPing ? { ping: () => client.onPing(context) } : {},
+            ...client?.onPong ? { pong: () => client.onPong(context) } : {}
+          }
+        });
+      },
+      pooling?.enabled === false ? 1 : pooling?.size ?? 5
+    );
+    this._sdk = { sdk: createSdk(() => this._pool.get(), getSdk) };
+  }
+  get sdk() {
+    return this._sdk.sdk;
+  }
+  async connect() {
+    await this._pool.connect();
+  }
+  async disconnect() {
+    await this._pool.disconnect();
+  }
+  /**
+   * Subscribes to a raw GraphQL operation against the connection pool.
+   * Returns an Observable that emits each result's data.
+   */
+  subscribe(query, variables) {
+    const wsClient = this._pool.get();
+    return new import_rxjs2.Observable((obs) => wsClient.subscribe({ query, variables }, obs)).pipe(
+      (0, import_rxjs2.map)((r) => r.data)
+    );
+  }
+  /**
+   * Executes a raw GraphQL query/mutation and returns the first result.
+   * Convenience wrapper around subscribe + firstValueFrom.
+   */
+  execute(query, variables) {
+    const fn = () => (0, import_rxjs2.firstValueFrom)(this.subscribe(query, variables));
+    const wrap = getWrap();
+    return wrap ? wrap("sdk:execute", fn) : fn();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ContelloSdkClient
+});

package/dist/index.d.cts

@@ -0,0 +1,49 @@
+import { Observable } from 'rxjs';
+import { DocumentNode, ExecutionResult } from 'graphql';
+
+type Requester<C = any, E = unknown> = <R, V>(doc: DocumentNode, vars?: V, options?: C) => Promise<ExecutionResult<R, E>> | Observable<ExecutionResult<R, E>>;
+
+type ClientEventContext = {
+    connectionId: string;
+    websocketUrl: string;
+};
+type ContelloSdkClientParams = {
+    url: string;
+    project: string;
+    token: string;
+    pooling?: {
+        enabled?: boolean | undefined;
+        size?: number | undefined;
+    } | undefined;
+    client?: {
+        retryAttempts?: number | undefined;
+        onError?: (context: ClientEventContext, error: unknown) => void;
+        onConnected?: (context: ClientEventContext) => void;
+        onClosed?: (context: ClientEventContext) => void;
+        onConnecting?: (context: ClientEventContext) => void;
+        onOpened?: (context: ClientEventContext) => void;
+        onMessage?: (context: ClientEventContext, message: any) => void;
+        onPing?: (context: ClientEventContext) => void;
+        onPong?: (context: ClientEventContext) => void;
+    } | undefined;
+};
+declare class ContelloSdkClient<T> {
+    private _pool;
+    private _sdk;
+    constructor(getSdk: <C, E>(requester: Requester<C, E>) => T, params: ContelloSdkClientParams);
+    get sdk(): T;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /**
+     * Subscribes to a raw GraphQL operation against the connection pool.
+     * Returns an Observable that emits each result's data.
+     */
+    subscribe<TData>(query: string, variables?: Record<string, unknown> | undefined): Observable<TData>;
+    /**
+     * Executes a raw GraphQL query/mutation and returns the first result.
+     * Convenience wrapper around subscribe + firstValueFrom.
+     */
+    execute<TData>(query: string, variables?: Record<string, unknown> | undefined): Promise<TData>;
+}
+
+export { ContelloSdkClient, type ContelloSdkClientParams };

package/dist/index.d.ts

@@ -1,53 +1,49 @@
-import { DocumentNode } from 'graphql';
-import { ExecutionResult } from 'graphql';
-import { Observable } from 'rxjs';
-
-declare type ClientEventContext = {
-    connectionId: string;
-    websocketUrl: string;
-};
-
-export declare class ContelloSdkClient<T> {
-    private _pool;
-    private _sdk;
-    constructor(getSdk: <C, E>(requester: Requester<C, E>) => T, params: ContelloSdkClientParams);
-    get sdk(): T;
-    connect(): Promise<void>;
-    disconnect(): Promise<void>;
-}
-
-export declare type ContelloSdkClientMiddleware = {
-    onRequest?: (request: {
-        kind: 'query' | 'mutation' | 'subscription';
-        operationName: string;
-        query: string;
-        variables: Record<string, any>;
-    }, next: () => Observable<any>) => Observable<any>;
-    onOutgoingMessage?: (message: any) => any;
-};
-
-export declare type ContelloSdkClientParams = {
-    url: string;
-    project: string;
-    token: string;
-    middlewares?: ContelloSdkClientMiddleware[] | undefined;
-    pooling?: {
-        enabled?: boolean | undefined;
-        size?: number | undefined;
-    } | undefined;
-    client?: {
-        retryAttempts?: number | undefined;
-        onError?: (context: ClientEventContext, error: unknown) => void;
-        onConnected?: (context: ClientEventContext) => void;
-        onClosed?: (context: ClientEventContext) => void;
-        onConnecting?: (context: ClientEventContext) => void;
-        onOpened?: (context: ClientEventContext) => void;
-        onMessage?: (context: ClientEventContext, message: any) => void;
-        onPing?: (context: ClientEventContext) => void;
-        onPong?: (context: ClientEventContext) => void;
-    } | undefined;
-};
-
-declare type Requester<C = any, E = unknown> = <R, V>(doc: DocumentNode, vars?: V, options?: C) => Promise<ExecutionResult<R, E>> | Observable<ExecutionResult<R, E>>;
-
-export { }
+import { Observable } from 'rxjs';
+import { DocumentNode, ExecutionResult } from 'graphql';
+
+type Requester<C = any, E = unknown> = <R, V>(doc: DocumentNode, vars?: V, options?: C) => Promise<ExecutionResult<R, E>> | Observable<ExecutionResult<R, E>>;
+
+type ClientEventContext = {
+    connectionId: string;
+    websocketUrl: string;
+};
+type ContelloSdkClientParams = {
+    url: string;
+    project: string;
+    token: string;
+    pooling?: {
+        enabled?: boolean | undefined;
+        size?: number | undefined;
+    } | undefined;
+    client?: {
+        retryAttempts?: number | undefined;
+        onError?: (context: ClientEventContext, error: unknown) => void;
+        onConnected?: (context: ClientEventContext) => void;
+        onClosed?: (context: ClientEventContext) => void;
+        onConnecting?: (context: ClientEventContext) => void;
+        onOpened?: (context: ClientEventContext) => void;
+        onMessage?: (context: ClientEventContext, message: any) => void;
+        onPing?: (context: ClientEventContext) => void;
+        onPong?: (context: ClientEventContext) => void;
+    } | undefined;
+};
+declare class ContelloSdkClient<T> {
+    private _pool;
+    private _sdk;
+    constructor(getSdk: <C, E>(requester: Requester<C, E>) => T, params: ContelloSdkClientParams);
+    get sdk(): T;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /**
+     * Subscribes to a raw GraphQL operation against the connection pool.
+     * Returns an Observable that emits each result's data.
+     */
+    subscribe<TData>(query: string, variables?: Record<string, unknown> | undefined): Observable<TData>;
+    /**
+     * Executes a raw GraphQL query/mutation and returns the first result.
+     * Convenience wrapper around subscribe + firstValueFrom.
+     */
+    execute<TData>(query: string, variables?: Record<string, unknown> | undefined): Promise<TData>;
+}
+
+export { ContelloSdkClient, type ContelloSdkClientParams };