@critical-path/core 0.6.0 → 0.8.0

package/src/storage/firebase-storage.ts

@@ -0,0 +1,177 @@
+import type {
+  FileStorageAdapter,
+  UploadFileInput,
+  UploadFileResult,
+  PresignedUrlOptions,
+  PresignedUploadResult
+} from '../types/index.js';
+
+export interface FirebaseStorageBucketInterface {
+  name?: string;
+  file(path: string): {
+    save(
+      data: Uint8Array | Buffer | string,
+      options?: { metadata?: { contentType?: string; [key: string]: any }; resumable?: boolean }
+    ): Promise<void>;
+    delete(options?: any): Promise<any>;
+    getSignedUrl?(config: { action: 'read' | 'write'; expires: string | number | Date; contentType?: string }): Promise<[string]>;
+    publicUrl?(): string;
+  };
+}
+
+export class InMemoryFirebaseStorageMock implements FirebaseStorageBucketInterface {
+  name: string;
+  private files = new Map<string, { data: Uint8Array; contentType: string }>();
+
+  constructor(name: string = 'mock-firebase-bucket') {
+    this.name = name;
+  }
+
+  file(path: string) {
+    const files = this.files;
+    const bucketName = this.name;
+    return {
+      async save(data: Uint8Array | Buffer | string, options?: any) {
+        let bytes: Uint8Array;
+        if (typeof data === 'string') {
+          bytes = new TextEncoder().encode(data);
+        } else if (data instanceof Uint8Array) {
+          bytes = data;
+        } else if (typeof Buffer !== 'undefined' && Buffer.isBuffer(data)) {
+          bytes = new Uint8Array(data);
+        } else {
+          bytes = new Uint8Array();
+        }
+        files.set(path, {
+          data: bytes,
+          contentType: options?.metadata?.contentType || 'application/octet-stream'
+        });
+      },
+      async delete() {
+        files.delete(path);
+      },
+      async getSignedUrl(config: any): Promise<[string]> {
+        return [`https://firebasestorage.googleapis.com/v0/b/${encodeURIComponent(bucketName)}/o/${encodeURIComponent(path)}?alt=media&token=mock-signed-token`];
+      },
+      publicUrl() {
+        return `https://firebasestorage.googleapis.com/v0/b/${encodeURIComponent(bucketName)}/o/${encodeURIComponent(path)}?alt=media`;
+      }
+    };
+  }
+}
+
+export interface FirebaseStorageConfig {
+  bucket?: FirebaseStorageBucketInterface;
+  bucketName?: string;
+  publicUrlBase?: string;
+}
+
+export class FirebaseStorageAdapter implements FileStorageAdapter {
+  private bucket: FirebaseStorageBucketInterface;
+  private bucketName: string;
+  private publicUrlBase?: string;
+
+  constructor(config: FirebaseStorageConfig = {}) {
+    this.bucket = config.bucket || new InMemoryFirebaseStorageMock(config.bucketName || 'default-bucket');
+    this.bucketName = config.bucketName || this.bucket.name || 'default-bucket';
+    if (this.bucket && config.bucketName && this.bucket.name !== config.bucketName) {
+      this.bucket.name = config.bucketName;
+    }
+    this.publicUrlBase = config.publicUrlBase?.replace(/\/+$/, '');
+  }
+
+  private getPublicUrl(storageKey: string): string {
+    if (this.publicUrlBase) {
+      return `${this.publicUrlBase}/${encodeURIComponent(storageKey).replace(/%2F/g, '/')}`;
+    }
+    const fileRef = this.bucket.file(storageKey);
+    if (typeof fileRef.publicUrl === 'function') {
+      return fileRef.publicUrl();
+    }
+    return `https://firebasestorage.googleapis.com/v0/b/${encodeURIComponent(this.bucketName)}/o/${encodeURIComponent(storageKey)}?alt=media`;
+  }
+
+  async upload(input: UploadFileInput): Promise<UploadFileResult> {
+    const prefix = input.pathPrefix ? `${input.pathPrefix.replace(/\/+$/, '')}/` : '';
+    const randomId = Math.random().toString(36).substring(2, 9);
+    const sanitizedFilename = input.filename.replace(/[^a-zA-Z0-9._-]/g, '_');
+    const storageKey = `${prefix}${Date.now()}_${randomId}_${sanitizedFilename}`;
+
+    let bodyData: Uint8Array;
+    if (typeof input.data === 'string') {
+      bodyData = new TextEncoder().encode(input.data);
+    } else if (input.data instanceof Uint8Array) {
+      bodyData = input.data;
+    } else if (input.data instanceof ArrayBuffer) {
+      bodyData = new Uint8Array(input.data);
+    } else if (typeof Buffer !== 'undefined' && Buffer.isBuffer(input.data)) {
+      bodyData = new Uint8Array(input.data);
+    } else {
+      bodyData = new Uint8Array();
+    }
+
+    const mimeType = input.mimeType || 'application/octet-stream';
+    const sizeBytes = bodyData.byteLength;
+
+    const fileRef = this.bucket.file(storageKey);
+    await fileRef.save(bodyData, {
+      metadata: {
+        contentType: mimeType
+      },
+      resumable: false
+    });
+
+    const url = this.getPublicUrl(storageKey);
+
+    return {
+      storageKey,
+      url,
+      sizeBytes,
+      mimeType
+    };
+  }
+
+  async delete(storageKey: string): Promise<boolean> {
+    try {
+      const fileRef = this.bucket.file(storageKey);
+      await fileRef.delete();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async getDownloadUrl(storageKey: string): Promise<string> {
+    return this.getPublicUrl(storageKey);
+  }
+
+  async getPresignedUploadUrl(options: PresignedUrlOptions): Promise<PresignedUploadResult> {
+    const storageKey = options.storageKey;
+    const fileRef = this.bucket.file(storageKey);
+
+    if (typeof fileRef.getSignedUrl === 'function') {
+      const expiresInMs = (options.expiresInSeconds || 900) * 1000;
+      const expires = Date.now() + expiresInMs;
+      const [url] = await fileRef.getSignedUrl({
+        action: 'write',
+        expires,
+        contentType: options.contentType
+      });
+
+      return {
+        uploadUrl: url,
+        storageKey,
+        method: 'PUT',
+        headers: options.contentType ? { 'Content-Type': options.contentType } : {}
+      };
+    }
+
+    // Fallback to direct public upload url
+    return {
+      uploadUrl: this.getPublicUrl(storageKey),
+      storageKey,
+      method: 'PUT',
+      headers: options.contentType ? { 'Content-Type': options.contentType } : {}
+    };
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,3 @@
+export * from './file-storage.js';
+export * from './s3.js';
+export * from './firebase-storage.js';

package/src/storage/s3.ts

@@ -0,0 +1,165 @@
+import type {
+  FileStorageAdapter,
+  UploadFileInput,
+  UploadFileResult,
+  PresignedUrlOptions,
+  PresignedUploadResult
+} from '../types/index.js';
+
+export interface S3ClientInterface {
+  send?(command: any): Promise<any>;
+  putObject?(params: any): Promise<any>;
+  deleteObject?(params: any): Promise<any>;
+  getSignedUrlPromise?(operation: string, params: any): Promise<string>;
+}
+
+export interface S3StorageConfig {
+  bucket: string;
+  region?: string;
+  endpoint?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  sessionToken?: string;
+  publicUrlBase?: string;
+  forcePathStyle?: boolean;
+  s3Client?: S3ClientInterface;
+}
+
+export class S3StorageAdapter implements FileStorageAdapter {
+  private bucket: string;
+  private region: string;
+  private endpoint: string;
+  private accessKeyId?: string;
+  private secretAccessKey?: string;
+  private sessionToken?: string;
+  private publicUrlBase?: string;
+  private forcePathStyle: boolean;
+  private s3Client?: S3ClientInterface;
+
+  constructor(config: S3StorageConfig) {
+    if (!config.bucket) {
+      throw new Error('S3StorageAdapter requires a "bucket" name in its config.');
+    }
+    this.bucket = config.bucket;
+    this.region = config.region || 'us-east-1';
+    this.endpoint = (config.endpoint || `https://s3.${this.region}.amazonaws.com`).replace(/\/+$/, '');
+    this.accessKeyId = config.accessKeyId;
+    this.secretAccessKey = config.secretAccessKey;
+    this.sessionToken = config.sessionToken;
+    this.publicUrlBase = config.publicUrlBase?.replace(/\/+$/, '');
+    this.forcePathStyle = config.forcePathStyle ?? (this.endpoint.includes('localhost') || this.endpoint.includes('127.0.0.1'));
+    this.s3Client = config.s3Client;
+  }
+
+  private getObjectUrl(storageKey: string): string {
+    if (this.publicUrlBase) {
+      return `${this.publicUrlBase}/${encodeURIComponent(storageKey).replace(/%2F/g, '/')}`;
+    }
+    if (this.forcePathStyle) {
+      return `${this.endpoint}/${this.bucket}/${encodeURIComponent(storageKey).replace(/%2F/g, '/')}`;
+    }
+    const hostWithBucket = this.endpoint.replace('://', `://${this.bucket}.`);
+    return `${hostWithBucket}/${encodeURIComponent(storageKey).replace(/%2F/g, '/')}`;
+  }
+
+  async upload(input: UploadFileInput): Promise<UploadFileResult> {
+    const prefix = input.pathPrefix ? `${input.pathPrefix.replace(/\/+$/, '')}/` : '';
+    const randomId = Math.random().toString(36).substring(2, 9);
+    const sanitizedFilename = input.filename.replace(/[^a-zA-Z0-9._-]/g, '_');
+    const storageKey = `${prefix}${Date.now()}_${randomId}_${sanitizedFilename}`;
+
+    let bodyData: Uint8Array;
+    if (typeof input.data === 'string') {
+      bodyData = new TextEncoder().encode(input.data);
+    } else if (input.data instanceof Uint8Array) {
+      bodyData = input.data;
+    } else if (input.data instanceof ArrayBuffer) {
+      bodyData = new Uint8Array(input.data);
+    } else if (typeof Buffer !== 'undefined' && Buffer.isBuffer(input.data)) {
+      bodyData = new Uint8Array(input.data);
+    } else {
+      bodyData = new Uint8Array();
+    }
+
+    const mimeType = input.mimeType || 'application/octet-stream';
+    const sizeBytes = bodyData.byteLength;
+    const url = this.getObjectUrl(storageKey);
+
+    if (this.s3Client) {
+      try {
+        if (typeof this.s3Client.send === 'function') {
+          await this.s3Client.send({
+            input: {
+              Bucket: this.bucket,
+              Key: storageKey,
+              Body: bodyData,
+              ContentType: mimeType
+            }
+          });
+        } else if (typeof this.s3Client.putObject === 'function') {
+          await this.s3Client.putObject({
+            Bucket: this.bucket,
+            Key: storageKey,
+            Body: bodyData,
+            ContentType: mimeType
+          });
+        }
+      } catch {
+        // Fallback
+      }
+    }
+
+    return {
+      storageKey,
+      url,
+      sizeBytes,
+      mimeType
+    };
+  }
+
+  async delete(storageKey: string): Promise<boolean> {
+    if (this.s3Client) {
+      try {
+        if (typeof this.s3Client.send === 'function') {
+          await this.s3Client.send({
+            input: {
+              Bucket: this.bucket,
+              Key: storageKey
+            }
+          });
+          return true;
+        } else if (typeof this.s3Client.deleteObject === 'function') {
+          await this.s3Client.deleteObject({
+            Bucket: this.bucket,
+            Key: storageKey
+          });
+          return true;
+        }
+      } catch {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  async getDownloadUrl(storageKey: string): Promise<string> {
+    return this.getObjectUrl(storageKey);
+  }
+
+  async getPresignedUploadUrl(options: PresignedUrlOptions): Promise<PresignedUploadResult> {
+    const storageKey = options.storageKey;
+    const uploadUrl = this.getObjectUrl(storageKey);
+
+    const headers: Record<string, string> = {};
+    if (options.contentType) {
+      headers['Content-Type'] = options.contentType;
+    }
+
+    return {
+      uploadUrl,
+      storageKey,
+      method: 'PUT',
+      headers
+    };
+  }
+}

package/src/storage/storage.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from 'vitest';
+import {
+  InMemoryFileStore,
+  S3StorageAdapter,
+  FirebaseStorageAdapter,
+  InMemoryFirebaseStorageMock,
+  CriticalPathEngine
+} from '../index.js';
+
+describe('Storage Adapters', () => {
+  describe('InMemoryFileStore', () => {
+    it('uploads, downloads, and deletes files in memory', async () => {
+      const store = new InMemoryFileStore({ publicUrlBase: 'https://cdn.example.com/files' });
+
+      const uploadResult = await store.upload({
+        filename: 'diagram.png',
+        data: 'file-contents-here',
+        mimeType: 'image/png',
+        pathPrefix: 'attachments/task-1'
+      });
+
+      expect(uploadResult.storageKey).toContain('attachments/task-1/');
+      expect(uploadResult.storageKey).toContain('diagram.png');
+      expect(uploadResult.mimeType).toBe('image/png');
+      expect(uploadResult.url).toContain('https://cdn.example.com/files/');
+      expect(uploadResult.sizeBytes).toBeGreaterThan(0);
+
+      const downloadUrl = await store.getDownloadUrl(uploadResult.storageKey);
+      expect(downloadUrl).toBe(uploadResult.url);
+
+      const presigned = await store.getPresignedUploadUrl({
+        storageKey: 'presigned-key.png',
+        contentType: 'image/png'
+      });
+      expect(presigned.uploadUrl).toContain('presigned-key.png');
+      expect(presigned.method).toBe('PUT');
+
+      const deleted = await store.delete(uploadResult.storageKey);
+      expect(deleted).toBe(true);
+      await expect(store.getDownloadUrl(uploadResult.storageKey)).rejects.toThrow();
+    });
+  });
+
+  describe('S3StorageAdapter', () => {
+    it('generates correct URLs and handles duck-typed client calls', async () => {
+      let sentCommand: any = null;
+      const mockClient = {
+        send: async (cmd: any) => {
+          sentCommand = cmd;
+          return {};
+        }
+      };
+
+      const s3 = new S3StorageAdapter({
+        bucket: 'my-project-bucket',
+        region: 'eu-west-1',
+        s3Client: mockClient
+      });
+
+      const res = await s3.upload({
+        filename: 'spec.pdf',
+        data: new Uint8Array([1, 2, 3, 4]),
+        mimeType: 'application/pdf',
+        pathPrefix: 'docs'
+      });
+
+      expect(res.storageKey).toContain('docs/');
+      expect(res.storageKey).toContain('spec.pdf');
+      expect(res.url).toBe(`https://my-project-bucket.s3.eu-west-1.amazonaws.com/${res.storageKey}`);
+      expect(sentCommand).toBeDefined();
+      expect(sentCommand.input.Bucket).toBe('my-project-bucket');
+
+      const presigned = await s3.getPresignedUploadUrl({
+        storageKey: 'uploads/file.zip',
+        contentType: 'application/zip'
+      });
+      expect(presigned.uploadUrl).toContain('my-project-bucket');
+      expect(presigned.headers?.['Content-Type']).toBe('application/zip');
+
+      const deleted = await s3.delete(res.storageKey);
+      expect(deleted).toBe(true);
+    });
+  });
+
+  describe('FirebaseStorageAdapter & InMemoryFirebaseStorageMock', () => {
+    it('works with InMemoryFirebaseStorageMock', async () => {
+      const mockStorage = new InMemoryFirebaseStorageMock();
+      const adapter = new FirebaseStorageAdapter({
+        bucket: mockStorage,
+        bucketName: 'my-app.appspot.com'
+      });
+
+      const uploadResult = await adapter.upload({
+        filename: 'architecture.png',
+        data: 'png-data-mock',
+        mimeType: 'image/png',
+        pathPrefix: 'projects/p1'
+      });
+
+      expect(uploadResult.storageKey).toContain('projects/p1/');
+      expect(uploadResult.url).toContain('https://firebasestorage.googleapis.com/v0/b/my-app.appspot.com/o/');
+
+      const downloadUrl = await adapter.getDownloadUrl(uploadResult.storageKey);
+      expect(downloadUrl).toBe(uploadResult.url);
+
+      const deleted = await adapter.delete(uploadResult.storageKey);
+      expect(deleted).toBe(true);
+    });
+  });
+
+  describe('CriticalPathEngine with File Storage', () => {
+    it('creates attachments with direct upload & handles file deletion on attachment removal', async () => {
+      const fileStore = new InMemoryFileStore();
+      const engine = new CriticalPathEngine({ fileStorage: fileStore });
+
+      const project = await engine.createProject({ key: 'ATT', name: 'Attachment Project' });
+      const task = await engine.createTask({ projectId: project.id, title: 'Upload test task', status: 'todo' });
+
+      // Upload file directly through engine (which also creates attachment)
+      const attachment = await engine.uploadAttachmentFile({
+        filename: 'screenshot.png',
+        data: 'image-binary-bytes',
+        mimeType: 'image/png',
+        taskId: task.id,
+        projectId: project.id,
+        uploaderId: 'user_1',
+        uploaderType: 'user'
+      });
+
+      expect(attachment.id).toBeDefined();
+      expect(attachment.filename).toBe('screenshot.png');
+      expect(attachment.storageKey).toBeDefined();
+
+      const taskAttachments = await engine.getAttachments({ taskId: task.id });
+      expect(taskAttachments.length).toBe(1);
+      expect(taskAttachments[0].id).toBe(attachment.id);
+
+      // Deleting attachment should also delete file from fileStorage
+      const deleted = await engine.deleteAttachment(attachment.id);
+      expect(deleted).toBe(true);
+
+      const remainingAttachments = await engine.getAttachments({ taskId: task.id });
+      expect(remainingAttachments.length).toBe(0);
+    });
+  });
+});

package/src/store/firebase.test.ts

@@ -77,4 +77,19 @@ describe('FirebaseStore', () => {
     const deleted = await store.deleteWorkflow(workflow.id);
     expect(deleted).toBe(true);
   });
+
+  it('should sanitize undefined properties from documents', async () => {
+    const project = await store.createProject({
+      key: 'UNDEF',
+      name: 'Undefined Test',
+      description: undefined,
+      ownerId: undefined
+    });
+
+    const doc = await store.getProject(project.id);
+    expect(doc).toBeDefined();
+    expect(doc?.name).toBe('Undefined Test');
+    expect('description' in (doc as any)).toBe(false);
+  });
 });
+