@omen.dog/sdk 1.0.0

package/dist/index.mjs

@@ -0,0 +1,510 @@
+// src/errors.ts
+var OmenError = class extends Error {
+  /** HTTP status code from the API. */
+  status;
+  /** Machine-readable error code (e.g. "RATE_LIMITED", "NOT_FOUND"). */
+  code;
+  constructor(message, status, code) {
+    super(message);
+    this.name = "OmenError";
+    this.status = status;
+    this.code = code;
+  }
+};
+var OmenNotFoundError = class extends OmenError {
+  constructor(message = "Resource not found") {
+    super(message, 404, "NOT_FOUND");
+    this.name = "OmenNotFoundError";
+  }
+};
+var OmenAuthError = class extends OmenError {
+  constructor(message = "Authentication failed") {
+    super(message, 401, "AUTH_FAILED");
+    this.name = "OmenAuthError";
+  }
+};
+var OmenValidationError = class extends OmenError {
+  /** Field-level validation errors, if available. */
+  errors;
+  constructor(message, errors) {
+    super(message, 422, "VALIDATION_ERROR");
+    this.name = "OmenValidationError";
+    this.errors = errors;
+  }
+};
+var OmenRateLimitError = class extends OmenError {
+  /** Seconds until the rate limit resets. */
+  retryAfter;
+  /** Remaining requests in the current window. */
+  remaining;
+  constructor(message = "Rate limit exceeded", retryAfter, remaining) {
+    super(message, 429, "RATE_LIMITED");
+    this.name = "OmenRateLimitError";
+    this.retryAfter = retryAfter;
+    this.remaining = remaining;
+  }
+};
+
+// src/client.ts
+var HttpClient = class {
+  baseUrl;
+  token;
+  constructor(token, baseUrl) {
+    this.token = token;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+  }
+  async request(path, opts = {}) {
+    const url = new URL(path, this.baseUrl);
+    if (opts.query) {
+      for (const [k, v] of Object.entries(opts.query)) {
+        if (v !== void 0) url.searchParams.set(k, String(v));
+      }
+    }
+    const headers = {
+      "Authorization": `Bearer ${this.token}`,
+      "Accept": "application/json",
+      ...opts.headers
+    };
+    if (opts.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    const res = await fetch(url.toString(), {
+      method: opts.method ?? "GET",
+      headers,
+      body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0
+    });
+    if (!res.ok) {
+      await this.handleError(res);
+    }
+    const text = await res.text();
+    return text ? JSON.parse(text) : {};
+  }
+  async handleError(res) {
+    let body = {};
+    try {
+      body = await res.json();
+    } catch {
+    }
+    const message = body.error || body.message || res.statusText;
+    switch (res.status) {
+      case 401:
+      case 403:
+        throw new OmenAuthError(message);
+      case 404:
+        throw new OmenNotFoundError(message);
+      case 422:
+        throw new OmenValidationError(message, body.errors);
+      case 429: {
+        const retryAfter = res.headers.get("Retry-After");
+        const remaining = res.headers.get("X-RateLimit-Remaining");
+        throw new OmenRateLimitError(
+          message,
+          retryAfter ? Number(retryAfter) : void 0,
+          remaining ? Number(remaining) : void 0
+        );
+      }
+      default:
+        throw new OmenError(message, res.status);
+    }
+  }
+};
+
+// src/namespaces/users.ts
+var UsersNamespace = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get a user's profile by ID or username.
+   *
+   * @example
+   * ```ts
+   * const profile = await omen.users.get('pistolphoenix');
+   * console.log(profile.user.username, profile.stats.creationsCount);
+   * ```
+   */
+  async get(userId) {
+    return this.http.request(`/api/v1/users/${encodeURIComponent(userId)}/profile`);
+  }
+  /**
+   * Get a user's friend list with optional filtering and pagination.
+   *
+   * @example
+   * ```ts
+   * const { friends, onlineCount } = await omen.users.friends('pistolphoenix', {
+   *   status: 'online',
+   *   limit: 10,
+   * });
+   * ```
+   */
+  async friends(userId, options = {}) {
+    return this.http.request(`/api/v1/users/${encodeURIComponent(userId)}/friends`, {
+      query: {
+        status: options.status,
+        sort: options.sort,
+        search: options.search,
+        cursor: options.cursor,
+        limit: options.limit
+      }
+    });
+  }
+};
+
+// src/namespaces/storage.ts
+var StorageNamespace = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get the current user's stored data for your app.
+   *
+   * @example
+   * ```ts
+   * const { data } = await omen.storage.get();
+   * console.log(data.highScore);
+   * ```
+   */
+  async get() {
+    return this.http.request("/api/appdata");
+  }
+  /**
+   * Replace the current user's stored data entirely.
+   *
+   * @example
+   * ```ts
+   * await omen.storage.set({ highScore: 100, level: 5 });
+   * ```
+   */
+  async set(data) {
+    return this.http.request("/api/appdata", {
+      method: "PUT",
+      body: { data }
+    });
+  }
+  /**
+   * Shallow-merge fields into the current user's stored data.
+   * Existing fields not in the payload are preserved.
+   *
+   * @example
+   * ```ts
+   * await omen.storage.merge({ highScore: 200 }); // keeps 'level' intact
+   * ```
+   */
+  async merge(data) {
+    return this.http.request("/api/appdata", {
+      method: "PATCH",
+      body: { data }
+    });
+  }
+};
+
+// src/namespaces/items.ts
+var ItemsNamespace = class {
+  constructor(http, appId) {
+    this.http = http;
+    this.appId = appId;
+  }
+  /**
+   * Issue a single item to a user.
+   *
+   * @example
+   * ```ts
+   * const item = await omen.items.issue({
+   *   userId: 'cmm0tzco8...',
+   *   name: 'Dragon Slayer Badge',
+   *   type: 'achievement',
+   *   rarity: 'legendary',
+   * });
+   * ```
+   */
+  async issue(options) {
+    return this.http.request(`/api/v1/apps/${this.appId}/items/issue`, {
+      method: "POST",
+      body: options
+    });
+  }
+  /**
+   * Issue multiple items in one request. Maximum 100 items per batch.
+   *
+   * @example
+   * ```ts
+   * const { items, count } = await omen.items.issueBatch([
+   *   { userId: 'user1', name: 'Gold Medal', type: 'achievement' },
+   *   { userId: 'user2', name: 'Silver Medal', type: 'achievement' },
+   * ]);
+   * ```
+   */
+  async issueBatch(items) {
+    return this.http.request(`/api/v1/apps/${this.appId}/items/issue-batch`, {
+      method: "POST",
+      body: { items }
+    });
+  }
+  /**
+   * Revoke an item. Idempotent — re-revoking a revoked item returns 200.
+   *
+   * @example
+   * ```ts
+   * await omen.items.revoke('item_abc123', 'Violated terms of service');
+   * ```
+   */
+  async revoke(itemId, reason) {
+    return this.http.request(`/api/v1/apps/${this.appId}/items/${encodeURIComponent(itemId)}/revoke`, {
+      method: "POST",
+      body: { reason }
+    });
+  }
+};
+
+// src/namespaces/collections.ts
+var CollectionsNamespace = class {
+  constructor(http, appId) {
+    this.http = http;
+    this.appId = appId;
+  }
+  /**
+   * Create a new collection.
+   *
+   * @example
+   * ```ts
+   * const col = await omen.collections.create({
+   *   name: 'player_stats',
+   *   schema: { score: 'number', level: 'number', name: 'string' },
+   *   indexedFields: ['score'],
+   * });
+   * ```
+   */
+  async create(options) {
+    return this.http.request(`/api/v1/apps/${this.appId}/collections`, {
+      method: "POST",
+      body: options
+    });
+  }
+  /** List all collections for your app. */
+  async list() {
+    return this.http.request(`/api/v1/apps/${this.appId}/collections`);
+  }
+  /** Get a single collection by name. */
+  async get(name) {
+    return this.http.request(`/api/v1/apps/${this.appId}/collections/${encodeURIComponent(name)}`);
+  }
+  /**
+   * Delete a collection and all its documents. This is irreversible.
+   */
+  async delete(name) {
+    return this.http.request(`/api/v1/apps/${this.appId}/collections/${encodeURIComponent(name)}`, {
+      method: "DELETE"
+    });
+  }
+  // ── Documents ──────────────────────────────
+  /**
+   * Insert a single document into a collection.
+   *
+   * @example
+   * ```ts
+   * const doc = await omen.collections.insert('player_stats', {
+   *   score: 1500,
+   *   level: 12,
+   *   name: 'PistolPhoenix',
+   * });
+   * ```
+   */
+  async insert(collection, data) {
+    return this.http.request(this.docsPath(collection), {
+      method: "POST",
+      body: { data }
+    });
+  }
+  /**
+   * Insert multiple documents at once. Maximum 100 per batch.
+   */
+  async insertBatch(collection, documents) {
+    return this.http.request(this.docsPath(collection), {
+      method: "POST",
+      body: { documents }
+    });
+  }
+  /**
+   * Query documents with optional filtering, sorting, and pagination.
+   *
+   * @example
+   * ```ts
+   * const { documents } = await omen.collections.query('player_stats', {
+   *   where: { level: { $gte: 10 } },
+   *   sort: { score: -1 },
+   *   limit: 20,
+   * });
+   * ```
+   */
+  async query(collection, options = {}) {
+    return this.http.request(this.docsPath(collection), {
+      query: {
+        where: options.where ? JSON.stringify(options.where) : void 0,
+        sort: options.sort ? JSON.stringify(options.sort) : void 0,
+        limit: options.limit,
+        offset: options.offset,
+        count: options.count ? "true" : void 0
+      }
+    });
+  }
+  /** Get a single document by ID. */
+  async getDocument(collection, documentId) {
+    return this.http.request(`${this.docsPath(collection)}/${encodeURIComponent(documentId)}`);
+  }
+  /** Update a document's data (shallow merge). */
+  async updateDocument(collection, documentId, data) {
+    return this.http.request(`${this.docsPath(collection)}/${encodeURIComponent(documentId)}`, {
+      method: "PATCH",
+      body: { data }
+    });
+  }
+  /** Delete a single document. */
+  async deleteDocument(collection, documentId) {
+    return this.http.request(`${this.docsPath(collection)}/${encodeURIComponent(documentId)}`, {
+      method: "DELETE"
+    });
+  }
+  /** Get the document count for a collection, with optional filter. */
+  async count(collection, where) {
+    return this.http.request(`/api/v1/apps/${this.appId}/collections/${encodeURIComponent(collection)}/count`, {
+      query: { where: where ? JSON.stringify(where) : void 0 }
+    });
+  }
+  /**
+   * Execute up to 5 operations atomically (Pro+ tier).
+   *
+   * @example
+   * ```ts
+   * const { results } = await omen.collections.transaction('game_state', [
+   *   { type: 'get', id: 'player_1' },
+   *   { type: 'update', id: 'player_1', data: { health: 50 } },
+   * ]);
+   * ```
+   */
+  async transaction(collection, operations) {
+    return this.http.request(
+      `/api/v1/apps/${this.appId}/collections/${encodeURIComponent(collection)}/transaction`,
+      { method: "POST", body: { operations } }
+    );
+  }
+  docsPath(collection) {
+    return `/api/v1/apps/${this.appId}/collections/${encodeURIComponent(collection)}/documents`;
+  }
+};
+
+// src/namespaces/webhooks.ts
+var WebhooksNamespace = class {
+  constructor(http, appId) {
+    this.http = http;
+    this.appId = appId;
+  }
+  /**
+   * Register a new webhook endpoint.
+   * The `secret` field is only returned on creation — store it securely.
+   *
+   * @example
+   * ```ts
+   * const webhook = await omen.webhooks.create({
+   *   url: 'https://myapp.com/webhooks/omen',
+   *   events: ['item.issued', 'friend.added'],
+   * });
+   * console.log(webhook.secret); // save this!
+   * ```
+   */
+  async create(options) {
+    return this.http.request(`/api/v1/apps/${this.appId}/webhooks`, {
+      method: "POST",
+      body: options
+    });
+  }
+  /** List all webhook endpoints for your app. Secrets are not included. */
+  async list() {
+    return this.http.request(`/api/v1/apps/${this.appId}/webhooks`);
+  }
+  /** Get a single webhook endpoint. Secret is not included. */
+  async get(endpointId) {
+    return this.http.request(`/api/v1/apps/${this.appId}/webhooks/${encodeURIComponent(endpointId)}`);
+  }
+  /** Delete a webhook endpoint. */
+  async delete(endpointId) {
+    return this.http.request(`/api/v1/apps/${this.appId}/webhooks/${encodeURIComponent(endpointId)}`, {
+      method: "DELETE"
+    });
+  }
+  /**
+   * Verify an incoming webhook signature. Use this in your webhook handler
+   * to confirm the request came from Omen.
+   *
+   * @param payload - The raw request body string.
+   * @param signature - The `X-Omen-Signature` header value.
+   * @param secret - The webhook secret from `create()`.
+   * @returns `true` if the signature is valid.
+   *
+   * @example
+   * ```ts
+   * app.post('/webhooks/omen', (req, res) => {
+   *   const valid = omen.webhooks.verify(
+   *     req.body, // raw string
+   *     req.headers['x-omen-signature'],
+   *     process.env.OMEN_WEBHOOK_SECRET,
+   *   );
+   *   if (!valid) return res.status(401).send('Bad signature');
+   *   // handle event...
+   * });
+   * ```
+   */
+  async verify(payload, signature, secret) {
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey(
+      "raw",
+      encoder.encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    );
+    const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+    const expected = Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+    return timingSafeEqual(expected, signature);
+  }
+};
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}
+
+// src/index.ts
+var OmenClient = class {
+  /** User profiles and friend lists. */
+  users;
+  /** Per-user key-value storage. */
+  storage;
+  /** Issue, revoke, and batch-manage items. */
+  items;
+  /** Structured data collections (document database). */
+  collections;
+  /** Webhook endpoint management and signature verification. */
+  webhooks;
+  constructor(options) {
+    if (!options.token) throw new Error("OmenClient: token is required");
+    if (!options.appId) throw new Error("OmenClient: appId is required");
+    const baseUrl = options.baseUrl ?? "https://omen.dog";
+    const http = new HttpClient(options.token, baseUrl);
+    this.users = new UsersNamespace(http);
+    this.storage = new StorageNamespace(http);
+    this.items = new ItemsNamespace(http, options.appId);
+    this.collections = new CollectionsNamespace(http, options.appId);
+    this.webhooks = new WebhooksNamespace(http, options.appId);
+  }
+};
+export {
+  OmenAuthError,
+  OmenClient,
+  OmenError,
+  OmenNotFoundError,
+  OmenRateLimitError,
+  OmenValidationError
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@omen.dog/sdk",
+  "version": "1.0.0",
+  "description": "Official server-side TypeScript SDK for the Omen platform",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./creation": {
+      "types": "./dist/creation.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean && cp src/creation.d.ts dist/creation.d.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "omen",
+    "game-platform",
+    "sdk",
+    "api-client"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/omen-dog/sdk"
+  },
+  "homepage": "https://omen.dog/docs"
+}