@syncular/client 0.0.1-60

package/dist/blobs/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @syncular/client - Blob storage exports
+ */
+export * from './manager';
+export * from './migrate';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/blobs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/blobs/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/dist/blobs/index.js

@@ -0,0 +1,7 @@
+/**
+ * @syncular/client - Blob storage exports
+ */
+export * from './manager';
+export * from './migrate';
+export * from './types';
+//# sourceMappingURL=index.js.map

package/dist/blobs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/blobs/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/dist/blobs/manager.d.ts

@@ -0,0 +1,345 @@
+/**
+ * @syncular/client - Client-side blob manager
+ *
+ * Handles blob upload/download with:
+ * - Local caching for offline access
+ * - Upload queue for offline uploads
+ * - SHA-256 hash computation
+ * - Optional client-side encryption
+ */
+import type { BlobTransport } from '@syncular/core';
+import type { Kysely } from 'kysely';
+import type { BlobUploadStatus, SyncBlobClientDb } from './types';
+export type { BlobTransport } from '@syncular/core';
+interface BlobEncryption {
+    /**
+     * Encrypt blob content.
+     * Returns encrypted bytes and the key ID used.
+     */
+    encrypt(data: Uint8Array, options?: {
+        keyId?: string;
+    }): Promise<{
+        encrypted: Uint8Array;
+        keyId: string;
+    }>;
+    /**
+     * Decrypt blob content.
+     */
+    decrypt(data: Uint8Array, keyId: string): Promise<Uint8Array>;
+}
+export interface ClientBlobManagerOptions {
+    /** Kysely database instance */
+    db: Kysely<SyncBlobClientDb>;
+    /** Blob transport for server communication */
+    transport: BlobTransport;
+    /** Optional encryption handler */
+    encryption?: BlobEncryption;
+    /** Maximum cache size in bytes. Default: 100MB */
+    maxCacheSize?: number;
+    /** Maximum retry attempts for uploads. Default: 3 */
+    maxUploadRetries?: number;
+    /** Custom fetch function for blob uploads/downloads. Default: globalThis.fetch */
+    fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+}
+export interface UploadOptions {
+    /** Encrypt the blob before uploading */
+    encrypt?: boolean;
+    /** Specific encryption key ID to use */
+    keyId?: string;
+    /** Skip queuing and upload immediately (blocks until complete) */
+    immediate?: boolean;
+}
+export interface DownloadOptions {
+    /** Skip cache lookup and always fetch from server */
+    skipCache?: boolean;
+    /** Update last_accessed_at in cache */
+    updateAccessTime?: boolean;
+}
+/**
+ * Create a client-side blob manager.
+ *
+ * @example
+ * ```typescript
+ * const blobManager = createClientBlobManager({
+ *   db,
+ *   transport: {
+ *     async initiateUpload(args) {
+ *       const res = await fetch('/api/sync/blobs/upload', {
+ *         method: 'POST',
+ *         body: JSON.stringify(args),
+ *       });
+ *       return res.json();
+ *     },
+ *     async completeUpload(hash) {
+ *       const res = await fetch(`/api/sync/blobs/${hash}/complete`, { method: 'POST' });
+ *       return res.json();
+ *     },
+ *     async getDownloadUrl(hash) {
+ *       const res = await fetch(`/api/sync/blobs/${hash}/url`);
+ *       return res.json();
+ *     },
+ *   },
+ * });
+ *
+ * // Upload a file
+ * const blobRef = await blobManager.upload(file);
+ *
+ * // Download a blob
+ * const blob = await blobManager.download(blobRef);
+ * ```
+ */
+export declare function createClientBlobManager(options: ClientBlobManagerOptions): {
+    /**
+     * Upload a blob to the server.
+     *
+     * If `immediate` is false (default), the blob is queued for background upload.
+     * If `immediate` is true, the upload blocks until complete.
+     */
+    upload(data: Blob | File | Uint8Array<ArrayBufferLike>, opts?: UploadOptions | undefined): Promise<{
+        hash: string;
+        size: number;
+        mimeType: string;
+        encrypted?: boolean | undefined;
+        keyId?: string | undefined;
+    }>;
+    /**
+     * Download a blob.
+     *
+     * First checks the local cache, then fetches from server if needed.
+     * Automatically decrypts if the blob was encrypted.
+     */
+    download(ref: {
+        hash: string;
+        size: number;
+        mimeType: string;
+        encrypted?: boolean | undefined;
+        keyId?: string | undefined;
+    }, opts?: DownloadOptions | undefined): Promise<Uint8Array<ArrayBufferLike>>;
+    /**
+     * Check if a blob is cached locally.
+     */
+    isCached(hash: string): Promise<boolean>;
+    /**
+     * Get a blob URL for display.
+     *
+     * Returns a blob: URL if cached locally, or fetches and creates one.
+     */
+    getBlobUrl(ref: {
+        hash: string;
+        size: number;
+        mimeType: string;
+        encrypted?: boolean | undefined;
+        keyId?: string | undefined;
+    }): Promise<string>;
+    /**
+     * Preload blobs into the cache.
+     */
+    preload(refs: {
+        hash: string;
+        size: number;
+        mimeType: string;
+        encrypted?: boolean | undefined;
+        keyId?: string | undefined;
+    }[]): Promise<void>;
+    /**
+     * Process pending uploads in the outbox.
+     *
+     * Call this periodically or when online to sync pending uploads.
+     * Returns the number of blobs processed.
+     */
+    processUploadQueue(): Promise<{
+        uploaded: number;
+        failed: number;
+        errors: {
+            hash: string;
+            error: string;
+        }[];
+    }>;
+    /**
+     * Get the status of a pending upload.
+     */
+    getUploadStatus(hash: string): Promise<{
+        status: BlobUploadStatus;
+        error?: string | undefined;
+    } | null>;
+    /**
+     * Clear failed uploads from the outbox.
+     */
+    clearFailedUploads(): Promise<number>;
+    /**
+     * Retry a failed upload.
+     */
+    retryUpload(hash: string): Promise<boolean>;
+    /**
+     * Prune the cache to stay under maxCacheSize.
+     * Uses LRU (least recently used) eviction.
+     */
+    pruneCache(): Promise<{
+        evicted: number;
+        freedBytes: number;
+    }>;
+    /**
+     * Clear the entire cache.
+     */
+    clearCache(): Promise<number>;
+    /**
+     * Get cache statistics.
+     */
+    getCacheStats(): Promise<{
+        count: number;
+        totalSize: number;
+        maxSize: number;
+    }>;
+    /**
+     * Get upload queue statistics.
+     */
+    getUploadQueueStats(): Promise<{
+        pending: number;
+        uploading: number;
+        failed: number;
+        total: number;
+    }>;
+};
+type ClientBlobManager = ReturnType<typeof createClientBlobManager>;
+interface BlobCachePruneSchedulerOptions {
+    /** Client blob manager instance */
+    blobManager: ClientBlobManager;
+    /** Interval between prune runs in milliseconds. Default: 300000 (5 minutes) */
+    intervalMs?: number;
+    /** Optional: Called after each prune run */
+    onPrune?: (result: {
+        evicted: number;
+        freedBytes: number;
+        error?: Error;
+    }) => void;
+}
+/**
+ * Create a cache pruning scheduler for the client blob manager.
+ *
+ * Periodically prunes the cache to stay under maxCacheSize using LRU eviction.
+ *
+ * @example
+ * ```typescript
+ * const scheduler = createBlobCachePruneScheduler({
+ *   blobManager,
+ *   intervalMs: 5 * 60 * 1000, // 5 minutes
+ *   onPrune: (result) => {
+ *     if (result.evicted > 0) {
+ *       console.log(`Cache pruned: ${result.evicted} blobs, ${result.freedBytes} bytes freed`);
+ *     }
+ *   },
+ * });
+ *
+ * // Start the scheduler
+ * scheduler.start();
+ *
+ * // Stop when unmounting/shutting down
+ * scheduler.stop();
+ * ```
+ */
+export declare function createBlobCachePruneScheduler(options: BlobCachePruneSchedulerOptions): {
+    /**
+     * Start the prune scheduler.
+     * Optionally runs an immediate prune before starting the interval.
+     */
+    start(options?: {
+        immediate?: boolean | undefined;
+    } | undefined): void;
+    /**
+     * Stop the prune scheduler.
+     */
+    stop(): void;
+    /**
+     * Run a single prune manually.
+     */
+    runOnce(): Promise<{
+        evicted: number;
+        freedBytes: number;
+        error?: Error | undefined;
+    }>;
+    /**
+     * Check if the scheduler is currently active.
+     */
+    readonly active: boolean;
+    /**
+     * Check if a prune is currently in progress.
+     */
+    readonly running: boolean;
+};
+interface BlobUploadQueueSchedulerOptions {
+    /** Client blob manager instance */
+    blobManager: ClientBlobManager;
+    /** Interval between processing runs in milliseconds. Default: 30000 (30 seconds) */
+    intervalMs?: number;
+    /** Optional: Called after each processing run */
+    onProcess?: (result: {
+        uploaded: number;
+        failed: number;
+        errors: Array<{
+            hash: string;
+            error: string;
+        }>;
+        error?: Error;
+    }) => void;
+}
+/**
+ * Create an upload queue processor scheduler for the client blob manager.
+ *
+ * Periodically processes pending uploads when online.
+ *
+ * @example
+ * ```typescript
+ * const scheduler = createBlobUploadQueueScheduler({
+ *   blobManager,
+ *   intervalMs: 30 * 1000, // 30 seconds
+ *   onProcess: (result) => {
+ *     if (result.uploaded > 0) {
+ *       console.log(`Uploaded ${result.uploaded} blobs`);
+ *     }
+ *     if (result.failed > 0) {
+ *       console.warn(`Failed to upload ${result.failed} blobs`);
+ *     }
+ *   },
+ * });
+ *
+ * // Start when online
+ * scheduler.start();
+ *
+ * // Stop when offline or shutting down
+ * scheduler.stop();
+ * ```
+ */
+export declare function createBlobUploadQueueScheduler(options: BlobUploadQueueSchedulerOptions): {
+    /**
+     * Start the upload queue processor.
+     * Optionally runs an immediate processing before starting the interval.
+     */
+    start(options?: {
+        immediate?: boolean | undefined;
+    } | undefined): void;
+    /**
+     * Stop the upload queue processor.
+     */
+    stop(): void;
+    /**
+     * Run a single processing manually.
+     */
+    runOnce(): Promise<{
+        uploaded: number;
+        failed: number;
+        errors: {
+            hash: string;
+            error: string;
+        }[];
+        error?: Error | undefined;
+    }>;
+    /**
+     * Check if the processor is currently active.
+     */
+    readonly active: boolean;
+    /**
+     * Check if processing is currently in progress.
+     */
+    readonly running: boolean;
+};
+//# sourceMappingURL=manager.d.ts.map

package/dist/blobs/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/blobs/manager.ts"],"names":[],"mappings":"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"}