app-settings-js 0.1.0

package/src/datetime.ts

@@ -0,0 +1,183 @@
+import { AppSettingsError } from "./errors.ts";
+
+/**
+ * Helpers for the `DATETIME` type, which accepts only a strict RFC 3339
+ * date-time with a mandatory offset. The offset is what makes a value an
+ * instant rather than a wall-clock reading, so the server rejects anything
+ * without one — including what `<input type="datetime-local">` produces.
+ */
+
+/** RFC 3339 §5.6 `date-time`, with the offset required. Lower-case t/z are legal. */
+const RFC_3339 =
+  /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+
+/** What `<input type="datetime-local">` yields: no offset, often no seconds. */
+const DATETIME_LOCAL = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}(:\d{2}(\.\d+)?)?$/;
+
+/**
+ * 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 function toInstant(value: Date | string | number): string {
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw invalid("an Invalid Date cannot be converted to an instant");
+    }
+    return value.toISOString();
+  }
+
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw invalid(`${value} is not a valid epoch milliseconds value`);
+    }
+    return new Date(value).toISOString();
+  }
+
+  if (DATETIME_LOCAL.test(value)) {
+    throw invalid(
+      `"${value}" has no UTC offset, so it is a wall-clock reading rather than an instant. ` +
+        "Pass it through localToInstant() to read it in a specific timezone, " +
+        "or through toInstant(new Date(value)) to accept the runtime's own zone.",
+    );
+  }
+  if (!RFC_3339.test(value)) {
+    throw invalid(
+      `"${value}" is not an RFC 3339 date-time. The expected shape is ` +
+        "2026-01-02T15:04:05Z or 2026-01-02T15:04:05-05:00.",
+    );
+  }
+
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    throw invalid(`"${value}" is shaped like an RFC 3339 date-time but is not a real moment`);
+  }
+  return parsed.toISOString();
+}
+
+/**
+ * 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 function localToInstant(local: string, timeZone?: string): string {
+  if (!DATETIME_LOCAL.test(local) && !RFC_3339.test(local)) {
+    throw invalid(`"${local}" is not a datetime-local value such as 2026-01-02T15:04`);
+  }
+  if (RFC_3339.test(local)) return toInstant(local);
+
+  // Without a zone the runtime's own is the only sensible reading, and `Date`
+  // already applies it.
+  if (!timeZone) {
+    const parsed = new Date(local);
+    if (Number.isNaN(parsed.getTime())) throw invalid(`"${local}" is not a real moment`);
+    return parsed.toISOString();
+  }
+
+  // Treat the reading as UTC, then measure how far that guess sits from the
+  // target zone and correct by it. Two passes settle the case where the offset
+  // itself changes across the correction, as it does at a DST boundary.
+  const naive = Date.parse(`${withSeconds(local)}Z`);
+  if (Number.isNaN(naive)) throw invalid(`"${local}" is not a real moment`);
+
+  let instant = naive;
+  for (let pass = 0; pass < 2; pass++) {
+    instant = naive + zoneOffsetMs(instant, timeZone);
+  }
+  return new Date(instant).toISOString();
+}
+
+/**
+ * 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 function parseInstant(value: unknown): Date | undefined {
+  if (value === null || value === undefined) return undefined;
+  if (value instanceof Date) return value;
+
+  if (typeof value !== "string") {
+    throw invalid(`expected an RFC 3339 string, got ${typeof value}`);
+  }
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    throw invalid(`"${value}" is not a parseable date-time`);
+  }
+  return parsed;
+}
+
+/** Reports whether a string is something the server will accept as a DATETIME. */
+export function isInstant(value: unknown): value is string {
+  return typeof value === "string" && RFC_3339.test(value) && !Number.isNaN(Date.parse(value));
+}
+
+/**
+ * Renders an instant for a `<input type="datetime-local">`, which is the
+ * inverse of {@link localToInstant} and equally zone-dependent.
+ */
+export function toDateTimeLocal(value: Date | string | number, timeZone?: string): string {
+  const date = value instanceof Date ? value : new Date(typeof value === "string" ? value : Number(value));
+  if (Number.isNaN(date.getTime())) throw invalid("cannot render an Invalid Date");
+
+  const parts = zoneParts(date, timeZone);
+  return `${parts.year}-${parts.month}-${parts.day}T${parts.hour}:${parts.minute}`;
+}
+
+/** How far `timeZone` sits from UTC at a given instant, in milliseconds. */
+function zoneOffsetMs(instant: number, timeZone: string): number {
+  const parts = zoneParts(new Date(instant), timeZone);
+  const asUtc = Date.UTC(
+    Number(parts.year),
+    Number(parts.month) - 1,
+    Number(parts.day),
+    Number(parts.hour),
+    Number(parts.minute),
+    Number(parts.second),
+    new Date(instant).getUTCMilliseconds(),
+  );
+  return instant - asUtc;
+}
+
+/** Splits an instant into calendar fields as they read in a timezone. */
+function zoneParts(date: Date, timeZone: string | undefined) {
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    hourCycle: "h23",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  });
+
+  const parts: Record<string, string> = {};
+  for (const part of formatter.formatToParts(date)) {
+    if (part.type !== "literal") parts[part.type] = part.value;
+  }
+  return parts as Record<"year" | "month" | "day" | "hour" | "minute" | "second", string>;
+}
+
+/** `datetime-local` may omit seconds; `Date.parse` wants them. */
+function withSeconds(local: string): string {
+  return /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}$/.test(local) ? `${local}:00` : local;
+}
+
+function invalid(message: string): AppSettingsError {
+  return new AppSettingsError(message, { code: "invalid_value" });
+}

package/src/errors.ts

@@ -0,0 +1,95 @@
+import type { ErrorCode } from "./types.ts";
+
+/**
+ * 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 class AppSettingsError extends Error {
+  override 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;
+    },
+  ) {
+    super(message, { cause: options.cause });
+    this.code = options.code;
+    this.status = options.status;
+    this.requestId = options.requestId;
+    this.request = options.request;
+    this.body = options.body;
+  }
+
+  /** Whether the failure is worth trying again unchanged. */
+  get retryable(): boolean {
+    if (this.code === "network_error" || this.code === "timeout" || this.code === "unavailable") {
+      return true;
+    }
+    return this.status === 429 || (this.status !== undefined && this.status >= 500);
+  }
+
+  /** Narrows an unknown caught value to this class. */
+  static is(error: unknown): error is AppSettingsError {
+    return error instanceof AppSettingsError;
+  }
+}
+
+/** The requested thing does not exist, or this key may not see that it does. */
+export const isNotFound = (error: unknown): boolean => codeIs(error, "not_found");
+
+/** The API key was missing, malformed, expired or revoked. */
+export const isUnauthorized = (error: unknown): boolean => codeIs(error, "unauthorized");
+
+/** The key is real but is fenced out of what it asked for. */
+export const isForbidden = (error: unknown): boolean => codeIs(error, "forbidden");
+
+/** The request collided with existing state, such as a duplicate name. */
+export const isConflict = (error: unknown): boolean => codeIs(error, "conflict");
+
+/** The request was malformed or a value failed validation. */
+export const isInvalidRequest = (error: unknown): boolean =>
+  codeIs(error, "invalid_request") || codeIs(error, "invalid_value");
+
+function codeIs(error: unknown, code: AnyErrorCode): boolean {
+  return AppSettingsError.is(error) && error.code === code;
+}

package/src/http.ts

@@ -0,0 +1,314 @@
+import { AppSettingsError } from "./errors.ts";
+
+/** 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 function createTransport(options: TransportOptions): TransportConfig {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new AppSettingsError(
+      "No `fetch` is available. Pass one as `fetch` in the client options, or run on Node 18+, Bun, Deno or a browser.",
+      { code: "invalid_request" },
+    );
+  }
+  if (!options.baseUrl) {
+    throw new AppSettingsError("`baseUrl` is required, for example http://localhost:8080", {
+      code: "invalid_request",
+    });
+  }
+  if (!options.apiKey) {
+    throw new AppSettingsError("`apiKey` is required; every route below /api/v1 needs one", {
+      code: "invalid_request",
+    });
+  }
+
+  return {
+    // A trailing slash would double up when paths are appended.
+    baseUrl: options.baseUrl.replace(/\/+$/, ""),
+    apiKey: options.apiKey,
+    // Unbind so an implementation that checks its receiver (the browser's) works.
+    fetch: (input, init) => fetchImpl(input, init),
+    timeoutMs: options.timeoutMs ?? 10_000,
+    retries: Math.max(0, options.retries ?? 2),
+    retryDelayMs: Math.max(0, options.retryDelayMs ?? 200),
+    headers: { ...options.headers },
+  };
+}
+
+/** 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 async function request<T>(config: TransportConfig, spec: RequestSpec): Promise<T> {
+  const url = config.baseUrl + spec.path + buildQuery(spec.query);
+  const label = `${spec.method} ${spec.path}`;
+  const timeoutMs = spec.options?.timeoutMs ?? config.timeoutMs;
+
+  const headers: Record<string, string> = {
+    accept: "application/json",
+    authorization: `Bearer ${config.apiKey}`,
+    ...config.headers,
+    ...lowercaseKeys(spec.options?.headers),
+  };
+  let payload: string | undefined;
+  if (spec.body !== undefined) {
+    payload = JSON.stringify(spec.body);
+    headers["content-type"] = "application/json";
+  }
+
+  // POST is the only non-idempotent method here, so it is the only one a retry
+  // could duplicate. Everything else is safe to repeat.
+  const attempts = spec.method === "POST" ? 1 : config.retries + 1;
+  let lastError: AppSettingsError | undefined;
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    if (attempt > 0) {
+      await delay(backoffFor(attempt, config.retryDelayMs, lastError), spec.options?.signal);
+    }
+
+    let response: Response;
+    try {
+      response = await config.fetch(url, {
+        method: spec.method,
+        headers,
+        body: payload,
+        signal: timeoutSignal(timeoutMs, spec.options?.signal),
+      });
+    } catch (cause) {
+      lastError = fromThrown(cause, label, spec.options?.signal, timeoutMs);
+      // An abort is the caller's decision, and a timeout has already spent its
+      // budget on a signal we cannot renew. Neither is worth another attempt.
+      if (lastError.code === "aborted" || lastError.code === "timeout") throw lastError;
+      continue;
+    }
+
+    if (response.ok) return (await decode<T>(response, label)) as T;
+
+    lastError = await errorFromResponse(response, label);
+    if (!lastError.retryable || attempt === attempts - 1) throw lastError;
+  }
+
+  throw lastError ?? new AppSettingsError(`${label} failed`, { code: "network_error", request: label });
+}
+
+/** Renders a query string, repeating a key for each element of an array. */
+export function buildQuery(query: Record<string, QueryValue> | undefined): string {
+  if (!query) return "";
+
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null || value === "") continue;
+    if (Array.isArray(value)) {
+      for (const item of value) if (item !== "") params.append(key, item);
+    } else {
+      params.append(key, String(value));
+    }
+  }
+
+  const rendered = params.toString();
+  return rendered ? `?${rendered}` : "";
+}
+
+/** Reads a successful body, tolerating the empty one a 204 carries. */
+async function decode<T>(response: Response, label: string): Promise<T | undefined> {
+  if (response.status === 204) return undefined;
+
+  const text = await response.text();
+  if (text === "") return undefined;
+
+  try {
+    return JSON.parse(text) as T;
+  } catch (cause) {
+    throw new AppSettingsError(`${label} returned a body that is not JSON`, {
+      code: "invalid_response",
+      status: response.status,
+      requestId: response.headers.get("x-request-id") ?? undefined,
+      request: label,
+      body: text.slice(0, 512),
+      cause,
+    });
+  }
+}
+
+/**
+ * Turns a failed response into an error, preferring the server's own message.
+ * Every endpoint returns `{"error": {"code", "message"}}`, so this is usually
+ * exact; a proxy in between might not, hence the fallbacks.
+ */
+async function errorFromResponse(response: Response, label: string): Promise<AppSettingsError> {
+  const requestId = response.headers.get("x-request-id") ?? undefined;
+  const text = await response.text().catch(() => "");
+
+  let body: unknown;
+  try {
+    body = text ? JSON.parse(text) : undefined;
+  } catch {
+    body = text;
+  }
+
+  const detail = (body as { error?: { code?: string; message?: string } } | undefined)?.error;
+  const message = detail?.message ?? (text ? text.slice(0, 512) : response.statusText) ?? "request failed";
+
+  return new AppSettingsError(`${label} failed with ${response.status}: ${message}`, {
+    code: (detail?.code as AppSettingsError["code"]) ?? statusToCode(response.status),
+    status: response.status,
+    requestId,
+    request: label,
+    body,
+  });
+}
+
+/** Maps a status onto the code the server would have used for it. */
+function statusToCode(status: number): AppSettingsError["code"] {
+  switch (status) {
+    case 400:
+      return "invalid_request";
+    case 401:
+      return "unauthorized";
+    case 403:
+      return "forbidden";
+    case 404:
+      return "not_found";
+    case 409:
+      return "conflict";
+    case 503:
+      return "unavailable";
+    default:
+      return status >= 500 ? "internal_error" : "invalid_request";
+  }
+}
+
+/** Classifies a throw from `fetch` itself, which never reached a response. */
+function fromThrown(cause: unknown, label: string, signal: AbortSignal | undefined, timeoutMs: number): AppSettingsError {
+  const aborted = cause instanceof Error && (cause.name === "AbortError" || cause.name === "TimeoutError");
+
+  if (aborted && signal?.aborted) {
+    return new AppSettingsError(`${label} was aborted`, { code: "aborted", request: label, cause });
+  }
+  if (aborted) {
+    return new AppSettingsError(`${label} timed out after ${timeoutMs}ms`, {
+      code: "timeout",
+      request: label,
+      cause,
+    });
+  }
+  return new AppSettingsError(`${label} could not reach the server: ${errorText(cause)}`, {
+    code: "network_error",
+    request: label,
+    cause,
+  });
+}
+
+/** Combines the caller's signal with a timeout, using whichever exist. */
+function timeoutSignal(timeoutMs: number, signal: AbortSignal | undefined): AbortSignal | undefined {
+  const timeout = timeoutMs > 0 && typeof AbortSignal?.timeout === "function" ? AbortSignal.timeout(timeoutMs) : undefined;
+
+  if (!timeout) return signal;
+  if (!signal) return timeout;
+  if (typeof AbortSignal.any === "function") return AbortSignal.any([signal, timeout]);
+
+  // An older runtime without AbortSignal.any: the caller's own signal wins,
+  // since losing cancellation is worse than losing a timeout.
+  return signal;
+}
+
+/** Honours `Retry-After` when the server sent one, else backs off exponentially. */
+function backoffFor(attempt: number, base: number, previous: AppSettingsError | undefined): number {
+  const retryAfter = retryAfterMs(previous);
+  if (retryAfter !== undefined) return retryAfter;
+
+  const exponential = base * 2 ** (attempt - 1);
+  // Jitter keeps a fleet of clients from retrying in lockstep after an outage.
+  return exponential + Math.random() * base;
+}
+
+function retryAfterMs(error: AppSettingsError | undefined): number | undefined {
+  if (error?.status !== 429 && error?.status !== 503) return undefined;
+  const header = (error.body as { retry_after?: number } | undefined)?.retry_after;
+  return typeof header === "number" && header >= 0 ? header * 1000 : undefined;
+}
+
+/** A cancellable sleep, so an abort during backoff takes effect immediately. */
+function delay(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(finish, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    function finish() {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }
+    function onAbort() {
+      clearTimeout(timer);
+      reject(new AppSettingsError("the request was aborted", { code: "aborted" }));
+    }
+  });
+}
+
+function lowercaseKeys(headers: Record<string, string> | undefined): Record<string, string> {
+  if (!headers) return {};
+  return Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
+}
+
+function errorText(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+/**
+ * A TypeScript SDK for the App Settings API.
+ *
+ * It has no dependencies and runs anywhere `fetch` does: browsers, Node 18+,
+ * Bun, Deno and edge runtimes.
+ */
+
+export { AppSettingsClient } from "./client.ts";
+export type {
+  ClientOptions,
+  CreateGroupInput,
+  CreateKeyInput,
+  CreateSettingInput,
+  FetchLike,
+  GroupValueOptions,
+  ListSettingsOptions,
+  RequestOptions,
+  ResolveOptions,
+  ResolveUserOptions,
+  UpdateSettingInput,
+} from "./client.ts";
+
+export { SettingsSnapshot, snapshotFrom } from "./snapshot.ts";
+
+export { createSettingsStore } from "./store.ts";
+export type { SettingsState, SettingsStore, SettingsStoreOptions } from "./store.ts";
+
+export {
+  AppSettingsError,
+  isConflict,
+  isForbidden,
+  isInvalidRequest,
+  isNotFound,
+  isUnauthorized,
+} from "./errors.ts";
+export type { AnyErrorCode, ClientErrorCode } from "./errors.ts";
+
+export { isInstant, localToInstant, parseInstant, toDateTimeLocal, toInstant } from "./datetime.ts";
+
+export type {
+  ApiKey,
+  CreatedApiKey,
+  Environment,
+  ErrorCode,
+  Group,
+  GroupMember,
+  Health,
+  IntermediateValue,
+  Override,
+  PersonalValue,
+  Platform,
+  ResolvedSetting,
+  ResolveResponse,
+  Role,
+  Scope,
+  SelectOption,
+  ServerValue,
+  Setting,
+  SettingScope,
+  SettingType,
+  SettingValue,
+  TypeConfig,
+  ValueSource,
+  WhoAmI,
+} from "./types.ts";