@usebido/sdk

TypeScript SDK for Bido — the sponsored-intent decision API for AI agents. Detect whether a user message represents a sponsorable decision moment, run an auction across eligible sponsors, and record conversion feedback.

Install

npm install @usebido/sdk

Requires Node.js 18+ (uses the global fetch and AbortController). Works in modern browsers, Deno, Bun, and edge runtimes.

Quick start

import { BidoClient } from '@usebido/sdk';

const bido = new BidoClient({
  agentTreasuryWallet: process.env.SOLANA_AGENT_WALLET,
});

// 1. Easiest path: detect + match in one call (the 90% use case).
const { intent, match } = await bido.run('quero viajar pra Lisboa em julho');

if (match?.selected_candidate) {
  const sponsor = match.selected_candidate;
  console.log(`Sponsor: ${sponsor.advertiser} → ${sponsor.destination_url}`);
  console.log(`Decision id: ${sponsor.decision_id}`);
}

API

new BidoClient(options?)

| Option | Type | Default | Notes | | --------------------- | -------------------------- | ---------------------------------------- | ------------------------------------------------------------------ | | agentTreasuryWallet | string \| null | null | Solana wallet that receives the agent owner's settlement share. | | intentApiUrl | string | https://api-intent.usebido.com | Intent-detection service base URL. | | backendApiUrl | string | https://api.usebido.com/api | Bido backend base URL. | | timeoutMs | number | 5000 | Per-attempt request timeout. | | retry | Partial<RetryOptions> | { retries: 3, factor: 2, jitter: true }| Exponential backoff with jitter. | | headers | Record<string, string> | — | Extra headers (e.g. Authorization) attached to every request. |

run(query, options?) → Promise<RunResult>

Full pipeline. Calls detect, then match if intent.sponsorable === true. When the message is not sponsorable, match is null and no auction call is made.

detect(query, options?) → Promise<IntentResult>

Calls POST /detect-intent. Returns the structured intent classification (sponsorable flag, vertical, intent type, purchase stage, urgency, entities, reason).

match(intent, options?) → Promise<MatchResult>

Calls POST /intent/match with an IntentResult. The backend ranks eligible sponsor campaigns, picks the winner via first-price auction, and settles the winning bid on-chain in the same request. Returns the selected candidate (with decision_id and settlement_tx_hash) plus the top qualified candidates.

agentTreasuryWallet falls back to the client-level default if omitted.

Granular usage

const intent = await bido.detect('hotel pet friendly em Floripa semana que vem');

if (intent.sponsorable && intent.confidence >= 0.6) {
  const match = await bido.match(intent);
  const winner = match.selected_candidate;

  if (winner) {
    console.log(`Use sponsor ${winner.advertiser} (decision ${winner.decision_id})`);
  }
}

Errors

Every failure throws a BidoError with a discriminated code:

| code | When | | ------------------- | ------------------------------------------------------------- | | timeout | A single attempt exceeded timeoutMs. | | network | fetch rejected (DNS, connection, TLS). | | http_4xx | API returned a 4xx (not retried). | | http_5xx | API returned a 5xx after all retries. | | invalid_response | Response was not the expected JSON shape. | | invalid_input | Argument validation failed locally (no network call made). | | aborted | Caller signalled abort via options.signal. |

import { BidoClient, isBidoError } from '@usebido/sdk';

try {
  await bido.run(query);
} catch (err) {
  if (isBidoError(err)) {
    console.error(`[${err.code}] ${err.message}`, { status: err.status });
  } else {
    throw err;
  }
}

Retries: idempotent retries are applied on timeout, network, and HTTP 408/425/429/500/502/503/504. Other 4xx errors fail fast. Default policy: 3 attempts, exponential backoff (200ms → 400ms → 800ms, capped at 3s, with jitter).

Cancellation

Pass an AbortSignal to cancel pending work, including the backoff sleeps between retries:

const controller = new AbortController();
setTimeout(() => controller.abort(), 2_000);

await bido.run(query, { signal: controller.signal });

Types

IntentResult, MatchResult, Candidate, SelectedCandidate, RunResult, plus the literal unions (Vertical, IntentType, PurchaseStage, Urgency) are exported from the package root.

Build

npm install
npm run build      # emits dist/ (ESM + CJS + .d.ts)
npm test