Interface HonuaClientOptions

Configuration passed to the HonuaClient constructor.

Example: Minimal config

new HonuaClient({ baseUrl: "https://your-honua-server.example" });

Example: With API key + retries

new HonuaClient({
  baseUrl: "https://your-honua-server.example",
  apiKey: process.env.HONUA_API_KEY,
  retry: { maxRetries: 3, baseDelayMs: 250 },
  timeoutMs: 30_000,
});

Example: With an OAuth-style credential provider

new HonuaClient({
  baseUrl: "https://your-honua-server.example",
  auth: async () => {
    const token = await fetchAccessToken();
    return { bearerToken: token.access_token, expiresAt: token.expiresAt };
  },
});
interface HonuaClientOptions {
    apiKey?: string;
    auth?: HonuaAuthProvider | HonuaAuthCredentialsProvider;
    authRefreshSkewMs?: number;
    baseUrl: string;
    bearerToken?: string;
    fetchFn?: {
        (input: URL | RequestInfo, init?: RequestInit): Promise<Response>;
        (input: string | URL | Request, init?: RequestInit): Promise<Response>;
    };
    interceptors?: readonly HonuaRequestInterceptor[];
    preferBinary?: boolean;
    retry?: HonuaRetryOptions;
    timeoutMs?: number;
    transport?: HonuaTransport;
}

Properties

apiKey? auth? authRefreshSkewMs? baseUrl bearerToken? fetchFn? interceptors? preferBinary? retry? timeoutMs? transport?

Properties

OptionalapiKey

apiKey?: string

Static API key sent as X-API-Key. Prefer auth for refreshable credentials.

Optionalauth

auth?: HonuaAuthProvider | HonuaAuthCredentialsProvider

Optional credential provider. The SDK calls it lazily, caches returned credentials until expiresAt nears, and never persists secrets itself. Returning a string is shorthand for { bearerToken: string }.

OptionalauthRefreshSkewMs

authRefreshSkewMs?: number

Milliseconds before expiresAt when credentials should be refreshed. Default: 60 seconds.

baseUrl

baseUrl: string

Absolute origin of the Honua server (e.g. https://api.honua.example). Trailing slashes are normalized.

OptionalbearerToken

bearerToken?: string

Static bearer token sent as Authorization: Bearer <token>. Prefer auth for refreshable credentials.

OptionalfetchFn

fetchFn?: {
    (input: URL | RequestInfo, init?: RequestInit): Promise<Response>;
    (input: string | URL | Request, init?: RequestInit): Promise<Response>;
}

Override the global fetch implementation (useful in Node before built-in fetch, or for testing).

Type declaration

    • (input, init?): Promise<Response>

    • MDN Reference

      Parameters

      • input: URL | RequestInfo
      • Optionalinit: RequestInit

      Returns Promise<Response>

    • (input, init?): Promise<Response>

    • Parameters

      • input: string | URL | Request
      • Optionalinit: RequestInit

      Returns Promise<Response>

Optionalinterceptors

interceptors?: readonly HonuaRequestInterceptor[]

Per-request before / after / error hooks invoked on every HTTP call.

OptionalpreferBinary

preferBinary?: boolean

When true, query methods use f=pbf for binary protobuf responses and decode them transparently into the same JSON-compatible shape. Falls back to f=json on decode failure. Default: false.

Optionalretry

retry?: HonuaRetryOptions

Retry strategy for transient failures.

Applies to both the REST and "grpc-web" transports. On gRPC-web the same policy is applied to replay-safe unary calls only: transient gRPC status codes (resource_exhausted, unavailable, deadline_exceeded, aborted) are retried with the same exponential backoff + jitter and retry-after handling as REST, and never past the abort/timeoutMs deadline. Server-streaming calls are not retried (they cannot be safely replayed mid-iteration).

OptionaltimeoutMs

timeoutMs?: number

Per-request hard timeout in milliseconds. Independent of any caller-supplied AbortSignal.

Optionaltransport

transport?: HonuaTransport

Transport protocol. "rest" uses JSON/PBF over HTTP (default). "grpc-web" uses typed RPC via Connect gRPC-Web transport.

Settings

Member Visibility

On This Page

Properties