nonecap 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,255 @@
+/**
+ * Wire types for the NoneCap API. Field names are snake_case to match the JSON
+ * on the wire exactly, so what you read in the docs is what you write in code.
+ */
+/** Captcha type a solve targets. */
+type SolveType = "hcaptcha" | "hcaptcha_enterprise";
+/** Lifecycle of a solve. `solved` and `failed`/`expired`/`cancelled` are terminal. */
+type SolveStatus = "pending" | "solving" | "solved" | "failed" | "cancelled" | "expired";
+/** A proxy the solve should egress through. */
+interface Proxy {
+    scheme?: string;
+    host?: string;
+    port?: string | number;
+    username?: string;
+    password?: string;
+}
+/** Fields common to every solve submission. */
+interface SolveCreateBase {
+    /** The captcha's sitekey. */
+    sitekey: string;
+    /** The page URL the captcha is served on. */
+    url: string;
+    /** User agent to present to the captcha. */
+    user_agent?: string;
+    /** Proxy to route the solve through, as a structured object or a URL string. */
+    proxy?: Proxy | string;
+    /** URL to POST the solve to when it reaches a terminal state. */
+    webhook_url?: string;
+}
+/**
+ * Parameters for {@link NoneCap.solves.create} and {@link NoneCap.solve}.
+ *
+ * Modeled as a discriminated union on `type`: `rqdata` is optional for
+ * `hcaptcha` but required for `hcaptcha_enterprise`, enforced at compile time.
+ */
+type SolveCreateParams = (SolveCreateBase & {
+    type: "hcaptcha";
+    rqdata?: string;
+}) | (SolveCreateBase & {
+    type: "hcaptcha_enterprise";
+    rqdata: string;
+});
+/** The error attached to a solve that did not succeed. */
+interface SolveError {
+    code: string;
+    message: string;
+}
+/** A solve resource. */
+interface Solve {
+    id: string;
+    object: "solve";
+    type: SolveType;
+    status: SolveStatus;
+    sitekey: string;
+    url: string;
+    /** The captcha token once `status === "solved"`, otherwise null. */
+    token: string | null;
+    /** Set when the solve did not succeed, otherwise null. */
+    error: SolveError | null;
+    /** Credits charged for this solve. Only successful solves are charged. */
+    credits_charged: number | null;
+    /** Bytes that egressed through the metered proxy, or null if none was used. */
+    proxy_bytes: number | null;
+    created_at: string;
+    started_at: string | null;
+    finished_at: string | null;
+    /** Milliseconds the solve waited in the queue before a worker picked it up. */
+    queue_ms: number | null;
+    /** Milliseconds of actual solving. */
+    resolve_ms: number | null;
+}
+/** Parameters for {@link NoneCap.solves.list}. */
+interface SolveListParams {
+    /** Page size, 1–100. Defaults to 20. */
+    limit?: number;
+    /** Return solves created after this solve id (cursor pagination). */
+    starting_after?: string;
+    /** Only solves with this status. */
+    status?: SolveStatus;
+    /** Only solves of this type. */
+    type?: SolveType;
+}
+/** One page of solves. */
+interface SolveList {
+    object: "list";
+    data: Solve[];
+    has_more: boolean;
+}
+/** Your account, including the current credit balance. */
+interface Account {
+    object: "account";
+    id: string;
+    email: string;
+    credits_balance: number;
+    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";
+/** The Stripe-style error envelope every non-2xx response carries. */
+interface ErrorEnvelope {
+    error: {
+        code: ErrorCode;
+        message: string;
+        param: string | null;
+    };
+}
+
+/** Is this a terminal solve status? */
+declare function isTerminal(status: SolveStatus): boolean;
+/** A `fetch` implementation. Defaults to the global `fetch`. */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** Options for constructing a {@link NoneCap} client. */
+interface NoneCapOptions {
+    /** Your NoneCap API key. Find it at https://dashboard.nonecap.com. */
+    apiKey: string;
+    /** Override the API base URL. Defaults to https://api.nonecap.com. */
+    baseURL?: string;
+    /**
+     * Per-request timeout in milliseconds for a single HTTP call. Defaults to
+     * 100000 (just above the 90s server long-poll). Note this bounds one HTTP
+     * round trip, not the whole {@link NoneCap.solve} wait — use the `timeout`
+     * option on `solve()` for that.
+     */
+    timeout?: number;
+    /** Inject a custom `fetch` (for testing, proxies, or non-standard runtimes). */
+    fetch?: FetchLike;
+}
+/** Per-call options for the long-polling endpoints. */
+interface WaitOptions {
+    /**
+     * Hold the connection open up to this many seconds (1–90) waiting for the
+     * solve to finish before responding. Omit to return immediately.
+     */
+    wait?: number;
+    /** Abort the request. */
+    signal?: AbortSignal;
+}
+/** Options for {@link NoneCap.solve}. */
+interface SolveHelperOptions {
+    /**
+     * Give up after this many milliseconds and throw {@link TimeoutError}.
+     * Defaults to 180000 (3 minutes).
+     */
+    timeout?: number;
+    /** Abort waiting. */
+    signal?: AbortSignal;
+}
+/**
+ * The NoneCap API client.
+ *
+ * ```ts
+ * const nc = new NoneCap({ apiKey: process.env.NONECAP_KEY! });
+ * const { token } = await nc.solve({ type: "hcaptcha", sitekey, url });
+ * ```
+ */
+declare class NoneCap {
+    #private;
+    constructor(options: NoneCapOptions);
+    /** Operations on solves. */
+    readonly solves: {
+        /** Submit a solve. Pass `{ wait }` to hold the connection until it finishes. */
+        create: (params: SolveCreateParams, options?: WaitOptions) => Promise<Solve>;
+        /** Fetch a solve by id. Pass `{ wait }` to long-poll until it finishes. */
+        retrieve: (id: string, options?: WaitOptions) => Promise<Solve>;
+        /** Cancel a pending or in-flight solve. */
+        cancel: (id: string, options?: {
+            signal?: AbortSignal;
+        }) => Promise<Solve>;
+        /** Fetch one page of solves. */
+        list: (params?: SolveListParams, options?: {
+            signal?: AbortSignal;
+        }) => Promise<SolveList>;
+        /**
+         * Iterate every solve across pages, newest first.
+         *
+         * ```ts
+         * for await (const solve of nc.solves.listAll()) { ... }
+         * ```
+         */
+        listAll: (params?: SolveListParams, options?: {
+            signal?: AbortSignal;
+        }) => AsyncIterableIterator<Solve>;
+    };
+    /** Fetch your account, including the current credit balance. */
+    me(options?: {
+        signal?: AbortSignal;
+    }): Promise<Account>;
+    /**
+     * Submit a solve and wait for it to finish, returning the solved solve.
+     *
+     * 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.
+     */
+    solve(params: SolveCreateParams, options?: SolveHelperOptions): Promise<Solve>;
+}
+
+/**
+ * Base class for every error this library throws. Catch `NoneCapError` to
+ * handle all of them, or catch a subclass to handle one kind.
+ */
+declare class NoneCapError extends Error {
+    /** Machine-readable error code from the API envelope, when there is one. */
+    readonly code: ErrorCode | undefined;
+    /** HTTP status, when the error came from a response. */
+    readonly status: number | undefined;
+    /** The request field that was rejected, for validation errors. */
+    readonly param: string | null;
+    constructor(message: string, opts?: {
+        code?: ErrorCode;
+        status?: number;
+        param?: string | null;
+    });
+}
+/** 401 — the API key is missing, malformed, or revoked. */
+declare class AuthenticationError extends NoneCapError {
+}
+/** 403 — the key is valid but not allowed to do this (scope or locked account). */
+declare class PermissionError extends NoneCapError {
+}
+/** 402 — the account is out of credits. */
+declare class InsufficientCreditsError extends NoneCapError {
+}
+/** 422 / 400 — the request was rejected. `param` names the offending field. */
+declare class ValidationError extends NoneCapError {
+}
+/** 404 — no such resource. */
+declare class NotFoundError extends NoneCapError {
+}
+/** 409 — the solve is already in a terminal state (e.g. cancelling a finished solve). */
+declare class ConflictError extends NoneCapError {
+}
+/** 429 — too many concurrent solves, or rate limited. Back off and retry. */
+declare class RateLimitError extends NoneCapError {
+}
+/** 5xx, or a response that wasn't the expected shape. */
+declare class APIError extends NoneCapError {
+}
+/** The request never reached the API (DNS, TCP, TLS, timeout, offline). */
+declare class ConnectionError extends NoneCapError {
+}
+/**
+ * Thrown by {@link NoneCap.solve} when a solve reaches a terminal state without
+ * a token: `failed`, `expired`, or `cancelled`. The full solve is attached so
+ * you can inspect `solve.error` and timings.
+ */
+declare class SolveFailedError extends NoneCapError {
+    readonly solve: Solve;
+    constructor(solve: Solve);
+}
+/** Thrown by {@link NoneCap.solve} when the client-side timeout elapses first. */
+declare class TimeoutError extends NoneCapError {
+}
+
+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 };

package/dist/index.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Wire types for the NoneCap API. Field names are snake_case to match the JSON
+ * on the wire exactly, so what you read in the docs is what you write in code.
+ */
+/** Captcha type a solve targets. */
+type SolveType = "hcaptcha" | "hcaptcha_enterprise";
+/** Lifecycle of a solve. `solved` and `failed`/`expired`/`cancelled` are terminal. */
+type SolveStatus = "pending" | "solving" | "solved" | "failed" | "cancelled" | "expired";
+/** A proxy the solve should egress through. */
+interface Proxy {
+    scheme?: string;
+    host?: string;
+    port?: string | number;
+    username?: string;
+    password?: string;
+}
+/** Fields common to every solve submission. */
+interface SolveCreateBase {
+    /** The captcha's sitekey. */
+    sitekey: string;
+    /** The page URL the captcha is served on. */
+    url: string;
+    /** User agent to present to the captcha. */
+    user_agent?: string;
+    /** Proxy to route the solve through, as a structured object or a URL string. */
+    proxy?: Proxy | string;
+    /** URL to POST the solve to when it reaches a terminal state. */
+    webhook_url?: string;
+}
+/**
+ * Parameters for {@link NoneCap.solves.create} and {@link NoneCap.solve}.
+ *
+ * Modeled as a discriminated union on `type`: `rqdata` is optional for
+ * `hcaptcha` but required for `hcaptcha_enterprise`, enforced at compile time.
+ */
+type SolveCreateParams = (SolveCreateBase & {
+    type: "hcaptcha";
+    rqdata?: string;
+}) | (SolveCreateBase & {
+    type: "hcaptcha_enterprise";
+    rqdata: string;
+});
+/** The error attached to a solve that did not succeed. */
+interface SolveError {
+    code: string;
+    message: string;
+}
+/** A solve resource. */
+interface Solve {
+    id: string;
+    object: "solve";
+    type: SolveType;
+    status: SolveStatus;
+    sitekey: string;
+    url: string;
+    /** The captcha token once `status === "solved"`, otherwise null. */
+    token: string | null;
+    /** Set when the solve did not succeed, otherwise null. */
+    error: SolveError | null;
+    /** Credits charged for this solve. Only successful solves are charged. */
+    credits_charged: number | null;
+    /** Bytes that egressed through the metered proxy, or null if none was used. */
+    proxy_bytes: number | null;
+    created_at: string;
+    started_at: string | null;
+    finished_at: string | null;
+    /** Milliseconds the solve waited in the queue before a worker picked it up. */
+    queue_ms: number | null;
+    /** Milliseconds of actual solving. */
+    resolve_ms: number | null;
+}
+/** Parameters for {@link NoneCap.solves.list}. */
+interface SolveListParams {
+    /** Page size, 1–100. Defaults to 20. */
+    limit?: number;
+    /** Return solves created after this solve id (cursor pagination). */
+    starting_after?: string;
+    /** Only solves with this status. */
+    status?: SolveStatus;
+    /** Only solves of this type. */
+    type?: SolveType;
+}
+/** One page of solves. */
+interface SolveList {
+    object: "list";
+    data: Solve[];
+    has_more: boolean;
+}
+/** Your account, including the current credit balance. */
+interface Account {
+    object: "account";
+    id: string;
+    email: string;
+    credits_balance: number;
+    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";
+/** The Stripe-style error envelope every non-2xx response carries. */
+interface ErrorEnvelope {
+    error: {
+        code: ErrorCode;
+        message: string;
+        param: string | null;
+    };
+}
+
+/** Is this a terminal solve status? */
+declare function isTerminal(status: SolveStatus): boolean;
+/** A `fetch` implementation. Defaults to the global `fetch`. */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** Options for constructing a {@link NoneCap} client. */
+interface NoneCapOptions {
+    /** Your NoneCap API key. Find it at https://dashboard.nonecap.com. */
+    apiKey: string;
+    /** Override the API base URL. Defaults to https://api.nonecap.com. */
+    baseURL?: string;
+    /**
+     * Per-request timeout in milliseconds for a single HTTP call. Defaults to
+     * 100000 (just above the 90s server long-poll). Note this bounds one HTTP
+     * round trip, not the whole {@link NoneCap.solve} wait — use the `timeout`
+     * option on `solve()` for that.
+     */
+    timeout?: number;
+    /** Inject a custom `fetch` (for testing, proxies, or non-standard runtimes). */
+    fetch?: FetchLike;
+}
+/** Per-call options for the long-polling endpoints. */
+interface WaitOptions {
+    /**
+     * Hold the connection open up to this many seconds (1–90) waiting for the
+     * solve to finish before responding. Omit to return immediately.
+     */
+    wait?: number;
+    /** Abort the request. */
+    signal?: AbortSignal;
+}
+/** Options for {@link NoneCap.solve}. */
+interface SolveHelperOptions {
+    /**
+     * Give up after this many milliseconds and throw {@link TimeoutError}.
+     * Defaults to 180000 (3 minutes).
+     */
+    timeout?: number;
+    /** Abort waiting. */
+    signal?: AbortSignal;
+}
+/**
+ * The NoneCap API client.
+ *
+ * ```ts
+ * const nc = new NoneCap({ apiKey: process.env.NONECAP_KEY! });
+ * const { token } = await nc.solve({ type: "hcaptcha", sitekey, url });
+ * ```
+ */
+declare class NoneCap {
+    #private;
+    constructor(options: NoneCapOptions);
+    /** Operations on solves. */
+    readonly solves: {
+        /** Submit a solve. Pass `{ wait }` to hold the connection until it finishes. */
+        create: (params: SolveCreateParams, options?: WaitOptions) => Promise<Solve>;
+        /** Fetch a solve by id. Pass `{ wait }` to long-poll until it finishes. */
+        retrieve: (id: string, options?: WaitOptions) => Promise<Solve>;
+        /** Cancel a pending or in-flight solve. */
+        cancel: (id: string, options?: {
+            signal?: AbortSignal;
+        }) => Promise<Solve>;
+        /** Fetch one page of solves. */
+        list: (params?: SolveListParams, options?: {
+            signal?: AbortSignal;
+        }) => Promise<SolveList>;
+        /**
+         * Iterate every solve across pages, newest first.
+         *
+         * ```ts
+         * for await (const solve of nc.solves.listAll()) { ... }
+         * ```
+         */
+        listAll: (params?: SolveListParams, options?: {
+            signal?: AbortSignal;
+        }) => AsyncIterableIterator<Solve>;
+    };
+    /** Fetch your account, including the current credit balance. */
+    me(options?: {
+        signal?: AbortSignal;
+    }): Promise<Account>;
+    /**
+     * Submit a solve and wait for it to finish, returning the solved solve.
+     *
+     * 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.
+     */
+    solve(params: SolveCreateParams, options?: SolveHelperOptions): Promise<Solve>;
+}
+
+/**
+ * Base class for every error this library throws. Catch `NoneCapError` to
+ * handle all of them, or catch a subclass to handle one kind.
+ */
+declare class NoneCapError extends Error {
+    /** Machine-readable error code from the API envelope, when there is one. */
+    readonly code: ErrorCode | undefined;
+    /** HTTP status, when the error came from a response. */
+    readonly status: number | undefined;
+    /** The request field that was rejected, for validation errors. */
+    readonly param: string | null;
+    constructor(message: string, opts?: {
+        code?: ErrorCode;
+        status?: number;
+        param?: string | null;
+    });
+}
+/** 401 — the API key is missing, malformed, or revoked. */
+declare class AuthenticationError extends NoneCapError {
+}
+/** 403 — the key is valid but not allowed to do this (scope or locked account). */
+declare class PermissionError extends NoneCapError {
+}
+/** 402 — the account is out of credits. */
+declare class InsufficientCreditsError extends NoneCapError {
+}
+/** 422 / 400 — the request was rejected. `param` names the offending field. */
+declare class ValidationError extends NoneCapError {
+}
+/** 404 — no such resource. */
+declare class NotFoundError extends NoneCapError {
+}
+/** 409 — the solve is already in a terminal state (e.g. cancelling a finished solve). */
+declare class ConflictError extends NoneCapError {
+}
+/** 429 — too many concurrent solves, or rate limited. Back off and retry. */
+declare class RateLimitError extends NoneCapError {
+}
+/** 5xx, or a response that wasn't the expected shape. */
+declare class APIError extends NoneCapError {
+}
+/** The request never reached the API (DNS, TCP, TLS, timeout, offline). */
+declare class ConnectionError extends NoneCapError {
+}
+/**
+ * Thrown by {@link NoneCap.solve} when a solve reaches a terminal state without
+ * a token: `failed`, `expired`, or `cancelled`. The full solve is attached so
+ * you can inspect `solve.error` and timings.
+ */
+declare class SolveFailedError extends NoneCapError {
+    readonly solve: Solve;
+    constructor(solve: Solve);
+}
+/** Thrown by {@link NoneCap.solve} when the client-side timeout elapses first. */
+declare class TimeoutError extends NoneCapError {
+}
+
+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 };