@luckystack/api 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.4] - 2026-08-17
+
+### Changed
+
+- Corrected consumer documentation for optional Prisma/error-tracking dependencies, registered-tracker capture, generated-type rule links, and stale freshness metadata.
+
 ## [0.8.1] - 2026-07-27
 
 ### Fixed

package/CLAUDE.md

@@ -82,10 +82,8 @@ No project env vars or secrets are read directly by this package — only the am
 ## Peer dependencies
 
 - **Required (runtime deps)**: `@luckystack/core`, `@luckystack/error-tracking`. **`@luckystack/login` is NOT a dependency** (0.2.0 decoupling) — sessions resolve through core's `readSession` / session-provider registry, with login as the default *provider* (optional package), not a hard runtime dep.
-- **Required (peer)**:
-  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core` session storage).
-  - `socket.io@^4.8.0` (only consumed for the `Socket` type — the HTTP entry point does not need a live socket.io instance at call time).
-- **No optional peers.** Streaming uses an injected callback, not an external SSE library.
+- **Required peer**: `socket.io@^4.8.0` (only consumed for the `Socket` type — the HTTP entry point does not need a live socket.io instance at call time).
+- **Optional peer**: `@prisma/client@^6.19.0` — only needed when the active session/user provider uses the default Prisma client. Streaming uses an injected callback, not an external SSE library.
 
 ## Hooks consumed
 
@@ -108,6 +106,6 @@ Deep behavior for each hook lives in `@luckystack/core`'s hook registry doc.
 
 - Architecture deep dives: `/docs/ARCHITECTURE_API.md`, `/docs/ARCHITECTURE_ROUTING.md`.
 - Consumer quickstart: `./README.md`.
-- Generated-type contract: `/docs/ARCHITECTURE_ROUTING.md` (see "Generated maps") and root `CLAUDE.md` rule 16 (no `unknown`/`any` casts).
+- Generated-type contract: `/docs/ARCHITECTURE_ROUTING.md` (see "Generated maps") and repository-root `CLAUDE.md` rule 21 (no `unknown`/`any` casts).
 - Session source: `@luckystack/core`'s session-provider registry — `readSession(token)` / `performLogout(...)` (see `docs/ARCHITECTURE_SESSION.md`). `@luckystack/login` is the DEFAULT provider when installed, not a hard dep. Shared types `BaseSessionLayout` / `AuthProps` come from `@luckystack/core`.
 - Runtime map source: `@luckystack/core` `getRuntimeApiMaps()` + `@luckystack/devkit` emitter.

package/README.md

@@ -5,7 +5,8 @@
 ## Install
 
 ```bash
-npm install @luckystack/api @luckystack/core @luckystack/error-tracking socket.io
+npm install @luckystack/api socket.io
+# Optional Prisma-backed route code: npm install @prisma/client
 ```
 
 ## Quickstart
@@ -59,7 +60,7 @@ You typically don't call these yourself — `createLuckyStackServer` does. Use t
 2. **Rate-limits** with two buckets via `checkRateLimit` from `@luckystack/core`: a per-route bucket keyed on the validated `user.id` (anonymous callers fall back to the resolved IP — never the raw session token, so re-login can't reset the limit; the basis is overridable via `rateLimiting.identity`) plus a global per-IP abuse bucket.
 3. **Validates** the inbound payload against the Zod schema generated from your `ApiParams['data']` interface (via `@luckystack/devkit`).
 4. **Dispatches** the `preApiExecute` hook (may abort with a stop signal).
-5. **Calls** your `main(...)` and captures errors via `tryCatch` (auto-forwarded to Sentry).
+5. **Calls** your `main(...)` and captures thrown errors via `tryCatch` (fanned out to every registered error tracker).
 6. **Dispatches** the `postApiExecute` hook with the result + duration.
 7. **Returns** the response via socket `ack` or HTTP body / SSE stream.
 
@@ -79,7 +80,7 @@ if (result.status === 'success') {
 }
 ```
 
-Do not wrap `apiRequest` in `unknown` / `any` shims (see `.claude/CLAUDE.md` rule 16). If inference fails, fix the typing source or regenerate maps instead.
+Do not wrap `apiRequest` in `unknown` / `any` shims (see repository-root [`CLAUDE.md`](../../CLAUDE.md) rule 21). If inference fails, fix the typing source or regenerate maps instead.
 
 ## Public API
 
@@ -97,9 +98,8 @@ Do not wrap `apiRequest` in `unknown` / `any` shims (see `.claude/CLAUDE.md` rul
 ## Dependencies
 
 - Runtime: `@luckystack/core`, `@luckystack/error-tracking` (`@luckystack/login` is NOT a runtime dependency — sessions resolve through core's session-provider registry; login is the optional default provider)
-- Peer (canonical ranges, standardized 2026-05-07):
-  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core`)
-  - `socket.io@^4.8.0`
+- Required peer: `socket.io@^4.8.0`
+- Optional peer: `@prisma/client@^6.19.0` — only needed when the active session/user provider uses the default Prisma client.
 
 ## License
 

package/docs/api-request-lifecycle.md

@@ -1,7 +1,5 @@
 # API Request Lifecycle
 
-> Last updated: 2026-05-20
-
 ## Overview
 
 `@luckystack/api` exposes two transport adapters — `handleApiRequest` (socket.io) and `handleHttpApiRequest` (raw HTTP) — that share an identical 13-step pipeline. The pipeline takes a transport payload, resolves it to a registered route in the runtime maps emitted by `@luckystack/devkit`, runs authentication / rate-limit / input-validation gates, dispatches a fixed set of lifecycle hooks, executes the route's `main(...)` function under a `tryCatch` boundary, then normalizes the result into a localized envelope before emitting it on the wire.

package/docs/auth-flow.md

@@ -1,7 +1,5 @@
 # Auth Flow
 
-> Last updated: 2026-05-20
-
 ## Overview
 
 `@luckystack/api` does not own authentication — it consumes `getSession` from `@luckystack/login` and `validateRequest` from `@luckystack/core`. The handler's job is to translate the per-route `AuthProps` declaration into the right gate (require login + optional predicate checks) and to attribute every framework error tracker call that follows to the right user.

package/docs/error-handling.md

@@ -1,12 +1,10 @@
 # Error Handling
 
-> Last updated: 2026-05-20
-
 ## Overview
 
 `@luckystack/api` produces a strict, two-shape response envelope. Every code path through the handler — malformed input, auth failure, rate-limit rejection, handler throw, handler return — ends in either `{ status: 'success', ... }` or `{ status: 'error', errorCode, errorParams?, httpStatus, message }`. The transformation from raw failure to wire envelope flows through three layers:
 
-1. **`tryCatch`** wraps the handler's `main(...)` call. Errors are captured (auto-forwarded to Sentry / any registered tracker with context), and the tuple `[error, result]` is returned to the pipeline. Raw exceptions never reach the client.
+1. **`tryCatch`** wraps the handler's `main(...)` call. Thrown errors are captured (fanned out to every registered tracker with context), and the tuple `[error, result]` is returned to the pipeline. Raw exceptions never reach the client.
 2. **`buildApiResponseEnvelope`** (socket) / **`buildNetworkError`** (HTTP) maps the raw handler result to a wire envelope, inferring `httpStatus` via `defaultHttpStatusForResponse` and routing the error fields through `normalizeErrorResponse`.
 3. **`normalizeErrorResponse`** renders the localized `message` field from the `errorCode` + `errorParams`, using the project-registered translate function. Locale is extracted in priority order: `x-language` header → `accept-language` header → `user.language`.
 
@@ -199,7 +197,7 @@ The error tracker (registered via `@luckystack/error-tracking`) receives every `
 
 ## What is NOT handled here
 
-- **Business-logic errors inside `main(...)`.** Routes return `{ status: 'error', errorCode: '...' }` directly. The envelope normalizer renders them — no thrown exception, no Sentry capture. This is by design: business outcomes (validation failures in domain code, "user already exists") are not "errors" in the tracking sense.
+- **Business-logic errors inside `main(...)`.** Routes return `{ status: 'error', errorCode: '...' }` directly. The envelope normalizer renders them — no thrown exception, no error-tracker capture. This is by design: business outcomes (validation failures in domain code, "user already exists") are not "errors" in the tracking sense.
 - **Localization of `errorCode` strings.** That is the consumer's responsibility — `registerLocalizedNormalizer` from the project's `server/utils/responseNormalizer.ts` provides the translate function backed by JSON locale files in `src/_locales/`.
 - **Frontend error rendering.** The client's `apiRequest` returns the normalized envelope. UI code consumes `result.errorCode` + `result.message` and decides how to render (toast via `notify`, inline form error, redirect).
 - **Hook handler errors.** Failures inside a `dispatchHook` handler are isolated by the hook bus — they log via `getLogger()` + the tracker but do not affect the main pipeline.

package/docs/generated-types.md

@@ -1,12 +1,10 @@
 # Generated Types
 
-> Last updated: 2026-05-20
-
 ## Overview
 
 LuckyStack's API layer is fully type-safe end-to-end. Every `src/{page}/_api/{name}_v{N}.ts` file is read by `@luckystack/devkit` via the TypeScript compiler API, its `ApiParams['data']` and `main` return types are extracted, and three artifacts are emitted: `apiTypes.generated.ts` (the static type map), `apiInputSchemas.generated.ts` (runtime Zod schemas), and `apiDocs.generated.json` (introspection JSON used by `@luckystack/docs-ui`). `@luckystack/api` reads the runtime map at request time and uses the input-type text to drive `validateInputByType`. The client-side `apiRequest` from `@luckystack/core` reads the static type map to infer payload + response shapes from the route-name + version literals you pass it.
 
-This means: any change to an API file's `ApiParams['data']` interface or `main` return type propagates to the client at the next regeneration. The hot-reload watcher (devkit) triggers regeneration on save. The strict typing policy in the repo root contract (`.claude/CLAUDE.md` rule 16) requires this inference chain to remain intact — `unknown` / `any` casts around `apiRequest` defeat the whole pipeline.
+This means: any change to an API file's `ApiParams['data']` interface or `main` return type propagates to the client at the next regeneration. The hot-reload watcher (devkit) triggers regeneration on save. The strict typing policy in the repository-root contract (`CLAUDE.md` rule 21) requires this inference chain to remain intact — `unknown` / `any` casts around `apiRequest` defeat the whole pipeline.
 
 This doc covers the generated type surface, the runtime validation flow that consumes it, and the per-route opt-out for cases where strict input typing is impossible (third-party webhooks).
 
@@ -159,7 +157,7 @@ The HTTP transport does **not** honor the flag — relax-mode endpoints typicall
 
 ## Strict typing policy
 
-Repository rule (root `.claude/CLAUDE.md` §16): **NEVER** cast typed API/sync payloads to `unknown`, `any`, or `unsafe*` wrappers when calling `apiRequest`, `syncRequest`, or `upsertSyncEventCallback`.
+Repository rule (root `CLAUDE.md` §21): **NEVER** cast typed API/sync payloads to `unknown`, `any`, or `unsafe*` wrappers when calling `apiRequest`, `syncRequest`, or `upsertSyncEventCallback`.
 
 ```ts
 // Bad — defeats the entire generated-types pipeline
@@ -261,4 +259,4 @@ This package does not own hooks specific to type generation. The runtime validat
 - Error handling: [`./error-handling.md`](./error-handling.md)
 - Architecture: [`/docs/ARCHITECTURE_ROUTING.md`](../../../docs/ARCHITECTURE_ROUTING.md) (see "Generated maps")
 - Devkit type-map generation: `@luckystack/devkit/docs/type-map-generation.md`
-- Root rule on casts: [`/.claude/CLAUDE.md`](../../../.claude/CLAUDE.md) §16
+- Root rule on casts: [`CLAUDE.md`](../../../CLAUDE.md) §21

package/docs/rate-limiting.md

@@ -1,7 +1,5 @@
 # Rate Limiting
 
-> Last updated: 2026-05-20
-
 ## Overview
 
 Every API request runs through two rate-limit buckets, in order. The per-route bucket protects an individual endpoint from a single caller; the global per-IP bucket protects the server as a whole from a single source hitting many endpoints. Both buckets use the same strategy backend (configurable via `registerRateLimitStrategy` in `@luckystack/core`; defaults to memory-or-redis depending on `rateLimiting.store`), share the same `windowMs`, and emit the same `rateLimitExceeded` hook on rejection.

package/docs/routing-conventions.md

@@ -1,7 +1,5 @@
 # Routing Conventions
 
-> Last updated: 2026-05-20
-
 ## Overview
 
 `@luckystack/api` is transport-agnostic — it does not own file-based routing. Discovery of `_api/<name>_v<N>.ts` files lives in `@luckystack/devkit`, which walks `src/`, parses each file's exports, and emits two artifacts the API handler reads at runtime: the route map (`getRuntimeApiMaps()`) and the generated type map (`apiTypes.generated.ts`). This document describes the route-name conventions both handlers enforce, the per-route exports the runtime map carries, and the HTTP-method inference contract the HTTP transport applies.
@@ -67,7 +65,7 @@ export const main = async ({ data, user, functions }: ApiParams): Promise<ApiRes
 
 | Export | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `main` | `(params) => Promise<ApiResponse>` | required | Handler invoked by `executeApiHandler` inside the `tryCatch` + Sentry span. |
+| `main` | `(params) => Promise<ApiResponse>` | required | Handler invoked by `executeApiHandler` inside the `tryCatch` + registered error-tracker span. |
 | `auth` | `AuthProps` | required | Auth gate (see [`./auth-flow.md`](./auth-flow.md)). |
 | `rateLimit` | `number \| false` | `rateLimiting.defaultApiLimit` from config | Per-route requests-per-window cap. `false` disables the per-route bucket; the global IP bucket still applies. See [`./rate-limiting.md`](./rate-limiting.md). |
 | `httpMethod` | `'GET' \| 'POST' \| 'PUT' \| 'DELETE'` | inferred from name | Overrides `inferHttpMethod` for the HTTP transport. Socket transport ignores this field. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckystack/api",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -56,8 +56,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@luckystack/core": "^0.8.2",
-    "@luckystack/error-tracking": "^0.8.2"
+    "@luckystack/core": "^0.8.4",
+    "@luckystack/error-tracking": "^0.8.4"
   },
   "peerDependencies": {
     "@prisma/client": "^6.19.0",