@airewards/agent-sdk
v0.1.0
Published
AIRewards ad spinner for CLI AI agents: show a sponsored line while a Promise resolves.
Readme
@airewards/agent-sdk
Monetize the "thinking" state of your CLI AI agent. While your Promise (an LLM call, a build, anything async) resolves, the SDK renders a one-line sponsored spinner and credits your AIRewards developer wallet once the ad has been visible for 5 seconds.
Zero runtime dependencies — native fetch (Node 18+) and plain
carriage-return terminal rendering.
Install
pnpm add @airewards/agent-sdkUsage
Wrap any Promise-returning task with withAdSpinner. Your task's result (or
rejection) passes through untouched, and nothing ad-related can delay or fail
it.
import { withAdSpinner } from '@airewards/agent-sdk';
const completion = await withAdSpinner({
apiKey: process.env.AIREWARDS_API_KEY!, // air_dev_… from the dashboard
task: () => llm.complete(prompt), // your real work
spinnerText: 'Thinking…', // shown until an ad arrives
});While task runs the terminal shows:
⠹ [Sponsored] Ship faster with Acme Cloud — free tier for CLI agentsHow it works
- The spinner starts immediately with your neutral
spinnerText. GET /v1/ads/current?platform=cliis fetched concurrently with your task (never before it — a slow ad server cannot add latency to your CLI).- When the ad arrives, the spinner text switches to
[Sponsored] <ad text>. - If the ad stays on screen for 5 seconds, the client begins a v2 challenge and sends visibility heartbeats while the ad remains visible. The server validates and risk-scores that evidence before recording provisional accounting; withdrawal eligibility follows the settlement delay.
- When your task settles, the spinner line is erased and the result returned.
Spinner rendering — and therefore impression reporting — is skipped when the output stream is not a TTY, so piped output stays clean and unseen ads are never credited.
Options
| Option | Type | Default | Notes |
| ------------- | --------------------- | ---------------------- | --------------------------------------- |
| apiKey | string | required | Developer API key, sent as Bearer token |
| task | () => Promise<T> | required | The work to run |
| baseUrl | string | production API | Point at a local backend for dev |
| spinnerText | string | 'Thinking…' | Label before/without an ad |
| stream | NodeJS.WriteStream | process.stdout | Where the spinner renders |
Demo
See apps/cli-demo for a runnable end-to-end example:
pnpm build
AIREWARDS_API_KEY=air_dev_… node apps/cli-demo/dist/index.js