nonecap 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -89,6 +89,94 @@ interface SolveList {
     data: Solve[];
     has_more: boolean;
 }
+/**
+ * What the downstream target did with a solve's token.
+ *
+ * Only `accepted` and `rejected` count toward the acceptance rate — the other
+ * three are recorded but kept out of the denominator, so a client-side outage
+ * can't look like a token-quality regression.
+ */
+type FeedbackOutcome = 
+/** Downstream accepted the token. */
+"accepted"
+/** Downstream rejected the token. */
+ | "rejected"
+/** Token was submitted but the verdict couldn't be determined. */
+ | "unknown"
+/** Token was never submitted downstream (expired, aborted, deduped). */
+ | "unused"
+/** Downstream failed for a non-token reason (network, 5xx, maintenance). */
+ | "error";
+/**
+ * One verdict to report, for {@link NoneCap.feedback.report} and
+ * {@link NoneCap.feedback.reportMany}.
+ */
+interface FeedbackReport {
+    /** The solve id returned by `solves.create` / `solve()`. Must be your own, `solved` solve. */
+    solve_id: string;
+    outcome: FeedbackOutcome;
+    /**
+     * The raw downstream boolean, when your target has one (OSIPTEL's `estado`:
+     * `false` = accepted, `true` = rejected). Stored verbatim. The API rejects an
+     * item whose `estado` disagrees with its `outcome`.
+     */
+    estado?: boolean | null;
+    /** Freeform downstream reason or code. Truncated to 512 chars server-side. */
+    reason?: string | null;
+    /** When the verdict happened. Advisory only — the server stamps its own timestamps. */
+    reported_at?: string | Date | null;
+}
+/** A recorded feedback resource. */
+interface Feedback {
+    object: "feedback";
+    solve_id: string;
+    outcome: FeedbackOutcome;
+    estado: boolean | null;
+    reason: string | null;
+    reported_at: string | null;
+    /** How many times this solve's verdict has been written. 1 on first report. */
+    report_count: number;
+    created_at: string;
+    updated_at: string;
+}
+/** What happened to one item of a batch. */
+type FeedbackStatus = 
+/** First report for this solve. */
+"recorded"
+/** Overwrote an earlier report. */
+ | "updated"
+/** Identical to what was already stored — no write. */
+ | "unchanged"
+/** Rejected; see `error`. */
+ | "error";
+/** One item's result, in the same position as the report you sent. */
+interface FeedbackResult {
+    solve_id: string;
+    status: FeedbackStatus;
+    /** Set only when `status === "error"`. Note the bare shape: no `error` wrapper. */
+    error: {
+        code: ErrorCode;
+        message: string;
+        param: string | null;
+    } | null;
+}
+/**
+ * The result of {@link NoneCap.feedback.reportMany}.
+ *
+ * Items are resolved independently, so one bad solve id never discards the
+ * rest — which also means a broken integration reports zero failures at the
+ * HTTP level. Check `failed` (or scan `results`), not just the absence of a
+ * thrown error.
+ */
+interface FeedbackBatch {
+    object: "feedback_batch";
+    recorded: number;
+    updated: number;
+    unchanged: number;
+    failed: number;
+    /** One entry per report you sent, in request order. */
+    results: FeedbackResult[];
+}
 /** Your account, including the current credit balance. */
 interface Account {
     object: "account";
@@ -98,7 +186,15 @@ interface Account {
     created_at: string;
 }
 /** Error codes returned in the API's error envelope. */
-type ErrorCode = "unauthorized" | "forbidden" | "account_locked" | "insufficient_credits" | "invalid_request" | "validation_error" | "not_found" | "conflict" | "rate_limited" | "ext_daily_limit" | "concurrency_limit_exceeded" | "internal_error" | "pool_exhausted";
+type ErrorCode = "unauthorized" | "forbidden" | "account_locked" | "insufficient_credits" | "invalid_request" | "validation_error" | "not_found" | "conflict" | "rate_limited" | "ext_daily_limit" | "concurrency_limit_exceeded"
+/** hCaptcha is rate-limiting this sitekey; the submit was shed. Honour `Retry-After`. */
+ | "sitekey_rate_limited"
+/** The submitting API key hit its own spend cap. */
+ | "key_credit_limit_exceeded"
+/** Feedback: the solve is missing, not yours, or never produced a token. */
+ | "not_eligible"
+/** Feedback: a first report arrived after the reporting window closed. */
+ | "expired_window" | "internal_error" | "pool_exhausted";
 /** The Stripe-style error envelope every non-2xx response carries. */
 interface ErrorEnvelope {
     error: {
@@ -108,6 +204,8 @@ interface ErrorEnvelope {
     };
 }
 
+/** The API caps one `POST /v1/feedback` call at 500 items. */
+declare const FEEDBACK_BATCH_MAX = 500;
 /** Is this a terminal solve status? */
 declare function isTerminal(status: SolveStatus): boolean;
 /** A `fetch` implementation. Defaults to the global `fetch`. */
@@ -138,7 +236,7 @@ interface WaitOptions {
     /** Abort the request. */
     signal?: AbortSignal;
 }
-/** Options for {@link NoneCap.solve}. */
+/** Options for {@link NoneCap.solve} and {@link SolveHandle.result}. */
 interface SolveHelperOptions {
     /**
      * Give up after this many milliseconds and throw {@link TimeoutError}.
@@ -148,6 +246,11 @@ interface SolveHelperOptions {
     /** Abort waiting. */
     signal?: AbortSignal;
 }
+/** Options for {@link NoneCap.solves.start}. */
+interface SolveStartOptions {
+    /** Abort the submission. */
+    signal?: AbortSignal;
+}
 /**
  * The NoneCap API client.
  *
@@ -169,6 +272,22 @@ declare class NoneCap {
         cancel: (id: string, options?: {
             signal?: AbortSignal;
         }) => Promise<Solve>;
+        /**
+         * Submit a solve and return a {@link SolveHandle} for it.
+         *
+         * Unlike {@link NoneCap.solve}, this returns as soon as the submission is
+         * accepted, so `handle.id` is available immediately. Use the handle to
+         * `cancel()` the solve or `await handle.result()` for the finished solve.
+         *
+         * ```ts
+         * const handle = await nc.solves.start({ type: "hcaptcha", sitekey, url });
+         * // ...later, e.g. on shutdown:
+         * await handle.cancel();
+         * // or wait for it:
+         * const { token } = await handle.result();
+         * ```
+         */
+        start: (params: SolveCreateParams, options?: SolveStartOptions) => Promise<SolveHandle>;
         /** Fetch one page of solves. */
         list: (params?: SolveListParams, options?: {
             signal?: AbortSignal;
@@ -184,6 +303,50 @@ declare class NoneCap {
             signal?: AbortSignal;
         }) => AsyncIterableIterator<Solve>;
     };
+    /**
+     * Report what your downstream target did with the tokens we minted.
+     *
+     * Feedback is free, own-solves-only, and idempotent per solve id: reporting
+     * the same solve again corrects the earlier verdict. Only `solved` solves can
+     * be reported, and only within the API's reporting window (~30 days from the
+     * solve; corrections to an already-reported solve are never re-gated by it).
+     */
+    readonly feedback: {
+        /**
+         * Report one solve's downstream outcome, returning the recorded feedback.
+         *
+         * Unlike {@link NoneCap.feedback.reportMany}, a rejected report throws:
+         * {@link NotFoundError} if the solve isn't yours or never minted a token,
+         * {@link ValidationError} if a field is wrong or the reporting window closed.
+         *
+         * ```ts
+         * await nc.feedback.report({ solve_id: solve.id, outcome: "rejected", reason: "..." });
+         * ```
+         */
+        report: (report: FeedbackReport, options?: {
+            signal?: AbortSignal;
+        }) => Promise<Feedback>;
+        /**
+         * Report many verdicts at once — the path to use at volume. Buffer verdicts
+         * as you learn them and flush them here.
+         *
+         * The call succeeds even when individual items are rejected: each is
+         * resolved on its own so one stale id never discards the rest. Check
+         * `failed` rather than relying on a thrown error.
+         *
+         * More than {@link FEEDBACK_BATCH_MAX} reports are split across sequential
+         * requests and merged into one result, in request order. An empty array is
+         * a no-op that returns an empty batch without a request.
+         *
+         * ```ts
+         * const batch = await nc.feedback.reportMany(buffer);
+         * if (batch.failed) console.warn(batch.results.filter((r) => r.status === "error"));
+         * ```
+         */
+        reportMany: (reports: readonly FeedbackReport[], options?: {
+            signal?: AbortSignal;
+        }) => Promise<FeedbackBatch>;
+    };
     /** Fetch your account, including the current credit balance. */
     me(options?: {
         signal?: AbortSignal;
@@ -194,9 +357,58 @@ declare class NoneCap {
      * Uses the server's long-poll under the hood and keeps polling until the
      * solve is terminal or `timeout` elapses. Throws {@link SolveFailedError} if
      * the solve fails/expires/is cancelled, or {@link TimeoutError} on timeout.
+     *
+     * This is sugar for `(await solves.start(params)).result(options)`. When you
+     * need to cancel the solve while it runs, use {@link NoneCap.solves.start}
+     * and keep the {@link SolveHandle}.
      */
     solve(params: SolveCreateParams, options?: SolveHelperOptions): Promise<Solve>;
 }
+/**
+ * A handle on a started solve, returned by {@link NoneCap.solves.start}.
+ *
+ * The handle is the cancellable lifecycle object for one solve. It is a plain
+ * object, not a promise: `await`ing it does nothing useful. Wait for the result
+ * with {@link SolveHandle.result}, and cancel with {@link SolveHandle.cancel}.
+ * You do not construct it yourself — `solves.start()` hands you one with `id`
+ * already resolved.
+ */
+declare class SolveHandle {
+    #private;
+    /** The id of the started solve, available as soon as `start()` resolved. */
+    readonly id: string;
+    constructor(client: NoneCap, solve: Solve);
+    /** The last-known solve state for this handle. */
+    get solve(): Solve;
+    /**
+     * Long-poll until the solve is terminal, returning the solved solve. Throws
+     * {@link SolveFailedError} if it fails/expires/is cancelled, or
+     * {@link TimeoutError} on timeout (with `solveId`/`solve` attached so you can
+     * still {@link SolveHandle.cancel} it).
+     *
+     * Memoizes the *terminal* outcome: once the solve actually finishes, every
+     * later call returns that same settled result. A {@link TimeoutError} is not
+     * memoized — it just means this wait gave up, so a later call (e.g. with a
+     * larger `timeout`) resumes polling. Concurrent calls share one in-flight
+     * poll, so they never issue duplicate requests. The first caller's
+     * `timeout`/`signal` drive the shared poll; a later call starts a fresh one.
+     */
+    result(options?: SolveHelperOptions): Promise<Solve>;
+    /**
+     * Cancel the solve. Cancelled solves are never charged, so this is for clean
+     * shutdown / freeing slots / stopping early, not cost protection.
+     *
+     * If the solve already reached a terminal state the API answers 409; that is
+     * not an error a caller cares about, so this swallows {@link ConflictError}
+     * and returns the current solve state instead. A cancel that lands on a
+     * terminal state (cancelled, or whatever the 409-swallow read back) settles
+     * this handle's {@link SolveHandle.result}, so any in-flight or later wait
+     * stops polling and reflects that terminal state.
+     */
+    cancel(options?: {
+        signal?: AbortSignal;
+    }): Promise<Solve>;
+}
 
 /**
  * Base class for every error this library throws. Catch `NoneCapError` to
@@ -251,8 +463,24 @@ declare class SolveFailedError extends NoneCapError {
     readonly solve: Solve;
     constructor(solve: Solve);
 }
-/** Thrown by {@link NoneCap.solve} when the client-side timeout elapses first. */
+/**
+ * Thrown by {@link NoneCap.solve} (and {@link SolveHandle.result}) when the
+ * client-side timeout elapses first. When the timeout came from waiting on a
+ * solve, `solveId` and the last-known `solve` are attached so you can still
+ * cancel the in-flight solve. They are `undefined` for transport-level timeouts.
+ */
 declare class TimeoutError extends NoneCapError {
+    /** The id of the in-flight solve, when the timeout came from a solve wait. */
+    readonly solveId: string | undefined;
+    /** The last-known solve state, so you can cancel it after a wait timed out. */
+    readonly solve: Solve | undefined;
+    constructor(message: string, opts?: {
+        code?: ErrorCode;
+        status?: number;
+        param?: string | null;
+        solveId?: string;
+        solve?: Solve;
+    });
 }
 
-export { APIError, type Account, AuthenticationError, ConflictError, ConnectionError, type ErrorCode, type ErrorEnvelope, type FetchLike, InsufficientCreditsError, NoneCap, NoneCapError, type NoneCapOptions, NotFoundError, PermissionError, type Proxy, RateLimitError, type Solve, type SolveCreateParams, type SolveError, SolveFailedError, type SolveHelperOptions, type SolveList, type SolveListParams, type SolveStatus, type SolveType, TimeoutError, ValidationError, type WaitOptions, isTerminal };
+export { APIError, type Account, AuthenticationError, ConflictError, ConnectionError, type ErrorCode, type ErrorEnvelope, FEEDBACK_BATCH_MAX, type Feedback, type FeedbackBatch, type FeedbackOutcome, type FeedbackReport, type FeedbackResult, type FeedbackStatus, type FetchLike, InsufficientCreditsError, NoneCap, NoneCapError, type NoneCapOptions, NotFoundError, PermissionError, type Proxy, RateLimitError, type Solve, type SolveCreateParams, type SolveError, SolveFailedError, SolveHandle, type SolveHelperOptions, type SolveList, type SolveListParams, type SolveStartOptions, type SolveStatus, type SolveType, TimeoutError, ValidationError, type WaitOptions, isTerminal };

package/dist/index.d.ts

@@ -89,6 +89,94 @@ interface SolveList {
     data: Solve[];
     has_more: boolean;
 }
+/**
+ * What the downstream target did with a solve's token.
+ *
+ * Only `accepted` and `rejected` count toward the acceptance rate — the other
+ * three are recorded but kept out of the denominator, so a client-side outage
+ * can't look like a token-quality regression.
+ */
+type FeedbackOutcome = 
+/** Downstream accepted the token. */
+"accepted"
+/** Downstream rejected the token. */
+ | "rejected"
+/** Token was submitted but the verdict couldn't be determined. */
+ | "unknown"
+/** Token was never submitted downstream (expired, aborted, deduped). */
+ | "unused"
+/** Downstream failed for a non-token reason (network, 5xx, maintenance). */
+ | "error";
+/**
+ * One verdict to report, for {@link NoneCap.feedback.report} and
+ * {@link NoneCap.feedback.reportMany}.
+ */
+interface FeedbackReport {
+    /** The solve id returned by `solves.create` / `solve()`. Must be your own, `solved` solve. */
+    solve_id: string;
+    outcome: FeedbackOutcome;
+    /**
+     * The raw downstream boolean, when your target has one (OSIPTEL's `estado`:
+     * `false` = accepted, `true` = rejected). Stored verbatim. The API rejects an
+     * item whose `estado` disagrees with its `outcome`.
+     */
+    estado?: boolean | null;
+    /** Freeform downstream reason or code. Truncated to 512 chars server-side. */
+    reason?: string | null;
+    /** When the verdict happened. Advisory only — the server stamps its own timestamps. */
+    reported_at?: string | Date | null;
+}
+/** A recorded feedback resource. */
+interface Feedback {
+    object: "feedback";
+    solve_id: string;
+    outcome: FeedbackOutcome;
+    estado: boolean | null;
+    reason: string | null;
+    reported_at: string | null;
+    /** How many times this solve's verdict has been written. 1 on first report. */
+    report_count: number;
+    created_at: string;
+    updated_at: string;
+}
+/** What happened to one item of a batch. */
+type FeedbackStatus = 
+/** First report for this solve. */
+"recorded"
+/** Overwrote an earlier report. */
+ | "updated"
+/** Identical to what was already stored — no write. */
+ | "unchanged"
+/** Rejected; see `error`. */
+ | "error";
+/** One item's result, in the same position as the report you sent. */
+interface FeedbackResult {
+    solve_id: string;
+    status: FeedbackStatus;
+    /** Set only when `status === "error"`. Note the bare shape: no `error` wrapper. */
+    error: {
+        code: ErrorCode;
+        message: string;
+        param: string | null;
+    } | null;
+}
+/**
+ * The result of {@link NoneCap.feedback.reportMany}.
+ *
+ * Items are resolved independently, so one bad solve id never discards the
+ * rest — which also means a broken integration reports zero failures at the
+ * HTTP level. Check `failed` (or scan `results`), not just the absence of a
+ * thrown error.
+ */
+interface FeedbackBatch {
+    object: "feedback_batch";
+    recorded: number;
+    updated: number;
+    unchanged: number;
+    failed: number;
+    /** One entry per report you sent, in request order. */
+    results: FeedbackResult[];
+}
 /** Your account, including the current credit balance. */
 interface Account {
     object: "account";
@@ -98,7 +186,15 @@ interface Account {
     created_at: string;
 }
 /** Error codes returned in the API's error envelope. */
-type ErrorCode = "unauthorized" | "forbidden" | "account_locked" | "insufficient_credits" | "invalid_request" | "validation_error" | "not_found" | "conflict" | "rate_limited" | "ext_daily_limit" | "concurrency_limit_exceeded" | "internal_error" | "pool_exhausted";
+type ErrorCode = "unauthorized" | "forbidden" | "account_locked" | "insufficient_credits" | "invalid_request" | "validation_error" | "not_found" | "conflict" | "rate_limited" | "ext_daily_limit" | "concurrency_limit_exceeded"
+/** hCaptcha is rate-limiting this sitekey; the submit was shed. Honour `Retry-After`. */
+ | "sitekey_rate_limited"
+/** The submitting API key hit its own spend cap. */
+ | "key_credit_limit_exceeded"
+/** Feedback: the solve is missing, not yours, or never produced a token. */
+ | "not_eligible"
+/** Feedback: a first report arrived after the reporting window closed. */
+ | "expired_window" | "internal_error" | "pool_exhausted";
 /** The Stripe-style error envelope every non-2xx response carries. */
 interface ErrorEnvelope {
     error: {
@@ -108,6 +204,8 @@ interface ErrorEnvelope {
     };
 }
 
+/** The API caps one `POST /v1/feedback` call at 500 items. */
+declare const FEEDBACK_BATCH_MAX = 500;
 /** Is this a terminal solve status? */
 declare function isTerminal(status: SolveStatus): boolean;
 /** A `fetch` implementation. Defaults to the global `fetch`. */
@@ -138,7 +236,7 @@ interface WaitOptions {
     /** Abort the request. */
     signal?: AbortSignal;
 }
-/** Options for {@link NoneCap.solve}. */
+/** Options for {@link NoneCap.solve} and {@link SolveHandle.result}. */
 interface SolveHelperOptions {
     /**
      * Give up after this many milliseconds and throw {@link TimeoutError}.
@@ -148,6 +246,11 @@ interface SolveHelperOptions {
     /** Abort waiting. */
     signal?: AbortSignal;
 }
+/** Options for {@link NoneCap.solves.start}. */
+interface SolveStartOptions {
+    /** Abort the submission. */
+    signal?: AbortSignal;
+}
 /**
  * The NoneCap API client.
  *
@@ -169,6 +272,22 @@ declare class NoneCap {
         cancel: (id: string, options?: {
             signal?: AbortSignal;
         }) => Promise<Solve>;
+        /**
+         * Submit a solve and return a {@link SolveHandle} for it.
+         *
+         * Unlike {@link NoneCap.solve}, this returns as soon as the submission is
+         * accepted, so `handle.id` is available immediately. Use the handle to
+         * `cancel()` the solve or `await handle.result()` for the finished solve.
+         *
+         * ```ts
+         * const handle = await nc.solves.start({ type: "hcaptcha", sitekey, url });
+         * // ...later, e.g. on shutdown:
+         * await handle.cancel();
+         * // or wait for it:
+         * const { token } = await handle.result();
+         * ```
+         */
+        start: (params: SolveCreateParams, options?: SolveStartOptions) => Promise<SolveHandle>;
         /** Fetch one page of solves. */
         list: (params?: SolveListParams, options?: {
             signal?: AbortSignal;
@@ -184,6 +303,50 @@ declare class NoneCap {
             signal?: AbortSignal;
         }) => AsyncIterableIterator<Solve>;
     };
+    /**
+     * Report what your downstream target did with the tokens we minted.
+     *
+     * Feedback is free, own-solves-only, and idempotent per solve id: reporting
+     * the same solve again corrects the earlier verdict. Only `solved` solves can
+     * be reported, and only within the API's reporting window (~30 days from the
+     * solve; corrections to an already-reported solve are never re-gated by it).
+     */
+    readonly feedback: {
+        /**
+         * Report one solve's downstream outcome, returning the recorded feedback.
+         *
+         * Unlike {@link NoneCap.feedback.reportMany}, a rejected report throws:
+         * {@link NotFoundError} if the solve isn't yours or never minted a token,
+         * {@link ValidationError} if a field is wrong or the reporting window closed.
+         *
+         * ```ts
+         * await nc.feedback.report({ solve_id: solve.id, outcome: "rejected", reason: "..." });
+         * ```
+         */
+        report: (report: FeedbackReport, options?: {
+            signal?: AbortSignal;
+        }) => Promise<Feedback>;
+        /**
+         * Report many verdicts at once — the path to use at volume. Buffer verdicts
+         * as you learn them and flush them here.
+         *
+         * The call succeeds even when individual items are rejected: each is
+         * resolved on its own so one stale id never discards the rest. Check
+         * `failed` rather than relying on a thrown error.
+         *
+         * More than {@link FEEDBACK_BATCH_MAX} reports are split across sequential
+         * requests and merged into one result, in request order. An empty array is
+         * a no-op that returns an empty batch without a request.
+         *
+         * ```ts
+         * const batch = await nc.feedback.reportMany(buffer);
+         * if (batch.failed) console.warn(batch.results.filter((r) => r.status === "error"));
+         * ```
+         */
+        reportMany: (reports: readonly FeedbackReport[], options?: {
+            signal?: AbortSignal;
+        }) => Promise<FeedbackBatch>;
+    };
     /** Fetch your account, including the current credit balance. */
     me(options?: {
         signal?: AbortSignal;
@@ -194,9 +357,58 @@ declare class NoneCap {
      * Uses the server's long-poll under the hood and keeps polling until the
      * solve is terminal or `timeout` elapses. Throws {@link SolveFailedError} if
      * the solve fails/expires/is cancelled, or {@link TimeoutError} on timeout.
+     *
+     * This is sugar for `(await solves.start(params)).result(options)`. When you
+     * need to cancel the solve while it runs, use {@link NoneCap.solves.start}
+     * and keep the {@link SolveHandle}.
      */
     solve(params: SolveCreateParams, options?: SolveHelperOptions): Promise<Solve>;
 }
+/**
+ * A handle on a started solve, returned by {@link NoneCap.solves.start}.
+ *
+ * The handle is the cancellable lifecycle object for one solve. It is a plain
+ * object, not a promise: `await`ing it does nothing useful. Wait for the result
+ * with {@link SolveHandle.result}, and cancel with {@link SolveHandle.cancel}.
+ * You do not construct it yourself — `solves.start()` hands you one with `id`
+ * already resolved.
+ */
+declare class SolveHandle {
+    #private;
+    /** The id of the started solve, available as soon as `start()` resolved. */
+    readonly id: string;
+    constructor(client: NoneCap, solve: Solve);
+    /** The last-known solve state for this handle. */
+    get solve(): Solve;
+    /**
+     * Long-poll until the solve is terminal, returning the solved solve. Throws
+     * {@link SolveFailedError} if it fails/expires/is cancelled, or
+     * {@link TimeoutError} on timeout (with `solveId`/`solve` attached so you can
+     * still {@link SolveHandle.cancel} it).
+     *
+     * Memoizes the *terminal* outcome: once the solve actually finishes, every
+     * later call returns that same settled result. A {@link TimeoutError} is not
+     * memoized — it just means this wait gave up, so a later call (e.g. with a
+     * larger `timeout`) resumes polling. Concurrent calls share one in-flight
+     * poll, so they never issue duplicate requests. The first caller's
+     * `timeout`/`signal` drive the shared poll; a later call starts a fresh one.
+     */
+    result(options?: SolveHelperOptions): Promise<Solve>;
+    /**
+     * Cancel the solve. Cancelled solves are never charged, so this is for clean
+     * shutdown / freeing slots / stopping early, not cost protection.
+     *
+     * If the solve already reached a terminal state the API answers 409; that is
+     * not an error a caller cares about, so this swallows {@link ConflictError}
+     * and returns the current solve state instead. A cancel that lands on a
+     * terminal state (cancelled, or whatever the 409-swallow read back) settles
+     * this handle's {@link SolveHandle.result}, so any in-flight or later wait
+     * stops polling and reflects that terminal state.
+     */
+    cancel(options?: {
+        signal?: AbortSignal;
+    }): Promise<Solve>;
+}
 
 /**
  * Base class for every error this library throws. Catch `NoneCapError` to
@@ -251,8 +463,24 @@ declare class SolveFailedError extends NoneCapError {
     readonly solve: Solve;
     constructor(solve: Solve);
 }
-/** Thrown by {@link NoneCap.solve} when the client-side timeout elapses first. */
+/**
+ * Thrown by {@link NoneCap.solve} (and {@link SolveHandle.result}) when the
+ * client-side timeout elapses first. When the timeout came from waiting on a
+ * solve, `solveId` and the last-known `solve` are attached so you can still
+ * cancel the in-flight solve. They are `undefined` for transport-level timeouts.
+ */
 declare class TimeoutError extends NoneCapError {
+    /** The id of the in-flight solve, when the timeout came from a solve wait. */
+    readonly solveId: string | undefined;
+    /** The last-known solve state, so you can cancel it after a wait timed out. */
+    readonly solve: Solve | undefined;
+    constructor(message: string, opts?: {
+        code?: ErrorCode;
+        status?: number;
+        param?: string | null;
+        solveId?: string;
+        solve?: Solve;
+    });
 }
 
-export { APIError, type Account, AuthenticationError, ConflictError, ConnectionError, type ErrorCode, type ErrorEnvelope, type FetchLike, InsufficientCreditsError, NoneCap, NoneCapError, type NoneCapOptions, NotFoundError, PermissionError, type Proxy, RateLimitError, type Solve, type SolveCreateParams, type SolveError, SolveFailedError, type SolveHelperOptions, type SolveList, type SolveListParams, type SolveStatus, type SolveType, TimeoutError, ValidationError, type WaitOptions, isTerminal };
+export { APIError, type Account, AuthenticationError, ConflictError, ConnectionError, type ErrorCode, type ErrorEnvelope, FEEDBACK_BATCH_MAX, type Feedback, type FeedbackBatch, type FeedbackOutcome, type FeedbackReport, type FeedbackResult, type FeedbackStatus, type FetchLike, InsufficientCreditsError, NoneCap, NoneCapError, type NoneCapOptions, NotFoundError, PermissionError, type Proxy, RateLimitError, type Solve, type SolveCreateParams, type SolveError, SolveFailedError, SolveHandle, type SolveHelperOptions, type SolveList, type SolveListParams, type SolveStartOptions, type SolveStatus, type SolveType, TimeoutError, ValidationError, type WaitOptions, isTerminal };