@productcraft/core 0.3.0 → 0.4.1

package/dist/index.cjs

@@ -6,7 +6,12 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var createClient__default = /*#__PURE__*/_interopDefault(createClient);
 
-// src/index.ts
+// src/legacy.ts
+
+// src/version.ts
+var CORE_VERSION = "0.4.1" ;
+
+// src/legacy.ts
 var PC_BASE_URL = {
   // platformAuth is the platform identity layer (workspaces, PATs);
   // it vacated api.auth so the customer-facing Auth product could
@@ -58,15 +63,841 @@ function makeClient(defaultBaseUrl, config = {}) {
     fetch: config.fetch
   });
   client.use(authMiddleware(resolveAuth(config.auth)));
+  client.use(userAgentMiddleware());
   return client;
 }
+function userAgentMiddleware() {
+  const g = globalThis;
+  const browser = typeof g.window?.document !== "undefined" && typeof g.navigator !== "undefined";
+  const node = g.process?.versions?.node;
+  const userAgent = `productcraft-node/core@${CORE_VERSION}${node ? ` node/${node}` : ""}`;
+  return {
+    onRequest({ request }) {
+      if (browser || request.headers.has("user-agent")) return void 0;
+      request.headers.set("User-Agent", userAgent);
+      return request;
+    }
+  };
+}
+
+// src/errors.ts
+var ERROR_DOCS_URL = "https://productcraft.co/docs/errors";
+var brandKey = (name) => /* @__PURE__ */ Symbol.for(`productcraft.error.${name}`);
+function stamp(instance, ctor) {
+  let current = ctor;
+  while (current && current !== Error && current !== Function.prototype) {
+    if (Object.prototype.hasOwnProperty.call(current, "brandName") && current.brandName) {
+      Object.defineProperty(instance, brandKey(current.brandName), {
+        value: true,
+        enumerable: false
+      });
+    }
+    current = Object.getPrototypeOf(current);
+  }
+}
+var ProductCraftError = class extends Error {
+  static brandName = "ProductCraftError";
+  static [Symbol.hasInstance](instance) {
+    if (typeof instance !== "object" || instance === null) return false;
+    return instance[brandKey(this.brandName)] === true;
+  }
+  constructor(message, options) {
+    super(message, options);
+    const ctor = new.target;
+    Object.defineProperty(this, "name", {
+      value: ctor.brandName,
+      enumerable: false,
+      writable: true,
+      configurable: true
+    });
+    stamp(this, new.target);
+  }
+};
+var ConfigurationError = class extends ProductCraftError {
+  static brandName = "ConfigurationError";
+};
+var WebhookVerificationError = class extends ProductCraftError {
+  static brandName = "WebhookVerificationError";
+};
+var APIConnectionError = class extends ProductCraftError {
+  static brandName = "APIConnectionError";
+  constructor(message = "Connection error.", options) {
+    super(message, options);
+  }
+};
+var APITimeoutError = class extends APIConnectionError {
+  static brandName = "APITimeoutError";
+  constructor(message = "Request timed out.", options) {
+    super(message, options);
+  }
+};
+var APIUserAbortError = class extends ProductCraftError {
+  static brandName = "APIUserAbortError";
+  constructor(message = "Request was aborted.", options) {
+    super(message, options);
+  }
+};
+function envelopeMessage(body, status) {
+  if (body && typeof body === "object") {
+    const msg = body.message;
+    if (typeof msg === "string" && msg !== "") return msg;
+    if (Array.isArray(msg) && msg.length > 0) return msg.map(String).join("; ");
+    const err = body.error;
+    if (typeof err === "string" && err !== "") return err;
+  }
+  if (typeof body === "string" && body.trim() !== "" && body.length <= 500) return body.trim();
+  return `${status} status code`;
+}
+function envelopeErrors(body) {
+  if (!body || typeof body !== "object") return [];
+  const list = body.errors;
+  if (!Array.isArray(list)) return [];
+  return list.filter((e) => !!e && typeof e === "object").map((e) => {
+    const out = {
+      param: typeof e.param === "string" ? e.param : "",
+      message: typeof e.message === "string" ? e.message : ""
+    };
+    if (typeof e.code === "string") out.code = e.code;
+    return out;
+  });
+}
+var APIError = class _APIError extends ProductCraftError {
+  static brandName = "APIError";
+  /** HTTP status of the response. */
+  status;
+  /** Stable, machine-readable code from the error envelope (branch on this, not on `message`). */
+  code;
+  /** Per-field validation errors from the envelope's `errors`; empty when absent. */
+  errors;
+  /** The envelope's route-specific `details` object (e.g. `{ fqdn, reason }`), when present. */
+  details;
+  /** `https://productcraft.co/docs/errors#<code>`, when there is a code. */
+  docUrl;
+  /** `X-Request-Id` response header, else the envelope's `request_id`. Quote it to support. */
+  requestId;
+  /** Response headers. */
+  headers;
+  /** Parsed response body (JSON when it parses, otherwise the text). */
+  body;
+  constructor(status, body, headers, message) {
+    super(message ?? envelopeMessage(body, status));
+    this.status = status;
+    this.headers = headers;
+    this.body = body;
+    const env = body && typeof body === "object" ? body : {};
+    this.code = typeof env.code === "string" && env.code !== "" ? env.code : void 0;
+    this.errors = envelopeErrors(body);
+    this.details = env.details && typeof env.details === "object" && !Array.isArray(env.details) ? env.details : void 0;
+    this.docUrl = this.code ? `${ERROR_DOCS_URL}#${this.code}` : void 0;
+    this.requestId = headers.get("x-request-id") ?? (typeof env.request_id === "string" ? env.request_id : void 0);
+  }
+  /** Build the right subclass for a status and envelope. */
+  static generate(status, body, headers) {
+    const code = body && typeof body === "object" && typeof body.code === "string" ? body.code : void 0;
+    switch (status) {
+      case 400:
+        return new BadRequestError(status, body, headers);
+      case 401:
+        return new AuthenticationError(status, body, headers);
+      case 403:
+        return new PermissionDeniedError(status, body, headers);
+      case 404:
+        return new NotFoundError(status, body, headers);
+      case 409:
+        return code === "IDEMPOTENCY_KEY_REUSE" ? new IdempotencyKeyReuseError(status, body, headers) : new ConflictError(status, body, headers);
+      case 422:
+        return new UnprocessableEntityError(status, body, headers);
+      case 429:
+        return new RateLimitError(status, body, headers);
+    }
+    if (status >= 500) return new InternalServerError(status, body, headers);
+    return new _APIError(status, body, headers);
+  }
+};
+var BadRequestError = class extends APIError {
+  static brandName = "BadRequestError";
+};
+var AuthenticationError = class extends APIError {
+  static brandName = "AuthenticationError";
+};
+var PermissionDeniedError = class extends APIError {
+  static brandName = "PermissionDeniedError";
+};
+var NotFoundError = class extends APIError {
+  static brandName = "NotFoundError";
+};
+var ConflictError = class extends APIError {
+  static brandName = "ConflictError";
+};
+var IdempotencyKeyReuseError = class extends ConflictError {
+  static brandName = "IdempotencyKeyReuseError";
+};
+var UnprocessableEntityError = class extends APIError {
+  static brandName = "UnprocessableEntityError";
+};
+var RateLimitError = class extends APIError {
+  static brandName = "RateLimitError";
+  retryAfter;
+  constructor(status, body, headers, message) {
+    super(status, body, headers, message);
+    const ms = parseRetryAfterMs(headers, Date.now());
+    this.retryAfter = ms === void 0 ? void 0 : ms / 1e3;
+  }
+};
+var InternalServerError = class extends APIError {
+  static brandName = "InternalServerError";
+};
+function parseRetryAfterMs(headers, now) {
+  const ms = headers.get("retry-after-ms");
+  if (ms !== null && ms.trim() !== "") {
+    const n = Number(ms);
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  const value = headers.get("retry-after");
+  if (value === null || value.trim() === "") return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return seconds >= 0 ? seconds * 1e3 : void 0;
+  const date = Date.parse(value);
+  if (Number.isNaN(date)) return void 0;
+  return Math.max(0, date - now);
+}
+
+// src/api-promise.ts
+function num(v) {
+  if (v === null || v.trim() === "") return void 0;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : void 0;
+}
+function parseRateLimit(headers) {
+  const limit = num(headers.get("x-ratelimit-limit"));
+  const remaining = num(headers.get("x-ratelimit-remaining"));
+  const reset = num(headers.get("x-ratelimit-reset"));
+  if (limit === void 0 && remaining === void 0 && reset === void 0) return void 0;
+  return { limit, remaining, reset };
+}
+function attachLastResponse(data, meta) {
+  if (data && typeof data === "object" && Object.isExtensible(data) && !(data instanceof Response)) {
+    Object.defineProperty(data, "lastResponse", {
+      value: meta,
+      enumerable: false,
+      writable: true,
+      configurable: true
+    });
+  }
+  return data;
+}
+var APIPromise = class extends Promise {
+  #raw;
+  #parse;
+  #parsed;
+  constructor(raw, parse) {
+    super((resolve) => resolve(null));
+    this.#raw = raw;
+    this.#parse = parse;
+  }
+  // `.then()` on a subclass must produce plain promises, not new APIPromises.
+  static get [Symbol.species]() {
+    return Promise;
+  }
+  #withParsed() {
+    if (!this.#parsed) {
+      this.#parsed = this.#raw.then(async (raw) => ({
+        data: await this.#parse(raw),
+        response: raw.response,
+        requestId: raw.requestId,
+        rateLimit: parseRateLimit(raw.response.headers)
+      }));
+    }
+    return this.#parsed;
+  }
+  /** The parsed body plus the `Response`, request id and rate-limit headers. */
+  withResponse() {
+    return this.#withParsed();
+  }
+  /** The raw `Response`, body unread. Use instead of awaiting (the body can only be read once). */
+  asResponse() {
+    return this.#raw.then((r) => r.response);
+  }
+  then(onfulfilled, onrejected) {
+    return this.#withParsed().then((r) => r.data).then(onfulfilled, onrejected);
+  }
+  catch(onrejected) {
+    return this.then(void 0, onrejected);
+  }
+  finally(onfinally) {
+    return this.then().finally(onfinally);
+  }
+};
+
+// src/pagination.ts
+var Page = class {
+  data;
+  has_more;
+  next_cursor;
+  #fetchPage;
+  constructor(body, fetchPage) {
+    this.data = Array.isArray(body?.data) ? body.data : [];
+    this.next_cursor = body?.pagination?.next_cursor ?? null;
+    this.has_more = Boolean(body?.pagination?.has_more) && this.next_cursor !== null;
+    this.#fetchPage = fetchPage;
+  }
+  hasNextPage() {
+    return this.has_more;
+  }
+  /** Fetch the following page. Throws when there is none (check `hasNextPage()` first). */
+  getNextPage() {
+    if (!this.has_more || this.next_cursor === null) {
+      throw new ProductCraftError("No next page; check hasNextPage() before calling getNextPage().");
+    }
+    return this.#fetchPage(this.next_cursor);
+  }
+  /** The wire shape, so `JSON.stringify(page)` matches the API response. */
+  toJSON() {
+    return { data: this.data, pagination: { next_cursor: this.next_cursor, has_more: this.has_more } };
+  }
+};
+var PagePromise = class extends APIPromise {
+  constructor(raw, parse) {
+    super(raw, parse);
+  }
+  /** Iterate pages, starting with this one. */
+  async *pages() {
+    let page = await this;
+    for (; ; ) {
+      yield page;
+      if (!page.hasNextPage()) return;
+      page = await page.getNextPage();
+    }
+  }
+  async *[Symbol.asyncIterator]() {
+    for await (const page of this.pages()) {
+      for (const item of page.data) yield item;
+    }
+  }
+  /** Collect items across pages, stopping at `maxItems`. */
+  async toArray(options) {
+    const max = options?.maxItems;
+    if (typeof max !== "number" || !(max >= 0)) {
+      throw new ProductCraftError("toArray() needs { maxItems }, a non-negative number.");
+    }
+    const out = [];
+    if (max === 0) return out;
+    for await (const item of this) {
+      out.push(item);
+      if (out.length >= max) break;
+    }
+    return out;
+  }
+};
+
+// src/webhooks.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function normalizeHeaders(headers) {
+  const out = /* @__PURE__ */ new Map();
+  if (!headers) return out;
+  const put = (k, v) => {
+    if (v === void 0 || v === null) return;
+    const value = Array.isArray(v) ? v.map(String).join(" ") : String(v);
+    out.set(k.toLowerCase(), value);
+  };
+  if (typeof headers.forEach === "function" && typeof headers.get === "function") {
+    headers.forEach((v, k) => put(k, v));
+    return out;
+  }
+  if (typeof headers[Symbol.iterator] === "function") {
+    for (const [k, v] of headers) put(k, v);
+    return out;
+  }
+  for (const [k, v] of Object.entries(headers)) put(k, v);
+  return out;
+}
+function payloadBytes(payload) {
+  if (typeof payload === "string") return encoder.encode(payload);
+  if (payload instanceof Uint8Array) return payload;
+  if (payload instanceof ArrayBuffer) return new Uint8Array(payload);
+  throw new WebhookVerificationError(
+    "Webhook payload must be the raw request body (string, Buffer, Uint8Array or ArrayBuffer), not a parsed object. Read the body before any JSON parser runs (express.raw(), `await req.text()`)."
+  );
+}
+function base64ToBytes(b64) {
+  try {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  } catch {
+    return void 0;
+  }
+}
+function hexToBytes(hex) {
+  if (hex.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(hex)) return void 0;
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+function concat(...parts) {
+  const len = parts.reduce((n, p) => n + p.length, 0);
+  const out = new Uint8Array(len);
+  let off = 0;
+  for (const p of parts) {
+    out.set(p, off);
+    off += p.length;
+  }
+  return out;
+}
+async function hmacSha256(key, data) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new WebhookVerificationError("crypto.subtle is unavailable in this runtime (Node 20.3+ required).");
+  }
+  const k = await subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return new Uint8Array(await subtle.sign("HMAC", k, data));
+}
+function standardKey(secret) {
+  if (secret.startsWith("whsec_")) {
+    const bytes = base64ToBytes(secret.slice("whsec_".length));
+    if (!bytes) throw new WebhookVerificationError("Webhook secret is not valid base64 after the whsec_ prefix.");
+    return bytes;
+  }
+  return encoder.encode(secret);
+}
+function checkTimestamp(ts, toleranceSeconds, now) {
+  const nowSeconds = Math.floor(now / 1e3);
+  if (nowSeconds - ts > toleranceSeconds) throw new WebhookVerificationError("Webhook timestamp is too old.");
+  if (ts - nowSeconds > toleranceSeconds) throw new WebhookVerificationError("Webhook timestamp is too far in the future.");
+}
+function parseTimestamp(raw) {
+  if (!/^\d+$/.test(raw.trim())) throw new WebhookVerificationError("Webhook timestamp header is not a unix timestamp.");
+  return Number(raw.trim());
+}
+function findLegacyHeader(h) {
+  for (const [k, v] of h) if (/^x-[a-z0-9-]+-signature$/.test(k)) return v;
+  return void 0;
+}
+async function verifyWebhook(params) {
+  const { headers, toleranceSeconds = 300 } = params;
+  const now = params.now ?? Date.now();
+  const secrets = (typeof params.secret === "string" ? [params.secret] : [...params.secret ?? []]).filter(
+    (s) => typeof s === "string" && s !== ""
+  );
+  if (secrets.length === 0) throw new WebhookVerificationError("No webhook secret was given.");
+  const body = payloadBytes(params.payload);
+  const h = normalizeHeaders(headers);
+  const id = h.get("webhook-id");
+  const timestamp = h.get("webhook-timestamp");
+  const signature = h.get("webhook-signature");
+  let verified = false;
+  if (id !== void 0 || timestamp !== void 0 || signature !== void 0) {
+    if (!id || !timestamp || !signature) {
+      throw new WebhookVerificationError("Missing webhook-id, webhook-timestamp or webhook-signature header.");
+    }
+    const ts = parseTimestamp(timestamp);
+    checkTimestamp(ts, toleranceSeconds, now);
+    const candidates = signature.split(" ").map((entry) => entry.split(",", 2)).filter(([version, sig]) => version === "v1" && !!sig).map(([, sig]) => base64ToBytes(sig)).filter((b) => !!b);
+    const signed = concat(encoder.encode(`${id}.${ts}.`), body);
+    for (const secret of secrets) {
+      const expected = await hmacSha256(standardKey(secret), signed);
+      for (const c of candidates) if (timingSafeEqual(expected, c)) verified = true;
+    }
+  } else {
+    const legacy = findLegacyHeader(h);
+    if (!legacy) throw new WebhookVerificationError("No webhook signature header found.");
+    let t;
+    const sigs = [];
+    for (const part of legacy.split(",").map((p) => p.trim())) {
+      if (part.startsWith("t=")) t = part.slice(2);
+      else if (part.startsWith("v1=")) {
+        const b = hexToBytes(part.slice(3));
+        if (b) sigs.push(b);
+      }
+    }
+    if (t === void 0 || sigs.length === 0) throw new WebhookVerificationError("Malformed signature header.");
+    const ts = parseTimestamp(t);
+    checkTimestamp(ts, toleranceSeconds, now);
+    const signed = concat(encoder.encode(`${ts}.`), body);
+    for (const secret of secrets) {
+      const expected = await hmacSha256(encoder.encode(secret), signed);
+      for (const c of sigs) if (timingSafeEqual(expected, c)) verified = true;
+    }
+  }
+  if (!verified) throw new WebhookVerificationError("Webhook signature does not match.");
+  const text = decoder.decode(body);
+  try {
+    return JSON.parse(text);
+  } catch (cause) {
+    throw new WebhookVerificationError("Webhook payload is not valid JSON.", { cause });
+  }
+}
+
+// src/client.ts
+var DEFAULT_TIMEOUT_MS = 6e4;
+var DEFAULT_MAX_RETRIES = 2;
+var MAX_RETRY_AFTER_MS = 6e4;
+var PC_WORKSPACE_ID_ENV = "PRODUCTCRAFT_WORKSPACE_ID";
+var PC_LOG_ENV = "PRODUCTCRAFT_LOG";
+var WORKSPACE_LOOKUP_TIMEOUT_MS = 5e3;
+var RETRY_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var SAFE_METHODS = /* @__PURE__ */ new Set(["GET", "PUT", "DELETE"]);
+function backoffMs(attempt) {
+  return Math.random() * Math.min(8e3, 500 * 2 ** attempt);
+}
+function isBrowser() {
+  const g = globalThis;
+  return typeof g.window !== "undefined" && typeof g.window?.document !== "undefined" && typeof g.navigator !== "undefined";
+}
+function runtimeTag() {
+  const g = globalThis;
+  if (g.Bun?.version) return `bun/${g.Bun.version}`;
+  if (g.Deno?.version?.deno) return `deno/${g.Deno.version.deno}`;
+  if (g.process?.versions?.node) return `node/${g.process.versions.node}`;
+  return "runtime/unknown";
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new APIUserAbortError());
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new APIUserAbortError());
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function isBodyInit(body) {
+  return typeof body === "string" || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || typeof Blob !== "undefined" && body instanceof Blob || typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams || typeof ReadableStream !== "undefined" && body instanceof ReadableStream;
+}
+async function readErrorBody(res) {
+  const text = await res.text().catch(() => "");
+  if (text === "") return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+var customFetch = /* @__PURE__ */ new WeakMap();
+function createOpenAPIClient(api) {
+  const client = createClient__default.default({ baseUrl: api.baseUrl, fetch: customFetch.get(api) });
+  client.use(authMiddleware(api.auth));
+  return client;
+}
+var workspaceCache = /* @__PURE__ */ new Map();
+function _resetWorkspaceCache() {
+  workspaceCache.clear();
+}
+var APIClient = class {
+  baseUrl;
+  workspaceId;
+  timeout;
+  maxRetries;
+  webhookSecret;
+  #fetch;
+  #defaultHeaders;
+  #platformAuthBaseUrl;
+  #logLevel;
+  #logger;
+  #userAgent;
+  constructor(options = {}, defaultBaseUrl, sdk) {
+    this.baseUrl = (options.baseUrl ?? defaultBaseUrl).replace(/\/+$/, "");
+    Object.defineProperty(this, "auth", {
+      value: resolveAuth(options.auth ?? (options.apiKey ? { type: "apiKey", key: options.apiKey } : void 0)),
+      enumerable: false,
+      writable: false
+    });
+    if (this.auth?.type === "apiKey" && isBrowser() && !options.dangerouslyAllowBrowser) {
+      throw new ConfigurationError(
+        "A workspace API key was used in a browser, where anyone who loads the page can read it. Call ProductCraft from your server, or pass dangerouslyAllowBrowser: true if you accept that risk."
+      );
+    }
+    this.workspaceId = options.workspaceId ?? readEnv(PC_WORKSPACE_ID_ENV);
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.webhookSecret = options.webhookSecret;
+    this.#fetch = options.fetch;
+    customFetch.set(this, options.fetch);
+    this.#defaultHeaders = { ...options.defaultHeaders };
+    this.#platformAuthBaseUrl = (options.platformAuthBaseUrl ?? PC_BASE_URL.platformAuth).replace(/\/+$/, "");
+    const level = options.logLevel ?? readEnv(PC_LOG_ENV);
+    this.#logLevel = level === "debug" || level === "warn" ? level : "off";
+    this.#logger = options.logger ?? console;
+    const product = sdk ? `${sdk.name}@${sdk.version}` : `core@${CORE_VERSION}`;
+    this.#userAgent = `productcraft-node/${product} ${runtimeTag()}`;
+  }
+  #log(level, message, fields) {
+    if (this.#logLevel === "off") return;
+    if (level === "debug" && this.#logLevel !== "debug") return;
+    try {
+      this.#logger[level](`[productcraft] ${message}`, fields);
+    } catch {
+    }
+  }
+  /** Send one logical API call (with retries). Resolves to the parsed body. */
+  request(spec, options = {}) {
+    return new APIPromise(this.#send(spec, options), (raw) => this.#parseBody(spec, raw));
+  }
+  /** A paginated list call. `await` for one page, `for await` for every item. */
+  list(spec, options = {}) {
+    const at = (cursor) => {
+      const pageSpec = cursor === void 0 ? spec : { ...spec, query: { ...spec.query, cursor } };
+      return new PagePromise(this.#send(pageSpec, options), async (raw) => {
+        const body = await this.#parseBody(pageSpec, raw);
+        const page = new Page(body, (next) => at(next));
+        return attachLastResponse(page, this.#meta(raw));
+      });
+    };
+    return at();
+  }
+  /** Retrieve repeatedly until `config.field` reaches a terminal value. */
+  async poll(spec, config, options = {}) {
+    const { intervalMs = 2e3, timeoutMs = 3e5, ...requestOptions } = options;
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const { data, response } = await this.request(spec, requestOptions).withResponse();
+      const value = data?.[config.field];
+      if (typeof value === "string" && config.terminal.includes(value)) return data;
+      const retryAfter = parseRetryAfterMs(response.headers, Date.now());
+      const wait = retryAfter !== void 0 && retryAfter <= MAX_RETRY_AFTER_MS ? retryAfter : intervalMs;
+      if (Date.now() + wait > deadline) {
+        throw new APITimeoutError(
+          `Polling ${spec.path} timed out after ${timeoutMs} ms; last ${config.field} was ${JSON.stringify(value)}.`
+        );
+      }
+      this.#log("debug", "poll", { path: spec.path, [config.field]: value, wait_ms: wait });
+      await sleep(wait, options.signal);
+    }
+  }
+  /** Create, then poll the created object to a terminal state. */
+  async createAndPoll(createSpec, retrieveSpec, config, options = {}) {
+    const { intervalMs, timeoutMs, ...requestOptions } = options;
+    const created = await this.request(createSpec, requestOptions);
+    const value = created?.[config.field];
+    if (typeof value === "string" && config.terminal.includes(value)) return created;
+    const pollOptions = { ...requestOptions, intervalMs, timeoutMs };
+    delete pollOptions.idempotencyKey;
+    return this.poll(retrieveSpec(created), config, pollOptions);
+  }
+  /** Verify a webhook with the given secret, the client's `webhookSecret`, or `envVar`. */
+  async unwrapWebhook(params, envVar) {
+    const secret = params.secret ?? this.webhookSecret ?? (envVar ? readEnv(envVar) : void 0);
+    if (!secret || Array.isArray(secret) && secret.length === 0) {
+      throw new ConfigurationError(
+        `No webhook secret: pass { secret }, set webhookSecret on the client${envVar ? ` or ${envVar}` : ""}.`
+      );
+    }
+    return verifyWebhook({ ...params, secret });
+  }
+  #meta(raw) {
+    return { requestId: raw.requestId, status: raw.response.status, headers: raw.response.headers };
+  }
+  async #parseBody(spec, raw) {
+    const res = raw.response;
+    if (spec.raw) return res;
+    if (res.status === 204 || res.status === 205) return void 0;
+    const type = res.headers.get("content-type") ?? "";
+    if (!/[/+]json\b/i.test(type)) {
+      if (res.headers.get("content-length") === "0") return void 0;
+      return res;
+    }
+    const text = await res.text();
+    if (text === "") return void 0;
+    const data = JSON.parse(text);
+    return attachLastResponse(data, this.#meta(raw));
+  }
+  async #resolveWorkspaceId(options, fetchImpl) {
+    if (options.workspaceId) return options.workspaceId;
+    if (this.workspaceId) return this.workspaceId;
+    if (this.auth?.type !== "apiKey") {
+      throw new ConfigurationError(
+        "pass workspaceId: this call is workspace-scoped and the credential is not a workspace API key (bearer and cookie credentials can span workspaces, so the SDK never guesses)."
+      );
+    }
+    const key = this.auth.key;
+    const cacheKey = `${this.#platformAuthBaseUrl}\0${key}`;
+    let pending = workspaceCache.get(cacheKey);
+    if (!pending) {
+      pending = this.#lookupWorkspace(key, fetchImpl);
+      workspaceCache.set(cacheKey, pending);
+      pending.catch(() => workspaceCache.delete(cacheKey));
+    }
+    return pending;
+  }
+  async #lookupWorkspace(key, fetchImpl) {
+    this.#log("debug", "resolving workspaceId", { path: "/v1/api-keys/self" });
+    let res;
+    try {
+      res = await fetchImpl(`${this.#platformAuthBaseUrl}/v1/api-keys/self`, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${key}`, Accept: "application/json", "User-Agent": this.#userAgent },
+        signal: AbortSignal.timeout(WORKSPACE_LOOKUP_TIMEOUT_MS)
+      });
+    } catch (cause) {
+      throw new ConfigurationError("pass workspaceId: looking it up from the API key failed.", { cause });
+    }
+    if (!res.ok) {
+      const body2 = await readErrorBody(res);
+      throw new ConfigurationError(
+        `pass workspaceId: looking it up from the API key failed with ${res.status}.`,
+        { cause: APIError.generate(res.status, body2, res.headers) }
+      );
+    }
+    const body = await res.json().catch(() => void 0);
+    const id = body?.workspace?.id;
+    if (typeof id !== "string" || id === "") {
+      throw new ConfigurationError("pass workspaceId: the API key lookup returned no workspace id.");
+    }
+    return id;
+  }
+  async #buildUrl(spec, options, fetchImpl) {
+    const params = { ...spec.pathParams };
+    if (spec.path.includes("{workspace_id}") && params.workspace_id === void 0) {
+      params.workspace_id = await this.#resolveWorkspaceId(options, fetchImpl);
+    }
+    const path = spec.path.replace(/\{([^}]+)\}/g, (_, name) => {
+      const value = params[name];
+      if (value === void 0 || value === null || value === "") {
+        throw new ProductCraftError(`Missing path parameter "${name}" for ${spec.method} ${spec.path}.`);
+      }
+      return encodeURIComponent(String(value));
+    });
+    const search = new URLSearchParams();
+    for (const [k, v] of Object.entries(spec.query ?? {})) {
+      if (v === void 0 || v === null) continue;
+      for (const item of Array.isArray(v) ? v : [v]) {
+        if (item === void 0 || item === null) continue;
+        search.append(k, item instanceof Date ? item.toISOString() : typeof item === "object" ? JSON.stringify(item) : String(item));
+      }
+    }
+    const qs = search.toString();
+    return `${this.baseUrl}${path}${qs ? `?${qs}` : ""}`;
+  }
+  async #send(spec, options) {
+    const fetchImpl = options.fetch ?? this.#fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+      throw new ConfigurationError("No fetch implementation: pass { fetch } or use Node 20.3+.");
+    }
+    if (options.signal?.aborted) throw new APIUserAbortError();
+    const url = await this.#buildUrl(spec, options, fetchImpl);
+    const headers = new Headers();
+    headers.set("Accept", "application/json");
+    if (!isBrowser()) headers.set("User-Agent", this.#userAgent);
+    for (const source of [this.#defaultHeaders, spec.headers, options.headers]) {
+      for (const [k, v] of Object.entries(source ?? {})) {
+        if (v === void 0) headers.delete(k);
+        else headers.set(k, v);
+      }
+    }
+    if (!spec.public && this.auth) {
+      if (this.auth.type === "cookie") headers.set("Cookie", `auth_token=${this.auth.value}`);
+      else headers.set("Authorization", `Bearer ${this.auth.type === "apiKey" ? this.auth.key : this.auth.token}`);
+    }
+    if (options.idempotencyKey) headers.set("Idempotency-Key", options.idempotencyKey);
+    else if (spec.idempotent && !headers.has("Idempotency-Key")) headers.set("Idempotency-Key", `pc_${crypto.randomUUID()}`);
+    let body;
+    if (spec.body !== void 0) {
+      if (isBodyInit(spec.body)) body = spec.body;
+      else {
+        body = JSON.stringify(spec.body);
+        if (!headers.has("Content-Type")) headers.set("Content-Type", "application/json");
+      }
+    }
+    const retryable = SAFE_METHODS.has(spec.method) || headers.has("Idempotency-Key");
+    const maxRetries = Math.max(0, options.maxRetries ?? this.maxRetries);
+    const timeout = options.timeout ?? this.timeout;
+    for (let attempt = 0; ; attempt++) {
+      if (attempt > 0) headers.set("X-PC-SDK-Retry-Count", String(attempt));
+      const timeoutCtl = new AbortController();
+      const timer = setTimeout(() => timeoutCtl.abort(), timeout);
+      const signal = options.signal ? AbortSignal.any([options.signal, timeoutCtl.signal]) : timeoutCtl.signal;
+      const canRetry = retryable && attempt < maxRetries;
+      this.#log("debug", "request", { method: spec.method, path: spec.path, attempt });
+      let res;
+      try {
+        res = await fetchImpl(url, { method: spec.method, headers, body, signal });
+      } catch (cause) {
+        clearTimeout(timer);
+        if (options.signal?.aborted) throw new APIUserAbortError(void 0, { cause });
+        const error2 = timeoutCtl.signal.aborted ? new APITimeoutError(`Request timed out after ${timeout} ms.`, { cause }) : new APIConnectionError(`Connection error: ${cause?.message ?? String(cause)}`, { cause });
+        if (!canRetry) throw error2;
+        const wait2 = backoffMs(attempt);
+        this.#log("debug", "retrying after connection error", { method: spec.method, path: spec.path, attempt, wait_ms: Math.round(wait2) });
+        await sleep(wait2, options.signal);
+        continue;
+      }
+      clearTimeout(timer);
+      const requestId = res.headers.get("x-request-id") ?? void 0;
+      if (res.ok) {
+        this.#log("debug", "response", { method: spec.method, path: spec.path, status: res.status, request_id: requestId, attempt });
+        return { response: res, requestId };
+      }
+      const errorBody = await readErrorBody(res);
+      const error = APIError.generate(res.status, errorBody, res.headers);
+      this.#log("debug", "response", { method: spec.method, path: spec.path, status: res.status, request_id: error.requestId, attempt });
+      const statusRetryable = RETRY_STATUSES.has(res.status) || res.status === 409 && error.code === "IDEMPOTENCY_IN_PROGRESS";
+      if (!canRetry || !statusRetryable) throw error;
+      const retryAfter = parseRetryAfterMs(res.headers, Date.now());
+      if (retryAfter !== void 0 && retryAfter > MAX_RETRY_AFTER_MS) {
+        this.#log("warn", "Retry-After above 60 s, not retrying", { path: spec.path, status: res.status, request_id: error.requestId });
+        throw error;
+      }
+      const wait = retryAfter ?? backoffMs(attempt);
+      this.#log("debug", "retrying", { method: spec.method, path: spec.path, status: res.status, attempt, wait_ms: Math.round(wait) });
+      await sleep(wait, options.signal);
+    }
+  }
+};
 
+exports.APIClient = APIClient;
+exports.APIConnectionError = APIConnectionError;
+exports.APIError = APIError;
+exports.APIPromise = APIPromise;
+exports.APITimeoutError = APITimeoutError;
+exports.APIUserAbortError = APIUserAbortError;
+exports.AuthenticationError = AuthenticationError;
+exports.BadRequestError = BadRequestError;
+exports.CORE_VERSION = CORE_VERSION;
+exports.ConfigurationError = ConfigurationError;
+exports.ConflictError = ConflictError;
+exports.DEFAULT_MAX_RETRIES = DEFAULT_MAX_RETRIES;
+exports.DEFAULT_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
+exports.ERROR_DOCS_URL = ERROR_DOCS_URL;
+exports.IdempotencyKeyReuseError = IdempotencyKeyReuseError;
+exports.InternalServerError = InternalServerError;
+exports.MAX_RETRY_AFTER_MS = MAX_RETRY_AFTER_MS;
+exports.NotFoundError = NotFoundError;
 exports.PC_API_KEY_ENV = PC_API_KEY_ENV;
 exports.PC_AUTH_APP_ENV = PC_AUTH_APP_ENV;
 exports.PC_BASE_URL = PC_BASE_URL;
+exports.PC_LOG_ENV = PC_LOG_ENV;
+exports.PC_WORKSPACE_ID_ENV = PC_WORKSPACE_ID_ENV;
+exports.Page = Page;
+exports.PagePromise = PagePromise;
+exports.PermissionDeniedError = PermissionDeniedError;
+exports.ProductCraftError = ProductCraftError;
+exports.RateLimitError = RateLimitError;
+exports.UnprocessableEntityError = UnprocessableEntityError;
+exports.WebhookVerificationError = WebhookVerificationError;
+exports._resetWorkspaceCache = _resetWorkspaceCache;
+exports.attachLastResponse = attachLastResponse;
 exports.authMiddleware = authMiddleware;
+exports.backoffMs = backoffMs;
+exports.createOpenAPIClient = createOpenAPIClient;
 exports.makeClient = makeClient;
+exports.normalizeHeaders = normalizeHeaders;
+exports.parseRateLimit = parseRateLimit;
+exports.parseRetryAfterMs = parseRetryAfterMs;
 exports.readEnv = readEnv;
 exports.resolveAuth = resolveAuth;
+exports.timingSafeEqual = timingSafeEqual;
+exports.verifyWebhook = verifyWebhook;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map