@rytass/bpm-core-client 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -8,6 +8,34 @@ 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.5 — 2026-05-28
+
+### Documentation
+
+- **README "Organization mirror pattern" section.** Condensed pointer to
+  the full pattern in `@rytass/bpm-core-nestjs-module`'s README plus a
+  client-side worked example using `createOrgUnit`, `updateOrgUnit`,
+  `deleteOrgUnit`, `commitOrgUnitTreeDraft`, `createPosition`,
+  `createMembership`, `createManagerResolution`. Clarifies that BPM owns
+  the org graph and host applications mirror their existing org data in
+  rather than expose a resolver (in contrast to the member-resolver
+  pattern).
+
+### Why a patch
+
+No type or runtime change. README only.
+
+## 0.1.4 — 2026-05-27
+
+No source changes. Bumped in lockstep with
+`@rytass/bpm-core-nestjs-module@0.1.4` (re-publish after the 0.1.3
+backend tarball shipped only `.ts` source — see that package's CHANGELOG).
+
+## 0.1.3 — 2026-05-27 (deprecated on npm)
+
+Lockstep bump alongside the broken 0.1.3 backend release. Avoid;
+upgrade directly to 0.1.4 or newer.
+
 ## 0.1.2 — 2026-05-27
 
 No source changes. Bumped in lockstep with

package/README.md

@@ -151,9 +151,9 @@ 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
-[`docs/10-bpm-embedding-auth.md`](../../docs/10-bpm-embedding-auth.md) for the
-host contract. Endpoint resolution rules:
+By default the client targets the same origin (no `/api` prefix) — see the
+"Embedding & auth" section of `@rytass/bpm-core-nestjs-module`'s README for
+the host-side contract. Endpoint resolution rules:
 
 | Source                                          | Behavior                                                                   |
 | ----------------------------------------------- | -------------------------------------------------------------------------- |
@@ -206,6 +206,72 @@ Every subpath uses the same `requestGraphQl` transport from the root. Hosts
 can mix and match — for example a read-only dashboard might only import
 `workflow` queries, never reaching for `/organization` mutations.
 
+## Organization Mirror Pattern (Important)
+
+> **TL;DR:** BPM owns the org graph (`org_units`, `positions`,
+> `memberships`, `manager_resolutions`). Hosts with their own org model
+> mirror data **into** BPM via the `/organization` mutations rather than
+> exposing a host-side resolver. See the
+> "Organization Data Ownership" section of
+> `@rytass/bpm-core-nestjs-module`'s README for the rationale.
+
+The integration shape is **asymmetric** with `BPMMemberResolver`:
+member identity stays in the host's user table and BPM reaches in via
+the resolver token; the org structure lives in BPM and the host pushes
+data in. Three rules keep the mirror idempotent:
+
+1. **Use `code` as the natural key.** Both `OrgUnit` and `Position`
+   carry a unique `code` you control. On every sync, look up by `code`
+   before deciding INSERT vs UPDATE.
+2. **Stash the host-FK in `metadata`.** Both entities carry an opaque
+   `metadata` JSON BPM never introspects — store your host's primary
+   key there to chase pointers back during reconciliation.
+3. **Soft-delete via the `delete*` mutations.** They set `deletedAt`;
+   live queries (`orgUnits`, `orgUnitCount`, etc.) filter soft-deleted
+   rows automatically.
+
+Quick wire-up using only this package's exports:
+
+```ts
+import {
+  createOrgUnit,
+  updateOrgUnit,
+  orgUnits,
+} from '@rytass/bpm-core-client/organization';
+
+async function upsertOrgUnit(hostUnit: {
+  code: string;
+  name: string;
+  type: 'COMPANY' | 'DIVISION' | 'DEPARTMENT' | 'TEAM';
+  parentCode: string | null;
+  hostId: string;
+}): Promise<string> {
+  const existing = (await orgUnits({ searchText: hostUnit.code })).find(
+    (u) => u.code === hostUnit.code,
+  );
+  const parentId = hostUnit.parentCode
+    ? (await orgUnits({ searchText: hostUnit.parentCode })).find(
+        (u) => u.code === hostUnit.parentCode,
+      )?.id ?? null
+    : null;
+  const metadataJson = JSON.stringify({ hostId: hostUnit.hostId });
+
+  if (existing) {
+    return (
+      await updateOrgUnit({
+        id: existing.id,
+        input: { ...hostUnit, parentId, metadataJson },
+      })
+    ).id;
+  }
+  return (await createOrgUnit({ ...hostUnit, parentId, metadataJson })).id;
+}
+```
+
+`createPosition`, `createMembership`, `updateMembership`, and
+`createManagerResolution` follow the same pattern. For bulk tree moves
+in one transaction, see `commitOrgUnitTreeDraft`.
+
 ## Auth REST Endpoints
 
 The BPM wrapper-host exposes the following endpoints under the host root (no

package/package.json

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