@rytass/bpm-core-client 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -8,6 +8,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Releases are managed by [`nx release`](https://nx.dev/recipes/nx-release) with
 Conventional Commits — see `nx.json` for the release config.
 
+## 0.5.0 — 2026-07-06
+
+No source changes. Version aligned with `@rytass/bpm-core-shared` and
+`@rytass/bpm-core-nestjs-module` 0.5.0 (fixed release group).
+
+### Changed
+
+- Peer dependency `@rytass/bpm-core-shared` now requires ^0.5.0.
+
 ## 0.4.0 — 2026-07-02
 
 ### Fixed

package/eslint.config.mjs

@@ -0,0 +1,19 @@
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredFiles: ['{projectRoot}/eslint.config.{js,cjs,mjs,ts,cts,mts}'],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: await import('jsonc-eslint-parser'),
+    },
+  },
+];

package/jest.config.cts

@@ -0,0 +1,10 @@
+module.exports = {
+  displayName: 'bpm-core-client',
+  preset: '../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../coverage/libs/bpm-core-client',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/bpm-core-client",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Framework-agnostic TypeScript client for the Rytass BPM approval workflow GraphQL surface: fetch-based GraphQL transport, REST auth client, pre-baked typed operations for organization, member, form, template, and workflow.",
   "keywords": [
     "bpm",
@@ -73,10 +73,9 @@
     }
   },
   "peerDependencies": {
-    "@rytass/bpm-core-shared": "^0.4.0"
+    "@rytass/bpm-core-shared": "^0.5.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"
-  },
-  "type": "commonjs"
+  }
 }

package/project.json

@@ -0,0 +1,66 @@
+{
+  "name": "bpm-core-client",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/bpm-core-client/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/bpm-core-client",
+        "main": "libs/bpm-core-client/src/index.ts",
+        "tsConfig": "libs/bpm-core-client/tsconfig.lib.json",
+        "generatePackageJson": true,
+        "assets": [
+          "libs/bpm-core-client/*.md",
+          { "input": ".", "glob": "LICENSE", "output": "." }
+        ]
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/libs/bpm-core-client"],
+      "options": {
+        "jestConfig": "libs/bpm-core-client/jest.config.cts",
+        "passWithNoTests": true
+      }
+    },
+    "typecheck": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "tsc --noEmit -p libs/bpm-core-client/tsconfig.lib.json"
+      }
+    },
+    "finalize-dist": {
+      "executor": "nx:run-commands",
+      "outputs": ["{workspaceRoot}/dist/libs/bpm-core-client"],
+      "dependsOn": ["build"],
+      "options": {
+        "command": "node tools/publish/finalize-dist-package.mjs dist/libs/bpm-core-client"
+      }
+    },
+    "pkg-quality": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["finalize-dist"],
+      "options": {
+        "commands": [
+          "pnpm exec publint dist/libs/bpm-core-client"
+        ],
+        "parallel": false
+      }
+    },
+    "pkg-quality-attw": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["finalize-dist"],
+      "options": {
+        "command": "pnpm exec attw --pack dist/libs/bpm-core-client"
+      }
+    },
+    "prepublish-check": {
+      "executor": "nx:noop",
+      "dependsOn": ["typecheck", "lint", "test", "finalize-dist", "pkg-quality"]
+    }
+  }
+}

package/src/lib/api-auth-client.ts

@@ -0,0 +1,182 @@
+import { readGraphQlEndpoint } from './graphql-client';
+import {
+  readBPMClientConfig,
+  readBPMConfiguredHeaders,
+  resolveBPMFetch,
+} from './client-config';
+
+/**
+ * Authenticated BPM member returned by {@link loginApi} and
+ * {@link readApiCurrentMember}.
+ *
+ * Mirrors the shape that BPM-compatible wrapper hosts emit from their
+ * `POST /auth/login` and `GET /auth/me` endpoints. Roles and permissions
+ * are used by BPM's `BPMAdminGuard` / `BPMDesignerGuard`.
+ */
+export interface ApiMember {
+  readonly email: string;
+  readonly expiresAt: string;
+  readonly memberId: string;
+  readonly name: string;
+  readonly permissions: readonly string[];
+  readonly roles: readonly string[];
+}
+
+/**
+ * Reduced member shape returned by {@link listApiTestMembers}. Excludes
+ * `permissions` and `expiresAt` because the test-members endpoint is meant
+ * for picker UIs in dev / demo, not for session establishment.
+ */
+export interface ApiPublicMember {
+  readonly email: string;
+  readonly memberId: string;
+  readonly name: string;
+  readonly roles: readonly string[];
+}
+
+/**
+ * Lists seeded test members exposed by the host's `/auth/test-members`
+ * endpoint. Hosts targeting production typically disable this endpoint or
+ * gate it behind a feature flag.
+ */
+export async function listApiTestMembers(): Promise<
+  readonly ApiPublicMember[]
+> {
+  return requestApi<readonly ApiPublicMember[]>('/auth/test-members');
+}
+
+/**
+ * Performs a login against the host's `POST /auth/login` endpoint. On
+ * success the host issues an HTTP-only session cookie that subsequent
+ * {@link requestGraphQl} calls automatically carry, because
+ * {@link requestApi} uses `credentials: 'include'`.
+ *
+ * Throws on HTTP errors with a message extracted from the response body
+ * when available.
+ *
+ * @param input.identifier - Member id, email, or any other identifier the
+ *                           host understands.
+ * @param input.password   - Cleartext credential — TLS is the consumer's
+ *                           responsibility.
+ */
+export async function loginApi(input: {
+  readonly identifier: string;
+  readonly password: string;
+}): Promise<ApiMember> {
+  return requestApi<ApiMember>('/auth/login', {
+    body: JSON.stringify(input),
+    headers: { 'Content-Type': 'application/json' },
+    method: 'POST',
+  });
+}
+
+/**
+ * Calls `POST /auth/logout` on the host. The host clears the session
+ * cookie. Safe to call when not logged in (host should return 200).
+ */
+export async function logoutApi(): Promise<void> {
+  await requestApi<{ readonly ok: true }>('/auth/logout', {
+    method: 'POST',
+  });
+}
+
+/**
+ * Reads the currently authenticated member from `GET /auth/me`.
+ *
+ * Returns `null` when the host replies `401`, which is the conventional
+ * way to signal "no active session". Any other HTTP failure throws.
+ */
+export async function readApiCurrentMember(): Promise<ApiMember | null> {
+  try {
+    return await requestApi<ApiMember>('/auth/me');
+  } catch (error: unknown) {
+    if (error instanceof ApiRequestError && error.status === 401) {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * Resolves the base URL used by the REST `/auth/*` calls.
+ *
+ * Resolution order:
+ * 1. `process.env.NEXT_PUBLIC_API_AUTH_URL` if non-empty.
+ * 2. Derived from {@link readGraphQlEndpoint}'s origin — the host is
+ *    assumed to expose both `/graphql` and `/auth/*` at the same origin.
+ */
+export function readApiBaseUrl(): string {
+  const config = readBPMClientConfig();
+  if (config.authBaseUrl?.trim()) {
+    return config.authBaseUrl.trim().replace(/\/$/, '');
+  }
+
+  const explicitApiBaseUrl = process.env.NEXT_PUBLIC_API_AUTH_URL?.trim();
+
+  if (explicitApiBaseUrl) {
+    return explicitApiBaseUrl.replace(/\/$/, '');
+  }
+
+  const graphQlEndpoint = readGraphQlEndpoint();
+
+  return resolveApiBaseUrlFromGraphQlEndpoint(graphQlEndpoint);
+}
+
+export function resolveApiBaseUrlFromGraphQlEndpoint(
+  graphQlEndpoint: string,
+): string {
+  if (!isAbsoluteUrl(graphQlEndpoint)) {
+    return '';
+  }
+
+  const endpoint = new URL(graphQlEndpoint);
+  endpoint.pathname = '/';
+  endpoint.search = '';
+  endpoint.hash = '';
+  return endpoint.toString().replace(/\/$/, '');
+}
+
+async function requestApi<TData>(
+  path: string,
+  init?: RequestInit,
+): Promise<TData> {
+  const fetchImpl = resolveBPMFetch();
+  const configuredHeaders = readBPMConfiguredHeaders();
+  const response = await fetchImpl(`${readApiBaseUrl()}${path}`, {
+    credentials: 'include',
+    ...init,
+    headers: { ...configuredHeaders, ...(init?.headers ?? {}) },
+  });
+
+  if (!response.ok) {
+    throw new ApiRequestError(response.status, await readError(response));
+  }
+
+  return (await response.json()) as TData;
+}
+
+async function readError(response: Response): Promise<string> {
+  try {
+    const payload = (await response.json()) as { readonly message?: unknown };
+
+    return typeof payload.message === 'string'
+      ? payload.message
+      : `BPM API request failed with HTTP ${response.status}`;
+  } catch {
+    return `BPM API request failed with HTTP ${response.status}`;
+  }
+}
+
+class ApiRequestError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+function isAbsoluteUrl(value: string): boolean {
+  return value.startsWith('http://') || value.startsWith('https://');
+}

package/src/lib/client-config.ts

@@ -0,0 +1,99 @@
+/**
+ * Programmatic configuration override for the BPM client transport.
+ *
+ * The default endpoint resolution (`NEXT_PUBLIC_API_URL` → localhost →
+ * same-origin) covers Next.js consumers. Node-side scripts (cron
+ * workers, one-off org seeds, integration tests) usually cannot rely on
+ * environment variables and need a programmatic hook. Call
+ * {@link configureBPMClient} once at startup; subsequent
+ * `requestGraphQl` and REST auth calls honor the override.
+ */
+
+export interface BPMClientConfig {
+  /**
+   * Override the GraphQL endpoint URL. When provided, takes precedence
+   * over `NEXT_PUBLIC_API_URL` and the default localhost / same-origin
+   * resolution. Pass an absolute URL ending without `/graphql` to also
+   * derive the REST `/auth/*` base URL automatically, or pass the full
+   * `https://host/graphql` form to set the GraphQL endpoint directly.
+   *
+   * If you need different bases for GraphQL vs `/auth/*` (rare — most
+   * hosts colocate them), set both `baseUrl` and `authBaseUrl`.
+   */
+  readonly baseUrl?: string;
+
+  /**
+   * Override the REST `/auth/*` base URL independently of `baseUrl`.
+   * Most hosts colocate GraphQL and auth on the same origin; this knob
+   * exists for the rare split-origin deployment.
+   */
+  readonly authBaseUrl?: string;
+
+  /**
+   * Replace the global `fetch` implementation. Useful when running on a
+   * runtime without a global `fetch` (older Node versions, edge runtimes
+   * with custom polyfills) or when you want to inject a tracing wrapper.
+   */
+  readonly fetch?: typeof fetch;
+
+  /**
+   * Additional headers merged into every outbound request. Use this to
+   * pass service tokens, tracing headers, or a server-side session
+   * cookie that the browser would normally send automatically.
+   *
+   * Note: `Content-Type` is set internally for GraphQL POSTs and
+   * cannot be overridden through this option.
+   */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+let currentConfig: BPMClientConfig = {};
+
+/**
+ * Sets the active {@link BPMClientConfig}. Subsequent calls **replace**
+ * the previous configuration; pass `{}` to reset to environment-based
+ * defaults.
+ *
+ * Idiomatic call site is the very top of a Node worker's bootstrap:
+ *
+ * ```ts
+ * import { configureBPMClient } from '@rytass/bpm-core-client';
+ *
+ * configureBPMClient({
+ *   baseUrl: 'https://api.shuttle.example.com',
+ *   headers: { 'X-Service-Token': process.env.BPM_SYNC_TOKEN ?? '' },
+ * });
+ * ```
+ *
+ * Browser consumers under Next.js typically do **not** need to call
+ * this — `NEXT_PUBLIC_API_URL` plus same-origin defaults cover the
+ * common case.
+ */
+export function configureBPMClient(config: BPMClientConfig): void {
+  currentConfig = { ...config };
+}
+
+/**
+ * Reads the active {@link BPMClientConfig}. Exposed primarily for tests
+ * and for inspecting the current override at runtime — consumers should
+ * use {@link configureBPMClient} to mutate, never reach in directly.
+ */
+export function readBPMClientConfig(): BPMClientConfig {
+  return currentConfig;
+}
+
+/**
+ * Resolves the effective `fetch` implementation honoring the active
+ * override, falling back to the global `fetch`.
+ */
+export function resolveBPMFetch(): typeof fetch {
+  return currentConfig.fetch ?? globalThis.fetch;
+}
+
+/**
+ * Returns the headers configured via {@link configureBPMClient}.
+ * Internal transports merge these into every outbound request.
+ */
+export function readBPMConfiguredHeaders(): Readonly<Record<string, string>> {
+  return currentConfig.headers ?? {};
+}

package/src/lib/form/form-api.spec.ts

@@ -0,0 +1,81 @@
+import { createFormDefinition, listFormDefinitions } from './form-api';
+
+interface CapturedRequest {
+  readonly query: string;
+  readonly variables?: Readonly<Record<string, unknown>>;
+}
+
+function installFetchMock<TData>(payload: TData): {
+  readonly capture: () => CapturedRequest;
+  readonly restore: () => void;
+} {
+  const originalFetch = global.fetch;
+  const fetchMock = jest.fn<
+    Promise<Response>,
+    [RequestInfo | URL, RequestInit?]
+  >();
+  fetchMock.mockImplementation(
+    async () =>
+      new Response(JSON.stringify({ data: payload }), {
+        headers: { 'Content-Type': 'application/json' },
+        status: 200,
+      }),
+  );
+  (global as { fetch: typeof fetch }).fetch =
+    fetchMock as unknown as typeof fetch;
+
+  return {
+    capture: (): CapturedRequest => {
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      const init = fetchMock.mock.calls[0]?.[1];
+      return JSON.parse(String(init?.body ?? '{}')) as CapturedRequest;
+    },
+    restore: (): void => {
+      (global as { fetch: typeof fetch }).fetch = originalFetch;
+    },
+  };
+}
+
+describe('@rytass/bpm-core-client/form', () => {
+  describe('listFormDefinitions', () => {
+    it('issues the FormDefinitions query and returns the array', async (): Promise<void> => {
+      const harness = installFetchMock({ formDefinitions: [] });
+      try {
+        const records = await listFormDefinitions();
+        const request = harness.capture();
+
+        expect(request.query).toContain('query FormDefinitions');
+        expect(request.variables).toBeUndefined();
+        expect(records).toEqual([]);
+      } finally {
+        harness.restore();
+      }
+    });
+  });
+
+  describe('createFormDefinition', () => {
+    it('wraps the name in a CreateFormDefinitionInput and returns the new id', async (): Promise<void> => {
+      const harness = installFetchMock({
+        createFormDefinition: { id: 'form-1' },
+      });
+      try {
+        const id = await createFormDefinition('Vacation request');
+        const request = harness.capture();
+
+        expect(request.query).toContain('mutation CreateFormDefinition');
+        expect(request.variables).toEqual({
+          input: {
+            createdByMemberId: null,
+            description: null,
+            name: 'Vacation request',
+            schemaJson: null,
+            uiSchemaJson: null,
+          },
+        });
+        expect(id).toBe('form-1');
+      } finally {
+        harness.restore();
+      }
+    });
+  });
+});