@luckystack/sync 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to `@luckystack/sync` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- Initial public release as part of the LuckyStack package split.

package/CLAUDE.md

@@ -0,0 +1,104 @@
+# @luckystack/sync
+
+> AI summary + function INDEX. For deep specs see `docs/` next to this file.
+
+## What this package does
+
+Real-time sync transport for LuckyStack. Provides type-safe, room-based fanout over Socket.io with an HTTP/SSE fallback. Each sync event is a file-based route with a mandatory `_server_v{N}.ts` (runs once, validates, produces `serverOutput`) and an optional `_client_v{N}.ts` (runs once per recipient socket for per-target filtering or auth). Streaming primitives (`stream`, `broadcastStream`, `streamTo`) support live LLM tokens, collab-editor diffs, and per-recipient progress. An offline queue with configurable drop policy keeps optimistic sends from being lost when the socket reconnects.
+
+## When to USE this package
+
+- Real-time room-based fanout (collab editors, chat, multiplayer state)
+- Streaming AI/LLM tokens with throttled chunking
+- Per-recipient customization (filter / translate / brand) without a second round-trip
+- Optimistic offline sends that should replay when the socket reconnects
+- Server-validated mutations that must be broadcast to every peer in a room
+
+## When to NOT suggest this (yet)
+
+- Request/response with no fanout — use `@luckystack/api` (`apiRequest`)
+- Pure presence/online-status broadcasts — use `@luckystack/presence`
+- Cross-instance fanout without a Redis adapter — wire the adapter first (see `/docs/ARCHITECTURE_SOCKET.md`)
+- One-off background jobs unrelated to a client room
+- HTTP-only environments without a long-lived connection AND no SSE — the package needs at minimum the HTTP/SSE fallback
+
+## Function Index
+
+### Server entry (`@luckystack/sync`)
+
+| Export | One-liner | Deep doc |
+|---|---|---|
+| `handleSyncRequest({ msg, socket, token })` | Socket.io sync entry — auth, rate-limit, validate, run `_server`, fanout, run `_client` per recipient, emit results, dispatch hooks. | → `docs/server-vs-client-handlers.md` |
+| `handleHttpSyncRequest(req, res)` | HTTP/SSE fallback for sync requests when websockets are blocked. | → `docs/sync-request.md` |
+| `createStreamThrottle({ flushEveryMs?, flushAtChars?, field? })` | Coalesce tiny stream pieces (LLM tokens) into bigger chunks before emit. | → `docs/streaming.md` |
+| Type: `HttpSyncStreamEvent` | SSE event shape emitted by the HTTP fallback. | → `docs/sync-request.md` |
+| Type: `StreamThrottle` / `CreateStreamThrottleOptions` | Throttle handle + options. | → `docs/streaming.md` |
+
+### Client entry (`@luckystack/sync/client`)
+
+| Export | One-liner | Deep doc |
+|---|---|---|
+| `syncRequest({ name, version, data?, receiver, ignoreSelf?, onStream?, offlineDropPolicy? })` | Fire a typed sync event into a room; resolves with the server result envelope. | → `docs/sync-request.md` |
+| `useSyncEvents()` | React hook returning `{ upsertSyncEventCallback, upsertSyncEventStreamCallback }` scoped to the component lifetime. | → `docs/callback-registration.md` |
+| `useSyncEventTrigger()` | React hook returning `{ triggerSyncEvent, triggerSyncStreamEvent }` for manually invoking registered callbacks (testing / local echo). | → `docs/callback-registration.md` |
+| `initSyncRequest({ setSocketStatus, sessionRef })` | One-time wiring of socket lifecycle handlers (connect/disconnect/reconnectAttempt/userAfk/userBack/connectError) into the socket-status provider. | → `docs/callback-registration.md` |
+| Type: `SyncRequestStreamEvent<T>` | Payload shape passed to `onStream` on the originator side. | → `docs/streaming.md` |
+| Type: `SyncRouteStreamEvent<T>` | Payload shape passed to `upsertSyncEventStreamCallback` on recipients. | → `docs/streaming.md` |
+
+### Streaming primitives (received inside `_server_v{N}.ts` params)
+
+| Primitive | Audience | Deep doc |
+|---|---|---|
+| `stream(payload)` | Originator socket only (cheapest). | → `docs/streaming.md` |
+| `broadcastStream(payload)` | Every socket in `roomCode`, across all instances (`io.to(room).emit` via the Redis adapter). | → `docs/streaming.md` |
+| `streamTo(tokens, payload)` | Selective fanout to specific session tokens. | → `docs/streaming.md` |
+| `stream(payload)` in `_client_v{N}.ts` | Per-recipient, runs after `_server` finishes. | → `docs/streaming.md` |
+
+### Hooks dispatched by the server handler
+
+| Hook | When | Deep doc |
+|---|---|---|
+| `preSyncAuthorize` | After basic `AuthProps` check, before rate-limit + input validation. Stop to reject. | → `docs/server-vs-client-handlers.md` |
+| `preSyncFanout` | After `_server` runs, before any recipient receives the payload. Stop to abort fanout. | → `docs/room-fanout.md` |
+| `postSyncFanout` | After all recipients have been emitted to. Receives `recipientCount`. | → `docs/room-fanout.md` |
+| `rateLimitExceeded` | When the per-route or per-IP bucket rejects a sync. | → `docs/error-states.md` |
+
+## Config keys
+
+### `registerProjectConfig({ sync, offlineQueue })`
+
+- `sync.streamThrottle.flushAtChars` — char threshold before a buffered throttle flushes. Default `32`.
+- `sync.streamThrottle.flushEveryMs` — timer-based flush interval; `false` disables the timer. Default `50`.
+- `sync.streamThrottle.field` — payload key carrying the buffered text. Default `'chunk'`.
+- `sync.fanoutYieldEvery` — yield to the event loop every N recipients during a giant fanout.
+- `sync.fanoutYieldMs` — duration of the yield `setTimeout`.
+- `offlineQueue.maxSize` — cap on the client-side offline queue.
+- `offlineQueue.dropPolicy` — `'reject'` (default — overflow returns `offline.queueFull`), `'drop-oldest'`, or `'drop-newest'`. Per-request override via `syncRequest({ offlineDropPolicy })`.
+
+### Logging toggles
+
+- `logging.devLogs`, `logging.devNotifications`, `logging.socketStatus`, `logging.stream` — drive the dev-only log lines in this package.
+
+### Env vars
+
+None directly. Inherits socket transport config from `@luckystack/server` and Redis adapter config from `@luckystack/core`.
+
+## Peer dependencies
+
+- **Required**: `@luckystack/core`, `@luckystack/login`, `@luckystack/error-tracking`
+- **Peer (canonical ranges, 2026-05-07)**:
+  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core`)
+  - `react@^19.2.0` (only the `/client` subpath)
+  - `socket.io@^4.8.0` (server entry)
+  - `socket.io-client@^4.8.0` (client entry)
+- Redis adapter (required for cross-instance fanout) wired by `@luckystack/server`; see `/docs/ARCHITECTURE_SOCKET.md`.
+
+## Related
+
+- Architecture deep-dive: `/docs/ARCHITECTURE_SYNC.md`
+- Socket setup + Redis adapter: `/docs/ARCHITECTURE_SOCKET.md`
+- Multi-instance model + pitfalls (regular `syncRequest` fan-out reaches across instances via `io.in(room).fetchSockets()` + `RemoteSocket.emit()`; streaming via `broadcastStream`/`streamTo`): `/docs/ARCHITECTURE_MULTI_INSTANCE.md`
+- File-based `_sync/` routing: `/docs/ARCHITECTURE_ROUTING.md`
+- Streaming page reconstruction: `/docs/STREAMING_RECONSTRUCTION.md`
+- README (consumer quickstart): `./README.md`
+- Sibling packages: `@luckystack/api`, `@luckystack/presence`, `@luckystack/server`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathijs van Melick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# @luckystack/sync
+
+> Real-time sync transport for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2). Type-safe room-based fanout, server + per-client validation, streaming, optimistic offline queue. Server entry plus a browser-safe `./client` subpath for React.
+
+## Install
+
+```bash
+npm install @luckystack/sync @luckystack/core @luckystack/login @luckystack/error-tracking react socket.io socket.io-client
+```
+
+## Quickstart
+
+A sync event is two files (one mandatory, one optional):
+
+```ts
+// src/board/_sync/moveCard_server_v1.ts  — runs ONCE per request, validates and produces serverOutput
+export const auth = { login: true };
+
+export interface SyncParams {
+  data: { cardId: string; toLane: string };
+  user: SessionLayout;
+  receiver: string; // room code
+  functions: Functions;
+}
+
+export const main = async ({ data, user, receiver }: SyncParams) => {
+  await prisma.card.update({ where: { id: data.cardId }, data: { laneId: data.toLane } });
+  return { status: 'success', serverOutput: { cardId: data.cardId, movedBy: user.id } };
+};
+```
+
+Add a `_client_v1.ts` only when you need per-client filtering, per-target auth, or a custom `clientOutput`. If it would just `return { status: 'success' }`, leave it out.
+
+### Client side
+
+```tsx
+import { syncRequest, upsertSyncEventCallback } from '@luckystack/sync/client';
+
+upsertSyncEventCallback({
+  name: 'board/moveCard',
+  version: 'v1',
+  callback: ({ serverOutput, clientOutput }) => {
+    if (serverOutput.status !== 'success') return;
+    setCards(prev => moveCardLocally(prev, serverOutput.cardId));
+  },
+});
+
+await syncRequest({
+  name: 'board/moveCard',
+  version: 'v1',
+  data: { cardId, toLane },
+  receiver: roomCode,
+  ignoreSelf: true,
+});
+```
+
+## Subpaths
+
+- `@luckystack/sync` — server-only transport adapters (`handleSyncRequest`, `handleHttpSyncRequest`). Wired by `@luckystack/server`.
+- `@luckystack/sync/client` — browser-safe hooks (`syncRequest`, `useSyncEvents`, `upsertSyncEventCallback`). React 19 required.
+
+## How it integrates
+
+1. **Validates** server payload, then runs `_server_v{N}.ts` once.
+2. **Dispatches** the `preSyncFanout` hook (may abort).
+3. **Resolves** the room receiver list, optionally running `_client_v{N}.ts` once per recipient socket for per-client filtering or auth.
+4. **Emits** the merged `{ serverOutput, clientOutput }` payload to each socket.
+5. **Dispatches** `postSyncFanout` with the recipient count.
+
+## Streaming
+
+Sync handlers receive **four** stream primitives in their `_server` params, each picking a different audience and cost profile:
+
+| Primitive | Audience | Use when |
+| --- | --- | --- |
+| `stream(payload)` | Originator only (cheapest) | Per-user progress nobody else cares about |
+| `broadcastStream(payload)` | Everyone in `roomCode`, across all instances (Redis adapter) | Live AI chat tokens, collab editor diffs |
+| `streamTo(tokens, payload)` | Specific session tokens | Selective subscribers (admin viewers, etc.) |
+| `_client_v{N}.ts` `stream(...)` | Per-recipient (after `_server` finishes) | Per-target customization (filter / translate / brand) |
+
+Plus `createStreamThrottle({ flushEveryMs, flushAtChars })` for coalescing tiny LLM tokens into bigger chunks — cuts message count by 10–100× without losing the "live" feel.
+
+```ts
+// src/chat/_sync/sendMessage_server_v1.ts — AI chat with live broadcast
+import { createStreamThrottle } from '@luckystack/sync';
+
+export const main = async ({ clientInput, broadcastStream }: SyncParams) => {
+  const throttle = createStreamThrottle({ flushEveryMs: 50, flushAtChars: 32 });
+
+  let full = '';
+  for await (const piece of openaiStream) {
+    full += piece.text;
+    throttle.push(piece.text, broadcastStream);
+  }
+  throttle.flush(broadcastStream);
+
+  return { status: 'success', message: full };
+};
+```
+
+Recipients consume both `broadcastStream` and `streamTo` chunks via the same `upsertSyncEventCallback` they already use:
+
+```ts
+upsertSyncEventCallback({
+  name: 'chat/sendMessage',
+  version: 'v1',
+  callback: ({ stream, status }) => {
+    if (status === 'stream' && stream?.chunk) appendToken(stream.chunk);
+  },
+});
+```
+
+Full decision tree, performance notes, and additional examples live in [`docs/ARCHITECTURE_SYNC.md`](../../docs/ARCHITECTURE_SYNC.md#streaming).
+
+## Public API
+
+Server entry (`@luckystack/sync`):
+
+| Export | Purpose |
+| --- | --- |
+| `handleSyncRequest(socket, msg, ack)` | Socket.io sync handler (default export). |
+| `handleHttpSyncRequest(req, res)` | HTTP/SSE fallback. |
+| `createStreamThrottle(options)` | Coalesce small stream pieces into bigger chunks (LLM-token-friendly). |
+| Type: `HttpSyncStreamEvent` | SSE event shape. |
+| Type: `StreamThrottle` / `CreateStreamThrottleOptions` | Throttle helper types. |
+
+Configure stream throttling and offline-queue policy via `registerProjectConfig({ sync, offlineQueue })`. The shapes are exported from `@luckystack/core` as **`SyncConfig`** (with nested `SyncStreamThrottleConfig`) and **`OfflineQueueConfig`** — they cover the throttle defaults, fanout iteration tuning, and the queue's max-size + drop policy (`'reject'` triggers the `offline.queueFull` error code on overflow).
+
+Client entry (`@luckystack/sync/client`):
+
+| Export | Purpose |
+| --- | --- |
+| `syncRequest(opts)` | Fire a typed sync event, optionally with `ignoreSelf` and `receiver`. |
+| `upsertSyncEventCallback({ name, version, callback })` | Subscribe to inbound sync payloads. |
+| `useSyncEvents(...)` | React hook for component-scoped subscriptions. |
+
+## Related architecture docs
+
+- [`docs/ARCHITECTURE_SYNC.md`](../../docs/ARCHITECTURE_SYNC.md) — full sync lifecycle, streaming decision tree, performance notes.
+- [`docs/ARCHITECTURE_SOCKET.md`](../../docs/ARCHITECTURE_SOCKET.md) — Socket.io + Redis adapter (required for cross-instance fanout).
+- [`docs/ARCHITECTURE_ROUTING.md`](../../docs/ARCHITECTURE_ROUTING.md) — `_sync/` file conventions and `_server` / `_client` split.
+- [`docs/STREAMING_RECONSTRUCTION.md`](../../docs/STREAMING_RECONSTRUCTION.md) — recreating the streaming demo page.
+
+## Dependencies
+
+- Runtime: `@luckystack/core`, `@luckystack/login`, `@luckystack/error-tracking`
+- Peer (canonical ranges, standardized 2026-05-07):
+  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core`)
+  - `react@^19.2.0` (`/client` entry only)
+  - `socket.io@^4.8.0`
+  - `socket.io-client@^4.8.0`
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,126 @@
+import { StreamPayload, statusContent, BaseSessionLayout, SyncTypeMap } from '@luckystack/core/client';
+import { Dispatch, SetStateAction, RefObject } from 'react';
+
+type SyncRequestStreamEvent<T extends StreamPayload = StreamPayload> = T;
+type SyncRouteStreamEvent<T extends StreamPayload = StreamPayload> = T;
+type DataRequired<T> = Record<string, never> extends T ? false : true;
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends ((arg: infer I) => void) ? I : never;
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type SyncRouteRecord = UnionToIntersection<{
+    [P in keyof SyncTypeMap]: {
+        [N in keyof SyncTypeMap[P] as P extends 'root' ? `system/${Extract<N, string>}` : `${Extract<P, string>}/${Extract<N, string>}`]: SyncTypeMap[P][N];
+    };
+}[keyof SyncTypeMap]>;
+type SyncFullName = Extract<keyof SyncRouteRecord, string>;
+type VersionsForFullName<F extends SyncFullName> = Extract<keyof SyncRouteRecord[F], string>;
+type ClientInputForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = SyncRouteRecord[F][V] extends {
+    clientInput: infer I;
+} ? I : never;
+type ServerOutputForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = SyncRouteRecord[F][V] extends {
+    serverOutput: infer O;
+} ? O : never;
+type ClientOutputForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = SyncRouteRecord[F][V] extends {
+    clientOutput: infer O;
+} ? O : never;
+type ServerStreamForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = SyncRouteRecord[F][V] extends {
+    serverStream: infer O;
+} ? O : never;
+type ClientStreamForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = SyncRouteRecord[F][V] extends {
+    clientStream: infer O;
+} ? O : never;
+type SyncRequestStreamCallbackForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = [
+    ServerStreamForFullName<F, V>
+] extends [never] ? never : (event: SyncRequestStreamEvent<Prettify<ServerStreamForFullName<F, V> extends StreamPayload ? ServerStreamForFullName<F, V> : StreamPayload>>) => void;
+type CombinedRouteStream<F extends SyncFullName, V extends VersionsForFullName<F>> = (ClientStreamForFullName<F, V> extends never ? never : ClientStreamForFullName<F, V>) | (ServerStreamForFullName<F, V> extends never ? never : ServerStreamForFullName<F, V>);
+type SyncRouteStreamCallbackForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = [
+    CombinedRouteStream<F, V>
+] extends [never] ? never : (params: {
+    stream: SyncRouteStreamEvent<Prettify<CombinedRouteStream<F, V> extends StreamPayload ? CombinedRouteStream<F, V> : StreamPayload>>;
+}) => void;
+type SyncParamsForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = DataRequired<ClientInputForFullName<F, V>> extends true ? {
+    name: F;
+    version: V;
+    data: ClientInputForFullName<F, V>;
+    receiver: string;
+    ignoreSelf?: boolean;
+    onStream?: SyncRequestStreamCallbackForFullName<F, V>;
+    /**
+     * Per-request override of `projectConfig.offlineQueue.dropPolicy`. Lets a
+     * specific sync ("editor cursor move") pick `'drop-oldest'` while the
+     * app default stays `'reject'` for safer sends. When omitted, falls back
+     * to the global config.
+     */
+    offlineDropPolicy?: 'drop-oldest' | 'drop-newest' | 'reject';
+    /**
+     * Optional AbortSignal. When aborted the client emits `syncCancel { cb }`
+     * to the server and resolves locally with
+     * `{ status: 'error', errorCode: 'request.aborted' }`.
+     */
+    signal?: AbortSignal;
+} : {
+    name: F;
+    version: V;
+    data?: ClientInputForFullName<F, V>;
+    receiver: string;
+    ignoreSelf?: boolean;
+    onStream?: SyncRequestStreamCallbackForFullName<F, V>;
+    /** Per-request override (see typed branch). */
+    offlineDropPolicy?: 'drop-oldest' | 'drop-newest' | 'reject';
+    /** Optional AbortSignal — see typed branch. */
+    signal?: AbortSignal;
+};
+interface SyncErrorParam {
+    key: string;
+    value: string | number | boolean;
+}
+interface SyncResponseError {
+    status: 'error';
+    message: string;
+    errorCode: string;
+    errorParams?: SyncErrorParam[];
+    httpStatus?: number;
+}
+type SyncResultForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = [
+    ServerOutputForFullName<F, V>
+] extends [never] ? Record<string, never> : ServerOutputForFullName<F, V>;
+type SyncRequestResponseForFullName<F extends SyncFullName, V extends VersionsForFullName<F>> = SyncResponseError | {
+    status: 'success';
+    message: string;
+    result: SyncResultForFullName<F, V>;
+};
+type SyncRequestParamsWithOptions<F extends SyncFullName, V extends VersionsForFullName<F>> = SyncParamsForFullName<F, V>;
+declare function syncRequest<F extends SyncFullName, V extends VersionsForFullName<F>>(params: SyncRequestParamsWithOptions<F, V>): Promise<Prettify<SyncRequestResponseForFullName<F, V>>>;
+interface TypedCallbackParams<F extends SyncFullName, V extends VersionsForFullName<F>> {
+    clientOutput: ClientOutputForFullName<F, V>;
+    serverOutput: ServerOutputForFullName<F, V>;
+}
+interface UpsertParams<F extends SyncFullName, V extends VersionsForFullName<F>> {
+    name: F;
+    version: V;
+    callback: (params: TypedCallbackParams<F, V>) => void;
+}
+interface UpsertStreamParams<F extends SyncFullName, V extends VersionsForFullName<F>> {
+    name: F;
+    version: V;
+    callback: SyncRouteStreamCallbackForFullName<F, V>;
+}
+declare const useSyncEvents: () => {
+    upsertSyncEventCallback: <F extends SyncFullName, V extends VersionsForFullName<F>>(params: UpsertParams<F, V>) => (() => void);
+    upsertSyncEventStreamCallback: <F extends SyncFullName, V extends VersionsForFullName<F>>(params: UpsertStreamParams<F, V>) => (() => void);
+};
+declare const useSyncEventTrigger: () => {
+    triggerSyncEvent: (name: string, clientOutput?: unknown, serverOutput?: unknown) => void;
+    triggerSyncStreamEvent: (name: string, stream: SyncRouteStreamEvent) => void;
+};
+type SocketStatusSetter = Dispatch<SetStateAction<{
+    self: statusContent;
+    [userId: string]: statusContent;
+}>>;
+declare const initSyncRequest: ({ setSocketStatus, sessionRef }: {
+    setSocketStatus: SocketStatusSetter;
+    sessionRef: RefObject<BaseSessionLayout | null> | null;
+}) => Promise<void>;
+
+export { type SyncRequestStreamEvent, type SyncRouteStreamEvent, initSyncRequest, syncRequest, useSyncEventTrigger, useSyncEvents };