arthron 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lapidix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,298 @@
-# Temporary Holding Version
+# arthron
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A `fetch` client you assemble from plugins.
+
+```ts
+import { arthron, logging, retry, timeout } from "arthron";
+
+const api = arthron({
+  baseURL: "https://api.example.com",
+  use: [logging(), timeout(10_000), retry()],
+});
+
+const user = await api.get("/me").json<User>();
+```
+
+- **Plain `Response` in, plain `Response` out.** No wrapper type to learn. `.json<T>()` and friends are there when you want the body.
+- **Two kinds of plugin, kept apart by the types.** Middleware wraps the request and controls the flow — it can call `next` again to retry. Interceptors transform one value and return it; they cannot retry, skip, or swallow. Auth refresh, retry and timeouts are middleware. Headers, logging and error mapping are interceptors.
+- **One error type, two causes.** `ArthronError` means the server said no (`!response.ok`) or the network failed (`status: 0`). Everything else — cancellation, a bug in a plugin — is rethrown as-is.
+- Zero dependencies. ESM and CJS. TypeScript types included. Node 18+ and browsers.
+
+## Install
+
+```sh
+npm i arthron
+```
+
+## Usage
+
+### Create a client
+
+```ts
+const api = arthron({
+  baseURL: "https://api.example.com", // prefix for relative paths
+  headers: { accept: "application/json" }, // defaults; per-call headers win
+  credentials: "include", // only if you need cookies cross-origin
+  use: [retry()], // plugins, outermost first
+});
+```
+
+Every field is optional. Without `baseURL`, only absolute URLs are accepted.
+
+### Make requests
+
+```ts
+await api.get("/users", { params: { page: 2 } }); // → Response
+await api.post("/users", { name: "kim" }); // object body → JSON
+await api.post("/upload", formData); // FormData/Blob/string/stream → sent as-is
+await api.put("/users/1", { name: "lee" });
+await api.patch("/users/1", { name: "lee" });
+await api.delete("/users/1");
+await api.head("/users/1");
+await api.request("/users", { method: "OPTIONS" });
+```
+
+Each call returns `Promise<Response>` with body helpers attached:
+
+```ts
+const res = await api.get("/me"); // Response — status, headers, body untouched
+const user = await api.get("/me").json<User>(); // body parsed; T is a cast, not validation
+const text = await api.get("/robots.txt").text();
+const blob = await api.get("/export").blob();
+const stream = (await api.post("/chat", prompt)).body; // ReadableStream
+for await (const e of api.post("/chat", prompt).sse()) {} // see "Stream responses"
+```
+
+`init` accepts everything `fetch` does (`signal`, `cache`, `headers`, …) plus `params`, a query object whose `null`/`undefined` values are dropped.
+
+### Stream responses
+
+```ts
+// Server-sent events — one event per `for await` step
+for await (const { event, data } of api.post("/v1/chat/completions", body).sse()) {
+  if (data === "[DONE]") break; // provider sentinel; arthron does not interpret it
+  process.stdout.write(JSON.parse(data).choices[0].delta.content ?? "");
+}
+
+// Newline-delimited JSON (Ollama, many log endpoints)
+for await (const row of api.get("/logs").ndjson<LogRow>()) console.log(row);
+```
+
+`.sse()` follows the EventSource spec (multi-line `data:` joined with `\n`, comments ignored, dispatch on blank line). Both helpers honour `signal` and `timeout` while the body is being read.
+
+### Handle errors
+
+```ts
+import { isArthronError } from "arthron";
+
+try {
+  await api.get("/users/404");
+} catch (e) {
+  if (isArthronError(e)) {
+    e.status; // 404, or 0 when the network failed
+    e.data; // parsed body: JSON, else text, else undefined
+    e.message; // from the body (`message` → `error` → `error.message` → `detail`), else "Request failed with status 404"
+    e.response; // the original Response, still readable
+  }
+}
+```
+
+A request that is aborted or times out rejects with the browser's `AbortError` / `TimeoutError`, not an `ArthronError`.
+
+### Derive clients
+
+Clients are immutable. `use` and `extend` return a new client and leave the original alone.
+
+```ts
+const base = arthron({ baseURL: API, use: [logging(), retry()] });
+const authed = base.use(auth()); // base + auth
+const admin = authed.extend({ headers: { "x-role": "admin" } }); // authed + header
+```
+
+`extend` shallow-merges the config, merges headers case-insensitively (child wins), and appends plugins.
+
+## Plugins
+
+A plugin is an object with any of four slots:
+
+```ts
+type Plugin = {
+  name?: string;
+  middleware?: (ctx: RequestContext, next: (ctx: RequestContext) => Promise<Response>) => Promise<Response>;
+  request?: (ctx: RequestContext) => RequestContext | Promise<RequestContext>;
+  response?: (res: Response, ctx: RequestContext) => Response | Promise<Response>;
+  error?: (err: ArthronError, ctx: RequestContext) => ArthronError | Promise<ArthronError>;
+};
+
+type RequestContext = { url: string; init: RequestInit };
+```
+
+How one request runs:
+
+```
+middleware 1
+  middleware 2
+    attempt ─ request interceptors → fetch → response interceptors
+                                           ↘ error interceptors → throw
+```
+
+| | Middleware | Interceptor |
+|---|---|---|
+| Runs | Once per call, wrapping everything below | Once per attempt |
+| Gets | `ctx` and `next` | A value: context, `Response`, or `ArthronError` |
+| Can | Call `next` again (retry), skip it, add a deadline | Return a changed value |
+| Cannot | — | Retry, skip, or stop the error from being thrown |
+| Examples | `retry`, `timeout`, auth refresh | auth header, tracing id, error mapping |
+
+Every attempt starts from a fresh copy of the context, so a header set by an interceptor on attempt one does not leak into attempt two.
+
+### Built in
+
+#### `retry(options)`
+
+Re-runs the attempt on network failure or a retryable status. Because it re-runs the whole attempt, request interceptors run again — a refreshed token or a new trace id is picked up automatically.
+
+| option | default | |
+|---|---|---|
+| `retries` | `2` | retries after the first attempt (3 requests total) |
+| `retryOn` | `[408, 429, 500, 502, 503, 504]` | network failures (`status: 0`) are always retried |
+| `methods` | `GET HEAD OPTIONS PUT DELETE` | case-insensitive |
+| `delay` | `(retry) => 300 * 2 ** retry` | ms; `retry` counts from 0 |
+| `maxRetryAfter` | `60_000` | a `Retry-After` longer than this means "don't retry" |
+
+Honours `Retry-After` (seconds or HTTP date). Never retries a `ReadableStream` body or an aborted request.
+
+#### `timeout(ms)`
+
+Aborts the attempt after `ms`, counted until the body has been fully read — a server that sends headers and then stalls still trips it. Rejects with a `TimeoutError`, which `retry` and error interceptors ignore. Combines with a `signal` you pass yourself.
+
+```ts
+arthron({ use: [retry(), timeout(5_000)] }); // 5 s per attempt
+arthron({ use: [timeout(5_000), retry()] }); // 5 s for all attempts together
+```
+
+#### `logging(options)`
+
+```
+[arthron] → GET https://api.example.com/users
+[arthron] ← GET https://api.example.com/users 200 42ms
+[arthron] ✕ GET https://api.example.com/users 503 1203ms
+```
+
+| option | default | |
+|---|---|---|
+| `enabled` | `true` | pass `process.env.NODE_ENV !== "production"` or similar — arthron never reads env |
+| `logger` | `console` | anything with `log` and `error` |
+| `onEvent` | — | receive `{ phase, method, path, status, ms, error }` instead of console lines |
+
+Query strings and `user:pass@` are never printed. Cancellations are not logged.
+
+### Write your own
+
+`definePlugin`, `defineMiddleware` and `defineInterceptor.{request,response,error}` are identity functions that give you the parameter types without annotations.
+
+**Refresh a session on 401, then redo the request.** The refresh is flow, so it is middleware. The header is a value, so it is a request interceptor — and because `next` re-runs the interceptors, the retried request carries the new token without extra code.
+
+```ts
+import { definePlugin, isArthronError } from "arthron";
+
+export const auth = (store: { token: () => string | null; refresh: () => Promise<void> }) =>
+  definePlugin({
+    name: "auth",
+    request: (ctx) => {
+      const token = store.token();
+      if (!token) return ctx;
+      return { ...ctx, init: { ...ctx.init, headers: { ...ctx.init.headers, authorization: `Bearer ${token}` } } };
+    },
+    middleware: async (ctx, next) => {
+      try {
+        return await next(ctx);
+      } catch (e) {
+        if (!isArthronError(e) || e.status !== 401) throw e;
+        await store.refresh(); // if this throws, the caller sees it
+        return next(ctx);
+      }
+    },
+  });
+```
+
+**Send users to an error page.** Error interceptors can look and act, but the error is thrown regardless — which is what you want for a side effect like navigation.
+
+```ts
+import { defineInterceptor } from "arthron";
+
+export const errorRedirect = (navigate: (to: string) => void) =>
+  defineInterceptor.error((err, ctx) => {
+    if ((ctx.init.method ?? "GET") !== "GET") return err;
+    if (err.status === 404) navigate("/not-found");
+    if (err.status >= 500) navigate("/error");
+    return err;
+  });
+
+api.use({ error: errorRedirect(router.push) });
+```
+
+**Attach a trace id.** A one-line request interceptor.
+
+```ts
+api.use({ request: (ctx) => ({ ...ctx, init: { ...ctx.init, headers: { ...ctx.init.headers, "x-trace-id": crypto.randomUUID() } } }) });
+```
+
+## Reference
+
+### `arthron(config)`
+
+```ts
+type ArthronConfig = {
+  baseURL?: string;
+  headers?: HeadersInit;
+  credentials?: RequestCredentials;
+  fetch?: typeof fetch; // inject for tests or a polyfill; resolved per request
+  use?: Plugin[];
+  errorMessage?: (data: unknown, res: Response) => string | undefined;
+};
+```
+
+### Client
+
+```ts
+get(path, init) · delete(path, init) · head(path, init)
+post(path, body, init) · put(path, body, init) · patch(path, body, init)
+request(path, { method, body, ...init })
+use(...plugins) → new client
+extend(config) → new client
+```
+
+All arguments after `path` are optional, except `method` in `request`.
+
+### `ArthronError`
+
+```ts
+class ArthronError extends Error {
+  status: number; // 0 for network failures
+  statusText: string;
+  headers: Headers;
+  data: unknown;
+  response?: Response; // absent for network failures
+  request: RequestContext;
+  cause?: unknown; // the underlying error for network failures
+}
+```
+
+### Rules worth knowing
+
+- **URLs are joined by string concatenation.** `baseURL: "https://a/v1"` + `"/users"` → `https://a/v1/users`. The `/v1` survives, unlike with `new URL()`. Absolute URLs bypass `baseURL`.
+- **Bodies.** `string`, `FormData`, `Blob`, `ArrayBuffer`/views, `URLSearchParams` and `ReadableStream` go through untouched. Anything else — including `null` — becomes JSON with `content-type: application/json` unless you set a content type. `GET`/`HEAD` with a body is rejected with a `TypeError`.
+- **`credentials` is not set unless you set it.** Cross-origin cookies need `credentials: "include"`.
+- **Response bodies are single-use.** A response interceptor that wants to inspect the body must `res.clone()`; one that changes it returns a new `Response`.
+- **Argument errors reject, they don't throw.** No `baseURL` with a relative path, a `BigInt` in a JSON body, a missing `method` in `request` — all surface as a rejected promise.
+
+## For tooling and agents
+
+- `llms.txt` ships in the package — a compressed API reference meant to be read by LLM-based tools (`node_modules/arthron/llms.txt`).
+- `examples/` holds type-checked, runnable recipes: LLM streaming, auth refresh, upload/download.
+- Error messages state the fix (`… — pass baseURL in arthron({ baseURL }) or use an absolute URL`).
+
+## License
+
+MIT