npm package: @omen.dog/sdk
Description: Official server-side TypeScript SDK for the Omen platform
Latest version: 1.0.0

# @omen.dog/sdk

Official server-side TypeScript SDK for the [Omen](https://omen.dog) platform.

## Install

```bash
npm install @omen.dog/sdk
```

Requires Node.js 18+ (uses native `fetch`). Zero dependencies.

## Quick Start

```ts
import { OmenClient } from '@omen.dog/sdk';

const omen = new OmenClient({
  token: process.env.OMEN_TOKEN!,  // dev_yourorg_abc123...
  appId: 'your-app-id',           // from the Developer Portal
});
```

## Namespaces

### Users

```ts
const profile = await omen.users.get('pistolphoenix');
const { friends, onlineCount } = await omen.users.friends('pistolphoenix', {
  status: 'online',
  limit: 10,
});
```

### Storage

Per-user key-value storage scoped to your app.

```ts
const { data } = await omen.storage.get();
await omen.storage.set({ highScore: 100, level: 5 });
await omen.storage.merge({ highScore: 200 }); // keeps 'level' intact
```

### Items

Issue achievements, collectibles, and in-game items to users.

```ts
const item = await omen.items.issue({
  userId: 'cmm0tzco8...',
  name: 'Dragon Slayer',
  type: 'achievement',
  rarity: 'legendary',
});

// Batch issue (up to 100)
const { items } = await omen.items.issueBatch([
  { userId: 'user1', name: 'Gold Medal', type: 'achievement' },
  { userId: 'user2', name: 'Silver Medal', type: 'achievement' },
]);

// Revoke
await omen.items.revoke(item.id, 'Violated terms');
```

### Collections

Structured data storage — like a simple document database.

```ts
// Create a collection with schema
await omen.collections.create({
  name: 'player_stats',
  schema: { score: 'number', level: 'number', name: 'string' },
  indexedFields: ['score'],
});

// Insert documents
const doc = await omen.collections.insert('player_stats', {
  score: 1500, level: 12, name: 'PistolPhoenix',
});

// Query with filters
const { documents } = await omen.collections.query('player_stats', {
  where: { level: { $gte: 10 } },
  sort: { score: -1 },
  limit: 20,
});

// Atomic transactions (Pro+ tier)
const { results } = await omen.collections.transaction('game_state', [
  { type: 'get', id: 'player_1' },
  { type: 'update', id: 'player_1', data: { health: 50 } },
]);
```

### Webhooks

```ts
// Register (secret is only returned once!)
const webhook = await omen.webhooks.create({
  url: 'https://myapp.com/webhooks/omen',
  events: ['item.issued', 'friend.added'],
});
console.log(webhook.secret); // save this!

// Verify incoming webhooks
const valid = await omen.webhooks.verify(rawBody, signature, secret);
```

## Creation Runtime Types

For creation developers — get autocomplete for the `omen.*` global:

```ts
/// <reference types="@omen.dog/sdk/creation" />

const save = await omen.load();
omen.score(100);
```

## Error Handling

```ts
import { OmenClient, OmenNotFoundError, OmenRateLimitError } from '@omen.dog/sdk';

try {
  await omen.users.get('nonexistent');
} catch (err) {
  if (err instanceof OmenNotFoundError) {
    console.log('User not found');
  }
  if (err instanceof OmenRateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  }
}
```

## API Reference

Full documentation at [omen.dog/docs](https://omen.dog/docs).

## License

MIT