@getabrain/sdk 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @getabrain/sdk
+
+Official Node/TypeScript SDK for [GetABrain.ai](https://getabrain.ai) — real human judgment as an API.
+
+## Install
+
+```bash
+npm install @getabrain/sdk
+```
+
+## Quickstart
+
+```ts
+import { GetABrain } from '@getabrain/sdk'
+
+const gab = new GetABrain({ apiKey: 'gab_k_…', apiSecret: 'gab_s_…' })
+
+// Submit a question (returns immediately)
+const query = await gab.queries.create({
+  type: 'ab_test',
+  title: 'Which headline converts better?',
+  content_data: {
+    question: 'Which is more compelling?',
+    variant_a: { description: 'Save 20% today' },
+    variant_b: { description: 'Your future self will thank you' },
+  },
+  required_responses: 5,
+  bid_amount_cents: 25,
+})
+
+// Wait for humans to answer (polls for you)
+const responses = await gab.queries.waitForResponses(query.id, { minResponses: 5 })
+console.log(responses.map((r) => r.response_data))
+```
+
+## Errors
+
+```ts
+import { InsufficientBalanceError, RateLimitError } from '@getabrain/sdk'
+
+try {
+  await gab.queries.create(/* … */)
+} catch (e) {
+  if (e instanceof InsufficientBalanceError) {
+    // top up your balance at https://getabrain.ai
+  }
+}
+```
+
+## API
+
+- `gab.queries.create(input)` / `.get(id)` / `.list({ status?, limit?, offset? })` / `.cancel(id)`
+- `gab.queries.waitForResponses(id, { minResponses, timeoutMs?, pollIntervalMs? })`
+- `gab.responses.rate(queryId, responseId, { score, feedback_text? })` / `.getRating(queryId, responseId)`
+- `gab.account.stats()` / `.balance()`
+
+Full reference: https://getabrain.ai/docs/api
+
+> The SDK types the **13 first-class query types**. Two legacy types (`custom`, `headline_test`) exist server-side but are deprecated and intentionally not typed by the SDK — use a first-class type instead.

package/dist/index.cjs

@@ -0,0 +1,292 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AccountResource: () => AccountResource,
+  AuthError: () => AuthError,
+  ConflictError: () => ConflictError,
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  ForbiddenError: () => ForbiddenError,
+  GetABrain: () => GetABrain,
+  GetABrainError: () => GetABrainError,
+  InsufficientBalanceError: () => InsufficientBalanceError,
+  NetworkError: () => NetworkError,
+  NotFoundError: () => NotFoundError,
+  QUERY_TYPES: () => QUERY_TYPES,
+  QueriesResource: () => QueriesResource,
+  RateLimitError: () => RateLimitError,
+  ResponsesResource: () => ResponsesResource,
+  ServerError: () => ServerError,
+  TimeoutError: () => TimeoutError,
+  ValidationError: () => ValidationError,
+  errorFromResponse: () => errorFromResponse
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var GetABrainError = class extends Error {
+  constructor(message, status, code = "error", requestId) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+    this.name = new.target.name;
+  }
+};
+var ValidationError = class extends GetABrainError {
+};
+var AuthError = class extends GetABrainError {
+};
+var InsufficientBalanceError = class extends GetABrainError {
+};
+var ForbiddenError = class extends GetABrainError {
+};
+var NotFoundError = class extends GetABrainError {
+};
+var ConflictError = class extends GetABrainError {
+};
+var ServerError = class extends GetABrainError {
+};
+var RateLimitError = class extends GetABrainError {
+  constructor(message, status, code, retryAfterMs, requestId) {
+    super(message, status, code, requestId);
+    this.retryAfterMs = retryAfterMs;
+  }
+};
+var TimeoutError = class extends GetABrainError {
+  constructor(message = "Request timed out") {
+    super(message, 0, "timeout");
+  }
+};
+var NetworkError = class extends GetABrainError {
+  constructor(message = "Network request failed") {
+    super(message, 0, "network");
+  }
+};
+function errorFromResponse(status, body, retryAfterMs) {
+  const message = body && body.message || body && body.error || `HTTP ${status}`;
+  const code = body && body.error || "error";
+  switch (status) {
+    case 400:
+      return new ValidationError(message, status, code);
+    case 401:
+      return new AuthError(message, status, code);
+    case 402:
+      return new InsufficientBalanceError(message, status, code);
+    case 403:
+      return new ForbiddenError(message, status, code);
+    case 404:
+      return new NotFoundError(message, status, code);
+    case 409:
+      return new ConflictError(message, status, code);
+    case 429:
+      return new RateLimitError(message, status, code, retryAfterMs);
+    default:
+      if (status >= 500) return new ServerError(message, status, code);
+      return new GetABrainError(message, status, code);
+  }
+}
+
+// src/http.ts
+var DEFAULT_BASE_URL = "https://www.getabrain.ai/api/v1";
+var realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function createTransport(config) {
+  var _a, _b, _c, _d, _e;
+  const baseUrl = ((_a = config.baseUrl) != null ? _a : DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const doFetch = (_b = config.fetch) != null ? _b : globalThis.fetch;
+  const timeoutMs = (_c = config.timeoutMs) != null ? _c : 3e4;
+  const maxRetries = (_d = config.maxRetries) != null ? _d : 2;
+  const sleep = (_e = config.sleep) != null ? _e : realSleep;
+  if (typeof doFetch !== "function") {
+    throw new GetABrainError("No fetch available \u2014 use Node 18+ or pass { fetch }", 0, "config");
+  }
+  return async function request(method, path, opts = {}) {
+    const url = new URL(baseUrl + path);
+    if (opts.query) {
+      for (const [k, v] of Object.entries(opts.query)) if (v !== void 0) url.searchParams.set(k, String(v));
+    }
+    const isRead = method.toUpperCase() === "GET";
+    let attempt = 0;
+    for (; ; ) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      let res;
+      try {
+        res = await doFetch(url.toString(), {
+          method,
+          headers: { "X-API-Key": config.apiKey, "X-API-Secret": config.apiSecret, "Content-Type": "application/json" },
+          body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0,
+          signal: controller.signal
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        if ((err == null ? void 0 : err.name) === "AbortError") throw new TimeoutError();
+        if (isRead && attempt < maxRetries) {
+          attempt++;
+          await sleep(backoff(attempt));
+          continue;
+        }
+        throw new NetworkError((err == null ? void 0 : err.message) || "fetch failed");
+      }
+      clearTimeout(timer);
+      if (res.ok) {
+        if (res.status === 204) return void 0;
+        return await res.json();
+      }
+      const retryAfterMs = parseRetryAfter(res.headers.get("retry-after"));
+      if (isRead && (res.status === 429 || res.status >= 500) && attempt < maxRetries) {
+        attempt++;
+        await sleep(retryAfterMs != null ? retryAfterMs : backoff(attempt));
+        continue;
+      }
+      let body = null;
+      try {
+        body = await res.json();
+      } catch (e) {
+      }
+      throw errorFromResponse(res.status, body, retryAfterMs);
+    }
+  };
+}
+function backoff(attempt) {
+  return Math.min(1e3 * 2 ** (attempt - 1), 8e3);
+}
+function parseRetryAfter(h) {
+  if (!h) return void 0;
+  const n = Number(h);
+  return Number.isFinite(n) ? n * 1e3 : void 0;
+}
+
+// src/resources/queries.ts
+var TERMINAL = /* @__PURE__ */ new Set(["completed", "cancelled", "failed", "expired"]);
+var realSleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+var QueriesResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  create(input) {
+    return this.request("POST", "/requestor/queries", { body: input });
+  }
+  get(id) {
+    return this.request("GET", `/requestor/queries/${encodeURIComponent(id)}`);
+  }
+  list(params = {}) {
+    return this.request("GET", "/requestor/queries", { query: { status: params.status, limit: params.limit, offset: params.offset } });
+  }
+  cancel(id) {
+    return this.request("PUT", `/requestor/queries/${encodeURIComponent(id)}`, { body: { action: "cancel" } });
+  }
+  // Poll until `minResponses` responses arrive, the query reaches a terminal
+  // status, or the timeout elapses (throws TimeoutError).
+  async waitForResponses(id, opts) {
+    var _a, _b, _c, _d, _e, _f;
+    const timeoutMs = (_a = opts.timeoutMs) != null ? _a : 6e5;
+    const pollIntervalMs = (_b = opts.pollIntervalMs) != null ? _b : 5e3;
+    const sleep = (_c = opts.sleep) != null ? _c : realSleep2;
+    const now = (_d = opts.now) != null ? _d : Date.now;
+    const deadline = now() + timeoutMs;
+    for (; ; ) {
+      const query = await this.get(id);
+      const responses = (_e = query.responses) != null ? _e : [];
+      if (((_f = query.completed_responses) != null ? _f : responses.length) >= opts.minResponses) return responses;
+      if (TERMINAL.has(query.status)) return responses;
+      if (now() >= deadline) throw new TimeoutError(`waitForResponses timed out after ${timeoutMs}ms for query ${id}`);
+      await sleep(pollIntervalMs);
+    }
+  }
+};
+
+// src/resources/responses.ts
+var ResponsesResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  rate(queryId, responseId, input) {
+    const q = encodeURIComponent(queryId);
+    const r = encodeURIComponent(responseId);
+    return this.request("POST", `/requestor/queries/${q}/responses/${r}/rate`, { body: input });
+  }
+  getRating(queryId, responseId) {
+    const q = encodeURIComponent(queryId);
+    const r = encodeURIComponent(responseId);
+    return this.request("GET", `/requestor/queries/${q}/responses/${r}/rate`);
+  }
+};
+
+// src/resources/account.ts
+var AccountResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  stats() {
+    return this.request("GET", "/requestor/stats");
+  }
+  balance() {
+    return this.request("GET", "/requestor/billing");
+  }
+};
+
+// src/client.ts
+var GetABrain = class {
+  constructor(config) {
+    const request = createTransport(config);
+    this.queries = new QueriesResource(request);
+    this.responses = new ResponsesResource(request);
+    this.account = new AccountResource(request);
+  }
+};
+
+// src/types.ts
+var QUERY_TYPES = [
+  "text",
+  "multiple_choice",
+  "rating_scale",
+  "image_comparison",
+  "ranking",
+  "yes_no",
+  "sentiment",
+  "image_selection",
+  "free_form_text",
+  "video_review",
+  "audio_review",
+  "image_analysis",
+  "ab_test"
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AccountResource,
+  AuthError,
+  ConflictError,
+  DEFAULT_BASE_URL,
+  ForbiddenError,
+  GetABrain,
+  GetABrainError,
+  InsufficientBalanceError,
+  NetworkError,
+  NotFoundError,
+  QUERY_TYPES,
+  QueriesResource,
+  RateLimitError,
+  ResponsesResource,
+  ServerError,
+  TimeoutError,
+  ValidationError,
+  errorFromResponse
+});

package/dist/index.d.cts

@@ -0,0 +1,329 @@
+declare const DEFAULT_BASE_URL = "https://www.getabrain.ai/api/v1";
+interface TransportConfig {
+    apiKey: string;
+    apiSecret: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    maxRetries?: number;
+    /** Injectable for deterministic tests; defaults to real setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+}
+interface RequestOptions {
+    body?: unknown;
+    query?: Record<string, string | number | undefined>;
+}
+type RequestFn = <T = any>(method: string, path: string, opts?: RequestOptions) => Promise<T>;
+
+declare const QUERY_TYPES: readonly ["text", "multiple_choice", "rating_scale", "image_comparison", "ranking", "yes_no", "sentiment", "image_selection", "free_form_text", "video_review", "audio_review", "image_analysis", "ab_test"];
+type QueryType = (typeof QUERY_TYPES)[number];
+interface SharedContent {
+    question: string;
+    instructions?: string;
+    context?: string;
+}
+interface TextContent extends SharedContent {
+    min_words?: number;
+    max_words?: number;
+}
+interface MultipleChoiceContent extends SharedContent {
+    options: {
+        id: string;
+        text: string;
+        image_url?: string;
+    }[];
+    allow_multiple?: boolean;
+    min_selections?: number;
+    max_selections?: number;
+}
+interface RatingScaleContent extends SharedContent {
+    scale_type: '1-5' | '1-10' | '0-100' | 'stars';
+    scale_min: number;
+    scale_max: number;
+    scale_labels?: {
+        min_label?: string;
+        mid_label?: string;
+        max_label?: string;
+    };
+    criteria?: string[];
+}
+interface ImageComparisonContent extends SharedContent {
+    images: {
+        id: string;
+        url: string;
+        label?: string;
+        description?: string;
+    }[];
+    comparison_type: 'preference' | 'quality' | 'relevance' | 'custom';
+    require_reasoning?: boolean;
+}
+interface RankingContent extends SharedContent {
+    items: {
+        id: string;
+        text: string;
+        image_url?: string;
+        description?: string;
+    }[];
+    max_items: number;
+    require_all?: boolean;
+}
+interface YesNoContent extends SharedContent {
+    require_explanation?: boolean;
+    min_explanation_words?: number;
+}
+interface SentimentContent extends SharedContent {
+    subject: string;
+    sentiment_options: ('very_positive' | 'positive' | 'neutral' | 'negative' | 'very_negative')[];
+    require_reasoning?: boolean;
+}
+interface ImageSelectionContent extends SharedContent {
+    images: {
+        id: string;
+        url: string;
+        caption?: string;
+    }[];
+    min_selections: number;
+    max_selections: number;
+    selection_criteria: string;
+}
+interface FreeFormTextContent extends SharedContent {
+    prompt: string;
+    min_characters?: number;
+    max_characters?: number;
+    format_guidelines?: string;
+}
+interface VideoReviewContent extends SharedContent {
+    video_url: string;
+    video_duration_seconds: number;
+    review_aspects: string[];
+    min_watch_time_seconds?: number;
+}
+interface AudioReviewContent extends SharedContent {
+    audio_url: string;
+    audio_duration_seconds: number;
+    review_aspects: string[];
+    transcription_required?: boolean;
+}
+interface ImageAnalysisContent {
+    question: string;
+    image_url: string;
+}
+interface AbTestContent {
+    question: string;
+    variant_a: {
+        description: string;
+        image_url?: string;
+        url?: string;
+    };
+    variant_b: {
+        description: string;
+        image_url?: string;
+        url?: string;
+    };
+}
+interface CreateQueryBase {
+    title: string;
+    description?: string;
+    required_responses: number;
+    bid_amount_cents: number;
+    bonus_amount_cents?: number;
+    min_worker_quality?: number;
+    required_languages?: string[];
+    required_location_countries?: string[];
+    required_skills?: string[];
+    excluded_worker_ids?: string[];
+    expires_in_hours?: number;
+}
+type CreateQueryInput = (CreateQueryBase & {
+    type: 'text';
+    content_data: TextContent;
+}) | (CreateQueryBase & {
+    type: 'multiple_choice';
+    content_data: MultipleChoiceContent;
+}) | (CreateQueryBase & {
+    type: 'rating_scale';
+    content_data: RatingScaleContent;
+}) | (CreateQueryBase & {
+    type: 'image_comparison';
+    content_data: ImageComparisonContent;
+}) | (CreateQueryBase & {
+    type: 'ranking';
+    content_data: RankingContent;
+}) | (CreateQueryBase & {
+    type: 'yes_no';
+    content_data: YesNoContent;
+}) | (CreateQueryBase & {
+    type: 'sentiment';
+    content_data: SentimentContent;
+}) | (CreateQueryBase & {
+    type: 'image_selection';
+    content_data: ImageSelectionContent;
+}) | (CreateQueryBase & {
+    type: 'free_form_text';
+    content_data: FreeFormTextContent;
+}) | (CreateQueryBase & {
+    type: 'video_review';
+    content_data: VideoReviewContent;
+}) | (CreateQueryBase & {
+    type: 'audio_review';
+    content_data: AudioReviewContent;
+}) | (CreateQueryBase & {
+    type: 'image_analysis';
+    content_data: ImageAnalysisContent;
+}) | (CreateQueryBase & {
+    type: 'ab_test';
+    content_data: AbTestContent;
+});
+interface QueryResponse {
+    id: string;
+    response_data: Record<string, unknown>;
+    status: string;
+    submitted_at: string;
+    worker?: {
+        quality_score: number;
+        tier: string;
+        rating_count: number;
+    };
+    rating?: {
+        score: number;
+        feedback_text?: string | null;
+    } | null;
+}
+interface Query {
+    id: string;
+    type: QueryType;
+    title: string;
+    description?: string;
+    status: 'pending' | 'active' | 'completed' | 'cancelled' | 'failed' | 'expired';
+    required_responses: number;
+    completed_responses?: number;
+    bid_amount_cents: number;
+    bonus_amount_cents?: number;
+    total_cost_cents: number;
+    created_at: string;
+    expires_at?: string | null;
+    content_data?: Record<string, unknown>;
+    responses?: QueryResponse[];
+}
+interface QueryList {
+    queries: Query[];
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+interface RatingResult {
+    response_id: string;
+    score: number;
+    worker_new_quality_score: number;
+    worker_new_rating_count?: number;
+    worker_suspended: boolean;
+    feedback_text?: string | null;
+}
+interface Rating {
+    id: string;
+    response_id: string;
+    score: number;
+    feedback_text?: string | null;
+    created_at: string;
+}
+interface AccountStats {
+    balance_cents: number;
+    company_name: string;
+    total_queries: number;
+    active_queries: number;
+    completed_queries: number;
+    total_spent_cents: number;
+    recent_queries: Query[];
+}
+interface BillingInfo {
+    balance_cents: number;
+    company_name: string;
+    transactions: Record<string, unknown>[];
+    total: number;
+    has_more: boolean;
+}
+
+interface ListParams {
+    status?: string;
+    limit?: number;
+    offset?: number;
+}
+interface WaitOptions {
+    minResponses: number;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+declare class QueriesResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    create(input: CreateQueryInput): Promise<Query>;
+    get(id: string): Promise<Query>;
+    list(params?: ListParams): Promise<QueryList>;
+    cancel(id: string): Promise<{
+        success: boolean;
+        message: string;
+        refund_amount_cents: number;
+    }>;
+    waitForResponses(id: string, opts: WaitOptions): Promise<QueryResponse[]>;
+}
+
+declare class ResponsesResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    rate(queryId: string, responseId: string, input: {
+        score: number;
+        feedback_text?: string;
+    }): Promise<RatingResult>;
+    getRating(queryId: string, responseId: string): Promise<Rating>;
+}
+
+declare class AccountResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    stats(): Promise<AccountStats>;
+    balance(): Promise<BillingInfo>;
+}
+
+declare class GetABrain {
+    readonly queries: QueriesResource;
+    readonly responses: ResponsesResource;
+    readonly account: AccountResource;
+    constructor(config: TransportConfig);
+}
+
+declare class GetABrainError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string;
+    constructor(message: string, status: number, code?: string, requestId?: string);
+}
+declare class ValidationError extends GetABrainError {
+}
+declare class AuthError extends GetABrainError {
+}
+declare class InsufficientBalanceError extends GetABrainError {
+}
+declare class ForbiddenError extends GetABrainError {
+}
+declare class NotFoundError extends GetABrainError {
+}
+declare class ConflictError extends GetABrainError {
+}
+declare class ServerError extends GetABrainError {
+}
+declare class RateLimitError extends GetABrainError {
+    readonly retryAfterMs?: number;
+    constructor(message: string, status: number, code: string, retryAfterMs?: number, requestId?: string);
+}
+declare class TimeoutError extends GetABrainError {
+    constructor(message?: string);
+}
+declare class NetworkError extends GetABrainError {
+    constructor(message?: string);
+}
+declare function errorFromResponse(status: number, body: any, retryAfterMs?: number): GetABrainError;
+
+export { type AbTestContent, AccountResource, type AccountStats, type AudioReviewContent, AuthError, type BillingInfo, ConflictError, type CreateQueryBase, type CreateQueryInput, DEFAULT_BASE_URL, ForbiddenError, type FreeFormTextContent, GetABrain, GetABrainError, type ImageAnalysisContent, type ImageComparisonContent, type ImageSelectionContent, InsufficientBalanceError, type ListParams, type MultipleChoiceContent, NetworkError, NotFoundError, QUERY_TYPES, QueriesResource, type Query, type QueryList, type QueryResponse, type QueryType, type RankingContent, RateLimitError, type Rating, type RatingResult, type RatingScaleContent, type RequestOptions, ResponsesResource, type SentimentContent, ServerError, type TextContent, TimeoutError, type TransportConfig, ValidationError, type VideoReviewContent, type WaitOptions, type YesNoContent, errorFromResponse };

package/dist/index.d.ts

@@ -0,0 +1,329 @@
+declare const DEFAULT_BASE_URL = "https://www.getabrain.ai/api/v1";
+interface TransportConfig {
+    apiKey: string;
+    apiSecret: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    maxRetries?: number;
+    /** Injectable for deterministic tests; defaults to real setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+}
+interface RequestOptions {
+    body?: unknown;
+    query?: Record<string, string | number | undefined>;
+}
+type RequestFn = <T = any>(method: string, path: string, opts?: RequestOptions) => Promise<T>;
+
+declare const QUERY_TYPES: readonly ["text", "multiple_choice", "rating_scale", "image_comparison", "ranking", "yes_no", "sentiment", "image_selection", "free_form_text", "video_review", "audio_review", "image_analysis", "ab_test"];
+type QueryType = (typeof QUERY_TYPES)[number];
+interface SharedContent {
+    question: string;
+    instructions?: string;
+    context?: string;
+}
+interface TextContent extends SharedContent {
+    min_words?: number;
+    max_words?: number;
+}
+interface MultipleChoiceContent extends SharedContent {
+    options: {
+        id: string;
+        text: string;
+        image_url?: string;
+    }[];
+    allow_multiple?: boolean;
+    min_selections?: number;
+    max_selections?: number;
+}
+interface RatingScaleContent extends SharedContent {
+    scale_type: '1-5' | '1-10' | '0-100' | 'stars';
+    scale_min: number;
+    scale_max: number;
+    scale_labels?: {
+        min_label?: string;
+        mid_label?: string;
+        max_label?: string;
+    };
+    criteria?: string[];
+}
+interface ImageComparisonContent extends SharedContent {
+    images: {
+        id: string;
+        url: string;
+        label?: string;
+        description?: string;
+    }[];
+    comparison_type: 'preference' | 'quality' | 'relevance' | 'custom';
+    require_reasoning?: boolean;
+}
+interface RankingContent extends SharedContent {
+    items: {
+        id: string;
+        text: string;
+        image_url?: string;
+        description?: string;
+    }[];
+    max_items: number;
+    require_all?: boolean;
+}
+interface YesNoContent extends SharedContent {
+    require_explanation?: boolean;
+    min_explanation_words?: number;
+}
+interface SentimentContent extends SharedContent {
+    subject: string;
+    sentiment_options: ('very_positive' | 'positive' | 'neutral' | 'negative' | 'very_negative')[];
+    require_reasoning?: boolean;
+}
+interface ImageSelectionContent extends SharedContent {
+    images: {
+        id: string;
+        url: string;
+        caption?: string;
+    }[];
+    min_selections: number;
+    max_selections: number;
+    selection_criteria: string;
+}
+interface FreeFormTextContent extends SharedContent {
+    prompt: string;
+    min_characters?: number;
+    max_characters?: number;
+    format_guidelines?: string;
+}
+interface VideoReviewContent extends SharedContent {
+    video_url: string;
+    video_duration_seconds: number;
+    review_aspects: string[];
+    min_watch_time_seconds?: number;
+}
+interface AudioReviewContent extends SharedContent {
+    audio_url: string;
+    audio_duration_seconds: number;
+    review_aspects: string[];
+    transcription_required?: boolean;
+}
+interface ImageAnalysisContent {
+    question: string;
+    image_url: string;
+}
+interface AbTestContent {
+    question: string;
+    variant_a: {
+        description: string;
+        image_url?: string;
+        url?: string;
+    };
+    variant_b: {
+        description: string;
+        image_url?: string;
+        url?: string;
+    };
+}
+interface CreateQueryBase {
+    title: string;
+    description?: string;
+    required_responses: number;
+    bid_amount_cents: number;
+    bonus_amount_cents?: number;
+    min_worker_quality?: number;
+    required_languages?: string[];
+    required_location_countries?: string[];
+    required_skills?: string[];
+    excluded_worker_ids?: string[];
+    expires_in_hours?: number;
+}
+type CreateQueryInput = (CreateQueryBase & {
+    type: 'text';
+    content_data: TextContent;
+}) | (CreateQueryBase & {
+    type: 'multiple_choice';
+    content_data: MultipleChoiceContent;
+}) | (CreateQueryBase & {
+    type: 'rating_scale';
+    content_data: RatingScaleContent;
+}) | (CreateQueryBase & {
+    type: 'image_comparison';
+    content_data: ImageComparisonContent;
+}) | (CreateQueryBase & {
+    type: 'ranking';
+    content_data: RankingContent;
+}) | (CreateQueryBase & {
+    type: 'yes_no';
+    content_data: YesNoContent;
+}) | (CreateQueryBase & {
+    type: 'sentiment';
+    content_data: SentimentContent;
+}) | (CreateQueryBase & {
+    type: 'image_selection';
+    content_data: ImageSelectionContent;
+}) | (CreateQueryBase & {
+    type: 'free_form_text';
+    content_data: FreeFormTextContent;
+}) | (CreateQueryBase & {
+    type: 'video_review';
+    content_data: VideoReviewContent;
+}) | (CreateQueryBase & {
+    type: 'audio_review';
+    content_data: AudioReviewContent;
+}) | (CreateQueryBase & {
+    type: 'image_analysis';
+    content_data: ImageAnalysisContent;
+}) | (CreateQueryBase & {
+    type: 'ab_test';
+    content_data: AbTestContent;
+});
+interface QueryResponse {
+    id: string;
+    response_data: Record<string, unknown>;
+    status: string;
+    submitted_at: string;
+    worker?: {
+        quality_score: number;
+        tier: string;
+        rating_count: number;
+    };
+    rating?: {
+        score: number;
+        feedback_text?: string | null;
+    } | null;
+}
+interface Query {
+    id: string;
+    type: QueryType;
+    title: string;
+    description?: string;
+    status: 'pending' | 'active' | 'completed' | 'cancelled' | 'failed' | 'expired';
+    required_responses: number;
+    completed_responses?: number;
+    bid_amount_cents: number;
+    bonus_amount_cents?: number;
+    total_cost_cents: number;
+    created_at: string;
+    expires_at?: string | null;
+    content_data?: Record<string, unknown>;
+    responses?: QueryResponse[];
+}
+interface QueryList {
+    queries: Query[];
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+interface RatingResult {
+    response_id: string;
+    score: number;
+    worker_new_quality_score: number;
+    worker_new_rating_count?: number;
+    worker_suspended: boolean;
+    feedback_text?: string | null;
+}
+interface Rating {
+    id: string;
+    response_id: string;
+    score: number;
+    feedback_text?: string | null;
+    created_at: string;
+}
+interface AccountStats {
+    balance_cents: number;
+    company_name: string;
+    total_queries: number;
+    active_queries: number;
+    completed_queries: number;
+    total_spent_cents: number;
+    recent_queries: Query[];
+}
+interface BillingInfo {
+    balance_cents: number;
+    company_name: string;
+    transactions: Record<string, unknown>[];
+    total: number;
+    has_more: boolean;
+}
+
+interface ListParams {
+    status?: string;
+    limit?: number;
+    offset?: number;
+}
+interface WaitOptions {
+    minResponses: number;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+declare class QueriesResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    create(input: CreateQueryInput): Promise<Query>;
+    get(id: string): Promise<Query>;
+    list(params?: ListParams): Promise<QueryList>;
+    cancel(id: string): Promise<{
+        success: boolean;
+        message: string;
+        refund_amount_cents: number;
+    }>;
+    waitForResponses(id: string, opts: WaitOptions): Promise<QueryResponse[]>;
+}
+
+declare class ResponsesResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    rate(queryId: string, responseId: string, input: {
+        score: number;
+        feedback_text?: string;
+    }): Promise<RatingResult>;
+    getRating(queryId: string, responseId: string): Promise<Rating>;
+}
+
+declare class AccountResource {
+    private readonly request;
+    constructor(request: RequestFn);
+    stats(): Promise<AccountStats>;
+    balance(): Promise<BillingInfo>;
+}
+
+declare class GetABrain {
+    readonly queries: QueriesResource;
+    readonly responses: ResponsesResource;
+    readonly account: AccountResource;
+    constructor(config: TransportConfig);
+}
+
+declare class GetABrainError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string;
+    constructor(message: string, status: number, code?: string, requestId?: string);
+}
+declare class ValidationError extends GetABrainError {
+}
+declare class AuthError extends GetABrainError {
+}
+declare class InsufficientBalanceError extends GetABrainError {
+}
+declare class ForbiddenError extends GetABrainError {
+}
+declare class NotFoundError extends GetABrainError {
+}
+declare class ConflictError extends GetABrainError {
+}
+declare class ServerError extends GetABrainError {
+}
+declare class RateLimitError extends GetABrainError {
+    readonly retryAfterMs?: number;
+    constructor(message: string, status: number, code: string, retryAfterMs?: number, requestId?: string);
+}
+declare class TimeoutError extends GetABrainError {
+    constructor(message?: string);
+}
+declare class NetworkError extends GetABrainError {
+    constructor(message?: string);
+}
+declare function errorFromResponse(status: number, body: any, retryAfterMs?: number): GetABrainError;
+
+export { type AbTestContent, AccountResource, type AccountStats, type AudioReviewContent, AuthError, type BillingInfo, ConflictError, type CreateQueryBase, type CreateQueryInput, DEFAULT_BASE_URL, ForbiddenError, type FreeFormTextContent, GetABrain, GetABrainError, type ImageAnalysisContent, type ImageComparisonContent, type ImageSelectionContent, InsufficientBalanceError, type ListParams, type MultipleChoiceContent, NetworkError, NotFoundError, QUERY_TYPES, QueriesResource, type Query, type QueryList, type QueryResponse, type QueryType, type RankingContent, RateLimitError, type Rating, type RatingResult, type RatingScaleContent, type RequestOptions, ResponsesResource, type SentimentContent, ServerError, type TextContent, TimeoutError, type TransportConfig, ValidationError, type VideoReviewContent, type WaitOptions, type YesNoContent, errorFromResponse };

package/dist/index.js

@@ -0,0 +1,249 @@
+// src/errors.ts
+var GetABrainError = class extends Error {
+  constructor(message, status, code = "error", requestId) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+    this.name = new.target.name;
+  }
+};
+var ValidationError = class extends GetABrainError {
+};
+var AuthError = class extends GetABrainError {
+};
+var InsufficientBalanceError = class extends GetABrainError {
+};
+var ForbiddenError = class extends GetABrainError {
+};
+var NotFoundError = class extends GetABrainError {
+};
+var ConflictError = class extends GetABrainError {
+};
+var ServerError = class extends GetABrainError {
+};
+var RateLimitError = class extends GetABrainError {
+  constructor(message, status, code, retryAfterMs, requestId) {
+    super(message, status, code, requestId);
+    this.retryAfterMs = retryAfterMs;
+  }
+};
+var TimeoutError = class extends GetABrainError {
+  constructor(message = "Request timed out") {
+    super(message, 0, "timeout");
+  }
+};
+var NetworkError = class extends GetABrainError {
+  constructor(message = "Network request failed") {
+    super(message, 0, "network");
+  }
+};
+function errorFromResponse(status, body, retryAfterMs) {
+  const message = body && body.message || body && body.error || `HTTP ${status}`;
+  const code = body && body.error || "error";
+  switch (status) {
+    case 400:
+      return new ValidationError(message, status, code);
+    case 401:
+      return new AuthError(message, status, code);
+    case 402:
+      return new InsufficientBalanceError(message, status, code);
+    case 403:
+      return new ForbiddenError(message, status, code);
+    case 404:
+      return new NotFoundError(message, status, code);
+    case 409:
+      return new ConflictError(message, status, code);
+    case 429:
+      return new RateLimitError(message, status, code, retryAfterMs);
+    default:
+      if (status >= 500) return new ServerError(message, status, code);
+      return new GetABrainError(message, status, code);
+  }
+}
+
+// src/http.ts
+var DEFAULT_BASE_URL = "https://www.getabrain.ai/api/v1";
+var realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function createTransport(config) {
+  var _a, _b, _c, _d, _e;
+  const baseUrl = ((_a = config.baseUrl) != null ? _a : DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const doFetch = (_b = config.fetch) != null ? _b : globalThis.fetch;
+  const timeoutMs = (_c = config.timeoutMs) != null ? _c : 3e4;
+  const maxRetries = (_d = config.maxRetries) != null ? _d : 2;
+  const sleep = (_e = config.sleep) != null ? _e : realSleep;
+  if (typeof doFetch !== "function") {
+    throw new GetABrainError("No fetch available \u2014 use Node 18+ or pass { fetch }", 0, "config");
+  }
+  return async function request(method, path, opts = {}) {
+    const url = new URL(baseUrl + path);
+    if (opts.query) {
+      for (const [k, v] of Object.entries(opts.query)) if (v !== void 0) url.searchParams.set(k, String(v));
+    }
+    const isRead = method.toUpperCase() === "GET";
+    let attempt = 0;
+    for (; ; ) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      let res;
+      try {
+        res = await doFetch(url.toString(), {
+          method,
+          headers: { "X-API-Key": config.apiKey, "X-API-Secret": config.apiSecret, "Content-Type": "application/json" },
+          body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0,
+          signal: controller.signal
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        if ((err == null ? void 0 : err.name) === "AbortError") throw new TimeoutError();
+        if (isRead && attempt < maxRetries) {
+          attempt++;
+          await sleep(backoff(attempt));
+          continue;
+        }
+        throw new NetworkError((err == null ? void 0 : err.message) || "fetch failed");
+      }
+      clearTimeout(timer);
+      if (res.ok) {
+        if (res.status === 204) return void 0;
+        return await res.json();
+      }
+      const retryAfterMs = parseRetryAfter(res.headers.get("retry-after"));
+      if (isRead && (res.status === 429 || res.status >= 500) && attempt < maxRetries) {
+        attempt++;
+        await sleep(retryAfterMs != null ? retryAfterMs : backoff(attempt));
+        continue;
+      }
+      let body = null;
+      try {
+        body = await res.json();
+      } catch (e) {
+      }
+      throw errorFromResponse(res.status, body, retryAfterMs);
+    }
+  };
+}
+function backoff(attempt) {
+  return Math.min(1e3 * 2 ** (attempt - 1), 8e3);
+}
+function parseRetryAfter(h) {
+  if (!h) return void 0;
+  const n = Number(h);
+  return Number.isFinite(n) ? n * 1e3 : void 0;
+}
+
+// src/resources/queries.ts
+var TERMINAL = /* @__PURE__ */ new Set(["completed", "cancelled", "failed", "expired"]);
+var realSleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+var QueriesResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  create(input) {
+    return this.request("POST", "/requestor/queries", { body: input });
+  }
+  get(id) {
+    return this.request("GET", `/requestor/queries/${encodeURIComponent(id)}`);
+  }
+  list(params = {}) {
+    return this.request("GET", "/requestor/queries", { query: { status: params.status, limit: params.limit, offset: params.offset } });
+  }
+  cancel(id) {
+    return this.request("PUT", `/requestor/queries/${encodeURIComponent(id)}`, { body: { action: "cancel" } });
+  }
+  // Poll until `minResponses` responses arrive, the query reaches a terminal
+  // status, or the timeout elapses (throws TimeoutError).
+  async waitForResponses(id, opts) {
+    var _a, _b, _c, _d, _e, _f;
+    const timeoutMs = (_a = opts.timeoutMs) != null ? _a : 6e5;
+    const pollIntervalMs = (_b = opts.pollIntervalMs) != null ? _b : 5e3;
+    const sleep = (_c = opts.sleep) != null ? _c : realSleep2;
+    const now = (_d = opts.now) != null ? _d : Date.now;
+    const deadline = now() + timeoutMs;
+    for (; ; ) {
+      const query = await this.get(id);
+      const responses = (_e = query.responses) != null ? _e : [];
+      if (((_f = query.completed_responses) != null ? _f : responses.length) >= opts.minResponses) return responses;
+      if (TERMINAL.has(query.status)) return responses;
+      if (now() >= deadline) throw new TimeoutError(`waitForResponses timed out after ${timeoutMs}ms for query ${id}`);
+      await sleep(pollIntervalMs);
+    }
+  }
+};
+
+// src/resources/responses.ts
+var ResponsesResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  rate(queryId, responseId, input) {
+    const q = encodeURIComponent(queryId);
+    const r = encodeURIComponent(responseId);
+    return this.request("POST", `/requestor/queries/${q}/responses/${r}/rate`, { body: input });
+  }
+  getRating(queryId, responseId) {
+    const q = encodeURIComponent(queryId);
+    const r = encodeURIComponent(responseId);
+    return this.request("GET", `/requestor/queries/${q}/responses/${r}/rate`);
+  }
+};
+
+// src/resources/account.ts
+var AccountResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  stats() {
+    return this.request("GET", "/requestor/stats");
+  }
+  balance() {
+    return this.request("GET", "/requestor/billing");
+  }
+};
+
+// src/client.ts
+var GetABrain = class {
+  constructor(config) {
+    const request = createTransport(config);
+    this.queries = new QueriesResource(request);
+    this.responses = new ResponsesResource(request);
+    this.account = new AccountResource(request);
+  }
+};
+
+// src/types.ts
+var QUERY_TYPES = [
+  "text",
+  "multiple_choice",
+  "rating_scale",
+  "image_comparison",
+  "ranking",
+  "yes_no",
+  "sentiment",
+  "image_selection",
+  "free_form_text",
+  "video_review",
+  "audio_review",
+  "image_analysis",
+  "ab_test"
+];
+export {
+  AccountResource,
+  AuthError,
+  ConflictError,
+  DEFAULT_BASE_URL,
+  ForbiddenError,
+  GetABrain,
+  GetABrainError,
+  InsufficientBalanceError,
+  NetworkError,
+  NotFoundError,
+  QUERY_TYPES,
+  QueriesResource,
+  RateLimitError,
+  ResponsesResource,
+  ServerError,
+  TimeoutError,
+  ValidationError,
+  errorFromResponse
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@getabrain/sdk",
+  "version": "0.1.0",
+  "description": "Official Node/TypeScript SDK for the GetABrain.ai human-intelligence API",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
+    }
+  },
+  "sideEffects": false,
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --tsconfig tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": { "node": ">=18" },
+  "devDependencies": { "tsup": "^8.0.0" },
+  "license": "MIT"
+}