npm package: @lucid-fdn/oracle
Description: TypeScript SDK for the [Lucid Agent Oracle API](https://api.lucid.foundation) — economic intelligence for the agent economy.
Author: Lucid Foundation
Latest version: 0.1.0

# @lucid-fdn/oracle

TypeScript SDK for the [Lucid Agent Oracle API](https://api.lucid.foundation) — economic intelligence for the agent economy.

[![npm](https://img.shields.io/npm/v/@lucid-fdn/oracle)](https://www.npmjs.com/package/@lucid-fdn/oracle)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

## Install

```bash
npm install @lucid-fdn/oracle
```

## Quick Start

```typescript
import { LucidOracle } from "@lucid-fdn/oracle";

// Auto-reads LUCID_ORACLE_API_KEY from env (optional — free-tier works without auth)
const oracle = new LucidOracle();

// List all oracle feeds
const feeds = await oracle.feeds.list();

// Search agents
const agents = await oracle.agents.search({ q: "lucid" });

// Get protocol details
const protocols = await oracle.protocols.list();
```

## Authentication

API key is **optional**. Free-tier endpoints work anonymously. Pro-tier endpoints require a key.

```typescript
// Explicit API key
const oracle = new LucidOracle({ apiKey: "sk_..." });

// Or set LUCID_ORACLE_API_KEY env var (auto-detected)
const oracle = new LucidOracle();

// Custom server URL (for local dev)
const oracle = new LucidOracle({
  serverURL: "http://localhost:4040",
});
```

## Resources

### Feeds

```typescript
oracle.feeds.list();                              // List all feeds
oracle.feeds.get({ id });                         // Get feed by ID
oracle.feeds.methodology({ id });                 // Get feed methodology
oracle.feeds.history({ id, period, interval });   // Get feed history
```

### Agents

```typescript
oracle.agents.search({ q, cursor, limit });       // Search agents
oracle.agents.leaderboard({ sort, cursor, limit }); // Agent leaderboard
oracle.agents.get({ id });                         // Get agent by ID
oracle.agents.metrics({ id });                     // Agent metrics (Pro)
oracle.agents.activity({ id, cursor, limit });     // Agent activity (Pro)
oracle.agents.modelUsage({ period, limit });       // Model usage stats (Pro)
```

### Protocols

```typescript
oracle.protocols.list();                           // List all protocols
oracle.protocols.get({ id });                      // Get protocol by ID
oracle.protocols.metrics({ id });                  // Protocol metrics (Pro)
```

### Reports

```typescript
oracle.reports.latest();                           // Get latest report
oracle.reports.verify({ ...reportEnvelope });      // Verify report signature
```

## Pagination

Cursor-paginated endpoints return `{ data, pagination }`:

```typescript
let cursor: string | undefined;
do {
  const page = await oracle.agents.search({ q: "lucid", cursor });
  for (const agent of page.data) {
    console.log(agent);
  }
  cursor = page.pagination?.nextCursor ?? undefined;
} while (cursor);
```

## Error Handling

```typescript
import { LucidOracleError } from "@lucid-fdn/oracle/models/errors";

try {
  await oracle.agents.get({ id: "nonexistent" });
} catch (err) {
  if (err instanceof LucidOracleError) {
    console.error(err.statusCode, err.body);
  }
}
```

Error codes: 400 (validation), 401 (invalid key), 403 (tier required), 404 (not found), 429 (rate limited), 500 (internal). All errors follow RFC 9457 Problem Details format.

## License

Apache-2.0