@hush-hush/sdk 3.0.0 → 4.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![ci](https://github.com/alrayyes/hush-hush-node/actions/workflows/ci.yml/badge.svg)](https://github.com/alrayyes/hush-hush-node/actions/workflows/ci.yml)
 [![Codecov](https://codecov.io/gh/alrayyes/hush-hush-node/graph/badge.svg)](https://codecov.io/gh/alrayyes/hush-hush-node)
-[![npm](https://img.shields.io/npm/v/hush-hush)](https://www.npmjs.com/package/hush-hush)
+[![npm](https://img.shields.io/npm/v/%40hush-hush%2Fsdk)](https://www.npmjs.com/package/@hush-hush/sdk)
 [![release](https://img.shields.io/github/v/release/alrayyes/hush-hush-node)](https://github.com/alrayyes/hush-hush-node/releases)
 [![license](https://img.shields.io/github/license/alrayyes/hush-hush-node)](LICENSE)
 
@@ -13,7 +13,7 @@ OpenAPI spec and kept in sync with it automatically.
 ## Install
 
 ```sh
-npm install hush-hush
+npm install @hush-hush/sdk
 ```
 
 Requires Node.js 22 or newer.
@@ -21,7 +21,7 @@ Requires Node.js 22 or newer.
 ## Quickstart
 
 ```ts
-import { Client } from "hush-hush";
+import { Client } from "@hush-hush/sdk";
 
 const client = new Client("https://hush-hush.example.com", {
   apiKey: "your-api-key", // or set HUSH_HUSH_API_KEY

package/dist/index.cjs

@@ -0,0 +1,282 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  APIError: () => APIError,
+  Client: () => Client,
+  HushHushError: () => HushHushError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var HushHushError = class extends Error {
+};
+var APIError = class _APIError extends HushHushError {
+  /** The HTTP status hush-hush responded with. */
+  status;
+  /** The response's request-ID header, when hush-hush's spec documents one for it. */
+  requestId;
+  /** The parsed `error` field from hush-hush's error body, if present. */
+  apiMessage;
+  /** The raw, unparsed response body, for a caller that needs more than `apiMessage`. */
+  body;
+  constructor(status, body, requestId) {
+    const apiMessage = _APIError.parseMessage(body);
+    super(
+      apiMessage !== void 0 ? `hush-hush: ${status}: ${apiMessage}` : `hush-hush: unexpected status ${status}`
+    );
+    this.name = "APIError";
+    this.status = status;
+    this.requestId = requestId;
+    this.apiMessage = apiMessage;
+    this.body = body;
+  }
+  static parseMessage(body) {
+    try {
+      const parsed = JSON.parse(new TextDecoder().decode(body));
+      if (typeof parsed === "object" && parsed !== null && "error" in parsed) {
+        const value = parsed.error;
+        if (typeof value === "string") return value;
+      }
+    } catch {
+    }
+    return void 0;
+  }
+};
+
+// src/retry.ts
+var DEFAULT_MAX_RETRIES = 3;
+function isRetryableStatus(status) {
+  return status >= 500 || status === 429;
+}
+function retryAfterMs(response) {
+  const value = response.headers.get("retry-after");
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) {
+    return seconds >= 0 ? seconds * 1e3 : void 0;
+  }
+  const when = Date.parse(value);
+  if (Number.isNaN(when)) return void 0;
+  return Math.max(when - Date.now(), 0);
+}
+function backoffMs(attempt, retryAfterOverrideMs) {
+  if (retryAfterOverrideMs !== void 0) return retryAfterOverrideMs;
+  const base = 100 * 2 ** (attempt - 1);
+  return base + Math.random() * base;
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function fetchWithRetry(fetchImpl, input, init, maxRetries) {
+  let nextDelayOverrideMs;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    if (attempt > 0) {
+      await delay(backoffMs(attempt, nextDelayOverrideMs));
+      nextDelayOverrideMs = void 0;
+    }
+    let response;
+    try {
+      response = await fetchImpl(input, init);
+    } catch (err) {
+      if (attempt === maxRetries) throw err;
+      continue;
+    }
+    if (!isRetryableStatus(response.status) || attempt === maxRetries) {
+      return response;
+    }
+    nextDelayOverrideMs = retryAfterMs(response);
+    await response.body?.cancel();
+  }
+  throw new Error("fetchWithRetry: unreachable \u2014 maxRetries must be >= 0");
+}
+
+// src/client.ts
+var API_KEY_ENV_VAR = "HUSH_HUSH_API_KEY";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var Client = class {
+  baseUrl;
+  apiKey;
+  timeoutMs;
+  maxRetries;
+  fetchImpl;
+  /**
+   * @param baseUrl - hush-hush's base URL, e.g. `https://hush-hush.example.com`.
+   * @param options - Credential, timeout, and retry configuration.
+   */
+  constructor(baseUrl, options = {}) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey ?? process.env[API_KEY_ENV_VAR];
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  /** Answers whether the server process is up. Needs no credential. */
+  async health() {
+    const response = await this.request("GET", "/healthz");
+    return await response.json();
+  }
+  /**
+   * Stores an already-sealed value under a new object id. Requires a credential.
+   *
+   * @param id - The new object's id. Must match hush-hush's id pattern (lowercase alphanumeric, `-`/`_`).
+   * @param value - The already-sealed (encrypted) value. This SDK never encrypts or decrypts anything.
+   * @param options.usedBy - Consumers (repos or hosts) recorded as depending on this object.
+   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+   * @throws {APIError} If the server responds with anything other than 201 (e.g. 409 if the id exists).
+   */
+  async createObject(id, value, options = {}) {
+    const response = await this.request("POST", "/objects", {
+      authenticated: true,
+      caller: options.caller,
+      jsonBody: {
+        id,
+        value: base64Encode(value),
+        ...options.usedBy !== void 0 ? { used_by: options.usedBy } : {}
+      }
+    });
+    return await response.json();
+  }
+  /**
+   * Fetches an object's sealed ciphertext exactly as stored — this SDK never
+   * decrypts it, the same as the server. Needs no credential.
+   *
+   * @param id - The object's id.
+   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+   * @throws {APIError} If the server responds with anything other than 200 (e.g. 404).
+   */
+  async getObject(id, options = {}) {
+    const response = await this.request("GET", `/objects/${encodeURIComponent(id)}`, {
+      caller: options.caller
+    });
+    return new Uint8Array(await response.arrayBuffer());
+  }
+  /**
+   * Replaces the stored ciphertext for an existing object. The object's id
+   * and used-by metadata are unchanged. Requires a credential.
+   *
+   * @param id - The existing object's id.
+   * @param value - The new already-sealed (encrypted) value.
+   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+   * @throws {APIError} If the server responds with anything other than 200 (e.g. 401 or 404).
+   */
+  async updateObject(id, value, options = {}) {
+    const response = await this.request("PUT", `/objects/${encodeURIComponent(id)}`, {
+      authenticated: true,
+      caller: options.caller,
+      jsonBody: { value: base64Encode(value) }
+    });
+    return await response.json();
+  }
+  /**
+   * Permanently removes an object. A subsequent fetch by this id returns 404. Requires a credential.
+   *
+   * @param id - The object's id.
+   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+   * @throws {APIError} If the server responds with anything other than 204 (e.g. 401 or 404).
+   */
+  async deleteObject(id, options = {}) {
+    await this.request("DELETE", `/objects/${encodeURIComponent(id)}`, {
+      authenticated: true,
+      caller: options.caller
+    });
+  }
+  /**
+   * Returns the recorded list of consumers for an object — the "what
+   * depends on this" mapping set at creation. Needs no credential.
+   *
+   * @param id - The object's id.
+   * @throws {APIError} If the server responds with anything other than 200 (e.g. 404).
+   */
+  async getObjectUsedBy(id) {
+    const response = await this.request("GET", `/objects/${encodeURIComponent(id)}/used-by`);
+    return await response.json();
+  }
+  /**
+   * Queries the audit log — every create, read, update, and delete call is
+   * recorded here. Needs no credential. Filters combine with AND when more
+   * than one is given.
+   *
+   * hush-hush's `/audit-log` endpoint has no pagination parameters, so this
+   * always resolves with the full matching result set as a single array,
+   * never a page plus a cursor.
+   *
+   * @param filter - Optional `objectId`/`caller`/`from`/`to` filters.
+   */
+  async queryAuditLog(filter = {}) {
+    const response = await this.request("GET", "/audit-log", {
+      query: {
+        object_id: filter.objectId,
+        caller: filter.caller,
+        from: filter.from,
+        to: filter.to
+      }
+    });
+    return await response.json();
+  }
+  async request(method, path, options = {}) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    for (const [key, value] of Object.entries(options.query ?? {})) {
+      if (value !== void 0) url.searchParams.set(key, value);
+    }
+    const headers = new Headers();
+    if (options.caller !== void 0) headers.set("X-Caller", options.caller);
+    if (options.authenticated === true && this.apiKey !== void 0) {
+      headers.set("Authorization", `Bearer ${this.apiKey}`);
+    }
+    let body = options.body;
+    if (options.jsonBody !== void 0) {
+      headers.set("Content-Type", "application/json");
+      body = JSON.stringify(options.jsonBody);
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await fetchWithRetry(
+        this.fetchImpl,
+        url.toString(),
+        { method, headers, signal: controller.signal, ...body !== void 0 ? { body } : {} },
+        this.maxRetries
+      );
+      if (!response.ok) {
+        const responseBody = new Uint8Array(await response.arrayBuffer());
+        throw new APIError(
+          response.status,
+          responseBody,
+          response.headers.get("x-request-id") ?? void 0
+        );
+      }
+      return response;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+};
+function base64Encode(value) {
+  return Buffer.from(value).toString("base64");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APIError,
+  Client,
+  HushHushError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/retry.ts","../src/client.ts"],"sourcesContent":["export type {\n  AuditLogAction,\n  AuditLogEntry,\n  AuditLogFilter,\n  ClientOptions,\n  Health,\n  ObjectMetadata,\n  UsedBy,\n} from \"./client.js\";\nexport { Client } from \"./client.js\";\nexport { APIError, HushHushError } from \"./errors.js\";\n","/** Base class for every error this SDK raises. */\nexport class HushHushError extends Error {}\n\n/**\n * Raised for any non-2xx response from hush-hush.\n *\n * `requestId` is populated only when the response carries a documented\n * request-ID header; hush-hush's spec doesn't currently document one, so\n * this is usually `undefined`. Kept as a property rather than omitted so a\n * future spec addition doesn't change this type's shape.\n */\nexport class APIError extends HushHushError {\n  /** The HTTP status hush-hush responded with. */\n  readonly status: number;\n  /** The response's request-ID header, when hush-hush's spec documents one for it. */\n  readonly requestId: string | undefined;\n  /** The parsed `error` field from hush-hush's error body, if present. */\n  readonly apiMessage: string | undefined;\n  /** The raw, unparsed response body, for a caller that needs more than `apiMessage`. */\n  readonly body: Uint8Array;\n\n  constructor(status: number, body: Uint8Array, requestId: string | undefined) {\n    const apiMessage = APIError.parseMessage(body);\n    super(\n      apiMessage !== undefined\n        ? `hush-hush: ${status}: ${apiMessage}`\n        : `hush-hush: unexpected status ${status}`,\n    );\n    this.name = \"APIError\";\n    this.status = status;\n    this.requestId = requestId;\n    this.apiMessage = apiMessage;\n    this.body = body;\n  }\n\n  private static parseMessage(body: Uint8Array): string | undefined {\n    try {\n      const parsed: unknown = JSON.parse(new TextDecoder().decode(body));\n      if (typeof parsed === \"object\" && parsed !== null && \"error\" in parsed) {\n        const value = (parsed as { error?: unknown }).error;\n        if (typeof value === \"string\") return value;\n      }\n    } catch {\n      // Not JSON, or not decodable as UTF-8 — apiMessage stays undefined.\n    }\n    return undefined;\n  }\n}\n","/**\n * Retries a request only on network failure or an HTTP 5xx/429 response,\n * using exponential backoff with jitter, and honors a `Retry-After` response\n * header ahead of the computed backoff delay when present. Any other 4xx is\n * never retried — it won't succeed on a second attempt, and retrying only\n * delays the real error reaching the caller.\n */\n\nexport const DEFAULT_MAX_RETRIES = 3;\n\nfunction isRetryableStatus(status: number): boolean {\n  return status >= 500 || status === 429;\n}\n\nfunction retryAfterMs(response: Response): number | undefined {\n  const value = response.headers.get(\"retry-after\");\n  if (!value) return undefined;\n\n  const seconds = Number(value);\n  if (Number.isFinite(seconds)) {\n    return seconds >= 0 ? seconds * 1000 : undefined;\n  }\n\n  const when = Date.parse(value);\n  if (Number.isNaN(when)) return undefined;\n  return Math.max(when - Date.now(), 0);\n}\n\nfunction backoffMs(attempt: number, retryAfterOverrideMs: number | undefined): number {\n  if (retryAfterOverrideMs !== undefined) return retryAfterOverrideMs;\n  const base = 100 * 2 ** (attempt - 1);\n  return base + Math.random() * base;\n}\n\nfunction delay(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nexport async function fetchWithRetry(\n  fetchImpl: typeof fetch,\n  input: string,\n  init: RequestInit,\n  maxRetries: number,\n): Promise<Response> {\n  let nextDelayOverrideMs: number | undefined;\n\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    if (attempt > 0) {\n      await delay(backoffMs(attempt, nextDelayOverrideMs));\n      nextDelayOverrideMs = undefined;\n    }\n\n    let response: Response;\n    try {\n      response = await fetchImpl(input, init);\n    } catch (err) {\n      if (attempt === maxRetries) throw err;\n      continue;\n    }\n\n    if (!isRetryableStatus(response.status) || attempt === maxRetries) {\n      return response;\n    }\n    nextDelayOverrideMs = retryAfterMs(response);\n    await response.body?.cancel();\n  }\n\n  throw new Error(\"fetchWithRetry: unreachable — maxRetries must be >= 0\");\n}\n","import { APIError } from \"./errors.js\";\nimport type { components } from \"./generated/types.js\";\nimport { DEFAULT_MAX_RETRIES, fetchWithRetry } from \"./retry.js\";\n\ntype _ObjectMetadata = components[\"schemas\"][\"ObjectMetadata\"];\ntype _UsedBy = components[\"schemas\"][\"UsedBy\"];\ntype _Health = components[\"schemas\"][\"Health\"];\ntype _AuditLogEntry = components[\"schemas\"][\"AuditLogEntry\"];\n\n/** An object's id and its recorded consumers. */\nexport interface ObjectMetadata extends _ObjectMetadata {}\n/** The consumers (repos or hosts) recorded as depending on an object. */\nexport interface UsedBy extends _UsedBy {}\n/** hush-hush's liveness response. */\nexport interface Health extends _Health {}\n/** One recorded create, read, update, or delete call. */\nexport interface AuditLogEntry extends _AuditLogEntry {}\n/** The kind of call an {@link AuditLogEntry} recorded. */\nexport type AuditLogAction = AuditLogEntry[\"action\"];\n\nconst API_KEY_ENV_VAR = \"HUSH_HUSH_API_KEY\";\nconst DEFAULT_TIMEOUT_MS = 30_000;\n\n/** Options accepted by the {@link Client} constructor. */\nexport interface ClientOptions {\n  /**\n   * Bearer credential for write paths (create/update/delete). Falls back to\n   * the `HUSH_HUSH_API_KEY` environment variable when not supplied. Read\n   * paths (get, used-by, audit-log query) need no credential at all.\n   */\n  apiKey?: string;\n  /** Per-request timeout, in milliseconds. Defaults to 30000. */\n  timeoutMs?: number;\n  /** Maximum retry attempts for network failures and 5xx/429 responses. Defaults to 3. */\n  maxRetries?: number;\n  /** Override for the `fetch` implementation, mainly for tests. Defaults to global `fetch`. */\n  fetch?: typeof fetch;\n}\n\n/** Optional filters for {@link Client.queryAuditLog}. Filters combine with AND when more than one is set. */\nexport interface AuditLogFilter {\n  /** Restrict to entries for this object id. */\n  objectId?: string;\n  /** Restrict to entries recorded with this caller identity. */\n  caller?: string;\n  /** Restrict to entries at or after this ISO-8601 timestamp. */\n  from?: string;\n  /** Restrict to entries at or before this ISO-8601 timestamp. */\n  to?: string;\n}\n\ninterface RequestOptions {\n  authenticated?: boolean;\n  caller?: string | undefined;\n  query?: Record<string, string | undefined>;\n  body?: RequestInit[\"body\"];\n  jsonBody?: unknown;\n}\n\n/**\n * A typed client for hush-hush, a standalone secrets object store.\n *\n * @example\n * ```ts\n * const client = new Client(\"https://hush-hush.example.com\");\n * const meta = await client.createObject(\"my-object\", sealedBytes);\n * ```\n */\nexport class Client {\n  private readonly baseUrl: string;\n  private readonly apiKey: string | undefined;\n  private readonly timeoutMs: number;\n  private readonly maxRetries: number;\n  private readonly fetchImpl: typeof fetch;\n\n  /**\n   * @param baseUrl - hush-hush's base URL, e.g. `https://hush-hush.example.com`.\n   * @param options - Credential, timeout, and retry configuration.\n   */\n  constructor(baseUrl: string, options: ClientOptions = {}) {\n    this.baseUrl = baseUrl.replace(/\\/+$/, \"\");\n    this.apiKey = options.apiKey ?? process.env[API_KEY_ENV_VAR];\n    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;\n    this.fetchImpl = options.fetch ?? fetch;\n  }\n\n  /** Answers whether the server process is up. Needs no credential. */\n  async health(): Promise<Health> {\n    const response = await this.request(\"GET\", \"/healthz\");\n    return (await response.json()) as Health;\n  }\n\n  /**\n   * Stores an already-sealed value under a new object id. Requires a credential.\n   *\n   * @param id - The new object's id. Must match hush-hush's id pattern (lowercase alphanumeric, `-`/`_`).\n   * @param value - The already-sealed (encrypted) value. This SDK never encrypts or decrypts anything.\n   * @param options.usedBy - Consumers (repos or hosts) recorded as depending on this object.\n   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.\n   * @throws {APIError} If the server responds with anything other than 201 (e.g. 409 if the id exists).\n   */\n  async createObject(\n    id: string,\n    value: Uint8Array,\n    options: { usedBy?: string[]; caller?: string } = {},\n  ): Promise<ObjectMetadata> {\n    const response = await this.request(\"POST\", \"/objects\", {\n      authenticated: true,\n      caller: options.caller,\n      jsonBody: {\n        id,\n        value: base64Encode(value),\n        ...(options.usedBy !== undefined ? { used_by: options.usedBy } : {}),\n      },\n    });\n    return (await response.json()) as ObjectMetadata;\n  }\n\n  /**\n   * Fetches an object's sealed ciphertext exactly as stored — this SDK never\n   * decrypts it, the same as the server. Needs no credential.\n   *\n   * @param id - The object's id.\n   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.\n   * @throws {APIError} If the server responds with anything other than 200 (e.g. 404).\n   */\n  async getObject(id: string, options: { caller?: string } = {}): Promise<Uint8Array> {\n    const response = await this.request(\"GET\", `/objects/${encodeURIComponent(id)}`, {\n      caller: options.caller,\n    });\n    return new Uint8Array(await response.arrayBuffer());\n  }\n\n  /**\n   * Replaces the stored ciphertext for an existing object. The object's id\n   * and used-by metadata are unchanged. Requires a credential.\n   *\n   * @param id - The existing object's id.\n   * @param value - The new already-sealed (encrypted) value.\n   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.\n   * @throws {APIError} If the server responds with anything other than 200 (e.g. 401 or 404).\n   */\n  async updateObject(\n    id: string,\n    value: Uint8Array,\n    options: { caller?: string } = {},\n  ): Promise<ObjectMetadata> {\n    const response = await this.request(\"PUT\", `/objects/${encodeURIComponent(id)}`, {\n      authenticated: true,\n      caller: options.caller,\n      jsonBody: { value: base64Encode(value) },\n    });\n    return (await response.json()) as ObjectMetadata;\n  }\n\n  /**\n   * Permanently removes an object. A subsequent fetch by this id returns 404. Requires a credential.\n   *\n   * @param id - The object's id.\n   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.\n   * @throws {APIError} If the server responds with anything other than 204 (e.g. 401 or 404).\n   */\n  async deleteObject(id: string, options: { caller?: string } = {}): Promise<void> {\n    await this.request(\"DELETE\", `/objects/${encodeURIComponent(id)}`, {\n      authenticated: true,\n      caller: options.caller,\n    });\n  }\n\n  /**\n   * Returns the recorded list of consumers for an object — the \"what\n   * depends on this\" mapping set at creation. Needs no credential.\n   *\n   * @param id - The object's id.\n   * @throws {APIError} If the server responds with anything other than 200 (e.g. 404).\n   */\n  async getObjectUsedBy(id: string): Promise<UsedBy> {\n    const response = await this.request(\"GET\", `/objects/${encodeURIComponent(id)}/used-by`);\n    return (await response.json()) as UsedBy;\n  }\n\n  /**\n   * Queries the audit log — every create, read, update, and delete call is\n   * recorded here. Needs no credential. Filters combine with AND when more\n   * than one is given.\n   *\n   * hush-hush's `/audit-log` endpoint has no pagination parameters, so this\n   * always resolves with the full matching result set as a single array,\n   * never a page plus a cursor.\n   *\n   * @param filter - Optional `objectId`/`caller`/`from`/`to` filters.\n   */\n  async queryAuditLog(filter: AuditLogFilter = {}): Promise<AuditLogEntry[]> {\n    const response = await this.request(\"GET\", \"/audit-log\", {\n      query: {\n        object_id: filter.objectId,\n        caller: filter.caller,\n        from: filter.from,\n        to: filter.to,\n      },\n    });\n    return (await response.json()) as AuditLogEntry[];\n  }\n\n  private async request(\n    method: string,\n    path: string,\n    options: RequestOptions = {},\n  ): Promise<Response> {\n    const url = new URL(`${this.baseUrl}${path}`);\n    for (const [key, value] of Object.entries(options.query ?? {})) {\n      if (value !== undefined) url.searchParams.set(key, value);\n    }\n\n    const headers = new Headers();\n    if (options.caller !== undefined) headers.set(\"X-Caller\", options.caller);\n    if (options.authenticated === true && this.apiKey !== undefined) {\n      headers.set(\"Authorization\", `Bearer ${this.apiKey}`);\n    }\n\n    let body: RequestInit[\"body\"] = options.body;\n    if (options.jsonBody !== undefined) {\n      headers.set(\"Content-Type\", \"application/json\");\n      body = JSON.stringify(options.jsonBody);\n    }\n\n    const controller = new AbortController();\n    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);\n    try {\n      const response = await fetchWithRetry(\n        this.fetchImpl,\n        url.toString(),\n        { method, headers, signal: controller.signal, ...(body !== undefined ? { body } : {}) },\n        this.maxRetries,\n      );\n      if (!response.ok) {\n        const responseBody = new Uint8Array(await response.arrayBuffer());\n        throw new APIError(\n          response.status,\n          responseBody,\n          response.headers.get(\"x-request-id\") ?? undefined,\n        );\n      }\n      return response;\n    } finally {\n      clearTimeout(timeout);\n    }\n  }\n}\n\nfunction base64Encode(value: Uint8Array): string {\n  return Buffer.from(value).toString(\"base64\");\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,276 @@
+interface components {
+    schemas: {
+        /** @example mattermost_deploy_webhook */
+        ObjectId: string;
+        CreateObjectRequest: {
+            id: components["schemas"]["ObjectId"];
+            /**
+             * Format: byte
+             * @description The sealed (encrypted) value, base64-encoded.
+             */
+            value: string;
+            used_by?: components["schemas"]["UsedByList"];
+        };
+        UpdateObjectRequest: {
+            /**
+             * Format: byte
+             * @description The new sealed (encrypted) value, base64-encoded.
+             */
+            value: string;
+        };
+        ObjectMetadata: {
+            id: components["schemas"]["ObjectId"];
+            used_by?: components["schemas"]["UsedByList"];
+        };
+        /**
+         * @description The consumers (repos or hosts) recorded as depending on this
+         *     object. Set at creation; unaffected by later value updates.
+         * @example [
+         *       "homelab/vps-docker"
+         *     ]
+         */
+        UsedByList: string[];
+        UsedBy: {
+            used_by: components["schemas"]["UsedByList"];
+        };
+        AuditLogEntry: {
+            object_id: components["schemas"]["ObjectId"];
+            /** @enum {string} */
+            action: "create" | "read" | "update" | "delete";
+            /** Format: date-time */
+            timestamp: string;
+            /** @description The caller's presented identity, if any. */
+            caller?: string;
+            /**
+             * @description The request's source IP. Unlike caller, this is never
+             *     self-reported - it's the one piece of the request nobody gets
+             *     to lie about via a header. Currently the immediate TCP peer's
+             *     address; this service isn't deployed behind a reverse proxy or
+             *     load balancer, so X-Forwarded-For (or similar) support isn't
+             *     implemented yet.
+             */
+            ip: string;
+        };
+        Health: {
+            /** @constant */
+            status: "ok";
+        };
+        Error: {
+            /**
+             * @description What went wrong, in terms safe to show a caller. Nothing here
+             *     handles authentication with a detail worth holding back.
+             * @example unknown object
+             */
+            error: string;
+        };
+    };
+    responses: {
+        /** @description The request is missing a valid bearer token. */
+        Unauthorized: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "error": "missing or invalid bearer token"
+                 *     }
+                 */
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description No object is stored under that id. */
+        NotFound: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "error": "unknown object"
+                 *     }
+                 */
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+    };
+    parameters: {
+        /**
+         * @description The object's id, which is the last path segment and so has to
+         *     survive being in a URL.
+         */
+        id: components["schemas"]["ObjectId"];
+        /**
+         * @description The caller's own identity - a repo or host name, whatever the
+         *     caller wants attributed to it in the audit log. Not authenticated
+         *     or verified: a courtesy label a caller presents about itself, not
+         *     an identity check the service performs. Absent means the
+         *     resulting audit log entry's caller field is empty.
+         */
+        caller: string;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
+type _ObjectMetadata = components["schemas"]["ObjectMetadata"];
+type _UsedBy = components["schemas"]["UsedBy"];
+type _Health = components["schemas"]["Health"];
+type _AuditLogEntry = components["schemas"]["AuditLogEntry"];
+/** An object's id and its recorded consumers. */
+interface ObjectMetadata extends _ObjectMetadata {
+}
+/** The consumers (repos or hosts) recorded as depending on an object. */
+interface UsedBy extends _UsedBy {
+}
+/** hush-hush's liveness response. */
+interface Health extends _Health {
+}
+/** One recorded create, read, update, or delete call. */
+interface AuditLogEntry extends _AuditLogEntry {
+}
+/** The kind of call an {@link AuditLogEntry} recorded. */
+type AuditLogAction = AuditLogEntry["action"];
+/** Options accepted by the {@link Client} constructor. */
+interface ClientOptions {
+    /**
+     * Bearer credential for write paths (create/update/delete). Falls back to
+     * the `HUSH_HUSH_API_KEY` environment variable when not supplied. Read
+     * paths (get, used-by, audit-log query) need no credential at all.
+     */
+    apiKey?: string;
+    /** Per-request timeout, in milliseconds. Defaults to 30000. */
+    timeoutMs?: number;
+    /** Maximum retry attempts for network failures and 5xx/429 responses. Defaults to 3. */
+    maxRetries?: number;
+    /** Override for the `fetch` implementation, mainly for tests. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+}
+/** Optional filters for {@link Client.queryAuditLog}. Filters combine with AND when more than one is set. */
+interface AuditLogFilter {
+    /** Restrict to entries for this object id. */
+    objectId?: string;
+    /** Restrict to entries recorded with this caller identity. */
+    caller?: string;
+    /** Restrict to entries at or after this ISO-8601 timestamp. */
+    from?: string;
+    /** Restrict to entries at or before this ISO-8601 timestamp. */
+    to?: string;
+}
+/**
+ * A typed client for hush-hush, a standalone secrets object store.
+ *
+ * @example
+ * ```ts
+ * const client = new Client("https://hush-hush.example.com");
+ * const meta = await client.createObject("my-object", sealedBytes);
+ * ```
+ */
+declare class Client {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    /**
+     * @param baseUrl - hush-hush's base URL, e.g. `https://hush-hush.example.com`.
+     * @param options - Credential, timeout, and retry configuration.
+     */
+    constructor(baseUrl: string, options?: ClientOptions);
+    /** Answers whether the server process is up. Needs no credential. */
+    health(): Promise<Health>;
+    /**
+     * Stores an already-sealed value under a new object id. Requires a credential.
+     *
+     * @param id - The new object's id. Must match hush-hush's id pattern (lowercase alphanumeric, `-`/`_`).
+     * @param value - The already-sealed (encrypted) value. This SDK never encrypts or decrypts anything.
+     * @param options.usedBy - Consumers (repos or hosts) recorded as depending on this object.
+     * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+     * @throws {APIError} If the server responds with anything other than 201 (e.g. 409 if the id exists).
+     */
+    createObject(id: string, value: Uint8Array, options?: {
+        usedBy?: string[];
+        caller?: string;
+    }): Promise<ObjectMetadata>;
+    /**
+     * Fetches an object's sealed ciphertext exactly as stored — this SDK never
+     * decrypts it, the same as the server. Needs no credential.
+     *
+     * @param id - The object's id.
+     * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+     * @throws {APIError} If the server responds with anything other than 200 (e.g. 404).
+     */
+    getObject(id: string, options?: {
+        caller?: string;
+    }): Promise<Uint8Array>;
+    /**
+     * Replaces the stored ciphertext for an existing object. The object's id
+     * and used-by metadata are unchanged. Requires a credential.
+     *
+     * @param id - The existing object's id.
+     * @param value - The new already-sealed (encrypted) value.
+     * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+     * @throws {APIError} If the server responds with anything other than 200 (e.g. 401 or 404).
+     */
+    updateObject(id: string, value: Uint8Array, options?: {
+        caller?: string;
+    }): Promise<ObjectMetadata>;
+    /**
+     * Permanently removes an object. A subsequent fetch by this id returns 404. Requires a credential.
+     *
+     * @param id - The object's id.
+     * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+     * @throws {APIError} If the server responds with anything other than 204 (e.g. 401 or 404).
+     */
+    deleteObject(id: string, options?: {
+        caller?: string;
+    }): Promise<void>;
+    /**
+     * Returns the recorded list of consumers for an object — the "what
+     * depends on this" mapping set at creation. Needs no credential.
+     *
+     * @param id - The object's id.
+     * @throws {APIError} If the server responds with anything other than 200 (e.g. 404).
+     */
+    getObjectUsedBy(id: string): Promise<UsedBy>;
+    /**
+     * Queries the audit log — every create, read, update, and delete call is
+     * recorded here. Needs no credential. Filters combine with AND when more
+     * than one is given.
+     *
+     * hush-hush's `/audit-log` endpoint has no pagination parameters, so this
+     * always resolves with the full matching result set as a single array,
+     * never a page plus a cursor.
+     *
+     * @param filter - Optional `objectId`/`caller`/`from`/`to` filters.
+     */
+    queryAuditLog(filter?: AuditLogFilter): Promise<AuditLogEntry[]>;
+    private request;
+}
+
+/** Base class for every error this SDK raises. */
+declare class HushHushError extends Error {
+}
+/**
+ * Raised for any non-2xx response from hush-hush.
+ *
+ * `requestId` is populated only when the response carries a documented
+ * request-ID header; hush-hush's spec doesn't currently document one, so
+ * this is usually `undefined`. Kept as a property rather than omitted so a
+ * future spec addition doesn't change this type's shape.
+ */
+declare class APIError extends HushHushError {
+    /** The HTTP status hush-hush responded with. */
+    readonly status: number;
+    /** The response's request-ID header, when hush-hush's spec documents one for it. */
+    readonly requestId: string | undefined;
+    /** The parsed `error` field from hush-hush's error body, if present. */
+    readonly apiMessage: string | undefined;
+    /** The raw, unparsed response body, for a caller that needs more than `apiMessage`. */
+    readonly body: Uint8Array;
+    constructor(status: number, body: Uint8Array, requestId: string | undefined);
+    private static parseMessage;
+}
+
+export { APIError, type AuditLogAction, type AuditLogEntry, type AuditLogFilter, Client, type ClientOptions, type Health, HushHushError, type ObjectMetadata, type UsedBy };

package/dist/index.d.ts

@@ -0,0 +1,276 @@
+interface components {
+    schemas: {
+        /** @example mattermost_deploy_webhook */
+        ObjectId: string;
+        CreateObjectRequest: {
+            id: components["schemas"]["ObjectId"];
+            /**
+             * Format: byte
+             * @description The sealed (encrypted) value, base64-encoded.
+             */
+            value: string;
+            used_by?: components["schemas"]["UsedByList"];
+        };
+        UpdateObjectRequest: {
+            /**
+             * Format: byte
+             * @description The new sealed (encrypted) value, base64-encoded.
+             */
+            value: string;
+        };
+        ObjectMetadata: {
+            id: components["schemas"]["ObjectId"];
+            used_by?: components["schemas"]["UsedByList"];
+        };
+        /**
+         * @description The consumers (repos or hosts) recorded as depending on this
+         *     object. Set at creation; unaffected by later value updates.
+         * @example [
+         *       "homelab/vps-docker"
+         *     ]
+         */
+        UsedByList: string[];
+        UsedBy: {
+            used_by: components["schemas"]["UsedByList"];
+        };
+        AuditLogEntry: {
+            object_id: components["schemas"]["ObjectId"];
+            /** @enum {string} */
+            action: "create" | "read" | "update" | "delete";
+            /** Format: date-time */
+            timestamp: string;
+            /** @description The caller's presented identity, if any. */
+            caller?: string;
+            /**
+             * @description The request's source IP. Unlike caller, this is never
+             *     self-reported - it's the one piece of the request nobody gets
+             *     to lie about via a header. Currently the immediate TCP peer's
+             *     address; this service isn't deployed behind a reverse proxy or
+             *     load balancer, so X-Forwarded-For (or similar) support isn't
+             *     implemented yet.
+             */
+            ip: string;
+        };
+        Health: {
+            /** @constant */
+            status: "ok";
+        };
+        Error: {
+            /**
+             * @description What went wrong, in terms safe to show a caller. Nothing here
+             *     handles authentication with a detail worth holding back.
+             * @example unknown object
+             */
+            error: string;
+        };
+    };
+    responses: {
+        /** @description The request is missing a valid bearer token. */
+        Unauthorized: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "error": "missing or invalid bearer token"
+                 *     }
+                 */
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description No object is stored under that id. */
+        NotFound: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "error": "unknown object"
+                 *     }
+                 */
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+    };
+    parameters: {
+        /**
+         * @description The object's id, which is the last path segment and so has to
+         *     survive being in a URL.
+         */
+        id: components["schemas"]["ObjectId"];
+        /**
+         * @description The caller's own identity - a repo or host name, whatever the
+         *     caller wants attributed to it in the audit log. Not authenticated
+         *     or verified: a courtesy label a caller presents about itself, not
+         *     an identity check the service performs. Absent means the
+         *     resulting audit log entry's caller field is empty.
+         */
+        caller: string;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
+type _ObjectMetadata = components["schemas"]["ObjectMetadata"];
+type _UsedBy = components["schemas"]["UsedBy"];
+type _Health = components["schemas"]["Health"];
+type _AuditLogEntry = components["schemas"]["AuditLogEntry"];
+/** An object's id and its recorded consumers. */
+interface ObjectMetadata extends _ObjectMetadata {
+}
+/** The consumers (repos or hosts) recorded as depending on an object. */
+interface UsedBy extends _UsedBy {
+}
+/** hush-hush's liveness response. */
+interface Health extends _Health {
+}
+/** One recorded create, read, update, or delete call. */
+interface AuditLogEntry extends _AuditLogEntry {
+}
+/** The kind of call an {@link AuditLogEntry} recorded. */
+type AuditLogAction = AuditLogEntry["action"];
+/** Options accepted by the {@link Client} constructor. */
+interface ClientOptions {
+    /**
+     * Bearer credential for write paths (create/update/delete). Falls back to
+     * the `HUSH_HUSH_API_KEY` environment variable when not supplied. Read
+     * paths (get, used-by, audit-log query) need no credential at all.
+     */
+    apiKey?: string;
+    /** Per-request timeout, in milliseconds. Defaults to 30000. */
+    timeoutMs?: number;
+    /** Maximum retry attempts for network failures and 5xx/429 responses. Defaults to 3. */
+    maxRetries?: number;
+    /** Override for the `fetch` implementation, mainly for tests. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+}
+/** Optional filters for {@link Client.queryAuditLog}. Filters combine with AND when more than one is set. */
+interface AuditLogFilter {
+    /** Restrict to entries for this object id. */
+    objectId?: string;
+    /** Restrict to entries recorded with this caller identity. */
+    caller?: string;
+    /** Restrict to entries at or after this ISO-8601 timestamp. */
+    from?: string;
+    /** Restrict to entries at or before this ISO-8601 timestamp. */
+    to?: string;
+}
+/**
+ * A typed client for hush-hush, a standalone secrets object store.
+ *
+ * @example
+ * ```ts
+ * const client = new Client("https://hush-hush.example.com");
+ * const meta = await client.createObject("my-object", sealedBytes);
+ * ```
+ */
+declare class Client {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    /**
+     * @param baseUrl - hush-hush's base URL, e.g. `https://hush-hush.example.com`.
+     * @param options - Credential, timeout, and retry configuration.
+     */
+    constructor(baseUrl: string, options?: ClientOptions);
+    /** Answers whether the server process is up. Needs no credential. */
+    health(): Promise<Health>;
+    /**
+     * Stores an already-sealed value under a new object id. Requires a credential.
+     *
+     * @param id - The new object's id. Must match hush-hush's id pattern (lowercase alphanumeric, `-`/`_`).
+     * @param value - The already-sealed (encrypted) value. This SDK never encrypts or decrypts anything.
+     * @param options.usedBy - Consumers (repos or hosts) recorded as depending on this object.
+     * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+     * @throws {APIError} If the server responds with anything other than 201 (e.g. 409 if the id exists).
+     */
+    createObject(id: string, value: Uint8Array, options?: {
+        usedBy?: string[];
+        caller?: string;
+    }): Promise<ObjectMetadata>;
+    /**
+     * Fetches an object's sealed ciphertext exactly as stored — this SDK never
+     * decrypts it, the same as the server. Needs no credential.
+     *
+     * @param id - The object's id.
+     * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+     * @throws {APIError} If the server responds with anything other than 200 (e.g. 404).
+     */
+    getObject(id: string, options?: {
+        caller?: string;
+    }): Promise<Uint8Array>;
+    /**
+     * Replaces the stored ciphertext for an existing object. The object's id
+     * and used-by metadata are unchanged. Requires a credential.
+     *
+     * @param id - The existing object's id.
+     * @param value - The new already-sealed (encrypted) value.
+     * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+     * @throws {APIError} If the server responds with anything other than 200 (e.g. 401 or 404).
+     */
+    updateObject(id: string, value: Uint8Array, options?: {
+        caller?: string;
+    }): Promise<ObjectMetadata>;
+    /**
+     * Permanently removes an object. A subsequent fetch by this id returns 404. Requires a credential.
+     *
+     * @param id - The object's id.
+     * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+     * @throws {APIError} If the server responds with anything other than 204 (e.g. 401 or 404).
+     */
+    deleteObject(id: string, options?: {
+        caller?: string;
+    }): Promise<void>;
+    /**
+     * Returns the recorded list of consumers for an object — the "what
+     * depends on this" mapping set at creation. Needs no credential.
+     *
+     * @param id - The object's id.
+     * @throws {APIError} If the server responds with anything other than 200 (e.g. 404).
+     */
+    getObjectUsedBy(id: string): Promise<UsedBy>;
+    /**
+     * Queries the audit log — every create, read, update, and delete call is
+     * recorded here. Needs no credential. Filters combine with AND when more
+     * than one is given.
+     *
+     * hush-hush's `/audit-log` endpoint has no pagination parameters, so this
+     * always resolves with the full matching result set as a single array,
+     * never a page plus a cursor.
+     *
+     * @param filter - Optional `objectId`/`caller`/`from`/`to` filters.
+     */
+    queryAuditLog(filter?: AuditLogFilter): Promise<AuditLogEntry[]>;
+    private request;
+}
+
+/** Base class for every error this SDK raises. */
+declare class HushHushError extends Error {
+}
+/**
+ * Raised for any non-2xx response from hush-hush.
+ *
+ * `requestId` is populated only when the response carries a documented
+ * request-ID header; hush-hush's spec doesn't currently document one, so
+ * this is usually `undefined`. Kept as a property rather than omitted so a
+ * future spec addition doesn't change this type's shape.
+ */
+declare class APIError extends HushHushError {
+    /** The HTTP status hush-hush responded with. */
+    readonly status: number;
+    /** The response's request-ID header, when hush-hush's spec documents one for it. */
+    readonly requestId: string | undefined;
+    /** The parsed `error` field from hush-hush's error body, if present. */
+    readonly apiMessage: string | undefined;
+    /** The raw, unparsed response body, for a caller that needs more than `apiMessage`. */
+    readonly body: Uint8Array;
+    constructor(status: number, body: Uint8Array, requestId: string | undefined);
+    private static parseMessage;
+}
+
+export { APIError, type AuditLogAction, type AuditLogEntry, type AuditLogFilter, Client, type ClientOptions, type Health, HushHushError, type ObjectMetadata, type UsedBy };

package/dist/index.js

@@ -0,0 +1,253 @@
+// src/errors.ts
+var HushHushError = class extends Error {
+};
+var APIError = class _APIError extends HushHushError {
+  /** The HTTP status hush-hush responded with. */
+  status;
+  /** The response's request-ID header, when hush-hush's spec documents one for it. */
+  requestId;
+  /** The parsed `error` field from hush-hush's error body, if present. */
+  apiMessage;
+  /** The raw, unparsed response body, for a caller that needs more than `apiMessage`. */
+  body;
+  constructor(status, body, requestId) {
+    const apiMessage = _APIError.parseMessage(body);
+    super(
+      apiMessage !== void 0 ? `hush-hush: ${status}: ${apiMessage}` : `hush-hush: unexpected status ${status}`
+    );
+    this.name = "APIError";
+    this.status = status;
+    this.requestId = requestId;
+    this.apiMessage = apiMessage;
+    this.body = body;
+  }
+  static parseMessage(body) {
+    try {
+      const parsed = JSON.parse(new TextDecoder().decode(body));
+      if (typeof parsed === "object" && parsed !== null && "error" in parsed) {
+        const value = parsed.error;
+        if (typeof value === "string") return value;
+      }
+    } catch {
+    }
+    return void 0;
+  }
+};
+
+// src/retry.ts
+var DEFAULT_MAX_RETRIES = 3;
+function isRetryableStatus(status) {
+  return status >= 500 || status === 429;
+}
+function retryAfterMs(response) {
+  const value = response.headers.get("retry-after");
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) {
+    return seconds >= 0 ? seconds * 1e3 : void 0;
+  }
+  const when = Date.parse(value);
+  if (Number.isNaN(when)) return void 0;
+  return Math.max(when - Date.now(), 0);
+}
+function backoffMs(attempt, retryAfterOverrideMs) {
+  if (retryAfterOverrideMs !== void 0) return retryAfterOverrideMs;
+  const base = 100 * 2 ** (attempt - 1);
+  return base + Math.random() * base;
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function fetchWithRetry(fetchImpl, input, init, maxRetries) {
+  let nextDelayOverrideMs;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    if (attempt > 0) {
+      await delay(backoffMs(attempt, nextDelayOverrideMs));
+      nextDelayOverrideMs = void 0;
+    }
+    let response;
+    try {
+      response = await fetchImpl(input, init);
+    } catch (err) {
+      if (attempt === maxRetries) throw err;
+      continue;
+    }
+    if (!isRetryableStatus(response.status) || attempt === maxRetries) {
+      return response;
+    }
+    nextDelayOverrideMs = retryAfterMs(response);
+    await response.body?.cancel();
+  }
+  throw new Error("fetchWithRetry: unreachable \u2014 maxRetries must be >= 0");
+}
+
+// src/client.ts
+var API_KEY_ENV_VAR = "HUSH_HUSH_API_KEY";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var Client = class {
+  baseUrl;
+  apiKey;
+  timeoutMs;
+  maxRetries;
+  fetchImpl;
+  /**
+   * @param baseUrl - hush-hush's base URL, e.g. `https://hush-hush.example.com`.
+   * @param options - Credential, timeout, and retry configuration.
+   */
+  constructor(baseUrl, options = {}) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey ?? process.env[API_KEY_ENV_VAR];
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  /** Answers whether the server process is up. Needs no credential. */
+  async health() {
+    const response = await this.request("GET", "/healthz");
+    return await response.json();
+  }
+  /**
+   * Stores an already-sealed value under a new object id. Requires a credential.
+   *
+   * @param id - The new object's id. Must match hush-hush's id pattern (lowercase alphanumeric, `-`/`_`).
+   * @param value - The already-sealed (encrypted) value. This SDK never encrypts or decrypts anything.
+   * @param options.usedBy - Consumers (repos or hosts) recorded as depending on this object.
+   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+   * @throws {APIError} If the server responds with anything other than 201 (e.g. 409 if the id exists).
+   */
+  async createObject(id, value, options = {}) {
+    const response = await this.request("POST", "/objects", {
+      authenticated: true,
+      caller: options.caller,
+      jsonBody: {
+        id,
+        value: base64Encode(value),
+        ...options.usedBy !== void 0 ? { used_by: options.usedBy } : {}
+      }
+    });
+    return await response.json();
+  }
+  /**
+   * Fetches an object's sealed ciphertext exactly as stored — this SDK never
+   * decrypts it, the same as the server. Needs no credential.
+   *
+   * @param id - The object's id.
+   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+   * @throws {APIError} If the server responds with anything other than 200 (e.g. 404).
+   */
+  async getObject(id, options = {}) {
+    const response = await this.request("GET", `/objects/${encodeURIComponent(id)}`, {
+      caller: options.caller
+    });
+    return new Uint8Array(await response.arrayBuffer());
+  }
+  /**
+   * Replaces the stored ciphertext for an existing object. The object's id
+   * and used-by metadata are unchanged. Requires a credential.
+   *
+   * @param id - The existing object's id.
+   * @param value - The new already-sealed (encrypted) value.
+   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+   * @throws {APIError} If the server responds with anything other than 200 (e.g. 401 or 404).
+   */
+  async updateObject(id, value, options = {}) {
+    const response = await this.request("PUT", `/objects/${encodeURIComponent(id)}`, {
+      authenticated: true,
+      caller: options.caller,
+      jsonBody: { value: base64Encode(value) }
+    });
+    return await response.json();
+  }
+  /**
+   * Permanently removes an object. A subsequent fetch by this id returns 404. Requires a credential.
+   *
+   * @param id - The object's id.
+   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.
+   * @throws {APIError} If the server responds with anything other than 204 (e.g. 401 or 404).
+   */
+  async deleteObject(id, options = {}) {
+    await this.request("DELETE", `/objects/${encodeURIComponent(id)}`, {
+      authenticated: true,
+      caller: options.caller
+    });
+  }
+  /**
+   * Returns the recorded list of consumers for an object — the "what
+   * depends on this" mapping set at creation. Needs no credential.
+   *
+   * @param id - The object's id.
+   * @throws {APIError} If the server responds with anything other than 200 (e.g. 404).
+   */
+  async getObjectUsedBy(id) {
+    const response = await this.request("GET", `/objects/${encodeURIComponent(id)}/used-by`);
+    return await response.json();
+  }
+  /**
+   * Queries the audit log — every create, read, update, and delete call is
+   * recorded here. Needs no credential. Filters combine with AND when more
+   * than one is given.
+   *
+   * hush-hush's `/audit-log` endpoint has no pagination parameters, so this
+   * always resolves with the full matching result set as a single array,
+   * never a page plus a cursor.
+   *
+   * @param filter - Optional `objectId`/`caller`/`from`/`to` filters.
+   */
+  async queryAuditLog(filter = {}) {
+    const response = await this.request("GET", "/audit-log", {
+      query: {
+        object_id: filter.objectId,
+        caller: filter.caller,
+        from: filter.from,
+        to: filter.to
+      }
+    });
+    return await response.json();
+  }
+  async request(method, path, options = {}) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    for (const [key, value] of Object.entries(options.query ?? {})) {
+      if (value !== void 0) url.searchParams.set(key, value);
+    }
+    const headers = new Headers();
+    if (options.caller !== void 0) headers.set("X-Caller", options.caller);
+    if (options.authenticated === true && this.apiKey !== void 0) {
+      headers.set("Authorization", `Bearer ${this.apiKey}`);
+    }
+    let body = options.body;
+    if (options.jsonBody !== void 0) {
+      headers.set("Content-Type", "application/json");
+      body = JSON.stringify(options.jsonBody);
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await fetchWithRetry(
+        this.fetchImpl,
+        url.toString(),
+        { method, headers, signal: controller.signal, ...body !== void 0 ? { body } : {} },
+        this.maxRetries
+      );
+      if (!response.ok) {
+        const responseBody = new Uint8Array(await response.arrayBuffer());
+        throw new APIError(
+          response.status,
+          responseBody,
+          response.headers.get("x-request-id") ?? void 0
+        );
+      }
+      return response;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+};
+function base64Encode(value) {
+  return Buffer.from(value).toString("base64");
+}
+export {
+  APIError,
+  Client,
+  HushHushError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/retry.ts","../src/client.ts"],"sourcesContent":["/** Base class for every error this SDK raises. */\nexport class HushHushError extends Error {}\n\n/**\n * Raised for any non-2xx response from hush-hush.\n *\n * `requestId` is populated only when the response carries a documented\n * request-ID header; hush-hush's spec doesn't currently document one, so\n * this is usually `undefined`. Kept as a property rather than omitted so a\n * future spec addition doesn't change this type's shape.\n */\nexport class APIError extends HushHushError {\n  /** The HTTP status hush-hush responded with. */\n  readonly status: number;\n  /** The response's request-ID header, when hush-hush's spec documents one for it. */\n  readonly requestId: string | undefined;\n  /** The parsed `error` field from hush-hush's error body, if present. */\n  readonly apiMessage: string | undefined;\n  /** The raw, unparsed response body, for a caller that needs more than `apiMessage`. */\n  readonly body: Uint8Array;\n\n  constructor(status: number, body: Uint8Array, requestId: string | undefined) {\n    const apiMessage = APIError.parseMessage(body);\n    super(\n      apiMessage !== undefined\n        ? `hush-hush: ${status}: ${apiMessage}`\n        : `hush-hush: unexpected status ${status}`,\n    );\n    this.name = \"APIError\";\n    this.status = status;\n    this.requestId = requestId;\n    this.apiMessage = apiMessage;\n    this.body = body;\n  }\n\n  private static parseMessage(body: Uint8Array): string | undefined {\n    try {\n      const parsed: unknown = JSON.parse(new TextDecoder().decode(body));\n      if (typeof parsed === \"object\" && parsed !== null && \"error\" in parsed) {\n        const value = (parsed as { error?: unknown }).error;\n        if (typeof value === \"string\") return value;\n      }\n    } catch {\n      // Not JSON, or not decodable as UTF-8 — apiMessage stays undefined.\n    }\n    return undefined;\n  }\n}\n","/**\n * Retries a request only on network failure or an HTTP 5xx/429 response,\n * using exponential backoff with jitter, and honors a `Retry-After` response\n * header ahead of the computed backoff delay when present. Any other 4xx is\n * never retried — it won't succeed on a second attempt, and retrying only\n * delays the real error reaching the caller.\n */\n\nexport const DEFAULT_MAX_RETRIES = 3;\n\nfunction isRetryableStatus(status: number): boolean {\n  return status >= 500 || status === 429;\n}\n\nfunction retryAfterMs(response: Response): number | undefined {\n  const value = response.headers.get(\"retry-after\");\n  if (!value) return undefined;\n\n  const seconds = Number(value);\n  if (Number.isFinite(seconds)) {\n    return seconds >= 0 ? seconds * 1000 : undefined;\n  }\n\n  const when = Date.parse(value);\n  if (Number.isNaN(when)) return undefined;\n  return Math.max(when - Date.now(), 0);\n}\n\nfunction backoffMs(attempt: number, retryAfterOverrideMs: number | undefined): number {\n  if (retryAfterOverrideMs !== undefined) return retryAfterOverrideMs;\n  const base = 100 * 2 ** (attempt - 1);\n  return base + Math.random() * base;\n}\n\nfunction delay(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nexport async function fetchWithRetry(\n  fetchImpl: typeof fetch,\n  input: string,\n  init: RequestInit,\n  maxRetries: number,\n): Promise<Response> {\n  let nextDelayOverrideMs: number | undefined;\n\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    if (attempt > 0) {\n      await delay(backoffMs(attempt, nextDelayOverrideMs));\n      nextDelayOverrideMs = undefined;\n    }\n\n    let response: Response;\n    try {\n      response = await fetchImpl(input, init);\n    } catch (err) {\n      if (attempt === maxRetries) throw err;\n      continue;\n    }\n\n    if (!isRetryableStatus(response.status) || attempt === maxRetries) {\n      return response;\n    }\n    nextDelayOverrideMs = retryAfterMs(response);\n    await response.body?.cancel();\n  }\n\n  throw new Error(\"fetchWithRetry: unreachable — maxRetries must be >= 0\");\n}\n","import { APIError } from \"./errors.js\";\nimport type { components } from \"./generated/types.js\";\nimport { DEFAULT_MAX_RETRIES, fetchWithRetry } from \"./retry.js\";\n\ntype _ObjectMetadata = components[\"schemas\"][\"ObjectMetadata\"];\ntype _UsedBy = components[\"schemas\"][\"UsedBy\"];\ntype _Health = components[\"schemas\"][\"Health\"];\ntype _AuditLogEntry = components[\"schemas\"][\"AuditLogEntry\"];\n\n/** An object's id and its recorded consumers. */\nexport interface ObjectMetadata extends _ObjectMetadata {}\n/** The consumers (repos or hosts) recorded as depending on an object. */\nexport interface UsedBy extends _UsedBy {}\n/** hush-hush's liveness response. */\nexport interface Health extends _Health {}\n/** One recorded create, read, update, or delete call. */\nexport interface AuditLogEntry extends _AuditLogEntry {}\n/** The kind of call an {@link AuditLogEntry} recorded. */\nexport type AuditLogAction = AuditLogEntry[\"action\"];\n\nconst API_KEY_ENV_VAR = \"HUSH_HUSH_API_KEY\";\nconst DEFAULT_TIMEOUT_MS = 30_000;\n\n/** Options accepted by the {@link Client} constructor. */\nexport interface ClientOptions {\n  /**\n   * Bearer credential for write paths (create/update/delete). Falls back to\n   * the `HUSH_HUSH_API_KEY` environment variable when not supplied. Read\n   * paths (get, used-by, audit-log query) need no credential at all.\n   */\n  apiKey?: string;\n  /** Per-request timeout, in milliseconds. Defaults to 30000. */\n  timeoutMs?: number;\n  /** Maximum retry attempts for network failures and 5xx/429 responses. Defaults to 3. */\n  maxRetries?: number;\n  /** Override for the `fetch` implementation, mainly for tests. Defaults to global `fetch`. */\n  fetch?: typeof fetch;\n}\n\n/** Optional filters for {@link Client.queryAuditLog}. Filters combine with AND when more than one is set. */\nexport interface AuditLogFilter {\n  /** Restrict to entries for this object id. */\n  objectId?: string;\n  /** Restrict to entries recorded with this caller identity. */\n  caller?: string;\n  /** Restrict to entries at or after this ISO-8601 timestamp. */\n  from?: string;\n  /** Restrict to entries at or before this ISO-8601 timestamp. */\n  to?: string;\n}\n\ninterface RequestOptions {\n  authenticated?: boolean;\n  caller?: string | undefined;\n  query?: Record<string, string | undefined>;\n  body?: RequestInit[\"body\"];\n  jsonBody?: unknown;\n}\n\n/**\n * A typed client for hush-hush, a standalone secrets object store.\n *\n * @example\n * ```ts\n * const client = new Client(\"https://hush-hush.example.com\");\n * const meta = await client.createObject(\"my-object\", sealedBytes);\n * ```\n */\nexport class Client {\n  private readonly baseUrl: string;\n  private readonly apiKey: string | undefined;\n  private readonly timeoutMs: number;\n  private readonly maxRetries: number;\n  private readonly fetchImpl: typeof fetch;\n\n  /**\n   * @param baseUrl - hush-hush's base URL, e.g. `https://hush-hush.example.com`.\n   * @param options - Credential, timeout, and retry configuration.\n   */\n  constructor(baseUrl: string, options: ClientOptions = {}) {\n    this.baseUrl = baseUrl.replace(/\\/+$/, \"\");\n    this.apiKey = options.apiKey ?? process.env[API_KEY_ENV_VAR];\n    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;\n    this.fetchImpl = options.fetch ?? fetch;\n  }\n\n  /** Answers whether the server process is up. Needs no credential. */\n  async health(): Promise<Health> {\n    const response = await this.request(\"GET\", \"/healthz\");\n    return (await response.json()) as Health;\n  }\n\n  /**\n   * Stores an already-sealed value under a new object id. Requires a credential.\n   *\n   * @param id - The new object's id. Must match hush-hush's id pattern (lowercase alphanumeric, `-`/`_`).\n   * @param value - The already-sealed (encrypted) value. This SDK never encrypts or decrypts anything.\n   * @param options.usedBy - Consumers (repos or hosts) recorded as depending on this object.\n   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.\n   * @throws {APIError} If the server responds with anything other than 201 (e.g. 409 if the id exists).\n   */\n  async createObject(\n    id: string,\n    value: Uint8Array,\n    options: { usedBy?: string[]; caller?: string } = {},\n  ): Promise<ObjectMetadata> {\n    const response = await this.request(\"POST\", \"/objects\", {\n      authenticated: true,\n      caller: options.caller,\n      jsonBody: {\n        id,\n        value: base64Encode(value),\n        ...(options.usedBy !== undefined ? { used_by: options.usedBy } : {}),\n      },\n    });\n    return (await response.json()) as ObjectMetadata;\n  }\n\n  /**\n   * Fetches an object's sealed ciphertext exactly as stored — this SDK never\n   * decrypts it, the same as the server. Needs no credential.\n   *\n   * @param id - The object's id.\n   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.\n   * @throws {APIError} If the server responds with anything other than 200 (e.g. 404).\n   */\n  async getObject(id: string, options: { caller?: string } = {}): Promise<Uint8Array> {\n    const response = await this.request(\"GET\", `/objects/${encodeURIComponent(id)}`, {\n      caller: options.caller,\n    });\n    return new Uint8Array(await response.arrayBuffer());\n  }\n\n  /**\n   * Replaces the stored ciphertext for an existing object. The object's id\n   * and used-by metadata are unchanged. Requires a credential.\n   *\n   * @param id - The existing object's id.\n   * @param value - The new already-sealed (encrypted) value.\n   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.\n   * @throws {APIError} If the server responds with anything other than 200 (e.g. 401 or 404).\n   */\n  async updateObject(\n    id: string,\n    value: Uint8Array,\n    options: { caller?: string } = {},\n  ): Promise<ObjectMetadata> {\n    const response = await this.request(\"PUT\", `/objects/${encodeURIComponent(id)}`, {\n      authenticated: true,\n      caller: options.caller,\n      jsonBody: { value: base64Encode(value) },\n    });\n    return (await response.json()) as ObjectMetadata;\n  }\n\n  /**\n   * Permanently removes an object. A subsequent fetch by this id returns 404. Requires a credential.\n   *\n   * @param id - The object's id.\n   * @param options.caller - Recorded in the audit log as the calling program's self-reported identity.\n   * @throws {APIError} If the server responds with anything other than 204 (e.g. 401 or 404).\n   */\n  async deleteObject(id: string, options: { caller?: string } = {}): Promise<void> {\n    await this.request(\"DELETE\", `/objects/${encodeURIComponent(id)}`, {\n      authenticated: true,\n      caller: options.caller,\n    });\n  }\n\n  /**\n   * Returns the recorded list of consumers for an object — the \"what\n   * depends on this\" mapping set at creation. Needs no credential.\n   *\n   * @param id - The object's id.\n   * @throws {APIError} If the server responds with anything other than 200 (e.g. 404).\n   */\n  async getObjectUsedBy(id: string): Promise<UsedBy> {\n    const response = await this.request(\"GET\", `/objects/${encodeURIComponent(id)}/used-by`);\n    return (await response.json()) as UsedBy;\n  }\n\n  /**\n   * Queries the audit log — every create, read, update, and delete call is\n   * recorded here. Needs no credential. Filters combine with AND when more\n   * than one is given.\n   *\n   * hush-hush's `/audit-log` endpoint has no pagination parameters, so this\n   * always resolves with the full matching result set as a single array,\n   * never a page plus a cursor.\n   *\n   * @param filter - Optional `objectId`/`caller`/`from`/`to` filters.\n   */\n  async queryAuditLog(filter: AuditLogFilter = {}): Promise<AuditLogEntry[]> {\n    const response = await this.request(\"GET\", \"/audit-log\", {\n      query: {\n        object_id: filter.objectId,\n        caller: filter.caller,\n        from: filter.from,\n        to: filter.to,\n      },\n    });\n    return (await response.json()) as AuditLogEntry[];\n  }\n\n  private async request(\n    method: string,\n    path: string,\n    options: RequestOptions = {},\n  ): Promise<Response> {\n    const url = new URL(`${this.baseUrl}${path}`);\n    for (const [key, value] of Object.entries(options.query ?? {})) {\n      if (value !== undefined) url.searchParams.set(key, value);\n    }\n\n    const headers = new Headers();\n    if (options.caller !== undefined) headers.set(\"X-Caller\", options.caller);\n    if (options.authenticated === true && this.apiKey !== undefined) {\n      headers.set(\"Authorization\", `Bearer ${this.apiKey}`);\n    }\n\n    let body: RequestInit[\"body\"] = options.body;\n    if (options.jsonBody !== undefined) {\n      headers.set(\"Content-Type\", \"application/json\");\n      body = JSON.stringify(options.jsonBody);\n    }\n\n    const controller = new AbortController();\n    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);\n    try {\n      const response = await fetchWithRetry(\n        this.fetchImpl,\n        url.toString(),\n        { method, headers, signal: controller.signal, ...(body !== undefined ? { body } : {}) },\n        this.maxRetries,\n      );\n      if (!response.ok) {\n        const responseBody = new Uint8Array(await response.arrayBuffer());\n        throw new APIError(\n          response.status,\n          responseBody,\n          response.headers.get(\"x-request-id\") ?? undefined,\n        );\n      }\n      return response;\n    } finally {\n      clearTimeout(timeout);\n    }\n  }\n}\n\nfunction base64Encode(value: Uint8Array): string {\n  return Buffer.from(value).toString(\"base64\");\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hush-hush/sdk",
-  "version": "3.0.0",
+  "version": "4.1.0",
   "description": "Official Node.js/TypeScript SDK for hush-hush, generated from its OpenAPI spec",
   "keywords": [
     "hush-hush",