@korajs/sync 0.6.1 → 1.0.0-beta.1

package/dist/internal.d.cts

@@ -1,4 +1,4 @@
-import { c as SyncTransport, T as TransportOptions, a as SyncMessage, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, Q as QueueStorage } from './transport-BrdBj7rH.cjs';
+import { c as SyncTransport, T as TransportOptions, a as SyncMessage, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, Q as QueueStorage } from './transport-CZLMdZ0k.cjs';
 import { Operation } from '@korajs/core';
 
 /**

package/dist/internal.d.ts

@@ -1,4 +1,4 @@
-import { c as SyncTransport, T as TransportOptions, a as SyncMessage, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, Q as QueueStorage } from './transport-BrdBj7rH.js';
+import { c as SyncTransport, T as TransportOptions, a as SyncMessage, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, Q as QueueStorage } from './transport-CZLMdZ0k.js';
 import { Operation } from '@korajs/core';
 
 /**

package/dist/{transport-BrdBj7rH.d.cts → transport-CZLMdZ0k.d.cts}

@@ -93,7 +93,7 @@ type SyncState = (typeof SYNC_STATES)[number];
 /**
  * Developer-facing sync status. Simplified view of the internal state.
  */
-declare const SYNC_STATUSES: readonly ["connected", "syncing", "synced", "offline", "error", "schema-mismatch"];
+declare const SYNC_STATUSES: readonly ["connected", "syncing", "synced", "offline", "clock-error", "error", "schema-mismatch"];
 type SyncStatus = (typeof SYNC_STATUSES)[number];
 /**
  * Sync status information exposed to developers.
@@ -111,6 +111,8 @@ interface SyncStatusInfo {
     lastSuccessfulPull: number | null;
     /** Number of merge conflicts encountered during this session */
     conflicts: number;
+    /** serverTime - localTime in ms measured at the last handshake, or null before first connect. Negative = this device's clock is fast. */
+    clockSkewMs: number | null;
 }
 /**
  * Per-collection sync scope map. Maps collection names to field-value filters.
@@ -303,6 +305,14 @@ interface HandshakeResponseMessage {
     selectedWireFormat?: WireFormat;
     /** The server-accepted per-collection sync scope. Confirms what data will be synced. */
     acceptedScope?: Record<string, Record<string, unknown>>;
+    /** Server wall-clock time (ms since epoch) at response creation. Lets clients measure their own clock skew. */
+    serverTime?: number;
+    /**
+     * Whether the server persists blob bytes centrally. When true, a client
+     * automatically uploads the bytes behind its `blob` fields so they remain
+     * available to other devices even after the authoring device goes offline.
+     */
+    blobStorageEnabled?: boolean;
 }
 /**
  * Batch of operations sent during delta exchange or streaming.
@@ -383,10 +393,55 @@ interface YjsDocUpdateMessage {
     /** Base64-encoded Yjs update binary */
     update: string;
 }
+/**
+ * Request for a single blob chunk by content hash. Ephemeral side channel for
+ * out-of-band blob transfer over the sync connection; never persisted in the
+ * operation log (durable state is the BlobRef inside a record's fields).
+ *
+ * Possession of a chunk hash is itself the capability to request it: hashes are
+ * only learned from BlobRefs inside records the peer already received through
+ * its (scope-filtered) sync, and SHA-256 preimage resistance makes guessing a
+ * hash infeasible. The server therefore relays chunk requests among peers
+ * without a separate ACL.
+ */
+interface BlobChunkRequestMessage {
+    type: 'blob-chunk-request';
+    messageId: string;
+    /** Correlates the response to this request. */
+    requestId: string;
+    /** SHA-256 hash of the requested chunk. */
+    hash: string;
+}
+/**
+ * Response to a {@link BlobChunkRequestMessage}. Carries the chunk bytes, or
+ * null when the responder does not hold that hash.
+ */
+interface BlobChunkResponseMessage {
+    type: 'blob-chunk-response';
+    messageId: string;
+    /** Echoes the request's `requestId` for correlation. */
+    requestId: string;
+    /** Base64-encoded chunk bytes, or null when the responder does not hold the hash. */
+    bytes: string | null;
+}
+/**
+ * Unsolicited upload of a blob chunk (or a blob manifest) from a client to the
+ * server, so the server can persist it centrally and serve it to other devices
+ * even after the authoring device disconnects. Content-addressed: the receiver
+ * verifies the bytes hash to `hash`.
+ */
+interface BlobChunkPushMessage {
+    type: 'blob-chunk-push';
+    messageId: string;
+    /** SHA-256 hash of the pushed bytes (a chunk hash or a manifest hash). */
+    hash: string;
+    /** Base64-encoded bytes. */
+    bytes: string;
+}
 /**
  * Union of all sync protocol messages.
  */
-type SyncMessage = HandshakeMessage | HandshakeResponseMessage | OperationBatchMessage | AcknowledgmentMessage | ErrorMessage | AwarenessUpdateMessage | YjsDocUpdateMessage;
+type SyncMessage = HandshakeMessage | HandshakeResponseMessage | OperationBatchMessage | AcknowledgmentMessage | ErrorMessage | AwarenessUpdateMessage | YjsDocUpdateMessage | BlobChunkRequestMessage | BlobChunkResponseMessage | BlobChunkPushMessage;
 /**
  * Check if an unknown value is a valid SyncMessage.
  */
@@ -419,6 +474,18 @@ declare function isAwarenessUpdateMessage(value: unknown): value is AwarenessUpd
  * Check if a value is a YjsDocUpdateMessage.
  */
 declare function isYjsDocUpdateMessage(value: unknown): value is YjsDocUpdateMessage;
+/**
+ * Check if a value is a BlobChunkRequestMessage.
+ */
+declare function isBlobChunkRequestMessage(value: unknown): value is BlobChunkRequestMessage;
+/**
+ * Check if a value is a BlobChunkResponseMessage.
+ */
+declare function isBlobChunkResponseMessage(value: unknown): value is BlobChunkResponseMessage;
+/**
+ * Check if a value is a BlobChunkPushMessage.
+ */
+declare function isBlobChunkPushMessage(value: unknown): value is BlobChunkPushMessage;
 
 /**
  * Options for transport connection.
@@ -462,4 +529,4 @@ interface SyncTransport {
     isConnected(): boolean;
 }
 
-export { type AcknowledgmentMessage as A, isHandshakeMessage as B, isHandshakeResponseMessage as C, type DeltaCursor as D, type EncryptedPayload as E, isOperationBatchMessage as F, isSyncMessage as G, type HandshakeMessage as H, InvalidScopeError as I, isYjsDocUpdateMessage as J, operationMatchesQuerySubsets as K, type OperationBatchMessage as O, type QueueStorage as Q, type SyncScopeMap as S, type TransportOptions as T, type VersionedKey as V, type WireFormat as W, type YjsDocUpdateMessage as Y, type SyncMessage as a, type SerializedOperation as b, type SyncTransport as c, type TransportMessageHandler as d, type TransportCloseHandler as e, type TransportErrorHandler as f, type SyncEncryptionConfig as g, type SyncState as h, type SyncStatusInfo as i, type SyncConfig as j, type SyncStatePersistence as k, type SyncQuerySubset as l, type AwarenessStateWire as m, type AwarenessUpdateMessage as n, type ErrorMessage as o, type HandshakeResponseMessage as p, SYNC_STATES as q, SYNC_STATUSES as r, ScopeViolationError as s, type SyncEncryptionAlgorithm as t, type SyncScopeContext as u, type SyncStatus as v, dedupeQuerySubsets as w, isAcknowledgmentMessage as x, isAwarenessUpdateMessage as y, isErrorMessage as z };
+export { type AcknowledgmentMessage as A, type BlobChunkRequestMessage as B, isAwarenessUpdateMessage as C, type DeltaCursor as D, type EncryptedPayload as E, isBlobChunkPushMessage as F, isBlobChunkRequestMessage as G, type HandshakeMessage as H, InvalidScopeError as I, isBlobChunkResponseMessage as J, isErrorMessage as K, isHandshakeMessage as L, isHandshakeResponseMessage as M, isOperationBatchMessage as N, type OperationBatchMessage as O, isSyncMessage as P, type QueueStorage as Q, isYjsDocUpdateMessage as R, type SyncScopeMap as S, type TransportOptions as T, operationMatchesQuerySubsets as U, type VersionedKey as V, type WireFormat as W, type YjsDocUpdateMessage as Y, type SyncMessage as a, type SerializedOperation as b, type SyncTransport as c, type TransportMessageHandler as d, type TransportCloseHandler as e, type TransportErrorHandler as f, type BlobChunkResponseMessage as g, type BlobChunkPushMessage as h, type SyncEncryptionConfig as i, type SyncState as j, type SyncStatusInfo as k, type SyncConfig as l, type SyncStatePersistence as m, type SyncQuerySubset as n, type AwarenessStateWire as o, type AwarenessUpdateMessage as p, type ErrorMessage as q, type HandshakeResponseMessage as r, SYNC_STATES as s, SYNC_STATUSES as t, ScopeViolationError as u, type SyncEncryptionAlgorithm as v, type SyncScopeContext as w, type SyncStatus as x, dedupeQuerySubsets as y, isAcknowledgmentMessage as z };

package/dist/{transport-BrdBj7rH.d.ts → transport-CZLMdZ0k.d.ts}

@@ -93,7 +93,7 @@ type SyncState = (typeof SYNC_STATES)[number];
 /**
  * Developer-facing sync status. Simplified view of the internal state.
  */
-declare const SYNC_STATUSES: readonly ["connected", "syncing", "synced", "offline", "error", "schema-mismatch"];
+declare const SYNC_STATUSES: readonly ["connected", "syncing", "synced", "offline", "clock-error", "error", "schema-mismatch"];
 type SyncStatus = (typeof SYNC_STATUSES)[number];
 /**
  * Sync status information exposed to developers.
@@ -111,6 +111,8 @@ interface SyncStatusInfo {
     lastSuccessfulPull: number | null;
     /** Number of merge conflicts encountered during this session */
     conflicts: number;
+    /** serverTime - localTime in ms measured at the last handshake, or null before first connect. Negative = this device's clock is fast. */
+    clockSkewMs: number | null;
 }
 /**
  * Per-collection sync scope map. Maps collection names to field-value filters.
@@ -303,6 +305,14 @@ interface HandshakeResponseMessage {
     selectedWireFormat?: WireFormat;
     /** The server-accepted per-collection sync scope. Confirms what data will be synced. */
     acceptedScope?: Record<string, Record<string, unknown>>;
+    /** Server wall-clock time (ms since epoch) at response creation. Lets clients measure their own clock skew. */
+    serverTime?: number;
+    /**
+     * Whether the server persists blob bytes centrally. When true, a client
+     * automatically uploads the bytes behind its `blob` fields so they remain
+     * available to other devices even after the authoring device goes offline.
+     */
+    blobStorageEnabled?: boolean;
 }
 /**
  * Batch of operations sent during delta exchange or streaming.
@@ -383,10 +393,55 @@ interface YjsDocUpdateMessage {
     /** Base64-encoded Yjs update binary */
     update: string;
 }
+/**
+ * Request for a single blob chunk by content hash. Ephemeral side channel for
+ * out-of-band blob transfer over the sync connection; never persisted in the
+ * operation log (durable state is the BlobRef inside a record's fields).
+ *
+ * Possession of a chunk hash is itself the capability to request it: hashes are
+ * only learned from BlobRefs inside records the peer already received through
+ * its (scope-filtered) sync, and SHA-256 preimage resistance makes guessing a
+ * hash infeasible. The server therefore relays chunk requests among peers
+ * without a separate ACL.
+ */
+interface BlobChunkRequestMessage {
+    type: 'blob-chunk-request';
+    messageId: string;
+    /** Correlates the response to this request. */
+    requestId: string;
+    /** SHA-256 hash of the requested chunk. */
+    hash: string;
+}
+/**
+ * Response to a {@link BlobChunkRequestMessage}. Carries the chunk bytes, or
+ * null when the responder does not hold that hash.
+ */
+interface BlobChunkResponseMessage {
+    type: 'blob-chunk-response';
+    messageId: string;
+    /** Echoes the request's `requestId` for correlation. */
+    requestId: string;
+    /** Base64-encoded chunk bytes, or null when the responder does not hold the hash. */
+    bytes: string | null;
+}
+/**
+ * Unsolicited upload of a blob chunk (or a blob manifest) from a client to the
+ * server, so the server can persist it centrally and serve it to other devices
+ * even after the authoring device disconnects. Content-addressed: the receiver
+ * verifies the bytes hash to `hash`.
+ */
+interface BlobChunkPushMessage {
+    type: 'blob-chunk-push';
+    messageId: string;
+    /** SHA-256 hash of the pushed bytes (a chunk hash or a manifest hash). */
+    hash: string;
+    /** Base64-encoded bytes. */
+    bytes: string;
+}
 /**
  * Union of all sync protocol messages.
  */
-type SyncMessage = HandshakeMessage | HandshakeResponseMessage | OperationBatchMessage | AcknowledgmentMessage | ErrorMessage | AwarenessUpdateMessage | YjsDocUpdateMessage;
+type SyncMessage = HandshakeMessage | HandshakeResponseMessage | OperationBatchMessage | AcknowledgmentMessage | ErrorMessage | AwarenessUpdateMessage | YjsDocUpdateMessage | BlobChunkRequestMessage | BlobChunkResponseMessage | BlobChunkPushMessage;
 /**
  * Check if an unknown value is a valid SyncMessage.
  */
@@ -419,6 +474,18 @@ declare function isAwarenessUpdateMessage(value: unknown): value is AwarenessUpd
  * Check if a value is a YjsDocUpdateMessage.
  */
 declare function isYjsDocUpdateMessage(value: unknown): value is YjsDocUpdateMessage;
+/**
+ * Check if a value is a BlobChunkRequestMessage.
+ */
+declare function isBlobChunkRequestMessage(value: unknown): value is BlobChunkRequestMessage;
+/**
+ * Check if a value is a BlobChunkResponseMessage.
+ */
+declare function isBlobChunkResponseMessage(value: unknown): value is BlobChunkResponseMessage;
+/**
+ * Check if a value is a BlobChunkPushMessage.
+ */
+declare function isBlobChunkPushMessage(value: unknown): value is BlobChunkPushMessage;
 
 /**
  * Options for transport connection.
@@ -462,4 +529,4 @@ interface SyncTransport {
     isConnected(): boolean;
 }
 
-export { type AcknowledgmentMessage as A, isHandshakeMessage as B, isHandshakeResponseMessage as C, type DeltaCursor as D, type EncryptedPayload as E, isOperationBatchMessage as F, isSyncMessage as G, type HandshakeMessage as H, InvalidScopeError as I, isYjsDocUpdateMessage as J, operationMatchesQuerySubsets as K, type OperationBatchMessage as O, type QueueStorage as Q, type SyncScopeMap as S, type TransportOptions as T, type VersionedKey as V, type WireFormat as W, type YjsDocUpdateMessage as Y, type SyncMessage as a, type SerializedOperation as b, type SyncTransport as c, type TransportMessageHandler as d, type TransportCloseHandler as e, type TransportErrorHandler as f, type SyncEncryptionConfig as g, type SyncState as h, type SyncStatusInfo as i, type SyncConfig as j, type SyncStatePersistence as k, type SyncQuerySubset as l, type AwarenessStateWire as m, type AwarenessUpdateMessage as n, type ErrorMessage as o, type HandshakeResponseMessage as p, SYNC_STATES as q, SYNC_STATUSES as r, ScopeViolationError as s, type SyncEncryptionAlgorithm as t, type SyncScopeContext as u, type SyncStatus as v, dedupeQuerySubsets as w, isAcknowledgmentMessage as x, isAwarenessUpdateMessage as y, isErrorMessage as z };
+export { type AcknowledgmentMessage as A, type BlobChunkRequestMessage as B, isAwarenessUpdateMessage as C, type DeltaCursor as D, type EncryptedPayload as E, isBlobChunkPushMessage as F, isBlobChunkRequestMessage as G, type HandshakeMessage as H, InvalidScopeError as I, isBlobChunkResponseMessage as J, isErrorMessage as K, isHandshakeMessage as L, isHandshakeResponseMessage as M, isOperationBatchMessage as N, type OperationBatchMessage as O, isSyncMessage as P, type QueueStorage as Q, isYjsDocUpdateMessage as R, type SyncScopeMap as S, type TransportOptions as T, operationMatchesQuerySubsets as U, type VersionedKey as V, type WireFormat as W, type YjsDocUpdateMessage as Y, type SyncMessage as a, type SerializedOperation as b, type SyncTransport as c, type TransportMessageHandler as d, type TransportCloseHandler as e, type TransportErrorHandler as f, type BlobChunkResponseMessage as g, type BlobChunkPushMessage as h, type SyncEncryptionConfig as i, type SyncState as j, type SyncStatusInfo as k, type SyncConfig as l, type SyncStatePersistence as m, type SyncQuerySubset as n, type AwarenessStateWire as o, type AwarenessUpdateMessage as p, type ErrorMessage as q, type HandshakeResponseMessage as r, SYNC_STATES as s, SYNC_STATUSES as t, ScopeViolationError as u, type SyncEncryptionAlgorithm as v, type SyncScopeContext as w, type SyncStatus as x, dedupeQuerySubsets as y, isAcknowledgmentMessage as z };

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@korajs/sync",
-  "version": "0.6.1",
+  "version": "1.0.0-beta.1",
   "description": "Sync protocol and transports for Kora.js with delta sync, causal ordering, and automatic reconnection",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
+    "./package.json": "./package.json",
     ".": {
       "import": {
         "types": "./dist/index.d.ts",
@@ -33,8 +34,8 @@
   ],
   "dependencies": {
     "protobufjs": "^8.0.1",
-    "@korajs/merge": "0.6.0",
-    "@korajs/core": "0.6.0"
+    "@korajs/core": "1.0.0-beta.1",
+    "@korajs/merge": "1.0.0-beta.1"
   },
   "devDependencies": {
     "@fast-check/vitest": "0.2.0",