@luckystack/sync 0.10.1 → 0.11.0

package/AGENTS.md

@@ -0,0 +1,9 @@
+# @luckystack/sync — design context
+
+Sync exists for server-authoritative mutations followed by realtime delivery. The server handler runs for the request; the optional client handler is for recipient-specific filtering or presentation, not for authorizing the originator. A successful originator acknowledgement does not prove that every recipient accepted the event. Source: `src/handleSyncRequest.ts`, `src/handleHttpSyncRequest.ts`, `src/_shared/clientFanout.ts`.
+
+A client-chosen receiver is an authorization boundary, not merely a room name. Keep the built-in all-room and membership restrictions and the `preSyncAuthorize` policy aligned across socket and HTTP/SSE. HTTP membership uses persisted session rooms. That source differs from the socket's on purpose, so do not unify the two checks (ADR 0059). Per-recipient filters must not replace sender-side authorization. Preserve server-side receiver validation before fanout and avoid leaking private data into shared `serverOutput`. Source: `src/_shared/receiverAuth.ts`, `src/_shared/receiverAuth.test.ts`, `src/handleSyncTransport.test.ts`.
+
+Both transports must answer the same thing at the same point. Recipients resolve across instances before the server handler commits, so a delivery failure is never reported on a saved mutation (ADR 0063). An empty room is `sync.noReceiversFound` on every transport (ADR 0058). Fanout code never enumerates the per-instance socket maps (ADR 0061). Every `sync.*` code a transport can emit belongs in `src/_shared/errorCodes.ts`, which consumers' locale parity tests rely on.
+
+Stream audiences differ; do not turn originator-only progress into broadcast or treat a client callback as a security filter. Use the browser-safe `/client` entry and generated types; never cast around a broken map. See `docs/server-vs-client-handlers.md`, `docs/room-fanout.md`, `docs/error-states.md`, `docs/streaming.md`, `docs/version-policy.md` and `../core/AGENTS.md`.

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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).
 
+## [0.11.0] - 2026-10-14
+
+### Changed
+
+- Type declarations are emitted per source file by TypeScript 7 (`tsc -b`) instead of one bundled `.d.ts` per entry, so the framework build no longer runs package by package. The exported types are unchanged; relative imports inside the declarations carry `.js`, so `moduleResolution: "node16"`/`"nodenext"` projects resolve them as before.
+- Package design guidance now ships as `AGENTS.md`, not `CLAUDE.md`. Handwritten docs focus on rationale and safety; exact API contracts remain in installed declarations/source.
+
 ## [0.10.0] - 2026-09-03
 
 ### Changed

package/README.md

@@ -1,153 +1,5 @@
 # @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.
+Server-authoritative, room-based realtime updates with socket and HTTP/SSE transports. Install with `npm install @luckystack/sync socket.io socket.io-client`; add optional React and Prisma peers only when those surfaces are used (see `package.json`). Browser callers import `@luckystack/sync/client`.
 
-## Install
-
-```bash
-npm install @luckystack/sync socket.io socket.io-client
-# Optional React client helpers: npm install react
-```
-
-## 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/ARCHITECTURE_SYNC.md#streaming`](../../docs/ARCHITECTURE_SYNC.md#streaming) — the streaming primitives (`stream` / `streamTo` / `broadcastStream` / `_client`), `createStreamThrottle`, and SSE.
-
-## Dependencies
-
-- Runtime: `@luckystack/core`, `@luckystack/error-tracking` (`@luckystack/login` is an optional session provider, not a runtime dependency)
-- Required peers: `socket.io@^4.8.0`, `socket.io-client@^4.8.0`
-- Optional peers: `@prisma/client@^6.19.0` (only for the default Prisma-backed session/user provider), `react@^19.2.0` (`/client` entry only).
-
-## License
-
-MIT — see [LICENSE](../../LICENSE).
+Use a server handler for shared mutations and an optional recipient handler only when individual recipients need different output. Choosing a receiver is an authorization decision, not just routing; maintain sender-side checks even when recipient filtering exists. See [design context](./AGENTS.md), [server vs recipient](./docs/server-vs-client-handlers.md), [room authorization](./docs/room-fanout.md) and [version rationale](./docs/version-policy.md). Source and generated maps own the API surface.

package/dist/_shared/clientFanout.d.ts

@@ -0,0 +1,39 @@
+import type { RuntimeSyncClientHandler, SyncErrorEnvelopeInput } from './syncTypes.js';
+interface FanoutRecipientSocket {
+    emit(event: string, ...args: unknown[]): unknown;
+    handshake: {
+        headers: Record<string, string | string[] | undefined>;
+    };
+}
+export interface ProcessClientSyncForRecipientArgs<TError extends object> {
+    tempSocket: FanoutRecipientSocket;
+    tempToken: string | null;
+    clientSyncHandler: RuntimeSyncClientHandler;
+    data: Record<string, unknown>;
+    functionsObject: Record<string, unknown>;
+    serverOutput: unknown;
+    receiver: string;
+    resolvedName: string;
+    callbackKey: string;
+    transport: 'socket' | 'http';
+    handlerName: 'handleSyncRequest' | 'handleHttpSyncRequest';
+    logLabel: 'sync' | 'http sync';
+    shouldLogDev: () => boolean;
+    shouldLogStream: () => boolean;
+    buildSyncError: (args: {
+        response: SyncErrorEnvelopeInput;
+        preferred?: string | null;
+        userLanguage?: string | null;
+    }) => TError;
+    resolvePreferredLocale: (headers: Record<string, string | string[] | undefined>) => string | null | undefined;
+    sourceUserId?: string;
+}
+/**
+ * Run the optional `_client` handler for ONE recipient socket and emit the
+ * per-recipient `sync` envelope. When the route has no `_client` file the
+ * caller emits the server-only success envelope instead (kept at the call site
+ * because it does not run the handler). Behaviour-identical to the previously
+ * inlined loop body in both transports.
+ */
+export declare const processClientSyncForRecipient: <TError extends object>({ tempSocket, tempToken, clientSyncHandler, data, functionsObject, serverOutput, receiver, resolvedName, callbackKey, transport, handlerName, logLabel, shouldLogDev, shouldLogStream, buildSyncError, resolvePreferredLocale, sourceUserId, }: ProcessClientSyncForRecipientArgs<TError>) => Promise<void>;
+export {};

package/dist/_shared/errorBuilders.d.ts

@@ -0,0 +1,35 @@
+import { type ErrorFormatter } from '@luckystack/core';
+import type { SyncErrorEnvelopeInput } from './syncTypes.js';
+export interface FormattedSyncErrorEnvelope {
+    status: 'error';
+    message: string;
+    errorCode: string;
+    errorParams?: {
+        key: string;
+        value: string | number | boolean;
+    }[];
+    httpStatus?: number;
+    [key: string]: unknown;
+}
+export interface BuildFormattedErrorArgs {
+    response: SyncErrorEnvelopeInput;
+    preferred?: string | null;
+    userLanguage?: string | null;
+    routeName: string | undefined;
+    transport: 'socket' | 'http';
+    userId?: string | null;
+    perRouteFormatter?: ErrorFormatter | undefined | null;
+}
+/**
+ * Normalize an error envelope (i18n message + envelope shape), then run it
+ * through the per-route → global → identity formatter chain. Transport
+ * handlers pass the same logical inputs; only `transport`, `routeName`, and
+ * the per-route formatter differ. Returns a typed, formatted error envelope.
+ */
+export declare const buildFormattedError: ({ response, preferred, userLanguage, routeName, transport, userId, perRouteFormatter, }: BuildFormattedErrorArgs) => FormattedSyncErrorEnvelope;
+/**
+ * Guarantee a client-rejection envelope always carries a non-empty
+ * `errorCode`, falling back to `sync.clientRejected`. Shared by both
+ * transports' per-recipient `_client` error path.
+ */
+export declare const ensureSyncErrorShape: (response: SyncErrorEnvelopeInput) => SyncErrorEnvelopeInput;

package/dist/_shared/errorCodes.d.ts

@@ -0,0 +1,3 @@
+export declare const SYNC_ERROR_CODES: readonly ['sync.invalidName', 'sync.invalidVersion', 'sync.missingReceiver', 'sync.ioUnavailable', 'sync.failedRequest', 'sync.invalidServerResponse', 'sync.invalidRequestFormat', 'sync.requestTimeout', 'sync.invalidRequest', 'sync.invalidCallback', 'sync.notFound', 'sync.rateLimitExceeded', 'sync.invalidInputType', 'sync.serverExecutionFailed', 'sync.receiverNotAllowed', 'sync.notRoomMember', 'sync.noReceiversFound', 'sync.clientExecutionFailed', 'sync.invalidClientResponse', 'sync.clientRejected', 'sync.disabled', 'sync.methodNotAllowed', 'sync.devToolsUnavailable'];
+/** Union of every framework-emitted `sync.*` error code. */
+export type SyncErrorCode = (typeof SYNC_ERROR_CODES)[number];

package/dist/_shared/logFlags.d.ts

@@ -0,0 +1,2 @@
+export declare const shouldLogDev: () => boolean;
+export declare const shouldLogStream: () => boolean;

package/dist/_shared/receiverAuth.d.ts

@@ -0,0 +1,34 @@
+/** Decision returned by {@link authorizeSyncReceiver}. */
+export type ReceiverAuthDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    errorCode: 'sync.receiverNotAllowed' | 'sync.notRoomMember';
+};
+export interface AuthorizeSyncReceiverInput {
+    /** The (already-trimmed, non-empty) receiver the client requested. */
+    receiver: string;
+    /** `sync.allowClientReceiverAll` from project config. */
+    allowClientReceiverAll: boolean;
+    /** `sync.requireRoomMembership` from project config. */
+    requireRoomMembership: boolean;
+    /**
+     * Membership predicate for the requested room. Pass a function that reports
+     * whether the requester has actually joined `receiver` — on the socket
+     * transport this is `socket.rooms.has(receiver)`; on HTTP/SSE (no originator
+     * socket) derive it from the session's persisted `roomCodes`. Pass `null`
+     * ONLY when membership genuinely cannot be determined for this requester
+     * (e.g. an anonymous HTTP caller with no session). When `null` and
+     * `requireRoomMembership` is true, this helper FAILS CLOSED (rejects) rather
+     * than silently delegating the security default to the opt-in
+     * `preSyncAuthorize` hook.
+     */
+    isMember: (() => boolean) | null;
+}
+/**
+ * Resolve whether a client may target `receiver` for a sync fanout under the
+ * configured default policy. Returns `{ allowed: true }` when permitted, or a
+ * specific generic error code when rejected. The `'all'` check runs first
+ * (cluster-wide broadcasts are the riskiest), then room-membership.
+ */
+export declare const authorizeSyncReceiver: ({ receiver, allowClientReceiverAll, requireRoomMembership, isMember, }: AuthorizeSyncReceiverInput) => ReceiverAuthDecision;

package/dist/_shared/redactToken.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Truncate a session token to `<first 4 chars>…` for safe logging. Returns the
+ * value unchanged when it is null/empty (nothing to redact) or already shorter
+ * than the visible prefix.
+ */
+export declare const redactToken: (token: string | null) => string | null;
+/**
+ * Redact a list of tokens (e.g. the `streamTo` recipient list) for logging.
+ */
+export declare const redactTokens: (tokens: readonly string[]) => string[];

package/dist/_shared/streamEmitters.d.ts

@@ -0,0 +1,51 @@
+import type { Socket } from 'socket.io';
+export type SyncStreamPayload = Record<string, unknown>;
+export interface FlushPressureOptions {
+    /**
+     * Drain threshold in bytes. Used as a packet-count approximation —
+     * we assume an average packet size of ~1024 bytes and resolve once the
+     * engine.io writeBuffer length is below `thresholdBytes / 1024`.
+     * When omitted, falls back to `projectConfig.sync.flushPressure.maxBufferedBytes`
+     * (default 5 MiB as configured in the framework defaults).
+     */
+    thresholdBytes?: number;
+}
+export type FlushPressure = (options?: FlushPressureOptions) => Promise<void>;
+export interface SyncStreamEmitters {
+    emitServerSyncStream: (payload?: SyncStreamPayload) => void;
+    emitBroadcastSyncStream: (payload?: SyncStreamPayload) => void;
+    emitStreamToTokens: (tokens: string | string[], payload?: SyncStreamPayload) => void;
+    buildBroadcastFrame: (payload: SyncStreamPayload) => Record<string, unknown>;
+    flushPressure: FlushPressure;
+}
+interface BuildSyncStreamEmittersArgs {
+    cb: string | undefined;
+    receiver: string;
+    /**
+     * Session user id of the request originator (or null when anonymous). Threaded
+     * through so `broadcastStream` / `flushPressure` can route the receiver room
+     * through `formatRoomName` with the SAME `{ purpose: 'broadcast', userId }`
+     * context the fanout in `handleSyncRequest` / `handleHttpSyncRequest` uses —
+     * otherwise a non-identity `registerRoomNameFormatter` (multi-tenant) makes
+     * broadcast streams target the UNFORMATTED room and miss every recipient.
+     */
+    userId?: string | null;
+    resolvedName: string;
+    emitOriginatorChunk: (payload: SyncStreamPayload) => void;
+    logLabel: string;
+    /**
+     * AbortSignal sourced from the per-request controller in `handleSyncRequest`
+     * / `handleHttpSyncRequest`. When aborted (client disconnect, explicit
+     * `syncCancel`), every emit is short-circuited with a single dev-log line
+     * and `flushPressure()` resolves immediately.
+     */
+    signal?: AbortSignal;
+    /**
+     * Originator socket — used to drive `flushPressure` measurement when the
+     * stream targets only the originator. Optional because the HTTP/SSE
+     * transport has no originator socket (SSE response writer is the sink).
+     */
+    originatorSocket?: Socket;
+}
+export declare const buildSyncStreamEmitters: ({ cb, receiver, userId, resolvedName, emitOriginatorChunk, logLabel, signal, originatorSocket, }: BuildSyncStreamEmittersArgs) => SyncStreamEmitters;
+export {};

package/dist/_shared/syncTypes.d.ts

@@ -0,0 +1,74 @@
+import type { AuthProps, BaseSessionLayout as SessionLayout, ErrorFormatter } from '@luckystack/core';
+import type { FlushPressure } from './streamEmitters.js';
+export type SyncStreamPayload = Record<string, unknown>;
+export interface RuntimeErrorResponse {
+    status: 'error';
+    errorCode?: string;
+    errorParams?: {
+        key: string;
+        value: string | number | boolean;
+    }[];
+    httpStatus?: number;
+    message?: string;
+    [key: string]: unknown;
+}
+export interface RuntimeSuccessResponse {
+    status: 'success';
+    message?: string;
+    httpStatus?: number;
+    [key: string]: unknown;
+}
+export type RuntimeSyncResponse = RuntimeSuccessResponse | RuntimeErrorResponse;
+export type SyncBroadcastStream = (payload?: SyncStreamPayload) => void;
+export type SyncStreamTo = (tokens: string | string[], payload?: SyncStreamPayload) => void;
+export interface RuntimeSyncServerEntry {
+    auth: AuthProps;
+    main: (params: {
+        clientInput: Record<string, unknown>;
+        user: SessionLayout | null;
+        functions: Record<string, unknown>;
+        roomCode: string;
+        stream: (payload?: SyncStreamPayload) => void;
+        broadcastStream: SyncBroadcastStream;
+        streamTo: SyncStreamTo;
+        abortSignal: AbortSignal;
+        flushPressure: FlushPressure;
+    }) => Promise<RuntimeSyncResponse>;
+    inputType?: string;
+    inputTypeFilePath?: string;
+    validation?: 'strict' | 'relaxed' | {
+        input: 'skip' | 'strict';
+    };
+    /**
+     * Per-route rate limit (mirrors `@luckystack/api`). Overrides
+     * `rateLimiting.defaultApiLimit` for this sync route's per-requester bucket;
+     * `false` disables it (the global per-IP bucket still applies); omit to fall
+     * back to `defaultApiLimit`. Honored by both transports (passed as
+     * `routeLimit` into `applySyncRateLimits` / `applyHttpSyncRateLimits`).
+     */
+    rateLimit?: number | false;
+    /**
+     * Per-route error response formatter. Falls back to the global formatter
+     * from `registerErrorFormatter(...)`, then to the framework default
+     * `normalizeErrorResponse`. Same contract as the API handler — both
+     * transports honor the same `errorFormatter` export.
+     */
+    errorFormatter?: ErrorFormatter;
+}
+export type RuntimeSyncClientHandler = (params: {
+    clientInput: Record<string, unknown>;
+    token: string | null;
+    functions: Record<string, unknown>;
+    serverOutput: unknown;
+    roomCode: string;
+    stream: (payload?: SyncStreamPayload) => void;
+}) => Promise<RuntimeSyncResponse>;
+export interface SyncErrorEnvelopeInput {
+    status: 'error';
+    errorCode?: string;
+    errorParams?: {
+        key: string;
+        value: string | number | boolean;
+    }[];
+    httpStatus?: number;
+}

package/dist/_shared/validationMode.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeSyncServerEntry } from './syncTypes.js';
+export declare const resolveSyncValidationMode: (validation: RuntimeSyncServerEntry['validation']) => 'strict' | 'relaxed';

package/dist/client.d.ts

@@ -1,129 +1,4 @@
-import { StreamPayload, statusContent, BaseSessionLayout, SyncTypeMap } from '@luckystack/core/client';
-import { Dispatch, SetStateAction, RefObject } from 'react';
-import { Socket } from 'socket.io-client';
-export { S as SYNC_ERROR_CODES, a as SyncErrorCode } from './errorCodes-B8GoTenr.js';
-
-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;
-};
-declare const attachSyncReceiver: (socketInstance: Socket) => 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, attachSyncReceiver, initSyncRequest, syncRequest, useSyncEventTrigger, useSyncEvents };
+export { syncRequest, useSyncEvents, useSyncEventTrigger, initSyncRequest, attachSyncReceiver, } from './syncRequest.js';
+export type { SyncRequestStreamEvent, SyncRouteStreamEvent } from './syncRequest.js';
+export { SYNC_ERROR_CODES } from './_shared/errorCodes.js';
+export type { SyncErrorCode } from './_shared/errorCodes.js';

package/dist/handleHttpSyncRequest.d.ts

@@ -0,0 +1,33 @@
+import type { SyncStreamPayload } from './_shared/syncTypes.js';
+interface HttpSyncRequestParams {
+    name: string;
+    cb?: string;
+    data: Record<string, unknown>;
+    receiver: string;
+    ignoreSelf?: boolean;
+    token: string | null;
+    requesterIp?: string;
+    xLanguageHeader?: string | string[];
+    acceptLanguageHeader?: string | string[];
+    stream?: (payload: HttpSyncStreamEvent) => void;
+    /**
+     * Optional AbortSignal. The HTTP server (`@luckystack/server`) wires this
+     * to `req.on('close', ...)` so a closed SSE connection aborts in-flight
+     * stream emits. Sync handlers receive it as `abortSignal` in params.
+     */
+    abortSignal?: AbortSignal;
+}
+interface HttpSyncResponse {
+    status: 'success' | 'error';
+    message: string;
+    result?: unknown;
+    errorCode?: string;
+    errorParams?: {
+        key: string;
+        value: string | number | boolean;
+    }[];
+    httpStatus?: number;
+}
+export type HttpSyncStreamEvent = SyncStreamPayload;
+export default function handleHttpSyncRequest(args: HttpSyncRequestParams): Promise<HttpSyncResponse>;
+export {};

package/dist/handleSyncRequest.d.ts

@@ -0,0 +1,7 @@
+import type { syncMessage } from "@luckystack/core";
+import { Socket } from "socket.io";
+export default function handleSyncRequest(args: {
+    msg: syncMessage;
+    socket: Socket;
+    token: string | null;
+}): Promise<void>;