Errors

{
  "data": {
    "error": {
      "message": "An active or pending verification already exists for this scope and user. Wait for it to expire or complete before creating another.",
      "statusCode": 409
    }
  }
}

{
  "code": "InputValidationError",
  "message": "Bad Request: Invalid input",
  "input": { "request_id": "not-a-uuid" },
  "errors": [
    {
      "propertyPath": "/request_id",
      "invalidValue": "not-a-uuid",
      "message": "Invalid uuid"
    }
  ]
}

{
  "errors": [
    {
      "message": "Rate limit exceeded. Bucket \"burst\" hit its cap; retry in 7s.",
      "code": "RATE_LIMITED"
    }
  ],
  "_rateLimit": {
    "scope": "dev",
    "primary": { "bucket": "burst", "limit": 30, "remaining": 0, "resetIn": 7 },
    "buckets": {
      "burst": { "limit": 30, "remaining": 0, "resetIn": 7 },
      "hourly": { "limit": 300, "remaining": 212, "resetIn": 1841 },
      "daily": { "limit": 2000, "remaining": 1704, "resetIn": 50112 }
    }
  }
}

{
  "data": {
    "data": {
      "success": true,
      "revoked_count": 1,
      "message": "1 pending verification(s) revoked. You may now create a new one."
    }
  }
}

export type BotShieldErrorBody = {
  message: string;
  statusCode: number;
  code?: string;
  min_ttl_seconds?: number;
  max_ttl_seconds?: number;
  violations?: { type?: string; path?: string; severity?: string }[];
};

export class BotShieldApiError extends Error {
  constructor(
    message: string,
    /** The status the error stands for: data.error.statusCode, or the real HTTP status. */
    readonly statusCode: number,
    /** Machine code when there is one. */
    readonly code: string | undefined,
    /** Seconds to wait before retrying. Set on rate-limit errors. */
    readonly retryAfterSeconds: number | undefined,
    /** The parsed error body, for logging. */
    readonly details: unknown,
  ) {
    super(message);
    this.name = "BotShieldApiError";
  }

  get retryable(): boolean {
    return this.code === "RATE_LIMITED" || this.statusCode >= 500;
  }
}

const BASE_URL = "https://api.botshield.ai/operations";

// Operations whose payload sits directly under `data` instead of `data.data`.
const FLAT_OPERATIONS = new Set(["sdk/logout", "verification/status"]);

export async function callBotShield<T>(
  operation: string,
  init: { method: "GET" | "POST"; bearer?: string; body?: unknown; query?: Record<string, string> },
): Promise<T> {
  const url = new URL(`${BASE_URL}/${operation}`);
  for (const [key, value] of Object.entries(init.query ?? {})) url.searchParams.set(key, value);

  const response = await fetch(url, {
    method: init.method,
    headers: {
      Accept: "application/json",
      ...(init.body !== undefined ? { "Content-Type": "application/json" } : {}),
      ...(init.bearer ? { Authorization: `Bearer ${init.bearer}` } : {}),
    },
    body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
  });

  const text = await response.text();
  let body: any;
  try {
    body = text ? JSON.parse(text) : {};
  } catch {
    throw new BotShieldApiError(`Non-JSON response (HTTP ${response.status})`, response.status, undefined, undefined, text);
  }

  // Real HTTP 403: rate limited.
  const topLevel = Array.isArray(body.errors) ? body.errors[0] : undefined;
  if (topLevel?.code === "RATE_LIMITED") {
    const retryAfter = body._rateLimit?.primary?.resetIn;
    throw new BotShieldApiError(topLevel.message, response.status, "RATE_LIMITED", retryAfter, body);
  }

  // Real HTTP 400: the request failed input validation.
  if (response.status === 400) {
    throw new BotShieldApiError(body.message ?? "Invalid input", 400, body.code ?? "InputValidationError", undefined, body);
  }

  // Any other non-200: unhandled failure.
  if (!response.ok) {
    throw new BotShieldApiError(body.message ?? `HTTP ${response.status}`, response.status, undefined, undefined, body);
  }

  // HTTP 200 with a handler error.
  const error: BotShieldErrorBody | undefined = body.data?.error;
  if (error) {
    throw new BotShieldApiError(error.message, error.statusCode, error.code, undefined, error);
  }

  return (FLAT_OPERATIONS.has(operation) ? body.data : body.data?.data) as T;
}

try {
  const session = await callBotShield<{ anchor_grant_token: string }>("sdk/create-session", {
    method: "POST",
    bearer: process.env.BOTSHIELD_API_KEY,
    body: { partner_user_id: "user_8842" },
  });

  const link = await callBotShield<{ request_id: string; web_url: string }>(
    "sdk/create-verification-link",
    { method: "POST", bearer: session.anchor_grant_token, body: { scope: "checkout" } },
  );
  console.log(link.request_id);
} catch (error) {
  if (error instanceof BotShieldApiError && error.statusCode === 409) {
    // This user still has a pending request for this gate. Revoke it, or let it finish.
  } else if (error instanceof BotShieldApiError && error.retryable) {
    // Back off (error.retryAfterSeconds when set), then try again.
  } else {
    throw error;
  }
}