@syncular/client-plugin-blob 0.0.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@syncular/client-plugin-blob",
+  "version": "0.0.0",
+  "description": "Blob storage plugin for the Syncular client",
+  "license": "Apache-2.0",
+  "author": "Benjamin Kniffler",
+  "homepage": "https://syncular.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncular/syncular.git",
+    "directory": "plugins/blob/client"
+  },
+  "bugs": {
+    "url": "https://github.com/syncular/syncular/issues"
+  },
+  "keywords": [
+    "sync",
+    "offline-first",
+    "realtime",
+    "database",
+    "typescript",
+    "blob",
+    "storage"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "browser": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "test": "bun test --pass-with-no-tests",
+    "tsgo": "tsgo --noEmit",
+    "build": "tsgo",
+    "release": "bunx syncular-publish"
+  },
+  "dependencies": {
+    "@syncular/client": "0.0.0",
+    "@syncular/core": "0.0.0"
+  },
+  "devDependencies": {
+    "@syncular/config": "0.0.0",
+    "kysely": "*",
+    "kysely-bun-sqlite": "^0.4.0"
+  },
+  "peerDependencies": {
+    "kysely": "*"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,223 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import {
+  createDatabase,
+  type SyncTransport,
+} from '@syncular/core';
+import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
+import { createBunSqliteDialect } from '../../../../packages/dialect-bun-sqlite/src';
+import {
+  Client,
+  type SyncClientDb,
+} from '../../../../packages/client/src';
+import type { ClientHandlerCollection } from '../../../../packages/client/src/handlers/collection';
+import { ensureClientSyncSchema } from '../../../../packages/client/src/migrate';
+import { createBlobPlugin, ensureClientBlobSchema, type ClientBlobStorage } from './index';
+
+interface TasksTable {
+  id: string;
+  title: string;
+  server_version: number;
+}
+
+interface TestDb extends SyncClientDb {
+  tasks: TasksTable;
+}
+
+const noopTransport: SyncTransport = {
+  async sync() {
+    return {};
+  },
+  async fetchSnapshotChunk() {
+    return new Uint8Array();
+  },
+};
+
+function createMemoryBlobStorage(): ClientBlobStorage {
+  const memory = new Map<string, Uint8Array>();
+  return {
+    async write(hash, data) {
+      if (data instanceof ReadableStream) {
+        const reader = data.getReader();
+        const chunks: Uint8Array[] = [];
+        let total = 0;
+        while (true) {
+          const chunk = await reader.read();
+          if (chunk.done) break;
+          chunks.push(chunk.value);
+          total += chunk.value.length;
+        }
+        const combined = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+          combined.set(chunk, offset);
+          offset += chunk.length;
+        }
+        memory.set(hash, combined);
+        return;
+      }
+      memory.set(hash, new Uint8Array(data));
+    },
+    async read(hash) {
+      const data = memory.get(hash);
+      return data ? new Uint8Array(data) : null;
+    },
+    async delete(hash) {
+      memory.delete(hash);
+    },
+    async exists(hash) {
+      return memory.has(hash);
+    },
+  };
+}
+
+describe('blob client plugin', () => {
+  let db: Kysely<TestDb>;
+  let client: Client<TestDb>;
+  let initiateCalls = 0;
+
+  async function insertBlobOutboxRow(input: {
+    hash: string;
+    status: string;
+    attemptCount: number;
+    updatedAt: number;
+  }): Promise<void> {
+    const now = Date.now();
+    await sql`
+      insert into ${sql.table('sync_blob_outbox')} (
+        ${sql.join([
+          sql.ref('hash'),
+          sql.ref('size'),
+          sql.ref('mime_type'),
+          sql.ref('body'),
+          sql.ref('encrypted'),
+          sql.ref('key_id'),
+          sql.ref('status'),
+          sql.ref('attempt_count'),
+          sql.ref('error'),
+          sql.ref('created_at'),
+          sql.ref('updated_at'),
+        ])}
+      ) values (
+        ${sql.join([
+          sql.val(input.hash),
+          sql.val(3),
+          sql.val('application/octet-stream'),
+          sql.val(new Uint8Array([1, 2, 3])),
+          sql.val(0),
+          sql.val(null),
+          sql.val(input.status),
+          sql.val(input.attemptCount),
+          sql.val(null),
+          sql.val(now),
+          sql.val(input.updatedAt),
+        ])}
+      )
+    `.execute(db);
+  }
+
+  beforeEach(async () => {
+    db = createDatabase<TestDb>({
+      dialect: createBunSqliteDialect({ path: ':memory:' }),
+      family: 'sqlite',
+    });
+    await ensureClientSyncSchema(db);
+    await ensureClientBlobSchema(db);
+    initiateCalls = 0;
+
+    const handlers: ClientHandlerCollection<TestDb> = [];
+    const transport: SyncTransport = {
+      ...noopTransport,
+      blobs: {
+        async initiateUpload() {
+          initiateCalls++;
+          return { exists: true };
+        },
+        async completeUpload() {
+          return { ok: true };
+        },
+        async getDownloadUrl() {
+          return {
+            url: 'https://example.invalid/blob',
+            expiresAt: new Date(0).toISOString(),
+          };
+        },
+      },
+    };
+
+    client = new Client<TestDb>({
+      db,
+      transport,
+      tableHandlers: handlers,
+      clientId: 'client-1',
+      actorId: 'u1',
+      subscriptions: [],
+      plugins: [createBlobPlugin({ storage: createMemoryBlobStorage() })],
+    });
+  });
+
+  afterEach(async () => {
+    client.destroy();
+    await db.destroy();
+  });
+
+  it('attaches client.blobs through plugin setup', () => {
+    expect(client.blobs).toBeDefined();
+  });
+
+  it('requeues stale uploading rows and uploads them on the next queue run', async () => {
+    await insertBlobOutboxRow({
+      hash: 'sha256:stale-upload',
+      status: 'uploading',
+      attemptCount: 0,
+      updatedAt: Date.now() - 31_000,
+    });
+
+    const result = await client.blobs.processUploadQueue();
+
+    expect(result.uploaded).toBe(1);
+    expect(result.failed).toBe(0);
+    expect(initiateCalls).toBe(1);
+
+    const remaining = await sql<{ count: number | bigint }>`
+      select count(${sql.ref('hash')}) as count
+      from ${sql.table('sync_blob_outbox')}
+      where ${sql.ref('hash')} = ${'sha256:stale-upload'}
+    `.execute(db);
+    expect(Number(remaining.rows[0]?.count ?? 0)).toBe(0);
+  });
+
+  it('marks stale uploading rows as failed after max retries', async () => {
+    await insertBlobOutboxRow({
+      hash: 'sha256:stale-failed',
+      status: 'uploading',
+      attemptCount: 2,
+      updatedAt: Date.now() - 31_000,
+    });
+
+    await client.blobs.processUploadQueue();
+
+    expect(initiateCalls).toBe(0);
+
+    const rowResult = await sql<{
+      status: string;
+      attempt_count: number;
+      error: string | null;
+    }>`
+      select
+        ${sql.ref('status')} as status,
+        ${sql.ref('attempt_count')} as attempt_count,
+        ${sql.ref('error')} as error
+      from ${sql.table('sync_blob_outbox')}
+      where ${sql.ref('hash')} = ${'sha256:stale-failed'}
+      limit 1
+    `.execute(db);
+    const row = rowResult.rows[0];
+    if (!row) {
+      throw new Error('Expected stale failed row to remain in outbox');
+    }
+    expect(row.status).toBe('failed');
+    expect(row.attempt_count).toBe(3);
+    expect(row.error).toContain('Upload timed out while in uploading state');
+  });
+});

package/src/index.ts

@@ -0,0 +1,481 @@
+import type { SyncTransport } from '@syncular/core';
+import type {
+  SyncClientDb,
+  SyncClientPlugin,
+} from '@syncular/client';
+import { sql } from 'kysely';
+import { ensureClientBlobSchema } from './migrate';
+import type { BlobClient, ClientBlobStorage } from './types';
+
+export * from './migrate';
+export * from './types';
+
+export const BLOB_PLUGIN_KIND = 'blob';
+
+export interface BlobPluginOptions {
+  storage: ClientBlobStorage;
+}
+
+declare module '@syncular/client' {
+  interface SyncClientFeatureRegistry {
+    blobs: BlobClient;
+  }
+}
+
+declare module 'syncular/client' {
+  interface SyncClientFeatureRegistry {
+    blobs: BlobClient;
+  }
+}
+
+export function createBlobPlugin(options: BlobPluginOptions): SyncClientPlugin {
+  return {
+    kind: BLOB_PLUGIN_KIND,
+    name: BLOB_PLUGIN_KIND,
+    setup(ctx) {
+      if (!ctx.transport.blobs) {
+        throw new Error(
+          'Blob plugin requires a transport with blob support enabled'
+        );
+      }
+
+      ctx.defineFeature(
+        'blobs',
+        createBlobClient({
+          db: ctx.db,
+          transport: ctx.transport,
+          storage: options.storage,
+          emit: ctx.emit,
+        })
+      );
+    },
+    async migrate(ctx) {
+      await ensureClientBlobSchema(ctx.db);
+    },
+  };
+}
+
+function createBlobClient(args: {
+  db: import('kysely').Kysely<SyncClientDb>;
+  transport: SyncTransport;
+  storage: ClientBlobStorage;
+  emit: (event: string, payload: object) => void;
+}): BlobClient {
+  const { db, storage, transport, emit } = args;
+  const blobs = transport.blobs!;
+  const staleUploadingTimeoutMs = 30_000;
+  const maxUploadRetries = 3;
+
+  return {
+    async store(data, options) {
+      const bytes = await toUint8Array(data);
+      const mimeType =
+        data instanceof Blob
+          ? data.type
+          : (options?.mimeType ?? 'application/octet-stream');
+
+      const hashHex = await computeSha256Hex(bytes);
+      const hash = `sha256:${hashHex}`;
+
+      await storage.write(hash, bytes);
+
+      const now = Date.now();
+      await sql`
+        insert into ${sql.table('sync_blob_cache')} (
+          ${sql.join([
+            sql.ref('hash'),
+            sql.ref('size'),
+            sql.ref('mime_type'),
+            sql.ref('cached_at'),
+            sql.ref('last_accessed_at'),
+            sql.ref('encrypted'),
+            sql.ref('key_id'),
+            sql.ref('body'),
+          ])}
+        ) values (
+          ${sql.join([
+            sql.val(hash),
+            sql.val(bytes.length),
+            sql.val(mimeType),
+            sql.val(now),
+            sql.val(now),
+            sql.val(0),
+            sql.val(null),
+            sql.val(bytes),
+          ])}
+        )
+        on conflict (${sql.ref('hash')}) do nothing
+      `.execute(db);
+
+      if (options?.immediate) {
+        const initResult = await blobs.initiateUpload({
+          hash,
+          size: bytes.length,
+          mimeType,
+        });
+
+        if (!initResult.exists && initResult.uploadUrl) {
+          const uploadResponse = await fetch(initResult.uploadUrl, {
+            method: initResult.uploadMethod ?? 'PUT',
+            body: bytes.buffer as ArrayBuffer,
+            headers: initResult.uploadHeaders,
+          });
+
+          if (!uploadResponse.ok) {
+            throw new Error(`Upload failed: ${uploadResponse.statusText}`);
+          }
+
+          await blobs.completeUpload(hash);
+        }
+      } else {
+        await sql`
+          insert into ${sql.table('sync_blob_outbox')} (
+            ${sql.join([
+              sql.ref('hash'),
+              sql.ref('size'),
+              sql.ref('mime_type'),
+              sql.ref('status'),
+              sql.ref('created_at'),
+              sql.ref('updated_at'),
+              sql.ref('attempt_count'),
+              sql.ref('error'),
+              sql.ref('encrypted'),
+              sql.ref('key_id'),
+              sql.ref('body'),
+            ])}
+          ) values (
+            ${sql.join([
+              sql.val(hash),
+              sql.val(bytes.length),
+              sql.val(mimeType),
+              sql.val('pending'),
+              sql.val(now),
+              sql.val(now),
+              sql.val(0),
+              sql.val(null),
+              sql.val(0),
+              sql.val(null),
+              sql.val(bytes),
+            ])}
+          )
+          on conflict (${sql.ref('hash')}) do nothing
+        `.execute(db);
+      }
+
+      return {
+        hash,
+        size: bytes.length,
+        mimeType,
+      };
+    },
+
+    async retrieve(ref) {
+      const local = await storage.read(ref.hash);
+      if (local) {
+        await sql`
+          update ${sql.table('sync_blob_cache')}
+          set ${sql.ref('last_accessed_at')} = ${sql.val(Date.now())}
+          where ${sql.ref('hash')} = ${sql.val(ref.hash)}
+        `.execute(db);
+        return local;
+      }
+
+      const { url } = await blobs.getDownloadUrl(ref.hash);
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error(`Download failed: ${response.statusText}`);
+      }
+
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      await storage.write(ref.hash, bytes);
+      const now = Date.now();
+      await sql`
+        insert into ${sql.table('sync_blob_cache')} (
+          ${sql.join([
+            sql.ref('hash'),
+            sql.ref('size'),
+            sql.ref('mime_type'),
+            sql.ref('cached_at'),
+            sql.ref('last_accessed_at'),
+            sql.ref('encrypted'),
+            sql.ref('key_id'),
+            sql.ref('body'),
+          ])}
+        ) values (
+          ${sql.join([
+            sql.val(ref.hash),
+            sql.val(bytes.length),
+            sql.val(ref.mimeType),
+            sql.val(now),
+            sql.val(now),
+            sql.val(0),
+            sql.val(null),
+            sql.val(bytes),
+          ])}
+        )
+        on conflict (${sql.ref('hash')}) do nothing
+      `.execute(db);
+
+      return bytes;
+    },
+
+    async isLocal(hash) {
+      return storage.exists(hash);
+    },
+
+    async preload(refs) {
+      await Promise.all(refs.map((ref) => this.retrieve(ref)));
+    },
+
+    async processUploadQueue() {
+      let uploaded = 0;
+      let failed = 0;
+      const now = Date.now();
+      const staleThreshold = now - staleUploadingTimeoutMs;
+
+      await sql`
+        update ${sql.table('sync_blob_outbox')}
+        set
+          ${sql.ref('status')} = ${sql.val('failed')},
+          ${sql.ref('attempt_count')} = ${sql.ref('attempt_count')} + ${sql.val(
+            1
+          )},
+          ${sql.ref('error')} = ${sql.val(
+            'Upload timed out while in uploading state'
+          )},
+          ${sql.ref('updated_at')} = ${sql.val(now)}
+        where ${sql.ref('status')} = ${sql.val('uploading')}
+          and ${sql.ref('updated_at')} < ${sql.val(staleThreshold)}
+          and ${sql.ref('attempt_count')} + ${sql.val(1)} >= ${sql.val(
+            maxUploadRetries
+          )}
+      `.execute(db);
+
+      await sql`
+        update ${sql.table('sync_blob_outbox')}
+        set
+          ${sql.ref('status')} = ${sql.val('pending')},
+          ${sql.ref('attempt_count')} = ${sql.ref('attempt_count')} + ${sql.val(
+            1
+          )},
+          ${sql.ref('error')} = ${sql.val(
+            'Upload timed out while in uploading state; retrying'
+          )},
+          ${sql.ref('updated_at')} = ${sql.val(now)}
+        where ${sql.ref('status')} = ${sql.val('uploading')}
+          and ${sql.ref('updated_at')} < ${sql.val(staleThreshold)}
+          and ${sql.ref('attempt_count')} + ${sql.val(1)} < ${sql.val(
+            maxUploadRetries
+          )}
+      `.execute(db);
+
+      const pendingResult = await sql<{
+        hash: string;
+        size: number;
+        mime_type: string;
+        body: Uint8Array | null;
+        attempt_count: number;
+      }>`
+        select
+          ${sql.ref('hash')},
+          ${sql.ref('size')},
+          ${sql.ref('mime_type')},
+          ${sql.ref('body')},
+          ${sql.ref('attempt_count')}
+        from ${sql.table('sync_blob_outbox')}
+        where ${sql.ref('status')} = ${sql.val('pending')}
+          and ${sql.ref('attempt_count')} < ${sql.val(maxUploadRetries)}
+        limit ${sql.val(10)}
+      `.execute(db);
+      const pending = pendingResult.rows;
+
+      for (const item of pending) {
+        const nextAttemptCount = item.attempt_count + 1;
+        try {
+          await sql`
+            update ${sql.table('sync_blob_outbox')}
+            set
+              ${sql.ref('status')} = ${sql.val('uploading')},
+              ${sql.ref('attempt_count')} = ${sql.val(nextAttemptCount)},
+              ${sql.ref('error')} = ${sql.val(null)},
+              ${sql.ref('updated_at')} = ${sql.val(Date.now())}
+            where ${sql.ref('hash')} = ${sql.val(item.hash)}
+              and ${sql.ref('status')} = ${sql.val('pending')}
+          `.execute(db);
+
+          const initResult = await blobs.initiateUpload({
+            hash: item.hash,
+            size: item.size,
+            mimeType: item.mime_type,
+          });
+
+          if (!initResult.exists && initResult.uploadUrl && item.body) {
+            const uploadBody = new ArrayBuffer(item.body.byteLength);
+            new Uint8Array(uploadBody).set(item.body);
+
+            const uploadResponse = await fetch(initResult.uploadUrl, {
+              method: initResult.uploadMethod ?? 'PUT',
+              body: uploadBody,
+              headers: initResult.uploadHeaders,
+            });
+
+            if (!uploadResponse.ok) {
+              throw new Error(`Upload failed: ${uploadResponse.statusText}`);
+            }
+
+            const completeResult = await blobs.completeUpload(item.hash);
+            if (!completeResult.ok) {
+              throw new Error(
+                completeResult.error ?? 'Failed to complete blob upload'
+              );
+            }
+          }
+
+          await sql`
+            delete from ${sql.table('sync_blob_outbox')}
+            where ${sql.ref('hash')} = ${sql.val(item.hash)}
+          `.execute(db);
+
+          emit('blob:upload:complete', {
+            hash: item.hash,
+            size: item.size,
+            mimeType: item.mime_type,
+          });
+          uploaded++;
+        } catch (err) {
+          const nextStatus =
+            nextAttemptCount >= maxUploadRetries ? 'failed' : 'pending';
+          const errorMessage =
+            err instanceof Error ? err.message : 'Unknown error';
+
+          await sql`
+            update ${sql.table('sync_blob_outbox')}
+            set
+              ${sql.ref('status')} = ${sql.val(nextStatus)},
+              ${sql.ref('error')} = ${sql.val(errorMessage)},
+              ${sql.ref('updated_at')} = ${sql.val(Date.now())}
+            where ${sql.ref('hash')} = ${sql.val(item.hash)}
+          `.execute(db);
+
+          emit('blob:upload:error', {
+            hash: item.hash,
+            error: errorMessage,
+          });
+
+          if (nextStatus === 'failed') {
+            failed++;
+          }
+        }
+      }
+
+      return { uploaded, failed };
+    },
+
+    async getUploadQueueStats() {
+      const rowsResult = await sql<{
+        status: string;
+        count: number | bigint;
+      }>`
+        select
+          ${sql.ref('status')} as status,
+          count(${sql.ref('hash')}) as count
+        from ${sql.table('sync_blob_outbox')}
+        group by ${sql.ref('status')}
+      `.execute(db);
+
+      const stats = { pending: 0, uploading: 0, failed: 0 };
+      for (const row of rowsResult.rows) {
+        if (row.status === 'pending') stats.pending = Number(row.count);
+        if (row.status === 'uploading') stats.uploading = Number(row.count);
+        if (row.status === 'failed') stats.failed = Number(row.count);
+      }
+      return stats;
+    },
+
+    async getCacheStats() {
+      const result = await sql<{
+        count: number | bigint;
+        totalBytes: number | bigint | null;
+      }>`
+        select
+          count(${sql.ref('hash')}) as count,
+          sum(${sql.ref('size')}) as totalBytes
+        from ${sql.table('sync_blob_cache')}
+      `.execute(db);
+      const row = result.rows[0];
+
+      return {
+        count: Number(row?.count ?? 0),
+        totalBytes: Number(row?.totalBytes ?? 0),
+      };
+    },
+
+    async pruneCache(maxBytes) {
+      if (!maxBytes) return 0;
+
+      const stats = await this.getCacheStats();
+      if (stats.totalBytes <= maxBytes) return 0;
+
+      const toFree = stats.totalBytes - maxBytes;
+      let freed = 0;
+
+      const oldEntriesResult = await sql<{ hash: string; size: number }>`
+        select ${sql.ref('hash')}, ${sql.ref('size')}
+        from ${sql.table('sync_blob_cache')}
+        order by ${sql.ref('last_accessed_at')} asc
+      `.execute(db);
+      const oldEntries = oldEntriesResult.rows;
+
+      for (const entry of oldEntries) {
+        if (freed >= toFree) break;
+
+        await storage.delete(entry.hash);
+        await sql`
+          delete from ${sql.table('sync_blob_cache')}
+          where ${sql.ref('hash')} = ${sql.val(entry.hash)}
+        `.execute(db);
+        freed += entry.size;
+      }
+
+      return freed;
+    },
+
+    async clearCache() {
+      if (storage.clear) {
+        await storage.clear();
+      } else {
+        const entriesResult = await sql<{ hash: string }>`
+          select ${sql.ref('hash')}
+          from ${sql.table('sync_blob_cache')}
+        `.execute(db);
+
+        for (const entry of entriesResult.rows) {
+          await storage.delete(entry.hash);
+        }
+      }
+
+      await sql`delete from ${sql.table('sync_blob_cache')}`.execute(db);
+    },
+  };
+}
+
+async function toUint8Array(
+  data: Blob | File | Uint8Array
+): Promise<Uint8Array> {
+  if (data instanceof Uint8Array) {
+    return data;
+  }
+  const buffer = await data.arrayBuffer();
+  return new Uint8Array(buffer);
+}
+
+async function computeSha256Hex(data: Uint8Array): Promise<string> {
+  const hashBuffer = await crypto.subtle.digest(
+    'SHA-256',
+    data.buffer as ArrayBuffer
+  );
+  const hashArray = new Uint8Array(hashBuffer);
+  return Array.from(hashArray)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}

package/src/migrate.ts

@@ -0,0 +1,54 @@
+import type { Kysely } from 'kysely';
+
+export async function ensureClientBlobSchema<DB>(
+  db: Kysely<DB>
+): Promise<void> {
+  await db.schema
+    .createTable('sync_blob_cache')
+    .ifNotExists()
+    .addColumn('hash', 'text', (col) => col.primaryKey())
+    .addColumn('size', 'integer', (col) => col.notNull())
+    .addColumn('mime_type', 'text', (col) => col.notNull())
+    .addColumn('body', 'blob', (col) => col.notNull())
+    .addColumn('encrypted', 'integer', (col) => col.notNull().defaultTo(0))
+    .addColumn('key_id', 'text')
+    .addColumn('cached_at', 'bigint', (col) => col.notNull())
+    .addColumn('last_accessed_at', 'bigint', (col) => col.notNull())
+    .execute();
+
+  await db.schema
+    .createIndex('idx_sync_blob_cache_last_accessed')
+    .ifNotExists()
+    .on('sync_blob_cache')
+    .columns(['last_accessed_at'])
+    .execute();
+
+  await db.schema
+    .createTable('sync_blob_outbox')
+    .ifNotExists()
+    .addColumn('id', 'integer', (col) => col.primaryKey().autoIncrement())
+    .addColumn('hash', 'text', (col) => col.notNull().unique())
+    .addColumn('size', 'integer', (col) => col.notNull())
+    .addColumn('mime_type', 'text', (col) => col.notNull())
+    .addColumn('body', 'blob', (col) => col.notNull())
+    .addColumn('encrypted', 'integer', (col) => col.notNull().defaultTo(0))
+    .addColumn('key_id', 'text')
+    .addColumn('status', 'text', (col) => col.notNull())
+    .addColumn('attempt_count', 'integer', (col) => col.notNull().defaultTo(0))
+    .addColumn('error', 'text')
+    .addColumn('created_at', 'bigint', (col) => col.notNull())
+    .addColumn('updated_at', 'bigint', (col) => col.notNull())
+    .execute();
+
+  await db.schema
+    .createIndex('idx_sync_blob_outbox_status')
+    .ifNotExists()
+    .on('sync_blob_outbox')
+    .columns(['status', 'created_at'])
+    .execute();
+}
+
+export async function dropClientBlobSchema<DB>(db: Kysely<DB>): Promise<void> {
+  await db.schema.dropTable('sync_blob_outbox').ifExists().execute();
+  await db.schema.dropTable('sync_blob_cache').ifExists().execute();
+}

package/src/types.ts

@@ -0,0 +1,77 @@
+import type { Generated } from 'kysely';
+
+export interface ClientBlobStorage {
+  write(
+    hash: string,
+    data: Uint8Array | ReadableStream<Uint8Array>
+  ): Promise<void>;
+  read(hash: string): Promise<Uint8Array | null>;
+  readStream?(hash: string): Promise<ReadableStream<Uint8Array> | null>;
+  delete(hash: string): Promise<void>;
+  exists(hash: string): Promise<boolean>;
+  getUsage?(): Promise<number>;
+  clear?(): Promise<void>;
+}
+
+interface BlobStoreOptions {
+  mimeType?: string;
+  immediate?: boolean;
+}
+
+export interface BlobClient {
+  store(
+    data: Blob | File | Uint8Array,
+    options?: BlobStoreOptions
+  ): Promise<import('@syncular/core').BlobRef>;
+  retrieve(ref: import('@syncular/core').BlobRef): Promise<Uint8Array>;
+  isLocal(hash: string): Promise<boolean>;
+  preload(refs: import('@syncular/core').BlobRef[]): Promise<void>;
+  processUploadQueue(): Promise<{ uploaded: number; failed: number }>;
+  getUploadQueueStats(): Promise<{
+    pending: number;
+    uploading: number;
+    failed: number;
+  }>;
+  getCacheStats(): Promise<{ count: number; totalBytes: number }>;
+  pruneCache(maxBytes?: number): Promise<number>;
+  clearCache(): Promise<void>;
+}
+
+export interface SyncBlobCacheTable {
+  hash: string;
+  size: number;
+  mime_type: string;
+  body: Uint8Array;
+  encrypted: number;
+  key_id: string | null;
+  cached_at: number;
+  last_accessed_at: number;
+}
+
+export type BlobUploadStatus =
+  | 'pending'
+  | 'uploading'
+  | 'uploaded'
+  | 'confirming'
+  | 'complete'
+  | 'failed';
+
+export interface SyncBlobOutboxTable {
+  id: Generated<number>;
+  hash: string;
+  size: number;
+  mime_type: string;
+  body: Uint8Array;
+  encrypted: number;
+  key_id: string | null;
+  status: BlobUploadStatus;
+  attempt_count: number;
+  error: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface SyncBlobClientDb {
+  sync_blob_cache: SyncBlobCacheTable;
+  sync_blob_outbox: SyncBlobOutboxTable;
+}