app-settings-js 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,222 @@
+import { type FetchLike, type RequestOptions, type TransportOptions } from "./http.js";
+import { SettingsSnapshot } from "./snapshot.js";
+import type { ApiKey, CreatedApiKey, Environment, Group, GroupMember, Health, IntermediateValue, PersonalValue, Platform, Role, Scope, ServerValue, Setting, SettingScope, SettingType, SettingValue, TypeConfig, WhoAmI } from "./types.js";
+/** How to reach the server, and what to assume when a call does not say. */
+export interface ClientOptions extends TransportOptions {
+    /**
+     * The environment used by calls that require one. Resolution always needs an
+     * environment, so setting it here means most calls take no options at all.
+     */
+    environment?: string;
+    /** The platform filter applied to resolution and to setting lookups. */
+    platform?: string | string[];
+}
+/** Options shared by both resolution calls. */
+export interface ResolveOptions extends RequestOptions {
+    /** Overrides the client's environment. Required if the client has none. */
+    environment?: string;
+    /** Restricts the resolution to these platforms. Capped by the key's own fence. */
+    platform?: string | string[];
+    /** Resolves as this role instead of the key's. It may not outrank the key. */
+    role?: string;
+}
+/** Resolution for one user. */
+export interface ResolveUserOptions extends ResolveOptions {
+    /**
+     * Groups to apply without storing membership, which is how an ad-hoc group
+     * is used. Saved memberships apply regardless.
+     */
+    groupId?: string | string[];
+}
+/** Filters for listing setting definitions. */
+export interface ListSettingsOptions extends RequestOptions {
+    environment?: string;
+    platform?: string;
+    scope?: SettingScope;
+}
+/** A new setting definition. Type, scope, platform and environment are fixed at creation. */
+export interface CreateSettingInput {
+    name: string;
+    type: SettingType;
+    scope: SettingScope;
+    platform: string;
+    /** Defaults to the client's environment. */
+    environment?: string;
+    description?: string;
+    /** The rules for this type. See {@link TypeConfig}. */
+    typeConfig?: TypeConfig;
+    /** Defaults to the calling key's own role. */
+    role?: string;
+    /** Used when no layer supplies a value. */
+    defaultValue?: SettingValue;
+}
+/** The parts of a definition that are safe to change after creation. */
+export interface UpdateSettingInput {
+    description?: string;
+    typeConfig?: TypeConfig;
+    role?: string;
+    defaultValue?: SettingValue;
+}
+/** Options for writing a group override. */
+export interface GroupValueOptions extends RequestOptions {
+    /** Whether the user is meant to observe the override. Defaults to true. */
+    visible?: boolean;
+    /** Whether the override beats the user's own value. Defaults to false. */
+    enforced?: boolean;
+}
+/** A new group. */
+export interface CreateGroupInput {
+    name: string;
+    description?: string;
+    /** Omit to span every environment, which a fenced key may not do. */
+    environment?: string | null;
+    /** Higher priority wins when two groups override the same setting. */
+    priority?: number;
+    /** Marks an ad-hoc group so operators can prune it later. */
+    ephemeral?: boolean;
+    /** Seeds membership in the same request. */
+    members?: string[];
+}
+/** A new API key. It can never reach further than the key that mints it. */
+export interface CreateKeyInput {
+    name: string;
+    scopes: Scope[];
+    /** Empty inherits the creating key's fence rather than granting everything. */
+    environments?: string[];
+    platforms?: string[];
+    /** Defaults to the lowest-ranked role. May not outrank the creating key. */
+    role?: string;
+    /** Supply at most one of these. */
+    expiresAt?: Date | string;
+    /** A Go duration such as `"720h"`. */
+    expiresIn?: string;
+}
+/**
+ * A client for the App Settings API.
+ *
+ * One instance is cheap and holds no connection state, so it is safe to build
+ * once at module scope and share it.
+ *
+ * @example
+ * const client = new AppSettingsClient({
+ *   baseUrl: "https://settings.example.com",
+ *   apiKey: process.env.SETTINGS_API_KEY!,
+ *   environment: "production",
+ * });
+ *
+ * const settings = await client.resolveUser("alice");
+ * if (settings.boolean("dark_mode")) { ... }
+ */
+export declare class AppSettingsClient {
+    #private;
+    constructor(options: ClientOptions);
+    /** The environment this client defaults to, if it has one. */
+    get environment(): string | undefined;
+    /** A copy of this client bound to a different environment. */
+    withEnvironment(environment: string): AppSettingsClient;
+    /**
+     * Every setting a user can see, collapsed to one effective value each.
+     *
+     * This is the call a product backend makes. Precedence, lowest to highest, is
+     * `default < server < advisory group < personal < enforced group`.
+     */
+    resolveUser(userId: string, options?: ResolveUserOptions): Promise<SettingsSnapshot>;
+    /** The server's own settings, with no user layer applied. */
+    resolveServer(options?: ResolveOptions): Promise<SettingsSnapshot>;
+    /** Describes the calling key, so a deployment can confirm what it can do. */
+    whoami(options?: RequestOptions): Promise<WhoAmI>;
+    /** Whether the process is up. Needs no API key on the server, but sends one. */
+    health(options?: RequestOptions): Promise<Health>;
+    /** Whether the server's dependencies are reachable. */
+    ready(options?: RequestOptions): Promise<Health>;
+    readonly settings: {
+        /** Every definition this key may see, narrowed by the given filters. */
+        list: (options?: ListSettingsOptions) => Promise<Setting[]>;
+        /** One definition by id. */
+        get: (id: string, options?: RequestOptions) => Promise<Setting>;
+        /** Defines a new setting. */
+        create: (input: CreateSettingInput, options?: RequestOptions) => Promise<Setting>;
+        /** Changes a definition. Omitted fields are left as they are. */
+        update: (id: string, input: UpdateSettingInput, options?: RequestOptions) => Promise<Setting>;
+        /**
+         * Removes a definition.
+         *
+         * A delete that would destroy stored values is refused with a `conflict`
+         * naming how many, unless `cascade` says to go ahead.
+         */
+        delete: (id: string, options?: RequestOptions & {
+            cascade?: boolean;
+        }) => Promise<void>;
+    };
+    readonly values: {
+        /** The server-wide layer, beneath every group and user value. */
+        server: {
+            get: (settingId: string, options?: RequestOptions) => Promise<ServerValue>;
+            set: (settingId: string, value: SettingValue, options?: RequestOptions) => Promise<ServerValue>;
+            /** Removes the value, falling back to the definition's default. */
+            clear: (settingId: string, options?: RequestOptions) => Promise<void>;
+        };
+        /** One user's own choice. */
+        personal: {
+            get: (settingId: string, userId: string, options?: RequestOptions) => Promise<PersonalValue>;
+            set: (settingId: string, userId: string, value: SettingValue, options?: RequestOptions) => Promise<PersonalValue>;
+            clear: (settingId: string, userId: string, options?: RequestOptions) => Promise<void>;
+        };
+        /** A group override, in either direction. */
+        group: {
+            get: (settingId: string, groupId: string, options?: RequestOptions) => Promise<IntermediateValue>;
+            /**
+             * Writes an override. `enforced` decides its direction: an enforced
+             * override beats the user's own value, an advisory one yields to it.
+             */
+            set: (settingId: string, groupId: string, value: SettingValue, options?: GroupValueOptions) => Promise<IntermediateValue>;
+            clear: (settingId: string, groupId: string, options?: RequestOptions) => Promise<void>;
+        };
+    };
+    readonly groups: {
+        list: (options?: RequestOptions & {
+            environment?: string;
+            includeEphemeral?: boolean;
+        }) => Promise<Group[]>;
+        get: (id: string, options?: RequestOptions) => Promise<Group>;
+        create: (input: CreateGroupInput, options?: RequestOptions) => Promise<Group>;
+        update: (id: string, input: {
+            description?: string;
+            priority?: number;
+        }, options?: RequestOptions) => Promise<Group>;
+        delete: (id: string, options?: RequestOptions) => Promise<void>;
+        /** Everyone whose membership is saved. Ad-hoc application does not appear here. */
+        members: (id: string, options?: RequestOptions) => Promise<GroupMember[]>;
+        addMembers: (id: string, userIds: string[], options?: RequestOptions) => Promise<number>;
+        removeMembers: (id: string, userIds: string[], options?: RequestOptions) => Promise<number>;
+    };
+    readonly taxonomy: {
+        roles: (options?: RequestOptions) => Promise<Role[]>;
+        /** Creates or updates a role. Rank orders roles and may not exceed the key's. */
+        upsertRole: (name: string, input: {
+            rank: number;
+            description?: string;
+        }, options?: RequestOptions) => Promise<Role>;
+        deleteRole: (name: string, options?: RequestOptions) => Promise<void>;
+        platforms: (options?: RequestOptions) => Promise<Platform[]>;
+        upsertPlatform: (name: string, description?: string, options?: RequestOptions) => Promise<Platform>;
+        deletePlatform: (name: string, options?: RequestOptions) => Promise<void>;
+        environments: (options?: RequestOptions) => Promise<Environment[]>;
+        upsertEnvironment: (name: string, description?: string, options?: RequestOptions) => Promise<Environment>;
+        deleteEnvironment: (name: string, options?: RequestOptions) => Promise<void>;
+    };
+    readonly keys: {
+        list: (options?: RequestOptions & {
+            includeRevoked?: boolean;
+        }) => Promise<ApiKey[]>;
+        /**
+         * Mints a key. The returned `token` is the only time it is ever available:
+         * only its hash is stored.
+         */
+        create: (input: CreateKeyInput, options?: RequestOptions) => Promise<CreatedApiKey>;
+        /** Revokes a key. This is permanent and takes effect immediately. */
+        revoke: (id: string, options?: RequestOptions) => Promise<void>;
+    };
+}
+export type { FetchLike, RequestOptions };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/datetime.d.cts

@@ -0,0 +1,40 @@
+/**
+ * Normalises a value to the canonical UTC instant the server stores.
+ *
+ * A `Date` or an epoch milliseconds number is unambiguous and converts freely.
+ * A string must already carry an offset: a bare `2026-01-02T15:04` means a
+ * different moment in every timezone, so guessing one would be a bug waiting
+ * to happen. Use {@link localToInstant} to state that assumption explicitly.
+ *
+ * @example
+ * toInstant(new Date())                        // "2026-01-02T20:04:05.250Z"
+ * toInstant("2026-01-02T15:04:05-05:00")       // "2026-01-02T20:04:05.000Z"
+ */
+export declare function toInstant(value: Date | string | number): string;
+/**
+ * Reads a `datetime-local` input in a named timezone and returns the instant.
+ *
+ * Passing the zone makes the assumption visible at the call site, which is the
+ * whole point: the same reading is a different moment in each zone.
+ *
+ * @param local A `datetime-local` value such as `2026-01-02T15:04`.
+ * @param timeZone An IANA zone. Defaults to the runtime's own.
+ *
+ * @example
+ * localToInstant("2026-01-02T15:04", "America/New_York")  // "2026-01-02T20:04:00.000Z"
+ */
+export declare function localToInstant(local: string, timeZone?: string): string;
+/**
+ * Parses a value returned by the API into a `Date`.
+ *
+ * Returns `undefined` for null or undefined, so an unset `DATETIME` reads
+ * naturally without a guard at every call site.
+ */
+export declare function parseInstant(value: unknown): Date | undefined;
+/** Reports whether a string is something the server will accept as a DATETIME. */
+export declare function isInstant(value: unknown): value is string;
+/**
+ * Renders an instant for a `<input type="datetime-local">`, which is the
+ * inverse of {@link localToInstant} and equally zone-dependent.
+ */
+export declare function toDateTimeLocal(value: Date | string | number, timeZone?: string): string;

package/dist/datetime.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Normalises a value to the canonical UTC instant the server stores.
+ *
+ * A `Date` or an epoch milliseconds number is unambiguous and converts freely.
+ * A string must already carry an offset: a bare `2026-01-02T15:04` means a
+ * different moment in every timezone, so guessing one would be a bug waiting
+ * to happen. Use {@link localToInstant} to state that assumption explicitly.
+ *
+ * @example
+ * toInstant(new Date())                        // "2026-01-02T20:04:05.250Z"
+ * toInstant("2026-01-02T15:04:05-05:00")       // "2026-01-02T20:04:05.000Z"
+ */
+export declare function toInstant(value: Date | string | number): string;
+/**
+ * Reads a `datetime-local` input in a named timezone and returns the instant.
+ *
+ * Passing the zone makes the assumption visible at the call site, which is the
+ * whole point: the same reading is a different moment in each zone.
+ *
+ * @param local A `datetime-local` value such as `2026-01-02T15:04`.
+ * @param timeZone An IANA zone. Defaults to the runtime's own.
+ *
+ * @example
+ * localToInstant("2026-01-02T15:04", "America/New_York")  // "2026-01-02T20:04:00.000Z"
+ */
+export declare function localToInstant(local: string, timeZone?: string): string;
+/**
+ * Parses a value returned by the API into a `Date`.
+ *
+ * Returns `undefined` for null or undefined, so an unset `DATETIME` reads
+ * naturally without a guard at every call site.
+ */
+export declare function parseInstant(value: unknown): Date | undefined;
+/** Reports whether a string is something the server will accept as a DATETIME. */
+export declare function isInstant(value: unknown): value is string;
+/**
+ * Renders an instant for a `<input type="datetime-local">`, which is the
+ * inverse of {@link localToInstant} and equally zone-dependent.
+ */
+export declare function toDateTimeLocal(value: Date | string | number, timeZone?: string): string;
+//# sourceMappingURL=datetime.d.ts.map

package/dist/datetime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datetime.d.ts","sourceRoot":"","sources":["../src/datetime.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAkC/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAyBvE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,CAY7D;AAED,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEzD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAMxF"}

package/dist/errors.d.cts

@@ -0,0 +1,61 @@
+import type { ErrorCode } from "./types.cjs";
+/**
+ * Codes this SDK raises on top of the ones the server defines. They occupy the
+ * same `code` field so a single `catch` can branch on one value.
+ */
+export type ClientErrorCode = 
+/** The request never got a response: DNS, TLS, CORS, offline. */
+"network_error"
+/** The request exceeded `timeoutMs`, or its signal was aborted. */
+ | "timeout"
+/** The caller aborted the request through an `AbortSignal`. */
+ | "aborted"
+/** A response arrived but was not the JSON this SDK expected. */
+ | "invalid_response"
+/** A typed accessor was used on a setting of a different type. */
+ | "type_mismatch"
+/** A value was rejected before it was ever sent. */
+ | "invalid_value";
+/** Every code an {@link AppSettingsError} can carry. */
+export type AnyErrorCode = ErrorCode | ClientErrorCode;
+/**
+ * The single error type this SDK throws.
+ *
+ * Branch on {@link AppSettingsError.code}, which is stable, rather than on the
+ * message, which is written for a human.
+ */
+export declare class AppSettingsError extends Error {
+    readonly name = "AppSettingsError";
+    /** A stable identifier for the failure. */
+    readonly code: AnyErrorCode;
+    /** The HTTP status, when the failure came from a response. */
+    readonly status?: number;
+    /** The server's `X-Request-ID`, worth quoting in a bug report. */
+    readonly requestId?: string;
+    /** The request that failed, as `GET /api/v1/settings`. */
+    readonly request?: string;
+    /** The parsed response body, when there was one. */
+    readonly body?: unknown;
+    constructor(message: string, options: {
+        code: AnyErrorCode;
+        status?: number;
+        requestId?: string;
+        request?: string;
+        body?: unknown;
+        cause?: unknown;
+    });
+    /** Whether the failure is worth trying again unchanged. */
+    get retryable(): boolean;
+    /** Narrows an unknown caught value to this class. */
+    static is(error: unknown): error is AppSettingsError;
+}
+/** The requested thing does not exist, or this key may not see that it does. */
+export declare const isNotFound: (error: unknown) => boolean;
+/** The API key was missing, malformed, expired or revoked. */
+export declare const isUnauthorized: (error: unknown) => boolean;
+/** The key is real but is fenced out of what it asked for. */
+export declare const isForbidden: (error: unknown) => boolean;
+/** The request collided with existing state, such as a duplicate name. */
+export declare const isConflict: (error: unknown) => boolean;
+/** The request was malformed or a value failed validation. */
+export declare const isInvalidRequest: (error: unknown) => boolean;

package/dist/errors.d.ts

@@ -0,0 +1,62 @@
+import type { ErrorCode } from "./types.js";
+/**
+ * Codes this SDK raises on top of the ones the server defines. They occupy the
+ * same `code` field so a single `catch` can branch on one value.
+ */
+export type ClientErrorCode = 
+/** The request never got a response: DNS, TLS, CORS, offline. */
+"network_error"
+/** The request exceeded `timeoutMs`, or its signal was aborted. */
+ | "timeout"
+/** The caller aborted the request through an `AbortSignal`. */
+ | "aborted"
+/** A response arrived but was not the JSON this SDK expected. */
+ | "invalid_response"
+/** A typed accessor was used on a setting of a different type. */
+ | "type_mismatch"
+/** A value was rejected before it was ever sent. */
+ | "invalid_value";
+/** Every code an {@link AppSettingsError} can carry. */
+export type AnyErrorCode = ErrorCode | ClientErrorCode;
+/**
+ * The single error type this SDK throws.
+ *
+ * Branch on {@link AppSettingsError.code}, which is stable, rather than on the
+ * message, which is written for a human.
+ */
+export declare class AppSettingsError extends Error {
+    readonly name = "AppSettingsError";
+    /** A stable identifier for the failure. */
+    readonly code: AnyErrorCode;
+    /** The HTTP status, when the failure came from a response. */
+    readonly status?: number;
+    /** The server's `X-Request-ID`, worth quoting in a bug report. */
+    readonly requestId?: string;
+    /** The request that failed, as `GET /api/v1/settings`. */
+    readonly request?: string;
+    /** The parsed response body, when there was one. */
+    readonly body?: unknown;
+    constructor(message: string, options: {
+        code: AnyErrorCode;
+        status?: number;
+        requestId?: string;
+        request?: string;
+        body?: unknown;
+        cause?: unknown;
+    });
+    /** Whether the failure is worth trying again unchanged. */
+    get retryable(): boolean;
+    /** Narrows an unknown caught value to this class. */
+    static is(error: unknown): error is AppSettingsError;
+}
+/** The requested thing does not exist, or this key may not see that it does. */
+export declare const isNotFound: (error: unknown) => boolean;
+/** The API key was missing, malformed, expired or revoked. */
+export declare const isUnauthorized: (error: unknown) => boolean;
+/** The key is real but is fenced out of what it asked for. */
+export declare const isForbidden: (error: unknown) => boolean;
+/** The request collided with existing state, such as a duplicate name. */
+export declare const isConflict: (error: unknown) => boolean;
+/** The request was malformed or a value failed validation. */
+export declare const isInvalidRequest: (error: unknown) => boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,eAAe;AACzB,iEAAiE;AAC/D,eAAe;AACjB,mEAAmE;GACjE,SAAS;AACX,+DAA+D;GAC7D,SAAS;AACX,iEAAiE;GAC/D,kBAAkB;AACpB,kEAAkE;GAChE,eAAe;AACjB,oDAAoD;GAClD,eAAe,CAAC;AAEpB,wDAAwD;AACxD,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,eAAe,CAAC;AAEvD;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAkB,IAAI,sBAAsB;IAE5C,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAExB,YACE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,IAAI,EAAE,YAAY,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,EAQF;IAED,2DAA2D;IAC3D,IAAI,SAAS,IAAI,OAAO,CAKvB;IAED,qDAAqD;IACrD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAEnD;CACF;AAED,gFAAgF;AAChF,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,OAAqC,CAAC;AAElF,8DAA8D;AAC9D,eAAO,MAAM,cAAc,UAAW,OAAO,KAAG,OAAwC,CAAC;AAEzF,8DAA8D;AAC9D,eAAO,MAAM,WAAW,UAAW,OAAO,KAAG,OAAqC,CAAC;AAEnF,0EAA0E;AAC1E,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,OAAoC,CAAC;AAEjF,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,UAAW,OAAO,KAAG,OACkB,CAAC"}

package/dist/http.d.cts

@@ -0,0 +1,62 @@
+/** The subset of `fetch` this SDK uses, so any compatible implementation fits. */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/** A value that can appear in a query string. Arrays become repeated keys. */
+export type QueryValue = string | number | boolean | string[] | undefined | null;
+/** Per-call options accepted by every method on the client. */
+export interface RequestOptions {
+    /** Cancels the request, and any retry still pending. */
+    signal?: AbortSignal;
+    /** Overrides the client's `timeoutMs` for this call. */
+    timeoutMs?: number;
+    /** Extra headers, merged over the client's own. */
+    headers?: Record<string, string>;
+}
+/** Everything the transport needs to make one call. */
+export interface TransportConfig {
+    baseUrl: string;
+    apiKey: string;
+    fetch: FetchLike;
+    timeoutMs: number;
+    retries: number;
+    retryDelayMs: number;
+    headers: Record<string, string>;
+    userAgent?: string;
+}
+/** Options for building a client's transport. */
+export interface TransportOptions {
+    /** Where the server lives, such as `https://settings.example.com`. */
+    baseUrl: string;
+    /** The API key sent as `Authorization: Bearer`. */
+    apiKey: string;
+    /** A `fetch` implementation. Defaults to the global one. */
+    fetch?: FetchLike;
+    /** How long one attempt may take. Defaults to 10000; 0 disables the timeout. */
+    timeoutMs?: number;
+    /** How many times to retry a retryable failure. Defaults to 2. */
+    retries?: number;
+    /** Base backoff between retries, doubled each time. Defaults to 200. */
+    retryDelayMs?: number;
+    /** Headers added to every request. */
+    headers?: Record<string, string>;
+}
+/**
+ * Builds the transport config, resolving defaults once so each request does no
+ * more work than it has to.
+ */
+export declare function createTransport(options: TransportOptions): TransportConfig;
+/** One request, before defaults and retries are applied. */
+export interface RequestSpec {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    options?: RequestOptions;
+}
+/**
+ * Performs a request and decodes its body.
+ *
+ * Returns `undefined` for a 204, which is what every successful DELETE returns.
+ */
+export declare function request<T>(config: TransportConfig, spec: RequestSpec): Promise<T>;
+/** Renders a query string, repeating a key for each element of an array. */
+export declare function buildQuery(query: Record<string, QueryValue> | undefined): string;

package/dist/http.d.ts

@@ -0,0 +1,63 @@
+/** The subset of `fetch` this SDK uses, so any compatible implementation fits. */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/** A value that can appear in a query string. Arrays become repeated keys. */
+export type QueryValue = string | number | boolean | string[] | undefined | null;
+/** Per-call options accepted by every method on the client. */
+export interface RequestOptions {
+    /** Cancels the request, and any retry still pending. */
+    signal?: AbortSignal;
+    /** Overrides the client's `timeoutMs` for this call. */
+    timeoutMs?: number;
+    /** Extra headers, merged over the client's own. */
+    headers?: Record<string, string>;
+}
+/** Everything the transport needs to make one call. */
+export interface TransportConfig {
+    baseUrl: string;
+    apiKey: string;
+    fetch: FetchLike;
+    timeoutMs: number;
+    retries: number;
+    retryDelayMs: number;
+    headers: Record<string, string>;
+    userAgent?: string;
+}
+/** Options for building a client's transport. */
+export interface TransportOptions {
+    /** Where the server lives, such as `https://settings.example.com`. */
+    baseUrl: string;
+    /** The API key sent as `Authorization: Bearer`. */
+    apiKey: string;
+    /** A `fetch` implementation. Defaults to the global one. */
+    fetch?: FetchLike;
+    /** How long one attempt may take. Defaults to 10000; 0 disables the timeout. */
+    timeoutMs?: number;
+    /** How many times to retry a retryable failure. Defaults to 2. */
+    retries?: number;
+    /** Base backoff between retries, doubled each time. Defaults to 200. */
+    retryDelayMs?: number;
+    /** Headers added to every request. */
+    headers?: Record<string, string>;
+}
+/**
+ * Builds the transport config, resolving defaults once so each request does no
+ * more work than it has to.
+ */
+export declare function createTransport(options: TransportOptions): TransportConfig;
+/** One request, before defaults and retries are applied. */
+export interface RequestSpec {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    options?: RequestOptions;
+}
+/**
+ * Performs a request and decodes its body.
+ *
+ * Returns `undefined` for a 204, which is what every successful DELETE returns.
+ */
+export declare function request<T>(config: TransportConfig, spec: RequestSpec): Promise<T>;
+/** Renders a query string, repeating a key for each element of an array. */
+export declare function buildQuery(query: Record<string, QueryValue> | undefined): string;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAEA,kFAAkF;AAClF,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEhF,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI,CAAC;AAEjF,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CA8B1E;AAED,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAkDvF;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,SAAS,GAAG,MAAM,CAehF"}