@hammr/cdn 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,357 @@
+/**
+ * Type definitions for CDN storage system
+ */
+/**
+ * Metadata for stored artifacts
+ */
+interface ArtifactMetadata {
+    /**
+     * Content-Type header (e.g., 'image/png', 'application/json')
+     */
+    contentType?: string;
+    /**
+     * Original filename (if provided)
+     */
+    filename?: string;
+    /**
+     * File size in bytes
+     */
+    size?: number;
+    /**
+     * Upload timestamp (Unix milliseconds)
+     */
+    uploadedAt?: number;
+    /**
+     * Custom metadata fields
+     */
+    customMetadata?: Record<string, string>;
+}
+/**
+ * Stored artifact with content and metadata
+ */
+interface StoredArtifact {
+    /**
+     * Content-addressable hash (SHA256)
+     */
+    hash: string;
+    /**
+     * Artifact content (raw bytes)
+     */
+    body: ArrayBuffer | ReadableStream | Uint8Array;
+    /**
+     * Metadata about the artifact
+     */
+    metadata: ArtifactMetadata;
+}
+/**
+ * Result from uploading an artifact
+ */
+interface UploadResult {
+    /**
+     * Content-addressable hash
+     */
+    hash: string;
+    /**
+     * Public URL to access the artifact
+     */
+    url: string;
+    /**
+     * Whether this was a new upload (true) or already existed (false)
+     */
+    created: boolean;
+    /**
+     * Artifact metadata
+     */
+    metadata: ArtifactMetadata;
+}
+/**
+ * Storage adapter interface
+ *
+ * Implement this to support different storage backends (R2, S3, etc.)
+ */
+interface StorageAdapter {
+    /**
+     * Store artifact content with hash as key
+     *
+     * @param hash - Content-addressable hash (SHA256)
+     * @param content - Raw bytes to store
+     * @param metadata - Optional metadata
+     */
+    put(hash: string, content: ArrayBuffer | Uint8Array, metadata?: ArtifactMetadata): Promise<void>;
+    /**
+     * Retrieve artifact by hash
+     *
+     * @param hash - Content-addressable hash
+     * @returns Artifact or null if not found
+     */
+    get(hash: string): Promise<StoredArtifact | null>;
+    /**
+     * Delete artifact by hash
+     *
+     * @param hash - Content-addressable hash
+     * @returns true if deleted, false if not found
+     */
+    delete(hash: string): Promise<boolean>;
+    /**
+     * Check if artifact exists
+     *
+     * @param hash - Content-addressable hash
+     * @returns true if exists, false otherwise
+     */
+    exists(hash: string): Promise<boolean>;
+    /**
+     * List all artifact hashes (optional, for admin/debugging)
+     *
+     * @param options - List options (limit, cursor, etc.)
+     * @returns Array of hashes
+     */
+    list?(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<string[]>;
+}
+/**
+ * Options for CDN
+ */
+interface CDNOptions {
+    /**
+     * Storage adapter (R2, S3, Memory, etc.)
+     */
+    storage: StorageAdapter;
+    /**
+     * Base URL for generating artifact URLs
+     * @example 'https://cdn.example.com'
+     */
+    baseUrl: string;
+    /**
+     * Cache-Control max-age in seconds
+     * @default 31536000 (1 year)
+     */
+    cacheMaxAge?: number;
+    /**
+     * Default content type if not detected
+     * @default 'application/octet-stream'
+     */
+    defaultContentType?: string;
+    /**
+     * Enable CORS headers
+     * @default true
+     */
+    cors?: boolean;
+}
+/**
+ * Content type map for common extensions
+ */
+declare const CONTENT_TYPES: Record<string, string>;
+/**
+ * Detect content type from filename extension
+ */
+declare function detectContentType(filename: string, defaultType?: string): string;
+
+/**
+ * CDN - Content-Addressable Storage System
+ *
+ * Features:
+ * - Content-addressable (SHA256 hashing via @sygnl/normalizer)
+ * - Storage abstraction (R2, S3, Memory, etc.)
+ * - Automatic content-type detection
+ * - Immutable artifacts (hash-based URLs)
+ * - Cache-friendly headers
+ */
+
+declare class CDN {
+    private storage;
+    private baseUrl;
+    private cacheMaxAge;
+    private defaultContentType;
+    private cors;
+    constructor(options: CDNOptions);
+    /**
+     * Upload an artifact and get content-addressable URL
+     *
+     * @param content - Raw bytes to upload
+     * @param metadata - Optional metadata (filename, contentType, etc.)
+     * @returns Upload result with hash and URL
+     *
+     * @example
+     * ```typescript
+     * const result = await cdn.put(imageBytes, {
+     *   filename: 'logo.png',
+     *   contentType: 'image/png'
+     * });
+     *
+     * console.log(result.url); // https://cdn.example.com/a/5e88489...
+     * ```
+     */
+    put(content: ArrayBuffer | Uint8Array, metadata?: Partial<ArtifactMetadata>): Promise<UploadResult>;
+    /**
+     * Retrieve an artifact by hash
+     *
+     * @param hash - Content-addressable hash
+     * @returns Artifact or null if not found
+     *
+     * @example
+     * ```typescript
+     * const artifact = await cdn.get('5e884898...');
+     * if (artifact) {
+     *   console.log(artifact.metadata.contentType);
+     * }
+     * ```
+     */
+    get(hash: string): Promise<StoredArtifact | null>;
+    /**
+     * Delete an artifact by hash
+     *
+     * @param hash - Content-addressable hash
+     * @returns true if deleted, false if not found
+     *
+     * @example
+     * ```typescript
+     * const deleted = await cdn.delete('5e884898...');
+     * ```
+     */
+    delete(hash: string): Promise<boolean>;
+    /**
+     * Check if artifact exists
+     *
+     * @param hash - Content-addressable hash
+     * @returns true if exists
+     */
+    exists(hash: string): Promise<boolean>;
+    /**
+     * List all artifacts (if supported by storage adapter)
+     *
+     * @param options - List options
+     * @returns Array of hashes
+     */
+    list(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<string[]>;
+    /**
+     * Handle HTTP request (for Cloudflare Workers, Express, etc.)
+     *
+     * Routes:
+     * - PUT /artifact - Upload artifact
+     * - GET /a/:hash(.ext) - Retrieve artifact
+     * - DELETE /a/:hash - Delete artifact
+     *
+     * @param request - HTTP request
+     * @returns HTTP response
+     *
+     * @example
+     * ```typescript
+     * export default {
+     *   async fetch(request, env) {
+     *     const cdn = new CDN({
+     *       storage: new R2Storage(env.ARTIFACTS),
+     *       baseUrl: 'https://cdn.example.com'
+     *     });
+     *     return cdn.handleRequest(request);
+     *   }
+     * }
+     * ```
+     */
+    handleRequest(request: Request): Promise<Response>;
+    /**
+     * Get CORS headers if enabled
+     */
+    private getCORSHeaders;
+}
+
+/**
+ * In-memory storage adapter
+ *
+ * Useful for:
+ * - Testing
+ * - Development
+ * - Temporary caching
+ *
+ * NOT for production (data lost on restart)
+ */
+
+declare class MemoryStorage implements StorageAdapter {
+    private storage;
+    put(hash: string, content: ArrayBuffer | Uint8Array, metadata?: ArtifactMetadata): Promise<void>;
+    get(hash: string): Promise<StoredArtifact | null>;
+    delete(hash: string): Promise<boolean>;
+    exists(hash: string): Promise<boolean>;
+    list(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<string[]>;
+    /**
+     * Clear all stored artifacts (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Get storage size (number of artifacts)
+     */
+    size(): number;
+}
+
+/**
+ * Cloudflare R2 storage adapter
+ *
+ * Uses Cloudflare R2 for artifact storage.
+ *
+ * Usage:
+ * ```typescript
+ * const storage = new R2Storage(env.ARTIFACTS);
+ * ```
+ */
+
+/**
+ * Minimal R2 bucket interface
+ * (matches Cloudflare Workers R2Bucket type)
+ */
+interface R2Bucket {
+    put(key: string, value: ArrayBuffer | Uint8Array | ReadableStream, options?: {
+        httpMetadata?: {
+            contentType?: string;
+        };
+        customMetadata?: Record<string, string>;
+    }): Promise<any>;
+    get(key: string): Promise<{
+        body?: ReadableStream | ArrayBuffer;
+        httpMetadata?: {
+            contentType?: string;
+        };
+        customMetadata?: Record<string, string>;
+        size?: number;
+        uploaded?: Date;
+    } | null>;
+    delete(key: string): Promise<void>;
+    head(key: string): Promise<{
+        httpMetadata?: {
+            contentType?: string;
+        };
+        customMetadata?: Record<string, string>;
+        size?: number;
+        uploaded?: Date;
+    } | null>;
+    list?(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        objects: Array<{
+            key: string;
+        }>;
+        truncated: boolean;
+        cursor?: string;
+    }>;
+}
+declare class R2Storage implements StorageAdapter {
+    private bucket;
+    constructor(bucket: R2Bucket);
+    put(hash: string, content: ArrayBuffer | Uint8Array, metadata?: ArtifactMetadata): Promise<void>;
+    get(hash: string): Promise<StoredArtifact | null>;
+    delete(hash: string): Promise<boolean>;
+    exists(hash: string): Promise<boolean>;
+    list(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<string[]>;
+}
+
+export { type ArtifactMetadata, CDN, type CDNOptions, CONTENT_TYPES, MemoryStorage, type R2Bucket, R2Storage, type StorageAdapter, type StoredArtifact, type UploadResult, detectContentType };

package/dist/index.d.ts

@@ -0,0 +1,357 @@
+/**
+ * Type definitions for CDN storage system
+ */
+/**
+ * Metadata for stored artifacts
+ */
+interface ArtifactMetadata {
+    /**
+     * Content-Type header (e.g., 'image/png', 'application/json')
+     */
+    contentType?: string;
+    /**
+     * Original filename (if provided)
+     */
+    filename?: string;
+    /**
+     * File size in bytes
+     */
+    size?: number;
+    /**
+     * Upload timestamp (Unix milliseconds)
+     */
+    uploadedAt?: number;
+    /**
+     * Custom metadata fields
+     */
+    customMetadata?: Record<string, string>;
+}
+/**
+ * Stored artifact with content and metadata
+ */
+interface StoredArtifact {
+    /**
+     * Content-addressable hash (SHA256)
+     */
+    hash: string;
+    /**
+     * Artifact content (raw bytes)
+     */
+    body: ArrayBuffer | ReadableStream | Uint8Array;
+    /**
+     * Metadata about the artifact
+     */
+    metadata: ArtifactMetadata;
+}
+/**
+ * Result from uploading an artifact
+ */
+interface UploadResult {
+    /**
+     * Content-addressable hash
+     */
+    hash: string;
+    /**
+     * Public URL to access the artifact
+     */
+    url: string;
+    /**
+     * Whether this was a new upload (true) or already existed (false)
+     */
+    created: boolean;
+    /**
+     * Artifact metadata
+     */
+    metadata: ArtifactMetadata;
+}
+/**
+ * Storage adapter interface
+ *
+ * Implement this to support different storage backends (R2, S3, etc.)
+ */
+interface StorageAdapter {
+    /**
+     * Store artifact content with hash as key
+     *
+     * @param hash - Content-addressable hash (SHA256)
+     * @param content - Raw bytes to store
+     * @param metadata - Optional metadata
+     */
+    put(hash: string, content: ArrayBuffer | Uint8Array, metadata?: ArtifactMetadata): Promise<void>;
+    /**
+     * Retrieve artifact by hash
+     *
+     * @param hash - Content-addressable hash
+     * @returns Artifact or null if not found
+     */
+    get(hash: string): Promise<StoredArtifact | null>;
+    /**
+     * Delete artifact by hash
+     *
+     * @param hash - Content-addressable hash
+     * @returns true if deleted, false if not found
+     */
+    delete(hash: string): Promise<boolean>;
+    /**
+     * Check if artifact exists
+     *
+     * @param hash - Content-addressable hash
+     * @returns true if exists, false otherwise
+     */
+    exists(hash: string): Promise<boolean>;
+    /**
+     * List all artifact hashes (optional, for admin/debugging)
+     *
+     * @param options - List options (limit, cursor, etc.)
+     * @returns Array of hashes
+     */
+    list?(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<string[]>;
+}
+/**
+ * Options for CDN
+ */
+interface CDNOptions {
+    /**
+     * Storage adapter (R2, S3, Memory, etc.)
+     */
+    storage: StorageAdapter;
+    /**
+     * Base URL for generating artifact URLs
+     * @example 'https://cdn.example.com'
+     */
+    baseUrl: string;
+    /**
+     * Cache-Control max-age in seconds
+     * @default 31536000 (1 year)
+     */
+    cacheMaxAge?: number;
+    /**
+     * Default content type if not detected
+     * @default 'application/octet-stream'
+     */
+    defaultContentType?: string;
+    /**
+     * Enable CORS headers
+     * @default true
+     */
+    cors?: boolean;
+}
+/**
+ * Content type map for common extensions
+ */
+declare const CONTENT_TYPES: Record<string, string>;
+/**
+ * Detect content type from filename extension
+ */
+declare function detectContentType(filename: string, defaultType?: string): string;
+
+/**
+ * CDN - Content-Addressable Storage System
+ *
+ * Features:
+ * - Content-addressable (SHA256 hashing via @sygnl/normalizer)
+ * - Storage abstraction (R2, S3, Memory, etc.)
+ * - Automatic content-type detection
+ * - Immutable artifacts (hash-based URLs)
+ * - Cache-friendly headers
+ */
+
+declare class CDN {
+    private storage;
+    private baseUrl;
+    private cacheMaxAge;
+    private defaultContentType;
+    private cors;
+    constructor(options: CDNOptions);
+    /**
+     * Upload an artifact and get content-addressable URL
+     *
+     * @param content - Raw bytes to upload
+     * @param metadata - Optional metadata (filename, contentType, etc.)
+     * @returns Upload result with hash and URL
+     *
+     * @example
+     * ```typescript
+     * const result = await cdn.put(imageBytes, {
+     *   filename: 'logo.png',
+     *   contentType: 'image/png'
+     * });
+     *
+     * console.log(result.url); // https://cdn.example.com/a/5e88489...
+     * ```
+     */
+    put(content: ArrayBuffer | Uint8Array, metadata?: Partial<ArtifactMetadata>): Promise<UploadResult>;
+    /**
+     * Retrieve an artifact by hash
+     *
+     * @param hash - Content-addressable hash
+     * @returns Artifact or null if not found
+     *
+     * @example
+     * ```typescript
+     * const artifact = await cdn.get('5e884898...');
+     * if (artifact) {
+     *   console.log(artifact.metadata.contentType);
+     * }
+     * ```
+     */
+    get(hash: string): Promise<StoredArtifact | null>;
+    /**
+     * Delete an artifact by hash
+     *
+     * @param hash - Content-addressable hash
+     * @returns true if deleted, false if not found
+     *
+     * @example
+     * ```typescript
+     * const deleted = await cdn.delete('5e884898...');
+     * ```
+     */
+    delete(hash: string): Promise<boolean>;
+    /**
+     * Check if artifact exists
+     *
+     * @param hash - Content-addressable hash
+     * @returns true if exists
+     */
+    exists(hash: string): Promise<boolean>;
+    /**
+     * List all artifacts (if supported by storage adapter)
+     *
+     * @param options - List options
+     * @returns Array of hashes
+     */
+    list(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<string[]>;
+    /**
+     * Handle HTTP request (for Cloudflare Workers, Express, etc.)
+     *
+     * Routes:
+     * - PUT /artifact - Upload artifact
+     * - GET /a/:hash(.ext) - Retrieve artifact
+     * - DELETE /a/:hash - Delete artifact
+     *
+     * @param request - HTTP request
+     * @returns HTTP response
+     *
+     * @example
+     * ```typescript
+     * export default {
+     *   async fetch(request, env) {
+     *     const cdn = new CDN({
+     *       storage: new R2Storage(env.ARTIFACTS),
+     *       baseUrl: 'https://cdn.example.com'
+     *     });
+     *     return cdn.handleRequest(request);
+     *   }
+     * }
+     * ```
+     */
+    handleRequest(request: Request): Promise<Response>;
+    /**
+     * Get CORS headers if enabled
+     */
+    private getCORSHeaders;
+}
+
+/**
+ * In-memory storage adapter
+ *
+ * Useful for:
+ * - Testing
+ * - Development
+ * - Temporary caching
+ *
+ * NOT for production (data lost on restart)
+ */
+
+declare class MemoryStorage implements StorageAdapter {
+    private storage;
+    put(hash: string, content: ArrayBuffer | Uint8Array, metadata?: ArtifactMetadata): Promise<void>;
+    get(hash: string): Promise<StoredArtifact | null>;
+    delete(hash: string): Promise<boolean>;
+    exists(hash: string): Promise<boolean>;
+    list(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<string[]>;
+    /**
+     * Clear all stored artifacts (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Get storage size (number of artifacts)
+     */
+    size(): number;
+}
+
+/**
+ * Cloudflare R2 storage adapter
+ *
+ * Uses Cloudflare R2 for artifact storage.
+ *
+ * Usage:
+ * ```typescript
+ * const storage = new R2Storage(env.ARTIFACTS);
+ * ```
+ */
+
+/**
+ * Minimal R2 bucket interface
+ * (matches Cloudflare Workers R2Bucket type)
+ */
+interface R2Bucket {
+    put(key: string, value: ArrayBuffer | Uint8Array | ReadableStream, options?: {
+        httpMetadata?: {
+            contentType?: string;
+        };
+        customMetadata?: Record<string, string>;
+    }): Promise<any>;
+    get(key: string): Promise<{
+        body?: ReadableStream | ArrayBuffer;
+        httpMetadata?: {
+            contentType?: string;
+        };
+        customMetadata?: Record<string, string>;
+        size?: number;
+        uploaded?: Date;
+    } | null>;
+    delete(key: string): Promise<void>;
+    head(key: string): Promise<{
+        httpMetadata?: {
+            contentType?: string;
+        };
+        customMetadata?: Record<string, string>;
+        size?: number;
+        uploaded?: Date;
+    } | null>;
+    list?(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        objects: Array<{
+            key: string;
+        }>;
+        truncated: boolean;
+        cursor?: string;
+    }>;
+}
+declare class R2Storage implements StorageAdapter {
+    private bucket;
+    constructor(bucket: R2Bucket);
+    put(hash: string, content: ArrayBuffer | Uint8Array, metadata?: ArtifactMetadata): Promise<void>;
+    get(hash: string): Promise<StoredArtifact | null>;
+    delete(hash: string): Promise<boolean>;
+    exists(hash: string): Promise<boolean>;
+    list(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<string[]>;
+}
+
+export { type ArtifactMetadata, CDN, type CDNOptions, CONTENT_TYPES, MemoryStorage, type R2Bucket, R2Storage, type StorageAdapter, type StoredArtifact, type UploadResult, detectContentType };