@convilyn/sdk 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,893 @@
+/**
+ * Typed errors raised by the Convilyn SDK — a faithful port of the Python
+ * SDK's `exceptions.py`.
+ *
+ * Hierarchy:
+ *
+ *     ConvilynError                  base; everything the SDK throws
+ *     ├── AuthError                  missing / malformed credentials
+ *     ├── APIError                   HTTP 4xx / 5xx (envelope {code, message, details})
+ *     │   ├── RateLimitError         HTTP 429
+ *     │   ├── PlanRequiredError      HTTP 402 + TIER_REQUIRED-family code
+ *     │   ├── QuotaExceededError     HTTP 402 (insufficient_balance / QUOTA_EXCEEDED)
+ *     │   ├── S3UploadError          presigned upload PUT failed
+ *     │   └── RetryExhaustedError    retry policy ran out of attempts
+ *     ├── JobFailedError             conversion job status=failed
+ *     ├── JobTimeoutError            convert.wait() timed out
+ *     ├── GoalJobFailedError         goal job status=failed
+ *     ├── GoalJobTimeoutError        goals.wait() timed out
+ *     └── WebSocketError             goal-event stream failure
+ *
+ * Catch `ConvilynError` to handle any SDK-originated failure; branch on the
+ * `code` / `statusCode` fields for typed handling.
+ */
+type ErrorDetails = Record<string, unknown>;
+/** Base class for every error this SDK throws. */
+declare class ConvilynError extends Error {
+    constructor(message: string);
+}
+/** Authentication / authorization failed before any HTTP call. */
+declare class AuthError extends ConvilynError {
+    constructor(message: string);
+}
+/**
+ * Server returned a non-success HTTP response. The Convilyn API uses the
+ * envelope `{code, message, details}`; those are exposed as fields.
+ *
+ * `message` holds the server's raw message (matching the Python `.message`
+ * attribute); branch on `code` / `statusCode` for typed handling.
+ */
+declare class APIError extends ConvilynError {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly details: ErrorDetails;
+    constructor(statusCode: number, code: string, message: string, details?: ErrorDetails);
+}
+/** HTTP 429 — the SDK or caller exceeded the API rate limit. */
+declare class RateLimitError extends APIError {
+    constructor(statusCode: number, code: string, message: string, details?: ErrorDetails);
+}
+/** HTTP 402 with a TIER_REQUIRED-family code — the caller's plan is too low. */
+declare class PlanRequiredError extends APIError {
+    readonly requiredPlan: string;
+    readonly upgradeUrl: string | null;
+    constructor(statusCode: number, code: string, message: string, details?: ErrorDetails, opts?: {
+        requiredPlan?: string;
+        upgradeUrl?: string | null;
+    });
+}
+/**
+ * HTTP 402 — the run would cost more **credits** than the account's balance.
+ *
+ * The backend currently emits code `insufficient_balance` (and intends to add
+ * `QUOTA_EXCEEDED`); both decode to this error. Fields are in **credits**
+ * (1 credit = $0.01) to match the vocabulary users see in the console / web /
+ * docs — never internal micro-units.
+ */
+declare class QuotaExceededError extends APIError {
+    readonly costCredits: number | null;
+    readonly balanceCredits: number | null;
+    readonly topUpUrl: string | null;
+    constructor(statusCode: number, code: string, message: string, details?: ErrorDetails, opts?: {
+        costCredits?: number | null;
+        balanceCredits?: number | null;
+        topUpUrl?: string | null;
+    });
+}
+/** The presigned upload PUT step of a file upload returned a non-success status. */
+declare class S3UploadError extends APIError {
+    constructor(statusCode: number, code: string, message: string, details?: ErrorDetails);
+}
+/** The retry policy ran out of attempts before the request succeeded. */
+declare class RetryExhaustedError extends APIError {
+    readonly attemptCount: number;
+    constructor(statusCode: number, code: string, message: string, details?: ErrorDetails, opts?: {
+        attemptCount?: number;
+    });
+}
+/** A conversion job (`convert.wait`) finished with status `failed`. */
+declare class JobFailedError extends ConvilynError {
+    readonly jobId: string;
+    readonly processorType: string;
+    readonly code: string;
+    constructor(opts: {
+        jobId: string;
+        processorType: string;
+        code: string;
+        message: string;
+    });
+}
+/** A polling helper exceeded its `timeout` before the conversion job finished. */
+declare class JobTimeoutError extends ConvilynError {
+    readonly jobId: string;
+    readonly elapsed: number;
+    readonly timeout: number;
+    constructor(opts: {
+        jobId: string;
+        elapsed: number;
+        timeout: number;
+    });
+}
+/** A goal (agentic) job finished with status `failed`. */
+declare class GoalJobFailedError extends ConvilynError {
+    readonly jobSpecId: string;
+    readonly code: string;
+    constructor(opts: {
+        jobSpecId: string;
+        code: string | null;
+        message: string | null;
+    });
+}
+/** A goal polling helper exceeded its `timeout` before a terminal status. */
+declare class GoalJobTimeoutError extends ConvilynError {
+    readonly jobSpecId: string;
+    readonly elapsed: number;
+    readonly timeout: number;
+    constructor(opts: {
+        jobSpecId: string;
+        elapsed: number;
+        timeout: number;
+    });
+}
+/** Raised when the goal event stream cannot proceed. */
+declare class WebSocketError extends ConvilynError {
+    readonly payload: string | null;
+    constructor(message: string, opts?: {
+        payload?: string | null;
+    });
+}
+
+/**
+ * Public response types — port of `types.py`.
+ *
+ * Field names are the SDK's **public** names in camelCase (the TS-idiomatic
+ * equivalent of the Python SDK's snake_case public surface), which already
+ * differ from the raw wire in places (`fileName`→`filename`, `mimeType`→
+ * `contentType`). The resource parsers (A2+) map wire → these shapes.
+ *
+ * Money is expressed in **credits** (1 credit = $0.01) everywhere user-facing,
+ * to match the console / web / docs vocabulary — never internal micro-units.
+ *
+ * Types carry data only; the `is_terminal` / `needs_input` Python *properties*
+ * become standalone predicate functions here (tree-shakeable, no class needed).
+ */
+/** Lifecycle status of a file-conversion job (`client.convert`). */
+type JobStatus = 'queued' | 'processing' | 'completed' | 'failed';
+/** A file known to the Convilyn platform. */
+interface File {
+    readonly fileId: string;
+    readonly filename: string;
+    readonly size: number;
+    readonly contentType: string;
+    readonly createdAt: Date;
+    readonly jobId: string | null;
+    readonly isInput: boolean;
+}
+/** A produced artifact attached to a completed job (presigned `url`, 1h TTL). */
+interface ResultFile {
+    readonly filename: string;
+    readonly size: number;
+    readonly mimetype: string;
+    readonly url: string;
+}
+/** Failure detail attached to a `failed` job. */
+interface JobError {
+    readonly code: string;
+    readonly message: string;
+}
+/** A file-conversion job (data only; actions live on the resource). */
+interface ConvertJob {
+    readonly jobId: string;
+    readonly status: JobStatus;
+    readonly processorType: string;
+    readonly progress: number;
+    readonly progressMessage: string | null;
+    readonly resultFiles: ResultFile[] | null;
+    readonly error: JobError | null;
+    readonly retryCount: number;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+    readonly startedAt: Date | null;
+    readonly completedAt: Date | null;
+    readonly estimatedDuration: number | null;
+}
+/** Conversion statuses at which `wait()` stops polling. */
+declare const CONVERT_JOB_TERMINAL_STATUSES: readonly JobStatus[];
+/** True when a conversion job has reached `completed` or `failed`. */
+declare function isConvertJobTerminal(job: Pick<ConvertJob, 'status'>): boolean;
+/** Lifecycle status of a goal (agentic) job (`client.goals`). */
+type GoalJobStatus = 'draft' | 'created' | 'analyzing' | 'slots_pending' | 'ready' | 'ready_with_preview' | 'confirmed' | 'queued' | 'executing' | 'completed' | 'partial' | 'failed' | 'cancelled';
+/** Goal-lane statuses at which `wait()` stops polling. */
+declare const GOAL_JOB_TERMINAL_STATUSES: readonly GoalJobStatus[];
+/** A piece of information the agent is asking the user to supply. */
+interface PendingSlot {
+    readonly slotId: string;
+    readonly slotType: string;
+    readonly question: string;
+    readonly options: Array<string | Record<string, string>> | null;
+    readonly required: boolean;
+    readonly isDisambiguation: boolean;
+    readonly suggestedValue: unknown | null;
+    readonly suggestedConfidence: number | null;
+}
+/** A goal (agentic) job — a "workflow run" in product vocabulary. */
+interface GoalJob {
+    readonly jobSpecId: string;
+    readonly status: GoalJobStatus;
+    readonly progress: number;
+    readonly itemVersion: number | null;
+    readonly attemptId: string | null;
+    readonly goalText: string | null;
+    readonly fileIds: string[];
+    readonly pendingSlots: PendingSlot[];
+    readonly filledSlots: Record<string, unknown>;
+    readonly pendingInterrupts: Record<string, unknown>[];
+    readonly agentMessage: string | null;
+    readonly errorMessage: string | null;
+    readonly errorCode: string | null;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+    readonly startedAt: Date | null;
+    readonly completedAt: Date | null;
+}
+/** True when the workflow run reached a stable end state (incl. `partial`). */
+declare function isGoalJobTerminal(job: Pick<GoalJob, 'status'>): boolean;
+/** True when the agent is blocked waiting on the user (`slots_pending`). */
+declare function goalJobNeedsInput(job: Pick<GoalJob, 'status'>): boolean;
+/** Discriminator for a server-sent event in a goal execution stream. */
+type GoalEventType = 'tool_started' | 'tool_finished' | 'agent_step_started' | 'agent_step_finished' | 'orchestration_transition' | 'status' | 'progress' | 'completed' | 'failed' | 'slot_needed' | 'keepalive' | 'agent_text' | 'agent_text_done';
+/** The known event `type` values (forward-compat: pre-listed so the SDK need
+ * not be re-cut the moment the backend starts emitting a reserved one). */
+declare const GOAL_EVENT_TYPES: readonly GoalEventType[];
+/** Type guard: is `value` a recognised {@link GoalEventType}? */
+declare function isGoalEventType(value: string): value is GoalEventType;
+/**
+ * Event `type` values that close the WebSocket and stop iteration. `cancelled`
+ * is included for a future backend that emits it directly (today it arrives as
+ * a `failed` event with `data.code === "CANCELLED"`) — so it is a plain string,
+ * not a {@link GoalEventType} member.
+ */
+declare const GOAL_EVENT_TERMINAL_TYPES: readonly string[];
+/** One server-sent event in a goal execution stream. */
+interface GoalEvent {
+    readonly type: GoalEventType;
+    readonly schemaVersion: number;
+    readonly jobSpecId: string;
+    readonly emittedAt: Date;
+    readonly seq: number;
+    readonly data: Record<string, unknown>;
+}
+/** True when this event signals the end of the stream. */
+declare function isGoalEventTerminal(event: Pick<GoalEvent, 'type'>): boolean;
+/** Marketplace visibility of a community workflow. */
+type WorkflowVisibility = 'private' | 'public' | 'archived';
+/** Aggregate counters surfaced on every workflow row. */
+interface WorkflowStats {
+    readonly runCount: number;
+    readonly forkCount: number;
+    readonly likeCount: number;
+}
+/** A community / private workflow row. */
+interface Workflow {
+    readonly workflowId: string;
+    readonly ownerId: string | null;
+    readonly specId: string;
+    readonly sourceSpecId: string | null;
+    readonly sourceType: string | null;
+    readonly name: string;
+    readonly description: string | null;
+    readonly visibility: WorkflowVisibility;
+    readonly tags: string[];
+    readonly stats: WorkflowStats;
+    readonly itemVersion: number;
+}
+/** Light-weight community-list row (no heavy spec/system-prompt fields). */
+interface WorkflowSummary {
+    readonly workflowId: string;
+    readonly specId: string;
+    readonly ownerId: string | null;
+    readonly name: string;
+    readonly description: string | null;
+    readonly visibility: WorkflowVisibility;
+    readonly tags: string[];
+    readonly stats: WorkflowStats;
+}
+/** One page of community workflow summaries + a pagination cursor. */
+interface WorkflowSearchPage {
+    readonly items: WorkflowSummary[];
+    readonly cursor: string | null;
+}
+/** Result of `workflows.like` — toggle state + fresh count. */
+interface LikeResponse {
+    readonly liked: boolean;
+    readonly likeCount: number;
+}
+/** Where an account sits against its quota window. */
+type QuotaState = 'ok' | 'soft_limit' | 'quota_exceeded';
+/** Account plan tier. */
+type PlanTier = 'free' | 'pro';
+/**
+ * Caller-plan vs cost-estimate verdict. Amounts in **credits** (the A4 parser
+ * converts the wire's micro-units → credits).
+ */
+interface QuotaCheck {
+    readonly state: QuotaState;
+    readonly tier: PlanTier;
+    readonly estimatedCredits: number;
+    readonly thresholdCredits: number;
+    readonly upgradeUrl: string | null;
+}
+/** Per-tool cost breakdown row inside {@link CostEstimate}. */
+interface ToolCostEstimate {
+    readonly toolName: string;
+    readonly perInvocationCredits: number;
+}
+/**
+ * Result of `account.getQuota()` — a cost-range projection (min / total / max)
+ * in **credits** plus the quota verdict, in one round-trip.
+ */
+interface CostEstimate {
+    readonly estimatedCredits: number;
+    readonly estimatedUsd: number;
+    readonly estimatedTotalCredits: number;
+    readonly estimatedMinCredits: number;
+    readonly estimatedMaxCredits: number;
+    readonly tools: ToolCostEstimate[];
+    readonly quotaCheck: QuotaCheck;
+}
+/** The caller's current billing plan. */
+interface Plan {
+    readonly tier: PlanTier;
+}
+/** One past usage period for a specific metric. */
+interface UsageHistoryEntry {
+    readonly metric: string;
+    readonly periodStart: Date;
+    readonly periodEnd: Date;
+    readonly used: number;
+    readonly limit: number | null;
+}
+
+/**
+ * The minimal response shape a policy needs — so policies never depend on the
+ * concrete `fetch` `Response` or on `HttpClient`. `headers.get` is the standard
+ * `Headers` accessor (case-insensitive in real `fetch`).
+ */
+interface RetryableResponse {
+    readonly status: number;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+}
+/** Pluggable retry policy. Mirrors the Python `RetryPolicy` Protocol. */
+interface RetryPolicy {
+    /** Decide whether a retry should fire for this outcome. */
+    shouldRetry(response: RetryableResponse | null, error: unknown, attempt: number): boolean;
+    /** Seconds to wait before the next attempt. */
+    nextDelay(response: RetryableResponse | null, attempt: number): number;
+}
+/** Tunables for {@link ExponentialBackoffRetry}; all optional. */
+interface ExponentialBackoffOptions {
+    maxAttempts?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    jitter?: number;
+    retryableStatuses?: ReadonlySet<number>;
+    /** Injectable RNG in [0, 1) — defaults to `Math.random` (tests pass a stub). */
+    rng?: () => number;
+}
+/**
+ * Capped exponential backoff with full jitter, honouring `Retry-After`.
+ *
+ * Defaults match the Python SDK: 5 attempts, 0.2s base, 30s cap, ±25% jitter.
+ * Retries only on a retryable **status** — never on a thrown error (mirrors the
+ * Python policy, which receives `error=null` from the transport loop).
+ */
+declare class ExponentialBackoffRetry implements RetryPolicy {
+    #private;
+    readonly maxAttempts: number;
+    readonly baseDelay: number;
+    readonly maxDelay: number;
+    readonly jitter: number;
+    readonly retryableStatuses: ReadonlySet<number>;
+    constructor(options?: ExponentialBackoffOptions);
+    shouldRetry(response: RetryableResponse | null, error: unknown, attempt: number): boolean;
+    nextDelay(response: RetryableResponse | null, attempt: number): number;
+}
+/** Disables retries entirely — pass to the client to fail fast. */
+declare class NoRetry implements RetryPolicy {
+    shouldRetry(): boolean;
+    nextDelay(): number;
+}
+
+/**
+ * Auto-throttle policy — sleep + retry on {@link QuotaExceededError}. Port of
+ * the Python SDK's `_internal/throttle.py`.
+ *
+ * Layered *above* the transport's {@link RetryPolicy}: that policy retries
+ * transient transport failures (5xx / 429 / 408), while this module targets the
+ * 402 `QUOTA_EXCEEDED` envelope specifically — where the remediation is *waiting
+ * for the quota window to reset*, not re-issuing the same request faster.
+ *
+ * Only {@link AutoThrottleConfig} is part of the public surface (re-exported
+ * from the package root); the resolver / sleep math / soft-limit helpers are
+ * internal wiring used by `internal/http.ts`.
+ *
+ * Design choices (mirroring the Python module):
+ * - **Bounded retry** — defaults to `maxRetries = 1` so a misconfigured caller
+ *   cannot get stuck in an infinite sleep+retry loop against a permanently
+ *   overrun account.
+ * - **Bounded sleep** — `maxSleep` caps any server-supplied delay; if the
+ *   server asks the SDK to wait longer, the SDK gives up immediately and
+ *   re-raises so the caller's UX path stays predictable.
+ * - **Forward-compat reset hints** — when the backend starts emitting them, the
+ *   SDK reads `details.retry_after_seconds` or `details.reset_at` transparently.
+ */
+
+/** Tunables for {@link AutoThrottleConfig}; all optional (each defaults above). */
+interface AutoThrottleOptions {
+    /** Max number of quota-retry attempts after the first 402 (default 1). */
+    maxRetries?: number;
+    /** Hard cap (seconds) on any single sleep; over this the SDK re-raises. */
+    maxSleep?: number;
+    /** Sleep (seconds) used when the 402 carries no reset hint. */
+    fallbackSleep?: number;
+}
+/**
+ * Knobs for the {@link QuotaExceededError} retry loop. Enable on the client with
+ * `new Convilyn({ autoThrottle: true })` (defaults) or
+ * `new Convilyn({ autoThrottle: new AutoThrottleConfig({ maxRetries: 2 }) })`.
+ */
+declare class AutoThrottleConfig {
+    readonly maxRetries: number;
+    readonly maxSleep: number;
+    readonly fallbackSleep: number;
+    constructor(options?: AutoThrottleOptions);
+}
+
+/** Pluggable auth strategy. Mirrors the Python `AuthStrategy` Protocol. */
+interface AuthStrategy {
+    /** Headers to merge into every request (e.g. `Authorization`). */
+    headers(): Record<string, string>;
+    /** The raw bearer token — used by non-HTTP transports (WebSocket). */
+    bearerToken(): string;
+}
+
+/**
+ * Public transport contracts — the dependency-injection seams the client
+ * surface exposes so callers can swap behaviour without forking the SDK.
+ *
+ * This module is **public** (re-exported from the package root): it holds the
+ * contract, not the implementation. The default WHATWG-`WebSocket` adapter that
+ * satisfies {@link WSTransport} lives in `internal/ws.ts` and is NOT part of the
+ * public surface — only the interface a custom transport must implement is.
+ */
+/**
+ * Minimal contract a goal event transport must satisfy. Inject a custom
+ * one via `new Convilyn({ wsTransportFactory })` to stream `goals.events()` over
+ * a non-default socket (e.g. the `ws` package in older Node, or a test double).
+ */
+interface WSTransport {
+    connect(url: string): Promise<void>;
+    send(payload: string): Promise<void>;
+    recv(): Promise<string>;
+    close(): Promise<void>;
+}
+
+/**
+ * HTTP transport — port of `_internal/http.py` (fetch-based; Node 18+ global
+ * `fetch` or any browser).
+ *
+ * Responsibilities (single, per SRP):
+ * - inject auth + standard headers (`User-Agent`, `Accept`);
+ * - normalise the Convilyn error envelope `{code, message, details}` (flat, or
+ *   nested under `detail` / `error`) into typed errors;
+ * - apply the injected {@link RetryPolicy} on transient 408/429/5xx, reusing one
+ *   `Idempotency-Key` across retries of a mutating verb;
+ * - presigned-URL helpers (`externalPut` / `externalGet`) that send NO auth.
+ *
+ * The resilience decision lives in {@link RetryPolicy} (DIP seam) — this client
+ * owns only the loop. Optionally, an {@link AutoThrottleConfig} adds a higher-
+ * level shim that sleeps + re-issues on the 402 `QUOTA_EXCEEDED` envelope
+ * (remediation = waiting for the quota window, not retrying faster); it stays
+ * OFF unless the caller opts in, so the default path decodes + throws unchanged.
+ */
+
+/** Request body shapes the transport accepts. */
+type RequestBody = Uint8Array | ArrayBuffer | string | ReadableStream<Uint8Array>;
+/** Narrow, stubbable `fetch` signature (the real global `fetch` satisfies it). */
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** Per-request options for {@link HttpClient.request} / `rawRequest`. */
+interface RequestOptions {
+    headers?: Record<string, string>;
+    json?: unknown;
+    params?: Record<string, string | number | boolean | null | undefined>;
+    content?: RequestBody;
+}
+/** Constructor options for {@link HttpClient}. */
+interface HttpClientOptions {
+    auth: AuthStrategy;
+    baseUrl?: string;
+    /** Per-request timeout in seconds. */
+    timeout?: number;
+    userAgent?: string;
+    retryPolicy?: RetryPolicy;
+    idempotencyEnabled?: boolean;
+    /** Opt-in 402-quota sleep+retry shim; omitted / null = disabled. */
+    autoThrottle?: AutoThrottleConfig | null;
+    /** Injectable `fetch` (tests pass a stub). Defaults to the global `fetch`. */
+    fetch?: FetchLike;
+    /** Injectable sleep in seconds (tests pass a no-op). Defaults to real timer. */
+    sleep?: (seconds: number) => Promise<void>;
+}
+/** Async HTTP client with Convilyn-specific header + error semantics. */
+declare class HttpClient {
+    #private;
+    constructor(options: HttpClientOptions);
+    get baseUrl(): string;
+    /** Read-only handle to the auth strategy (used by the WS transport). */
+    get auth(): AuthStrategy;
+    /**
+     * Issue a request, applying the retry policy on transient failures and
+     * raising a typed error on a non-2xx final response.
+     */
+    request(method: string, path: string, options?: RequestOptions): Promise<Response>;
+    /**
+     * Like {@link request} but never raises on HTTP status — returns the final
+     * response so callers (the `convilyn api` CLI escape hatch) can inspect it.
+     */
+    rawRequest(method: string, path: string, options?: RequestOptions): Promise<Response>;
+    /**
+     * PUT to an external absolute URL (e.g. a presigned upload URL). Sends NO
+     * Convilyn auth (the URL carries its own signature) and is NOT retried.
+     */
+    externalPut(url: string, { content, headers }: {
+        content: RequestBody;
+        headers?: Record<string, string>;
+    }): Promise<Response>;
+    /** GET an external absolute URL (e.g. a presigned download). No auth. */
+    externalGet(url: string, { headers }?: {
+        headers?: Record<string, string>;
+    }): Promise<Response>;
+    /** No persistent connection pool with `fetch`; provided for API symmetry. */
+    close(): Promise<void>;
+}
+
+/**
+ * Account resource — caller-side billing plan + quota queries. Port of
+ * `resources/account.py`.
+ *
+ *   POST /api/v1/workflows/cost-preview  — estimate cost (credits) + quota verdict
+ *   GET  /api/v1/payment/usage/history   — past usage periods
+ *
+ * Read-only — actions (upgrade, top-up) live on the website, not the SDK.
+ * Money is expressed in **credits** (the µU wire is converted in the parser).
+ */
+
+/** Options for {@link Account.getQuota}. */
+interface GetQuotaOptions {
+    /** Fully-qualified tool ids (e.g. `pdf-mcp:extract_text`). */
+    tools?: string[];
+    /** Iteration cap from the draft spec. */
+    maxIterations?: number;
+}
+/** Asynchronous account-tier resource (`client.account`). */
+declare class Account {
+    #private;
+    constructor(http: HttpClient);
+    /** Estimate a workflow's cost (credits) + check the verdict against the plan. */
+    getQuota(options?: GetQuotaOptions): Promise<CostEstimate>;
+    /** Return the caller's current billing plan (derived from the cost-preview tier). */
+    getPlan(): Promise<Plan>;
+    /**
+     * List the caller's past usage periods (one row per metric+period). `since`
+     * filters client-side to entries whose `periodStart` is on or after it
+     * (the backend does not honour a query param today).
+     */
+    usageHistory(options?: {
+        since?: Date;
+    }): Promise<UsageHistoryEntry[]>;
+}
+
+/**
+ * Convert resource — document conversion jobs. Port of
+ * `resources/convert.py`.
+ *
+ *   POST /api/v1/jobs        — create a conversion job
+ *   GET  /api/v1/jobs/{id}   — poll status
+ *   GET  <resultFiles[0].url>— download the produced artifact (presigned, no auth)
+ *
+ * Data lives on {@link ConvertJob}; behaviour (poll / wait / download) lives
+ * here. The poll clock + sleep are injectable so the wait loop is testable
+ * without real time.
+ */
+
+/** Options for {@link Convert.create} — supply exactly one of `file` / `fileId`. */
+interface CreateConvertOptions {
+    file?: File;
+    fileId?: string;
+    targetFormat: string;
+    sourceFormat?: string;
+    quality?: string;
+    pageRange?: string;
+}
+/** Polling controls for {@link Convert.wait}. */
+interface WaitOptions {
+    timeout?: number;
+    pollInterval?: number;
+}
+/** Test seams: an injectable clock (ms) + sleep (seconds). */
+interface ConvertResourceOptions {
+    sleep?: (seconds: number) => Promise<void>;
+    now?: () => number;
+}
+/** Asynchronous conversion resource (`client.convert`). */
+declare class Convert {
+    #private;
+    constructor(http: HttpClient, options?: ConvertResourceOptions);
+    /** Create a conversion job and return immediately (queued/processing). */
+    create(options: CreateConvertOptions): Promise<ConvertJob>;
+    /** Fetch the current state of a job (one-shot poll). */
+    retrieve(jobId: string): Promise<ConvertJob>;
+    /**
+     * Poll until the job reaches a terminal status, the timeout expires, or the
+     * backend reports failure.
+     *
+     * @throws {@link JobFailedError} when the terminal status is `failed`.
+     * @throws {@link JobTimeoutError} when `timeout` elapses first.
+     */
+    wait(jobId: string, options?: WaitOptions): Promise<ConvertJob>;
+    /** Shortcut: {@link create} then {@link wait}. */
+    createAndWait(options: CreateConvertOptions & WaitOptions): Promise<ConvertJob>;
+    /** Presigned download URL for the first result file. */
+    downloadUrl(job: ConvertJob | string): Promise<string>;
+    /** Download the first result file to `to` (Node) and return that path. */
+    downloadTo(job: ConvertJob | string, { to }: {
+        to: string;
+    }): Promise<string>;
+}
+
+/**
+ * Files resource — upload local files via Convilyn's presigned-URL flow.
+ *
+ * Port of `resources/files.py`. Three steps behind one {@link Files.upload}:
+ *   1. `POST /api/v1/upload/presign`  — Convilyn issues a presigned upload URL
+ *   2. `PUT  <presigned-url>`         — bytes go straight to storage (no Convilyn auth)
+ *   3. `POST /api/v1/upload/confirm`  — Convilyn registers the file record
+ *
+ * The steps are private methods so future extensions (multipart, progress) can
+ * override one without rewriting the orchestration. The resource depends only
+ * on {@link HttpClient} + types (clean DIP — no sibling-resource imports).
+ */
+
+/** Caller input for {@link Files.upload} — exactly one of `path` / `content`. */
+interface UploadOptions {
+    /** Filesystem path (Node only). */
+    path?: string;
+    /** Raw bytes (works in the browser too). */
+    content?: Uint8Array | ArrayBuffer | string;
+    /** Override the filename (required when uploading raw `content`). */
+    filename?: string;
+    /** MIME type; defaults to a best-guess from the filename suffix. */
+    contentType?: string;
+}
+/** Asynchronous file-management resource (`client.files`). */
+declare class Files {
+    #private;
+    constructor(http: HttpClient);
+    /**
+     * Upload a file and return its {@link File} record. Supply exactly one of
+     * `path` (Node) or `content` (bytes/string).
+     */
+    upload(options: UploadOptions): Promise<File>;
+}
+
+/**
+ * Goals resource — agentic goal workflow execution. Port of
+ * `resources/goals.py`.
+ *
+ *   POST  /api/v1/jobs/goal                    — create a job ("workflow run")
+ *   GET   /api/v1/jobs/goal/{id}               — full status (drives polling)
+ *   PATCH /api/v1/jobs/goal/{id}/slots         — answer HITL slots
+ *   POST  /api/v1/jobs/goal/{id}/confirm|cancel|retry
+ *   WS    subscribe → GoalEvent stream         — live execution events
+ *
+ * Same SOLID seams as the convert resource (data on {@link GoalJob}, behaviour
+ * here) plus the {@link WSTransport} DIP seam for the event stream.
+ */
+
+/** Options for {@link Goals.start} — supply exactly one of `workflowId` / `goalText`. */
+interface StartGoalOptions {
+    workflowId?: string;
+    goalText?: string;
+    files?: string[];
+    slots?: Record<string, unknown>;
+    /**
+     * Optional BYO-LLM provider config id (from the console vault) to run this
+     * job on your own provider/key. Omit to use your account default config.
+     * Honoured only when BYO-LLM is enabled for your account; otherwise the run
+     * uses the platform provider.
+     */
+    llmConfigId?: string;
+}
+/** Polling controls for {@link Goals.wait}. */
+interface GoalWaitOptions {
+    timeout?: number;
+    pollInterval?: number;
+}
+/** Constructor options + test seams for {@link Goals}. */
+interface GoalsResourceOptions {
+    wsUrl?: string | null;
+    wsTransportFactory?: () => WSTransport;
+    sleep?: (seconds: number) => Promise<void>;
+    now?: () => number;
+}
+/** Asynchronous goal workflow resource (`client.goals`). */
+declare class Goals {
+    #private;
+    constructor(http: HttpClient, options?: GoalsResourceOptions);
+    /** Create a goal job and return its initial {@link GoalJob} state. */
+    start(options: StartGoalOptions): Promise<GoalJob>;
+    /** Fetch the current state of a goal job. */
+    retrieve(jobSpecId: string): Promise<GoalJob>;
+    /**
+     * Poll until the job reaches a terminal state OR stops for HITL
+     * (`slots_pending`). `failed` raises {@link GoalJobFailedError}; an elapsed
+     * deadline raises {@link GoalJobTimeoutError}.
+     */
+    wait(jobSpecId: string, options?: GoalWaitOptions): Promise<GoalJob>;
+    /** Shortcut: {@link start} then {@link wait}. */
+    run(options: StartGoalOptions & GoalWaitOptions): Promise<GoalJob>;
+    /** Answer a single slot the agent is waiting on (sugar over {@link fillSlots}). */
+    fillSlot(jobSpecId: string, options: {
+        slotId: string;
+        value: unknown;
+        expectedVersion?: number;
+    }): Promise<GoalJob>;
+    /** Answer one or more slots in a single PATCH (`{slotId: value}` → wire list). */
+    fillSlots(jobSpecId: string, answers: Record<string, unknown>, options?: {
+        expectedVersion?: number;
+    }): Promise<GoalJob>;
+    /** Confirm a slots-filled job, queueing it for execution. */
+    confirm(jobSpecId: string, options?: {
+        expectedVersion?: number;
+    }): Promise<GoalJob>;
+    /** Cancel a running or queued job. */
+    cancel(jobSpecId: string): Promise<GoalJob>;
+    /** Retry a failed job (resume the thread or start a fresh rerun). */
+    retry(jobSpecId: string, options?: {
+        rerunMode?: 'retry_same_thread' | 'fresh_rerun';
+        reason?: string;
+    }): Promise<GoalJob>;
+    /**
+     * Stream goal execution events for a job. Opens a WebSocket, subscribes,
+     * then yields each {@link GoalEvent} in order; the iterator ends (and the
+     * socket closes) on a terminal event. No auto-reconnect — the backend does
+     * not replay missed events, so a silent reconnect would hide gaps.
+     *
+     * **WebSocket streaming is not available with a `ck_` consumer key in v1** —
+     * the backend WS gateway does not authenticate `ck_` keys, so the connection
+     * is denied. Use {@link wait} polling (standard HTTP auth, works today) for
+     * the supported real-time path. This method is wired and ready for when the
+     * gateway gains `ck_` support.
+     *
+     * @throws {@link WebSocketError} on connect/subscribe failure, a dropped
+     *   stream, or an unparseable/unrecognised envelope.
+     */
+    events(jobSpecId: string, options?: {
+        wsUrl?: string;
+    }): AsyncGenerator<GoalEvent, void, void>;
+}
+
+/**
+ * Workflows resource — community marketplace + private workflow management.
+ * Port of `resources/workflows.py`.
+ *
+ *   GET   /api/v1/workflows/community   — browse the public listing (search)
+ *   GET   /api/v1/workflows/{id}        — fetch one row
+ *   POST  /api/v1/workflows/fork        — fork a source into a private workflow
+ *   PATCH /api/v1/workflows/{id}        — partial update (publish = visibility)
+ *   POST  /api/v1/workflows/{id}/like   — toggle like
+ *
+ * `fork` / `publish` require Pro tier; the platform's 402/403 surfaces as
+ * {@link import('../errors').APIError} so callers branch on the status code.
+ */
+
+/** Sort order for a marketplace workflow search. */
+type WorkflowSortMode = 'recent' | 'popular';
+/** Options for {@link Workflows.search}. */
+interface WorkflowSearchOptions {
+    tag?: string;
+    sort?: WorkflowSortMode;
+    limit?: number;
+    cursor?: string;
+}
+/** Options for {@link Workflows.fork}. */
+interface ForkWorkflowOptions {
+    sourceSpecId: string;
+    name?: string;
+}
+/** Options for {@link Workflows.patch} (optimistic lock via `itemVersion`). */
+interface PatchWorkflowOptions {
+    itemVersion: number;
+    name?: string;
+    description?: string;
+    visibility?: WorkflowVisibility;
+    tags?: string[];
+}
+/** Asynchronous community-workflows resource (`client.workflows`). */
+declare class Workflows {
+    #private;
+    constructor(http: HttpClient);
+    /** Browse the public community listing (one page + a `cursor`). */
+    search(options?: WorkflowSearchOptions): Promise<WorkflowSearchPage>;
+    /** Fetch a single workflow by id. */
+    get(workflowId: string): Promise<Workflow>;
+    /** Fork a curated/user source into a new private workflow (Pro). */
+    fork(options: ForkWorkflowOptions): Promise<Workflow>;
+    /** Flip an owned workflow's visibility to `public` (Pro; optimistic lock). */
+    publish(workflowId: string, options: {
+        itemVersion: number;
+    }): Promise<Workflow>;
+    /** Partial update of an owned workflow (the generic PATCH escape hatch). */
+    patch(workflowId: string, options: PatchWorkflowOptions): Promise<Workflow>;
+    /** Toggle the caller's like on a public workflow (idempotent toggle). */
+    like(workflowId: string): Promise<LikeResponse>;
+}
+
+/**
+ * Async root client — port of `client.py`.
+ *
+ * Wires auth + HTTP transport and exposes the resource accessors. This A2
+ * increment exposes `files` + `convert`; `goals` / `workflows` / `account`
+ * (and the WebSocket knobs) extend this class in A4. Async-only: Node and the
+ * browser are async-native, so there is no synchronous wrapper.
+ */
+
+/** Constructor options for {@link Convilyn}. */
+interface ConvilynOptions {
+    /** API key; falls back to `CONVILYN_API_KEY`. Ignored when `auth` is given. */
+    apiKey?: string;
+    baseUrl?: string;
+    /** Per-request timeout in seconds. */
+    timeout?: number;
+    /** Custom auth strategy (overrides `apiKey`). */
+    auth?: AuthStrategy;
+    /** Cap retry attempts (`0` = no retries). Ignored when `retryPolicy` is given. */
+    maxRetries?: number;
+    /** Custom retry policy (overrides `maxRetries`). */
+    retryPolicy?: RetryPolicy;
+    /** Disable the automatic `Idempotency-Key` on mutating verbs. */
+    disableIdempotency?: boolean;
+    /** WebSocket base URL for `goals.events()`; falls back to `CONVILYN_WS_URL`. */
+    wsUrl?: string;
+    /** Custom WebSocket transport factory (advanced / testing). */
+    wsTransportFactory?: () => WSTransport;
+    /**
+     * Sleep + retry on a 402 quota error, waiting for the quota window to reset
+     * (distinct from {@link retryPolicy}, which handles transient 5xx/429/408).
+     * `true` enables it with defaults (1 retry, 60s cap); pass
+     * `new AutoThrottleConfig({ … })` to tune. Omitted = disabled.
+     */
+    autoThrottle?: boolean | AutoThrottleConfig;
+}
+/** Asynchronous Convilyn client. */
+declare class Convilyn {
+    #private;
+    readonly files: Files;
+    readonly convert: Convert;
+    readonly goals: Goals;
+    readonly workflows: Workflows;
+    readonly account: Account;
+    constructor(options?: ConvilynOptions);
+    get baseUrl(): string;
+    close(): Promise<void>;
+}
+
+/**
+ * Single source of truth for the package version. Kept in lockstep with
+ * package.json + CHANGELOG.md (guarded by test/packaging/version-changelog.test.ts).
+ */
+declare const VERSION = "0.2.0";
+
+export { APIError, AuthError, AutoThrottleConfig, CONVERT_JOB_TERMINAL_STATUSES, type ConvertJob, Convilyn, ConvilynError, type ConvilynOptions, type CostEstimate, type CreateConvertOptions, type ErrorDetails, ExponentialBackoffRetry, type File, type ForkWorkflowOptions, GOAL_EVENT_TERMINAL_TYPES, GOAL_EVENT_TYPES, GOAL_JOB_TERMINAL_STATUSES, type GetQuotaOptions, type GoalEvent, type GoalEventType, type GoalJob, GoalJobFailedError, type GoalJobStatus, GoalJobTimeoutError, type GoalWaitOptions, type JobError, JobFailedError, type JobStatus, JobTimeoutError, type LikeResponse, NoRetry, type PatchWorkflowOptions, type PendingSlot, type Plan, PlanRequiredError, type PlanTier, type QuotaCheck, QuotaExceededError, type QuotaState, RateLimitError, type ResultFile, RetryExhaustedError, type RetryPolicy, S3UploadError, type StartGoalOptions, type ToolCostEstimate, type UploadOptions, type UsageHistoryEntry, VERSION, type WSTransport, type WaitOptions, WebSocketError, type Workflow, type WorkflowSearchOptions, type WorkflowSearchPage, type WorkflowSortMode, type WorkflowStats, type WorkflowSummary, type WorkflowVisibility, goalJobNeedsInput, isConvertJobTerminal, isGoalEventTerminal, isGoalEventType, isGoalJobTerminal };