@rytass/bpm-core-client 0.1.2 → 0.1.4

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/bpm-core-client",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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,7 +73,7 @@
     }
   },
   "peerDependencies": {
-    "@rytass/bpm-core-shared": "^0.1.0"
+    "@rytass/bpm-core-shared": "^0.1.4"
   },
   "dependencies": {
     "tslib": "^2.3.0"