@productcraft/core 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -1,18 +1,10 @@
 import { Middleware, Client } from 'openapi-fetch';
 
 /**
- * Shared transport + auth plumbing used by every surface client.
- *
- * Each surface package (`@productcraft/auth`, `@productcraft/mail`,
- * ...) defines a thin class around `openapi-fetch` plus the generated
- * `paths` types from its own `_generated.d.ts`. The class delegates
- * wire I/O to `openapi-fetch`, but exposes a Stripe-style ergonomic
- * surface where callers reach for `pc.mail.messages.send(...)` rather
- * than the underlying `client.POST("/v1/...")` shape.
- *
- * v0 ships only the underlying `client` (named `client` on each
- * surface) — every endpoint is reachable through it. Ergonomic
- * resource surfaces land in v0.1+ as we hand-roll them.
+ * The 0.x primitives: credential types, environment helpers, base URLs
+ * and the `openapi-fetch` client builder behind every product's
+ * `.client` escape hatch. Kept exported for compatibility; new code
+ * goes through `APIClient` (see `client.ts`).
  */
 
 /**
@@ -94,7 +86,399 @@ declare function authMiddleware(auth: PCAuth | undefined): Middleware;
  *
  * When `config.auth` is omitted the client falls back to
  * `PRODUCTCRAFT_API_KEY` (see `resolveAuth`).
+ *
+ * @deprecated Build the runtime with `new APIClient(options, baseUrl)`
+ * and take the typed escape hatch from `createOpenAPIClient<paths>(apiClient)`,
+ * which shares its credential and base URL. Kept for the 0.x product
+ * packages; removed no earlier than core 2.0.
  */
 declare function makeClient<TPaths extends object>(defaultBaseUrl: string, config?: PCClientConfig): Client<TPaths>;
 
-export { type PCAuth, type PCClientConfig, PC_API_KEY_ENV, PC_AUTH_APP_ENV, PC_BASE_URL, authMiddleware, makeClient, readEnv, resolveAuth };
+/**
+ * The error hierarchy every ProductCraft SDK throws.
+ *
+ * Every class is branded with `Symbol.for("productcraft.error.<Name>")`
+ * and answers `instanceof` through `static [Symbol.hasInstance]`, so a
+ * check like `err instanceof NotFoundError` holds even when the error
+ * was thrown by the CJS build and the check runs against the ESM build,
+ * or when two copies of `@productcraft/core` are installed.
+ */
+/** Base URL of the public error-code catalogue. */
+declare const ERROR_DOCS_URL = "https://productcraft.co/docs/errors";
+/** A string-literal union that also accepts values this SDK version does not know. */
+type OpenEnum<T extends string> = T | (string & {});
+/** One invalid request field, from the error envelope's `errors` list. */
+interface ErrorParam {
+    /** The request field, e.g. `to` or `domains[0].name`. */
+    param: string;
+    message: string;
+    code?: string;
+}
+/** Base class of every error the SDK throws. */
+declare class ProductCraftError extends Error {
+    static readonly brandName: string;
+    static [Symbol.hasInstance](instance: unknown): boolean;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The client was configured in a way that cannot work (missing `workspaceId`, a key in a browser, ...). */
+declare class ConfigurationError extends ProductCraftError {
+    static readonly brandName: string;
+}
+/** A webhook payload failed signature or timestamp verification. */
+declare class WebhookVerificationError extends ProductCraftError {
+    static readonly brandName: string;
+}
+/** The request never produced an HTTP response (DNS, TLS, reset connection, ...). */
+declare class APIConnectionError extends ProductCraftError {
+    static readonly brandName: string;
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/** An attempt (or a poll) ran past its timeout. */
+declare class APITimeoutError extends APIConnectionError {
+    static readonly brandName: string;
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The caller's `AbortSignal` fired. Never retried. */
+declare class APIUserAbortError extends ProductCraftError {
+    static readonly brandName: string;
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A non-2xx HTTP response. Subclassed by status. */
+declare class APIError extends ProductCraftError {
+    static readonly brandName: string;
+    /** HTTP status of the response. */
+    readonly status: number;
+    /** Stable, machine-readable code from the error envelope (branch on this, not on `message`). */
+    readonly code: string | undefined;
+    /** Per-field validation errors from the envelope's `errors`; empty when absent. */
+    readonly errors: ErrorParam[];
+    /** The envelope's route-specific `details` object (e.g. `{ fqdn, reason }`), when present. */
+    readonly details: Record<string, unknown> | undefined;
+    /** `https://productcraft.co/docs/errors#<code>`, when there is a code. */
+    readonly docUrl: string | undefined;
+    /** `X-Request-Id` response header, else the envelope's `request_id`. Quote it to support. */
+    readonly requestId: string | undefined;
+    /** Response headers. */
+    readonly headers: Headers;
+    /** Parsed response body (JSON when it parses, otherwise the text). */
+    readonly body: unknown;
+    constructor(status: number, body: unknown, headers: Headers, message?: string);
+    /** Build the right subclass for a status and envelope. */
+    static generate(status: number, body: unknown, headers: Headers): APIError;
+}
+declare class BadRequestError extends APIError {
+    static readonly brandName: string;
+}
+declare class AuthenticationError extends APIError {
+    static readonly brandName: string;
+}
+declare class PermissionDeniedError extends APIError {
+    static readonly brandName: string;
+}
+declare class NotFoundError extends APIError {
+    static readonly brandName: string;
+}
+declare class ConflictError extends APIError {
+    static readonly brandName: string;
+}
+/** 409 `IDEMPOTENCY_KEY_REUSE`: the same Idempotency-Key was sent with a different body. */
+declare class IdempotencyKeyReuseError extends ConflictError {
+    static readonly brandName: string;
+}
+declare class UnprocessableEntityError extends APIError {
+    static readonly brandName: string;
+}
+/** 429. `retryAfter` is the server's `Retry-After`, in seconds, when sent. */
+declare class RateLimitError extends APIError {
+    static readonly brandName: string;
+    readonly retryAfter: number | undefined;
+    constructor(status: number, body: unknown, headers: Headers, message?: string);
+}
+/** Any 5xx. */
+declare class InternalServerError extends APIError {
+    static readonly brandName: string;
+}
+/**
+ * Milliseconds the server asked us to wait: `retry-after-ms`, else
+ * `Retry-After` as seconds or an HTTP date. `undefined` when absent or
+ * unparseable; negative dates clamp to 0.
+ */
+declare function parseRetryAfterMs(headers: Headers, now: number): number | undefined;
+
+/**
+ * `APIPromise`: what every SDK method returns. Await it for the parsed
+ * body, or call `.withResponse()` / `.asResponse()` for the HTTP layer.
+ */
+/** Metadata attached (non-enumerable) to every object an SDK method returns. */
+interface LastResponse {
+    requestId: string | undefined;
+    status: number;
+    headers: Headers;
+}
+/** Parsed `X-RateLimit-*` headers. Fields are `undefined` when the header is absent. */
+interface RateLimitInfo {
+    limit: number | undefined;
+    remaining: number | undefined;
+    /** As sent by the server (seconds until reset, or a unix timestamp, per API). */
+    reset: number | undefined;
+}
+interface WithResponse<T> {
+    data: T;
+    response: Response;
+    requestId: string | undefined;
+    rateLimit: RateLimitInfo | undefined;
+}
+/** What the transport hands to an `APIPromise`: a successful response plus how to parse it. */
+interface RawResult {
+    response: Response;
+    requestId: string | undefined;
+}
+declare function parseRateLimit(headers: Headers): RateLimitInfo | undefined;
+/** Attach `lastResponse` to an object without it showing up in `JSON.stringify`, spreads or `Object.keys`. */
+declare function attachLastResponse<T>(data: T, meta: LastResponse): T;
+declare class APIPromise<T> extends Promise<T> {
+    #private;
+    constructor(raw: Promise<RawResult>, parse: (raw: RawResult) => Promise<T>);
+    static get [Symbol.species](): PromiseConstructor;
+    /** The parsed body plus the `Response`, request id and rate-limit headers. */
+    withResponse(): Promise<WithResponse<T>>;
+    /** The raw `Response`, body unread. Use instead of awaiting (the body can only be read once). */
+    asResponse(): Promise<Response>;
+    then<R1 = T, R2 = never>(onfulfilled?: ((value: T) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+    catch<R = never>(onrejected?: ((reason: unknown) => R | PromiseLike<R>) | null): Promise<T | R>;
+    finally(onfinally?: (() => void) | null): Promise<T>;
+}
+
+/**
+ * Cursor pagination over the uniform `{ data, pagination: { next_cursor, has_more } }` shape.
+ */
+
+/** The wire shape of every paginated list response. */
+interface PageResponse<Item> {
+    data: Item[];
+    pagination?: {
+        next_cursor?: string | null;
+        has_more?: boolean;
+    };
+}
+/** One page of a list. `await`ing a list call gives you this. */
+declare class Page<Item> {
+    #private;
+    readonly data: Item[];
+    readonly has_more: boolean;
+    readonly next_cursor: string | null;
+    readonly lastResponse: LastResponse;
+    constructor(body: PageResponse<Item>, fetchPage: (cursor: string) => PagePromise<Item>);
+    hasNextPage(): boolean;
+    /** Fetch the following page. Throws when there is none (check `hasNextPage()` first). */
+    getNextPage(): PagePromise<Item>;
+    /** The wire shape, so `JSON.stringify(page)` matches the API response. */
+    toJSON(): PageResponse<Item>;
+}
+interface ToArrayOptions {
+    /** Required cap on how many items to collect across pages. `limit` stays the page size. */
+    maxItems: number;
+}
+/**
+ * Returned by paginated list methods. `await` it for the first `Page`;
+ * `for await` over it for every item across pages; `.pages()` for pages.
+ */
+declare class PagePromise<Item> extends APIPromise<Page<Item>> implements AsyncIterable<Item> {
+    constructor(raw: Promise<RawResult>, parse: (raw: RawResult) => Promise<Page<Item>>);
+    /** Iterate pages, starting with this one. */
+    pages(): AsyncGenerator<Page<Item>, void, undefined>;
+    [Symbol.asyncIterator](): AsyncGenerator<Item, void, undefined>;
+    /** Collect items across pages, stopping at `maxItems`. */
+    toArray(options: ToArrayOptions): Promise<Item[]>;
+}
+
+/**
+ * Webhook signature verification, shared by every product.
+ *
+ * Two schemes are accepted:
+ *
+ * - **Standard Webhooks** (`webhook-id`, `webhook-timestamp`,
+ *   `webhook-signature: v1,<base64> [v1,<base64> ...]`), HMAC-SHA256 over
+ *   `<id>.<timestamp>.<body>`. A `whsec_` secret is base64 key bytes; any
+ *   other secret is used as its UTF-8 bytes (Mail secrets minted before
+ *   Standard Webhooks support).
+ * - **Legacy** `X-<Product>-Signature: t=<unix>,v1=<hex>`, HMAC-SHA256
+ *   over `<t>.<body>` with the secret's UTF-8 bytes (Auth audit sink,
+ *   Trawl, Social, Mail's first scheme).
+ *
+ * Uses `crypto.subtle` only (Node 20.3+, Bun, Deno, edge) and compares in
+ * constant time.
+ */
+/** Node `IncomingHttpHeaders`, a Fetch `Headers`, or any plain header record. */
+type WebhookHeaders = Headers | Record<string, string | string[] | undefined> | Iterable<[string, string]>;
+/** The raw request body, exactly as received. Never a parsed object. */
+type WebhookPayload = string | Uint8Array | ArrayBuffer;
+interface VerifyWebhookParams {
+    payload: WebhookPayload;
+    headers: WebhookHeaders;
+    /** One secret, or several (Mail: default, per-domain and endpoint secrets; rotation). */
+    secret: string | readonly string[];
+    /** Maximum age (and clock skew) of the timestamp, in seconds. Default 300. */
+    toleranceSeconds?: number;
+    /** Override "now" (ms since epoch), for tests. */
+    now?: number;
+}
+/** Lower-case header lookup over every supported header shape. */
+declare function normalizeHeaders(headers: WebhookHeaders): Map<string, string>;
+/** Constant-time comparison of two byte strings (length is not secret). */
+declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Verify a webhook's signature and timestamp, then return the parsed
+ * JSON payload. Throws `WebhookVerificationError` on any failure.
+ *
+ * @example
+ * const event = await verifyWebhook({ payload: rawBody, headers: req.headers, secret: process.env.WEBHOOK_SECRET! });
+ */
+declare function verifyWebhook<T = unknown>(params: VerifyWebhookParams): Promise<T>;
+
+/**
+ * `APIClient`: the hand-written runtime every generated resource method
+ * calls. Nothing per-endpoint lives here (docs/sdk-standard.md section 4).
+ */
+
+type HTTPMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+type LogLevel = "off" | "warn" | "debug";
+/** Anything with pino- or console-shaped methods. */
+interface Logger {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+interface ClientOptions {
+    /** Workspace API key (`pcft_live_…`). Falls back to `PRODUCTCRAFT_API_KEY`. Shorthand for `auth: { type: "apiKey", key }`. */
+    apiKey?: string;
+    /** Explicit credential (API key, bearer token or cookie). Wins over `apiKey`. */
+    auth?: PCAuth;
+    /** Override the product's base URL. */
+    baseUrl?: string;
+    /**
+     * Default `{workspace_id}`. Falls back to `PRODUCTCRAFT_WORKSPACE_ID`, then (workspace API keys only)
+     * one cached `GET /v1/api-keys/self` lookup per process.
+     */
+    workspaceId?: string;
+    /** Per-attempt timeout in ms. Default 60 000. */
+    timeout?: number;
+    /** Retries after the first attempt. Default 2. */
+    maxRetries?: number;
+    /** Custom `fetch` (custom transports, tracing). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Headers sent on every request. */
+    defaultHeaders?: Record<string, string>;
+    /** Allow a workspace API key in a browser. Leaks the key to anyone who loads the page. */
+    dangerouslyAllowBrowser?: boolean;
+    /** `off` (default), `warn` or `debug`. Falls back to `PRODUCTCRAFT_LOG`. */
+    logLevel?: LogLevel;
+    /** Where log lines go. Default `console`. Never receives headers or bodies. */
+    logger?: Logger;
+    /** Default secret(s) for `webhooks.unwrap`. */
+    webhookSecret?: string | readonly string[];
+    /** Platform-auth host used for the workspace lookup. */
+    platformAuthBaseUrl?: string;
+}
+/** Per-request options: always the last argument of an SDK method. */
+interface RequestOptions {
+    /** Overrides the automatic Idempotency-Key (and makes a POST/PATCH retryable). */
+    idempotencyKey?: string;
+    /** Per-attempt timeout in ms. */
+    timeout?: number;
+    maxRetries?: number;
+    headers?: Record<string, string | undefined>;
+    signal?: AbortSignal;
+    /** `{workspace_id}` for this call (bearer tokens that span workspaces). */
+    workspaceId?: string;
+    fetch?: typeof fetch;
+}
+/** What a generated method hands to `request()`. */
+interface RequestSpec {
+    method: HTTPMethod;
+    /** Path template, e.g. `/v1/workspaces/{workspace_id}/domains/{id}`. */
+    path: string;
+    pathParams?: Record<string, string | number | undefined>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string | undefined>;
+    /** The spec declares an `Idempotency-Key` header on this operation. */
+    idempotent?: boolean;
+    /** The success response is not JSON: resolve to the raw `Response`. */
+    raw?: boolean;
+    /** Keyless, browser-safe route: send no credential. */
+    public?: boolean;
+}
+interface PollConfig {
+    /** Field whose value decides completion, e.g. `status`. */
+    field: string;
+    /** Values that end the poll. */
+    terminal: readonly string[];
+}
+interface PollOptions extends RequestOptions {
+    /** Delay between polls in ms, unless the server sends `Retry-After`. Default 2 000. */
+    intervalMs?: number;
+    /** Give up after this many ms. Default 300 000. */
+    timeoutMs?: number;
+}
+/** Identifies the product package in `User-Agent`. */
+interface SDKIdentity {
+    name: string;
+    version: string;
+}
+declare const DEFAULT_TIMEOUT_MS = 60000;
+declare const DEFAULT_MAX_RETRIES = 2;
+/** Retry-After above this fails fast instead of waiting. */
+declare const MAX_RETRY_AFTER_MS = 60000;
+declare const PC_WORKSPACE_ID_ENV = "PRODUCTCRAFT_WORKSPACE_ID";
+declare const PC_LOG_ENV = "PRODUCTCRAFT_LOG";
+/** Full-jitter exponential backoff: random in [0, min(8 s, 0.5 s * 2^attempt)). */
+declare function backoffMs(attempt: number): number;
+/**
+ * The typed `openapi-fetch` escape hatch (`.client` on every product), over
+ * the same credential and base URL as `api`. It does not retry.
+ * A standalone function so bundles that never use it leave openapi-fetch out.
+ */
+declare function createOpenAPIClient<TPaths extends object>(api: APIClient): Client<TPaths>;
+/** Clears the per-process workspace lookup cache. For tests. */
+declare function _resetWorkspaceCache(): void;
+declare class APIClient {
+    #private;
+    readonly baseUrl: string;
+    /** The resolved credential. Non-enumerable, so logging the client does not print the key. */
+    readonly auth: PCAuth | undefined;
+    readonly workspaceId: string | undefined;
+    readonly timeout: number;
+    readonly maxRetries: number;
+    readonly webhookSecret: string | readonly string[] | undefined;
+    constructor(options: ClientOptions | undefined, defaultBaseUrl: string, sdk?: SDKIdentity);
+    /** Send one logical API call (with retries). Resolves to the parsed body. */
+    request<T>(spec: RequestSpec, options?: RequestOptions): APIPromise<T>;
+    /** A paginated list call. `await` for one page, `for await` for every item. */
+    list<Item>(spec: RequestSpec, options?: RequestOptions): PagePromise<Item>;
+    /** Retrieve repeatedly until `config.field` reaches a terminal value. */
+    poll<T>(spec: RequestSpec, config: PollConfig, options?: PollOptions): Promise<T>;
+    /** Create, then poll the created object to a terminal state. */
+    createAndPoll<T>(createSpec: RequestSpec, retrieveSpec: (created: T) => RequestSpec, config: PollConfig, options?: PollOptions): Promise<T>;
+    /** Verify a webhook with the given secret, the client's `webhookSecret`, or `envVar`. */
+    unwrapWebhook<T = unknown>(params: {
+        payload: WebhookPayload;
+        headers: WebhookHeaders;
+        secret?: string | readonly string[];
+        toleranceSeconds?: number;
+    }, envVar?: string): Promise<T>;
+}
+
+/** This package's version, injected at build time from package.json. */
+declare const CORE_VERSION: string;
+
+export { APIClient, APIConnectionError, APIError, APIPromise, APITimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, CORE_VERSION, type ClientOptions, ConfigurationError, ConflictError, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, ERROR_DOCS_URL, type ErrorParam, type HTTPMethod, IdempotencyKeyReuseError, InternalServerError, type LastResponse, type LogLevel, type Logger, MAX_RETRY_AFTER_MS, NotFoundError, type OpenEnum, type PCAuth, type PCClientConfig, PC_API_KEY_ENV, PC_AUTH_APP_ENV, PC_BASE_URL, PC_LOG_ENV, PC_WORKSPACE_ID_ENV, Page, PagePromise, type PageResponse, PermissionDeniedError, type PollConfig, type PollOptions, ProductCraftError, RateLimitError, type RateLimitInfo, type RawResult, type RequestOptions, type RequestSpec, type SDKIdentity, type ToArrayOptions, UnprocessableEntityError, type VerifyWebhookParams, type WebhookHeaders, type WebhookPayload, WebhookVerificationError, type WithResponse, _resetWorkspaceCache, attachLastResponse, authMiddleware, backoffMs, createOpenAPIClient, makeClient, normalizeHeaders, parseRateLimit, parseRetryAfterMs, readEnv, resolveAuth, timingSafeEqual, verifyWebhook };