@omen.dog/sdk 1.0.0

package/README.md

@@ -0,0 +1,147 @@
+# @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

package/dist/creation.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Type definitions for the Omen Creation Runtime SDK.
+ *
+ * Add to your creation's tsconfig.json or use a triple-slash directive:
+ * ```ts
+ * /// <reference types="@omen.dog/sdk/creation" />
+ * ```
+ *
+ * This provides autocomplete for the `omen.*` global available inside creations.
+ * Zero runtime cost — types only.
+ */
+
+interface OmenStorageAPI {
+  /** Load the user's saved data for this creation. */
+  load(): Promise<Record<string, unknown> | null>;
+  /** Save data for the current user. */
+  save(data: Record<string, unknown>): Promise<void>;
+  /** Delete the user's saved data. */
+  delete(): Promise<void>;
+}
+
+interface OmenCollectionsAPI {
+  /** Insert a document into a collection. */
+  insert(collection: string, data: Record<string, unknown>): Promise<{ id: string }>;
+  /** Find documents in a collection. */
+  find(collection: string, query?: {
+    where?: Record<string, unknown>;
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    offset?: number;
+  }): Promise<{ documents: Array<{ id: string; data: Record<string, unknown> }> }>;
+  /** Update a document. */
+  update(collection: string, docId: string, data: Record<string, unknown>): Promise<void>;
+  /** Delete a document. */
+  delete(collection: string, docId: string): Promise<void>;
+}
+
+interface OmenInputAPI {
+  /** True while the key/button is held. */
+  isDown(action: 'action' | 'secondary' | 'up' | 'down' | 'left' | 'right'): boolean;
+  /** True for one frame on press. */
+  pressed(action: 'action' | 'secondary' | 'up' | 'down' | 'left' | 'right'): boolean;
+  /** True for one frame on release. */
+  released(action: 'action' | 'secondary' | 'up' | 'down' | 'left' | 'right'): boolean;
+  /** Register a callback on press. */
+  on(action: string, fn: () => void): void;
+  /** Pointer state (normalized 0-1 coordinates). */
+  pointer: { x: number; y: number; down: boolean };
+  /** Show the virtual joystick on mobile. */
+  joystick(): void;
+  /** Virtual joystick position (-1 to 1). */
+  stick: { x: number; y: number };
+}
+
+interface OmenDeviceAPI {
+  type: 'mobile' | 'tablet' | 'desktop';
+  touch: boolean;
+  keyboard: boolean;
+  width: number;
+  height: number;
+  orientation: 'portrait' | 'landscape';
+  on(event: 'resize', fn: () => void): void;
+}
+
+interface OmenSDK {
+  /** Current user info. */
+  me: { id: string; username: string; avatar: string | null };
+
+  // Storage
+  load(): Promise<Record<string, unknown> | null>;
+  save(data: Record<string, unknown>): Promise<void>;
+
+  // Collections
+  collections: OmenCollectionsAPI;
+
+  // Economy
+  buy(productId: string): Promise<{ success: boolean; item?: unknown; newBalance?: number }>;
+  owns(itemId: string): boolean;
+  inventory(): Promise<Array<{ id: string; name: string; type: string }>>;
+
+  // Items & Badges
+  hasItem(itemId: string): boolean;
+  hasBadge(badgeId: string): boolean;
+
+  // Social
+  friends(): Promise<Array<{ id: string; username: string; avatar: string | null; status: string }>>;
+  invite(friendId: string): Promise<void>;
+  presence(text: string | null): void;
+
+  // Companion
+  companion(): Promise<{ name: string; mood: string; traits: string[] } | null>;
+
+  // Input
+  input: OmenInputAPI;
+
+  // Device
+  device: OmenDeviceAPI;
+
+  // Moderation
+  filter(text: string, options?: { context?: 'username' | 'content'; mode?: 'check' }): Promise<string | { allowed: boolean; reason?: string }>;
+  isChild(): boolean;
+  report(userId: string, reason: string): Promise<void>;
+
+  // Leaderboards
+  score(value: number, options?: { board?: string; metadata?: Record<string, unknown> }): Promise<{ rank: number; score: number; isNewBest: boolean; previousRank: number | null }>;
+  leaderboard(options?: { board?: string; friends?: boolean; period?: 'all' | 'week' | 'month' }): Promise<{ entries: Array<{ rank: number; userId: string; username: string; score: number }>; board: string; userRank: number | null }>;
+  showLeaderboard(board?: string): void;
+
+  // Haptics
+  vibrate(type: 'light' | 'medium' | 'heavy' | 'success' | 'error'): void;
+
+  // Feature detection
+  has(feature: 'storage' | 'collections' | 'economy' | 'identity' | 'input' | 'social' | 'companion' | 'moderation' | 'leaderboard'): boolean;
+}
+
+declare const omen: OmenSDK;