@rytass/bpm-core-nestjs-module 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -9,6 +9,55 @@ 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
+
+- **Identity contract clarifications.** `BPMMemberResolver.resolve` JSDoc
+  now states the unknown-id contract explicitly (throw
+  `MemberNotFoundException`); `resolveMany` documents the diverging
+  partial-success contract (omit unknown ids from the returned `Map`).
+  Both methods cross-link `identityMemberMetadataCacheTtlMs`
+  (default 5 min) so consumers know BPM caches their resolver responses.
+- **`BPMRootModule` JSDoc dangling refs removed.** The previous
+  references to `docs/10-bpm-embedding-auth.md` and
+  `docs/11-consumer-quickstart.md` (files that never shipped) are now
+  inline pointers to the README sections.
+- **New "Organization data ownership" README section.** Documents that
+  BPM is authoritative for `org_units`, `positions`, `memberships`, and
+  `manager_resolutions` (no host-injectable resolver pattern, unlike
+  members), the rationale (approver-routing / tree-diff hot path), the
+  mirror pattern using `OrgUnit.code` as the natural key and the
+  `metadata` JSON for host foreign-keys, and an idempotent worked
+  example using only `@rytass/bpm-core-client/organization` exports.
+
+### Why a patch
+
+No public type signatures change. JSDoc + README only.
+
+## 0.1.4 — 2026-05-27
+
+### Fixed
+
+- **Re-publish of the 0.1.3 release.** The 0.1.3 tarball was inadvertently
+  published from `libs/bpm-core/` instead of from `dist/libs/bpm-core/`,
+  shipping only TypeScript sources with `main: "./src/index.js"` pointing
+  at non-existent files. 0.1.3 has been **deprecated on npm**. The
+  publish procedure (`docs/api-reference.md` Publish Procedure section
+  and `tools/publish/finalize-dist-package.mjs` header) now codifies the
+  correct flow: `nx build` → `finalize-dist-package.mjs` →
+  `cd dist/libs/<pkg> && npm publish`.
+
+### Documentation
+
+- Publish-procedure-from-dist section added to `docs/api-reference.md`.
+- `tools/publish/finalize-dist-package.mjs` header warning expanded.
+
+## 0.1.3 — 2026-05-27 (deprecated on npm)
+
+**DO NOT INSTALL — broken release.** Published from source dir instead
+of dist dir; tarball contains only `.ts` files. Use 0.1.4 or newer.
+
 ## 0.1.2 — 2026-05-27
 
 ### Fixed

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rytass
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -275,6 +275,149 @@ export interface BPMMemberResolver {
 }
 ```
 
+## Organization Data Ownership
+
+> **Read this before integrating BPM into a host that already has its own
+> organization model.** The org-integration shape is **asymmetric** with
+> member integration above — knowing which side owns what saves a day of
+> source spelunking.
+
+### Ownership claim
+
+BPM is the **sole authority** for four organization tables:
+
+| Table | Owns |
+|---|---|
+| `org_units` | Department / division / company nodes (typed by `OrgUnitType`) |
+| `positions` | Job titles, with optional org-unit scoping |
+| `memberships` | Member × org-unit × position relations (the join table that puts a member at a position inside a unit) |
+| `manager_resolutions` | "Who is whose manager" rules (per-member, per-org-unit, or per-position scope), consumed by the `ORG_MANAGER` approver resolver |
+
+There is **no** host-injectable `OrgUnitResolver` / `PositionResolver` /
+`MembershipResolver` pattern, deliberately so. If you went looking for
+the symmetric counterpart to `BPMMemberResolver`, stop now — it doesn't
+exist, and the rest of this section explains why and what to do instead.
+
+### Why no resolver
+
+The BPM workflow engine reads the org graph on hot paths:
+
+- **Approver routing** — every running instance evaluates `UserTaskNode`
+  candidates (resolved via `DIRECT`, `POSITION`, `ORG_MANAGER`, or
+  `CANDIDATE_GROUP`) against the current org snapshot. A `ParallelGateway`
+  fanning out to "all managers in the IT division" may touch dozens of
+  membership rows in one step.
+- **Tree-diff commits** — `commitOrgUnitTreeDraft` writes batched moves
+  inside a single transaction, with referential integrity against
+  `memberships` and `manager_resolutions`. Round-tripping each lookup
+  through a host adapter would make this prohibitively chatty.
+- **Reporting** — admin dashboards aggregate counts across the full graph.
+
+A read-through adapter would force the host to mirror BPM's tree
+semantics (ltree paths, soft-delete masking, position-vs-org-unit join
+shape) anyway. We chose to make BPM authoritative so the contract is one
+direction only.
+
+### Mirror pattern
+
+Host applications that already maintain their own org structure should
+**mirror their data into BPM** through the GraphQL mutations exposed by
+`@rytass/bpm-core-client/organization`. Three rules keep this idempotent
+and observable:
+
+1. **`OrgUnit.code` is your natural key.** Every `createOrgUnit` /
+   `createPosition` accepts a `code` field that you control. BPM enforces
+   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.
+3. **Soft delete via `deleteOrgUnit` / `deleteMembership`.** Deletes set
+   `deletedAt` rather than removing rows. BPM's query layer hides
+   soft-deleted rows automatically; reading `orgUnitCount()` will report
+   the live count.
+
+### Worked example: idempotent sync
+
+The example below uses only published exports from
+`@rytass/bpm-core-client/organization`. It pushes a host org tree into
+BPM, handling the create-or-update path by checking `code` matches.
+Verified exports: `orgUnits`, `createOrgUnit`, `updateOrgUnit`,
+`deleteOrgUnit`, `createPosition`, `createMembership`, `updateMembership`,
+`createManagerResolution`, `commitOrgUnitTreeDraft`.
+
+```ts
+import {
+  createOrgUnit,
+  updateOrgUnit,
+  createPosition,
+  createMembership,
+  orgUnits,
+  type OrgUnitRecord,
+} from '@rytass/bpm-core-client/organization';
+
+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: 'COMPANY' | 'DIVISION' | 'DEPARTMENT' | 'TEAM';
+  readonly parentCode: string | null;
+}
+
+async function syncOrgUnit(host: HostOrgUnit): Promise<OrgUnitRecord> {
+  // 1. Look up by host's stable code; BPM enforces uniqueness.
+  const existing = (
+    await orgUnits({ page: 1, pageSize: 1, searchText: host.code })
+  ).find((u) => u.code === host.code);
+
+  const parentId = host.parentCode
+    ? (await orgUnits({ searchText: host.parentCode })).find(
+        (u) => u.code === host.parentCode,
+      )?.id ?? null
+    : null;
+
+  // 2. Stash the host-FK back into metadata so future reconciliations
+  //    can chase the pointer either direction.
+  const metadataJson = JSON.stringify({ hostId: host.hostId });
+
+  if (existing) {
+    return updateOrgUnit({
+      id: existing.id,
+      input: {
+        code: host.code,
+        name: host.name,
+        type: host.type,
+        parentId,
+        metadataJson,
+      },
+    });
+  }
+
+  return createOrgUnit({
+    code: host.code,
+    name: host.name,
+    type: host.type,
+    parentId,
+    metadataJson,
+  });
+}
+```
+
+The same pattern works for `Position` (key on `code`), `Membership`
+(unique by `memberId × orgUnitId × positionId`), and
+`ManagerResolution` (unique by scope shape + active flag). For bulk
+tree-shape changes (multi-node moves under a single parent),
+`commitOrgUnitTreeDraft` accepts the full draft in one transaction.
+
+### What you do NOT mirror
+
+Member identity itself stays in your host's user table — BPM reaches it
+through `BPMMemberResolver` (see the previous section). Only the
+**org structure** (who reports where, what unit they sit in, who manages
+them) needs to live inside BPM.
+
 ## Root Module Configuration
 
 Use `BPMRootModule.forRoot()` for static configuration or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/bpm-core-nestjs-module",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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.3",
+    "@rytass/bpm-core-shared": "^0.1.5",
     "@rytass/secret-adapter-vault-nestjs": "^0.4.5 || ^0.5.0",
     "express": "^4.0.0 || ^5.0.0",
     "graphql": "^16.0.0",
@@ -165,4 +165,4 @@
     "nodemailer": "^8.0.7",
     "tslib": "^2.3.0"
   }
-}
+}

package/src/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./lib/attachment"), exports);
+tslib_1.__exportStar(require("./lib/bpm"), exports);
+tslib_1.__exportStar(require("./lib/bpm-auth"), exports);
+tslib_1.__exportStar(require("./lib/common"), exports);
+tslib_1.__exportStar(require("./lib/condition"), exports);
+tslib_1.__exportStar(require("./lib/database"), exports);
+tslib_1.__exportStar(require("./lib/delegation"), exports);
+tslib_1.__exportStar(require("./lib/form"), exports);
+tslib_1.__exportStar(require("./lib/identity"), exports);
+tslib_1.__exportStar(require("./lib/notification"), exports);
+tslib_1.__exportStar(require("./lib/organization"), exports);
+tslib_1.__exportStar(require("./lib/signature"), exports);
+tslib_1.__exportStar(require("./lib/template"), exports);
+tslib_1.__exportStar(require("./lib/workflow-engine"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/bpm-core/src/index.ts"],"names":[],"mappings":";;;AAAA,2DAAiC;AACjC,oDAA0B;AAC1B,yDAA+B;AAC/B,uDAA6B;AAC7B,0DAAgC;AAChC,yDAA+B;AAC/B,2DAAiC;AACjC,qDAA2B;AAC3B,yDAA+B;AAC/B,6DAAmC;AACnC,6DAAmC;AACnC,0DAAgC;AAChC,yDAA+B;AAC/B,gEAAsC"}

package/src/lib/attachment/attachment-options.d.ts

@@ -0,0 +1,44 @@
+import { InjectionToken } from '@nestjs/common';
+export interface BPMRootAttachmentOptions {
+    /**
+     * Public HTTP base URL used to build signed attachment download and preview
+     * URLs.
+     */
+    readonly attachmentPublicBaseUrl?: string | null;
+    /**
+     * Route prefix used by the host application for BPM attachment endpoints.
+     *
+     * Drives both the Nest controller mount path and the path embedded in BPM
+     * signed attachment URLs. Defaults to `/attachments`.
+     */
+    readonly attachmentRoutePrefix?: string | null;
+    /**
+     * HMAC secret used to sign attachment download and preview tokens.
+     */
+    readonly attachmentSignedUrlSecret?: string | null;
+    /**
+     * Signed attachment URL lifetime in seconds.
+     */
+    readonly attachmentSignedUrlTtlSeconds?: number;
+    /**
+     * Storage provider id recorded on attachment metadata.
+     */
+    readonly attachmentStorageProviderId?: string | null;
+}
+export interface BPMResolvedAttachmentOptions {
+    readonly publicBaseUrl: string;
+    readonly routePrefix: string;
+    readonly signedUrlSecret: string;
+    readonly signedUrlTtlSeconds: number;
+    readonly storageProviderId: string;
+}
+export declare const BPM_ATTACHMENT_OPTIONS: InjectionToken<BPMResolvedAttachmentOptions>;
+export declare const DEFAULT_BPM_ATTACHMENT_OPTIONS: BPMResolvedAttachmentOptions;
+export declare function resolveBPMAttachmentOptions(options?: BPMRootAttachmentOptions): BPMResolvedAttachmentOptions;
+/**
+ * Normalizes an attachment route prefix into the form Nest expects on a
+ * controller decorator (no leading slash, no trailing slash).
+ *
+ * Returns the BPM default `attachments` path when no value is provided.
+ */
+export declare function resolveAttachmentControllerPath(value: string | null | undefined): string;

package/src/lib/attachment/attachment-options.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BPM_ATTACHMENT_OPTIONS = exports.BPM_ATTACHMENT_OPTIONS = void 0;
+exports.resolveBPMAttachmentOptions = resolveBPMAttachmentOptions;
+exports.resolveAttachmentControllerPath = resolveAttachmentControllerPath;
+exports.BPM_ATTACHMENT_OPTIONS = Symbol('BPM_ATTACHMENT_OPTIONS');
+exports.DEFAULT_BPM_ATTACHMENT_OPTIONS = {
+    publicBaseUrl: 'http://localhost:17603',
+    routePrefix: '/attachments',
+    signedUrlSecret: 'bpm-core-local-attachment-url-key-v1',
+    signedUrlTtlSeconds: 300,
+    storageProviderId: 'local',
+};
+function resolveBPMAttachmentOptions(options = {}) {
+    const resolvedSignedUrlSecret = normalizeText(options.attachmentSignedUrlSecret) ??
+        exports.DEFAULT_BPM_ATTACHMENT_OPTIONS.signedUrlSecret;
+    if (resolvedSignedUrlSecret === exports.DEFAULT_BPM_ATTACHMENT_OPTIONS.signedUrlSecret &&
+        process.env.NODE_ENV === 'production') {
+        // eslint-disable-next-line no-console
+        console.warn('[@rytass/bpm-core-nestjs-module] attachmentSignedUrlSecret is using the built-in local development value. Set BPMRootModuleOptions.attachmentSignedUrlSecret to a strong secret before serving production traffic — signed attachment URLs would otherwise be forgeable.');
+    }
+    return {
+        publicBaseUrl: normalizePublicBaseUrl(options.attachmentPublicBaseUrl),
+        routePrefix: normalizeRoutePrefix(options.attachmentRoutePrefix),
+        signedUrlSecret: resolvedSignedUrlSecret,
+        signedUrlTtlSeconds: normalizePositiveInteger(options.attachmentSignedUrlTtlSeconds, exports.DEFAULT_BPM_ATTACHMENT_OPTIONS.signedUrlTtlSeconds),
+        storageProviderId: normalizeText(options.attachmentStorageProviderId) ??
+            exports.DEFAULT_BPM_ATTACHMENT_OPTIONS.storageProviderId,
+    };
+}
+/**
+ * Normalizes an attachment route prefix into the form Nest expects on a
+ * controller decorator (no leading slash, no trailing slash).
+ *
+ * Returns the BPM default `attachments` path when no value is provided.
+ */
+function resolveAttachmentControllerPath(value) {
+    const normalizedPrefix = normalizeRoutePrefix(value);
+    return normalizedPrefix.replace(/^\//, '');
+}
+function normalizePublicBaseUrl(value) {
+    const normalizedValue = normalizeText(value) ?? exports.DEFAULT_BPM_ATTACHMENT_OPTIONS.publicBaseUrl;
+    return normalizedValue.replace(/\/+$/, '');
+}
+function normalizeRoutePrefix(value) {
+    const normalizedValue = normalizeText(value) ?? exports.DEFAULT_BPM_ATTACHMENT_OPTIONS.routePrefix;
+    const withLeadingSlash = normalizedValue.startsWith('/')
+        ? normalizedValue
+        : `/${normalizedValue}`;
+    return withLeadingSlash.replace(/\/+$/, '');
+}
+function normalizeText(value) {
+    const trimmedValue = value?.trim() ?? '';
+    return trimmedValue || null;
+}
+function normalizePositiveInteger(value, fallback) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+        return fallback;
+    }
+    return value;
+}
+//# sourceMappingURL=attachment-options.js.map

package/src/lib/attachment/attachment-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-options.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/attachment/attachment-options.ts"],"names":[],"mappings":";;;AAoDA,kEA6BC;AAQD,0EAMC;AAtDY,QAAA,sBAAsB,GACjC,MAAM,CAAC,wBAAwB,CAAC,CAAC;AAEtB,QAAA,8BAA8B,GAAiC;IAC1E,aAAa,EAAE,wBAAwB;IACvC,WAAW,EAAE,cAAc;IAC3B,eAAe,EAAE,sCAAsC;IACvD,mBAAmB,EAAE,GAAG;IACxB,iBAAiB,EAAE,OAAO;CAC3B,CAAC;AAEF,SAAgB,2BAA2B,CACzC,UAAoC,EAAE;IAEtC,MAAM,uBAAuB,GAC3B,aAAa,CAAC,OAAO,CAAC,yBAAyB,CAAC;QAChD,sCAA8B,CAAC,eAAe,CAAC;IAEjD,IACE,uBAAuB,KAAK,sCAA8B,CAAC,eAAe;QAC1E,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EACrC,CAAC;QACD,sCAAsC;QACtC,OAAO,CAAC,IAAI,CACV,0QAA0Q,CAC3Q,CAAC;IACJ,CAAC;IAED,OAAO;QACL,aAAa,EAAE,sBAAsB,CAAC,OAAO,CAAC,uBAAuB,CAAC;QACtE,WAAW,EAAE,oBAAoB,CAAC,OAAO,CAAC,qBAAqB,CAAC;QAChE,eAAe,EAAE,uBAAuB;QACxC,mBAAmB,EAAE,wBAAwB,CAC3C,OAAO,CAAC,6BAA6B,EACrC,sCAA8B,CAAC,mBAAmB,CACnD;QACD,iBAAiB,EACf,aAAa,CAAC,OAAO,CAAC,2BAA2B,CAAC;YAClD,sCAA8B,CAAC,iBAAiB;KACnD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,+BAA+B,CAC7C,KAAgC;IAEhC,MAAM,gBAAgB,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAErD,OAAO,gBAAgB,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,sBAAsB,CAAC,KAAgC;IAC9D,MAAM,eAAe,GACnB,aAAa,CAAC,KAAK,CAAC,IAAI,sCAA8B,CAAC,aAAa,CAAC;IAEvE,OAAO,eAAe,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAgC;IAC5D,MAAM,eAAe,GACnB,aAAa,CAAC,KAAK,CAAC,IAAI,sCAA8B,CAAC,WAAW,CAAC;IACrE,MAAM,gBAAgB,GAAG,eAAe,CAAC,UAAU,CAAC,GAAG,CAAC;QACtD,CAAC,CAAC,eAAe;QACjB,CAAC,CAAC,IAAI,eAAe,EAAE,CAAC;IAE1B,OAAO,gBAAgB,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,aAAa,CAAC,KAAgC;IACrD,MAAM,YAAY,GAAG,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAEzC,OAAO,YAAY,IAAI,IAAI,CAAC;AAC9B,CAAC;AAED,SAAS,wBAAwB,CAC/B,KAAyB,EACzB,QAAgB;IAEhB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACxE,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/src/lib/attachment/attachment-storage.provider.d.ts

@@ -0,0 +1,4 @@
+import { Provider } from '@nestjs/common';
+import { AttachmentStorage } from './attachment-storage.token';
+export declare const attachmentStorageProvider: Provider<AttachmentStorage>;
+export declare function createLocalAttachmentStorage(directory: string): AttachmentStorage;

package/src/lib/attachment/attachment-storage.provider.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachmentStorageProvider = void 0;
+exports.createLocalAttachmentStorage = createLocalAttachmentStorage;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const attachment_storage_token_1 = require("./attachment-storage.token");
+exports.attachmentStorageProvider = {
+    provide: attachment_storage_token_1.ATTACHMENT_STORAGE,
+    useFactory: () => createLocalAttachmentStorage((0, path_1.resolve)(process.cwd(), '.storage', 'attachments')),
+};
+function createLocalAttachmentStorage(directory) {
+    const storageDirectory = (0, path_1.resolve)(directory);
+    const LocalStorage = readLocalStorageConstructor();
+    const localStorage = new LocalStorage({
+        autoMkdir: true,
+        directory: storageDirectory,
+    });
+    const write = async (file, options) => {
+        if (options?.filename) {
+            await (0, promises_1.mkdir)((0, path_1.dirname)((0, path_1.resolve)(storageDirectory, options.filename)), {
+                recursive: true,
+            });
+        }
+        return localStorage.write(file, options);
+    };
+    return new Proxy(localStorage, {
+        get: (target, property, receiver) => property === 'write' ? write : Reflect.get(target, property, receiver),
+    });
+}
+function readLocalStorageConstructor() {
+    const adapter = require('@rytass/storages-adapter-local');
+    return adapter.LocalStorage;
+}
+//# sourceMappingURL=attachment-storage.provider.js.map

package/src/lib/attachment/attachment-storage.provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-storage.provider.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/attachment/attachment-storage.provider.ts"],"names":[],"mappings":";;;AA2BA,oEA0BC;AApDD,0CAAoC;AACpC,+BAAwC;AACxC,yEAGoC;AAavB,QAAA,yBAAyB,GAAgC;IACpE,OAAO,EAAE,6CAAkB;IAC3B,UAAU,EAAE,GAAsB,EAAE,CAClC,4BAA4B,CAC1B,IAAA,cAAO,EAAC,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,aAAa,CAAC,CAClD;CACJ,CAAC;AAEF,SAAgB,4BAA4B,CAC1C,SAAiB;IAEjB,MAAM,gBAAgB,GAAG,IAAA,cAAO,EAAC,SAAS,CAAC,CAAC;IAC5C,MAAM,YAAY,GAAG,2BAA2B,EAAE,CAAC;IACnD,MAAM,YAAY,GAAG,IAAI,YAAY,CAAC;QACpC,SAAS,EAAE,IAAI;QACf,SAAS,EAAE,gBAAgB;KAC5B,CAAC,CAAC;IACH,MAAM,KAAK,GAA+B,KAAK,EAC7C,IAAI,EACJ,OAAO,EACiC,EAAE;QAC1C,IAAI,OAAO,EAAE,QAAQ,EAAE,CAAC;YACtB,MAAM,IAAA,gBAAK,EAAC,IAAA,cAAO,EAAC,IAAA,cAAO,EAAC,gBAAgB,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE;gBAChE,SAAS,EAAE,IAAI;aAChB,CAAC,CAAC;QACL,CAAC;QAED,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC,CAAC;IAEF,OAAO,IAAI,KAAK,CAAC,YAAY,EAAE;QAC7B,GAAG,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAW,EAAE,CAC3C,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC;KACzE,CAAsB,CAAC;AAC1B,CAAC;AAED,SAAS,2BAA2B;IAClC,MAAM,OAAO,GAAG,OAAO,CAAC,gCAAgC,CAAuB,CAAC;IAEhF,OAAO,OAAO,CAAC,YAAY,CAAC;AAC9B,CAAC"}

package/src/lib/attachment/{attachment-storage.token.ts → attachment-storage.token.d.ts}

@@ -1,5 +1,3 @@
 import type { Storage } from '@rytass/storages';
-
-export const ATTACHMENT_STORAGE = Symbol('ATTACHMENT_STORAGE');
-
+export declare const ATTACHMENT_STORAGE: unique symbol;
 export type AttachmentStorage = Storage<Readonly<Record<string, unknown>>>;

package/src/lib/attachment/attachment-storage.token.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ATTACHMENT_STORAGE = void 0;
+exports.ATTACHMENT_STORAGE = Symbol('ATTACHMENT_STORAGE');
+//# sourceMappingURL=attachment-storage.token.js.map

package/src/lib/attachment/attachment-storage.token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-storage.token.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/attachment/attachment-storage.token.ts"],"names":[],"mappings":";;;AAEa,QAAA,kBAAkB,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC"}

package/src/lib/attachment/attachment.controller.d.ts

@@ -0,0 +1,8 @@
+import { StreamableFile } from '@nestjs/common';
+import type { Response } from 'express';
+import { AttachmentService } from './attachment.service';
+export declare class AttachmentController {
+    private readonly attachmentService;
+    constructor(attachmentService: AttachmentService);
+    downloadAttachment(id: string, token: string, disposition: "attachment" | "inline" | undefined, response: Response): Promise<StreamableFile>;
+}

package/src/lib/attachment/attachment.controller.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachmentController = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const attachment_service_1 = require("./attachment.service");
+let AttachmentController = class AttachmentController {
+    constructor(attachmentService) {
+        this.attachmentService = attachmentService;
+    }
+    async downloadAttachment(id, token, disposition = 'attachment', response) {
+        const { attachment, buffer } = await this.attachmentService.readSignedAttachment({
+            disposition,
+            id,
+            token,
+        });
+        response.setHeader('Content-Type', attachment.mimeType);
+        response.setHeader('Content-Disposition', `${disposition}; filename="${encodeURIComponent(attachment.filename)}"`);
+        response.setHeader('Content-Length', String(buffer.length));
+        return new common_1.StreamableFile(buffer);
+    }
+};
+exports.AttachmentController = AttachmentController;
+tslib_1.__decorate([
+    (0, common_1.Get)(':id/download'),
+    tslib_1.__param(0, (0, common_1.Param)('id')),
+    tslib_1.__param(1, (0, common_1.Query)('token')),
+    tslib_1.__param(2, (0, common_1.Query)('disposition')),
+    tslib_1.__param(3, (0, common_1.Res)({ passthrough: true })),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [String, String, String, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], AttachmentController.prototype, "downloadAttachment", null);
+exports.AttachmentController = AttachmentController = tslib_1.__decorate([
+    (0, common_1.Controller)('attachments'),
+    tslib_1.__metadata("design:paramtypes", [attachment_service_1.AttachmentService])
+], AttachmentController);
+//# sourceMappingURL=attachment.controller.js.map

package/src/lib/attachment/attachment.controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment.controller.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/attachment/attachment.controller.ts"],"names":[],"mappings":";;;;AAAA,2CAOwB;AAExB,6DAAyD;AAGlD,IAAM,oBAAoB,GAA1B,MAAM,oBAAoB;IAC/B,YAA6B,iBAAoC;QAApC,sBAAiB,GAAjB,iBAAiB,CAAmB;IAAG,CAAC;IAG/D,AAAN,KAAK,CAAC,kBAAkB,CACT,EAAU,EACP,KAAa,EACP,cAAuC,YAAY,EAC7C,QAAkB;QAE9C,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAC1B,MAAM,IAAI,CAAC,iBAAiB,CAAC,oBAAoB,CAAC;YAChD,WAAW;YACX,EAAE;YACF,KAAK;SACN,CAAC,CAAC;QAEL,QAAQ,CAAC,SAAS,CAAC,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;QACxD,QAAQ,CAAC,SAAS,CAChB,qBAAqB,EACrB,GAAG,WAAW,eAAe,kBAAkB,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CACxE,CAAC;QACF,QAAQ,CAAC,SAAS,CAAC,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QAE5D,OAAO,IAAI,uBAAc,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;CACF,CAAA;AA1BY,oDAAoB;AAIzB;IADL,IAAA,YAAG,EAAC,cAAc,CAAC;IAEjB,mBAAA,IAAA,cAAK,EAAC,IAAI,CAAC,CAAA;IACX,mBAAA,IAAA,cAAK,EAAC,OAAO,CAAC,CAAA;IACd,mBAAA,IAAA,cAAK,EAAC,aAAa,CAAC,CAAA;IACpB,mBAAA,IAAA,YAAG,EAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAA;;;;8DAiB5B;+BAzBU,oBAAoB;IADhC,IAAA,mBAAU,EAAC,aAAa,CAAC;6CAEwB,sCAAiB;GADtD,oBAAoB,CA0BhC"}

package/src/lib/attachment/attachment.entity.d.ts

@@ -0,0 +1,14 @@
+export declare class AttachmentEntity {
+    id: string;
+    instanceId: string | null;
+    taskId: string | null;
+    formFieldPath: string | null;
+    uploaderMemberId: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: string;
+    storageProvider: string;
+    storageKey: string;
+    checksumSha256: string;
+    createdAt: Date;
+}

package/src/lib/attachment/attachment.entity.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachmentEntity = void 0;
+const tslib_1 = require("tslib");
+const graphql_1 = require("@nestjs/graphql");
+const typeorm_1 = require("typeorm");
+let AttachmentEntity = class AttachmentEntity {
+};
+exports.AttachmentEntity = AttachmentEntity;
+tslib_1.__decorate([
+    (0, typeorm_1.PrimaryGeneratedColumn)('uuid'),
+    (0, graphql_1.Field)(() => graphql_1.ID),
+    tslib_1.__metadata("design:type", String)
+], AttachmentEntity.prototype, "id", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)('uuid', { name: 'instance_id', nullable: true }),
+    (0, graphql_1.Field)(() => graphql_1.ID, { nullable: true }),
+    tslib_1.__metadata("design:type", Object)
+], AttachmentEntity.prototype, "instanceId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)('uuid', { name: 'task_id', nullable: true }),
+    (0, graphql_1.Field)(() => graphql_1.ID, { nullable: true }),
+    tslib_1.__metadata("design:type", Object)
+], AttachmentEntity.prototype, "taskId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)('text', { name: 'form_field_path', nullable: true }),
+    (0, graphql_1.Field)(() => String, { nullable: true }),
+    tslib_1.__metadata("design:type", Object)
+], AttachmentEntity.prototype, "formFieldPath", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)('text', { name: 'uploader_member_id' }),
+    (0, graphql_1.Field)(),
+    tslib_1.__metadata("design:type", String)
+], AttachmentEntity.prototype, "uploaderMemberId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)('text'),
+    (0, graphql_1.Field)(),
+    tslib_1.__metadata("design:type", String)
+], AttachmentEntity.prototype, "filename", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)('text', { name: 'mime_type' }),
+    (0, graphql_1.Field)(),
+    tslib_1.__metadata("design:type", String)
+], AttachmentEntity.prototype, "mimeType", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)('bigint', { name: 'size_bytes' }),
+    (0, graphql_1.Field)(),
+    tslib_1.__metadata("design:type", String)
+], AttachmentEntity.prototype, "sizeBytes", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)('text', { name: 'storage_provider' }),
+    (0, graphql_1.Field)(),
+    tslib_1.__metadata("design:type", String)
+], AttachmentEntity.prototype, "storageProvider", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)('text', { name: 'storage_key' }),
+    (0, graphql_1.Field)(),
+    tslib_1.__metadata("design:type", String)
+], AttachmentEntity.prototype, "storageKey", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)('text', { name: 'checksum_sha256' }),
+    (0, graphql_1.Field)(),
+    tslib_1.__metadata("design:type", String)
+], AttachmentEntity.prototype, "checksumSha256", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.CreateDateColumn)({ name: 'created_at', type: 'timestamptz' }),
+    (0, graphql_1.Field)(),
+    tslib_1.__metadata("design:type", Date)
+], AttachmentEntity.prototype, "createdAt", void 0);
+exports.AttachmentEntity = AttachmentEntity = tslib_1.__decorate([
+    (0, typeorm_1.Entity)('attachments'),
+    (0, graphql_1.ObjectType)('Attachment')
+], AttachmentEntity);
+//# sourceMappingURL=attachment.entity.js.map

package/src/lib/attachment/attachment.entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment.entity.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/attachment/attachment.entity.ts"],"names":[],"mappings":";;;;AAAA,6CAAwD;AACxD,qCAKiB;AAIV,IAAM,gBAAgB,GAAtB,MAAM,gBAAgB;CAgD5B,CAAA;AAhDY,4CAAgB;AAG3B;IAFC,IAAA,gCAAsB,EAAC,MAAM,CAAC;IAC9B,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,YAAE,CAAC;;4CACJ;AAIZ;IAFC,IAAA,gBAAM,EAAC,MAAM,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACvD,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,YAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;oDACT;AAI3B;IAFC,IAAA,gBAAM,EAAC,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACnD,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,YAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;gDACb;AAIvB;IAFC,IAAA,gBAAM,EAAC,MAAM,EAAE,EAAE,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC3D,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;uDACV;AAI9B;IAFC,IAAA,gBAAM,EAAC,MAAM,EAAE,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;IAC9C,IAAA,eAAK,GAAE;;0DACkB;AAI1B;IAFC,IAAA,gBAAM,EAAC,MAAM,CAAC;IACd,IAAA,eAAK,GAAE;;kDACU;AAIlB;IAFC,IAAA,gBAAM,EAAC,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IACrC,IAAA,eAAK,GAAE;;kDACU;AAIlB;IAFC,IAAA,gBAAM,EAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;IACxC,IAAA,eAAK,GAAE;;mDACW;AAInB;IAFC,IAAA,gBAAM,EAAC,MAAM,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAC;IAC5C,IAAA,eAAK,GAAE;;yDACiB;AAIzB;IAFC,IAAA,gBAAM,EAAC,MAAM,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;IACvC,IAAA,eAAK,GAAE;;oDACY;AAIpB;IAFC,IAAA,gBAAM,EAAC,MAAM,EAAE,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;IAC3C,IAAA,eAAK,GAAE;;wDACgB;AAIxB;IAFC,IAAA,0BAAgB,EAAC,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;IAC7D,IAAA,eAAK,GAAE;sCACI,IAAI;mDAAC;2BA/CN,gBAAgB;IAF5B,IAAA,gBAAM,EAAC,aAAa,CAAC;IACrB,IAAA,oBAAU,EAAC,YAAY,CAAC;GACZ,gBAAgB,CAgD5B"}

package/src/lib/attachment/attachment.module.d.ts

@@ -0,0 +1,27 @@
+import { DynamicModule, InjectionToken, Provider } from '@nestjs/common';
+import { ModuleMetadata } from '@nestjs/common/interfaces';
+import { AttachmentStorage } from './attachment-storage.token';
+import { BPMRootAttachmentOptions } from './attachment-options';
+export interface AttachmentModuleOptions extends BPMRootAttachmentOptions {
+    readonly imports?: ModuleMetadata['imports'];
+    readonly storageProvider?: Provider<AttachmentStorage>;
+}
+export interface AttachmentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    /**
+     * Controller mount path used by the BPM attachment endpoints.
+     *
+     * Set at module wiring time because Nest reads the controller path metadata
+     * synchronously when the application starts. Async secrets cannot drive this
+     * value; only static URL routing decisions should set it.
+     *
+     * Defaults to `/attachments`.
+     */
+    readonly attachmentRoutePrefix?: string | null;
+    readonly inject?: readonly InjectionToken[];
+    readonly storageProvider?: Provider<AttachmentStorage>;
+    readonly useFactory: (...args: readonly unknown[]) => BPMRootAttachmentOptions | Promise<BPMRootAttachmentOptions>;
+}
+export declare class AttachmentModule {
+    static forRoot(options?: AttachmentModuleOptions): DynamicModule;
+    static forRootAsync(options: AttachmentModuleAsyncOptions): DynamicModule;
+}