@contractspec/lib.files 1.44.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+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

@@ -0,0 +1,197 @@
+# @contractspec/lib.files
+
+Website: https://contractspec.io/
+
+
+Files, documents, and attachments module for ContractSpec applications.
+
+## Overview
+
+This module provides a reusable file management system that can be used across all ContractSpec applications. It supports:
+
+- **File Storage**: Upload and manage files with multiple storage backends
+- **Document Versioning**: Track file versions over time
+- **Polymorphic Attachments**: Attach files to any entity type
+- **Access Control**: Control who can upload, view, and delete files
+- **Presigned URLs**: Direct uploads to storage backends
+
+## Entities
+
+### File
+
+Core file record.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Unique identifier |
+| name | string | Original file name |
+| mimeType | string | MIME type |
+| size | int | File size in bytes |
+| storageProvider | enum | Storage backend (local, s3, etc.) |
+| storagePath | string | Path in storage backend |
+| checksum | string | File checksum (SHA-256) |
+| ownerId | string | User who uploaded |
+| orgId | string | Organization scope |
+| isPublic | boolean | Whether file is publicly accessible |
+| metadata | json | Additional metadata |
+| createdAt | datetime | Upload timestamp |
+| updatedAt | datetime | Last update timestamp |
+
+### FileVersion
+
+Version history for documents.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Unique identifier |
+| fileId | string | Parent file |
+| version | int | Version number |
+| size | int | Version size in bytes |
+| storagePath | string | Path in storage |
+| checksum | string | Version checksum |
+| createdBy | string | User who created version |
+| createdAt | datetime | Version timestamp |
+| comment | string | Version comment |
+
+### Attachment
+
+Polymorphic link between files and entities.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | string | Unique identifier |
+| fileId | string | Attached file |
+| entityType | string | Target entity type |
+| entityId | string | Target entity ID |
+| attachmentType | string | Type of attachment (document, image, etc.) |
+| order | int | Display order |
+| metadata | json | Attachment-specific metadata |
+| createdAt | datetime | Attachment timestamp |
+
+## Contracts
+
+### Commands
+
+- `file.upload` - Upload a new file
+- `file.update` - Update file metadata
+- `file.delete` - Delete a file
+- `file.createVersion` - Create a new version
+- `attachment.attach` - Attach file to entity
+- `attachment.detach` - Remove attachment
+- `presignedUrl.create` - Get presigned upload URL
+
+### Queries
+
+- `file.get` - Get file by ID
+- `file.list` - List files with filtering
+- `file.getVersions` - Get file version history
+- `file.download` - Get download URL
+- `attachment.list` - List attachments for entity
+
+## Events
+
+- `file.uploaded` - File was uploaded
+- `file.updated` - File metadata changed
+- `file.deleted` - File was deleted
+- `file.version_created` - New version created
+- `attachment.attached` - File attached to entity
+- `attachment.detached` - File detached from entity
+
+## Storage Adapters
+
+### LocalStorageAdapter
+
+For development and testing. Stores files on the local filesystem.
+
+```typescript
+import { LocalStorageAdapter } from '@contractspec/lib.files/storage';
+
+const storage = new LocalStorageAdapter({
+  basePath: './uploads',
+  baseUrl: 'http://localhost:3000/uploads',
+});
+```
+
+### S3StorageAdapter
+
+For production use with AWS S3 or compatible services.
+
+```typescript
+import { S3StorageAdapter } from '@contractspec/lib.files/storage';
+
+const storage = new S3StorageAdapter({
+  bucket: 'my-bucket',
+  region: 'us-east-1',
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+});
+```
+
+## Usage
+
+```typescript
+import { 
+  FileEntity, 
+  UploadFileContract,
+  LocalStorageAdapter 
+} from '@contractspec/lib.files';
+
+// Upload a file
+const file = await fileService.upload({
+  name: 'document.pdf',
+  mimeType: 'application/pdf',
+  size: 1024,
+  content: buffer,
+  orgId: 'org-123',
+});
+
+// Attach to an entity
+await attachmentService.attach({
+  fileId: file.id,
+  entityType: 'deal',
+  entityId: 'deal-456',
+  attachmentType: 'contract',
+});
+
+// List attachments
+const attachments = await attachmentService.list({
+  entityType: 'deal',
+  entityId: 'deal-456',
+});
+```
+
+## Integration
+
+This module integrates with:
+
+- `@contractspec/lib.identity-rbac` - Access control
+- `@contractspec/module.audit-trail` - File operations audit
+
+## Schema Contribution
+
+```typescript
+import { filesSchemaContribution } from '@contractspec/lib.files';
+
+export const schemaComposition = {
+  modules: [
+    filesSchemaContribution,
+    // ... other modules
+  ],
+};
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+