@lssm/lib.files 0.0.0-canary-20251210171026 → 0.0.0-canary-20251212210835

package/README.md

@@ -162,7 +162,7 @@ const attachments = await attachmentService.list({
 This module integrates with:
 
 - `@lssm/lib.identity-rbac` - Access control
-- `@lssm/modules.audit-trail` - File operations audit
+- `@lssm/module.audit-trail` - File operations audit
 
 ## Schema Contribution
 

package/dist/docs/files.docblock.js

@@ -0,0 +1,51 @@
+import{registerDocBlocks as e}from"@lssm/lib.contracts/docs";e([{id:`docs.files.attachments`,title:`Files, Versions & Attachments`,summary:`Spec-first file management with storage adapters, versioning, presigned URLs, and polymorphic attachments for any entity.`,kind:`reference`,visibility:`public`,route:`/docs/files/attachments`,tags:[`files`,`attachments`,`storage`,`versions`],body:`## Capabilities
+
+- **Entities**: File, FileVersion, Attachment, UploadSession with retention, checksum, ACLs.
+- **Contracts**: upload/update/delete/list/get files; presigned upload/download; version create/list; attach/detach/list attachments.
+- **Storage**: pluggable adapters (Local, S3 placeholder + interface), in-memory for tests.
+- **Events**: file.uploaded/deleted, attachment.added/removed (see events export).
+
+## Usage
+
+1) Compose schema
+- Include \`filesSchemaContribution\` in your schema composition.
+
+2) Register contracts/events
+- Import contracts and events from \`@lssm/lib.files\` in your spec registry.
+
+3) Wire storage
+- Provide a \`StorageAdapter\` implementation (local/in-memory or S3 via custom impl).
+- Use \`createStorageAdapter\` with config to instantiate.
+
+4) Attach to domain entities
+- Use \`attachment.attach\` with \`entityType/entityId\` to link files to deals, orders, runs, etc.
+
+## Example
+
+\`\`\`ts
+import {
+  UploadFileContract,
+  AttachFileContract,
+  InMemoryStorageAdapter,
+} from '@lssm/lib.files';
+
+// storage
+const storage = new InMemoryStorageAdapter();
+
+// upload
+const file = await storage.upload({
+  path: 'org-1/reports/r1.pdf',
+  content: Buffer.from(pdfBytes),
+  mimeType: 'application/pdf',
+});
+
+// attach
+await AttachFileContract; // register in spec to enable attach flows
+\`\`\`,
+
+## Guardrails
+
+- Enforce size/MIME limits in your handlers; avoid storing PII in paths.
+- Keep \`orgId\` scoped for multi-tenant isolation; prefer presigned URLs for public delivery.
+- Persist checksums for integrity; emit audit + events for access/retention changes.
+`}]);

package/dist/docs/index.js

@@ -0,0 +1 @@
+import"./files.docblock.js";

package/dist/index.js

@@ -1 +1 @@
-import{AttachmentAttachedEvent as e,AttachmentDetachedEvent as t,FileDeletedEvent as n,FileEvents as r,FileUpdatedEvent as i,FileUploadedEvent as a,FileVersionCreatedEvent as o,UploadSessionCompletedEvent as s,UploadSessionStartedEvent as c}from"./events.js";import{AttachmentEntity as l,FileEntity as u,FileStatusEnum as d,FileVersionEntity as f,StorageProviderEnum as p,UploadSessionEntity as m,fileEntities as h,filesSchemaContribution as g}from"./entities/index.js";import{AttachFileContract as _,AttachmentModel as v,CreatePresignedUrlContract as y,CreateVersionContract as b,DeleteFileContract as x,DetachFileContract as S,FileModel as C,FileVersionModel as w,GetDownloadUrlContract as T,GetFileContract as E,GetVersionsContract as D,ListAttachmentsContract as O,ListFilesContract as k,PresignedUrlModel as A,UpdateFileContract as j,UploadFileContract as M}from"./contracts/index.js";import{InMemoryStorageAdapter as N,LocalStorageAdapter as P,S3StorageAdapter as F,createStorageAdapter as I}from"./storage/index.js";export{_ as AttachFileContract,e as AttachmentAttachedEvent,t as AttachmentDetachedEvent,l as AttachmentEntity,v as AttachmentModel,y as CreatePresignedUrlContract,b as CreateVersionContract,x as DeleteFileContract,S as DetachFileContract,n as FileDeletedEvent,u as FileEntity,r as FileEvents,C as FileModel,d as FileStatusEnum,i as FileUpdatedEvent,a as FileUploadedEvent,o as FileVersionCreatedEvent,f as FileVersionEntity,w as FileVersionModel,T as GetDownloadUrlContract,E as GetFileContract,D as GetVersionsContract,N as InMemoryStorageAdapter,O as ListAttachmentsContract,k as ListFilesContract,P as LocalStorageAdapter,A as PresignedUrlModel,F as S3StorageAdapter,p as StorageProviderEnum,j as UpdateFileContract,M as UploadFileContract,s as UploadSessionCompletedEvent,m as UploadSessionEntity,c as UploadSessionStartedEvent,I as createStorageAdapter,h as fileEntities,g as filesSchemaContribution};
+import{AttachmentAttachedEvent as e,AttachmentDetachedEvent as t,FileDeletedEvent as n,FileEvents as r,FileUpdatedEvent as i,FileUploadedEvent as a,FileVersionCreatedEvent as o,UploadSessionCompletedEvent as s,UploadSessionStartedEvent as c}from"./events.js";import{AttachmentEntity as l,FileEntity as u,FileStatusEnum as d,FileVersionEntity as f,StorageProviderEnum as p,UploadSessionEntity as m,fileEntities as h,filesSchemaContribution as g}from"./entities/index.js";import{AttachFileContract as _,AttachmentModel as v,CreatePresignedUrlContract as y,CreateVersionContract as b,DeleteFileContract as x,DetachFileContract as S,FileModel as C,FileVersionModel as w,GetDownloadUrlContract as T,GetFileContract as E,GetVersionsContract as D,ListAttachmentsContract as O,ListFilesContract as k,PresignedUrlModel as A,UpdateFileContract as j,UploadFileContract as M}from"./contracts/index.js";import{InMemoryStorageAdapter as N,LocalStorageAdapter as P,S3StorageAdapter as F,createStorageAdapter as I}from"./storage/index.js";import"./docs/index.js";export{_ as AttachFileContract,e as AttachmentAttachedEvent,t as AttachmentDetachedEvent,l as AttachmentEntity,v as AttachmentModel,y as CreatePresignedUrlContract,b as CreateVersionContract,x as DeleteFileContract,S as DetachFileContract,n as FileDeletedEvent,u as FileEntity,r as FileEvents,C as FileModel,d as FileStatusEnum,i as FileUpdatedEvent,a as FileUploadedEvent,o as FileVersionCreatedEvent,f as FileVersionEntity,w as FileVersionModel,T as GetDownloadUrlContract,E as GetFileContract,D as GetVersionsContract,N as InMemoryStorageAdapter,O as ListAttachmentsContract,k as ListFilesContract,P as LocalStorageAdapter,A as PresignedUrlModel,F as S3StorageAdapter,p as StorageProviderEnum,j as UpdateFileContract,M as UploadFileContract,s as UploadSessionCompletedEvent,m as UploadSessionEntity,c as UploadSessionStartedEvent,I as createStorageAdapter,h as fileEntities,g as filesSchemaContribution};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.files",
-  "version": "0.0.0-canary-20251210171026",
+  "version": "0.0.0-canary-20251212210835",
   "description": "Files, documents and attachments module for ContractSpec applications",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -29,6 +29,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./contracts": "./src/contracts/index.ts",
+    "./docs": "./src/docs/index.ts",
+    "./docs/files.docblock": "./src/docs/files.docblock.ts",
     "./entities": "./src/entities/index.ts",
     "./events": "./src/events.ts",
     "./storage": "./src/storage/index.ts",
@@ -44,6 +46,8 @@
     "exports": {
       ".": "./dist/index.js",
       "./contracts": "./dist/contracts/index.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/files.docblock": "./dist/docs/files.docblock.js",
       "./entities": "./dist/entities/index.js",
       "./events": "./dist/events.js",
       "./storage": "./dist/storage/index.js",