@omen.dog/sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,559 @@
+interface RequestOptions {
+    method?: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+}
+/**
+ * Low-level HTTP client. All namespace methods delegate to this.
+ * Not exported — consumers use OmenClient directly.
+ */
+declare class HttpClient {
+    readonly baseUrl: string;
+    private readonly token;
+    constructor(token: string, baseUrl: string);
+    request<T = unknown>(path: string, opts?: RequestOptions): Promise<T>;
+    private handleError;
+}
+
+interface OmenClientOptions {
+    /** Developer token (starts with `dev_`). Required. */
+    token: string;
+    /** Base URL for the Omen API. Defaults to `https://omen.dog`. */
+    baseUrl?: string;
+}
+interface UserProfile {
+    id: string;
+    username: string;
+    name: string | null;
+    image: string | null;
+    bio: string | null;
+    moodEmoji: string | null;
+    moodText: string | null;
+    theme: string | null;
+    accentColor: string | null;
+    totalStarsReceived: number;
+    prestigeTier: string | null;
+    createdAt: string;
+}
+interface UserProfileResponse {
+    user: UserProfile;
+    viewerContext: 'owner' | 'friend' | 'user' | 'anonymous';
+    isOwner: boolean;
+    stats: {
+        creationsCount: number;
+        itemsCount: number;
+        badgesCount: number;
+    };
+    pinnedCreations: PinnedCreation[];
+    featuredItems: FeaturedItem[];
+    badges: Badge[];
+    friends: Friend[];
+}
+interface PinnedCreation {
+    id: string;
+    name: string;
+    slug: string;
+    thumbnailUrl: string | null;
+    liveUrl: string | null;
+    category: string | null;
+    hostingType: string;
+    iconUrl: string | null;
+    starCount: number;
+    uniqueUserCount: number;
+}
+interface FeaturedItem {
+    id: string;
+    name: string;
+    imageUrl: string | null;
+    thumbnailUrl: string | null;
+    rarity: string | null;
+    type: string | null;
+}
+interface Badge {
+    id: string;
+    name: string;
+    description: string | null;
+    imageUrl: string | null;
+    category: string | null;
+    tier: string | null;
+    org: {
+        id: string;
+        name: string;
+        image: string | null;
+    };
+}
+interface Friend {
+    user: {
+        id: string;
+        username: string;
+        name: string | null;
+        image: string | null;
+        prestigeTier: string | null;
+    };
+    presence: {
+        status: 'offline' | 'online' | 'playing';
+        presenceText?: string;
+        lastSeenAt?: string;
+    };
+    acceptedAt: string;
+    friendshipId: string;
+    creationCount: number;
+}
+interface FriendsListOptions {
+    status?: 'online' | 'offline';
+    sort?: 'active' | 'stars' | 'creations' | 'alpha' | 'newest';
+    search?: string;
+    cursor?: string;
+    limit?: number;
+}
+interface FriendsListResponse {
+    friends: Friend[];
+    total: number;
+    onlineCount: number;
+    nextCursor: string | null;
+}
+interface StorageData {
+    data: Record<string, unknown>;
+}
+type ItemType = 'avatar_trait' | 'collectible' | 'achievement' | 'in_game_item' | 'physical_good' | 'profile_decoration';
+type AcquisitionType = 'purchase' | 'transfer' | 'gift' | 'earn' | 'redeem' | 'mint';
+interface IssueItemOptions {
+    userId: string;
+    templateId?: string;
+    name?: string;
+    type?: ItemType;
+    description?: string;
+    imageUrl?: string;
+    thumbnailUrl?: string;
+    rarity?: string;
+    metadata?: Record<string, unknown>;
+    tags?: string[];
+    acquisitionType?: AcquisitionType;
+    transferable?: boolean;
+    listable?: boolean;
+    soulbound?: boolean;
+}
+interface Item {
+    id: string;
+    name: string;
+    type: ItemType;
+    ownerId: string;
+    originAppId: string;
+    templateId: string | null;
+    description: string | null;
+    imageUrl: string | null;
+    thumbnailUrl: string | null;
+    rarity: string | null;
+    editionNumber: number | null;
+    metadata: Record<string, unknown> | null;
+    tags: string[];
+    acquisitionType: AcquisitionType;
+    transferable: boolean;
+    listable: boolean;
+    soulbound: boolean;
+    acquiredAt: string;
+    revokedAt: string | null;
+    revokedReason: string | null;
+}
+interface BatchIssueResponse {
+    items: Item[];
+    count: number;
+}
+type SchemaFieldType = 'string' | 'number' | 'boolean' | 'date';
+interface CreateCollectionOptions {
+    name: string;
+    schema?: Record<string, SchemaFieldType>;
+    indexedFields?: string[];
+}
+interface Collection {
+    name: string;
+    schema: Record<string, SchemaFieldType> | null;
+    indexedFields: string[];
+    documentCount: number;
+    maxDocuments: number;
+    createdAt: string;
+}
+interface Document {
+    id: string;
+    data: Record<string, unknown>;
+    ownerId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface QueryDocumentsOptions {
+    where?: Record<string, unknown>;
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    offset?: number;
+    count?: boolean;
+}
+interface QueryDocumentsResponse {
+    documents: Document[];
+    total?: number;
+}
+interface TransactionOperation {
+    type: 'get' | 'insert' | 'update' | 'delete';
+    id?: string;
+    data?: Record<string, unknown>;
+    merge?: boolean;
+}
+interface TransactionResponse {
+    results: Array<null | Document | {
+        deleted: string;
+    }>;
+}
+interface CreateWebhookOptions {
+    url: string;
+    events: string[];
+}
+interface Webhook {
+    id: string;
+    appId: string;
+    url: string;
+    events: string[];
+    secret?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/** Read-only access to Omen user profiles and friend lists. */
+declare class UsersNamespace {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * 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);
+     * ```
+     */
+    get(userId: string): Promise<UserProfileResponse>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    friends(userId: string, options?: FriendsListOptions): Promise<FriendsListResponse>;
+}
+
+/**
+ * Per-user key-value storage for your app.
+ *
+ * Each user gets one JSON blob scoped to your app. Use `set()` to replace it entirely
+ * or `merge()` to shallow-merge fields into the existing blob.
+ */
+declare class StorageNamespace {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get the current user's stored data for your app.
+     *
+     * @example
+     * ```ts
+     * const { data } = await omen.storage.get();
+     * console.log(data.highScore);
+     * ```
+     */
+    get(): Promise<StorageData>;
+    /**
+     * Replace the current user's stored data entirely.
+     *
+     * @example
+     * ```ts
+     * await omen.storage.set({ highScore: 100, level: 5 });
+     * ```
+     */
+    set(data: Record<string, unknown>): Promise<StorageData>;
+    /**
+     * 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
+     * ```
+     */
+    merge(data: Record<string, unknown>): Promise<StorageData>;
+}
+
+/**
+ * Issue, revoke, and manage items for users in your app.
+ *
+ * Items are cross-app assets (achievements, collectibles, in-game items) that
+ * users own and can display on their profile.
+ */
+declare class ItemsNamespace {
+    private readonly http;
+    private readonly appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * 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',
+     * });
+     * ```
+     */
+    issue(options: IssueItemOptions): Promise<Item>;
+    /**
+     * 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' },
+     * ]);
+     * ```
+     */
+    issueBatch(items: IssueItemOptions[]): Promise<BatchIssueResponse>;
+    /**
+     * Revoke an item. Idempotent — re-revoking a revoked item returns 200.
+     *
+     * @example
+     * ```ts
+     * await omen.items.revoke('item_abc123', 'Violated terms of service');
+     * ```
+     */
+    revoke(itemId: string, reason?: string): Promise<Item>;
+}
+
+/**
+ * Structured data collections — like a simple document database scoped to your app.
+ *
+ * Collections have optional schemas, indexed fields, and support queries with
+ * filtering, sorting, and pagination.
+ */
+declare class CollectionsNamespace {
+    private readonly http;
+    private readonly appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * Create a new collection.
+     *
+     * @example
+     * ```ts
+     * const col = await omen.collections.create({
+     *   name: 'player_stats',
+     *   schema: { score: 'number', level: 'number', name: 'string' },
+     *   indexedFields: ['score'],
+     * });
+     * ```
+     */
+    create(options: CreateCollectionOptions): Promise<Collection>;
+    /** List all collections for your app. */
+    list(): Promise<{
+        collections: Collection[];
+    }>;
+    /** Get a single collection by name. */
+    get(name: string): Promise<Collection>;
+    /**
+     * Delete a collection and all its documents. This is irreversible.
+     */
+    delete(name: string): Promise<{
+        deleted: true;
+    }>;
+    /**
+     * Insert a single document into a collection.
+     *
+     * @example
+     * ```ts
+     * const doc = await omen.collections.insert('player_stats', {
+     *   score: 1500,
+     *   level: 12,
+     *   name: 'PistolPhoenix',
+     * });
+     * ```
+     */
+    insert(collection: string, data: Record<string, unknown>): Promise<Document>;
+    /**
+     * Insert multiple documents at once. Maximum 100 per batch.
+     */
+    insertBatch(collection: string, documents: Record<string, unknown>[]): Promise<{
+        documents: Document[];
+        count: number;
+    }>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    query(collection: string, options?: QueryDocumentsOptions): Promise<QueryDocumentsResponse>;
+    /** Get a single document by ID. */
+    getDocument(collection: string, documentId: string): Promise<Document>;
+    /** Update a document's data (shallow merge). */
+    updateDocument(collection: string, documentId: string, data: Record<string, unknown>): Promise<Document>;
+    /** Delete a single document. */
+    deleteDocument(collection: string, documentId: string): Promise<{
+        deleted: true;
+    }>;
+    /** Get the document count for a collection, with optional filter. */
+    count(collection: string, where?: Record<string, unknown>): Promise<{
+        count: number;
+    }>;
+    /**
+     * 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 } },
+     * ]);
+     * ```
+     */
+    transaction(collection: string, operations: TransactionOperation[]): Promise<TransactionResponse>;
+    private docsPath;
+}
+
+/**
+ * Manage webhook endpoints and verify incoming webhook signatures.
+ */
+declare class WebhooksNamespace {
+    private readonly http;
+    private readonly appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * 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!
+     * ```
+     */
+    create(options: CreateWebhookOptions): Promise<Webhook>;
+    /** List all webhook endpoints for your app. Secrets are not included. */
+    list(): Promise<{
+        endpoints: Webhook[];
+    }>;
+    /** Get a single webhook endpoint. Secret is not included. */
+    get(endpointId: string): Promise<Webhook>;
+    /** Delete a webhook endpoint. */
+    delete(endpointId: string): Promise<{
+        deleted: true;
+    }>;
+    /**
+     * 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...
+     * });
+     * ```
+     */
+    verify(payload: string, signature: string, secret: string): Promise<boolean>;
+}
+
+/** Base error for all Omen SDK errors. */
+declare class OmenError extends Error {
+    /** HTTP status code from the API. */
+    readonly status: number;
+    /** Machine-readable error code (e.g. "RATE_LIMITED", "NOT_FOUND"). */
+    readonly code: string | undefined;
+    constructor(message: string, status: number, code?: string);
+}
+/** Thrown when the API returns 404. */
+declare class OmenNotFoundError extends OmenError {
+    constructor(message?: string);
+}
+/** Thrown when the API returns 401 or 403. */
+declare class OmenAuthError extends OmenError {
+    constructor(message?: string);
+}
+/** Thrown when the API returns 422. */
+declare class OmenValidationError extends OmenError {
+    /** Field-level validation errors, if available. */
+    readonly errors: Record<string, string> | undefined;
+    constructor(message: string, errors?: Record<string, string>);
+}
+/** Thrown when the API returns 429. */
+declare class OmenRateLimitError extends OmenError {
+    /** Seconds until the rate limit resets. */
+    readonly retryAfter: number | undefined;
+    /** Remaining requests in the current window. */
+    readonly remaining: number | undefined;
+    constructor(message?: string, retryAfter?: number, remaining?: number);
+}
+
+/**
+ * The Omen SDK client. Initialize with your developer token to access all namespaces.
+ *
+ * @example
+ * ```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
+ * });
+ *
+ * // Get a user's profile
+ * const profile = await omen.users.get('pistolphoenix');
+ *
+ * // Store data for a user
+ * await omen.storage.set({ highScore: 9001 });
+ *
+ * // Issue an achievement
+ * await omen.items.issue({
+ *   userId: profile.user.id,
+ *   name: 'Welcome Badge',
+ *   type: 'achievement',
+ * });
+ * ```
+ */
+declare class OmenClient {
+    /** User profiles and friend lists. */
+    readonly users: UsersNamespace;
+    /** Per-user key-value storage. */
+    readonly storage: StorageNamespace;
+    /** Issue, revoke, and batch-manage items. */
+    readonly items: ItemsNamespace;
+    /** Structured data collections (document database). */
+    readonly collections: CollectionsNamespace;
+    /** Webhook endpoint management and signature verification. */
+    readonly webhooks: WebhooksNamespace;
+    constructor(options: OmenClientOptions & {
+        appId: string;
+    });
+}
+
+export { type AcquisitionType, type Badge, type BatchIssueResponse, type Collection, type CreateCollectionOptions, type CreateWebhookOptions, type Document, type FeaturedItem, type Friend, type FriendsListOptions, type FriendsListResponse, type IssueItemOptions, type Item, type ItemType, OmenAuthError, OmenClient, type OmenClientOptions, OmenError, OmenNotFoundError, OmenRateLimitError, OmenValidationError, type PinnedCreation, type QueryDocumentsOptions, type QueryDocumentsResponse, type SchemaFieldType, type StorageData, type TransactionOperation, type TransactionResponse, type UserProfile, type UserProfileResponse, type Webhook };