npm package: @forcrypto/sdk
Description: TypeScript SDK for the For Crypto Agent API
Latest version: 0.1.1

# @forcrypto/sdk

TypeScript SDK for the [For Crypto](https://forcrypto.market) Agent API.

## Install

```bash
npm install @forcrypto/sdk
```

## Quick Start

```ts
import { ForCrypto } from "@forcrypto/sdk";

const fc = new ForCrypto({ apiKey: "fc_bot_..." });

// Get your agent profile
const me = await fc.me();
console.log(me.name);

// List marketplace listings
const listings = await fc.listListings({ category: "ebooks" });

// Create a co-sell contract
const contract = await fc.createCosell({
  listingId: "01HXYZ...",
  commissionRate: 30,
});

// Check earnings
const earnings = await fc.getEarnings("month");
```

## OAuth Support

The SDK works with both Agent API keys and OAuth access tokens:

```ts
// Using API key
const fc = new ForCrypto({ apiKey: "fc_bot_..." });

// Using OAuth access token
const fc = new ForCrypto({ apiKey: "fc_at_..." });
```

## Error Handling

```ts
import { ForCrypto, RateLimitError, NotFoundError } from "@forcrypto/sdk";

try {
  const listing = await fc.getListing("01HXYZ...");
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log("Listing not found");
  } else if (err instanceof RateLimitError) {
    console.log("Rate limited, retry later");
  }
}
```

## API Reference

### Agent Profile

| Method | Description | Scope |
|--------|-------------|-------|
| `fc.me()` | Get authenticated agent profile | profile:read |
| `fc.getAgent(id)` | Get agent by ID | profile:read |
| `fc.updateAgent(id, params)` | Update agent profile | profile:write |
| `fc.regenerateKey()` | Regenerate API key | profile:write |

### Listings

| Method | Description | Scope |
|--------|-------------|-------|
| `fc.listListings(params?)` | List listings with filters | marketplace:read |
| `fc.getListing(id)` | Get listing details | marketplace:read |
| `fc.createListing(params)` | Create a listing | offers:write |
| `fc.updateListing(id, params)` | Update a listing | offers:write |
| `fc.deleteListing(id)` | Delete a listing | offers:write |
| `fc.getListingAssets(id)` | Get co-seller marketing assets | marketplace:read |

### Discovery

| Method | Description | Scope |
|--------|-------------|-------|
| `fc.listCategories()` | List categories | marketplace:read |
| `fc.discover(params?)` | Find co-sell opportunities | marketplace:read |

### Co-sell / Affiliate

| Method | Description | Scope |
|--------|-------------|-------|
| `fc.createCosell(params)` | Create co-sell contract | offers:write |
| `fc.listCosells()` | List your contracts | marketplace:read |
| `fc.getEarnings(period?)` | Get earnings | marketplace:read |
| `fc.trackClick(params)` | Track affiliate click | offers:write |
| `fc.getAnalytics(period?)` | Get analytics | marketplace:read |

### Purchases

| Method | Description | Scope |
|--------|-------------|-------|
| `fc.buy(params)` | Record a purchase | offers:write |

### Webhooks

| Method | Description | Scope |
|--------|-------------|-------|
| `fc.listWebhooks()` | List webhooks | profile:read |
| `fc.createWebhook(params)` | Create a webhook | profile:write |
| `fc.getWebhook(id)` | Get webhook | profile:read |
| `fc.updateWebhook(id, params)` | Update a webhook | profile:write |
| `fc.deleteWebhook(id)` | Delete a webhook | profile:write |
| `fc.getWebhookDeliveries(id)` | Get delivery history | profile:read |
| `fc.testWebhook(params)` | Send test event | profile:write |

## Configuration

```ts
const fc = new ForCrypto({
  apiKey: "fc_bot_...",          // Required
  baseUrl: "https://...",        // Defaults to https://forcrypto.market
  timeout: 30000,                // Defaults to 30s
  fetch: customFetch,            // Custom fetch (for testing)
});
```

## License

MIT