@fastaf-co/fastaf
v0.2.1
Published
FastAF API-key and opt-in x402 client
Readme
@fastaf-co/fastaf
TypeScript/ESM, Node 20.3+. Published 0.1.0; proposed 0.2.0 is not published.
Install: npm install @fastaf-co/fastaf.
import { FastAF, FastAFError } from '@fastaf-co/fastaf';
const client = new FastAF({ apiKey: process.env.FASTAF_API_KEY! });
const data = await client.search('best espresso machine', { results: 5 });
const markdown = await client.request<string>('scrape', {
url: 'https://example.com', formats: 'markdown',
});
const post = await client.request('serp', { query: 'coffee' }, { method: 'POST' });request(endpoint, params) calls /v1/<endpoint>, returning JSON, text or
Uint8Array for images. raw() returns a checked Response for custom decoding.
Endpoint names cannot contain paths, query strings or URLs. baseUrl is an
explicit HTTP(S) origin; only send keys over HTTPS outside local testing.
timeoutMs defaults to 60,000; each request also accepts an AbortSignal.
FastAFError has status, parsed body and headers (including Retry-After).
Transport/abort errors propagate unchanged. No redirects. One safe retry by default; set maxRetries: 0 to disable.
Never embed an API key or wallet in public frontend code.
Opt-in x402
API-key mode never signs or switches to payments on a 402. Configure an x402
client yourself (network, signer and spending policy) and install the optional
peer @x402/fetch separately:
import { x402Client } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm';
import { privateKeyToAccount } from 'viem/accounts';
import { createX402Client } from '@fastaf-co/fastaf/x402';
const signer = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);
const paymentClient = new x402Client().register('eip155:8453', new ExactEvmScheme(signer));
// This example limits each authorized payment to 0.01 USDC (six decimals).
paymentClient.onBeforePaymentCreation(async ({ selectedRequirements }) => {
if (selectedRequirements.network !== 'eip155:8453' ||
selectedRequirements.asset.toLowerCase() !== '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' ||
BigInt(selectedRequirements.amount) > 10_000n) {
return { abort: true, reason: 'Payment outside configured policy' };
}
});
const paid = createX402Client(paymentClient);
const data = await paid.search('coffee');Install @x402/evm and viem for that signer example; they are not core SDK
dependencies. Configure a trusted merchant/payTo allowlist and an aggregate
spending budget in your application too. A per-call cap is not a total budget.
The adapter blocks additional signed transmissions, including recovery hooks;
only unsigned probes get transient retries.
Already have an x402-aware fetch (including legacy x402-fetch)? Inject it:
const paid = new FastAF({ mode: 'x402', fetch: paymentAwareFetch });This always starts at /x402/v1/*, never /v1/*, and sends no API key. Do not
follow arbitrary resource URLs from challenges or reuse settled signatures.
Both payment integrations are optional; importing @fastaf-co/fastaf alone loads neither.
LangChain.js
Install optional peers @langchain/core and zod:
import { createSearchTool } from '@fastaf-co/fastaf/langchain';
const search = createSearchTool(client); // Or the explicitly configured paid client.
const result = await search.invoke({ query: 'coffee', results: 5 });Tool arguments are only query and results (1-10); credentials remain in the
client closure. Limit agent steps: each tool invocation can cost credits/money.
Test
npx [email protected] ci && npm test builds declarations and runs Node tests with mocked
fetch, including the real optional x402 wrapper and LangChain tool. No real
wallet, API key, facilitator or paid upstream request is used.
New endpoint helpers (0.2.0)
await client.linkedinJobs('Python developer', { location: 'London' });
await client.bing('coffee', { mkt: 'en-US' });
await client.images('coffee', { licenses: 'f' });
await client.reddit('https://www.reddit.com/r/python/');
await client.patents('battery', { num: 5 });
await client.flights('JFK', 'LHR', '2026-12-01', { type: '2' });
await client.youtube('coffee');
await client.youtubeTranscript('dQw4w9WgXcQ');Helpers accept extra REST parameters and a final RequestOptions (GET/POST,
AbortSignal); request() / raw() continue to support every live endpoint.
Reddit returns public RSS markdown without author fields/user-profile links,
not user histories; quoted discussion text is not a guarantee of anonymization.
Images license filters do not replace checking source rights.
Prices come from the live x402 challenge, not SDK constants.
Retry safety
At most one retry, after at least 500 ms and respecting Retry-After; see the full contract. Keyed transport errors, unknown 5xx, 402 and signed x402 requests are not retried. Do not put your own retry loop around a paid call: a lost response can follow a successful settlement. The adapter never generates a second transmission with a new proof to recover that call. An opaque injected payment-aware fetch is invoked once; its internal behavior is your responsibility.
The existing 60-second operation timeout can abort a server request while it
is still running. For the server's 105-second search retry budget, consider
timeoutMs: 120_000; an abort is never evidence of no charge.
