@bippsi/client

Install

npm publish is pending. For the alpha, clone the repo:

# clone the public repo
git clone https://github.com/bigappstudiollc/bippsi.git
# install from local path
npm install ./bippsi/ai-lock-protocol/clients/node

Requires Node 18+ (uses native global fetch). No other runtime dependencies.

30-second quickstart

import { BippsiClient } from '@bippsi/client';

const bippsi = new BippsiClient({
  agentKey: process.env.BIPPSI_AGENT_KEY,  // bak_* key
  maxPricePerRequest: 10,                   // hard cap, in Bips
});

// 1. Discover — cross-site registry search, no auth needed
const r = await bippsi.discover({ q: 'finance', access: 'paid' });

// 2. Resolve — get metadata for any URL before you fetch
const meta = await bippsi.resolve(r.results[0].resource_url);

// 3. Fetch — handles 402 retry + payment automatically
const res = await bippsi.fetch(r.results[0].resource_url);
console.log(res.body, 'paid:', res.paid, 'Bips');

Drop-in fetch

Zero-config replacement for the global fetch:

import { bippsiFetch } from '@bippsi/client/fetch';

// Same signature as native fetch(). Handles 402s automatically.
const r = await bippsiFetch('https://biptest.com/articles/whitepaper', {
  maxPricePerRequest: 25,
});
console.log(r.body);    // paid content
console.log(r.paid);    // Bips spent (0 if unpriced)

Set BIPPSI_AGENT_KEY in your environment and this works with zero config.

Error handling

import { OverspendCapError, InsufficientBalanceError } from '@bippsi/client/errors';

try {
  const r = await bippsi.fetch(url);
} catch (err) {
  if (err instanceof OverspendCapError) {
    // err.priceBips, err.cap — price was higher than config
  } else if (err instanceof InsufficientBalanceError) {
    // err.balance — top up at bippsi.com/ai-key
  } else {
    throw err;
  }
}

Full API

• bippsi.discover({ q, category, access, partner, sort, limit, offset }) — search the registry.
• bippsi.resolve(url) — get Bippsi metadata for any URL.
• bippsi.fetch(url, opts) — fetch + 402 handling.
• bippsi.pay({ url, priceBips }) — explicit charge without a fetch.
• bippsi.getBalance() — current Bip balance.
• bippsi.listReceipts({ since, limit }) — recent charges.

Behavior contract shared with the Python SDK is documented at client-spec.md.