katanakit-js 2.14.0 → 2.14.2

package/README.md

@@ -58,6 +58,147 @@ if (result.ok) {
 }
 ```
 
+## HTTP Client — API Manager
+
+The core of KatanaKit is a **typed, registry-based HTTP client**. You register
+your APIs once, then fetch by name — the client builds URLs, handles serialization,
+and returns a **Safe Result** (`{ ok, data, error }`) that never throws on HTTP errors.
+
+### 1. Register your APIs
+
+```ts
+import { useInitApis } from "katanakit-js";
+
+useInitApis({
+  // A public REST API
+  jsonplaceholder: {
+    baseUri: "https://jsonplaceholder.typicode.com",
+    endpoints: {
+      posts: "/posts",
+      postById: "/posts/:id",
+    },
+    // Applied automatically to specific endpoints (overridable per-call)
+    defaultQueryParams: {
+      posts: { _limit: 10 },
+    },
+  },
+
+  // Your own backend
+  myApi: {
+    baseUri: "https://api.myapp.com/v1",
+    endpoints: {
+      users: "/users",
+      userById: "/users/:id",
+      createUser: "/users",
+    },
+  },
+});
+```
+
+### 2. GET — list and read
+
+```ts
+import { useGetApi } from "katanakit-js";
+
+// List (uses defaultQueryParams: _limit=10)
+const list = await useGetApi<{ id: number; title: string }[]>("jsonplaceholder", "posts");
+if (list.ok) console.log(list.data);
+
+// Read by ID — :id is replaced by params
+const post = await useGetApi<{ title: string }>("jsonplaceholder", "postById", {
+  params: { id: 1 },
+});
+if (post.ok) console.log(post.data.title);
+
+// Override default query params
+const filtered = await useGetApi("jsonplaceholder", "posts", {
+  query: { _limit: 5, userId: 1 },
+});
+```
+
+### 3. POST, PUT, PATCH, DELETE
+
+```ts
+import { usePost, usePut, usePatch, useDelete } from "katanakit-js";
+
+// POST — body is auto-serialized to JSON
+const created = await usePost<{ id: number }>("myApi", "createUser", {
+  name: "Alice",
+  email: "alice@example.com",
+});
+
+// PUT — full replacement (body + path params)
+const updated = await usePut("myApi", "userById", { name: "Bob" }, { params: { id: 42 } });
+
+// PATCH — partial update
+const patched = await usePatch("myApi", "userById", { name: "Charlie" }, { params: { id: 42 } });
+
+// DELETE
+const deleted = await useDelete("myApi", "userById", { params: { id: 42 } });
+```
+
+### 4. Auth tokens — inject headers per call
+
+There's no global interceptor — pass `headers` directly. This keeps things explicit and testable.
+
+```ts
+const result = await useFetch("myApi", "users", {
+  method: "GET",
+  headers: {
+    Authorization: `Bearer ${getToken()}`,
+  },
+});
+```
+
+### 5. Error handling — the Safe Result pattern
+
+Every fetch returns `{ ok, data, error, status, url }`. No try/catch needed for HTTP failures.
+
+```ts
+const result = await useGetApi("myApi", "userById", { params: { id: 99999 } });
+
+if (result.ok) {
+  // result.data is typed
+  console.log(result.data);
+} else {
+  // result.error is always structured
+  console.log(result.error.status);   // 404
+  console.log(result.error.message);  // "HTTP Error: Not Found"
+  console.log(result.error.details);  // parsed response body (if any)
+  console.log(result.url);            // the URL that was called
+}
+```
+
+### 6. Build URLs without fetching
+
+```ts
+import { useBuildUrl } from "katanakit-js";
+
+const url = useBuildUrl("jsonplaceholder", "postById", {
+  params: { id: 7 },
+  query: { _limit: 3 },
+});
+// "https://jsonplaceholder.typicode.com/posts/7?_limit=3"
+```
+
+### 7. FormData and raw bodies
+
+`usePost`/`usePut`/`usePatch` auto-detect `FormData`, `Blob`, `URLSearchParams`,
+`ArrayBuffer`, `ReadableStream`, and `string` — these are sent as-is without
+forcing `Content-Type: application/json`.
+
+```ts
+const form = new FormData();
+form.append("file", blob);
+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
+covering all CRUD operations, auth injection, URL building, and error handling
+against a real API (JSONPlaceholder).
+
 ## Features
 
 - **Safe Results** — HTTP (and other fallible) operations return `{ data, error, ok }` instead of throwing
@@ -150,7 +291,7 @@ Also on the main barrel:
 | `useResetSession` | `(sessionId) => Promise<void>` |
 | `useCreateMemoryStore` | `() => ConversationStore` |
 
-Then start a channel (see below). Copy keys from [`.env.example`](.env.example):
+Then start a channel (see below). Copy keys from [`.env.example`](https://github.com/senseikatana/katanakit-js/blob/main/.env.example):
 
 ```env
 DASHSCOPE_API_KEY=
@@ -285,7 +426,7 @@ owns the database, run `prisma contract emit` then `prisma db init` in that app.
 
 ### Real use case
 
-[`examples/assistant/`](examples/assistant/) is a generic digital assistant with two demo tools:
+[`examples/assistant/`](https://github.com/senseikatana/katanakit-js/tree/main/examples/assistant) is a generic digital assistant with two demo tools:
 `readFile` on `knowledge-base.md` and `saveNote` to `notes.jsonl`.
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "katanakit-js",
-  "version": "2.14.0",
+  "version": "2.14.2",
   "description": "KatanaKit — a sharp, framework-agnostic TypeScript service toolkit organized with hexagonal architecture.",
   "type": "module",
   "workspaces": [
@@ -73,16 +73,18 @@
     "telegram:dev": "tsx src/adapters/telegram/main.ts",
     "whatsapp:dev": "tsx src/adapters/whatsapp/main.ts",
     "assistant:demo": "tsx examples/assistant/demo.ts",
+    "api:demo": "tsx examples/api-manager/demo.ts",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "check": "biome check ./src && tsc --noEmit && vitest run",
-    "fix": "biome check --write ./src && tsc --noEmit && vitest run",
+    "check": "biome check ./src ./scripts && tsc --noEmit && vitest run",
+    "fix": "biome check --write ./src ./scripts && tsc --noEmit && vitest run",
     "build": "yarn clean && yarn run check && tsc -p tsconfig.json",
     "bump:patch": "yarn version patch --all && git commit -am \"chore: release v$(node -p \"require('./package.json').version\")\" && git tag \"v$(node -p \"require('./package.json').version\")\"",
     "bump:minor": "yarn version minor --all && git commit -am \"chore: release v$(node -p \"require('./package.json').version\")\" && git tag \"v$(node -p \"require('./package.json').version\")\"",
     "bump:major": "yarn version major --all && git commit -am \"chore: release v$(node -p \"require('./package.json').version\")\" && git tag \"v$(node -p \"require('./package.json').version\")\"",
-    "release": "yarn build && yarn bump:patch && yarn npm publish && git push && git push --tags && gh release create \"v$(node -p \"require('./package.json').version\")\" --generate-notes",
-    "release:minor": "yarn build && yarn bump:minor && yarn npm publish && git push && git push --tags && gh release create \"v$(node -p \"require('./package.json').version\")\" --generate-notes",
-    "release:major": "yarn build && yarn bump:major && yarn npm publish && git push && git push --tags && gh release create \"v$(node -p \"require('./package.json').version\")\" --generate-notes",
+    "release": "yarn build && yarn bump:patch && npm publish --access public && git push && git push --tags && node scripts/generate-release-notes.mjs \"v$(node -p \"require('./package.json').version\")\" | gh release create \"v$(node -p \"require('./package.json').version\")\" --notes-file -",
+    "release:minor": "yarn build && yarn bump:minor && npm publish --access public && git push && git push --tags && node scripts/generate-release-notes.mjs \"v$(node -p \"require('./package.json').version\")\" | gh release create \"v$(node -p \"require('./package.json').version\")\" --notes-file -",
+    "release:major": "yarn build && yarn bump:major && npm publish --access public && git push && git push --tags && node scripts/generate-release-notes.mjs \"v$(node -p \"require('./package.json').version\")\" | gh release create \"v$(node -p \"require('./package.json').version\")\" --notes-file -",
+    "notes": "node scripts/generate-release-notes.mjs",
     "version:sync": "node -e \"const v=require('child_process').execSync('git tag --sort=-v:refname').toString().split('\\n')[0].replace('v',''); ['package.json','docs/package.json'].forEach(f=>{const p=require('./'+f); p.version=v; require('fs').writeFileSync(f,JSON.stringify(p,null,2)+'\\n')}); console.log('Synced to v'+v)\"",
     "docs:dev": "yarn workspace katanakit-docs run dev",
     "docs:build": "yarn workspace katanakit-docs run build",
@@ -115,7 +117,7 @@
   "unpkg": "./dist/index.js",
   "jsdelivr": "./dist/index.js",
   "dependencies": {
-    "@js-temporal/polyfill": "^0.5.1",
+    "@js-temporal/polyfill": "0.5.1",
     "@prisma/orm-postgres": "8.0.0-rc.8"
   },
   "peerDependencies": {
@@ -139,21 +141,24 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.12",
-    "@types/bun": "^1.4.2",
-    "@types/cors": "^2.8.19",
-    "@types/express": "^5.0.6",
-    "@types/express-rate-limit": "^6.0.2",
-    "@types/node": "^26.5.0",
-    "cors": "^2.8.6",
-    "dotenv": "^17.4.2",
-    "express": "^5.2.1",
+    "@biomejs/biome": "2.5.12",
+    "@types/cors": "2.8.19",
+    "@types/express": "5.0.6",
+    "@types/express-rate-limit": "6.0.2",
+    "@types/node": "26.5.0",
+    "cors": "2.8.6",
+    "dotenv": "17.4.2",
+    "express": "5.2.1",
     "prisma": "8.0.0-rc.13",
-    "tsx": "^4.23.13",
-    "typescript": "^7.0.2",
-    "vite": "^8.2.2",
-    "vitest": "^5.0.0",
-    "vue": "^3.5.42"
+    "tsx": "4.23.13",
+    "typescript": "7.0.2",
+    "vite": "8.2.2",
+    "vitest": "5.0.0",
+    "vue": "3.5.42"
+  },
+  "resolutions": {
+    "pathe": "2.0.3",
+    "jsbi": "4.3.2"
   },
   "packageManager": "yarn@4.18.0"
 }