gatsbie 1.0.0

package/README.md

@@ -0,0 +1,61 @@
+# Gatsbie Node.js SDK
+
+Official Node.js/TypeScript SDK for the [Gatsbie Captcha API](https://gatsbie.io).
+
+## Installation
+
+```bash
+npm install gatsbie
+```
+
+## Quick Start
+
+```typescript
+import { Client } from "gatsbie";
+
+const client = new Client("gats_your_api_key");
+
+// Solve a Turnstile challenge
+const response = await client.solveTurnstile({
+  proxy: "http://user:pass@proxy:8080",
+  targetUrl: "https://example.com",
+  siteKey: "0x4AAAAAAABS7TtLxsNa7Z2e",
+});
+
+console.log(response.solution.token);
+```
+
+## Supported Captcha Types
+
+- **Datadome** - Device check and slider
+- **reCAPTCHA v3** - Including enterprise
+- **Akamai** - Bot management
+- **Vercel** - Bot protection
+- **Shape** - Antibot
+- **Cloudflare Turnstile** - Turnstile challenges
+- **Cloudflare WAF** - WAF challenges
+- **PerimeterX** - Invisible challenges
+
+## Error Handling
+
+```typescript
+import { Client, APIError } from "gatsbie";
+
+try {
+  const response = await client.solveTurnstile(request);
+} catch (err) {
+  if (err instanceof APIError) {
+    if (err.isAuthError()) {
+      console.log("Check your API key");
+    } else if (err.isInsufficientCredits()) {
+      console.log("Add more credits");
+    } else if (err.isSolveFailed()) {
+      console.log("Solve failed, try again");
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,265 @@
+/** Response from the health check endpoint. */
+interface HealthResponse {
+    status: string;
+}
+/** Generic response for successful captcha solves. */
+interface SolveResponse<T> {
+    success: boolean;
+    taskId: string;
+    service: string;
+    solution: T;
+    cost: number;
+    solveTime: number;
+}
+/** Solution for Datadome challenges. */
+interface DatadomeSolution {
+    datadome: string;
+    userAgent: string;
+}
+/** Solution for reCAPTCHA v3 challenges. */
+interface RecaptchaV3Solution {
+    token: string;
+    userAgent: string;
+}
+/** Solution for Akamai challenges. */
+interface AkamaiSolution {
+    abck: string;
+    bmSz: string;
+    userAgent: string;
+    country?: string;
+    usrLocale?: string;
+}
+/** Solution for Vercel challenges. */
+interface VercelSolution {
+    vcrcs: string;
+    userAgent: string;
+}
+/**
+ * Solution for Shape challenges.
+ * Shape uses dynamic header names that vary by site.
+ */
+interface ShapeSolution {
+    headers: Record<string, string>;
+    userAgent: string;
+}
+/** Solution for Cloudflare Turnstile challenges. */
+interface TurnstileSolution {
+    token: string;
+    userAgent: string;
+}
+/** PerimeterX cookies needed for requests. */
+interface PerimeterXCookies {
+    px3: string;
+    pxde: string;
+    pxvid: string;
+    pxcts: string;
+}
+/** Solution for PerimeterX challenges. */
+interface PerimeterXSolution {
+    cookies: PerimeterXCookies;
+    userAgent: string;
+}
+/** Solution for Cloudflare WAF challenges. */
+interface CloudflareWAFSolution {
+    cfClearance: string;
+    userAgent: string;
+}
+/** Solution for Datadome Slider challenges. */
+interface DatadomeSliderSolution {
+    datadome: string;
+    userAgent: string;
+}
+/** Request for solving Datadome device check challenges. */
+interface DatadomeRequest {
+    proxy: string;
+    targetUrl: string;
+    targetMethod?: string;
+}
+/** Request for solving reCAPTCHA v3 challenges. */
+interface RecaptchaV3Request {
+    proxy: string;
+    targetUrl: string;
+    siteKey: string;
+    action?: string;
+    title?: string;
+    enterprise?: boolean;
+}
+/** Request for solving Akamai challenges. */
+interface AkamaiRequest {
+    proxy: string;
+    targetUrl: string;
+    akamaiJsUrl: string;
+    pageFp?: string;
+}
+/** Request for solving Vercel challenges. */
+interface VercelRequest {
+    proxy: string;
+    targetUrl: string;
+}
+/** Request for solving Shape challenges. */
+interface ShapeRequest {
+    proxy: string;
+    targetUrl: string;
+    targetApi: string;
+    shapeJsUrl: string;
+    title: string;
+    method: string;
+}
+/** Request for solving Cloudflare Turnstile challenges. */
+interface TurnstileRequest {
+    proxy: string;
+    targetUrl: string;
+    siteKey: string;
+}
+/** Request for solving PerimeterX challenges. */
+interface PerimeterXRequest {
+    proxy: string;
+    targetUrl: string;
+    perimeterxJsUrl: string;
+    pxAppId: string;
+}
+/** Request for solving Cloudflare WAF challenges. */
+interface CloudflareWAFRequest {
+    proxy: string;
+    targetUrl: string;
+    targetMethod?: string;
+}
+/** Request for solving Datadome Slider challenges. */
+interface DatadomeSliderRequest {
+    proxy: string;
+    targetUrl: string;
+    targetMethod?: string;
+}
+/** Options for configuring the Gatsbie client. */
+interface ClientOptions {
+    /** Custom base URL for the API. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 120000). */
+    timeout?: number;
+}
+
+/**
+ * Gatsbie API client.
+ *
+ * @example
+ * ```typescript
+ * const client = new Client("gats_your_api_key");
+ *
+ * const response = await client.solveTurnstile({
+ *   proxy: "http://user:pass@proxy:8080",
+ *   targetUrl: "https://example.com",
+ *   siteKey: "0x4AAAAAAABS7TtLxsNa7Z2e",
+ * });
+ *
+ * console.log(response.solution.token);
+ * ```
+ */
+declare class Client {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    /**
+     * Create a new Gatsbie API client.
+     *
+     * @param apiKey - Your Gatsbie API key (should start with 'gats_').
+     * @param options - Optional client configuration.
+     */
+    constructor(apiKey: string, options?: ClientOptions);
+    private request;
+    /**
+     * Check the API server health status.
+     */
+    health(): Promise<HealthResponse>;
+    /**
+     * Solve a Datadome device check challenge.
+     */
+    solveDatadome(request: DatadomeRequest): Promise<SolveResponse<DatadomeSolution>>;
+    /**
+     * Solve a reCAPTCHA v3 challenge.
+     */
+    solveRecaptchaV3(request: RecaptchaV3Request): Promise<SolveResponse<RecaptchaV3Solution>>;
+    /**
+     * Solve an Akamai bot management challenge.
+     */
+    solveAkamai(request: AkamaiRequest): Promise<SolveResponse<AkamaiSolution>>;
+    /**
+     * Solve a Vercel bot protection challenge.
+     */
+    solveVercel(request: VercelRequest): Promise<SolveResponse<VercelSolution>>;
+    /**
+     * Solve a Shape antibot challenge.
+     */
+    solveShape(request: ShapeRequest): Promise<SolveResponse<ShapeSolution>>;
+    /**
+     * Solve a Cloudflare Turnstile challenge.
+     */
+    solveTurnstile(request: TurnstileRequest): Promise<SolveResponse<TurnstileSolution>>;
+    /**
+     * Solve a PerimeterX Invisible challenge.
+     */
+    solvePerimeterX(request: PerimeterXRequest): Promise<SolveResponse<PerimeterXSolution>>;
+    /**
+     * Solve a Cloudflare WAF challenge.
+     */
+    solveCloudflareWAF(request: CloudflareWAFRequest): Promise<SolveResponse<CloudflareWAFSolution>>;
+    /**
+     * Solve a Datadome Slider CAPTCHA challenge.
+     */
+    solveDatadomeSlider(request: DatadomeSliderRequest): Promise<SolveResponse<DatadomeSliderSolution>>;
+}
+
+/**
+ * Error codes returned by the Gatsbie API.
+ */
+declare const ErrorCode: {
+    readonly AUTH_FAILED: "AUTH_FAILED";
+    readonly INSUFFICIENT_CREDITS: "INSUFFICIENT_CREDITS";
+    readonly INVALID_REQUEST: "INVALID_REQUEST";
+    readonly UPSTREAM_ERROR: "UPSTREAM_ERROR";
+    readonly SOLVE_FAILED: "SOLVE_FAILED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/**
+ * Base error class for Gatsbie SDK errors.
+ */
+declare class GatsbieError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when the Gatsbie API returns an error response.
+ */
+declare class APIError extends GatsbieError {
+    readonly code: string;
+    readonly details?: string;
+    readonly timestamp?: number;
+    readonly httpStatus?: number;
+    constructor(options: {
+        code: string;
+        message: string;
+        details?: string;
+        timestamp?: number;
+        httpStatus?: number;
+    });
+    /** Check if this is an authentication error. */
+    isAuthError(): boolean;
+    /** Check if this error is due to insufficient credits. */
+    isInsufficientCredits(): boolean;
+    /** Check if this error is due to an invalid request. */
+    isInvalidRequest(): boolean;
+    /** Check if this error is from an upstream service. */
+    isUpstreamError(): boolean;
+    /** Check if the captcha solving failed. */
+    isSolveFailed(): boolean;
+    /** Check if this is an internal server error. */
+    isInternalError(): boolean;
+}
+/**
+ * Error thrown when a request fails (network error, timeout, etc.).
+ */
+declare class RequestError extends GatsbieError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+
+export { APIError, type AkamaiRequest, type AkamaiSolution, Client, type ClientOptions, type CloudflareWAFRequest, type CloudflareWAFSolution, type DatadomeRequest, type DatadomeSliderRequest, type DatadomeSliderSolution, type DatadomeSolution, ErrorCode, GatsbieError, type HealthResponse, type PerimeterXCookies, type PerimeterXRequest, type PerimeterXSolution, type RecaptchaV3Request, type RecaptchaV3Solution, RequestError, type ShapeRequest, type ShapeSolution, type SolveResponse, type TurnstileRequest, type TurnstileSolution, type VercelRequest, type VercelSolution };

package/dist/index.d.ts

@@ -0,0 +1,265 @@
+/** Response from the health check endpoint. */
+interface HealthResponse {
+    status: string;
+}
+/** Generic response for successful captcha solves. */
+interface SolveResponse<T> {
+    success: boolean;
+    taskId: string;
+    service: string;
+    solution: T;
+    cost: number;
+    solveTime: number;
+}
+/** Solution for Datadome challenges. */
+interface DatadomeSolution {
+    datadome: string;
+    userAgent: string;
+}
+/** Solution for reCAPTCHA v3 challenges. */
+interface RecaptchaV3Solution {
+    token: string;
+    userAgent: string;
+}
+/** Solution for Akamai challenges. */
+interface AkamaiSolution {
+    abck: string;
+    bmSz: string;
+    userAgent: string;
+    country?: string;
+    usrLocale?: string;
+}
+/** Solution for Vercel challenges. */
+interface VercelSolution {
+    vcrcs: string;
+    userAgent: string;
+}
+/**
+ * Solution for Shape challenges.
+ * Shape uses dynamic header names that vary by site.
+ */
+interface ShapeSolution {
+    headers: Record<string, string>;
+    userAgent: string;
+}
+/** Solution for Cloudflare Turnstile challenges. */
+interface TurnstileSolution {
+    token: string;
+    userAgent: string;
+}
+/** PerimeterX cookies needed for requests. */
+interface PerimeterXCookies {
+    px3: string;
+    pxde: string;
+    pxvid: string;
+    pxcts: string;
+}
+/** Solution for PerimeterX challenges. */
+interface PerimeterXSolution {
+    cookies: PerimeterXCookies;
+    userAgent: string;
+}
+/** Solution for Cloudflare WAF challenges. */
+interface CloudflareWAFSolution {
+    cfClearance: string;
+    userAgent: string;
+}
+/** Solution for Datadome Slider challenges. */
+interface DatadomeSliderSolution {
+    datadome: string;
+    userAgent: string;
+}
+/** Request for solving Datadome device check challenges. */
+interface DatadomeRequest {
+    proxy: string;
+    targetUrl: string;
+    targetMethod?: string;
+}
+/** Request for solving reCAPTCHA v3 challenges. */
+interface RecaptchaV3Request {
+    proxy: string;
+    targetUrl: string;
+    siteKey: string;
+    action?: string;
+    title?: string;
+    enterprise?: boolean;
+}
+/** Request for solving Akamai challenges. */
+interface AkamaiRequest {
+    proxy: string;
+    targetUrl: string;
+    akamaiJsUrl: string;
+    pageFp?: string;
+}
+/** Request for solving Vercel challenges. */
+interface VercelRequest {
+    proxy: string;
+    targetUrl: string;
+}
+/** Request for solving Shape challenges. */
+interface ShapeRequest {
+    proxy: string;
+    targetUrl: string;
+    targetApi: string;
+    shapeJsUrl: string;
+    title: string;
+    method: string;
+}
+/** Request for solving Cloudflare Turnstile challenges. */
+interface TurnstileRequest {
+    proxy: string;
+    targetUrl: string;
+    siteKey: string;
+}
+/** Request for solving PerimeterX challenges. */
+interface PerimeterXRequest {
+    proxy: string;
+    targetUrl: string;
+    perimeterxJsUrl: string;
+    pxAppId: string;
+}
+/** Request for solving Cloudflare WAF challenges. */
+interface CloudflareWAFRequest {
+    proxy: string;
+    targetUrl: string;
+    targetMethod?: string;
+}
+/** Request for solving Datadome Slider challenges. */
+interface DatadomeSliderRequest {
+    proxy: string;
+    targetUrl: string;
+    targetMethod?: string;
+}
+/** Options for configuring the Gatsbie client. */
+interface ClientOptions {
+    /** Custom base URL for the API. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 120000). */
+    timeout?: number;
+}
+
+/**
+ * Gatsbie API client.
+ *
+ * @example
+ * ```typescript
+ * const client = new Client("gats_your_api_key");
+ *
+ * const response = await client.solveTurnstile({
+ *   proxy: "http://user:pass@proxy:8080",
+ *   targetUrl: "https://example.com",
+ *   siteKey: "0x4AAAAAAABS7TtLxsNa7Z2e",
+ * });
+ *
+ * console.log(response.solution.token);
+ * ```
+ */
+declare class Client {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    /**
+     * Create a new Gatsbie API client.
+     *
+     * @param apiKey - Your Gatsbie API key (should start with 'gats_').
+     * @param options - Optional client configuration.
+     */
+    constructor(apiKey: string, options?: ClientOptions);
+    private request;
+    /**
+     * Check the API server health status.
+     */
+    health(): Promise<HealthResponse>;
+    /**
+     * Solve a Datadome device check challenge.
+     */
+    solveDatadome(request: DatadomeRequest): Promise<SolveResponse<DatadomeSolution>>;
+    /**
+     * Solve a reCAPTCHA v3 challenge.
+     */
+    solveRecaptchaV3(request: RecaptchaV3Request): Promise<SolveResponse<RecaptchaV3Solution>>;
+    /**
+     * Solve an Akamai bot management challenge.
+     */
+    solveAkamai(request: AkamaiRequest): Promise<SolveResponse<AkamaiSolution>>;
+    /**
+     * Solve a Vercel bot protection challenge.
+     */
+    solveVercel(request: VercelRequest): Promise<SolveResponse<VercelSolution>>;
+    /**
+     * Solve a Shape antibot challenge.
+     */
+    solveShape(request: ShapeRequest): Promise<SolveResponse<ShapeSolution>>;
+    /**
+     * Solve a Cloudflare Turnstile challenge.
+     */
+    solveTurnstile(request: TurnstileRequest): Promise<SolveResponse<TurnstileSolution>>;
+    /**
+     * Solve a PerimeterX Invisible challenge.
+     */
+    solvePerimeterX(request: PerimeterXRequest): Promise<SolveResponse<PerimeterXSolution>>;
+    /**
+     * Solve a Cloudflare WAF challenge.
+     */
+    solveCloudflareWAF(request: CloudflareWAFRequest): Promise<SolveResponse<CloudflareWAFSolution>>;
+    /**
+     * Solve a Datadome Slider CAPTCHA challenge.
+     */
+    solveDatadomeSlider(request: DatadomeSliderRequest): Promise<SolveResponse<DatadomeSliderSolution>>;
+}
+
+/**
+ * Error codes returned by the Gatsbie API.
+ */
+declare const ErrorCode: {
+    readonly AUTH_FAILED: "AUTH_FAILED";
+    readonly INSUFFICIENT_CREDITS: "INSUFFICIENT_CREDITS";
+    readonly INVALID_REQUEST: "INVALID_REQUEST";
+    readonly UPSTREAM_ERROR: "UPSTREAM_ERROR";
+    readonly SOLVE_FAILED: "SOLVE_FAILED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/**
+ * Base error class for Gatsbie SDK errors.
+ */
+declare class GatsbieError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when the Gatsbie API returns an error response.
+ */
+declare class APIError extends GatsbieError {
+    readonly code: string;
+    readonly details?: string;
+    readonly timestamp?: number;
+    readonly httpStatus?: number;
+    constructor(options: {
+        code: string;
+        message: string;
+        details?: string;
+        timestamp?: number;
+        httpStatus?: number;
+    });
+    /** Check if this is an authentication error. */
+    isAuthError(): boolean;
+    /** Check if this error is due to insufficient credits. */
+    isInsufficientCredits(): boolean;
+    /** Check if this error is due to an invalid request. */
+    isInvalidRequest(): boolean;
+    /** Check if this error is from an upstream service. */
+    isUpstreamError(): boolean;
+    /** Check if the captcha solving failed. */
+    isSolveFailed(): boolean;
+    /** Check if this is an internal server error. */
+    isInternalError(): boolean;
+}
+/**
+ * Error thrown when a request fails (network error, timeout, etc.).
+ */
+declare class RequestError extends GatsbieError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+
+export { APIError, type AkamaiRequest, type AkamaiSolution, Client, type ClientOptions, type CloudflareWAFRequest, type CloudflareWAFSolution, type DatadomeRequest, type DatadomeSliderRequest, type DatadomeSliderSolution, type DatadomeSolution, ErrorCode, GatsbieError, type HealthResponse, type PerimeterXCookies, type PerimeterXRequest, type PerimeterXSolution, type RecaptchaV3Request, type RecaptchaV3Solution, RequestError, type ShapeRequest, type ShapeSolution, type SolveResponse, type TurnstileRequest, type TurnstileSolution, type VercelRequest, type VercelSolution };