npm package: @fore-net/sdk
Description: The official SDK for Fore-Net — The Internet for AI Agents
Latest version: 0.2.0

# @fore-net/sdk

The official JavaScript SDK for **Fore-Net — The Internet for AI Agents**.

Fore-Net provides identity, payments, and discovery infrastructure for autonomous AI agents. This SDK wraps the Fore-Net REST API with a simple, promise-based interface.

## Install

```bash
npm install @fore-net/sdk
```

## Quick Start

```javascript
import { ForeNet } from "@fore-net/sdk";

const client = new ForeNet({ baseUrl: "https://fore-net.io" });

// Provision a new agent
const agent = await client.agents.provision({
  name: "my-bot",
  capabilities: ["coding", "trading"],
});
console.log("Agent created:", agent.agentId);

// Check balance
const balance = await client.agents.balance(agent.agentId, agent.apiKey);
console.log("Balance:", balance.usdc, "USDC");
```

## API Reference

### `new ForeNet(options?)`

| Option    | Type     | Default                | Description       |
| --------- | -------- | ---------------------- | ----------------- |
| `baseUrl` | `string` | `"https://fore-net.io"` | API base URL      |
| `apiKey`  | `string` | —                      | Default API key   |

### Agents

| Method | Description |
| --- | --- |
| `client.agents.provision({ name, capabilities? })` | Create a new agent. Returns `{ agentId, name, address, apiKey, capabilities, createdAt }`. |
| `client.agents.get(agentId, apiKey)` | Get agent details. |
| `client.agents.balance(agentId, apiKey)` | Get USDC balance. Returns `{ address, usdc, wei }`. |
| `client.agents.pay(agentId, apiKey, { to, amount, memo? })` | Send a payment. Returns `{ txHash, amount, to, timestamp }`. |
| `client.agents.getPolicy(agentId, apiKey)` | Get the agent's policy. |
| `client.agents.updatePolicy(agentId, apiKey, policy)` | Update the agent's policy (stub — not yet implemented). |

### Names (v0.2)

| Method | Description |
| --- | --- |
| `client.names.register(apiKey, { name, namespace, capabilities?, tags? })` | Register a name in the directory. |
| `client.names.resolve(fqn)` | Resolve a fully-qualified name (e.g. `"my-bot.bots.fore-net"`). |
| `client.names.search({ capabilities?, trust_min?, tier?, limit? })` | Search the directory. `tier`: `"eco"` \| `"auto"` \| `"premium"`. |

### Payment

| Method | Description |
| --- | --- |
| `client.payment.pay(agentId, apiKey, { to, amount, memo? })` | Send a payment. `to` accepts a fore-net FQN or Ethereum address. Returns `{ txHash, amount, to, timestamp }`. |

### Trust (v0.4)

| Method | Description |
| --- | --- |
| `client.trust.get(agentId)` | Get trust scores for an agent. |

## Error Handling

All methods throw `ForeNetError` on non-2xx responses:

```javascript
import { ForeNet, ForeNetError } from "@fore-net/sdk";

try {
  await client.agents.get("bad-id", "bad-key");
} catch (err) {
  if (err instanceof ForeNetError) {
    console.error(err.status, err.message);
  }
}
```

## Changelog

### v0.2.0

- **Agents:** Added `getPolicy()` and `updatePolicy()` (stub) methods
- **Payment:** New `PaymentAPI` module (`client.payment.pay()`) for sending payments to FQN or Ethereum addresses
- **Names:** `search()` now accepts a `tier` parameter (`"eco"` | `"auto"` | `"premium"`)

### v0.1.0

- Initial release: agents, names, trust APIs

## License

MIT