npm package: @simpleapps-com/augur-api
Description: TypeScript client library for Augur microservices API endpoints
Author: SimpleEnigma
Latest version: 2026.4.6

# @simpleapps-com/augur-api

TypeScript client library for Augur microservices.

## Installation

```bash
npm install @simpleapps-com/augur-api
```

## Quick Start

```typescript
import { AugurAPI } from '@simpleapps-com/augur-api';

const api = new AugurAPI({
  siteId: process.env.AUGUR_SITE_ID,
  bearerToken: process.env.AUGUR_TOKEN,
});

// Access any service via api.{serviceName}
const items = await api.items.invMast.list({ limit: 10 });
const customers = await api.customers.customer.list({ limit: 10 });
const orders = await api.orders.orders.lookup({ limit: 10 });
```

## Service Access Pattern

All services are accessed through the unified `AugurAPI` client:

```typescript
api.items        // Items service
api.customers    // Customers service
api.orders       // Orders service
api.pricing      // Pricing service
api.commerce     // Commerce service
// ... 27 services total
```

## Documentation

| Resource | URL |
|----------|-----|
| **Full API Reference** | https://augur-api.info |
| **Endpoint Hints** | `https://{service}.augur-api.com/llms.txt` |
| **Parameters** | `https://{service}.augur-api.com/endpoints.jsonl` |
| **OpenAPI Spec** | `https://{service}.augur-api.com/openapi.json` |

### Example: Items Service

- https://items.augur-api.com/llms.txt
- https://items.augur-api.com/endpoints.jsonl
- https://items.augur-api.com/openapi.json

Each `llms.txt` lists all other available services for discovery.

## Authentication

All endpoints require:
- `siteId` - Site identifier
- `bearerToken` - Bearer authentication token

```typescript
const api = new AugurAPI({
  siteId: 'your-site-id',
  bearerToken: 'your-bearer-token',
});
```

## Configuration

```typescript
import { AugurAPI, AugurAPIConfig } from '@simpleapps-com/augur-api';

// With custom configuration
const config: AugurAPIConfig = {
  bearerToken: 'your-bearer-token',
  siteId: 'your-site-id',
  timeout: 30000,
  retries: 3,
  retryDelay: 1000,
};
const api = new AugurAPI(config);

// From context (for framework integration)
const api = AugurAPI.fromContext(context);
```

## Edge Caching

Enable Cloudflare edge caching on any GET request using the `edgeCache` parameter:

```typescript
// Sub-hour caching
const items = await api.items.invMast.list({ limit: 10, edgeCache: '30s' }); // 30 seconds
const items = await api.items.invMast.list({ limit: 10, edgeCache: '1m' });  // 1 minute
const items = await api.items.invMast.list({ limit: 10, edgeCache: '5m' });  // 5 minutes

// Hourly caching (1, 2, 3, 4, 5, or 8 hours)
const items = await api.items.invMast.list({ limit: 10, edgeCache: 1 });     // 1 hour
const items = await api.items.invMast.list({ limit: 10, edgeCache: 8 });     // 8 hours
```

| Value | Duration |
|-------|----------|
| `'30s'` | 30 seconds |
| `'1m'` | 1 minute |
| `'5m'` | 5 minutes |
| `1` - `5`, `8` | 1-5 or 8 hours |

The client automatically transforms `edgeCache` to Cloudflare's `cacheSiteId{N}` format.

## Error Handling

```typescript
import { AugurAPI } from '@simpleapps-com/augur-api';
import {
  AugurError,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  ValidationError,
} from '@simpleapps-com/augur-api';

const api = new AugurAPI({ siteId: '...', bearerToken: '...' });

try {
  const response = await api.items.invMast.get(12345);
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log(`Item not found: ${error.message}`);
  } else if (error instanceof AuthenticationError) {
    console.log(`Auth failed: ${error.message}`);
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited: ${error.message}`);
  } else if (error instanceof AugurError) {
    console.log(`API error: ${error.code} - ${error.message}`);
  }
}
```

## For AI Agents

See [SKILL.md](./SKILL.md) for guidance on using this package with AI assistance.

## License

MIT