@inshorts/glint-http 1.2.0

package/dist/index.d.cts

@@ -0,0 +1,200 @@
+type UpstreamClientConfig = {
+    /** Read on every request, so tests and deployments can swap it lazily. */
+    baseUrl: () => string;
+    /** Read on every request; a natural place to attach a system token. */
+    headers?: () => HeadersInit;
+    /**
+     * Builds the error thrown for a non-OK response.
+     * Defaults to `UpstreamError`. Third arg is a redacted curl (optional).
+     */
+    makeError?: (message: string, status: number, curl?: string) => Error;
+    /** Default timeout for this client; see `fetchUpstream`. */
+    timeoutMs?: number;
+};
+type UpstreamRequest = Omit<RequestInit, "body" | "headers"> & {
+    /** Serialised with `JSON.stringify`. */
+    body?: unknown;
+    /** Merged over the client's headers; same-named ones win. */
+    headers?: HeadersInit;
+    /** Overrides the client's timeout for this call. */
+    timeoutMs?: number;
+};
+interface UpstreamClient {
+    request<T>(path: string, init?: UpstreamRequest): Promise<T>;
+}
+/**
+ * Creates a small server-only JSON client. Configuration stays lazy so tests
+ * and deployments can substitute environment-backed URLs and credentials.
+ *
+ * On failure the thrown error has:
+ * - `message` — upstream / timeout reason (safe for the API JSON body)
+ * - `status` — HTTP status for `errorResponse`
+ * - `curl` — redacted replay line for **server logs only**
+ */
+declare function createUpstreamClient(config: UpstreamClientConfig): UpstreamClient;
+
+/**
+ * Turns a request into a `curl` line you can paste into a terminal.
+ *
+ * The point is the thing that is missing when an upstream call fails in
+ * production: the log says a request to some service returned 502, and
+ * reproducing it means reading the calling code to work out what was actually
+ * sent. This writes that down at the moment it fails.
+ *
+ * **Nothing secret goes in.** Every header whose name looks like a credential
+ * is emitted as `$ENV_VAR` where the value matches a known one, and
+ * `<redacted>` otherwise — so the line is still runnable after
+ * `export SOME_SYS_TOKEN=…`, without the token itself ever reaching a log
+ * aggregator. Body fields that look like credentials get the same treatment.
+ *
+ * The alternative — logging the real header — is how tokens end up in Cloud
+ * Logging, readable by anyone with project viewer, retained for a month, and
+ * impossible to rotate out of the archive.
+ */
+interface CurlRequest {
+    method?: string;
+    url: string;
+    headers?: HeadersInit;
+    body?: unknown;
+}
+interface CurlOptions {
+    /** Longest body to include before truncating. */
+    maxBody?: number;
+    /**
+     * Environment variable names to match secret values against, so the line
+     * comes out as `$SOME_SYS_TOKEN` rather than `<redacted>` and can actually
+     * be replayed. Defaults to `process.env`; only values of 8+ characters are
+     * matched.
+     */
+    env?: Record<string, string | undefined>;
+}
+declare function toCurl(request: CurlRequest, options?: CurlOptions): string;
+
+/**
+ * Errors this package throws. Each carries a numeric `status`, so
+ * `errorResponse` turns it into the right HTTP code without having to know
+ * the class.
+ *
+ * `curl` is for **server logs only** — never put it in the JSON body sent to
+ * the browser (`errorResponse` strips it).
+ */
+/** A required upstream setting (base URL, token) is missing. */
+declare class UpstreamConfigError extends Error {
+    status: number;
+    curl?: string;
+    constructor(message: string, options?: {
+        curl?: string;
+    });
+}
+/** The upstream did not answer before the deadline. */
+declare class UpstreamTimeoutError extends Error {
+    status: number;
+    curl?: string;
+    constructor(message?: string, options?: {
+        curl?: string;
+    });
+}
+/**
+ * The default error `createUpstreamClient` throws for a non-OK response when
+ * the caller does not supply its own `makeError`.
+ */
+declare class UpstreamError extends Error {
+    status: number;
+    curl?: string;
+    constructor(message: string, status: number, options?: {
+        curl?: string;
+    });
+}
+/** True when `error` looks like one of ours (or any `{ status, message }`). */
+declare function isUpstreamFailure(error: unknown): error is Error & {
+    status: number;
+    curl?: string;
+};
+/** Read a redacted replay curl if the thrown value carries one. */
+declare function curlOf(error: unknown): string | undefined;
+
+/**
+ * Turning a thrown error into an HTTP response, for route handlers.
+ *
+ * This does not list error classes. Anything thrown with a numeric `status`
+ * (every error in this package, and most upstream ones) keeps that status, so
+ * an upstream 404 reaches the browser as a 404 rather than a 500.
+ *
+ * Returns a standard `Response`, which Next.js route handlers, Hono, Remix and
+ * any other fetch-style server accept as-is.
+ *
+ * **Body is always `{ message }` only.** Never include `curl` — that is for
+ * Cloud Logging via `logApiError`.
+ */
+/** Only a real HTTP failure code. Anything else is our fault, so 500. */
+declare function statusOf(error: unknown): number;
+declare function messageOf(error: unknown, fallback?: string): string;
+/**
+ * `fallback` is used only when the thrown value is not an `Error` (a rejected
+ * string, say), or is one with an empty message. A real error's own message is
+ * more useful than a generic one.
+ */
+declare function errorResponse(error: unknown, fallback?: string): Response;
+/** A rejected payload: the caller sent something we will not act on. */
+declare function invalidResponse(message: string): Response;
+/**
+ * Log an API / upstream failure for Cloud Logging, including redacted curl
+ * when present. Call this in a route `catch` **before** `errorResponse`.
+ *
+ * ```ts
+ * } catch (error) {
+ *   logApiError(error, { service: "inpix-panel", route: "POST /api/x" });
+ *   return errorResponse(error);
+ * }
+ * ```
+ */
+declare function logApiError(error: unknown, context: {
+    service: string;
+    route?: string;
+    requestId?: string;
+}): void;
+
+/**
+ * Server-side `fetch` for calls to internal upstream services. These calls
+ * usually attach system tokens, so never import this into browser code.
+ */
+/**
+ * Base headers for an internal service-to-service call. `deviceId` names the
+ * calling app (`"inpix-panel"`, `"users-crm"`) so upstream logs show who sent it.
+ */
+declare function internalHeaders(deviceId: string): Record<string, string>;
+/** Used when neither the call nor `UPSTREAM_TIMEOUT_MS` sets a timeout. */
+declare const DEFAULT_UPSTREAM_TIMEOUT_MS = 15000;
+/**
+ * Require an absolute upstream base URL. There is deliberately no default
+ * host: missing config fails closed instead of quietly calling a hard-coded one.
+ */
+declare function requireUpstreamBaseUrl(value: string | null | undefined, envName: string): string;
+/** Test seam. */
+declare function resetUpstreamFailureLog(): void;
+/**
+ * `fetch` with an AbortSignal timeout. Throws `UpstreamTimeoutError` (status
+ * 504) when the deadline is hit before the upstream responds.
+ *
+ * The timeout is `timeoutMs` if given, else the `UPSTREAM_TIMEOUT_MS` env var,
+ * else `DEFAULT_UPSTREAM_TIMEOUT_MS`.
+ *
+ * Every failure — a non-OK status, a timeout, a refused connection — is logged
+ * once here with a replayable curl, so no caller has to remember to do it and
+ * none of them can do it differently.
+ *
+ * No caller currently treats a non-OK status as normal flow, so there is no
+ * opt-out. If one appears — a lookup where 404 means "absent" — add a
+ * `silentStatuses` option here rather than logging around it at the call site.
+ */
+/** Build the redacted replay curl for this attempt (also used on thrown errors). */
+declare function curlForRequest(input: RequestInfo | URL, init?: RequestInit): string;
+declare function fetchUpstream(input: RequestInfo | URL, init?: RequestInit, timeoutMs?: number): Promise<Response>;
+/**
+ * Reads an upstream response: returns parsed JSON on success (undefined for
+ * 204), otherwise extracts a `message`/`error` field and throws via the
+ * provided factory so callers keep their own typed error class + status.
+ */
+declare function parseUpstream<T>(response: Response, makeError: (message: string, status: number) => Error, fallbackMessage?: string): Promise<T>;
+
+export { type CurlOptions, type CurlRequest, DEFAULT_UPSTREAM_TIMEOUT_MS, type UpstreamClient, type UpstreamClientConfig, UpstreamConfigError, UpstreamError, type UpstreamRequest, UpstreamTimeoutError, createUpstreamClient, curlForRequest, curlOf, errorResponse, fetchUpstream, internalHeaders, invalidResponse, isUpstreamFailure, logApiError, messageOf, parseUpstream, requireUpstreamBaseUrl, resetUpstreamFailureLog, statusOf, toCurl };

package/dist/index.d.ts

@@ -0,0 +1,200 @@
+type UpstreamClientConfig = {
+    /** Read on every request, so tests and deployments can swap it lazily. */
+    baseUrl: () => string;
+    /** Read on every request; a natural place to attach a system token. */
+    headers?: () => HeadersInit;
+    /**
+     * Builds the error thrown for a non-OK response.
+     * Defaults to `UpstreamError`. Third arg is a redacted curl (optional).
+     */
+    makeError?: (message: string, status: number, curl?: string) => Error;
+    /** Default timeout for this client; see `fetchUpstream`. */
+    timeoutMs?: number;
+};
+type UpstreamRequest = Omit<RequestInit, "body" | "headers"> & {
+    /** Serialised with `JSON.stringify`. */
+    body?: unknown;
+    /** Merged over the client's headers; same-named ones win. */
+    headers?: HeadersInit;
+    /** Overrides the client's timeout for this call. */
+    timeoutMs?: number;
+};
+interface UpstreamClient {
+    request<T>(path: string, init?: UpstreamRequest): Promise<T>;
+}
+/**
+ * Creates a small server-only JSON client. Configuration stays lazy so tests
+ * and deployments can substitute environment-backed URLs and credentials.
+ *
+ * On failure the thrown error has:
+ * - `message` — upstream / timeout reason (safe for the API JSON body)
+ * - `status` — HTTP status for `errorResponse`
+ * - `curl` — redacted replay line for **server logs only**
+ */
+declare function createUpstreamClient(config: UpstreamClientConfig): UpstreamClient;
+
+/**
+ * Turns a request into a `curl` line you can paste into a terminal.
+ *
+ * The point is the thing that is missing when an upstream call fails in
+ * production: the log says a request to some service returned 502, and
+ * reproducing it means reading the calling code to work out what was actually
+ * sent. This writes that down at the moment it fails.
+ *
+ * **Nothing secret goes in.** Every header whose name looks like a credential
+ * is emitted as `$ENV_VAR` where the value matches a known one, and
+ * `<redacted>` otherwise — so the line is still runnable after
+ * `export SOME_SYS_TOKEN=…`, without the token itself ever reaching a log
+ * aggregator. Body fields that look like credentials get the same treatment.
+ *
+ * The alternative — logging the real header — is how tokens end up in Cloud
+ * Logging, readable by anyone with project viewer, retained for a month, and
+ * impossible to rotate out of the archive.
+ */
+interface CurlRequest {
+    method?: string;
+    url: string;
+    headers?: HeadersInit;
+    body?: unknown;
+}
+interface CurlOptions {
+    /** Longest body to include before truncating. */
+    maxBody?: number;
+    /**
+     * Environment variable names to match secret values against, so the line
+     * comes out as `$SOME_SYS_TOKEN` rather than `<redacted>` and can actually
+     * be replayed. Defaults to `process.env`; only values of 8+ characters are
+     * matched.
+     */
+    env?: Record<string, string | undefined>;
+}
+declare function toCurl(request: CurlRequest, options?: CurlOptions): string;
+
+/**
+ * Errors this package throws. Each carries a numeric `status`, so
+ * `errorResponse` turns it into the right HTTP code without having to know
+ * the class.
+ *
+ * `curl` is for **server logs only** — never put it in the JSON body sent to
+ * the browser (`errorResponse` strips it).
+ */
+/** A required upstream setting (base URL, token) is missing. */
+declare class UpstreamConfigError extends Error {
+    status: number;
+    curl?: string;
+    constructor(message: string, options?: {
+        curl?: string;
+    });
+}
+/** The upstream did not answer before the deadline. */
+declare class UpstreamTimeoutError extends Error {
+    status: number;
+    curl?: string;
+    constructor(message?: string, options?: {
+        curl?: string;
+    });
+}
+/**
+ * The default error `createUpstreamClient` throws for a non-OK response when
+ * the caller does not supply its own `makeError`.
+ */
+declare class UpstreamError extends Error {
+    status: number;
+    curl?: string;
+    constructor(message: string, status: number, options?: {
+        curl?: string;
+    });
+}
+/** True when `error` looks like one of ours (or any `{ status, message }`). */
+declare function isUpstreamFailure(error: unknown): error is Error & {
+    status: number;
+    curl?: string;
+};
+/** Read a redacted replay curl if the thrown value carries one. */
+declare function curlOf(error: unknown): string | undefined;
+
+/**
+ * Turning a thrown error into an HTTP response, for route handlers.
+ *
+ * This does not list error classes. Anything thrown with a numeric `status`
+ * (every error in this package, and most upstream ones) keeps that status, so
+ * an upstream 404 reaches the browser as a 404 rather than a 500.
+ *
+ * Returns a standard `Response`, which Next.js route handlers, Hono, Remix and
+ * any other fetch-style server accept as-is.
+ *
+ * **Body is always `{ message }` only.** Never include `curl` — that is for
+ * Cloud Logging via `logApiError`.
+ */
+/** Only a real HTTP failure code. Anything else is our fault, so 500. */
+declare function statusOf(error: unknown): number;
+declare function messageOf(error: unknown, fallback?: string): string;
+/**
+ * `fallback` is used only when the thrown value is not an `Error` (a rejected
+ * string, say), or is one with an empty message. A real error's own message is
+ * more useful than a generic one.
+ */
+declare function errorResponse(error: unknown, fallback?: string): Response;
+/** A rejected payload: the caller sent something we will not act on. */
+declare function invalidResponse(message: string): Response;
+/**
+ * Log an API / upstream failure for Cloud Logging, including redacted curl
+ * when present. Call this in a route `catch` **before** `errorResponse`.
+ *
+ * ```ts
+ * } catch (error) {
+ *   logApiError(error, { service: "inpix-panel", route: "POST /api/x" });
+ *   return errorResponse(error);
+ * }
+ * ```
+ */
+declare function logApiError(error: unknown, context: {
+    service: string;
+    route?: string;
+    requestId?: string;
+}): void;
+
+/**
+ * Server-side `fetch` for calls to internal upstream services. These calls
+ * usually attach system tokens, so never import this into browser code.
+ */
+/**
+ * Base headers for an internal service-to-service call. `deviceId` names the
+ * calling app (`"inpix-panel"`, `"users-crm"`) so upstream logs show who sent it.
+ */
+declare function internalHeaders(deviceId: string): Record<string, string>;
+/** Used when neither the call nor `UPSTREAM_TIMEOUT_MS` sets a timeout. */
+declare const DEFAULT_UPSTREAM_TIMEOUT_MS = 15000;
+/**
+ * Require an absolute upstream base URL. There is deliberately no default
+ * host: missing config fails closed instead of quietly calling a hard-coded one.
+ */
+declare function requireUpstreamBaseUrl(value: string | null | undefined, envName: string): string;
+/** Test seam. */
+declare function resetUpstreamFailureLog(): void;
+/**
+ * `fetch` with an AbortSignal timeout. Throws `UpstreamTimeoutError` (status
+ * 504) when the deadline is hit before the upstream responds.
+ *
+ * The timeout is `timeoutMs` if given, else the `UPSTREAM_TIMEOUT_MS` env var,
+ * else `DEFAULT_UPSTREAM_TIMEOUT_MS`.
+ *
+ * Every failure — a non-OK status, a timeout, a refused connection — is logged
+ * once here with a replayable curl, so no caller has to remember to do it and
+ * none of them can do it differently.
+ *
+ * No caller currently treats a non-OK status as normal flow, so there is no
+ * opt-out. If one appears — a lookup where 404 means "absent" — add a
+ * `silentStatuses` option here rather than logging around it at the call site.
+ */
+/** Build the redacted replay curl for this attempt (also used on thrown errors). */
+declare function curlForRequest(input: RequestInfo | URL, init?: RequestInit): string;
+declare function fetchUpstream(input: RequestInfo | URL, init?: RequestInit, timeoutMs?: number): Promise<Response>;
+/**
+ * Reads an upstream response: returns parsed JSON on success (undefined for
+ * 204), otherwise extracts a `message`/`error` field and throws via the
+ * provided factory so callers keep their own typed error class + status.
+ */
+declare function parseUpstream<T>(response: Response, makeError: (message: string, status: number) => Error, fallbackMessage?: string): Promise<T>;
+
+export { type CurlOptions, type CurlRequest, DEFAULT_UPSTREAM_TIMEOUT_MS, type UpstreamClient, type UpstreamClientConfig, UpstreamConfigError, UpstreamError, type UpstreamRequest, UpstreamTimeoutError, createUpstreamClient, curlForRequest, curlOf, errorResponse, fetchUpstream, internalHeaders, invalidResponse, isUpstreamFailure, logApiError, messageOf, parseUpstream, requireUpstreamBaseUrl, resetUpstreamFailureLog, statusOf, toCurl };