theokit 0.12.0 → 0.13.0

package/dist/error-envelope-BsNzzAV5.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Error envelope — canonical cross-layer contract for theokit framework, SDK,
+ * and UI per plan g5-error-envelope-cross-layer v1.0 § Phase 1 / T1.1.
+ *
+ * Blueprint G5 (SHIPPABLE_WITH_CAVEATS 89/100) — Form 4 Hybrid: shared CODE
+ * enum + per-domain extensions + 2-layer SDK boundary translation.
+ *
+ * 3/3 references convergence: code + message + cause base (trpc TRPCError
+ * + hono HTTPException + encore Error). Wasp confirms ecosystem gap.
+ *
+ * Reference anchors (verified file:line):
+ * - referencia: trpc/packages/server/src/unstable-core-do-not-import/error/TRPCError.ts:65-87
+ * - referencia: trpc/packages/server/src/unstable-core-do-not-import/rpc/codes.ts:11-44,76-81
+ * - referencia: hono/src/http-exception.ts:46-78
+ * - referencia: encore/runtimes/go/beta/errs/error.go:38-55 (Go — D4 disclaimer applied)
+ *
+ * Per blueprint ADR D2: retryable + hint are extension slots, NOT base fields
+ * (3/3 references derive retryability from code identity; no reference ships
+ * a `retryable: boolean` on envelope; `hint` is novel).
+ *
+ * Per blueprint ADR D5: server-only `meta` filtered at serializer boundary
+ * (encore `json:"-"` analog).
+ *
+ * Lives in `core/contracts/` per architecture.md v3 — canonical home for
+ * shared client↔server types. Zero intra-monorepo deps; zero runtime deps
+ * (trpc + hono ship envelope with zero runtime deps per blueprint Q5).
+ */
+/**
+ * Canonical TheoKit error code union. HTTP-status flavor + SDK/agent-domain
+ * additions per blueprint Recommendations § concrete shape.
+ *
+ * String-literal union mirrors trpc's TRPC_ERROR_CODE_KEY pattern — enables
+ * exhaustive `switch (env.code)` narrowing in consumer code (UI display
+ * dispatch, retry-policy gates, telemetry classification).
+ */
+type TheoErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'CONFLICT' | 'PRECONDITION_FAILED' | 'PAYLOAD_TOO_LARGE' | 'UNSUPPORTED_MEDIA_TYPE' | 'UNPROCESSABLE_ENTITY' | 'TOO_MANY_REQUESTS' | 'INTERNAL_SERVER_ERROR' | 'NOT_IMPLEMENTED' | 'BAD_GATEWAY' | 'SERVICE_UNAVAILABLE' | 'GATEWAY_TIMEOUT' | 'AGENT_RUN_ERROR' | 'PROVIDER_KEY_MISSING' | 'BUDGET_EXCEEDED' | 'RATE_LIMITED' | 'CREDENTIAL_POOL_EXHAUSTED';
+/**
+ * Base envelope shape — `{ code, message, cause?, meta?, ext? }`.
+ *
+ * `cause` follows TC39 proposal-error-cause (universal pattern, 3/3 references).
+ * `meta` is server-only metadata filtered at serializer boundary per ADR D5
+ * (`stack` is auto-stripped in non-dev builds — see T1.2 `TheoError.toJSON()`).
+ * `ext` carries opt-in per-domain extensions (`ValidationFieldsExt`,
+ * `RetryableExt`, `HintExt`, or arbitrary user-defined types via formatter hook).
+ */
+interface TheoErrorEnvelope<TExt = unknown> {
+    readonly code: TheoErrorCode;
+    readonly message: string;
+    readonly cause?: unknown;
+    readonly meta?: Record<string, unknown>;
+    readonly ext?: TExt;
+}
+/**
+ * `ValidationFieldsExt` — validation-failure extension carrying the dot-notation
+ * field map identical to G3 `ActionInputError.fields`. Empty-string key for
+ * root-level errors (mirrors G3 EC-7). Multiple messages per key are preserved.
+ */
+interface ValidationFieldsExt {
+    readonly fields: Record<string, string[]>;
+}
+
+export type { TheoErrorEnvelope as T, ValidationFieldsExt as V, TheoErrorCode as a };

package/dist/health-route-C0hk64_U.d.ts

@@ -0,0 +1,57 @@
+/**
+ * M7-2 — health/ready reserved routes for the convention/filesystem-route
+ * server. Liveness (`/__theo/health`, always 200) and readiness
+ * (`/__theo/ready`, 200/503 from a probe) are registered on a reserved
+ * namespace BEFORE the user-route catch-all + 404 branch — mirroring nitro's
+ * `/_nitro/*` reserved-namespace pattern (knowledge-base/references/nitro/src/
+ * runtime/internal/routes/dev-tasks.ts). Liveness and readiness are kept
+ * separate by design: liveness says "the process is up", readiness says
+ * "dependencies are up".
+ *
+ * @public
+ */
+/** Reserved path for the liveness endpoint. */
+declare const HEALTH_PATH = "/__theo/health";
+/** Reserved path for the readiness endpoint. */
+declare const READY_PATH = "/__theo/ready";
+/** Config produced by {@link defineHealthRoute}. */
+interface HealthRouteConfig {
+    readonly kind: 'health';
+    /** Returns the liveness body (auto-serialized to JSON). Default: `{ status: 'ok' }`. */
+    readonly handler: () => unknown;
+}
+/** Config produced by {@link defineReadyRoute}. */
+interface ReadyRouteConfig {
+    readonly kind: 'ready';
+    /** Resolves `true` when dependencies are ready. A throw/reject is treated as not-ready (503). */
+    readonly probe: () => boolean | Promise<boolean>;
+}
+/** The reserved-route registry consulted by {@link serveReservedRoute}. */
+interface ReservedRoutes {
+    readonly health?: HealthRouteConfig;
+    readonly ready?: ReadyRouteConfig;
+}
+/** A reserved-route response: an HTTP status + a JSON-serializable body. */
+interface ReservedResponse {
+    readonly status: number;
+    readonly body: unknown;
+}
+/**
+ * Define the liveness route. The default handler returns `{ status: 'ok' }`.
+ * Liveness is always 200 — it asserts the process is up, not that dependencies are.
+ */
+declare function defineHealthRoute(handler?: () => unknown): HealthRouteConfig;
+/**
+ * Define the readiness route. The `probe` decides 200 (ready) vs 503 (not-ready).
+ * A probe that throws/rejects is treated as not-ready (503) — never a 500 crash.
+ */
+declare function defineReadyRoute(probe: () => boolean | Promise<boolean>): ReadyRouteConfig;
+/**
+ * Pure dispatcher: map a request pathname to a reserved-route response, or
+ * `null` when the path is not reserved (so the user catch-all + 404 take over).
+ * Liveness defaults to 200 `{status:'ok'}`; readiness without a probe is
+ * trivially ready (200). Registered BEFORE the user catch-all by the caller.
+ */
+declare function serveReservedRoute(pathname: string, routes?: ReservedRoutes): Promise<ReservedResponse | null>;
+
+export { HEALTH_PATH as H, type ReservedRoutes as R, type HealthRouteConfig as a, READY_PATH as b, type ReadyRouteConfig as c, type ReservedResponse as d, defineHealthRoute as e, defineReadyRoute as f, serveReservedRoute as s };