@syncular/core 0.0.6-96 → 0.1.0

package/src/http/transport-client.ts

@@ -0,0 +1,314 @@
+import type {
+  SyncAuthErrorContext,
+  SyncAuthLifecycle,
+  SyncCombinedRequest,
+  SyncCombinedResponse,
+} from '@syncular/core';
+import {
+  decodeBinarySyncPack,
+  isBinarySyncPackContentType,
+} from '@syncular/core';
+import type { SyncClient } from './api-client';
+import {
+  type ApiResult,
+  type ClientOptions,
+  encodeSnapshotScopes,
+  type ResolveAuthRetry,
+  resolveRequestUrl,
+  SNAPSHOT_SCOPES_HEADER,
+} from './shared';
+
+export type { ClientOptions };
+
+export const HTTP_TRANSPORT_SOURCE = Symbol.for('@syncular/core/http/source');
+
+export type HttpTransportSource = SyncClient | ClientOptions;
+
+function isApiClientLike(value: unknown): value is SyncClient {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as SyncClient).GET === 'function' &&
+    typeof (value as SyncClient).POST === 'function'
+  );
+}
+
+interface TransportApiClient {
+  sync(
+    request: SyncCombinedRequest,
+    signal?: AbortSignal
+  ): Promise<ApiResult<SyncCombinedResponse>>;
+  initiateUpload(
+    args: { hash: string; size: number; mimeType: string },
+    signal?: AbortSignal
+  ): Promise<
+    ApiResult<{
+      exists: boolean;
+      uploadUrl?: string;
+      uploadMethod?: 'PUT' | 'POST';
+      uploadHeaders?: Record<string, string>;
+    }>
+  >;
+  completeUpload(
+    hash: string,
+    signal?: AbortSignal
+  ): Promise<ApiResult<{ ok: boolean; error?: string }>>;
+  getDownloadUrl(
+    hash: string,
+    signal?: AbortSignal
+  ): Promise<ApiResult<{ url: string; expiresAt: string }>>;
+  getSnapshotChunk(
+    chunkId: string,
+    scopeValues: Record<string, string | string[]> | undefined,
+    signal?: AbortSignal
+  ): Promise<ApiResult<Blob>>;
+}
+
+function isJsonContentType(contentType: string | null): boolean {
+  return contentType?.includes('application/json') === true;
+}
+
+async function parseErrorBody(response: Response): Promise<unknown> {
+  if (!isJsonContentType(response.headers.get('content-type'))) {
+    return undefined;
+  }
+  try {
+    return (await response.json()) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+async function parseJsonBody<T>(response: Response): Promise<T | undefined> {
+  if (!isJsonContentType(response.headers.get('content-type'))) {
+    return undefined;
+  }
+  try {
+    return (await response.json()) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+function createAuthRetryResolver(
+  defaultAuthLifecycle: SyncAuthLifecycle | undefined
+): ResolveAuthRetry {
+  let refreshInFlight: Promise<boolean> | null = null;
+
+  const runRefreshSingleFlight = async (
+    lifecycle: SyncAuthLifecycle,
+    context: SyncAuthErrorContext
+  ): Promise<boolean> => {
+    if (!lifecycle.refreshToken) return false;
+
+    if (!refreshInFlight) {
+      refreshInFlight = Promise.resolve(lifecycle.refreshToken(context))
+        .then((result) => Boolean(result))
+        .finally(() => {
+          refreshInFlight = null;
+        });
+    }
+
+    return refreshInFlight;
+  };
+
+  return async (context, options) => {
+    const lifecycle = options?.authLifecycle ?? defaultAuthLifecycle;
+    if (!lifecycle) return false;
+
+    await lifecycle.onAuthExpired?.(context);
+
+    const refreshResult = await runRefreshSingleFlight(lifecycle, context);
+    if (lifecycle.retryWithFreshToken) {
+      return Boolean(
+        await lifecycle.retryWithFreshToken({ ...context, refreshResult })
+      );
+    }
+    return refreshResult;
+  };
+}
+
+function createRequestHeaders(
+  baseOptions: ClientOptions,
+  extraHeaders?: Record<string, string>
+): Promise<Headers> {
+  return Promise.resolve(baseOptions.getHeaders?.()).then((dynamicHeaders) => {
+    const headers = new Headers(extraHeaders);
+    if (dynamicHeaders) {
+      for (const [key, value] of Object.entries(dynamicHeaders)) {
+        headers.set(key, value);
+      }
+    }
+    if (!headers.has('x-syncular-transport-path')) {
+      headers.set(
+        'x-syncular-transport-path',
+        baseOptions.transportPath ?? 'direct'
+      );
+    }
+    return headers;
+  });
+}
+
+function createFetchApiClient(baseOptions: ClientOptions): TransportApiClient {
+  const fetchImpl = baseOptions.fetch ?? globalThis.fetch;
+
+  const request = async <T>(args: {
+    method: 'GET' | 'POST';
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    parseAs?: 'json' | 'blob';
+  }): Promise<ApiResult<T>> => {
+    const headers = await createRequestHeaders(baseOptions, args.headers);
+    let body: BodyInit | undefined;
+    if (args.body !== undefined) {
+      headers.set('content-type', 'application/json');
+      body = JSON.stringify(args.body);
+    }
+
+    const response = await fetchImpl(
+      resolveRequestUrl(baseOptions.baseUrl, args.path),
+      {
+        method: args.method,
+        headers,
+        body,
+        ...(args.signal ? { signal: args.signal } : {}),
+      }
+    );
+
+    if (!response.ok) {
+      return {
+        response,
+        error: await parseErrorBody(response),
+      };
+    }
+
+    if (args.parseAs === 'blob') {
+      return {
+        response,
+        data: (await response.blob()) as T,
+      };
+    }
+
+    if (isBinarySyncPackContentType(response.headers.get('content-type'))) {
+      return {
+        response,
+        data: decodeBinarySyncPack(
+          new Uint8Array(await response.arrayBuffer())
+        ) as T,
+      };
+    }
+
+    return {
+      response,
+      data: await parseJsonBody<T>(response),
+    };
+  };
+
+  return {
+    sync: (requestBody, signal) =>
+      request({
+        method: 'POST',
+        path: '/sync',
+        body: requestBody,
+        signal,
+      }),
+    initiateUpload: (args, signal) =>
+      request({
+        method: 'POST',
+        path: '/sync/blobs/upload',
+        body: args,
+        signal,
+      }),
+    completeUpload: (hash, signal) =>
+      request({
+        method: 'POST',
+        path: `/sync/blobs/${encodeURIComponent(hash)}/complete`,
+        signal,
+      }),
+    getDownloadUrl: (hash, signal) =>
+      request({
+        method: 'GET',
+        path: `/sync/blobs/${encodeURIComponent(hash)}/url`,
+        signal,
+      }),
+    getSnapshotChunk: (chunkId, scopeValues, signal) =>
+      request({
+        method: 'GET',
+        path: `/sync/snapshot-chunks/${encodeURIComponent(chunkId)}`,
+        headers: (() => {
+          const encodedScopes = encodeSnapshotScopes(scopeValues);
+          return encodedScopes
+            ? {
+                [SNAPSHOT_SCOPES_HEADER]: encodedScopes,
+              }
+            : undefined;
+        })(),
+        signal,
+        parseAs: 'blob',
+      }),
+  };
+}
+
+function createTypedTransportClient(client: SyncClient): TransportApiClient {
+  return {
+    sync: (request, signal) =>
+      client.POST('/sync', {
+        body: request,
+        ...(signal ? { signal } : {}),
+      }) as Promise<ApiResult<SyncCombinedResponse>>,
+    initiateUpload: (args, signal) =>
+      client.POST('/sync/blobs/upload', {
+        body: args,
+        ...(signal ? { signal } : {}),
+      }) as Promise<
+        ApiResult<{
+          exists: boolean;
+          uploadUrl?: string;
+          uploadMethod?: 'PUT' | 'POST';
+          uploadHeaders?: Record<string, string>;
+        }>
+      >,
+    completeUpload: (hash, signal) =>
+      client.POST('/sync/blobs/{hash}/complete', {
+        params: { path: { hash } },
+        ...(signal ? { signal } : {}),
+      }) as Promise<ApiResult<{ ok: boolean; error?: string }>>,
+    getDownloadUrl: (hash, signal) =>
+      client.GET('/sync/blobs/{hash}/url', {
+        params: { path: { hash } },
+        ...(signal ? { signal } : {}),
+      }) as Promise<ApiResult<{ url: string; expiresAt: string }>>,
+    getSnapshotChunk: (chunkId, scopeValues, signal) =>
+      client.GET('/sync/snapshot-chunks/{chunkId}', {
+        params: { path: { chunkId } },
+        parseAs: 'blob',
+        headers: (() => {
+          const encodedScopes = encodeSnapshotScopes(scopeValues);
+          return encodedScopes
+            ? {
+                [SNAPSHOT_SCOPES_HEADER]: encodedScopes,
+              }
+            : undefined;
+        })(),
+        ...(signal ? { signal } : {}),
+      }) as Promise<ApiResult<Blob>>,
+  };
+}
+
+export function createTransportApiClient(
+  source: HttpTransportSource
+): TransportApiClient {
+  return isApiClientLike(source)
+    ? createTypedTransportClient(source)
+    : createFetchApiClient(source);
+}
+
+export function createTransportAuthRetryResolver(
+  source: HttpTransportSource
+): ResolveAuthRetry {
+  return createAuthRetryResolver(
+    isApiClientLike(source) ? undefined : source.authLifecycle
+  );
+}

package/src/index.ts

@@ -20,6 +20,8 @@ export * from './conflict';
 export * from './database';
 // Database dialect descriptors
 export * from './dialect';
+// Public error response envelopes
+export * from './error-responses';
 // Kysely plugin for applying column codecs in generic queries
 export * from './kysely-column-codecs';
 // Logging utilities
@@ -32,6 +34,8 @@ export * from './schemas';
 export * from './scopes';
 // Snapshot chunk encoding helpers
 export * from './snapshot-chunks';
+// Sync response pack encoding helpers
+export * from './sync-packs';
 // Telemetry abstraction
 export * from './telemetry';
 // Data transformation hooks

package/src/kysely-column-codecs.ts

@@ -28,8 +28,8 @@ import {
   applyCodecToDbValue,
   type ColumnCodecDialect,
   type ColumnCodecSource,
+  createTableColumnCodecsResolver,
   type TableColumnCodecs,
-  toTableColumnCodecs,
 } from './column-codecs';
 
 interface ColumnCodecPluginOptions {
@@ -43,7 +43,7 @@ interface ColumnReference {
   column: string;
 }
 
-interface QueryResultPlan {
+export interface QueryResultPlan {
   explicit: ColumnReference[];
   selectAllTables: string[];
 }
@@ -335,7 +335,9 @@ function planForDelete(node: DeleteQueryNode): QueryResultPlan | null {
   return collected;
 }
 
-function buildResultPlan(node: RootOperationNode): QueryResultPlan | null {
+export function buildQueryResultPlan(
+  node: RootOperationNode
+): QueryResultPlan | null {
   if (node.kind === 'SelectQueryNode') return planForSelect(node);
   if (node.kind === 'InsertQueryNode') return planForInsert(node);
   if (node.kind === 'UpdateQueryNode') return planForUpdate(node);
@@ -343,35 +345,73 @@ function buildResultPlan(node: RootOperationNode): QueryResultPlan | null {
   return null;
 }
 
-function cacheKey(table: string, columns: readonly string[]): string {
-  const sorted = [...columns].sort().join('\u0000');
-  return `${table}\u0001${sorted}`;
+export function applyQueryResultPlan(args: {
+  row: UnknownRow;
+  plan: QueryResultPlan;
+  resolveTableCodecs: (
+    table: string,
+    row: Record<string, unknown>
+  ) => TableColumnCodecs;
+  dialect: ColumnCodecDialect;
+}): UnknownRow {
+  const { row, plan, resolveTableCodecs, dialect } = args;
+  const source = row as Record<string, unknown>;
+  const target: Record<string, unknown> = { ...source };
+
+  if (plan.selectAllTables.length > 0) {
+    const codecCandidates = new Map<string, AnyColumnCodec>();
+    const ambiguousColumns = new Set<string>();
+
+    for (const table of plan.selectAllTables) {
+      const tableCodecs = resolveTableCodecs(table, source);
+      for (const [column, codec] of Object.entries(tableCodecs)) {
+        if (!(column in source)) continue;
+        const existing = codecCandidates.get(column);
+        if (existing && existing !== codec) {
+          ambiguousColumns.add(column);
+          continue;
+        }
+        codecCandidates.set(column, codec);
+      }
+    }
+
+    for (const [column, codec] of codecCandidates.entries()) {
+      if (ambiguousColumns.has(column)) continue;
+      target[column] = applyCodecFromDbValue(codec, target[column], dialect);
+    }
+  }
+
+  for (const ref of plan.explicit) {
+    if (!(ref.outputKey in source)) continue;
+    const tableCodecs = resolveTableCodecs(ref.table, {
+      [ref.column]: source[ref.outputKey],
+    });
+    const codec = tableCodecs[ref.column];
+    if (!codec) continue;
+    target[ref.outputKey] = applyCodecFromDbValue(
+      codec,
+      target[ref.outputKey],
+      dialect
+    );
+  }
+
+  return target;
 }
 
 class ColumnCodecsTransformer extends OperationNodeTransformer {
-  readonly #codecs: ColumnCodecSource;
   readonly #dialect: ColumnCodecDialect;
-  readonly #tableCodecsCache = new Map<string, TableColumnCodecs>();
+  readonly #resolveTableCodecs: (
+    table: string,
+    row: Record<string, unknown>
+  ) => TableColumnCodecs;
   #currentUpdateTable: string | null = null;
 
   constructor(options: ColumnCodecPluginOptions) {
     super();
-    this.#codecs = options.codecs;
     this.#dialect = options.dialect ?? 'sqlite';
-  }
-
-  resolveTableCodecs(
-    table: string,
-    columns: readonly string[]
-  ): TableColumnCodecs {
-    const key = cacheKey(table, columns);
-    const cached = this.#tableCodecsCache.get(key);
-    if (cached) return cached;
-    const resolved = toTableColumnCodecs(table, this.#codecs, columns, {
+    this.#resolveTableCodecs = createTableColumnCodecsResolver(options.codecs, {
       dialect: this.#dialect,
     });
-    this.#tableCodecsCache.set(key, resolved);
-    return resolved;
   }
 
   protected override transformInsertQuery(
@@ -393,7 +433,10 @@ class ColumnCodecsTransformer extends OperationNodeTransformer {
       .filter((columnName): columnName is string => Boolean(columnName));
     if (columns.length === 0) return transformed;
 
-    const tableCodecs = this.resolveTableCodecs(tableName, columns);
+    const tableCodecs = this.#resolveTableCodecs(
+      tableName,
+      Object.fromEntries(columns.map((column) => [column, null]))
+    );
 
     let didChange = false;
     const nextValueRows = transformed.values.values.map((valueNode) => {
@@ -456,9 +499,9 @@ class ColumnCodecsTransformer extends OperationNodeTransformer {
     const columnName = getColumnName(transformed.column);
     if (!columnName) return transformed;
 
-    const tableCodecs = this.resolveTableCodecs(this.#currentUpdateTable, [
-      columnName,
-    ]);
+    const tableCodecs = this.#resolveTableCodecs(this.#currentUpdateTable, {
+      [columnName]: null,
+    });
     const codec = tableCodecs[columnName];
     if (!codec) return transformed;
 
@@ -485,12 +528,16 @@ export class ColumnCodecsPlugin implements KyselyPlugin {
   readonly #dialect: ColumnCodecDialect;
   readonly #transformer: ColumnCodecsTransformer;
   readonly #resultPlans = new WeakMap<object, QueryResultPlan>();
-  readonly #codecs: ColumnCodecSource;
-  readonly #resultCodecCache = new Map<string, TableColumnCodecs>();
+  readonly #resolveTableCodecs: (
+    table: string,
+    row: Record<string, unknown>
+  ) => TableColumnCodecs;
 
   constructor(options: ColumnCodecPluginOptions) {
     this.#dialect = options.dialect ?? 'sqlite';
-    this.#codecs = options.codecs;
+    this.#resolveTableCodecs = createTableColumnCodecsResolver(options.codecs, {
+      dialect: this.#dialect,
+    });
     this.#transformer = new ColumnCodecsTransformer(options);
   }
 
@@ -499,7 +546,7 @@ export class ColumnCodecsPlugin implements KyselyPlugin {
     queryId,
   }: PluginTransformQueryArgs): RootOperationNode {
     const transformed = this.#transformer.transformNode(node);
-    const plan = buildResultPlan(transformed);
+    const plan = buildQueryResultPlan(transformed);
     if (plan) {
       this.#resultPlans.set(queryId, plan);
     }
@@ -521,65 +568,13 @@ export class ColumnCodecsPlugin implements KyselyPlugin {
     };
   }
 
-  #resolveTableCodecs(
-    table: string,
-    columns: readonly string[]
-  ): TableColumnCodecs {
-    const key = cacheKey(table, columns);
-    const cached = this.#resultCodecCache.get(key);
-    if (cached) return cached;
-    const resolved = toTableColumnCodecs(table, this.#codecs, columns, {
+  #transformRow(row: UnknownRow, plan: QueryResultPlan): UnknownRow {
+    return applyQueryResultPlan({
+      row,
+      plan,
+      resolveTableCodecs: this.#resolveTableCodecs,
       dialect: this.#dialect,
     });
-    this.#resultCodecCache.set(key, resolved);
-    return resolved;
-  }
-
-  #transformRow(row: UnknownRow, plan: QueryResultPlan): UnknownRow {
-    const source = row as Record<string, unknown>;
-    const target: Record<string, unknown> = { ...source };
-    const rowColumns = Object.keys(source);
-
-    if (plan.selectAllTables.length > 0) {
-      const codecCandidates = new Map<string, AnyColumnCodec>();
-      const ambiguousColumns = new Set<string>();
-
-      for (const table of plan.selectAllTables) {
-        const tableCodecs = this.#resolveTableCodecs(table, rowColumns);
-        for (const [column, codec] of Object.entries(tableCodecs)) {
-          if (!(column in source)) continue;
-          const existing = codecCandidates.get(column);
-          if (existing && existing !== codec) {
-            ambiguousColumns.add(column);
-            continue;
-          }
-          codecCandidates.set(column, codec);
-        }
-      }
-
-      for (const [column, codec] of codecCandidates.entries()) {
-        if (ambiguousColumns.has(column)) continue;
-        target[column] = applyCodecFromDbValue(
-          codec,
-          target[column],
-          this.#dialect
-        );
-      }
-    }
-
-    for (const ref of plan.explicit) {
-      if (!(ref.outputKey in source)) continue;
-      const tableCodecs = this.#resolveTableCodecs(ref.table, [ref.column]);
-      const codec = tableCodecs[ref.column];
-      if (!codec) continue;
-      target[ref.outputKey] = applyCodecFromDbValue(
-        codec,
-        target[ref.outputKey],
-        this.#dialect
-      );
-    }
-
-    return target;
   }
 }
 

package/src/schemas/blobs.ts

@@ -5,6 +5,7 @@
  */
 
 import { z } from 'zod';
+import type { SyncularErrorCode } from '../error-responses';
 
 // ============================================================================
 // Blob Reference Schema
@@ -72,12 +73,20 @@ export const BlobUploadCompleteResponseSchema = z.object({
   ok: z.boolean(),
   metadata: BlobMetadataSchema.optional(),
   error: z.string().optional(),
+  code: z.string().optional(),
 });
 
-export type BlobUploadCompleteResponse = z.infer<
+type BlobUploadCompleteResponseBase = z.infer<
   typeof BlobUploadCompleteResponseSchema
 >;
 
+export type BlobUploadCompleteResponse = Omit<
+  BlobUploadCompleteResponseBase,
+  'code'
+> & {
+  code?: SyncularErrorCode;
+};
+
 // ============================================================================
 // Download URL Request/Response Schemas
 // ============================================================================

package/src/schemas/common.ts

@@ -8,13 +8,57 @@ import { z } from 'zod';
 // Error Response Schemas
 // ============================================================================
 
+export const SyncularErrorCategorySchema = z.enum([
+  'auth-required',
+  'forbidden',
+  'conflict',
+  'scope-revoked',
+  'offline',
+  'invalid-request',
+  'not-found',
+  'schema-mismatch',
+  'integrity-rejected',
+  'rate-limited',
+  'limit-exceeded',
+  'transport',
+  'storage',
+  'blob',
+  'server',
+  'internal',
+]);
+
+export const SyncularErrorRecommendedActionSchema = z.enum([
+  'refreshAuth',
+  'checkPermissions',
+  'fixRequest',
+  'resetClientId',
+  'splitBatch',
+  'reduceInput',
+  'retryLater',
+  'forceResync',
+  'regenerateClient',
+  'upgradeClient',
+  'inspectStorage',
+  'inspectServer',
+  'resolveConflict',
+  'recreateClient',
+]);
+
 export const ErrorResponseSchema = z.object({
   error: z.string(),
   message: z.string().optional(),
   code: z.string().optional(),
+  category: SyncularErrorCategorySchema.optional(),
+  retryable: z.boolean().optional(),
+  recommendedAction: SyncularErrorRecommendedActionSchema.optional(),
+  details: z.record(z.string(), z.unknown()).optional(),
 });
 
 export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
+export type SyncularErrorCategory = z.infer<typeof SyncularErrorCategorySchema>;
+export type SyncularErrorRecommendedAction = z.infer<
+  typeof SyncularErrorRecommendedActionSchema
+>;
 
 // ============================================================================
 // Pagination Schemas