app-settings-js 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1004 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  AppSettingsClient: () => AppSettingsClient,
+  AppSettingsError: () => AppSettingsError,
+  SettingsSnapshot: () => SettingsSnapshot,
+  createSettingsStore: () => createSettingsStore,
+  isConflict: () => isConflict,
+  isForbidden: () => isForbidden,
+  isInstant: () => isInstant,
+  isInvalidRequest: () => isInvalidRequest,
+  isNotFound: () => isNotFound,
+  isUnauthorized: () => isUnauthorized,
+  localToInstant: () => localToInstant,
+  parseInstant: () => parseInstant,
+  snapshotFrom: () => snapshotFrom,
+  toDateTimeLocal: () => toDateTimeLocal,
+  toInstant: () => toInstant
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/errors.ts
+class AppSettingsError extends Error {
+  name = "AppSettingsError";
+  code;
+  status;
+  requestId;
+  request;
+  body;
+  constructor(message, options) {
+    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;
+  }
+  get retryable() {
+    if (this.code === "network_error" || this.code === "timeout" || this.code === "unavailable") {
+      return true;
+    }
+    return this.status === 429 || this.status !== undefined && this.status >= 500;
+  }
+  static is(error) {
+    return error instanceof AppSettingsError;
+  }
+}
+var isNotFound = (error) => codeIs(error, "not_found");
+var isUnauthorized = (error) => codeIs(error, "unauthorized");
+var isForbidden = (error) => codeIs(error, "forbidden");
+var isConflict = (error) => codeIs(error, "conflict");
+var isInvalidRequest = (error) => codeIs(error, "invalid_request") || codeIs(error, "invalid_value");
+function codeIs(error, code) {
+  return AppSettingsError.is(error) && error.code === code;
+}
+
+// src/http.ts
+function createTransport(options) {
+  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 {
+    baseUrl: options.baseUrl.replace(/\/+$/, ""),
+    apiKey: options.apiKey,
+    fetch: (input, init) => fetchImpl(input, init),
+    timeoutMs: options.timeoutMs ?? 1e4,
+    retries: Math.max(0, options.retries ?? 2),
+    retryDelayMs: Math.max(0, options.retryDelayMs ?? 200),
+    headers: { ...options.headers }
+  };
+}
+async function request(config, spec) {
+  const url = config.baseUrl + spec.path + buildQuery(spec.query);
+  const label = `${spec.method} ${spec.path}`;
+  const timeoutMs = spec.options?.timeoutMs ?? config.timeoutMs;
+  const headers = {
+    accept: "application/json",
+    authorization: `Bearer ${config.apiKey}`,
+    ...config.headers,
+    ...lowercaseKeys(spec.options?.headers)
+  };
+  let payload;
+  if (spec.body !== undefined) {
+    payload = JSON.stringify(spec.body);
+    headers["content-type"] = "application/json";
+  }
+  const attempts = spec.method === "POST" ? 1 : config.retries + 1;
+  let lastError;
+  for (let attempt = 0;attempt < attempts; attempt++) {
+    if (attempt > 0) {
+      await delay(backoffFor(attempt, config.retryDelayMs, lastError), spec.options?.signal);
+    }
+    let 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);
+      if (lastError.code === "aborted" || lastError.code === "timeout")
+        throw lastError;
+      continue;
+    }
+    if (response.ok)
+      return await decode(response, label);
+    lastError = await errorFromResponse(response, label);
+    if (!lastError.retryable || attempt === attempts - 1)
+      throw lastError;
+  }
+  throw lastError ?? new AppSettingsError(`${label} failed`, { code: "network_error", request: label });
+}
+function buildQuery(query) {
+  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}` : "";
+}
+async function decode(response, label) {
+  if (response.status === 204)
+    return;
+  const text = await response.text();
+  if (text === "")
+    return;
+  try {
+    return JSON.parse(text);
+  } 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
+    });
+  }
+}
+async function errorFromResponse(response, label) {
+  const requestId = response.headers.get("x-request-id") ?? undefined;
+  const text = await response.text().catch(() => "");
+  let body;
+  try {
+    body = text ? JSON.parse(text) : undefined;
+  } catch {
+    body = text;
+  }
+  const detail = body?.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 ?? statusToCode(response.status),
+    status: response.status,
+    requestId,
+    request: label,
+    body
+  });
+}
+function statusToCode(status) {
+  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";
+  }
+}
+function fromThrown(cause, label, signal, timeoutMs) {
+  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
+  });
+}
+function timeoutSignal(timeoutMs, signal) {
+  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]);
+  return signal;
+}
+function backoffFor(attempt, base, previous) {
+  const retryAfter = retryAfterMs(previous);
+  if (retryAfter !== undefined)
+    return retryAfter;
+  const exponential = base * 2 ** (attempt - 1);
+  return exponential + Math.random() * base;
+}
+function retryAfterMs(error) {
+  if (error?.status !== 429 && error?.status !== 503)
+    return;
+  const header = error.body?.retry_after;
+  return typeof header === "number" && header >= 0 ? header * 1000 : undefined;
+}
+function delay(ms, signal) {
+  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) {
+  if (!headers)
+    return {};
+  return Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
+}
+function errorText(cause) {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+// src/datetime.ts
+var RFC_3339 = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+var DATETIME_LOCAL = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}(:\d{2}(\.\d+)?)?$/;
+function toInstant(value) {
+  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();
+}
+function localToInstant(local, timeZone) {
+  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);
+  if (!timeZone) {
+    const parsed = new Date(local);
+    if (Number.isNaN(parsed.getTime()))
+      throw invalid(`"${local}" is not a real moment`);
+    return parsed.toISOString();
+  }
+  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();
+}
+function parseInstant(value) {
+  if (value === null || value === undefined)
+    return;
+  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;
+}
+function isInstant(value) {
+  return typeof value === "string" && RFC_3339.test(value) && !Number.isNaN(Date.parse(value));
+}
+function toDateTimeLocal(value, timeZone) {
+  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}`;
+}
+function zoneOffsetMs(instant, timeZone) {
+  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;
+}
+function zoneParts(date, timeZone) {
+  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 = {};
+  for (const part of formatter.formatToParts(date)) {
+    if (part.type !== "literal")
+      parts[part.type] = part.value;
+  }
+  return parts;
+}
+function withSeconds(local) {
+  return /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}$/.test(local) ? `${local}:00` : local;
+}
+function invalid(message) {
+  return new AppSettingsError(message, { code: "invalid_value" });
+}
+
+// src/snapshot.ts
+class SettingsSnapshot {
+  settings;
+  environment;
+  platforms;
+  userId;
+  role;
+  resolvedAt;
+  #byName;
+  constructor(response) {
+    this.settings = Object.freeze([...response.settings ?? []]);
+    this.environment = response.environment;
+    this.platforms = Object.freeze([...response.platforms ?? []]);
+    this.userId = response.user_id;
+    this.role = response.role;
+    this.resolvedAt = parseInstant(response.resolved_at) ?? new Date;
+    this.#byName = new Map(this.settings.map((setting) => [setting.name, setting]));
+    Object.freeze(this);
+  }
+  get names() {
+    return [...this.#byName.keys()];
+  }
+  get size() {
+    return this.settings.length;
+  }
+  has(name) {
+    return this.#byName.has(name);
+  }
+  get(name) {
+    return this.#byName.get(name);
+  }
+  value(name) {
+    return this.#byName.get(name)?.value ?? null;
+  }
+  isSet(name) {
+    const setting = this.#byName.get(name);
+    return setting !== undefined && setting.source !== "UNSET";
+  }
+  source(name) {
+    return this.#byName.get(name)?.source;
+  }
+  boolean(name, fallback = false) {
+    return this.#typed(name, fallback, "boolean", (value) => typeof value === "boolean");
+  }
+  number(name, fallback = 0) {
+    return this.#typed(name, fallback, "number", (value) => typeof value === "number" && Number.isFinite(value));
+  }
+  string(name, fallback = "") {
+    return this.#typed(name, fallback, "string", (value) => typeof value === "string");
+  }
+  date(name, fallback) {
+    const value = this.#present(name);
+    if (value === undefined || value === null)
+      return fallback;
+    if (typeof value !== "string")
+      throw this.#mismatch(name, "a date-time string", value);
+    return parseInstant(value);
+  }
+  list(name, fallback = []) {
+    const value = this.#present(name);
+    if (value === undefined || value === null)
+      return fallback;
+    return Array.isArray(value) ? value : [value];
+  }
+  json(name, fallback) {
+    const value = this.#present(name);
+    return value === undefined || value === null ? fallback : value;
+  }
+  options(name) {
+    return this.#byName.get(name)?.type_config?.options ?? [];
+  }
+  override(name) {
+    return this.#byName.get(name)?.override;
+  }
+  visibleOverride(name) {
+    const override = this.override(name);
+    return override?.visible ? override : undefined;
+  }
+  isEnforced(name) {
+    return this.override(name)?.enforced === true;
+  }
+  editable() {
+    return this.settings.filter((setting) => setting.scope === "PERSONAL" && setting.override?.enforced !== true);
+  }
+  filter(predicate) {
+    return this.settings.filter(predicate);
+  }
+  toObject() {
+    return Object.fromEntries(this.settings.map((setting) => [setting.name, setting.value]));
+  }
+  toJSON() {
+    return {
+      environment: this.environment,
+      platforms: [...this.platforms],
+      user_id: this.userId,
+      role: this.role,
+      settings: [...this.settings],
+      resolved_at: this.resolvedAt.toISOString()
+    };
+  }
+  with(name, value, source = "PERSONAL") {
+    if (!this.#byName.has(name))
+      return this;
+    return new SettingsSnapshot({
+      ...this.toJSON(),
+      settings: this.settings.map((setting) => setting.name === name ? { ...setting, value, source } : setting)
+    });
+  }
+  [Symbol.iterator]() {
+    return this.settings[Symbol.iterator]();
+  }
+  #present(name) {
+    const setting = this.#byName.get(name);
+    if (setting === undefined || setting.source === "UNSET")
+      return;
+    return setting.value ?? undefined;
+  }
+  #typed(name, fallback, expected, matches) {
+    const value = this.#present(name);
+    if (value === undefined)
+      return fallback;
+    if (!matches(value))
+      throw this.#mismatch(name, `a ${expected}`, value);
+    return value;
+  }
+  #mismatch(name, expected, value) {
+    const declared = this.#byName.get(name)?.type;
+    return new AppSettingsError(`setting "${name}" is declared ${declared} and holds ${describe(value)}, not ${expected}`, { code: "type_mismatch" });
+  }
+}
+function snapshotFrom(response) {
+  return new SettingsSnapshot(response);
+}
+function describe(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "an array";
+  return `a ${typeof value}`;
+}
+
+// src/client.ts
+class AppSettingsClient {
+  #transport;
+  #environment;
+  #platform;
+  constructor(options) {
+    this.#transport = createTransport(options);
+    this.#environment = options.environment;
+    this.#platform = options.platform === undefined ? undefined : toArray(options.platform);
+  }
+  get environment() {
+    return this.#environment;
+  }
+  withEnvironment(environment) {
+    return new AppSettingsClient({
+      ...this.#transport,
+      environment,
+      platform: this.#platform
+    });
+  }
+  async resolveUser(userId, options = {}) {
+    const response = await this.#request({
+      method: "GET",
+      path: `/api/v1/resolve/user/${encode(userId)}`,
+      query: {
+        ...this.#resolveQuery(options),
+        group_id: options.groupId === undefined ? undefined : toArray(options.groupId)
+      },
+      options
+    });
+    return new SettingsSnapshot(response);
+  }
+  async resolveServer(options = {}) {
+    const response = await this.#request({
+      method: "GET",
+      path: "/api/v1/resolve/server",
+      query: this.#resolveQuery(options),
+      options
+    });
+    return new SettingsSnapshot(response);
+  }
+  whoami(options) {
+    return this.#request({ method: "GET", path: "/api/v1/whoami", options });
+  }
+  health(options) {
+    return this.#request({ method: "GET", path: "/healthz", options });
+  }
+  ready(options) {
+    return this.#request({ method: "GET", path: "/readyz", options });
+  }
+  settings = {
+    list: async (options = {}) => {
+      const body = await this.#request({
+        method: "GET",
+        path: "/api/v1/settings",
+        query: {
+          environment: options.environment ?? this.#environment,
+          platform: options.platform ?? this.#platform?.[0],
+          scope: options.scope
+        },
+        options
+      });
+      return body.settings ?? [];
+    },
+    get: (id, options) => this.#request({ method: "GET", path: `/api/v1/settings/${encode(id)}`, options }),
+    create: async (input, options) => {
+      const environment = input.environment ?? this.#environment;
+      if (!environment)
+        throw missingEnvironment("settings.create");
+      return this.#request({
+        method: "POST",
+        path: "/api/v1/settings",
+        body: {
+          name: input.name,
+          description: input.description ?? "",
+          type: input.type,
+          type_config: input.typeConfig ?? {},
+          role: input.role,
+          scope: input.scope,
+          platform: input.platform,
+          environment,
+          default_value: input.defaultValue ?? null
+        },
+        options
+      });
+    },
+    update: (id, input, options) => this.#request({
+      method: "PATCH",
+      path: `/api/v1/settings/${encode(id)}`,
+      body: {
+        description: input.description,
+        type_config: input.typeConfig,
+        role: input.role,
+        default_value: input.defaultValue
+      },
+      options
+    }),
+    delete: (id, options = {}) => this.#request({
+      method: "DELETE",
+      path: `/api/v1/settings/${encode(id)}`,
+      query: { cascade: options.cascade ? "true" : undefined },
+      options
+    })
+  };
+  values = {
+    server: {
+      get: (settingId, options) => this.#request({ method: "GET", path: `/api/v1/settings/${encode(settingId)}/server`, options }),
+      set: async (settingId, value, options) => this.#request({
+        method: "PUT",
+        path: `/api/v1/settings/${encode(settingId)}/server`,
+        body: { value: requireValue(value) },
+        options
+      }),
+      clear: (settingId, options) => this.#request({ method: "DELETE", path: `/api/v1/settings/${encode(settingId)}/server`, options })
+    },
+    personal: {
+      get: (settingId, userId, options) => this.#request({
+        method: "GET",
+        path: `/api/v1/settings/${encode(settingId)}/personal/${encode(userId)}`,
+        options
+      }),
+      set: async (settingId, userId, value, options) => this.#request({
+        method: "PUT",
+        path: `/api/v1/settings/${encode(settingId)}/personal/${encode(userId)}`,
+        body: { value: requireValue(value) },
+        options
+      }),
+      clear: (settingId, userId, options) => this.#request({
+        method: "DELETE",
+        path: `/api/v1/settings/${encode(settingId)}/personal/${encode(userId)}`,
+        options
+      })
+    },
+    group: {
+      get: (settingId, groupId, options) => this.#request({
+        method: "GET",
+        path: `/api/v1/settings/${encode(settingId)}/intermediate/${encode(groupId)}`,
+        options
+      }),
+      set: async (settingId, groupId, value, options = {}) => this.#request({
+        method: "PUT",
+        path: `/api/v1/settings/${encode(settingId)}/intermediate/${encode(groupId)}`,
+        body: { value: requireValue(value), visible: options.visible, enforced: options.enforced },
+        options
+      }),
+      clear: (settingId, groupId, options) => this.#request({
+        method: "DELETE",
+        path: `/api/v1/settings/${encode(settingId)}/intermediate/${encode(groupId)}`,
+        options
+      })
+    }
+  };
+  groups = {
+    list: async (options = {}) => {
+      const body = await this.#request({
+        method: "GET",
+        path: "/api/v1/groups",
+        query: {
+          environment: options.environment ?? this.#environment,
+          include_ephemeral: options.includeEphemeral === false ? "false" : undefined
+        },
+        options
+      });
+      return body.groups ?? [];
+    },
+    get: (id, options) => this.#request({ method: "GET", path: `/api/v1/groups/${encode(id)}`, options }),
+    create: (input, options) => this.#request({
+      method: "POST",
+      path: "/api/v1/groups",
+      body: {
+        name: input.name,
+        description: input.description ?? "",
+        environment: input.environment === undefined ? this.#environment ?? null : input.environment,
+        priority: input.priority ?? 0,
+        ephemeral: input.ephemeral ?? false,
+        members: input.members
+      },
+      options
+    }),
+    update: (id, input, options) => this.#request({ method: "PATCH", path: `/api/v1/groups/${encode(id)}`, body: input, options }),
+    delete: (id, options) => this.#request({ method: "DELETE", path: `/api/v1/groups/${encode(id)}`, options }),
+    members: async (id, options) => {
+      const body = await this.#request({
+        method: "GET",
+        path: `/api/v1/groups/${encode(id)}/members`,
+        options
+      });
+      return body.members ?? [];
+    },
+    addMembers: async (id, userIds, options) => {
+      const body = await this.#request({
+        method: "POST",
+        path: `/api/v1/groups/${encode(id)}/members`,
+        body: { members: userIds },
+        options
+      });
+      return body.added ?? 0;
+    },
+    removeMembers: async (id, userIds, options) => {
+      const body = await this.#request({
+        method: "DELETE",
+        path: `/api/v1/groups/${encode(id)}/members`,
+        body: { members: userIds },
+        options
+      });
+      return body.removed ?? 0;
+    }
+  };
+  taxonomy = {
+    roles: async (options) => (await this.#request({ method: "GET", path: "/api/v1/roles", options })).roles ?? [],
+    upsertRole: (name, input, options) => this.#request({
+      method: "PUT",
+      path: `/api/v1/roles/${encode(name)}`,
+      body: { rank: input.rank, description: input.description ?? "" },
+      options
+    }),
+    deleteRole: (name, options) => this.#request({ method: "DELETE", path: `/api/v1/roles/${encode(name)}`, options }),
+    platforms: async (options) => (await this.#request({ method: "GET", path: "/api/v1/platforms", options })).platforms ?? [],
+    upsertPlatform: (name, description = "", options) => this.#request({ method: "PUT", path: `/api/v1/platforms/${encode(name)}`, body: { description }, options }),
+    deletePlatform: (name, options) => this.#request({ method: "DELETE", path: `/api/v1/platforms/${encode(name)}`, options }),
+    environments: async (options) => (await this.#request({
+      method: "GET",
+      path: "/api/v1/environments",
+      options
+    })).environments ?? [],
+    upsertEnvironment: (name, description = "", options) => this.#request({ method: "PUT", path: `/api/v1/environments/${encode(name)}`, body: { description }, options }),
+    deleteEnvironment: (name, options) => this.#request({ method: "DELETE", path: `/api/v1/environments/${encode(name)}`, options })
+  };
+  keys = {
+    list: async (options = {}) => {
+      const body = await this.#request({
+        method: "GET",
+        path: "/api/v1/keys",
+        query: { include_revoked: options.includeRevoked ? "true" : undefined },
+        options
+      });
+      return body.keys ?? [];
+    },
+    create: (input, options) => this.#request({
+      method: "POST",
+      path: "/api/v1/keys",
+      body: {
+        name: input.name,
+        scopes: input.scopes,
+        environments: input.environments,
+        platforms: input.platforms,
+        role: input.role,
+        expires_at: input.expiresAt instanceof Date ? input.expiresAt.toISOString() : input.expiresAt,
+        expires_in: input.expiresIn
+      },
+      options
+    }),
+    revoke: (id, options) => this.#request({ method: "DELETE", path: `/api/v1/keys/${encode(id)}`, options })
+  };
+  #request(spec) {
+    return request(this.#transport, spec);
+  }
+  #resolveQuery(options) {
+    const environment = options.environment ?? this.#environment;
+    if (!environment)
+      throw missingEnvironment("resolve");
+    const platform = options.platform === undefined ? this.#platform : toArray(options.platform);
+    return { environment, platform, role: options.role };
+  }
+}
+function toArray(value) {
+  return Array.isArray(value) ? value : [value];
+}
+function encode(segment) {
+  return encodeURIComponent(segment);
+}
+function requireValue(value) {
+  if (value === undefined) {
+    throw new AppSettingsError("`value` is required; use clear() to remove a value", {
+      code: "invalid_value"
+    });
+  }
+  return value;
+}
+function missingEnvironment(operation) {
+  return new AppSettingsError(`${operation} needs an environment. Pass one as \`environment\` in the call, ` + "or set it once on the client.", { code: "invalid_request" });
+}
+// src/store.ts
+function createSettingsStore(client, options = {}) {
+  const listeners = new Set;
+  const initial = initialSnapshot(options.initialData);
+  let userId = options.userId;
+  let state = {
+    status: initial ? "ready" : "idle",
+    snapshot: initial,
+    error: null,
+    isValidating: false,
+    updatedAt: initial ? Date.now() : null
+  };
+  const serverState = state;
+  let generation = 0;
+  let inFlight = null;
+  let interval;
+  let disposed = false;
+  function emit(next) {
+    state = { ...state, ...next };
+    for (const listener of listeners)
+      listener();
+  }
+  async function load() {
+    if (disposed)
+      return state;
+    if (inFlight)
+      return inFlight;
+    const ticket = ++generation;
+    emit({ isValidating: true, status: state.snapshot ? state.status : "loading" });
+    inFlight = (async () => {
+      try {
+        const resolveOptions = {
+          environment: options.environment,
+          platform: options.platform,
+          role: options.role,
+          groupId: options.groupId
+        };
+        const snapshot = userId ? await client.resolveUser(userId, resolveOptions) : await client.resolveServer(resolveOptions);
+        if (ticket !== generation || disposed)
+          return state;
+        emit({ status: "ready", snapshot, error: null, isValidating: false, updatedAt: Date.now() });
+      } catch (caught) {
+        if (ticket !== generation || disposed)
+          return state;
+        const error = asError(caught);
+        options.onError?.(error);
+        emit({ status: state.snapshot ? "ready" : "error", error, isValidating: false });
+      } finally {
+        if (ticket === generation)
+          inFlight = null;
+      }
+      return state;
+    })();
+    return inFlight;
+  }
+  function writeTarget(name) {
+    const snapshot = state.snapshot;
+    if (!snapshot) {
+      throw new AppSettingsError(`cannot write "${name}" before the first resolution has loaded`, {
+        code: "invalid_request"
+      });
+    }
+    if (!userId) {
+      throw new AppSettingsError(`cannot write "${name}": this store resolves the server layer, which has no personal value. ` + "Give the store a `userId`, or use client.values.server.set().", { code: "invalid_request" });
+    }
+    const setting = snapshot.get(name);
+    if (!setting) {
+      throw new AppSettingsError(`no setting named "${name}" is visible to this key and role`, {
+        code: "not_found"
+      });
+    }
+    return { snapshot, setting, userId };
+  }
+  async function writePersonal(name, value) {
+    const target = writeTarget(name);
+    const previous = state.snapshot;
+    const optimistic = value !== undefined && !target.snapshot.isEnforced(name) ? target.snapshot.with(name, value) : target.snapshot;
+    if (optimistic !== previous)
+      emit({ snapshot: optimistic });
+    try {
+      if (value === undefined) {
+        await client.values.personal.clear(target.setting.id, target.userId);
+      } else {
+        await client.values.personal.set(target.setting.id, target.userId, value);
+      }
+    } catch (caught) {
+      if (state.snapshot === optimistic)
+        emit({ snapshot: previous });
+      throw asError(caught);
+    }
+    await load();
+  }
+  function startTimers() {
+    const target = eventTarget();
+    if (!target)
+      return;
+    if (options.revalidateOnFocus)
+      target.addEventListener("focus", onWake);
+    if (options.revalidateOnReconnect)
+      target.addEventListener("online", onWake);
+  }
+  function stopTimers() {
+    if (interval !== undefined) {
+      clearInterval(interval);
+      interval = undefined;
+    }
+    const target = eventTarget();
+    target?.removeEventListener("focus", onWake);
+    target?.removeEventListener("online", onWake);
+  }
+  function onWake() {
+    load();
+  }
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      if (listeners.size === 1 && !disposed) {
+        if (!state.snapshot)
+          load();
+        if (options.refreshIntervalMs && options.refreshIntervalMs > 0) {
+          interval = setInterval(onWake, options.refreshIntervalMs);
+        }
+        startTimers();
+      }
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0)
+          stopTimers();
+      };
+    },
+    getSnapshot: () => state,
+    getServerSnapshot: () => serverState,
+    refresh: load,
+    set: (name, value) => writePersonal(name, normalise(value)),
+    clear: (name) => writePersonal(name, undefined),
+    setUser(next) {
+      if (next === userId)
+        return;
+      userId = next;
+      generation++;
+      inFlight = null;
+      emit({ status: "loading", snapshot: null, error: null, updatedAt: null });
+      load();
+    },
+    dispose() {
+      disposed = true;
+      generation++;
+      stopTimers();
+      listeners.clear();
+    }
+  };
+}
+function eventTarget() {
+  const candidate = globalThis.window;
+  return typeof candidate?.addEventListener === "function" ? candidate : undefined;
+}
+function initialSnapshot(data) {
+  if (!data)
+    return null;
+  return data instanceof SettingsSnapshot ? data : new SettingsSnapshot(data);
+}
+function normalise(value) {
+  return value instanceof Date ? toInstant(value) : value;
+}
+function asError(caught) {
+  if (AppSettingsError.is(caught))
+    return caught;
+  return new AppSettingsError(caught instanceof Error ? caught.message : String(caught), {
+    code: "internal_error",
+    cause: caught
+  });
+}
+
+//# debugId=A4CB969932E0318764756E2164756E21
+//# sourceMappingURL=index.cjs.map