@rytass/bpm-core-nestjs-module 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -9,6 +9,53 @@ 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.9 — 2026-05-28
+
+### Documentation
+
+- **README "Machine-to-machine authentication" section** added under
+  Auth Context. Documents three patterns for server-side scripts (org
+  seeds, cron workers, integration tests) to authenticate against BPM:
+  (1) service member + login flow with cookie-jar fetch (recommended),
+  (2) service token header for hosts that issue long-lived JWTs,
+  (3) direct cookie injection for testing only.
+- **README "Coexisting with a host's existing `<AuthProvider>`"** added
+  under Auth Context. Explains that BPM's React provider is a separate
+  context safe to nest under a host provider, with three rules of
+  thumb (scope to sub-tree, share cookie jar same-origin, don't
+  double-wrap `<AuthProvider>` directly).
+
+### Why a patch
+
+Documentation only.
+
+## 0.1.8 — 2026-05-28
+
+### Documentation
+
+- **Casbin example BPMAuthContext shape corrected.** The 0.1.6/0.1.7
+  example returned `{ memberId, email, name, roles, permissions,
+  metadata }` — the actual `BPMAuthContext` interface is
+  `{ memberId, roles, permissions, metadata }` (no `email`, no `name`).
+  Example now stashes display data inside `metadata`, with an explicit
+  callout that name/email reach resolvers through `BPMMemberResolver`
+  instead.
+- **`createPosition` / `updatePosition` / `createMembership` /
+  `updateMembership` / `createManagerResolution` exact signatures
+  added** to the org Worked Example section. The 0.1.7 README only
+  listed function names; downstream developers were guessing input
+  shapes (e.g. mandatory `level` and `metadataJson` on positions).
+- **`metadataJson` write-only clarification.** The "host-FK stash"
+  rule was misleading: `metadataJson` is accepted by every mutation
+  but the records returned by `readOrganizationDashboard` do NOT
+  surface a `metadata` field. Updated to "always reconcile by `code`;
+  treat `metadataJson` as audit/debugging breadcrumb, not a live FK
+  pointer."
+
+### Why a patch
+
+Documentation only. No source change.
+
 ## 0.1.7 — 2026-05-28
 
 ### Documentation

package/README.md

@@ -296,6 +296,125 @@ the simplest path is to **not mount `<AuthProvider>` from
 `useAuth()` shim that returns the host's session. This is rare — most
 consumers find Pattern A simpler.
 
+### Machine-to-machine authentication
+
+Server-side scripts (org seeds, cron workers, integration tests) call
+`configureBPMClient` to set the GraphQL base URL and optional default
+headers, then must establish a session. Three patterns work:
+
+#### Pattern 1 — Service member + login flow (recommended)
+
+Create a dedicated BPM admin member (e.g. `bpm-sync@svc.example.com`),
+store its credentials in Vault, and let the script call `loginApi`
+during bootstrap. The login response sets an HTTP-only session cookie
+that subsequent `requestGraphQl` calls automatically include.
+
+```ts
+import { configureBPMClient, loginApi } from '@rytass/bpm-core-client';
+
+async function bootstrap(): Promise<void> {
+  configureBPMClient({
+    baseUrl: process.env.BPM_API_URL ?? 'http://localhost:17603',
+    fetch: globalThis.fetch,
+  });
+  await loginApi({
+    identifier: process.env.BPM_SYNC_IDENTIFIER!,
+    password: process.env.BPM_SYNC_PASSWORD!,
+  });
+  // Subsequent calls to readOrganizationDashboard / createOrgUnit / etc.
+  // automatically forward the session cookie.
+}
+```
+
+Caveats: `globalThis.fetch` on Node 20+ does **not** maintain a cookie
+jar across calls by default — set up one of:
+
+- `undici`'s `Agent` with `cookies` enabled, then `setGlobalDispatcher(agent)`
+- the `tough-cookie` + `node-fetch-cookies` pairing
+- BPM's `configureBPMClient({ fetch: cookieAwareFetch })` injection
+
+Without a cookie jar, the login succeeds but no subsequent call carries
+the session. Most production deployments already use `undici` with
+cookie support; verify before shipping.
+
+#### Pattern 2 — Service token header (when supported by host)
+
+If your wrapper host issues a long-lived service token (e.g. a JWT
+signed with a known shared secret), pass it through
+`configureBPMClient`'s `headers`:
+
+```ts
+configureBPMClient({
+  baseUrl: process.env.BPM_API_URL!,
+  headers: { Authorization: `Bearer ${process.env.BPM_SERVICE_TOKEN!}` },
+});
+```
+
+This requires the wrapper host's auth middleware to honor `Authorization`
+headers (member-base hosts can be configured to do so via
+`authStrategy: 'jwt'` in addition to `cookieMode: true`).
+
+#### Pattern 3 — Direct cookie injection (testing only)
+
+For integration tests where you've already obtained a session cookie
+out-of-band (e.g. from a Playwright fixture), pass it raw:
+
+```ts
+configureBPMClient({
+  baseUrl: 'http://localhost:17603',
+  headers: { Cookie: 'access_token=<jwt>; refresh_token=<jwt>' },
+});
+```
+
+Do not use this in production scripts — cookies expire and the script
+must handle refresh, which means you actually want Pattern 1.
+
+### Coexisting with a host's existing `<AuthProvider>`
+
+Many host applications (Shuttle, custom admin panels) already mount
+their own `<AuthProvider>` at the root of the Next.js tree. BPM's
+`<AuthProvider>` (mounted indirectly via `<BPMNextProviders>`) is a
+**separate context** that only tracks BPM session state. The two do
+not conflict — they coexist as parallel React contexts:
+
+```tsx
+// app/layout.tsx — host's root layout (untouched)
+import { HostAuthProvider } from '@your-host/auth';
+
+export default function RootLayout({ children }) {
+  return (
+    <html><body>
+      <HostAuthProvider>{children}</HostAuthProvider>
+    </body></html>
+  );
+}
+
+// app/operations/approval/layout.tsx — BPM sub-tree
+'use client';
+import { BPMNextProviders } from '@rytass/bpm-core-react/next';
+
+export default function ApprovalLayout({ children }) {
+  return (
+    <BPMNextProviders loginPath="/login">
+      {children}
+    </BPMNextProviders>
+  );
+}
+```
+
+Rules of thumb:
+
+- **Scope `<BPMNextProviders>` to the BPM sub-tree** — never put it at
+  the root. Otherwise every host page goes through BPM's auth gate,
+  which redirects unauthenticated users to BPM's `/login`.
+- **BPM auth and host auth share the cookie jar** when same-origin.
+  If `<BPMNextProviders loginPath="/login">` and the host's auth share
+  `/login`, the same login form can satisfy both — implement the host
+  login endpoint to also satisfy `/auth/login` from BPM's contract.
+- **Do not import `<AuthProvider>` from `@rytass/bpm-core-react`
+  directly** if you've already mounted `<BPMNextProviders>` —
+  double-wrapping creates redundant `/auth/me` polls.
+
 ## Role and Permission Contract
 
 BPM guards inspect `BPMAuthContext.roles` and `BPMAuthContext.permissions` with
@@ -353,16 +472,23 @@ export class BPMAuthContextFactory {
 
     return {
       memberId: member.id,
-      email: member.email,
-      name: member.name,
       roles: bpmRoles,
       permissions: [], // Host can also use `bpm:*` style permissions if preferred.
-      metadata: {},
+      // The BPMAuthContext shape does NOT include name/email — those are
+      // surfaced through BPMMemberResolver instead. If you want them
+      // available to downstream resolvers without an extra resolver call,
+      // stash them in `metadata` (BPM passes it through unchanged).
+      metadata: { name: member.name, email: member.email },
     };
   }
 }
 ```
 
+> **`BPMAuthContext` shape**: `{ memberId, roles, permissions, metadata }`
+> — exactly four fields. The host's `name` / `email` are not part of the
+> contract; resolvers call `BPMMemberResolver.resolve(memberId)` when
+> they need display data.
+
 > The host owns the mapping table. Keep it in one place (a constant
 > module or a database table) so adding a new BPM tier in a future
 > BPMCore release becomes a one-line addition.
@@ -482,10 +608,15 @@ and observable:
    uniqueness; use your host's stable identifier here (e.g. an LDAP DN
    slug or a internal ERP code). On a re-sync, look up existing entities
    by `code` before deciding INSERT vs UPDATE.
-2. **`metadata` is the host-FK stash.** Both `OrgUnit` and `Membership`
-   carry an opaque `metadata` JSON object that BPM never introspects.
-   Store your host's primary key here (e.g. `{ shuttleOrgUnitId: 12345 }`)
-   so you can chase the back-pointer when reconciling.
+2. **`metadataJson` is write-only.** The mutations
+   (`createOrgUnit`/`updateOrgUnit`/`createPosition`/`updatePosition`)
+   accept a `metadataJson` string that BPM stores verbatim. **However**,
+   `OrgUnitRecord` and `PositionRecord` returned by
+   `readOrganizationDashboard` do NOT include the metadata field —
+   it's intentionally hidden so the JSON blob doesn't bloat every
+   pagination payload. **For reconciliation, always key on `code`**
+   (which IS returned). Treat `metadataJson` as a debugging/audit
+   stash, not a live FK pointer.
 3. **Soft delete via `deleteOrgUnit` / `deleteMembership` / `deleteManagerResolution`.** Deletes set
    `deletedAt` rather than removing rows. BPM's query layer hides
    soft-deleted rows automatically; reading `orgUnitCount()` will report
@@ -511,7 +642,11 @@ input shapes — no `{id, input: {...}}` wrapping):
 - `updateOrgUnit({ id, code, name, type, parentId, metadataJson })`
 - `deleteOrgUnit(id)` (soft-delete)
 - `commitOrgUnitTreeDraft({ moves: { id, parentId, baseUpdatedAt }[] })` (transactional batch moves — each entry's `baseUpdatedAt` is the row's last-known `updatedAt`, used by BPM for optimistic-locking conflict detection)
-- `createPosition` / `updatePosition` (key on `code`)
+- `createPosition({ code, name, level, metadataJson })` — `level` (1+) controls hierarchy weight (higher = more senior, used by manager-resolution priority sort); `metadataJson` is required (pass `'{}'` if unused)
+- `updatePosition({ id, code, name, level, metadataJson })` — every field except `id` is `T | null`; pass `null` to leave a field unchanged
+- `createMembership({ memberId, orgUnitId, positionId, isPrimary, effectiveFrom, effectiveTo })` — `positionId` and `effectiveTo` accept `null`; `effectiveFrom` is an ISO timestamp string. Uniqueness key is `(memberId, orgUnitId, positionId)`
+- `updateMembership({ id, orgUnitId, positionId, isPrimary, effectiveFrom, effectiveTo })` — every field except `id` is `T | null`
+- `createManagerResolution({ scopeType, scopeId, managerMemberId, priority, effectiveFrom, effectiveTo })` — `scopeType` is `'MEMBER' | 'ORG_UNIT' | 'POSITION'`; `priority` orders the resolver chain (lower number = checked first)
 - `createMembership` / `updateMembership` (unique by `(memberId, orgUnitId, positionId)`)
 - `createManagerResolution` / `updateManagerResolution`
 
@@ -528,7 +663,7 @@ interface HostOrgUnit {
   readonly hostId: string;          // e.g. ERP primary key — your host-FK
   readonly code: string;            // stable across sync runs
   readonly name: string;
-  readonly type: OrgUnitType;       // 'company' | 'division' | 'department' | 'team'
+  readonly type: OrgUnitType;       // 'COMPANY' | 'DIVISION' | 'DEPARTMENT' | 'TEAM'
   readonly parentCode: string | null;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/bpm-core-nestjs-module",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Embeddable NestJS BPM approval workflow module: workflow engine, approval templates, forms, organization/member contracts, attachments, signatures, notifications, delegation, and TypeORM migrations.",
   "keywords": [
     "bpm",
@@ -141,7 +141,7 @@
     "@nestjs/core": "^11.0.0",
     "@nestjs/graphql": "^13.4.0",
     "@nestjs/typeorm": "^11.0.1",
-    "@rytass/bpm-core-shared": "^0.1.7",
+    "@rytass/bpm-core-shared": "^0.1.9",
     "@rytass/secret-adapter-vault-nestjs": "^0.4.5 || ^0.5.0",
     "express": "^4.0.0 || ^5.0.0",
     "graphql": "^16.0.0",