@syncular/client 0.30.5 → 0.30.6

package/dist/errors.d.ts

@@ -20,7 +20,8 @@ export declare class ClientSyncError extends Error {
     readonly name: string;
     readonly code: string;
     readonly retryable: boolean;
-    constructor(code: string, message: string, retryable?: boolean);
+    readonly details: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: string, message: string, retryable?: boolean, details?: Readonly<Record<string, unknown>>);
 }
 /**
  * SPEC §7.5: the latest sync attempt failed while a live query still waited

package/dist/errors.js

@@ -19,10 +19,12 @@ export class ClientSyncError extends Error {
     name = 'ClientSyncError';
     code;
     retryable;
-    constructor(code, message, retryable = false) {
+    details;
+    constructor(code, message, retryable = false, details) {
         super(message);
         this.code = code;
         this.retryable = retryable;
+        this.details = details;
     }
 }
 /**

package/dist/http.js

@@ -1,8 +1,8 @@
 import { SSP2_CONTENT_TYPE } from './content-type.js';
 import { ClientSyncError } from './errors.js';
-async function throwHttpError(response) {
+async function throwHttpError(response, details) {
     let code = 'sync.transport_failed';
-    let message = `HTTP ${response.status}`;
+    let message = 'HTTP request failed';
     let retryable = response.status >= 500 || response.status === 429;
     try {
         const body = (await response.json());
@@ -16,7 +16,10 @@ async function throwHttpError(response) {
     catch {
         // non-JSON error body — keep the HTTP-status defaults
     }
-    throw new ClientSyncError(code, message, retryable);
+    throw new ClientSyncError(code, message, retryable, {
+        ...details,
+        httpStatus: response.status,
+    });
 }
 function hostHeaders(options) {
     const headers = options?.headers;
@@ -136,25 +139,39 @@ async function readSegmentBody(response, onProgress) {
 }
 export function httpSegmentDownloader(segmentsBaseUrl, options) {
     const doFetch = options?.fetch ?? fetch;
-    const direct = async (request) => {
-        const response = await doFetch(`${segmentsBaseUrl}/${encodeURIComponent(request.segmentId)}`, {
-            headers: {
-                'X-Syncular-Scopes': request.requestedScopesJson,
-                ...hostHeaders(options),
-            },
-        });
-        if (!response.ok)
-            await throwHttpError(response);
-        return readSegmentBody(response, request.onProgress);
-    };
-    const fetchUrl = async (url, onProgress) => {
-        // Deliberately headerless: the URL is the bearer grant (§5.4).
-        const response = await doFetch(url);
-        if (!response.ok) {
-            throw new ClientSyncError('sync.transport_failed', `signed-URL fetch failed with HTTP ${response.status} (§5.4: descriptor invalidated, re-pull to recover)`, true);
+    const download = async (url, init, onProgress, signed = false) => {
+        // A capability's query/fragment and URL credentials never enter details.
+        const path = URL.canParse(url)
+            ? new URL(url).pathname
+            : url.split(/[?#]/)[0];
+        let response;
+        try {
+            response = await doFetch(url, init);
+            if (!response.ok) {
+                if (!signed)
+                    await throwHttpError(response, { path });
+                throw new ClientSyncError('sync.transport_failed', 'signed segment request failed; invalidate the descriptor and re-pull', true, { path, httpStatus: response.status });
+            }
+            return await readSegmentBody(response, onProgress);
+        }
+        catch (error) {
+            if (error instanceof ClientSyncError)
+                throw error;
+            throw new ClientSyncError('sync.transport_failed', 'segment transfer failed', true, {
+                path,
+                ...(response !== undefined ? { httpStatus: response.status } : {}),
+                causeMessage: error instanceof Error ? error.message : String(error),
+            });
         }
-        return readSegmentBody(response, onProgress);
     };
+    const direct = (request) => download(`${segmentsBaseUrl}/${encodeURIComponent(request.segmentId)}`, {
+        headers: {
+            'X-Syncular-Scopes': request.requestedScopesJson,
+            ...hostHeaders(options),
+        },
+    }, request.onProgress);
+    // Deliberately headerless: the URL is the bearer grant (§5.4).
+    const fetchUrl = (url, onProgress) => download(url, undefined, onProgress, true);
     return Object.assign(direct, { fetchUrl });
 }
 /**

package/dist/multi-tab.d.ts

@@ -86,6 +86,7 @@ interface ResMessage {
         code: string;
         message: string;
         retryable: boolean;
+        details?: Readonly<Record<string, unknown>>;
     };
 }
 interface EventMessage {

package/dist/multi-tab.js

@@ -206,6 +206,9 @@ export class LeaderBridge {
                     code: error.code,
                     message: error.message,
                     retryable: error.retryable,
+                    ...(error.details !== undefined
+                        ? { details: error.details }
+                        : {}),
                 }
                 : {
                     code: WORKER_FAILED_CODE,
@@ -470,7 +473,7 @@ export class FollowerLink {
             }
             else {
                 const err = message.error;
-                inflight.reject(new ClientSyncError(err?.code ?? WORKER_FAILED_CODE, err?.message ?? 'follower request failed', err?.retryable ?? false));
+                inflight.reject(new ClientSyncError(err?.code ?? WORKER_FAILED_CODE, err?.message ?? 'follower request failed', err?.retryable ?? false, err?.details));
             }
             return;
         }

package/dist/reactive-store.js

@@ -246,6 +246,13 @@ class ObservationCache {
 }
 const EMPTY_ROWS = Object.freeze([]);
 const unreadQuerySnapshots = new Map();
+/** Schema floors stop network transfer; the retained local replica remains readable.
+ * Leadership stops still refuse local access through the unavailable owner. */
+function localReadsBlocked(availability) {
+    return (availability.state === 'blocked' &&
+        (availability.reason === 'leader-unreachable' ||
+            availability.reason === 'leader-incompatible'));
+}
 /** One frozen snapshot per phase and availability for entries that have no
  * successful read, so switching between unread entries keeps the snapshot and
  * `rows` identity. */
@@ -458,7 +465,7 @@ class QueryEntry {
     }
     #onAvailabilityChange() {
         const availability = this.store.availabilitySnapshot();
-        if (availability.state === 'blocked') {
+        if (localReadsBlocked(availability)) {
             this.#publish({
                 ...this.#state,
                 phase: 'blocked',
@@ -512,7 +519,7 @@ class QueryEntry {
         try {
             do {
                 this.#requested = false;
-                if (this.store.availabilitySnapshot().state === 'blocked')
+                if (localReadsBlocked(this.store.availabilitySnapshot()))
                     break;
                 if (generation !== this.#generation || this.#listeners.size === 0)
                     return;
@@ -537,7 +544,7 @@ class QueryEntry {
                 if (this.#claimError !== undefined)
                     throw this.#claimError;
                 const availability = this.store.availabilitySnapshot();
-                if (availability.state === 'blocked') {
+                if (localReadsBlocked(availability)) {
                     this.#publish({
                         ...this.#state,
                         phase: 'blocked',

package/dist/worker-entry.js

@@ -26,6 +26,7 @@ function toErrorShape(error) {
             code: error.code,
             message: error.message,
             retryable: error.retryable,
+            ...(error.details !== undefined ? { details: error.details } : {}),
         };
     }
     return {

package/dist/worker-host.js

@@ -466,7 +466,7 @@ async function startWorkerCore(options) {
                 case 'error': {
                     const entry = pending.get(message.id);
                     pending.delete(message.id);
-                    entry?.reject(new ClientSyncError(message.error.code, message.error.message, message.error.retryable));
+                    entry?.reject(new ClientSyncError(message.error.code, message.error.message, message.error.retryable, message.error.details));
                     break;
                 }
                 case 'event':

package/dist/worker-protocol.d.ts

@@ -175,6 +175,7 @@ export type MainToWorkerMessage = {
     readonly config: WorkerInitConfig;
 } | WorkerCallMessage;
 export interface WorkerErrorShape {
+    readonly details?: Readonly<Record<string, unknown>>;
     readonly code: string;
     readonly message: string;
     readonly retryable: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.30.5",
+  "version": "0.30.6",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -89,10 +89,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.30.5"
+    "@syncular/core": "0.30.6"
   },
   "devDependencies": {
-    "@syncular/server": "0.30.5",
+    "@syncular/server": "0.30.6",
     "playwright": "1.63.0"
   }
 }

package/src/errors.ts

@@ -27,11 +27,18 @@ export class ClientSyncError extends Error {
   override readonly name: string = 'ClientSyncError';
   readonly code: string;
   readonly retryable: boolean;
+  readonly details: Readonly<Record<string, unknown>> | undefined;
 
-  constructor(code: string, message: string, retryable = false) {
+  constructor(
+    code: string,
+    message: string,
+    retryable = false,
+    details?: Readonly<Record<string, unknown>>,
+  ) {
     super(message);
     this.code = code;
     this.retryable = retryable;
+    this.details = details;
   }
 }
 

package/src/http.ts

@@ -15,9 +15,12 @@ import type {
   SyncTransport,
 } from './transport';
 
-async function throwHttpError(response: Response): Promise<never> {
+async function throwHttpError(
+  response: Response,
+  details?: Readonly<Record<string, unknown>>,
+): Promise<never> {
   let code = 'sync.transport_failed';
-  let message = `HTTP ${response.status}`;
+  let message = 'HTTP request failed';
   let retryable = response.status >= 500 || response.status === 429;
   try {
     const body = (await response.json()) as {
@@ -31,7 +34,10 @@ async function throwHttpError(response: Response): Promise<never> {
   } catch {
     // non-JSON error body — keep the HTTP-status defaults
   }
-  throw new ClientSyncError(code, message, retryable);
+  throw new ClientSyncError(code, message, retryable, {
+    ...details,
+    httpStatus: response.status,
+  });
 }
 
 export interface HttpTransportOptions {
@@ -192,12 +198,49 @@ export function httpSegmentDownloader(
   options?: HttpTransportOptions,
 ): SegmentDownloader {
   const doFetch = options?.fetch ?? fetch;
-  const direct = async (request: {
+  const download = async (
+    url: string,
+    init?: RequestInit,
+    onProgress?: (bytesReceived: number) => void,
+    signed = false,
+  ) => {
+    // A capability's query/fragment and URL credentials never enter details.
+    const path = URL.canParse(url)
+      ? new URL(url).pathname
+      : url.split(/[?#]/)[0];
+    let response: Response | undefined;
+    try {
+      response = await doFetch(url, init);
+      if (!response.ok) {
+        if (!signed) await throwHttpError(response, { path });
+        throw new ClientSyncError(
+          'sync.transport_failed',
+          'signed segment request failed; invalidate the descriptor and re-pull',
+          true,
+          { path, httpStatus: response.status },
+        );
+      }
+      return await readSegmentBody(response, onProgress);
+    } catch (error) {
+      if (error instanceof ClientSyncError) throw error;
+      throw new ClientSyncError(
+        'sync.transport_failed',
+        'segment transfer failed',
+        true,
+        {
+          path,
+          ...(response !== undefined ? { httpStatus: response.status } : {}),
+          causeMessage: error instanceof Error ? error.message : String(error),
+        },
+      );
+    }
+  };
+  const direct = (request: {
     readonly segmentId: string;
     readonly requestedScopesJson: string;
     readonly onProgress?: (bytesReceived: number) => void;
-  }) => {
-    const response = await doFetch(
+  }) =>
+    download(
       `${segmentsBaseUrl}/${encodeURIComponent(request.segmentId)}`,
       {
         headers: {
@@ -205,25 +248,13 @@ export function httpSegmentDownloader(
           ...hostHeaders(options),
         },
       },
+      request.onProgress,
     );
-    if (!response.ok) await throwHttpError(response);
-    return readSegmentBody(response, request.onProgress);
-  };
-  const fetchUrl = async (
+  // Deliberately headerless: the URL is the bearer grant (§5.4).
+  const fetchUrl = (
     url: string,
     onProgress?: (bytesReceived: number) => void,
-  ) => {
-    // Deliberately headerless: the URL is the bearer grant (§5.4).
-    const response = await doFetch(url);
-    if (!response.ok) {
-      throw new ClientSyncError(
-        'sync.transport_failed',
-        `signed-URL fetch failed with HTTP ${response.status} (§5.4: descriptor invalidated, re-pull to recover)`,
-        true,
-      );
-    }
-    return readSegmentBody(response, onProgress);
-  };
+  ) => download(url, undefined, onProgress, true);
   return Object.assign(direct, { fetchUrl });
 }
 

package/src/multi-tab.ts

@@ -171,7 +171,12 @@ interface ResMessage {
   readonly reqId: number;
   readonly ok: boolean;
   readonly value?: unknown;
-  readonly error?: { code: string; message: string; retryable: boolean };
+  readonly error?: {
+    code: string;
+    message: string;
+    retryable: boolean;
+    details?: Readonly<Record<string, unknown>>;
+  };
 }
 
 interface EventMessage {
@@ -336,6 +341,9 @@ export class LeaderBridge {
                 code: error.code,
                 message: error.message,
                 retryable: error.retryable,
+                ...(error.details !== undefined
+                  ? { details: error.details }
+                  : {}),
               }
             : {
                 code: WORKER_FAILED_CODE,
@@ -682,6 +690,7 @@ export class FollowerLink {
             err?.code ?? WORKER_FAILED_CODE,
             err?.message ?? 'follower request failed',
             err?.retryable ?? false,
+            err?.details,
           ),
         );
       }

package/src/reactive-store.ts

@@ -371,6 +371,16 @@ class ObservationCache {
 const EMPTY_ROWS: readonly never[] = Object.freeze([]);
 const unreadQuerySnapshots = new Map<string, LiveQueryResult<never>>();
 
+/** Schema floors stop network transfer; the retained local replica remains readable.
+ * Leadership stops still refuse local access through the unavailable owner. */
+function localReadsBlocked(availability: SyncAvailability): boolean {
+  return (
+    availability.state === 'blocked' &&
+    (availability.reason === 'leader-unreachable' ||
+      availability.reason === 'leader-incompatible')
+  );
+}
+
 /** One frozen snapshot per phase and availability for entries that have no
  * successful read, so switching between unread entries keeps the snapshot and
  * `rows` identity. */
@@ -598,7 +608,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
 
   #onAvailabilityChange(): void {
     const availability = this.store.availabilitySnapshot();
-    if (availability.state === 'blocked') {
+    if (localReadsBlocked(availability)) {
       this.#publish({
         ...this.#state,
         phase: 'blocked',
@@ -654,7 +664,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
     try {
       do {
         this.#requested = false;
-        if (this.store.availabilitySnapshot().state === 'blocked') break;
+        if (localReadsBlocked(this.store.availabilitySnapshot())) break;
 
         if (generation !== this.#generation || this.#listeners.size === 0)
           return;
@@ -681,7 +691,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
           return;
         if (this.#claimError !== undefined) throw this.#claimError;
         const availability = this.store.availabilitySnapshot();
-        if (availability.state === 'blocked') {
+        if (localReadsBlocked(availability)) {
           this.#publish({
             ...this.#state,
             phase: 'blocked',

package/src/worker-entry.ts

@@ -83,6 +83,7 @@ function toErrorShape(error: unknown): WorkerErrorShape {
       code: error.code,
       message: error.message,
       retryable: error.retryable,
+      ...(error.details !== undefined ? { details: error.details } : {}),
     };
   }
   return {

package/src/worker-host.ts

@@ -843,6 +843,7 @@ async function startWorkerCore(options: {
               message.error.code,
               message.error.message,
               message.error.retryable,
+              message.error.details,
             ),
           );
           break;

package/src/worker-protocol.ts

@@ -233,6 +233,7 @@ export type MainToWorkerMessage =
   | WorkerCallMessage;
 
 export interface WorkerErrorShape {
+  readonly details?: Readonly<Record<string, unknown>>;
   readonly code: string;
   readonly message: string;
   readonly retryable: boolean;