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

package/CHANGELOG.md

@@ -9,6 +9,30 @@ 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.10 — 2026-05-28
+
+### Documentation
+
+- **Pattern A response status contract table** added — explicit success
+  / auth-fail / validation-fail HTTP status codes for `/auth/login`,
+  `/auth/me`, `/auth/logout`. Also notes that `roles` and `permissions`
+  must be arrays (not `null`/`undefined`), and shows the
+  `projectMemberToApiMember` skeleton mapping `ApiMember.email: string`
+  (not `string | null`).
+- **"Concrete wiring" snippet** for the recommended same-database
+  separate-schema option B: dual `TypeOrmModule.forRootAsync` with
+  `name: 'bpm'` so the host's existing connection and BPM's stay
+  isolated. Also shows handing `typeormConnectionName: 'bpm'` to
+  `BPMRootModule.forRootAsync`.
+- **`createBPMMemberBaseResolverProvider<HostMember>` generic** added
+  to the README example with a callout about why omitting it causes
+  TS to infer `unknown`.
+- "Current version" line refreshed to `0.1.10`.
+
+### Why a patch
+
+Documentation only.
+
 ## 0.1.9 — 2026-05-28
 
 ### Documentation

package/README.md

@@ -14,7 +14,7 @@ directory integration, storage adapters, and deployment.
 
 ## Package Status
 
-Current version: `0.1.7`
+Current version: `0.1.10`
 
 The package is intended for NestJS backend hosts. It does not include the
 Next.js backoffice UI and does not provide a production auth system by itself.
@@ -273,6 +273,31 @@ member shape to BPM's expectations, project Casbin roles into the BPM
 role-literal strings (see "Mapping from a host RBAC system" below),
 and compute `expiresAt` from the token TTL.
 
+```ts
+function projectMemberToApiMember(member: HostMember): ApiMember {
+  return {
+    memberId: member.id,
+    email: member.email ?? '',         // ApiMember.email is `string`, not `string | null`
+    name: member.name,
+    roles: projectHostRolesToBPMRoles(member.roles), // [] if no admin/designer claim
+    permissions: [],                   // optional — return [] if not used
+    expiresAt: new Date(Date.now() + JWT_TTL_MS).toISOString(),
+  };
+}
+```
+
+Response status contract that BPM's React client expects:
+
+| Endpoint | Success | Auth fail | Validation fail |
+|---|---|---|---|
+| `POST /auth/login` | `200` + `ApiMember` JSON, set HTTP-only cookie | `401` | `400` |
+| `GET /auth/me` | `200` + `ApiMember` JSON | `401` (client treats as anonymous, **not error**) | n/a |
+| `POST /auth/logout` | `204` (or `200` with empty body) | `401` ignored — client clears local state anyway | n/a |
+
+`roles` and `permissions` MUST be arrays (use `[]` for no claim), not
+`null` or `undefined` — the React client's `member.roles.includes(...)`
+checks would crash otherwise.
+
 #### Pattern B — Run BPM on a separate auth host
 
 When BPM lives on its own subdomain (e.g. `bpm.example.com`) separate
@@ -531,7 +556,10 @@ export const hostMemberProviders: readonly Provider[] = [
     provide: HOST_MEMBER_DIRECTORY,
     useClass: HostMemberDirectory,
   },
-  createBPMMemberBaseResolverProvider({
+  createBPMMemberBaseResolverProvider<HostMember>({
+    // ^^^^^^^^^^^^ explicit generic is recommended — without it,
+    // TS infers `unknown` for the adapter callbacks below and you get
+    // "Parameter 'member' implicitly has an 'any' type" errors.
     adapterOptions: {
       readEmail: (member): string => member.email,
       readMemberId: (member): string => member.id,
@@ -910,6 +938,40 @@ BPM's `buildTypeOrmModuleOptions` create **two distinct connections**
 to the same Postgres cluster with different `schema:` settings — that
 is the cleanest separation Nest's TypeORM module supports.
 
+Concrete wiring:
+
+```ts
+// apps/api/src/app/app.module.ts
+@Module({
+  imports: [
+    // Host's existing TypeORM connection (default name, host's schema).
+    TypeOrmModule.forRootAsync({
+      imports: [HostVaultModule],
+      inject: [HostVaultService],
+      useFactory: (vault) => buildHostDataSourceOptions(vault),  // schema: 'public'
+    }),
+    // BPM's own connection (named, separate schema, separate Vault path).
+    TypeOrmModule.forRootAsync({
+      name: 'bpm',                              // <-- distinct connection name
+      imports: [BPMVaultModule],
+      inject: [BPMVaultService],
+      useFactory: buildTypeOrmModuleOptions,    // reads DB_SCHEMA=bpm_core from Vault
+    }),
+    // Hand BPM the connection name so its repositories bind to the right pool.
+    BPMRootModule.forRootAsync({
+      typeormConnectionName: 'bpm',
+      // ...
+    }),
+  ],
+})
+```
+
+If the host runs only one Vault path (e.g. `shuttle/develop`) and you
+want to keep secrets there, expose `bpm_core/*` keys under the host
+path with a prefix and provide a custom factory that reads them — BPM
+doesn't require its own Vault path, only that the secrets are
+available to `buildTypeOrmModuleOptions`.
+
 Vault paths can be split independently: keep `shuttle/develop` for the
 host and create `bpm_core/develop` for BPM secrets. BPM's helper reads
 its own path; the host's auth module reads its own. They do not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/bpm-core-nestjs-module",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "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.9",
+    "@rytass/bpm-core-shared": "^0.1.10",
     "@rytass/secret-adapter-vault-nestjs": "^0.4.5 || ^0.5.0",
     "express": "^4.0.0 || ^5.0.0",
     "graphql": "^16.0.0",