@omen.dog/sdk 1.0.0 → 1.1.0

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+export { ASK_GROWN_UP_STATES, CHILD_LOGIN_STATES, ChildIdentity, ChildLogin, ChildLoginApprovedPayload, ChildLoginContext, ChildLoginDisplayGroup, ChildLoginOptions, ChildLoginSignal, ChildLoginState, ChildRebind, ChildTokens, DeviceStartOptions, DeviceStartResult, ENTRY_STATES, PollResult, PollUntilOptions, SealedSession, deriveInitialState, displayGroup, reduce } from './child-login.mjs';
+
 interface RequestOptions {
     method?: string;
     body?: unknown;
@@ -160,6 +162,149 @@ interface BatchIssueResponse {
     items: Item[];
     count: number;
 }
+interface AwardSparksOptions {
+    userId: string;
+    amount: number;
+    reason?: string;
+    /** Make retries safe — the same key is credited at most once. */
+    idempotencyKey?: string;
+}
+interface AwardResult {
+    awarded: number;
+    userId: string;
+    userBalance: number;
+    poolBalance: number;
+    transactionId: string | null;
+    idempotent: boolean;
+}
+interface AwardBatchItem {
+    userId: string;
+    amount: number;
+    reason?: string;
+    idempotencyKey?: string;
+}
+interface AwardBatchResultItem {
+    index: number;
+    userId: string | null;
+    ok: boolean;
+    awarded?: number;
+    userBalance?: number;
+    idempotent?: boolean;
+    error?: string;
+}
+interface AwardBatchResponse {
+    results: AwardBatchResultItem[];
+    succeeded: number;
+    failed: number;
+    poolBalance: number;
+}
+interface PoolBudget {
+    appId: string;
+    balance: number;
+    lifetimeAllocated: number;
+    lifetimeAwarded: number;
+}
+interface PoolStatus {
+    balance: number;
+    lifetimePurchased: number;
+    lifetimeAwarded: number;
+    lowBalanceThreshold: number;
+    currency: string;
+    budgets: PoolBudget[];
+}
+interface DisplayTokenOptions {
+    userId: string;
+    /** Your app's OAuth client secret (backend only). */
+    secret: string;
+    /** Token lifetime in seconds. Default 600, max 3600. */
+    ttlSeconds?: number;
+}
+/** F262 — write-scoped editor token for <omen-avatar-editor>. */
+interface EditorTokenOptions {
+    userId: string;
+    /** Your app's OAuth client secret (backend only). */
+    secret: string;
+    /** Token lifetime in seconds. Default 600, max 3600. */
+    ttlSeconds?: number;
+}
+interface AvatarCatalogTrait {
+    /** `category/file.svg` path — also a public SVG at `{baseUrl}/avatar/{id}`. */
+    id: string;
+    name: string;
+    rarity: string;
+    /** Sparks list price derived from rarity (0 = common/free). */
+    price: number;
+    /** With an editor token: whether that user still needs to unlock it. */
+    locked: boolean;
+    [key: string]: unknown;
+}
+interface AvatarCatalogResult {
+    catalog: Record<string, {
+        traits: AvatarCatalogTrait[];
+        [key: string]: unknown;
+    }>;
+    /** Sparks price per rarity tier. */
+    rarityPricing: Record<string, number>;
+    [key: string]: unknown;
+}
+interface SendEmailOptions {
+    /** Sender address. Its domain must be a verified sending domain on your org. */
+    from: string;
+    /** Display name shown next to the from address. */
+    fromName?: string;
+    /** One address or up to 10. */
+    to: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    replyTo?: string;
+}
+interface SendEmailResult {
+    sent: number;
+    rejected: string[];
+    messageId: string | null;
+    from: string;
+    dailyRemaining: number;
+}
+interface EmailLogEntry {
+    id: string;
+    fromEmail: string;
+    toEmail: string;
+    subject: string;
+    status: 'sent' | 'failed';
+    error: string | null;
+    createdAt: string;
+}
+interface EmailLogResponse {
+    messages: EmailLogEntry[];
+    quota: {
+        dailyLimit: number;
+        usedToday: number;
+        remaining: number;
+    };
+}
+type CatalogType = 'store' | 'avatar_trait';
+interface AwardCatalogOptions {
+    userId: string;
+    /** 'store' = open-shop item, 'avatar_trait' = avatar-editor item. */
+    catalogType: CatalogType;
+    catalogItemId: string;
+    idempotencyKey?: string;
+}
+interface AwardCatalogResult {
+    userId: string;
+    item?: {
+        id: string;
+        name: string;
+        rarity?: string | null;
+        type?: string;
+        category?: string;
+    };
+    price?: number;
+    poolBalance?: number;
+    alreadyOwned?: boolean;
+    idempotent?: boolean;
+}
 type SchemaFieldType = 'string' | 'number' | 'boolean' | 'date';
 interface CreateCollectionOptions {
     name: string;
@@ -203,6 +348,81 @@ interface TransactionResponse {
         deleted: string;
     }>;
 }
+interface Product {
+    id: string;
+    appId: string;
+    name: string;
+    description: string;
+    type: 'one_time' | 'subscription';
+    priceCents: number;
+    currency: string;
+    billingInterval: 'month' | 'year' | null;
+    trialDays: number | null;
+    maxPurchasesPerUser: number | null;
+    templateId: string | null;
+    active: boolean;
+    stripeProductId: string | null;
+    stripePriceId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateProductOptions {
+    name: string;
+    type: 'one_time' | 'subscription';
+    priceCents: number;
+    currency?: string;
+    description?: string;
+    billingInterval?: 'month' | 'year';
+    trialDays?: number;
+    maxPurchasesPerUser?: number;
+    templateId?: string;
+}
+interface UpdateProductOptions {
+    name?: string;
+    description?: string;
+    active?: boolean;
+    maxPurchasesPerUser?: number;
+    templateId?: string;
+}
+interface MultiplayerConfig {
+    managed: boolean;
+    maxPlayers: number;
+    soloSupported: boolean;
+    allowSpectators: boolean;
+    voiceEnabled: boolean;
+    teamMode: 'none' | 'manual' | 'auto';
+    teamCount: number;
+    matchmaking: boolean;
+}
+interface UpdateMultiplayerConfigOptions {
+    managed?: boolean;
+    maxPlayers?: number;
+    soloSupported?: boolean;
+    allowSpectators?: boolean;
+    voiceEnabled?: boolean;
+    teamMode?: 'none' | 'manual' | 'auto';
+    teamCount?: number;
+    matchmaking?: boolean;
+}
+interface RoomLogicVersion {
+    version: number;
+    deployedAt: string;
+    active: boolean;
+    sizeBytes: number;
+}
+type NotificationCategory = 'general' | 'items' | 'transfers' | 'badges' | 'social' | 'app' | 'system';
+interface SendNotificationOptions {
+    userId: string;
+    title: string;
+    body: string;
+    category?: NotificationCategory;
+    data?: Record<string, unknown>;
+    actionUrl?: string;
+}
+interface NotificationResponse {
+    id: string;
+    status: 'sent';
+}
 interface CreateWebhookOptions {
     url: string;
     events: string[];
@@ -330,6 +550,20 @@ declare class ItemsNamespace {
      * ```
      */
     revoke(itemId: string, reason?: string): Promise<Item>;
+    /**
+     * Award a catalog item (open-shop cosmetic or avatar-editor trait) to a user,
+     * paid for from your Sparks pool at the item's list price. Custom items use
+     * `issue()` and are free; catalog items draw the pool down. Re-awarding an item
+     * the user already owns is a no-op (no charge).
+     *
+     * @example
+     * ```ts
+     * await omen.items.awardCatalog({
+     *   userId, catalogType: 'store', catalogItemId: 'theme_lava',
+     * });
+     * ```
+     */
+    awardCatalog(options: AwardCatalogOptions): Promise<AwardCatalogResult>;
 }
 
 /**
@@ -483,6 +717,265 @@ declare class WebhooksNamespace {
     verify(payload: string, signature: string, secret: string): Promise<boolean>;
 }
 
+/**
+ * Manage in-app products (one-time purchases and subscriptions).
+ *
+ * Products are created by developers and purchased by users via Stripe.
+ */
+declare class ProductsNamespace {
+    private readonly http;
+    private readonly appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * Create a new product.
+     *
+     * @example
+     * ```ts
+     * const product = await omen.products.create({
+     *   name: 'Premium Sword',
+     *   type: 'one_time',
+     *   priceCents: 499,
+     * });
+     * ```
+     */
+    create(options: CreateProductOptions): Promise<Product>;
+    /**
+     * List all products for this app.
+     *
+     * @param activeOnly - If true, only return active products. Defaults to false.
+     */
+    list(activeOnly?: boolean): Promise<Product[]>;
+    /**
+     * Update an existing product.
+     *
+     * @param productId - The product ID to update.
+     * @param options - Fields to update.
+     */
+    update(productId: string, options: UpdateProductOptions): Promise<Product>;
+    /**
+     * Deactivate a product. Deactivated products cannot be purchased but existing
+     * purchases remain valid.
+     *
+     * @param productId - The product ID to deactivate.
+     */
+    deactivate(productId: string): Promise<void>;
+}
+
+/**
+ * Configure managed multiplayer and deploy authoritative room logic.
+ *
+ * Room creation/joining is handled by the platform via the SDK bridge.
+ * This namespace is for developer-side configuration and deployment.
+ */
+declare class MultiplayerNamespace {
+    private readonly http;
+    private readonly appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * Get the current multiplayer configuration for this app.
+     */
+    getConfig(): Promise<MultiplayerConfig | null>;
+    /**
+     * Enable or update managed multiplayer configuration.
+     *
+     * @example
+     * ```ts
+     * await omen.multiplayer.updateConfig({
+     *   managed: true,
+     *   maxPlayers: 8,
+     *   voiceEnabled: true,
+     *   teamMode: 'manual',
+     * });
+     * ```
+     */
+    updateConfig(options: UpdateMultiplayerConfigOptions): Promise<MultiplayerConfig>;
+    /**
+     * Deploy authoritative room logic (Pro tier required).
+     * The bundle is a JavaScript file that exports room lifecycle hooks.
+     *
+     * @param bundle - The JavaScript source code as a string.
+     */
+    deployLogic(bundle: string): Promise<{
+        version: number;
+        deployedAt: string;
+    }>;
+    /**
+     * List deployed room logic versions.
+     */
+    listLogicVersions(): Promise<RoomLogicVersion[]>;
+    /**
+     * Roll back to a previous room logic version.
+     *
+     * @param version - The version number to roll back to.
+     */
+    rollbackLogic(version: number): Promise<{
+        version: number;
+        rolledBackAt: string;
+    }>;
+}
+
+/**
+ * Send notifications to users of your app.
+ *
+ * Notifications appear in the user's notification inbox on Omen.
+ */
+declare class NotificationsNamespace {
+    private readonly http;
+    private readonly appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * Send a notification to a user.
+     *
+     * @example
+     * ```ts
+     * await omen.notifications.send({
+     *   userId: 'cmm0tzco8...',
+     *   title: 'New high score!',
+     *   body: 'Someone beat your record on Pixel Duel.',
+     *   category: 'app',
+     *   actionUrl: '/creations/pixel-duel',
+     * });
+     * ```
+     */
+    send(options: SendNotificationOptions): Promise<NotificationResponse>;
+}
+
+/**
+ * Award Sparks (money-backed) to your app's users from your prepaid pool, and
+ * mint short-lived display tokens for the embeddable UI kit.
+ *
+ * Buy and manage the pool in the Developer Portal → Sparks Pool. Awards draw the
+ * pool down (or an app's allocated sub-budget if one exists).
+ *
+ * NOTE: `award`, `awardBatch`, and `items.awardCatalog` require an APPROVED
+ * Partner App (Developer Portal → Partner Program). Unapproved apps receive
+ * `403 partner_required`. Funding a pool and minting display tokens do not.
+ */
+declare class SparksNamespace {
+    private readonly http;
+    private readonly appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * Award Sparks to a single user. Pass `idempotencyKey` to make retries safe.
+     *
+     * @example
+     * ```ts
+     * await omen.sparks.award({
+     *   userId: 'cmm0tzco8...',
+     *   amount: 250,
+     *   reason: 'Beat level 10',
+     *   idempotencyKey: `level10:${userId}`,
+     * });
+     * ```
+     */
+    award(options: AwardSparksOptions): Promise<AwardResult>;
+    /**
+     * Award Sparks to many users in one request (max 100). Best-effort per item:
+     * a single bad/underfunded entry does not fail the rest. Inspect `results`.
+     */
+    awardBatch(awards: AwardBatchItem[]): Promise<AwardBatchResponse>;
+    /** Current pool status: balance, lifetime stats, and per-app budgets. */
+    pool(): Promise<PoolStatus>;
+    /**
+     * Mint a short-lived display token for the UI kit, scoped to one user. Sign
+     * with your app's OAuth client SECRET (from the Developer Portal) — never ship
+     * the secret to the browser; call this on your backend and pass the token to
+     * `<omen-sparks-balance token="...">` / `<omen-inventory token="...">`.
+     *
+     * Synchronous (no network). Default TTL 10 min, max 1 hour.
+     *
+     * @example
+     * ```ts
+     * const token = omen.sparks.displayToken({ userId, secret: process.env.OMEN_CLIENT_SECRET! });
+     * ```
+     */
+    displayToken(options: DisplayTokenOptions): string;
+}
+
+/**
+ * Send transactional email from your own verified domain through Omen.
+ *
+ * Add and verify a sending domain in the Developer Portal → Email (publish the
+ * ownership/SPF/DKIM TXT records it gives you), then send from any address on
+ * that domain.
+ *
+ * NOTE: sending requires an APPROVED Partner App (Developer Portal → Partner
+ * Program); unapproved apps receive `403 partner_required`. Sends are capped
+ * per app per rolling 24h — check `dailyRemaining` / `emails.log()`.
+ */
+declare class EmailsNamespace {
+    private readonly http;
+    private readonly appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * Send one email (up to 10 recipients). No attachments; 256 KB body max.
+     *
+     * @example
+     * ```ts
+     * await omen.emails.send({
+     *   from: 'hello@yourdomain.com',
+     *   fromName: 'My App',
+     *   to: player.email,
+     *   subject: 'Your weekly recap',
+     *   html: '<h1>Nice run!</h1>',
+     * });
+     * ```
+     */
+    send(options: SendEmailOptions): Promise<SendEmailResult>;
+    /** Recent sends for this app plus the rolling 24h quota. */
+    log(limit?: number): Promise<EmailLogResponse>;
+}
+
+/**
+ * F262 Embedded Avatar Kit — the shared Omen avatar inside your app.
+ *
+ * Your users keep ONE avatar across Omen and every partner app: display it
+ * with `<omen-avatar>` (or `renderUrl()`), and let users edit it in-place
+ * with `<omen-avatar-editor>` powered by an editor token minted here.
+ *
+ * NOTE: editor tokens only verify for APPROVED Partner Apps, and only for
+ * users who have connected your app via Omen OAuth. Theme, currency display
+ * and commerce flags are configured per-app via the Developer Portal →
+ * Embed, or PUT /api/v1/developer/apps/{appId}/embed-config.
+ */
+declare class AvatarNamespace {
+    private readonly appId;
+    private readonly baseUrl;
+    constructor(appId: string, baseUrl: string);
+    /**
+     * Mint a short-lived WRITE-scoped editor token for one user (backend only —
+     * never expose your client secret to the browser). Pass it to
+     * `<omen-avatar-editor token="...">`.
+     *
+     * @example
+     * ```ts
+     * const token = omen.avatar.editorToken({ userId, secret: process.env.OMEN_CLIENT_SECRET! });
+     * ```
+     */
+    editorToken(options: EditorTokenOptions): string;
+    /**
+     * Public render URL for a user's shared avatar (SVG; append `&format=png`
+     * where supported). Pass `version` (from the `avatar:saved` event or the
+     * `user.avatar_updated` webhook) to bust caches after an edit.
+     */
+    renderUrl(userId: string, options?: {
+        version?: string;
+    }): string;
+    /**
+     * Enumerate the shared avatar catalog — every trait id, name, rarity and
+     * Sparks list price. Public, no auth. Trait ids (`category/file.svg` paths)
+     * are also public SVGs at `{baseUrl}/avatar/{id}` for previews, and feed
+     * `omen.items.awardCatalog({ catalogType: 'avatar_trait', catalogItemId })`
+     * for pool-funded gifts.
+     *
+     * Pass a user's editor token and each trait's `locked` flag reflects that
+     * user's ownership instead of the anonymous default.
+     */
+    catalog(options?: {
+        editorToken?: string;
+    }): Promise<AvatarCatalogResult>;
+}
+
 /** Base error for all Omen SDK errors. */
 declare class OmenError extends Error {
     /** HTTP status code from the API. */
@@ -551,9 +1044,21 @@ declare class OmenClient {
     readonly collections: CollectionsNamespace;
     /** Webhook endpoint management and signature verification. */
     readonly webhooks: WebhooksNamespace;
+    /** In-app products (one-time purchases and subscriptions). */
+    readonly products: ProductsNamespace;
+    /** Managed multiplayer configuration and room logic deployment. */
+    readonly multiplayer: MultiplayerNamespace;
+    /** Send notifications to app users. */
+    readonly notifications: NotificationsNamespace;
+    /** Award Sparks from your prepaid pool + mint UI-kit display tokens. */
+    readonly sparks: SparksNamespace;
+    /** Send transactional email from your verified domains (Partner Apps). */
+    readonly emails: EmailsNamespace;
+    /** Shared Omen avatar in your app: editor tokens + render URLs (F262). */
+    readonly avatar: AvatarNamespace;
     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 };
+export { type AcquisitionType, type AwardBatchItem, type AwardBatchResponse, type AwardBatchResultItem, type AwardCatalogOptions, type AwardCatalogResult, type AwardResult, type AwardSparksOptions, type Badge, type BatchIssueResponse, type CatalogType, type Collection, type CreateCollectionOptions, type CreateProductOptions, type CreateWebhookOptions, type DisplayTokenOptions, type Document, type EditorTokenOptions, type EmailLogEntry, type EmailLogResponse, type FeaturedItem, type Friend, type FriendsListOptions, type FriendsListResponse, type IssueItemOptions, type Item, type ItemType, type MultiplayerConfig, type NotificationCategory, type NotificationResponse, OmenAuthError, OmenClient, type OmenClientOptions, OmenError, OmenNotFoundError, OmenRateLimitError, OmenValidationError, type PinnedCreation, type PoolBudget, type PoolStatus, type Product, type QueryDocumentsOptions, type QueryDocumentsResponse, type RoomLogicVersion, type SchemaFieldType, type SendEmailOptions, type SendEmailResult, type SendNotificationOptions, type StorageData, type TransactionOperation, type TransactionResponse, type UpdateMultiplayerConfigOptions, type UpdateProductOptions, type UserProfile, type UserProfileResponse, type Webhook };