katanakit-js 6.7.4 → 6.8.0

package/README.md

@@ -29,7 +29,7 @@ In the browser, use jsDelivr **`/+esm`** so named exports and dependencies resol
 | **esm.sh**                         | `https://esm.sh/katanakit-js`                                                           |
 | **Raw ESM file**                   | `https://cdn.jsdelivr.net/npm/katanakit-js/dist/index.js` (needs bundler or import map) |
 
-Pin a version in production (e.g. `@6.7.4/+esm`). There is no IIFE/UMD build.
+Pin a version in production (e.g. `@6.8.0/+esm`). There is no IIFE/UMD build.
 
 ## Quick Start
 
@@ -871,6 +871,8 @@ See [Getting Started](https://docs.senseikatana.com/guides/getting-started) for
 | ----------- | ----------------------------------------------- | ------------------------------------------------------- |
 | **Express** | `katanakit-js/adapters/express`                 | Reference server with CORS and hardened headers         |
 | **Bun**     | `katanakit-js/adapters/bun`                     | `Bun.serve` route table + dummyjson.com demo            |
+| **NestJS**  | `katanakit-js/adapters/nestjs`                  | `KatanaKitModule`, injectable facade, capability guard and logger bridge |
+| **Hono**    | `katanakit-js/adapters/hono`                    | Runtime-agnostic app factory, capability middleware and `useSafeJson` |
 | **Nuxt**    | `katanakit-js/adapters/nuxt`                    | `useUnwrap`, `useSafeResponse`, `useEventResponse`      |
 | **Astro**   | `katanakit-js` or `katanakit-js/adapters/astro` | `AstroService`, `RssService`                            |
 
@@ -1548,13 +1550,15 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development contract.
 
 The docs site is built with **VitePress** from [`docs/`](./docs) and deployed with Cloudflare Pages at [docs.senseikatana.com](https://docs.senseikatana.com/). Run it locally with `bun run docs:dev`.
 
-- [Getting Started](https://docs.senseikatana.com/guides/getting-started)
-- [Error Handling](https://docs.senseikatana.com/guides/errors)
-- [Architecture](https://docs.senseikatana.com/guides/architecture)
-- [UI Kit (Katana UI)](https://docs.senseikatana.com/ui-kit/)
-- [API Reference](https://docs.senseikatana.com/api/)
-- [Roadmap](https://docs.senseikatana.com/guides/roadmap)
-- [Changelog](https://docs.senseikatana.com/changelog)
+- **Introduction** — [Getting Started](https://docs.senseikatana.com/guides/getting-started) · [Error Handling](https://docs.senseikatana.com/guides/errors) · [Architecture](https://docs.senseikatana.com/guides/architecture) · [Roadmap](https://docs.senseikatana.com/guides/roadmap)
+- **Core Services** — [Overview](https://docs.senseikatana.com/guides/services/) · [HTTP Client](https://docs.senseikatana.com/guides/services/http-client) · [DOM](https://docs.senseikatana.com/guides/services/dom) · [Storage](https://docs.senseikatana.com/guides/services/storage) · [Dates](https://docs.senseikatana.com/guides/services/dates)
+- **Platform Services** — [Theme](https://docs.senseikatana.com/guides/services/theme) · [Astro Adapter](https://docs.senseikatana.com/guides/services/astro-adapter) · [RSS](https://docs.senseikatana.com/guides/services/rss) · [SEO](https://docs.senseikatana.com/guides/services/seo)
+- **Integrations** — [Nuxt Adapter](https://docs.senseikatana.com/guides/services/nuxt-adapter) · [Vue Adapter](https://docs.senseikatana.com/guides/services/vue-adapter) · [Express Server](https://docs.senseikatana.com/guides/services/express-server)
+- **HTTP & REST** — [Query Client](https://docs.senseikatana.com/guides/query-client) · [Framework Adapters](https://docs.senseikatana.com/guides/framework-adapters) · [Better Auth](https://docs.senseikatana.com/guides/better-auth)
+- **Runtime & Filesystem** — [Filesystem](https://docs.senseikatana.com/guides/filesystem) · [Bun Adapter](https://docs.senseikatana.com/guides/bun-adapter) · [Faker](https://docs.senseikatana.com/guides/faker)
+- **Browser & DOM** — [Watch](https://docs.senseikatana.com/guides/watch) · [PhotoSwipe](https://docs.senseikatana.com/guides/photoswipe)
+- **UI Kit (Katana UI)** — [Overview](https://docs.senseikatana.com/ui-kit/) · [SCSS framework](https://docs.senseikatana.com/ui-kit/css/)
+- **Reference** — [API Reference](https://docs.senseikatana.com/api/) · [Changelog](https://docs.senseikatana.com/changelog)
 
 ## License
 

package/dist/adapters/hono/access.guard.d.ts

@@ -0,0 +1,31 @@
+import type { Context, MiddlewareHandler } from "hono";
+import type { AccessCapability, AccessSubject } from "../../types/index.js";
+/**
+ * Builds a Hono middleware that requires an access capability, mirroring the
+ * Express `useRequireCapability()` and Nest guard behavior.
+ *
+ * The project ships no auth provider, so the subject is resolved by the caller
+ * (JWT, session, API key…) from the request context. Return `null` for
+ * anonymous requests — they get a 401; authenticated but not allowed gets a
+ * 403. Both bodies use the toolkit's `{ ok, data, error }` shape.
+ *
+ * @param capability - The capability required to reach the route.
+ * @param resolveSubject - Resolves the access subject from the Hono context.
+ * @returns A Hono middleware handler for `app.use()` / `app.get(..., mw)`.
+ *
+ * @example
+ * ```ts
+ * import { Hono } from "hono";
+ * import { useRequireCapability } from "katanakit-js/adapters/hono";
+ *
+ * const app = new Hono();
+ * const canPublish = useRequireCapability("content:publish", (c) => {
+ *   const header = c.req.header("authorization");
+ *   return header ? { id: 1, roles: ["owner"] } : null; // your auth lookup
+ * });
+ *
+ * app.post("/articles/:id/publish", canPublish, (c) => c.json({ ok: true }));
+ * ```
+ */
+export declare function useRequireCapability(capability: AccessCapability, resolveSubject: (context: Context) => AccessSubject | null): MiddlewareHandler;
+//# sourceMappingURL=access.guard.d.ts.map

package/dist/adapters/hono/access.guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.guard.d.ts","sourceRoot":"","sources":["../../../src/adapters/hono/access.guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAGvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CACnC,UAAU,EAAE,gBAAgB,EAC5B,cAAc,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,aAAa,GAAG,IAAI,GACxD,iBAAiB,CAgCnB"}

package/dist/adapters/hono/access.guard.js

@@ -0,0 +1,53 @@
+import { useCan } from "../../core/services/access.service.js";
+/**
+ * Builds a Hono middleware that requires an access capability, mirroring the
+ * Express `useRequireCapability()` and Nest guard behavior.
+ *
+ * The project ships no auth provider, so the subject is resolved by the caller
+ * (JWT, session, API key…) from the request context. Return `null` for
+ * anonymous requests — they get a 401; authenticated but not allowed gets a
+ * 403. Both bodies use the toolkit's `{ ok, data, error }` shape.
+ *
+ * @param capability - The capability required to reach the route.
+ * @param resolveSubject - Resolves the access subject from the Hono context.
+ * @returns A Hono middleware handler for `app.use()` / `app.get(..., mw)`.
+ *
+ * @example
+ * ```ts
+ * import { Hono } from "hono";
+ * import { useRequireCapability } from "katanakit-js/adapters/hono";
+ *
+ * const app = new Hono();
+ * const canPublish = useRequireCapability("content:publish", (c) => {
+ *   const header = c.req.header("authorization");
+ *   return header ? { id: 1, roles: ["owner"] } : null; // your auth lookup
+ * });
+ *
+ * app.post("/articles/:id/publish", canPublish, (c) => c.json({ ok: true }));
+ * ```
+ */
+export function useRequireCapability(capability, resolveSubject) {
+    return async (context, next) => {
+        const subject = resolveSubject(context);
+        if (!subject) {
+            return context.json({ ok: false, data: null, error: { message: "Authentication required", status: 401 } }, 401);
+        }
+        let allowed;
+        try {
+            allowed = useCan(subject, capability);
+        }
+        catch {
+            // Malformed subject or unknown role: fail closed at the HTTP boundary.
+            allowed = false;
+        }
+        if (!allowed) {
+            return context.json({
+                ok: false,
+                data: null,
+                error: { message: `Missing capability: ${capability}`, status: 403 },
+            }, 403);
+        }
+        await next();
+    };
+}
+//# sourceMappingURL=access.guard.js.map

package/dist/adapters/hono/access.guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.guard.js","sourceRoot":"","sources":["../../../src/adapters/hono/access.guard.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,uCAAuC,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,oBAAoB,CACnC,UAA4B,EAC5B,cAA0D;IAE1D,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QAC9B,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QAExC,IAAI,CAAC,OAAO,EAAE,CAAC;YACd,OAAO,OAAO,CAAC,IAAI,CAClB,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,yBAAyB,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,EACrF,GAAG,CACH,CAAC;QACH,CAAC;QAED,IAAI,OAAgB,CAAC;QACrB,IAAI,CAAC;YACJ,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACR,uEAAuE;YACvE,OAAO,GAAG,KAAK,CAAC;QACjB,CAAC;QAED,IAAI,CAAC,OAAO,EAAE,CAAC;YACd,OAAO,OAAO,CAAC,IAAI,CAClB;gBACC,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,IAAI;gBACV,KAAK,EAAE,EAAE,OAAO,EAAE,uBAAuB,UAAU,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE;aACpE,EACD,GAAG,CACH,CAAC;QACH,CAAC;QAED,MAAM,IAAI,EAAE,CAAC;IACd,CAAC,CAAC;AACH,CAAC"}

package/dist/adapters/hono/app.d.ts

@@ -0,0 +1,42 @@
+import { Hono } from "hono";
+/** Options accepted by {@link useCreateApp}. */
+export interface HonoAppOptions {
+    /**
+     * Allowed CORS origins. Defaults to the `CORS_ORIGINS` env variable
+     * (comma-separated) or `http://localhost:3000`.
+     */
+    corsOrigins?: string[];
+    /** Registers `GET /health` (default `true`). */
+    health?: boolean;
+}
+/**
+ * Creates a Hono app pre-configured for KatanaKit services.
+ *
+ * The factory is runtime-agnostic — the same app runs on Node
+ * (`@hono/node-server`), Bun (`Bun.serve`), Deno and Cloudflare Workers
+ * (`export default app`). It mounts `secureHeaders()`, CORS from the same
+ * `CORS_ORIGINS` convention as the Express adapter, an optional `/health`
+ * probe and JSON error bodies in the toolkit's `{ ok, data, error }` shape.
+ *
+ * @param options - CORS origins and health-check toggle.
+ * @returns A configured Hono application, ready to mount routes on.
+ *
+ * @example
+ * ```ts
+ * import { useCreateApp, useRequireCapability, useSafeJson } from "katanakit-js/adapters/hono";
+ * import { useGetApi } from "katanakit-js";
+ *
+ * const app = useCreateApp();
+ *
+ * app.get("/pokemon/:id", async (c) => {
+ *   const result = await useGetApi("pokeapi", "pokemonById", {
+ *     params: { id: c.req.param("id") },
+ *   });
+ *   return useSafeJson(c, result);
+ * });
+ *
+ * export default app; // Cloudflare Workers / Deno
+ * ```
+ */
+export declare function useCreateApp(options?: HonoAppOptions): Hono;
+//# sourceMappingURL=app.d.ts.map

package/dist/adapters/hono/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/adapters/hono/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAM5B,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,gDAAgD;IAChD,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,cAAmB,GAAG,IAAI,CA+B/D"}

package/dist/adapters/hono/app.js

@@ -0,0 +1,59 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { secureHeaders } from "hono/secure-headers";
+import { useLogger } from "../../core/services/logger.service.js";
+/** Resolves the CORS allow-list from options or the environment. */
+function resolveCorsOrigins(options) {
+    if (options.corsOrigins)
+        return options.corsOrigins;
+    return (process.env.CORS_ORIGINS?.split(",") ?? ["http://localhost:3000"])
+        .map((origin) => origin.trim())
+        .filter(Boolean);
+}
+/**
+ * Creates a Hono app pre-configured for KatanaKit services.
+ *
+ * The factory is runtime-agnostic — the same app runs on Node
+ * (`@hono/node-server`), Bun (`Bun.serve`), Deno and Cloudflare Workers
+ * (`export default app`). It mounts `secureHeaders()`, CORS from the same
+ * `CORS_ORIGINS` convention as the Express adapter, an optional `/health`
+ * probe and JSON error bodies in the toolkit's `{ ok, data, error }` shape.
+ *
+ * @param options - CORS origins and health-check toggle.
+ * @returns A configured Hono application, ready to mount routes on.
+ *
+ * @example
+ * ```ts
+ * import { useCreateApp, useRequireCapability, useSafeJson } from "katanakit-js/adapters/hono";
+ * import { useGetApi } from "katanakit-js";
+ *
+ * const app = useCreateApp();
+ *
+ * app.get("/pokemon/:id", async (c) => {
+ *   const result = await useGetApi("pokeapi", "pokemonById", {
+ *     params: { id: c.req.param("id") },
+ *   });
+ *   return useSafeJson(c, result);
+ * });
+ *
+ * export default app; // Cloudflare Workers / Deno
+ * ```
+ */
+export function useCreateApp(options = {}) {
+    const app = new Hono();
+    app.use("*", secureHeaders());
+    app.use("*", cors({
+        origin: resolveCorsOrigins(options),
+        allowMethods: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+    }));
+    if (options.health ?? true) {
+        app.get("/health", (context) => context.json({ status: "ok", timestamp: new Date().toISOString() }));
+    }
+    app.notFound((context) => context.json({ ok: false, data: null, error: { message: "Not Found", status: 404 } }, 404));
+    app.onError((error, context) => {
+        useLogger("Unhandled error:", error, "error");
+        return context.json({ ok: false, data: null, error: { message: "Internal Server Error", status: 500 } }, 500);
+    });
+    return app;
+}
+//# sourceMappingURL=app.js.map

package/dist/adapters/hono/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../../src/adapters/hono/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AAalE,oEAAoE;AACpE,SAAS,kBAAkB,CAAC,OAAuB;IAClD,IAAI,OAAO,CAAC,WAAW;QAAE,OAAO,OAAO,CAAC,WAAW,CAAC;IACpD,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;SACxE,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;SAC9B,MAAM,CAAC,OAAO,CAAC,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,YAAY,CAAC,UAA0B,EAAE;IACxD,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IAEvB,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC;IAC9B,GAAG,CAAC,GAAG,CACN,GAAG,EACH,IAAI,CAAC;QACJ,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC;QACnC,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC;KACvD,CAAC,CACF,CAAC;IAEF,IAAI,OAAO,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;QAC5B,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE,CAC9B,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CACnE,CAAC;IACH,CAAC;IAED,GAAG,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,EAAE,CACxB,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,CAAC,CAC1F,CAAC;IAEF,GAAG,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QAC9B,SAAS,CAAC,kBAAkB,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QAC9C,OAAO,OAAO,CAAC,IAAI,CAClB,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,uBAAuB,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,EACnF,GAAG,CACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/adapters/hono/index.d.ts

@@ -0,0 +1,4 @@
+export { useRequireCapability } from "./access.guard.js";
+export { type HonoAppOptions, useCreateApp } from "./app.js";
+export { useSafeJson } from "./result.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/hono/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/hono/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,KAAK,cAAc,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/adapters/hono/index.js

@@ -0,0 +1,4 @@
+export { useRequireCapability } from "./access.guard.js";
+export { useCreateApp } from "./app.js";
+export { useSafeJson } from "./result.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/hono/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/hono/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAuB,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/adapters/hono/result.d.ts

@@ -0,0 +1,32 @@
+import type { Context } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { FetchResult } from "../../types/index.js";
+/**
+ * Maps a KatanaKit Safe Result to a Hono JSON response.
+ *
+ * On success returns the whole Safe Result (`{ ok: true, data, error: null }`)
+ * with a 200. On failure it echoes the upstream HTTP status when the error
+ * carries one between 400 and 599 (proxy-style endpoints keep 404/429/503
+ * semantics); network and config errors (`status: 0`) fall back to
+ * `fallbackStatus` (500 by default).
+ *
+ * @param context - The Hono context.
+ * @param result - The Safe Result from any KatanaKit fetch method.
+ * @param fallbackStatus - Status used when the error has none (default 500).
+ * @returns A Hono JSON response.
+ *
+ * @example
+ * ```ts
+ * import { useSafeJson } from "katanakit-js/adapters/hono";
+ * import { useGetApi } from "katanakit-js";
+ *
+ * app.get("/products/:id", async (c) => {
+ *   const result = await useGetApi("shop", "productById", {
+ *     params: { id: c.req.param("id") },
+ *   });
+ *   return useSafeJson(c, result); // 200, upstream 4xx/5xx, or 500
+ * });
+ * ```
+ */
+export declare function useSafeJson<T>(context: Context, result: FetchResult<T>, fallbackStatus?: ContentfulStatusCode): Response;
+//# sourceMappingURL=result.d.ts.map

package/dist/adapters/hono/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../../src/adapters/hono/result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC5B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACtB,cAAc,GAAE,oBAA0B,GACxC,QAAQ,CAWV"}

package/dist/adapters/hono/result.js

@@ -0,0 +1,37 @@
+/**
+ * Maps a KatanaKit Safe Result to a Hono JSON response.
+ *
+ * On success returns the whole Safe Result (`{ ok: true, data, error: null }`)
+ * with a 200. On failure it echoes the upstream HTTP status when the error
+ * carries one between 400 and 599 (proxy-style endpoints keep 404/429/503
+ * semantics); network and config errors (`status: 0`) fall back to
+ * `fallbackStatus` (500 by default).
+ *
+ * @param context - The Hono context.
+ * @param result - The Safe Result from any KatanaKit fetch method.
+ * @param fallbackStatus - Status used when the error has none (default 500).
+ * @returns A Hono JSON response.
+ *
+ * @example
+ * ```ts
+ * import { useSafeJson } from "katanakit-js/adapters/hono";
+ * import { useGetApi } from "katanakit-js";
+ *
+ * app.get("/products/:id", async (c) => {
+ *   const result = await useGetApi("shop", "productById", {
+ *     params: { id: c.req.param("id") },
+ *   });
+ *   return useSafeJson(c, result); // 200, upstream 4xx/5xx, or 500
+ * });
+ * ```
+ */
+export function useSafeJson(context, result, fallbackStatus = 500) {
+    if (result.ok) {
+        return context.json(result, 200);
+    }
+    const status = result.error.status >= 400 && result.error.status <= 599
+        ? result.error.status
+        : fallbackStatus;
+    return context.json(result, status);
+}
+//# sourceMappingURL=result.js.map

package/dist/adapters/hono/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../../src/adapters/hono/result.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,WAAW,CAC1B,OAAgB,EAChB,MAAsB,EACtB,iBAAuC,GAAG;IAE1C,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,MAAM,MAAM,GACX,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,GAAG,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,GAAG;QACvD,CAAC,CAAE,MAAM,CAAC,KAAK,CAAC,MAA+B;QAC/C,CAAC,CAAC,cAAc,CAAC;IAEnB,OAAO,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACrC,CAAC"}

package/dist/adapters/nestjs/access.guard.d.ts

@@ -0,0 +1,38 @@
+import { type CanActivate, type Type } from "@nestjs/common";
+import type { AccessCapability, AccessSubject } from "../../types/index.js";
+/**
+ * Builds a Nest guard that requires an access capability, mirroring the
+ * Express `useRequireCapability()` behavior on Nest's exception pipeline.
+ *
+ * The project ships no auth provider, so the subject is resolved by the caller
+ * (JWT, session, API key…). Return `null` for anonymous requests — they get a
+ * 401; authenticated but not allowed gets a 403. Both exceptions carry the
+ * same `{ ok, data, error }` body shape used across the toolkit.
+ *
+ * @typeParam TRequest - The platform request type (Express by default).
+ * @param capability - The capability required to activate the route.
+ * @param resolveSubject - Resolves the access subject from the request.
+ * @returns A guard class ready for `@UseGuards(...)`.
+ *
+ * @example
+ * ```ts
+ * import { Controller, Get, UseGuards } from "@nestjs/common";
+ * import { useRequireCapability } from "katanakit-js/adapters/nestjs";
+ *
+ * const CanPublish = useRequireCapability(
+ *   "content:publish",
+ *   (request: { account?: { id: number; roles: string[] } }) => request.account ?? null,
+ * );
+ *
+ * @Controller("articles")
+ * export class ArticlesController {
+ *   @Get("drafts")
+ *   @UseGuards(CanPublish)
+ *   drafts() {
+ *     return [];
+ *   }
+ * }
+ * ```
+ */
+export declare function useRequireCapability<TRequest = unknown>(capability: AccessCapability, resolveSubject: (request: TRequest) => AccessSubject | null): Type<CanActivate>;
+//# sourceMappingURL=access.guard.d.ts.map

package/dist/adapters/nestjs/access.guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.guard.d.ts","sourceRoot":"","sources":["../../../src/adapters/nestjs/access.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,WAAW,EAGhB,KAAK,IAAI,EAET,MAAM,gBAAgB,CAAC;AAGxB,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,GAAG,OAAO,EACtD,UAAU,EAAE,gBAAgB,EAC5B,cAAc,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,aAAa,GAAG,IAAI,GACzD,IAAI,CAAC,WAAW,CAAC,CAmCnB"}

package/dist/adapters/nestjs/access.guard.js

@@ -0,0 +1,69 @@
+import { ForbiddenException, UnauthorizedException, } from "@nestjs/common";
+import { useCan } from "../../core/services/access.service.js";
+/**
+ * Builds a Nest guard that requires an access capability, mirroring the
+ * Express `useRequireCapability()` behavior on Nest's exception pipeline.
+ *
+ * The project ships no auth provider, so the subject is resolved by the caller
+ * (JWT, session, API key…). Return `null` for anonymous requests — they get a
+ * 401; authenticated but not allowed gets a 403. Both exceptions carry the
+ * same `{ ok, data, error }` body shape used across the toolkit.
+ *
+ * @typeParam TRequest - The platform request type (Express by default).
+ * @param capability - The capability required to activate the route.
+ * @param resolveSubject - Resolves the access subject from the request.
+ * @returns A guard class ready for `@UseGuards(...)`.
+ *
+ * @example
+ * ```ts
+ * import { Controller, Get, UseGuards } from "@nestjs/common";
+ * import { useRequireCapability } from "katanakit-js/adapters/nestjs";
+ *
+ * const CanPublish = useRequireCapability(
+ *   "content:publish",
+ *   (request: { account?: { id: number; roles: string[] } }) => request.account ?? null,
+ * );
+ *
+ * @Controller("articles")
+ * export class ArticlesController {
+ *   @Get("drafts")
+ *   @UseGuards(CanPublish)
+ *   drafts() {
+ *     return [];
+ *   }
+ * }
+ * ```
+ */
+export function useRequireCapability(capability, resolveSubject) {
+    class KatanaCapabilityGuard {
+        canActivate(context) {
+            const request = context.switchToHttp().getRequest();
+            const subject = resolveSubject(request);
+            if (!subject) {
+                throw new UnauthorizedException({
+                    ok: false,
+                    data: null,
+                    error: { message: "Authentication required", status: 401 },
+                });
+            }
+            let allowed;
+            try {
+                allowed = useCan(subject, capability);
+            }
+            catch {
+                // Malformed subject or unknown role: fail closed at the HTTP boundary.
+                allowed = false;
+            }
+            if (!allowed) {
+                throw new ForbiddenException({
+                    ok: false,
+                    data: null,
+                    error: { message: `Missing capability: ${capability}`, status: 403 },
+                });
+            }
+            return true;
+        }
+    }
+    return KatanaCapabilityGuard;
+}
+//# sourceMappingURL=access.guard.js.map

package/dist/adapters/nestjs/access.guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.guard.js","sourceRoot":"","sources":["../../../src/adapters/nestjs/access.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,kBAAkB,EAElB,qBAAqB,GACrB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,MAAM,EAAE,MAAM,uCAAuC,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,oBAAoB,CACnC,UAA4B,EAC5B,cAA2D;IAE3D,MAAM,qBAAqB;QAC1B,WAAW,CAAC,OAAyB;YACpC,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,UAAU,EAAY,CAAC;YAC9D,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;YAExC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACd,MAAM,IAAI,qBAAqB,CAAC;oBAC/B,EAAE,EAAE,KAAK;oBACT,IAAI,EAAE,IAAI;oBACV,KAAK,EAAE,EAAE,OAAO,EAAE,yBAAyB,EAAE,MAAM,EAAE,GAAG,EAAE;iBAC1D,CAAC,CAAC;YACJ,CAAC;YAED,IAAI,OAAgB,CAAC;YACrB,IAAI,CAAC;gBACJ,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YACvC,CAAC;YAAC,MAAM,CAAC;gBACR,uEAAuE;gBACvE,OAAO,GAAG,KAAK,CAAC;YACjB,CAAC;YAED,IAAI,CAAC,OAAO,EAAE,CAAC;gBACd,MAAM,IAAI,kBAAkB,CAAC;oBAC5B,EAAE,EAAE,KAAK;oBACT,IAAI,EAAE,IAAI;oBACV,KAAK,EAAE,EAAE,OAAO,EAAE,uBAAuB,UAAU,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE;iBACpE,CAAC,CAAC;YACJ,CAAC;YAED,OAAO,IAAI,CAAC;QACb,CAAC;KACD;IAED,OAAO,qBAAqB,CAAC;AAC9B,CAAC"}

package/dist/adapters/nestjs/index.d.ts

@@ -0,0 +1,6 @@
+export { useRequireCapability } from "./access.guard.js";
+export { KatanaKitModule } from "./kit.module.js";
+export { KatanaKitService } from "./kit.service.js";
+export { KatanaLogger } from "./logger.service.js";
+export { KATANA_KIT_OPTIONS, type KatanaKitModuleOptions } from "./options.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/nestjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/nestjs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,cAAc,CAAC"}

package/dist/adapters/nestjs/index.js

@@ -0,0 +1,6 @@
+export { useRequireCapability } from "./access.guard.js";
+export { KatanaKitModule } from "./kit.module.js";
+export { KatanaKitService } from "./kit.service.js";
+export { KatanaLogger } from "./logger.service.js";
+export { KATANA_KIT_OPTIONS } from "./options.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/nestjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/nestjs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAA+B,MAAM,cAAc,CAAC"}

package/dist/adapters/nestjs/kit.module.d.ts

@@ -0,0 +1,35 @@
+import { type DynamicModule } from "@nestjs/common";
+import { type KatanaKitModuleOptions } from "./options.js";
+/**
+ * Wires KatanaKit into a Nest application.
+ *
+ * `forRoot()` registers the APIs (and optionally the shared query client) at
+ * bootstrap and exposes an injectable {@link KatanaKitService}. The module is
+ * global by default so feature modules do not need to import it again; pass
+ * `global: false` to scope it explicitly.
+ *
+ * @example
+ * ```ts
+ * import { Module } from "@nestjs/common";
+ * import { KatanaKitModule } from "katanakit-js/adapters/nestjs";
+ *
+ * @Module({
+ *   imports: [
+ *     KatanaKitModule.forRoot({
+ *       apis: {
+ *         pokeapi: {
+ *           baseUri: "https://pokeapi.co/api/v2",
+ *           endpoints: { pokemonById: "/pokemon/:id/" },
+ *         },
+ *       },
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+export declare class KatanaKitModule {
+    /** Creates the dynamic module with the toolkit providers. */
+    static forRoot(options?: KatanaKitModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=kit.module.d.ts.map

package/dist/adapters/nestjs/kit.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kit.module.d.ts","sourceRoot":"","sources":["../../../src/adapters/nestjs/kit.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAU,MAAM,gBAAgB,CAAC;AAG5D,OAAO,EAAsB,KAAK,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBACa,eAAe;IAC3B,6DAA6D;IAC7D,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,sBAA2B,GAAG,aAAa;CAQnE"}

package/dist/adapters/nestjs/kit.module.js

@@ -0,0 +1,54 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var KatanaKitModule_1;
+import { Module } from "@nestjs/common";
+import { KatanaKitService } from "./kit.service.js";
+import { KATANA_KIT_OPTIONS } from "./options.js";
+/**
+ * Wires KatanaKit into a Nest application.
+ *
+ * `forRoot()` registers the APIs (and optionally the shared query client) at
+ * bootstrap and exposes an injectable {@link KatanaKitService}. The module is
+ * global by default so feature modules do not need to import it again; pass
+ * `global: false` to scope it explicitly.
+ *
+ * @example
+ * ```ts
+ * import { Module } from "@nestjs/common";
+ * import { KatanaKitModule } from "katanakit-js/adapters/nestjs";
+ *
+ * @Module({
+ *   imports: [
+ *     KatanaKitModule.forRoot({
+ *       apis: {
+ *         pokeapi: {
+ *           baseUri: "https://pokeapi.co/api/v2",
+ *           endpoints: { pokemonById: "/pokemon/:id/" },
+ *         },
+ *       },
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+let KatanaKitModule = KatanaKitModule_1 = class KatanaKitModule {
+    /** Creates the dynamic module with the toolkit providers. */
+    static forRoot(options = {}) {
+        return {
+            module: KatanaKitModule_1,
+            global: options.global ?? true,
+            providers: [KatanaKitService, { provide: KATANA_KIT_OPTIONS, useValue: options }],
+            exports: [KatanaKitService],
+        };
+    }
+};
+KatanaKitModule = KatanaKitModule_1 = __decorate([
+    Module({})
+], KatanaKitModule);
+export { KatanaKitModule };
+//# sourceMappingURL=kit.module.js.map

package/dist/adapters/nestjs/kit.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kit.module.js","sourceRoot":"","sources":["../../../src/adapters/nestjs/kit.module.ts"],"names":[],"mappings":";;;;;;;AAAA,OAAO,EAAsB,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAA+B,MAAM,cAAc,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEI,IAAM,eAAe,uBAArB,MAAM,eAAe;IAC3B,6DAA6D;IAC7D,MAAM,CAAC,OAAO,CAAC,UAAkC,EAAE;QAClD,OAAO;YACN,MAAM,EAAE,iBAAe;YACvB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;YAC9B,SAAS,EAAE,CAAC,gBAAgB,EAAE,EAAE,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;YACjF,OAAO,EAAE,CAAC,gBAAgB,CAAC;SAC3B,CAAC;IACH,CAAC;CACD,CAAA;AAVY,eAAe;IAD3B,MAAM,CAAC,EAAE,CAAC;GACE,eAAe,CAU3B"}