@luckystack/sync 0.1.9 → 0.2.0

package/docs/error-states.md

@@ -115,21 +115,22 @@ Project codes can carry whatever slots their templates declare. The normalizer d
 
 Fired whenever a rate-limit bucket rejects a sync request. The payload differs by `scope`:
 
-### Scope `'user'` or `'route'` (per-route bucket, identified by token or by IP)
+### Scope `'user'` or `'ip'` (per-route bucket, identified by token or by IP)
 
 ```ts
 {
-  scope: 'user' | 'route',
+  scope: 'user' | 'ip',
   key: string,         // 'token:<token>:sync:<routeName>' or 'ip:<ip>:sync:<routeName>'
   limit: number,       // projectConfig.rateLimiting.defaultApiLimit
   windowMs: number,    // projectConfig.rateLimiting.windowMs
   count: number,       // limit + 1 (the request that tipped over)
-  route: string,       // e.g. 'board/moveCard/v1'
+  route: string,       // e.g. 'board/moveCard/v1' — marks this a per-route bucket
   userId: string | undefined,
+  ip: string | undefined, // set when anonymous (no token), else undefined
 }
 ```
 
-`scope: 'user'` when the request carried a session token; `scope: 'route'` when it was anonymous (only an IP).
+`scope: 'user'` when the request carried a session token; `scope: 'ip'` when it was anonymous (the per-route bucket is then IP-keyed). The `route` field stays set in both cases to distinguish this per-route bucket from the global `:sync:all` IP bucket below (parity with the API handler).
 
 ### Scope `'ip'` (global per-IP bucket, across all sync routes)
 

package/docs/server-vs-client-handlers.md

@@ -54,6 +54,8 @@ Key rules:
 - **`auth: AuthProps` is mandatory.** Drives the framework's auth gate (`auth.login` -> require session, `auth.additional` -> run `validateRequest` predicates). See `@luckystack/login` `AuthProps`.
 - **Return must include `status: 'success' | 'error'`.** Anything else collapses to `sync.invalidServerResponse`. The rest of the object is forwarded as `serverOutput` (after stripping `status`).
 - **Streaming primitives are received as params.** See [`./streaming.md`](./streaming.md) for the audience matrix.
+- **Optional `export const validation`** toggles runtime input validation, exactly like the API handler. `'strict'` (default, or omit the export) validates `clientInput` against the generated Zod schema; `'relaxed'` or `{ input: 'skip' }` skips validation entirely — use it for routes whose payload shape can't be modelled in TypeScript (third-party webhook fan-in, dynamic blobs). Honored identically by both the Socket.io and HTTP/SSE transports.
+- **Optional `export const errorFormatter`** overrides the error envelope for this route only (falls back to the global `registerErrorFormatter`, then the framework default). Both transports honor it.
 - **Never `try/catch` manually.** Wrap async ops in `functions.tryCatch` (or the destructured `tryCatch` from `functions`) — the framework already wraps the whole `main()` in its own `tryCatch` for Sentry capture, but per-operation `tryCatch` lets you surface targeted error codes.
 
 ---