katanakit-js 3.2.2 → 4.0.0

package/README.md

@@ -9,7 +9,7 @@ npm install katanakit-js
 # or
 bun add katanakit-js
 # or
-pnpm add katanakit-js
+bun add katanakit-js
 ```
 
 ### CDN (ESM)
@@ -171,14 +171,66 @@ if (result.ok) {
 
 ### 6. Build URLs without fetching
 
+`useBuildUrl` constructs a full URL from your registered APIs **without making
+a request**. Use it to generate links, image sources, or pass URLs to libraries
+that handle their own fetching.
+
+#### Generate navigation links
+
 ```ts
 import { useBuildUrl } from "katanakit-js";
 
-const url = useBuildUrl("jsonplaceholder", "postById", {
-  params: { id: 7 },
-  query: { _limit: 3 },
+// Build a download link
+const downloadUrl = useBuildUrl("myApi", "export", {
+  query: { format: "pdf", lang: "es" },
+});
+// → "https://api.myapp.com/v1/export?format=pdf&lang=es"
+
+// Use in a template
+<a href={downloadUrl}>Download PDF</a>
+```
+
+#### Generate image/file URLs
+
+```ts
+// Build an image URL for <img src>
+const avatarUrl = useBuildUrl("myApi", "userAvatar", {
+  params: { id: 42 },
+  query: { size: "large" },
+});
+// → "https://api.myapp.com/v1/users/42/avatar?size=large"
+
+<img src={avatarUrl} alt="User avatar" />
+```
+
+#### Pass to third-party libraries
+
+```ts
+// Charts, maps, analytics — libraries that fetch their own data
+const chartDataUrl = useBuildUrl("myApi", "analytics", {
+  query: { range: "7d", metric: "visits" },
+});
+new Chart(canvas, { data: chartDataUrl });
+```
+
+#### Debug before fetching
+
+```ts
+// See the full URL before making the request
+console.log("Will fetch:", useBuildUrl("myApi", "users", {
+  query: { page: 1, per_page: 20 },
+}));
+// → "https://api.myapp.com/v1/users?page=1&per_page=20"
+```
+
+#### SSR: construct URLs server-side
+
+```ts
+// In Astro, Next.js, or Nuxt server code
+const apiUrl = useBuildUrl("notion", "database", {
+  params: { id: "db-123" },
 });
-// "https://jsonplaceholder.typicode.com/posts/7?_limit=3"
+// Pass to client component or pre-render
 ```
 
 ### 7. FormData and raw bodies
@@ -195,7 +247,7 @@ await usePost("myApi", "upload", form);
 
 ### Full example
 
-See [`examples/api-manager/demo.ts`](https://github.com/senseikatana/katanakit-js/tree/main/examples/api-manager) for a runnable demo
+See [`examples/api-manager/demo.ts`](https://github.com/senseikatana/katanakit/tree/main/examples/api-manager) for a runnable demo
 covering all CRUD operations, auth injection, URL building, and error handling
 against a real API (JSONPlaceholder).
 
@@ -286,6 +338,27 @@ when you want sessions, persistence, and channels (REST, Telegram, WhatsApp). Fa
 follow the Safe Result pattern: they **never throw**. Check `result.ok` and read `result.data`
 or `result.error`.
 
+### When to use Kitt
+
+Kitt is a **lightweight, zero-dependency** wrapper for OpenAI-compatible APIs.
+Use it when you need:
+
+- **One-shot chat** — ask a question, get an answer (`useChat`)
+- **Tool-calling agents** — autonomous loops that read/write/run (`useRunAgent`)
+- **Session-aware bots** — REST, Telegram, WhatsApp channels (`useReply`)
+
+### When to use alternatives
+
+| Need | Use instead |
+|------|------------|
+| Streaming token-by-token | [Vercel AI SDK](https://sdk.vercel.ai) |
+| RAG with embeddings | [LangChain.js](https://js.langchain.com) |
+| Multi-agent orchestration | [CrewAI](https://github.com/crewAIInc/crewAI) |
+| Full chatbot framework | [Botpress](https://botpress.com) |
+
+Kitt stays small (0 dependencies) because it does one thing well:
+**chat completions with tool calls, using any OpenAI-compatible endpoint.**
+
 ### Low-level API
 
 ```ts
@@ -360,7 +433,7 @@ Also on the main barrel:
 | `useResetSession` | `(sessionId) => Promise<void>` |
 | `useCreateMemoryStore` | `() => ConversationStore` |
 
-Then start a channel (see below). Copy keys from [`.env.example`](https://github.com/senseikatana/katanakit-js/blob/main/.env.example):
+Then start a channel (see below). Copy keys from [`.env.example`](https://github.com/senseikatana/katanakit/blob/main/.env.example):
 
 ```env
 DASHSCOPE_API_KEY=
@@ -379,10 +452,10 @@ DATABASE_URL=
 
 | Script | Starts |
 |--------|--------|
-| `pnpm assistant:dev` | REST assistant. Uses Prisma when `DATABASE_URL` is set. |
-| `pnpm telegram:dev` | Telegram long polling. Requires `TELEGRAM_BOT_TOKEN`. |
-| `pnpm whatsapp:dev` | WhatsApp webhook. Requires `WHATSAPP_*`. |
-| `pnpm assistant:demo` | Demo in `examples/assistant/`. Set `KITT_CHANNEL=rest\|telegram\|whatsapp`. |
+| `bun run assistant:dev` | REST assistant. Uses Prisma when `DATABASE_URL` is set. |
+| `bun run telegram:dev` | Telegram long polling. Requires `TELEGRAM_BOT_TOKEN`. |
+| `bun run whatsapp:dev` | WhatsApp webhook. Requires `WHATSAPP_*`. |
+| `bun run assistant:demo` | Demo in `examples/assistant/`. Set `KITT_CHANNEL=rest\|telegram\|whatsapp`. |
 
 ### REST
 
@@ -442,7 +515,7 @@ await useStartTelegramPolling();
 2. Send `/newbot` — choose a name and a username.
 3. Copy the token.
 4. Set `TELEGRAM_BOT_TOKEN`.
-5. Run `pnpm telegram:dev` (long polling, no public URL).
+5. Run `bun run telegram:dev` (long polling, no public URL).
 6. Optional webhook: expose HTTPS and call `useHandleTelegramUpdate(update)` on inbound updates.
 
 ### WhatsApp (Meta Cloud API)
@@ -465,7 +538,7 @@ useStartWhatsApp();
 2. Add the WhatsApp product.
 3. Copy the temporary or permanent token, the Phone number ID, and the **App Secret**.
 4. Set `WHATSAPP_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_VERIFY_TOKEN`, and `WHATSAPP_APP_SECRET`.
-5. Run `pnpm whatsapp:dev`.
+5. Run `bun run whatsapp:dev`.
 6. Expose public HTTPS (Cloudflare Tunnel or ngrok) to `GET`/`POST` `/whatsapp/webhook`.
 7. In Meta, set the webhook URL and verify token; subscribe to `messages`.
 
@@ -496,11 +569,11 @@ owns the database, run `prisma contract emit` then `prisma db init` in that app.
 
 ### Real use case
 
-[`examples/assistant/`](https://github.com/senseikatana/katanakit-js/tree/main/examples/assistant) is a generic digital assistant with two demo tools:
+[`examples/assistant/`](https://github.com/senseikatana/katanakit/tree/main/examples/assistant) is a generic digital assistant with two demo tools:
 `readFile` on `knowledge-base.md` and `saveNote` to `notes.jsonl`.
 
 ```bash
-pnpm assistant:demo
+bun run assistant:demo
 # KITT_CHANNEL=rest|telegram|whatsapp
 ```
 
@@ -540,7 +613,7 @@ const result = await useGetApi("pokeapi", "pokemonById", { params: { id: 25 } })
 
 ```ts
 import { useLogger, useInitApis, useGetApi } from "katanakit-js";
-import { useKatanaFetch } from "katanakit-js/adapters/vue";   // Vue only
+import { useRequest } from "katanakit-js/adapters/vue";   // Vue only
 import { useUnwrap } from "katanakit-js/adapters/nuxt";         // Nuxt only
 ```
 
@@ -559,7 +632,7 @@ See [Getting Started](https://senseikatana.com/katanakit-js/docs/guides/getting-
 |---------|--------|-------------|
 | **Express** | `katanakit-js/adapters/express` | Reference server with CORS and hardened headers |
 | **Nuxt** | `katanakit-js/adapters/nuxt` | `useUnwrap`, `useSafeResponse`, `useEventResponse` |
-| **Vue** | `katanakit-js/adapters/vue` | `useKatanaFetch` composable with reactivity |
+| **Vue** | `katanakit-js/adapters/vue` | `useRequest` composable with reactivity |
 | **Astro** | `katanakit-js` or `katanakit-js/adapters/astro` | `AstroService`, `RssService` |
 | **Assistant** | `katanakit-js/adapters/assistant` | REST digital assistant (`useStartAssistant`) |
 | **Telegram** | `katanakit-js/adapters/telegram` | BotFather bot (`useInitTelegram`, `useStartTelegramPolling`) |
@@ -775,15 +848,15 @@ if (users.ok) users.data.results.forEach(u => console.log(u.name));
 
 | Framework | Example | Description |
 |-----------|---------|-------------|
-| **Vue 3** | [`examples/notion/vue-blog.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/vue-blog.vue) | Blog listing with `useQuery` composable |
-| **Vue 3** | [`examples/notion/vue-post.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/vue-post.vue) | Single post view |
-| **Nuxt 3** | [`examples/notion/nuxt-blog.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/nuxt-blog.vue) | SSR blog listing with `useAsyncData` |
-| **Nuxt 3** | [`examples/notion/nuxt-post.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/nuxt-post.vue) | SSR single post view |
-| **Astro** | [`examples/notion/astro-blog.astro`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/astro-blog.astro) | Static blog listing |
-| **Astro** | [`examples/notion/astro-[slug].astro`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/astro-[slug].astro) | Dynamic `[slug]` route |
-| **Next.js** | [`examples/notion/next-blog.tsx`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/next-blog.tsx) | Server component blog listing |
-| **Next.js** | [`examples/notion/next-[slug].tsx`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/next-[slug].tsx) | Dynamic `[slug]` page |
-| **Node.js** | [`examples/notion/demo.ts`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/demo.ts) | Runnable demo covering all Notion operations |
+| **Vue 3** | [`examples/notion/vue-blog.vue`](https://github.com/senseikatana/katanakit/tree/main/examples/notion/vue-blog.vue) | Blog listing with `useQuery` composable |
+| **Vue 3** | [`examples/notion/vue-post.vue`](https://github.com/senseikatana/katanakit/tree/main/examples/notion/vue-post.vue) | Single post view |
+| **Nuxt 3** | [`examples/notion/nuxt-blog.vue`](https://github.com/senseikatana/katanakit/tree/main/examples/notion/nuxt-blog.vue) | SSR blog listing with `useAsyncData` |
+| **Nuxt 3** | [`examples/notion/nuxt-post.vue`](https://github.com/senseikatana/katanakit/tree/main/examples/notion/nuxt-post.vue) | SSR single post view |
+| **Astro** | [`examples/notion/astro-blog.astro`](https://github.com/senseikatana/katanakit/tree/main/examples/notion/astro-blog.astro) | Static blog listing |
+| **Astro** | [`examples/notion/astro-[slug].astro`](https://github.com/senseikatana/katanakit/tree/main/examples/notion/astro-[slug].astro) | Dynamic `[slug]` route |
+| **Next.js** | [`examples/notion/next-blog.tsx`](https://github.com/senseikatana/katanakit/tree/main/examples/notion/next-blog.tsx) | Server component blog listing |
+| **Next.js** | [`examples/notion/next-[slug].tsx`](https://github.com/senseikatana/katanakit/tree/main/examples/notion/next-[slug].tsx) | Dynamic `[slug]` page |
+| **Node.js** | [`examples/notion/demo.ts`](https://github.com/senseikatana/katanakit/tree/main/examples/notion/demo.ts) | Runnable demo covering all Notion operations |
 
 ### WordPress
 
@@ -1114,15 +1187,49 @@ const full = await useWpGetPosts({
 
 | Framework | Example | Description |
 |-----------|---------|-------------|
-| **Vue 3** | [`examples/wordpress/vue-blog.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/vue-blog.vue) | Blog listing with categories, featured images, `_embed` |
-| **Vue 3** | [`examples/wordpress/vue-post.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/vue-post.vue) | Single post view with embedded author |
-| **Nuxt 3** | [`examples/wordpress/nuxt-blog.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/nuxt-blog.vue) | SSR blog listing with `useAsyncData` |
-| **Nuxt 3** | [`examples/wordpress/nuxt-post.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/nuxt-post.vue) | SSR single post view |
-| **Astro** | [`examples/wordpress/astro-blog.astro`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/astro-blog.astro) | Static blog listing |
-| **Astro** | [`examples/wordpress/astro-[slug].astro`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/astro-[slug].astro) | Dynamic `[slug]` route |
-| **Next.js** | [`examples/wordpress/next-blog.tsx`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/next-blog.tsx) | Server component blog listing |
-| **Next.js** | [`examples/wordpress/next-[slug].tsx`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/next-[slug].tsx) | Dynamic `[slug]` page |
-| **Node.js** | [`examples/wordpress/demo.ts`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/demo.ts) | Runnable demo covering all WP operations, `_fields`, `_embed`, ACF |
+| **Vue 3** | [`examples/wordpress/vue-blog.vue`](https://github.com/senseikatana/katanakit/tree/main/examples/wordpress/vue-blog.vue) | Blog listing with categories, featured images, `_embed` |
+| **Vue 3** | [`examples/wordpress/vue-post.vue`](https://github.com/senseikatana/katanakit/tree/main/examples/wordpress/vue-post.vue) | Single post view with embedded author |
+| **Nuxt 3** | [`examples/wordpress/nuxt-blog.vue`](https://github.com/senseikatana/katanakit/tree/main/examples/wordpress/nuxt-blog.vue) | SSR blog listing with `useAsyncData` |
+| **Nuxt 3** | [`examples/wordpress/nuxt-post.vue`](https://github.com/senseikatana/katanakit/tree/main/examples/wordpress/nuxt-post.vue) | SSR single post view |
+| **Astro** | [`examples/wordpress/astro-blog.astro`](https://github.com/senseikatana/katanakit/tree/main/examples/wordpress/astro-blog.astro) | Static blog listing |
+| **Astro** | [`examples/wordpress/astro-[slug].astro`](https://github.com/senseikatana/katanakit/tree/main/examples/wordpress/astro-[slug].astro) | Dynamic `[slug]` route |
+| **Next.js** | [`examples/wordpress/next-blog.tsx`](https://github.com/senseikatana/katanakit/tree/main/examples/wordpress/next-blog.tsx) | Server component blog listing |
+| **Next.js** | [`examples/wordpress/next-[slug].tsx`](https://github.com/senseikatana/katanakit/tree/main/examples/wordpress/next-[slug].tsx) | Dynamic `[slug]` page |
+| **Node.js** | [`examples/wordpress/demo.ts`](https://github.com/senseikatana/katanakit/tree/main/examples/wordpress/demo.ts) | Runnable demo covering all WP operations, `_fields`, `_embed`, ACF |
+
+## Contributing
+
+We welcome contributions from the community! Whether it's fixing a bug, adding
+a feature, or improving documentation, every contribution helps make KatanaKit
+better for everyone.
+
+### Quick start
+
+```bash
+git clone https://github.com/senseikatana/katanakit.git
+cd katanakit-js
+git checkout dev
+bun install
+bun run check  # verify everything works
+```
+
+### Ways to contribute
+
+- **Report bugs** — [Open an issue](https://github.com/senseikatana/katanakit/issues) with a clear description and reproduction steps
+- **Suggest features** — [Start a discussion](https://github.com/senseikatana/katanakit/discussions) to propose new ideas
+- **Submit a PR** — Fork the repo, create a branch from `dev`, make your changes, and open a PR
+- **Improve docs** — Fix typos, add examples, or clarify explanations
+- **Add adapters** — Build integrations for new APIs or frameworks
+
+### PR guidelines
+
+1. Branch from `dev` (not `main`)
+2. Follow the `use*` naming convention
+3. Add TypeScript types in `src/types/index.ts`
+4. Run `bun run check` before submitting
+5. Update `CHANGELOG.md` if the public API changed
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development contract.
 
 ## Documentation
 

package/dist/adapters/angular/fetch.d.ts

@@ -0,0 +1,37 @@
+import { type Signal } from "@angular/core";
+import type { ApiError, UrlOptions } from "../../types/index.js";
+/** Reactive state exposed by the {@link useRequest} factory (Angular signals). */
+export interface RequestState<T = unknown> {
+    data: Signal<T | null>;
+    error: Signal<ApiError | null>;
+    loading: Signal<boolean>;
+    refetch: () => Promise<void>;
+}
+/**
+ * Angular signal factory that wraps KatanaKit's HTTP GET. Bridges the Safe
+ * Result pattern to Angular signals and never throws on HTTP errors.
+ *
+ * Must be called within an injection context (component field initializer,
+ * constructor, or service) so it can abort in-flight requests via `DestroyRef`.
+ * Stale responses are ignored via a request version counter.
+ *
+ * @param apiName - Name of the registered API (see `useInitApis`).
+ * @param endpointName - Name of the endpoint inside that API.
+ * @param options - Optional `UrlOptions` (path/query params).
+ * @returns Signals `{ data, error, loading }` plus `refetch`.
+ *
+ * @example
+ * ```ts
+ * import { Component } from "@angular/core";
+ * import { useRequest } from "katanakit-js/adapters/angular";
+ *
+ * @Component({ selector: "app-pokemon", template: `@if (loading()) { Loading… } @else { {{ data()?.name }} }` })
+ * export class PokemonComponent {
+ *   readonly result = useRequest<{ name: string }>("pokeapi", "pokemonById", { params: { id: 25 } });
+ *   readonly data = this.result.data;
+ *   readonly loading = this.result.loading;
+ * }
+ * ```
+ */
+export declare function useRequest<T>(apiName: string, endpointName: string, options?: UrlOptions): RequestState<T>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/adapters/angular/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../../src/adapters/angular/fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,MAAM,EAAU,MAAM,eAAe,CAAC;AAGxE,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEjE,kFAAkF;AAClF,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACxC,IAAI,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACzB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC3B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,UAAU,GAClB,YAAY,CAAC,CAAC,CAAC,CA6CjB"}

package/dist/adapters/angular/fetch.js

@@ -0,0 +1,67 @@
+import { DestroyRef, inject, signal } from "@angular/core";
+import { useFetch } from "../../core/services/http.service.js";
+/**
+ * Angular signal factory that wraps KatanaKit's HTTP GET. Bridges the Safe
+ * Result pattern to Angular signals and never throws on HTTP errors.
+ *
+ * Must be called within an injection context (component field initializer,
+ * constructor, or service) so it can abort in-flight requests via `DestroyRef`.
+ * Stale responses are ignored via a request version counter.
+ *
+ * @param apiName - Name of the registered API (see `useInitApis`).
+ * @param endpointName - Name of the endpoint inside that API.
+ * @param options - Optional `UrlOptions` (path/query params).
+ * @returns Signals `{ data, error, loading }` plus `refetch`.
+ *
+ * @example
+ * ```ts
+ * import { Component } from "@angular/core";
+ * import { useRequest } from "katanakit-js/adapters/angular";
+ *
+ * @Component({ selector: "app-pokemon", template: `@if (loading()) { Loading… } @else { {{ data()?.name }} }` })
+ * export class PokemonComponent {
+ *   readonly result = useRequest<{ name: string }>("pokeapi", "pokemonById", { params: { id: 25 } });
+ *   readonly data = this.result.data;
+ *   readonly loading = this.result.loading;
+ * }
+ * ```
+ */
+export function useRequest(apiName, endpointName, options) {
+    const destroyRef = inject(DestroyRef);
+    const data = signal(null);
+    const error = signal(null);
+    const loading = signal(true);
+    let version = 0;
+    let controller = null;
+    let disposed = false;
+    const refetch = async () => {
+        const current = ++version;
+        controller?.abort();
+        const next = new AbortController();
+        controller = next;
+        loading.set(true);
+        error.set(null);
+        const result = await useFetch(apiName, endpointName, {
+            method: "GET",
+            urlOptions: options,
+            signal: next.signal,
+        });
+        if (disposed || current !== version)
+            return;
+        if (result.ok) {
+            data.set(result.data);
+            error.set(null);
+        }
+        else if (!next.signal.aborted) {
+            error.set(result.error);
+        }
+        loading.set(false);
+    };
+    destroyRef.onDestroy(() => {
+        disposed = true;
+        controller?.abort();
+    });
+    void refetch();
+    return { data, error, loading, refetch };
+}
+//# sourceMappingURL=fetch.js.map

package/dist/adapters/angular/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../../src/adapters/angular/fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAe,MAAM,EAAE,MAAM,eAAe,CAAC;AAExE,OAAO,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AAW/D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,UAAU,CACzB,OAAe,EACf,YAAoB,EACpB,OAAoB;IAEpB,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IAEtC,MAAM,IAAI,GAAG,MAAM,CAAW,IAAI,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,MAAM,CAAkB,IAAI,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7B,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,UAAU,GAA2B,IAAI,CAAC;IAC9C,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,MAAM,OAAO,GAAG,KAAK,IAAmB,EAAE;QACzC,MAAM,OAAO,GAAG,EAAE,OAAO,CAAC;QAC1B,UAAU,EAAE,KAAK,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,IAAI,eAAe,EAAE,CAAC;QACnC,UAAU,GAAG,IAAI,CAAC;QAElB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEhB,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAI,OAAO,EAAE,YAAY,EAAE;YACvD,MAAM,EAAE,KAAK;YACb,UAAU,EAAE,OAAO;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM;SACnB,CAAC,CAAC;QAEH,IAAI,QAAQ,IAAI,OAAO,KAAK,OAAO;YAAE,OAAO;QAE5C,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACtB,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;aAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACjC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC,CAAC;IAEF,UAAU,CAAC,SAAS,CAAC,GAAG,EAAE;QACzB,QAAQ,GAAG,IAAI,CAAC;QAChB,UAAU,EAAE,KAAK,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,KAAK,OAAO,EAAE,CAAC;IAEf,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC1C,CAAC"}

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

@@ -0,0 +1,4 @@
+export * from "./fetch.js";
+export * from "./query.js";
+export * from "./watch.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/angular/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/adapters/angular/index.js

@@ -0,0 +1,4 @@
+export * from "./fetch.js";
+export * from "./query.js";
+export * from "./watch.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/angular/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/adapters/angular/query.d.ts

@@ -0,0 +1,107 @@
+import { type Signal } from "@angular/core";
+import { type QueryClient, type QueryKey, type QueryState } from "../../core/services/query.service.js";
+import type { ApiError, FetchResult } from "../../types/index.js";
+/** Configuration for `useQuery` (Angular signal factory). */
+export interface UseQueryConfig<T = unknown> {
+    /** Cache key (stable array). */
+    queryKey: QueryKey;
+    /** Fetcher function returning a Safe Result. */
+    queryFn: () => Promise<FetchResult<T>>;
+    /** Time in ms before cached data is stale (default: 0). */
+    staleTime?: number;
+    /** Time in ms to keep unused data (default: 5 min). */
+    cacheTime?: number;
+    /** Retry count on failure (default: 3). */
+    retry?: number;
+    /** Base delay for exponential backoff (default: 1000). */
+    retryDelay?: number;
+    /** Whether the query is enabled (default: true). */
+    enabled?: boolean;
+}
+/** Reactive return value of `useQuery` (Angular signals). */
+export interface UseQueryReturn<T = unknown> {
+    data: Signal<T | null>;
+    error: Signal<ApiError | null>;
+    isLoading: Signal<boolean>;
+    isSuccess: Signal<boolean>;
+    isError: Signal<boolean>;
+    isStale: Signal<boolean>;
+    status: Signal<QueryState<T>["status"]>;
+    /** Manually refetch the query. */
+    refetch: () => Promise<void>;
+}
+/** Configuration for `useMutation`. */
+export interface UseMutationConfig<TData = unknown, TVariables = unknown> {
+    mutationFn: (variables: TVariables) => Promise<FetchResult<TData>>;
+    onSuccess?: (data: TData, variables: TVariables) => void;
+    onError?: (error: ApiError, variables: TVariables) => void;
+    onSettled?: (data: TData | null, error: ApiError | null, variables: TVariables) => void;
+}
+/** Reactive return value of `useMutation`. */
+export interface UseMutationReturn<TData = unknown, TVariables = unknown> {
+    data: Signal<TData | null>;
+    error: Signal<ApiError | null>;
+    isLoading: Signal<boolean>;
+    isSuccess: Signal<boolean>;
+    isError: Signal<boolean>;
+    status: Signal<"idle" | "loading" | "success" | "error">;
+    /** Execute the mutation. */
+    mutate: (variables: TVariables) => Promise<void>;
+    /** Reset the mutation state. */
+    reset: () => void;
+}
+/**
+ * Angular signal factory that wraps the {@link QueryClient}.
+ * Integrates with the API manager — your `queryFn` typically calls `useGetApi`
+ * or `useFetch` and returns the Safe Result.
+ *
+ * Must be called within an injection context (component field initializer,
+ * constructor, or a service) so the returned query can auto-cleanup via
+ * `DestroyRef`. Requires Angular 16+ signals.
+ *
+ * @param config - Query configuration.
+ * @param client - Optional QueryClient instance (uses global singleton by default).
+ * @returns Signals `{ data, error, isLoading, isSuccess, isError, isStale, status }` plus `refetch`.
+ *
+ * @example
+ * ```ts
+ * import { Component, inject } from "@angular/core";
+ * import { useQuery } from "katanakit-js/adapters/angular";
+ * import { useGetApi } from "katanakit-js";
+ *
+ * @Component({ selector: "app-pokemon", template: `@if (isLoading()) { Loading… } @else { {{ data()?.name }} }` })
+ * export class PokemonComponent {
+ *   readonly data = useQuery({ queryKey: ["pokemon", 25], queryFn: () => useGetApi("pokeapi", "pokemonById", { params: { id: 25 } }) }).data;
+ * }
+ * ```
+ */
+export declare function useQuery<T>(config: UseQueryConfig<T>, client?: QueryClient): UseQueryReturn<T>;
+/**
+ * Angular signal factory for mutations (POST/PUT/PATCH/DELETE).
+ * Does not cache — returns a `mutate` function that executes the mutation.
+ *
+ * Must be called within an injection context. Requires Angular 16+ signals.
+ *
+ * @param config - Mutation configuration.
+ * @returns Signals plus `{ mutate, reset }`.
+ *
+ * @example
+ * ```ts
+ * import { Component } from "@angular/core";
+ * import { useMutation, useQueryClient } from "katanakit-js/adapters/angular";
+ * import { usePost } from "katanakit-js";
+ *
+ * @Component({ selector: "app-create", template: `<button [disabled]="isLoading()" (click)="mutate('Ada')">Create</button>` })
+ * export class CreateUserComponent {
+ *   private readonly qc = useQueryClient();
+ *   readonly result = useMutation({
+ *     mutationFn: (name: string) => usePost("api", "createUser", { name }),
+ *     onSuccess: () => this.qc.invalidateQueries({ queryKey: ["users"] }),
+ *   });
+ *   readonly isLoading = this.result.isLoading;
+ *   readonly mutate = this.result.mutate;
+ * }
+ * ```
+ */
+export declare function useMutation<TData = unknown, TVariables = unknown>(config: UseMutationConfig<TData, TVariables>): UseMutationReturn<TData, TVariables>;
+//# sourceMappingURL=query.d.ts.map

package/dist/adapters/angular/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/adapters/angular/query.ts"],"names":[],"mappings":"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"}