@pylonsync/sync 0.3.292 → 0.3.294

package/dist/transport.d.ts

@@ -0,0 +1,89 @@
+/**
+ * What every caller of `pylonFetch` must supply. The SyncEngine
+ * passes its own config; the React free helpers pass a lightweight
+ * shim built from `getBaseUrl()` + `currentAuthToken()`.
+ */
+export interface TransportConfig {
+    baseUrl?: string;
+    /** Static bearer token. Use `getToken` if the token can change. */
+    token?: string;
+    /** Lazy bearer-token resolver — called per request. Use this when
+     *  the token can be rotated mid-session (refresh, session-changed).
+     *  Returning null/undefined means "no auth header"; cookie-auth
+     *  apps rely on `credentials: "include"` instead. */
+    getToken?: () => string | null | undefined;
+    /** Invoked with the value of the X-Pylon-Change-Seq response
+     *  header when the server sets one. Returning a Promise pauses no
+     *  one — the transport doesn't await it. */
+    onChangeSeq?: (seq: number) => void;
+}
+/**
+ * Per-call init shape. Mirrors the standard `RequestInit` but
+ * normalizes the two body shapes (JSON-encode-this vs raw-pass-
+ * through) into separate fields so callers don't have to remember
+ * to set Content-Type.
+ */
+export interface PylonRequestInit {
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** When set, JSON-stringified into the body and Content-Type
+     *  defaults to application/json. */
+    json?: unknown;
+    /** Raw body — passed through to fetch unchanged. Use this for file
+     *  uploads (Blob, ArrayBuffer, FormData). */
+    body?: BodyInit;
+    /** Extra headers. Caller-supplied keys win against the transport's
+     *  defaults. */
+    headers?: Record<string, string>;
+    /** Override the request's Accept header (useful for SSE streams). */
+    accept?: string;
+    /** AbortController signal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Resolve the base URL. Browser-side fallback to
+ * `window.location.origin` matches the SDK contract: when
+ * `configureClient` was called with no baseUrl, calls go to the
+ * current document's origin so dev + prod work without env
+ * gymnastics.
+ */
+export declare function resolveBaseUrl(config: TransportConfig): string;
+/**
+ * Assemble fetch URL + RequestInit. Exposed for streaming / raw-
+ * response callers (SSE, file upload) that need to handle the
+ * Response themselves but want the transport's auth + credentials +
+ * URL logic.
+ */
+export declare function buildRequest(config: TransportConfig, path: string, init?: PylonRequestInit): {
+    url: string;
+    init: RequestInit;
+};
+/** Error thrown by `pylonFetch` for non-2xx responses. Carries the
+ *  status + structured error code + the parsed JSON body (if any). */
+export declare class PylonHttpError extends Error {
+    status: number;
+    code?: string;
+    body?: unknown;
+    constructor(message: string, status: number, code?: string, body?: unknown);
+}
+/**
+ * The canonical client HTTP call. Returns the parsed JSON body on
+ * 2xx. Throws `PylonHttpError` on non-2xx. Empty 204 bodies parse
+ * as `null`.
+ *
+ * Surfaces `X-Pylon-Change-Seq` via `config.onChangeSeq` so the
+ * SyncEngine can fire a catch-up pull when a mutation's seq is
+ * ahead of its local cursor — matches the
+ * `requestWithChangeSync` shape but lifts the logic out of the
+ * engine so React free helpers (`callFn`, `apiRequest`) get it too.
+ */
+export declare function pylonFetch<T = unknown>(config: TransportConfig, path: string, init?: PylonRequestInit): Promise<T>;
+/**
+ * Streaming variant — returns the raw `Response` so callers can read
+ * `.body` (SSE), `.blob()` (file download), etc. Bypasses JSON
+ * parsing but keeps the URL + auth + credentials logic.
+ *
+ * Caller is responsible for status checking and the
+ * X-Pylon-Change-Seq callback (we don't read the response without
+ * the caller's involvement).
+ */
+export declare function pylonFetchRaw(config: TransportConfig, path: string, init?: PylonRequestInit): Promise<Response>;

package/dist/transports/index.d.ts

@@ -0,0 +1,19 @@
+import type { Transport, TransportHost } from "./types";
+export type TransportKind = "websocket" | "sse" | "poll";
+export type { Transport, TransportHost } from "./types";
+export { WebSocketTransport } from "./websocket";
+export { SseTransport } from "./sse";
+export { PollingTransport } from "./polling";
+/** Build the right transport for a given kind. The host supplies all
+ *  config + the inbound dispatch callbacks; the transport hides the
+ *  underlying mechanism.
+ *
+ *  Fallback rule: `transport: "sse"` in an environment without a
+ *  native EventSource (Node, jsdom without a polyfill, old browsers)
+ *  silently downgrades to polling. The pre-refactor `connectSse()`
+ *  did this inside its constructor catch — we lift the decision to
+ *  the factory so the engine never sees an SseTransport that can
+ *  never connect. Clients that NEED SSE specifically can detect this
+ *  by feature-checking `typeof EventSource` themselves before calling
+ *  `init()`. */
+export declare function createTransport(kind: TransportKind, host: TransportHost): Transport;

package/dist/transports/polling.d.ts

@@ -0,0 +1,15 @@
+import type { Transport, TransportHost } from "./types";
+export declare class PollingTransport implements Transport {
+    private readonly host;
+    private timer;
+    constructor(host: TransportHost);
+    start(): void;
+    stop(): void;
+    send(_msg: unknown): void;
+    isOpen(): boolean;
+    /** No-op — polling doesn't have a backoff counter; it just retries
+     *  every interval. A 429 on the in-flight push/pull will surface as
+     *  a thrown error on the next tick but the loop continues at the
+     *  same cadence. */
+    bumpReconnect(_by?: number): void;
+}

package/dist/transports/reconnect.d.ts

@@ -0,0 +1,20 @@
+/** Stateful backoff counter. Reset to 0 attempts after a successful
+ *  stable connection window. Increment on every failed connect /
+ *  unexpected close. */
+export declare class ReconnectBackoff {
+    private attempts;
+    private baseDelayMs;
+    constructor(baseDelayMs?: number);
+    /** Record a failed connect / unexpected close. Returns the new attempt
+     *  count so callers can use it for bookkeeping (e.g., the 429 case
+     *  bumps by 3 to push the next delay further out). */
+    bump(by?: number): number;
+    /** Reset the counter — call this after the connection has been
+     *  stable long enough that subsequent reconnects shouldn't carry
+     *  the prior backoff over. */
+    reset(): void;
+    /** Compute the next delay in ms. Always returns at least 0; never
+     *  negative. Full-jitter over [0, exp] where exp grows
+     *  exponentially with the attempt count and caps at MAX_DELAY_MS. */
+    nextDelayMs(): number;
+}

package/dist/transports/sse.d.ts

@@ -0,0 +1,22 @@
+import type { Transport, TransportHost } from "./types";
+export declare class SseTransport implements Transport {
+    private readonly host;
+    private es;
+    private reconnectTimer;
+    private readonly backoff;
+    constructor(host: TransportHost);
+    start(): void;
+    stop(): void;
+    /** SSE is one-way. The engine still calls send() for subscribe /
+     *  presence / topic / ping, but those frames have nowhere to go.
+     *  Silent no-op rather than throw: a no-op keeps app code identical
+     *  across transports. */
+    send(_msg: unknown): void;
+    /** SSE is always "open enough" to receive once the EventSource is
+     *  attached and not in CLOSED. We expose this for the engine's
+     *  `connected` getter so UI status matches reality. */
+    isOpen(): boolean;
+    bumpReconnect(by?: number): void;
+    private scheduleReconnect;
+    private deriveSseUrl;
+}

package/dist/transports/types.d.ts

@@ -0,0 +1,97 @@
+import type { ChangeEvent, SyncConnectionStatus } from "../types";
+/** Real-time transport implementations all conform to this shape. The
+ *  engine holds exactly one. The interface intentionally hides the
+ *  underlying mechanism (WebSocket vs EventSource vs setInterval) so
+ *  the engine can be told "go connect" without caring which one. */
+export interface Transport {
+    /** Connect / start the transport. Idempotent — calling twice is a
+     *  no-op for an already-running transport. */
+    start(): void;
+    /** Disconnect / stop the transport, clearing every timer and
+     *  releasing the socket. Idempotent. After stop() the transport is
+     *  re-startable. */
+    stop(): void;
+    /** Send a JSON message over the transport. No-op for non-bidirectional
+     *  transports (SSE, polling) — the engine still sends subscribe
+     *  frames + presence + topic + ping through this entry point, and
+     *  those frames simply never reach the wire when the transport
+     *  doesn't support uplink. */
+    send(msg: unknown): void;
+    /** True when the underlying connection is currently open for sending.
+     *  Used by the engine's `connected` getter and by paths that need to
+     *  short-circuit when no socket exists (e.g., avoid throwing on a
+     *  send-without-WS). */
+    isOpen(): boolean;
+    /** Bump the reconnect backoff counter by N attempts. Called by the
+     *  engine when it observes a hint that the NEXT reconnect should
+     *  wait longer — typically a 429 on pull, which would otherwise
+     *  drive a tight 429 / reconnect / 429 loop. Transports without a
+     *  backoff (polling) implement this as a no-op. */
+    bumpReconnect(by?: number): void;
+}
+/** Engine-side surface the transport calls into. Transport is the
+ *  thing that knows about sockets and timers; the host (engine) is the
+ *  thing that knows what to DO with inbound frames and lifecycle
+ *  events. Keeping this small + explicit makes the boundary clear:
+ *  if a transport needs a new engine capability it gets added here,
+ *  not via reaching back into the engine instance. */
+export interface TransportHost {
+    /** Base URL of the Pylon HTTP API (e.g. `https://api.example.com`).
+     *  Transports derive their own URLs from this (ws upgrade path, SSE
+     *  endpoint, poll path). */
+    readonly baseUrl: string;
+    /** Optional explicit WS URL — overrides the derived one. */
+    readonly wsUrl?: string;
+    /** WS keepalive interval. Default is implementation-defined; the
+     *  engine accepts `pingIntervalMs` from config to tune broadcast
+     *  latency on single-threaded server fallbacks. */
+    readonly pingIntervalMs?: number;
+    /** Base delay for reconnect backoff (full-jitter). */
+    readonly reconnectDelayMs?: number;
+    /** Polling cadence (polling transport only). */
+    readonly pollIntervalMs?: number;
+    /** Current bearer token, or undefined when anonymous. The transport
+     *  must call this fresh on each connect / reconnect so token rotation
+     *  is picked up automatically. */
+    getToken(): string | undefined;
+    /** Is this tab the multi-tab leader. Followers don't open their own
+     *  transport — they mirror the leader's broadcasts. Transports check
+     *  this defensively at start() to avoid wasting socket budget. */
+    isLeader(): boolean;
+    /** Is the engine currently running. Set false on stop(); transports
+     *  bail out of reconnect timers when this flips. */
+    isRunning(): boolean;
+    /** Inbound: a typed change event from the server's change log.
+     *  Engine routes through the apply queue so order is preserved. */
+    onChangeEvent(ev: ChangeEvent): void;
+    /** Inbound: a typed JSON envelope (not a ChangeEvent). The transport
+     *  doesn't try to interpret the envelope — engine has the dispatch
+     *  table (session-changed, reactive-result, row-revoked, presence,
+     *  pong, etc). */
+    onJsonMessage(msg: Record<string, unknown>): void;
+    /** Inbound: a binary frame. CRDT broadcast layer ships these for
+     *  every Loro-mode write; the engine routes via its binaryHandlers
+     *  + multi-tab forwarders. */
+    onBinaryFrame(bytes: Uint8Array): void;
+    /** Lifecycle: the transport just connected. Engine uses this to
+     *  replay active subscriptions, fire a catch-up pull + reconcile,
+     *  and flip the public connection status. */
+    onConnected(): void;
+    /** Lifecycle: the transport just disconnected. Engine flips status
+     *  to `reconnecting` while the transport's own backoff timer is
+     *  pending; or to `offline` when `isRunning()` is false. */
+    onDisconnected(): void;
+    /** Flip the engine's public `connectionStatus`. Transports drive
+     *  this so the UI sees `connecting` / `connected` / `reconnecting`
+     *  / `offline` at the right moments. */
+    setStatus(s: SyncConnectionStatus): void;
+    /** Polling transport only: one iteration of the push→pull cycle.
+     *  Implementations of polling do nothing else; they just call this
+     *  on a timer. */
+    performPollTick(): Promise<void>;
+    /** Reconnect-aware transports (WS, SSE) need to do a catch-up pull
+     *  before the next connect attempt so they don't open a fresh socket
+     *  and immediately discover their cursor is stale. The engine owns
+     *  the pull queue + reconcile path; the transport invokes this. */
+    performReconnectPull(): Promise<void>;
+}

package/dist/transports/websocket.d.ts

@@ -0,0 +1,21 @@
+import type { Transport, TransportHost } from "./types";
+export declare class WebSocketTransport implements Transport {
+    private readonly host;
+    private ws;
+    private reconnectTimer;
+    private stableTimer;
+    private pingTimer;
+    private readonly backoff;
+    constructor(host: TransportHost);
+    start(): void;
+    stop(): void;
+    send(msg: unknown): void;
+    isOpen(): boolean;
+    /** Bump the reconnect counter explicitly. Used for the 429 RESYNC
+     *  case where the engine wants the next delay to be 3 steps further
+     *  out — protects the server from a 429-loop where a 429 on pull
+     *  triggers onclose → reconnect → pull → 429 in a tight cycle. */
+    bumpReconnect(by?: number): void;
+    private scheduleReconnect;
+    private deriveWsUrl;
+}

package/dist/types.d.ts

@@ -0,0 +1,124 @@
+export interface ChangeEvent {
+    seq: number;
+    entity: string;
+    row_id: string;
+    kind: "insert" | "update" | "delete";
+    data?: Record<string, unknown>;
+    timestamp: string;
+}
+export interface SyncCursor {
+    last_seq: number;
+}
+export interface PullResponse {
+    changes: ChangeEvent[];
+    cursor: SyncCursor;
+    has_more: boolean;
+}
+/**
+ * Server-resolved auth/session state. Shape mirrors what `/api/auth/me`
+ * returns (which is `AuthContext` from the Rust side, with camelCase
+ * normalization on the way out).
+ *
+ * `userId=null` means anonymous. `tenantId=null` means the user hasn't
+ * selected an org yet (or the backend is single-tenant).
+ */
+export interface ResolvedSession {
+    userId: string | null;
+    tenantId: string | null;
+    isAdmin: boolean;
+    roles: string[];
+}
+/**
+ * Per-op result on /api/sync/push. Formal shape:
+ *
+ *   { op_id, row_id, entity, kind, status, seq?, error? }
+ *
+ * Status semantics:
+ *   - `applied`   — first-time write committed at `seq`.
+ *   - `replayed`  — same op_id arrived again after a confirmed apply;
+ *                   `seq` is the cached value of the original write so
+ *                   the client can adopt it on its optimistic ghost
+ *                   without waiting for the WS rebroadcast.
+ *   - `pending`   — a concurrent push carrying this op_id is still
+ *                   in flight on the server. No `seq` yet; the
+ *                   client should retry after a short backoff.
+ *   - `error`     — the write was attempted and rejected; `error`
+ *                   carries the server's code + message.
+ *
+ * Legacy `deduped` is treated as `replayed` for compatibility — older
+ * servers (≤ 0.3.190) returned `deduped` for both InFlight and
+ * Replayed cases.
+ */
+export interface PushOpResult {
+    op_id?: string | null;
+    entity?: string;
+    row_id?: string;
+    kind?: "insert" | "update" | "delete";
+    status: "applied" | "replayed" | "pending" | "error" | "deduped";
+    seq?: number;
+    error?: {
+        code: string;
+        message: string;
+    } | string;
+}
+export interface PushResponse {
+    applied: number;
+    deduped: number;
+    errors: string[];
+    results?: PushOpResult[];
+    cursor: SyncCursor;
+}
+export interface ClientChange {
+    entity: string;
+    row_id: string;
+    kind: "insert" | "update" | "delete";
+    data?: Record<string, unknown>;
+    /**
+     * Client-minted idempotency key. The server tracks recently-seen op_ids
+     * and returns a no-op success for replays. Supply this on every retry of
+     * the same logical mutation — the `MutationQueue` does so automatically.
+     */
+    op_id?: string;
+}
+/**
+ * Reactive subscription spec — what the server needs to replay a
+ * subscription if the client reconnects. Cached client-side so the
+ * `ws.onopen` reconnect sweep can re-register every active sub
+ * without the React hooks having to know about reconnect lifecycle.
+ */
+export interface ReactiveSpec {
+    fn_name: string;
+    args: unknown;
+}
+/**
+ * Push message routed to a reactive subscription handler. `result`
+ * fires on initial run + every time the server's re-run produces a
+ * value whose hash differs from the last push. `error` fires when
+ * the server can't execute the handler (function not registered,
+ * reactive runtime unavailable, runtime error in user code).
+ */
+export type ReactiveMessage = {
+    kind: "result";
+    result: unknown;
+} | {
+    kind: "error";
+    code: string;
+    message: string;
+};
+export type Row = Record<string, unknown>;
+export type TransportType = "websocket" | "sse" | "poll";
+/**
+ * Coarse connection state for UI consumers.
+ *
+ * - `connecting`   — engine is starting up; first WS handshake hasn't
+ *                    completed yet. Apps typically render their initial
+ *                    skeleton during this state.
+ * - `connected`    — WS is open and we've stayed open long enough to
+ *                    consider it stable (5s on the wire). Live queries
+ *                    are receiving real-time updates.
+ * - `reconnecting` — WS dropped (network blip, autostop) and the
+ *                    engine is backing off + retrying.
+ * - `offline`      — engine has been stopped via `engine.stop()` or
+ *                    was never started. No retries pending.
+ */
+export type SyncConnectionStatus = "connecting" | "connected" | "reconnecting" | "offline";

package/package.json

@@ -3,14 +3,20 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.292",
+  "version": "0.3.294",
   "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "./src/index.ts",
+  "types": "./dist/index.d.ts",
   "scripts": {
-    "check": "tsc -p tsconfig.json --noEmit"
+    "check": "tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "bun run build"
   },
   "devDependencies": {
     "fake-indexeddb": "^6.2.5"
-  }
+  },
+  "files": [
+    "src",
+    "dist"
+  ]
 }

package/tsconfig.json

@@ -1,7 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "types": ["bun-types"]
-  },
-  "include": ["src"]
-}