@rytass/bpm-core-client 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -8,6 +8,12 @@ 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.1.2 — 2026-05-27
+
+No source changes. Bumped in lockstep with
+`@rytass/bpm-core-nestjs-module@0.1.2` (see its CHANGELOG for the
+migration class-name fix).
+
 ## 0.1.1 — 2026-05-27
 
 No source changes. Version bumped in lockstep with

package/README.md

@@ -18,7 +18,7 @@ functions directly from any framework (Next.js / Vite / Remix / plain Node).
 
 ## Package Status
 
-Current version: `0.0.1`
+Current version: `0.1.2`
 
 The package intentionally stays framework-agnostic so it can be reused from
 Next.js Server Components, Server Actions, plain React, or non-React
@@ -42,6 +42,113 @@ your `tsconfig.json` so the package's `exports` field is honored. Classic
 shipped with this package, but is on TypeScript's long-term deprecation
 path — new projects should opt in to modern resolution.
 
+## Runtime Compatibility
+
+> **TL;DR — the transport is isomorphic (always `fetch`), but session is
+> browser-first.** Out of the box every function works in a browser tab.
+> Server Components, Server Actions, Node CLIs, workers, and Edge Functions
+> can also call the same functions, but the caller is responsible for
+> resolving the endpoint to an absolute URL and for forwarding any
+> session cookie.
+
+### What is identical across runtimes
+
+| Concern             | Behavior                                                                                                                                          |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Transport           | Always `globalThis.fetch`. No `axios`, no `node-fetch`, no `cross-fetch`, no Apollo Link.                                                         |
+| Serialization       | `Content-Type: application/json`; `POST { query, variables }`.                                                                                    |
+| Error model         | Throws `Error` on non-2xx HTTP, on `payload.errors[]`, or on missing `data`.                                                                      |
+| Type guarantees     | Every function returns a typed `Promise<T>` — return shape is identical regardless of where the call runs.                                        |
+
+### What differs across runtimes
+
+| Concern                | Browser                                                                                  | Node SSR / Server Component / CLI                                                                                                     |
+| ---------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Default endpoint       | Same-origin `/graphql` resolves to `https://your-host/graphql`.                          | Same-origin `/graphql` **throws** `TypeError: Failed to parse URL`. Set `NEXT_PUBLIC_API_URL` to an absolute URL.                     |
+| Session cookie         | `credentials: 'include'` automatically sends the HttpOnly cookie issued by `/auth/login`.| `fetch` has no cookie jar; the host must forward the incoming request's `Cookie` header manually.                                     |
+| `loginApi()` storage   | Cookie lands in browser jar, persists across navigations.                                | Returned `Set-Cookie` header is dropped — caller must read and reuse it explicitly.                                                   |
+| `window.location`      | Used to detect `localhost` for the dev fallback endpoint.                                | `typeof window === 'undefined'` → endpoint resolver returns `/graphql` (relative), which is invalid in Node unless overridden.        |
+
+### Server Component / Server Action recipe
+
+Next.js App Router server runtime needs two things: an absolute endpoint and
+a way to relay the inbound `Cookie` header. The recommended pattern is to
+set `NEXT_PUBLIC_API_URL` at build time and pass cookies via the underlying
+`fetch` headers using a wrapper such as Next's `cookies()`:
+
+```ts
+// app/inbox/page.tsx — Server Component
+import { cookies } from 'next/headers';
+
+async function fetchInbox(): Promise<unknown> {
+  const cookieHeader = (await cookies()).toString();
+  const response = await fetch(`${process.env.BPM_API_URL}/graphql`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Cookie: cookieHeader,
+    },
+    body: JSON.stringify({
+      query: 'query Ping { memberCount }',
+    }),
+  });
+  return response.json();
+}
+```
+
+> For SSR cases that need to call **many** typed functions, the cleanest
+> long-term option is to add a `configureBPMClient({ fetch, endpoint })`
+> hook so the typed wrappers can be reused. That is not yet shipped — if
+> you need it, file an issue. Today, Server Component callers either talk
+> to the host directly (as above) or proxy through a Route Handler that
+> runs inside the consumer's browser session.
+
+### Node CLI recipe
+
+CLIs that drive BPM from outside a browser need both an absolute endpoint
+and explicit session management. The auth REST client (`loginApi`,
+`logoutApi`, `readApiCurrentMember`) returns typed bodies but does not
+persist cookies in Node — capture them yourself:
+
+```ts
+// scripts/dump-running-instances.ts
+import { listApprovalInstancesPage } from '@rytass/bpm-core-client/workflow';
+
+process.env.NEXT_PUBLIC_API_URL ??= 'https://bpm.your-host.example/graphql';
+
+// 1. Log in and capture the session cookie manually.
+const loginResponse = await fetch(
+  'https://bpm.your-host.example/auth/login',
+  {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ identifier: 'svc-bot', password: '...' }),
+  },
+);
+const cookieJar = loginResponse.headers.get('set-cookie') ?? '';
+
+// 2. Hand the cookie to subsequent fetches via a small fetch override.
+const originalFetch = globalThis.fetch;
+globalThis.fetch = ((input, init = {}) =>
+  originalFetch(input, {
+    ...init,
+    headers: { ...(init.headers ?? {}), Cookie: cookieJar },
+  })) as typeof fetch;
+
+// 3. Call typed BPM functions as usual.
+const { instances } = await listApprovalInstancesPage({
+  view: 'ALL', state: 'RUNNING', page: 1, pageSize: 1000,
+  searchText: '', templateId: null,
+});
+console.log(instances.length, 'running instances');
+```
+
+### Edge / Workers
+
+Cloudflare Workers, Vercel Edge Functions, and similar V8-isolate runtimes
+ship `fetch` natively and follow the **Node SSR** column above — no
+default endpoint, no cookie jar. Treat them the same as Server Components.
+
 ## Endpoint Resolution
 
 By default the client targets the same origin (no `/api` prefix) — see
@@ -161,8 +268,11 @@ export function useMembers(memberIds: readonly string[]) {
 }
 ```
 
-For Next.js App Router, call the same functions from Server Components or
-Server Actions — they only need standard `fetch`.
+For Next.js App Router Client Components the typed wrappers work
+out of the box (same-origin endpoint, browser cookie jar). For Server
+Components, Server Actions, Route Handlers, Edge runtimes, or plain Node
+CLIs, see **[Runtime Compatibility](#runtime-compatibility)** — those
+runtimes need an absolute endpoint and manual cookie forwarding.
 
 ## Local Development
 

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.1.1",
+  "version": "0.1.3",
   "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.1.0"
+    "@rytass/bpm-core-shared": "^0.1.3"
   },
   "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,169 @@
+import { readGraphQlEndpoint } from './graphql-client';
+
+/**
+ * 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 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 response = await fetch(`${readApiBaseUrl()}${path}`, {
+    credentials: 'include',
+    ...init,
+  });
+
+  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/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();
+      }
+    });
+  });
+});