@syncular/transport-http 0.0.1 → 0.0.2-127

package/README.md

@@ -0,0 +1,32 @@
+# @syncular/transport-http
+
+HTTP transport for Syncular using a typed OpenAPI client. Used by `@syncular/client` to push and pull commits, and to upload/download blobs.
+
+## Install
+
+```bash
+npm install @syncular/transport-http
+```
+
+## Usage
+
+```ts
+import { createHttpTransport } from '@syncular/transport-http';
+
+const transport = createHttpTransport({
+  baseUrl: 'https://api.example.com',
+  getHeaders: () => ({ Authorization: `Bearer ${token}` }),
+});
+```
+
+## Documentation
+
+- How sync works (push/pull): https://syncular.dev/docs/introduction/architecture
+- API reference: https://syncular.dev/docs/api/postSync
+
+## Links
+
+- GitHub: https://github.com/syncular/syncular
+- Issues: https://github.com/syncular/syncular/issues
+
+> Status: Alpha. APIs and storage layouts may change between releases.

package/dist/generated/api.d.ts

@@ -3,7 +3,7 @@
  * Do not make direct changes to the file.
  */
 export interface paths {
-    "/sync/pull": {
+    "/sync": {
         parameters: {
             query?: never;
             header?: never;
@@ -13,10 +13,10 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * Pull commits and snapshots
-         * @description Pull commits and optional bootstrap snapshots for subscriptions
+         * Combined push and pull
+         * @description Perform push and/or pull in a single request to reduce round-trips
          */
-        post: operations["postSyncPull"];
+        post: operations["postSync"];
         delete?: never;
         options?: never;
         head?: never;
@@ -43,26 +43,6 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/sync/push": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Push a commit
-         * @description Push a client commit with operations to the server
-         */
-        post: operations["postSyncPush"];
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/console/stats": {
         parameters: {
             query?: never;
@@ -233,6 +213,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/console/notify-data-change": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Notify external data change
+         * @description Creates a synthetic commit to force re-bootstrap for affected tables. Use after pipeline imports or direct DB writes to notify connected clients.
+         */
+        post: operations["postConsoleNotifyDataChange"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/console/clients/{id}": {
         parameters: {
             query?: never;
@@ -427,7 +427,7 @@ export interface components {
 }
 export type $defs = Record<string, never>;
 export interface operations {
-    postSyncPull: {
+    postSync: {
         parameters: {
             query?: never;
             header?: never;
@@ -438,32 +438,48 @@ export interface operations {
             content: {
                 "application/json": {
                     clientId: string;
-                    limitCommits: number;
-                    limitSnapshotRows?: number;
-                    maxSnapshotPages?: number;
-                    dedupeRows?: boolean;
-                    subscriptions: {
-                        id: string;
-                        shape: string;
-                        scopes: {
-                            [key: string]: string | string[];
-                        };
-                        params?: {
-                            [key: string]: unknown;
-                        };
-                        cursor: number;
-                        bootstrapState?: {
-                            asOfCommitSeq: number;
-                            tables: string[];
-                            tableIndex: number;
-                            rowCursor: string | null;
-                        } | null;
-                    }[];
+                    push?: {
+                        clientCommitId: string;
+                        operations: {
+                            table: string;
+                            row_id: string;
+                            /** @enum {string} */
+                            op: "upsert" | "delete";
+                            payload: {
+                                [key: string]: unknown;
+                            } | null;
+                            base_version?: number | null;
+                        }[];
+                        schemaVersion: number;
+                    };
+                    pull?: {
+                        limitCommits: number;
+                        limitSnapshotRows?: number;
+                        maxSnapshotPages?: number;
+                        dedupeRows?: boolean;
+                        subscriptions: {
+                            id: string;
+                            table: string;
+                            scopes: {
+                                [key: string]: string | string[];
+                            };
+                            params?: {
+                                [key: string]: unknown;
+                            };
+                            cursor: number;
+                            bootstrapState?: {
+                                asOfCommitSeq: number;
+                                tables: string[];
+                                tableIndex: number;
+                                rowCursor: string | null;
+                            } | null;
+                        }[];
+                    };
                 };
             };
         };
         responses: {
-            /** @description Successful pull response */
+            /** @description Combined sync response */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -472,53 +488,83 @@ export interface operations {
                     "application/json": {
                         /** @constant */
                         ok: true;
-                        subscriptions: {
-                            id: string;
+                        push?: {
+                            /** @constant */
+                            ok: true;
                             /** @enum {string} */
-                            status: "active" | "revoked";
-                            scopes: {
-                                [key: string]: string | string[];
-                            };
-                            bootstrap: boolean;
-                            bootstrapState?: {
-                                asOfCommitSeq: number;
-                                tables: string[];
-                                tableIndex: number;
-                                rowCursor: string | null;
-                            } | null;
-                            nextCursor: number;
-                            commits: {
-                                commitSeq: number;
-                                createdAt: string;
-                                actorId: string;
-                                changes: {
-                                    table: string;
-                                    row_id: string;
-                                    /** @enum {string} */
-                                    op: "upsert" | "delete";
-                                    row_json: unknown | null;
-                                    row_version: number | null;
-                                    scopes: {
-                                        [key: string]: string;
-                                    };
+                            status: "applied" | "cached" | "rejected";
+                            commitSeq?: number;
+                            results: ({
+                                opIndex: number;
+                                /** @constant */
+                                status: "applied";
+                            } | {
+                                opIndex: number;
+                                /** @constant */
+                                status: "conflict";
+                                message: string;
+                                server_version: number;
+                                server_row: unknown;
+                            } | {
+                                opIndex: number;
+                                /** @constant */
+                                status: "error";
+                                error: string;
+                                code?: string;
+                                retriable?: boolean;
+                            })[];
+                        };
+                        pull?: {
+                            /** @constant */
+                            ok: true;
+                            subscriptions: {
+                                id: string;
+                                /** @enum {string} */
+                                status: "active" | "revoked";
+                                scopes: {
+                                    [key: string]: string | string[];
+                                };
+                                bootstrap: boolean;
+                                bootstrapState?: {
+                                    asOfCommitSeq: number;
+                                    tables: string[];
+                                    tableIndex: number;
+                                    rowCursor: string | null;
+                                } | null;
+                                nextCursor: number;
+                                commits: {
+                                    commitSeq: number;
+                                    createdAt: string;
+                                    actorId: string;
+                                    changes: {
+                                        table: string;
+                                        row_id: string;
+                                        /** @enum {string} */
+                                        op: "upsert" | "delete";
+                                        row_json: unknown | null;
+                                        row_version: number | null;
+                                        scopes: {
+                                            [key: string]: string;
+                                        };
+                                    }[];
                                 }[];
-                            }[];
-                            snapshots?: {
-                                table: string;
-                                rows: unknown[];
-                                chunks?: {
-                                    id: string;
-                                    byteLength: number;
-                                    sha256: string;
-                                    /** @constant */
-                                    encoding: "ndjson";
-                                    /** @constant */
-                                    compression: "gzip";
+                                snapshots?: {
+                                    table: string;
+                                    rows: unknown[];
+                                    chunks?: {
+                                        id: string;
+                                        byteLength: number;
+                                        sha256: string;
+                                        /** @constant */
+                                        encoding: "json-row-frame-v1";
+                                        /** @constant */
+                                        compression: "gzip";
+                                    }[];
+                                    isFirstPage: boolean;
+                                    isLastPage: boolean;
                                 }[];
-                                isFirstPage: boolean;
-                                isLastPage: boolean;
                             }[];
-                        }[];
+                        };
                     };
                 };
             };
@@ -561,12 +607,14 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Snapshot chunk data (gzip-compressed NDJSON) */
+            /** @description Snapshot chunk data (gzip-compressed framed JSON rows) */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
-                content?: never;
+                content: {
+                    "application/octet-stream": string;
+                };
             };
             /** @description Not modified (cached) */
             304: {
@@ -616,95 +664,6 @@ export interface operations {
             };
         };
     };
-    postSyncPush: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        requestBody?: {
-            content: {
-                "application/json": {
-                    clientId: string;
-                    clientCommitId: string;
-                    operations: {
-                        table: string;
-                        row_id: string;
-                        /** @enum {string} */
-                        op: "upsert" | "delete";
-                        payload: {
-                            [key: string]: unknown;
-                        } | null;
-                        base_version?: number | null;
-                    }[];
-                    schemaVersion: number;
-                };
-            };
-        };
-        responses: {
-            /** @description Successful push response */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": {
-                        /** @constant */
-                        ok: true;
-                        /** @enum {string} */
-                        status: "applied" | "cached" | "rejected";
-                        commitSeq?: number;
-                        results: ({
-                            opIndex: number;
-                            /** @constant */
-                            status: "applied";
-                        } | {
-                            opIndex: number;
-                            /** @constant */
-                            status: "conflict";
-                            message: string;
-                            server_version: number;
-                            server_row: unknown;
-                        } | {
-                            opIndex: number;
-                            /** @constant */
-                            status: "error";
-                            error: string;
-                            code?: string;
-                            retriable?: boolean;
-                        })[];
-                    };
-                };
-            };
-            /** @description Invalid request */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": {
-                        error: string;
-                        message?: string;
-                        code?: string;
-                    };
-                };
-            };
-            /** @description Unauthenticated */
-            401: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": {
-                        error: string;
-                        message?: string;
-                        code?: string;
-                    };
-                };
-            };
-        };
-    };
     getConsoleStats: {
         parameters: {
             query?: never;
@@ -919,7 +878,7 @@ export interface operations {
                             rowId: string;
                             /** @enum {string} */
                             op: "upsert" | "delete";
-                            rowJson?: null;
+                            rowJson: unknown | null;
                             rowVersion: number | null;
                             scopes: {
                                 [key: string]: unknown;
@@ -999,8 +958,7 @@ export interface operations {
                             /** @enum {string} */
                             activityState: "active" | "idle" | "stale";
                             lastRequestAt: string | null;
-                            /** @enum {string|null} */
-                            lastRequestType: "push" | "pull" | null;
+                            lastRequestType: ("push" | "pull") | null;
                             lastRequestOutcome: string | null;
                             effectiveScopes: {
                                 [key: string]: unknown;
@@ -1168,6 +1126,61 @@ export interface operations {
             };
         };
     };
+    postConsoleNotifyDataChange: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    tables: string[];
+                    partitionId?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Notification result */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        commitSeq: number;
+                        tables: string[];
+                        deletedChunks: number;
+                    };
+                };
+            };
+            /** @description Invalid request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: string;
+                        message?: string;
+                    };
+                };
+            };
+            /** @description Unauthenticated */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: string;
+                        message?: string;
+                    };
+                };
+            };
+        };
+    };
     deleteConsoleClientsById: {
         parameters: {
             query?: never;
@@ -1724,6 +1737,7 @@ export interface operations {
                     "application/json": {
                         exists: boolean;
                         uploadId?: string;
+                        /** Format: uri */
                         uploadUrl?: string;
                         /** @enum {string} */
                         uploadMethod?: "PUT" | "POST";