@theholocron/http-client 1.15.1 → 1.16.0

package/README.md

@@ -28,16 +28,39 @@ const data = await client.request<{ id: string }>("/widgets/42");
 
 **Config options:**
 
-| Option         | Type                     | Default            | Description                                      |
-| -------------- | ------------------------ | ------------------ | ------------------------------------------------ |
-| `baseUrl`      | `string`                 | —                  | Base URL, trailing slashes trimmed automatically |
-| `token`        | `string`                 | —                  | Auth token                                       |
-| `tokenScheme`  | `"bearer" \| "apikey"`   | `"bearer"`         | How the token is sent                            |
-| `apiKeyHeader` | `string`                 | `"x-api-key"`      | Header name when `tokenScheme` is `"apikey"`     |
-| `extraHeaders` | `Record<string, string>` | —                  | Static headers merged into every request         |
-| `defaultQuery` | `Record<string, string>` | —                  | Query params appended to every request URL       |
-| `vendor`       | `string`                 | —                  | Vendor label for error messages                  |
-| `fetch`        | `typeof fetch`           | `globalThis.fetch` | Override fetch for testing                       |
+| Option         | Type                     | Default            | Description                                       |
+| -------------- | ------------------------ | ------------------ | ------------------------------------------------- |
+| `baseUrl`      | `string`                 | —                  | Base URL, trailing slashes trimmed automatically  |
+| `token`        | `string`                 | —                  | Auth token                                        |
+| `tokenScheme`  | `"bearer" \| "apikey"`   | `"bearer"`         | How the token is sent                             |
+| `apiKeyHeader` | `string`                 | `"x-api-key"`      | Header name when `tokenScheme` is `"apikey"`      |
+| `extraHeaders` | `Record<string, string>` | —                  | Static headers merged into every request          |
+| `defaultQuery` | `Record<string, string>` | —                  | Query params appended to every request URL        |
+| `vendor`       | `string`                 | —                  | Vendor label for error messages                   |
+| `fetch`        | `typeof fetch`           | `globalThis.fetch` | Override fetch for testing                        |
+| `logger`       | `Logger`                 | no-op              | Structured request/response diagnostics (`debug`) |
+| `errors`       | `ErrorSink`              | no-op              | Reports transport failures + unexpected 5xx       |
+
+**Observability seam.** `logger` and `errors` accept the `Logger` / `ErrorSink`
+interfaces from [`@theholocron/observability/core`](https://github.com/theholocron/observability)
+— a seam, not a runtime: the library never calls `Sentry.init` or reads
+credentials itself, and both default to a silent no-op when omitted.
+
+```ts
+import { SentrySink } from "@theholocron/observability/errors";
+import { createLogger } from "@theholocron/observability/logger";
+
+const { logger } = createLogger({ level: "info" });
+const errors = new SentrySink();
+errors.init({ dsn: process.env.SENTRY_DSN!, release: "my-app@1.0.0", environment: "local", tags: {} });
+
+const client = createRestClient({ baseUrl: "...", token: "...", logger, errors });
+```
+
+`errors.captureException` only fires for a transport failure (network error —
+`status: 0`) or an unexpected 5xx; a 4xx is left unreported since those are
+typically expected and already handled by the caller (a 404 from a
+"does this exist" check, etc.).
 
 ### `createResolveToken(config)`
 

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { ErrorSink, Logger } from "@theholocron/observability/core";
 //#region src/auth-resolver.d.ts
 declare class AuthError extends Error {
   name: string;
@@ -79,6 +80,20 @@ interface RestClientConfig {
   vendor?: string;
   /** Override `fetch` for tests. Defaults to `globalThis.fetch`. */
   fetch?: typeof fetch;
+  /**
+   * Structured logger for request/response diagnostics (`debug` level).
+   * Defaults to a no-op — the seam, not a runtime. Bring your own
+   * `@theholocron/observability` `Logger` (or any structurally-compatible
+   * one) to see it.
+   */
+  logger?: Logger;
+  /**
+   * Reports transport failures (network errors, `status: 0`) and unexpected
+   * 5xx responses. 4xx is left unreported — those are typically expected /
+   * handled by the caller (a 404 from a "does this exist" check, etc.).
+   * Defaults to a no-op.
+   */
+  errors?: ErrorSink;
 }
 interface RequestOptions {
   method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { NoopErrorSink, NoopLogger } from "@theholocron/observability/core";
 //#region src/auth-resolver.ts
 var AuthError = class extends Error {
 	name = "AuthError";
@@ -49,6 +50,8 @@ var ProviderApiError = class extends Error {
 function createRestClient(config) {
 	const fetchImpl = config.fetch ?? globalThis.fetch;
 	const vendor = config.vendor ?? "";
+	const logger = config.logger ?? new NoopLogger();
+	const errors = config.errors ?? new NoopErrorSink();
 	let baseUrl = config.baseUrl;
 	while (baseUrl.endsWith("/")) baseUrl = baseUrl.slice(0, -1);
 	const staticHeaders = { accept: "application/json" };
@@ -72,16 +75,31 @@ function createRestClient(config) {
 				init.body = JSON.stringify(opts.body);
 			}
 			const tag = vendor ? `${vendor} ${init.method} ${path}` : `${init.method} ${path}`;
+			logger.debug({
+				vendor,
+				method: init.method,
+				path
+			}, "request");
 			let res;
 			try {
 				res = await fetchImpl(url.toString(), init);
 			} catch (err) {
-				throw new ProviderApiError(`${tag} failed: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}`, 0, void 0);
+				const apiErr = new ProviderApiError(`${tag} failed: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}`, 0, void 0);
+				errors.captureException(apiErr);
+				throw apiErr;
 			}
 			if (!res.ok) {
 				const body = await res.text().catch(() => "");
-				throw new ProviderApiError(`${tag} → ${res.status}`, res.status, body);
+				const apiErr = new ProviderApiError(`${tag} → ${res.status}`, res.status, body);
+				if (res.status >= 500) errors.captureException(apiErr);
+				throw apiErr;
 			}
+			logger.debug({
+				vendor,
+				method: init.method,
+				path,
+				status: res.status
+			}, "response");
 			if (opts.expectNoContent || res.status === 204) return void 0;
 			const text = await res.text();
 			if (!text) return void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/http-client",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "Shared HTTP primitives for theholocron — REST client factory, auth resolver, and error types",
   "keywords": [
     "typescript",
@@ -35,6 +35,9 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "@theholocron/observability": "^0.3.0"
+  },
   "devDependencies": {
     "@theholocron/eslint-config": "^8.2.0",
     "@theholocron/tsconfig": "^8.2.0",