@omen.dog/sdk 1.1.0 → 1.2.0

package/README.md

@@ -182,6 +182,43 @@ Trait ids are `category/file.svg` paths and double as public preview SVGs at
 `https://omen.dog/avatar/{traitId}`. Common traits are free for everyone and
 can't be awarded.
 
+### App-owned assets & image generation
+
+Host content art your **app** owns (shared across all your users, not a single
+user's upload) and serve it from a public, immutable, CDN-cacheable URL — exempt
+from the per-user asset cap. Bring your own bytes, or generate them on Omen
+billed to your prepaid Sparks pool.
+
+```ts
+// Host bytes you already have (Buffer / Uint8Array / base64). Max 10 MB.
+const asset = await omen.assets.upload(pngBuffer, { name: 'Apple', contentType: 'image/png' });
+console.log(asset.url); // /api/v1/assets/…/file — embed anywhere
+
+// List / fetch / evict (eviction is yours to control — never purged on a timer)
+const { assets, nextCursor } = await omen.assets.list({ limit: 50 });
+await omen.assets.delete(asset.id);
+
+// Generate one image, billed to your pool, hosted app-owned. Requires an
+// approved Partner App + a funded pool. Output is child-safety-filtered.
+const { asset: img, cost, poolBalance } = await omen.images.generate({
+  prompt: 'a friendly red apple with a smiling face',
+  aspectRatio: '4:3',            // 1:1 | 4:3 | 3:4 | 16:9 | 9:16
+  style: 'storybook',           // optional preset; omit for raw-prompt mode
+  idempotencyKey: `apple:${pageId}`,
+});
+
+// Keep a recurring character consistent across story pages — pass an identity ref
+await omen.images.generate({
+  prompt: 'the same fox, now jumping over a log',
+  aspectRatio: '3:4',
+  referenceImages: [{ data: foxPngBase64, tag: 'identity' }], // up to 4, ≤4 MB each
+});
+```
+
+A depleted pool fails closed (`402`, throws `OmenError`); a rejected prompt or
+blocked image throws `OmenValidationError` (`400 content_rejected`) and your pool
+is not charged.
+
 ## Creation Runtime Types
 
 For creation developers — get autocomplete for the `omen.*` global:

package/dist/index.d.mts

@@ -436,6 +436,79 @@ interface Webhook {
     createdAt: string;
     updatedAt: string;
 }
+/** A content asset owned by your app (not a user), served by a public immutable URL. */
+interface AppAsset {
+    id: string;
+    name: string;
+    /** Public, immutable, CDN-cacheable file URL (relative to the API base). */
+    url: string;
+    width: number;
+    height: number;
+    fileSize: number;
+    contentType: string | null;
+    /** 'upload' (you sent the bytes) or 'generated' (app-pool generation). */
+    source: 'upload' | 'generated';
+    /** The generation prompt, for generated assets. */
+    prompt?: string | null;
+    createdAt: string;
+}
+interface UploadAssetOptions {
+    /** Display name. Defaults to a slug of the filename. */
+    name?: string;
+    /** MIME type of the bytes (e.g. 'image/png'). Inferred from a data: URL if omitted. */
+    contentType?: string;
+    /** Original filename — used to derive the stored extension if contentType is absent. */
+    filename?: string;
+}
+interface AppAssetListOptions {
+    /** Page size (1–100, default 50). */
+    limit?: number;
+    /** Pagination cursor — pass the previous response's `nextCursor`. */
+    cursor?: string;
+}
+interface AppAssetListResponse {
+    assets: AppAsset[];
+    nextCursor: string | null;
+}
+/** Curated model-native aspect ratios (Decision 7). */
+type ImageAspectRatio = '1:1' | '4:3' | '3:4' | '16:9' | '9:16';
+/** Optional illustration style presets. Omit for raw-prompt mode. */
+type ContentImageStyle = 'storybook' | 'watercolor' | 'flat-vector' | 'cartoon' | 'crayon' | '3d-clay';
+/**
+ * A reference image passed natively to the model. `tag: 'style'` matches palette
+ * / line / rendering; `tag: 'identity'` keeps a recurring character consistent
+ * across pages. `data` is base64 (raw or a data: URL).
+ */
+interface ReferenceImage {
+    data: string;
+    tag?: 'style' | 'identity';
+    contentType?: string;
+}
+interface GenerateImageOptions {
+    /** What to draw. Mandatory; always passes the child-safety filter (output is child-facing). */
+    prompt: string;
+    /** Curated native aspect ratio. Default '1:1'. */
+    aspectRatio?: ImageAspectRatio;
+    /** Optional illustration style preset. Omit for raw-prompt mode. */
+    style?: ContentImageStyle;
+    /** Cut the subject out onto transparency (chroma-key). Default false. */
+    transparent?: boolean;
+    /** Up to 4 reference images (base64 string or { data, tag }). */
+    referenceImages?: Array<string | ReferenceImage>;
+    /** Display name for the stored asset. */
+    name?: string;
+    /** Make retries safe — the same key produces one asset and is charged once. */
+    idempotencyKey?: string;
+}
+interface GeneratedImageResult {
+    asset: AppAsset;
+    /** Sparks debited from your pool for this image. */
+    cost: number;
+    /** Pool balance after the debit (null on an idempotent replay). */
+    poolBalance: number | null;
+    /** True when an idempotent replay returned an already-generated asset. */
+    idempotent?: boolean;
+}
 
 /** Read-only access to Omen user profiles and friend lists. */
 declare class UsersNamespace {
@@ -976,6 +1049,88 @@ declare class AvatarNamespace {
     }): Promise<AvatarCatalogResult>;
 }
 
+/**
+ * App-owned content hosting (Tier 3, F264 Phase 1).
+ *
+ * Host images your **app** owns — content art shared across all your users (a
+ * vocabulary item's picture, a story-page illustration), not a single user's
+ * upload. App-owned assets are server-to-server, owned by the app, **exempt from
+ * the per-user asset cap**, and served by a public, immutable, CDN-cacheable URL.
+ *
+ * Build the bytes with your own provider and host them here, or generate them on
+ * Omen with {@link ImagesNamespace.generate}.
+ */
+declare class AssetsNamespace {
+    private readonly http;
+    private readonly appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * Upload bytes and get back a public, immutable file URL. Accepts a Buffer /
+     * Uint8Array (raw bytes) or a base64 string (raw or a `data:` URL). Supported:
+     * PNG, JPG, SVG, GIF (SVGs are sanitized). Max 10 MB.
+     *
+     * @example
+     * ```ts
+     * const { url } = await omen.assets.upload(pngBuffer, { name: 'Apple', contentType: 'image/png' });
+     * ```
+     */
+    upload(data: Buffer | Uint8Array | string, options?: UploadAssetOptions): Promise<AppAsset>;
+    /** List the app's assets, newest first. Paginate with `nextCursor`. */
+    list(options?: AppAssetListOptions): Promise<AppAssetListResponse>;
+    /** Get one asset's metadata. */
+    get(id: string): Promise<AppAsset>;
+    /** Evict an asset (hard delete — row + bytes). Never purged on a timer; deletion is yours to control. */
+    delete(id: string): Promise<{
+        deleted: boolean;
+        id: string;
+    }>;
+}
+
+/**
+ * App-pool image generation (Tier 3, F264 Phase 2).
+ *
+ * Generate content art on your app's behalf, **billed to your prepaid Sparks
+ * pool** (never an end user), stored **app-owned**, and served by the same public
+ * immutable URL as every other Omen asset. Built for content-time / overnight
+ * pre-builds — no user, no spinner.
+ *
+ * Requires an **approved Partner App** (Developer Portal → Partner Program) and a
+ * funded pool. A depleted pool fails closed (`402 pool_insufficient`). The output
+ * is child-facing, so generation always runs the safety filter; a rejected prompt
+ * or blocked image returns `400 content_rejected` (the SDK throws `OmenError`
+ * with `.status === 400`; inspect the response body's `code`/`reason`) and your
+ * pool is **not** charged.
+ */
+declare class ImagesNamespace {
+    private readonly http;
+    private readonly appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * Generate one image and host it app-owned.
+     *
+     * @example
+     * ```ts
+     * const { asset, cost, poolBalance } = await omen.images.generate({
+     *   prompt: 'a friendly red apple with a smiling face',
+     *   aspectRatio: '4:3',
+     *   style: 'storybook',
+     *   idempotencyKey: `apple:${pageId}`,
+     * });
+     * console.log(asset.url); // embed anywhere
+     * ```
+     *
+     * @example Recurring character across story pages — pass an identity reference:
+     * ```ts
+     * await omen.images.generate({
+     *   prompt: 'the same fox, now jumping over a log',
+     *   aspectRatio: '3:4',
+     *   referenceImages: [{ data: foxPngBase64, tag: 'identity' }],
+     * });
+     * ```
+     */
+    generate(options: GenerateImageOptions): Promise<GeneratedImageResult>;
+}
+
 /** Base error for all Omen SDK errors. */
 declare class OmenError extends Error {
     /** HTTP status code from the API. */
@@ -1056,9 +1211,13 @@ declare class OmenClient {
     readonly emails: EmailsNamespace;
     /** Shared Omen avatar in your app: editor tokens + render URLs (F262). */
     readonly avatar: AvatarNamespace;
+    /** Host app-owned content art — upload + serve from a public immutable URL (F264). */
+    readonly assets: AssetsNamespace;
+    /** Generate content art billed to your prepaid Sparks pool, hosted app-owned (F264). */
+    readonly images: ImagesNamespace;
     constructor(options: OmenClientOptions & {
         appId: string;
     });
 }
 
-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 };
+export { type AcquisitionType, type AppAsset, type AppAssetListOptions, type AppAssetListResponse, type AwardBatchItem, type AwardBatchResponse, type AwardBatchResultItem, type AwardCatalogOptions, type AwardCatalogResult, type AwardResult, type AwardSparksOptions, type Badge, type BatchIssueResponse, type CatalogType, type Collection, type ContentImageStyle, 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 GenerateImageOptions, type GeneratedImageResult, type ImageAspectRatio, 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 ReferenceImage, type RoomLogicVersion, type SchemaFieldType, type SendEmailOptions, type SendEmailResult, type SendNotificationOptions, type StorageData, type TransactionOperation, type TransactionResponse, type UpdateMultiplayerConfigOptions, type UpdateProductOptions, type UploadAssetOptions, type UserProfile, type UserProfileResponse, type Webhook };

package/dist/index.d.ts

@@ -436,6 +436,79 @@ interface Webhook {
     createdAt: string;
     updatedAt: string;
 }
+/** A content asset owned by your app (not a user), served by a public immutable URL. */
+interface AppAsset {
+    id: string;
+    name: string;
+    /** Public, immutable, CDN-cacheable file URL (relative to the API base). */
+    url: string;
+    width: number;
+    height: number;
+    fileSize: number;
+    contentType: string | null;
+    /** 'upload' (you sent the bytes) or 'generated' (app-pool generation). */
+    source: 'upload' | 'generated';
+    /** The generation prompt, for generated assets. */
+    prompt?: string | null;
+    createdAt: string;
+}
+interface UploadAssetOptions {
+    /** Display name. Defaults to a slug of the filename. */
+    name?: string;
+    /** MIME type of the bytes (e.g. 'image/png'). Inferred from a data: URL if omitted. */
+    contentType?: string;
+    /** Original filename — used to derive the stored extension if contentType is absent. */
+    filename?: string;
+}
+interface AppAssetListOptions {
+    /** Page size (1–100, default 50). */
+    limit?: number;
+    /** Pagination cursor — pass the previous response's `nextCursor`. */
+    cursor?: string;
+}
+interface AppAssetListResponse {
+    assets: AppAsset[];
+    nextCursor: string | null;
+}
+/** Curated model-native aspect ratios (Decision 7). */
+type ImageAspectRatio = '1:1' | '4:3' | '3:4' | '16:9' | '9:16';
+/** Optional illustration style presets. Omit for raw-prompt mode. */
+type ContentImageStyle = 'storybook' | 'watercolor' | 'flat-vector' | 'cartoon' | 'crayon' | '3d-clay';
+/**
+ * A reference image passed natively to the model. `tag: 'style'` matches palette
+ * / line / rendering; `tag: 'identity'` keeps a recurring character consistent
+ * across pages. `data` is base64 (raw or a data: URL).
+ */
+interface ReferenceImage {
+    data: string;
+    tag?: 'style' | 'identity';
+    contentType?: string;
+}
+interface GenerateImageOptions {
+    /** What to draw. Mandatory; always passes the child-safety filter (output is child-facing). */
+    prompt: string;
+    /** Curated native aspect ratio. Default '1:1'. */
+    aspectRatio?: ImageAspectRatio;
+    /** Optional illustration style preset. Omit for raw-prompt mode. */
+    style?: ContentImageStyle;
+    /** Cut the subject out onto transparency (chroma-key). Default false. */
+    transparent?: boolean;
+    /** Up to 4 reference images (base64 string or { data, tag }). */
+    referenceImages?: Array<string | ReferenceImage>;
+    /** Display name for the stored asset. */
+    name?: string;
+    /** Make retries safe — the same key produces one asset and is charged once. */
+    idempotencyKey?: string;
+}
+interface GeneratedImageResult {
+    asset: AppAsset;
+    /** Sparks debited from your pool for this image. */
+    cost: number;
+    /** Pool balance after the debit (null on an idempotent replay). */
+    poolBalance: number | null;
+    /** True when an idempotent replay returned an already-generated asset. */
+    idempotent?: boolean;
+}
 
 /** Read-only access to Omen user profiles and friend lists. */
 declare class UsersNamespace {
@@ -976,6 +1049,88 @@ declare class AvatarNamespace {
     }): Promise<AvatarCatalogResult>;
 }
 
+/**
+ * App-owned content hosting (Tier 3, F264 Phase 1).
+ *
+ * Host images your **app** owns — content art shared across all your users (a
+ * vocabulary item's picture, a story-page illustration), not a single user's
+ * upload. App-owned assets are server-to-server, owned by the app, **exempt from
+ * the per-user asset cap**, and served by a public, immutable, CDN-cacheable URL.
+ *
+ * Build the bytes with your own provider and host them here, or generate them on
+ * Omen with {@link ImagesNamespace.generate}.
+ */
+declare class AssetsNamespace {
+    private readonly http;
+    private readonly appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * Upload bytes and get back a public, immutable file URL. Accepts a Buffer /
+     * Uint8Array (raw bytes) or a base64 string (raw or a `data:` URL). Supported:
+     * PNG, JPG, SVG, GIF (SVGs are sanitized). Max 10 MB.
+     *
+     * @example
+     * ```ts
+     * const { url } = await omen.assets.upload(pngBuffer, { name: 'Apple', contentType: 'image/png' });
+     * ```
+     */
+    upload(data: Buffer | Uint8Array | string, options?: UploadAssetOptions): Promise<AppAsset>;
+    /** List the app's assets, newest first. Paginate with `nextCursor`. */
+    list(options?: AppAssetListOptions): Promise<AppAssetListResponse>;
+    /** Get one asset's metadata. */
+    get(id: string): Promise<AppAsset>;
+    /** Evict an asset (hard delete — row + bytes). Never purged on a timer; deletion is yours to control. */
+    delete(id: string): Promise<{
+        deleted: boolean;
+        id: string;
+    }>;
+}
+
+/**
+ * App-pool image generation (Tier 3, F264 Phase 2).
+ *
+ * Generate content art on your app's behalf, **billed to your prepaid Sparks
+ * pool** (never an end user), stored **app-owned**, and served by the same public
+ * immutable URL as every other Omen asset. Built for content-time / overnight
+ * pre-builds — no user, no spinner.
+ *
+ * Requires an **approved Partner App** (Developer Portal → Partner Program) and a
+ * funded pool. A depleted pool fails closed (`402 pool_insufficient`). The output
+ * is child-facing, so generation always runs the safety filter; a rejected prompt
+ * or blocked image returns `400 content_rejected` (the SDK throws `OmenError`
+ * with `.status === 400`; inspect the response body's `code`/`reason`) and your
+ * pool is **not** charged.
+ */
+declare class ImagesNamespace {
+    private readonly http;
+    private readonly appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * Generate one image and host it app-owned.
+     *
+     * @example
+     * ```ts
+     * const { asset, cost, poolBalance } = await omen.images.generate({
+     *   prompt: 'a friendly red apple with a smiling face',
+     *   aspectRatio: '4:3',
+     *   style: 'storybook',
+     *   idempotencyKey: `apple:${pageId}`,
+     * });
+     * console.log(asset.url); // embed anywhere
+     * ```
+     *
+     * @example Recurring character across story pages — pass an identity reference:
+     * ```ts
+     * await omen.images.generate({
+     *   prompt: 'the same fox, now jumping over a log',
+     *   aspectRatio: '3:4',
+     *   referenceImages: [{ data: foxPngBase64, tag: 'identity' }],
+     * });
+     * ```
+     */
+    generate(options: GenerateImageOptions): Promise<GeneratedImageResult>;
+}
+
 /** Base error for all Omen SDK errors. */
 declare class OmenError extends Error {
     /** HTTP status code from the API. */
@@ -1056,9 +1211,13 @@ declare class OmenClient {
     readonly emails: EmailsNamespace;
     /** Shared Omen avatar in your app: editor tokens + render URLs (F262). */
     readonly avatar: AvatarNamespace;
+    /** Host app-owned content art — upload + serve from a public immutable URL (F264). */
+    readonly assets: AssetsNamespace;
+    /** Generate content art billed to your prepaid Sparks pool, hosted app-owned (F264). */
+    readonly images: ImagesNamespace;
     constructor(options: OmenClientOptions & {
         appId: string;
     });
 }
 
-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 };
+export { type AcquisitionType, type AppAsset, type AppAssetListOptions, type AppAssetListResponse, type AwardBatchItem, type AwardBatchResponse, type AwardBatchResultItem, type AwardCatalogOptions, type AwardCatalogResult, type AwardResult, type AwardSparksOptions, type Badge, type BatchIssueResponse, type CatalogType, type Collection, type ContentImageStyle, 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 GenerateImageOptions, type GeneratedImageResult, type ImageAspectRatio, 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 ReferenceImage, type RoomLogicVersion, type SchemaFieldType, type SendEmailOptions, type SendEmailResult, type SendNotificationOptions, type StorageData, type TransactionOperation, type TransactionResponse, type UpdateMultiplayerConfigOptions, type UpdateProductOptions, type UploadAssetOptions, type UserProfile, type UserProfileResponse, type Webhook };

package/dist/index.js

@@ -845,6 +845,86 @@ var AvatarNamespace = class {
   }
 };
 
+// src/namespaces/assets.ts
+var AssetsNamespace = class {
+  constructor(http, appId) {
+    this.http = http;
+    this.appId = appId;
+  }
+  /**
+   * Upload bytes and get back a public, immutable file URL. Accepts a Buffer /
+   * Uint8Array (raw bytes) or a base64 string (raw or a `data:` URL). Supported:
+   * PNG, JPG, SVG, GIF (SVGs are sanitized). Max 10 MB.
+   *
+   * @example
+   * ```ts
+   * const { url } = await omen.assets.upload(pngBuffer, { name: 'Apple', contentType: 'image/png' });
+   * ```
+   */
+  async upload(data, options = {}) {
+    const fileData = typeof data === "string" ? data : Buffer.from(data).toString("base64");
+    const res = await this.http.request(`/api/v1/apps/${this.appId}/assets`, {
+      method: "POST",
+      body: { fileData, ...options }
+    });
+    return res.asset;
+  }
+  /** List the app's assets, newest first. Paginate with `nextCursor`. */
+  async list(options = {}) {
+    return this.http.request(`/api/v1/apps/${this.appId}/assets`, {
+      query: { limit: options.limit, cursor: options.cursor }
+    });
+  }
+  /** Get one asset's metadata. */
+  async get(id) {
+    const res = await this.http.request(`/api/v1/apps/${this.appId}/assets/${id}`);
+    return res.asset;
+  }
+  /** Evict an asset (hard delete — row + bytes). Never purged on a timer; deletion is yours to control. */
+  async delete(id) {
+    return this.http.request(`/api/v1/apps/${this.appId}/assets/${id}`, { method: "DELETE" });
+  }
+};
+
+// src/namespaces/images.ts
+var ImagesNamespace = class {
+  constructor(http, appId) {
+    this.http = http;
+    this.appId = appId;
+  }
+  /**
+   * Generate one image and host it app-owned.
+   *
+   * @example
+   * ```ts
+   * const { asset, cost, poolBalance } = await omen.images.generate({
+   *   prompt: 'a friendly red apple with a smiling face',
+   *   aspectRatio: '4:3',
+   *   style: 'storybook',
+   *   idempotencyKey: `apple:${pageId}`,
+   * });
+   * console.log(asset.url); // embed anywhere
+   * ```
+   *
+   * @example Recurring character across story pages — pass an identity reference:
+   * ```ts
+   * await omen.images.generate({
+   *   prompt: 'the same fox, now jumping over a log',
+   *   aspectRatio: '3:4',
+   *   referenceImages: [{ data: foxPngBase64, tag: 'identity' }],
+   * });
+   * ```
+   */
+  async generate(options) {
+    const { idempotencyKey, ...body } = options;
+    return this.http.request(`/api/v1/apps/${this.appId}/generate/image`, {
+      method: "POST",
+      body,
+      headers: idempotencyKey ? { "Idempotency-Key": idempotencyKey } : void 0
+    });
+  }
+};
+
 // src/childLogin/rfc8628.js
 function mapPollResponse(httpStatus, body) {
   body = body || {};
@@ -1163,6 +1243,10 @@ var OmenClient = class {
   emails;
   /** Shared Omen avatar in your app: editor tokens + render URLs (F262). */
   avatar;
+  /** Host app-owned content art — upload + serve from a public immutable URL (F264). */
+  assets;
+  /** Generate content art billed to your prepaid Sparks pool, hosted app-owned (F264). */
+  images;
   constructor(options) {
     if (!options.token) throw new Error("OmenClient: token is required");
     if (!options.appId) throw new Error("OmenClient: appId is required");
@@ -1179,6 +1263,8 @@ var OmenClient = class {
     this.sparks = new SparksNamespace(http, options.appId);
     this.emails = new EmailsNamespace(http, options.appId);
     this.avatar = new AvatarNamespace(options.appId, baseUrl);
+    this.assets = new AssetsNamespace(http, options.appId);
+    this.images = new ImagesNamespace(http, options.appId);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.mjs

@@ -817,6 +817,86 @@ var AvatarNamespace = class {
   }
 };
 
+// src/namespaces/assets.ts
+var AssetsNamespace = class {
+  constructor(http, appId) {
+    this.http = http;
+    this.appId = appId;
+  }
+  /**
+   * Upload bytes and get back a public, immutable file URL. Accepts a Buffer /
+   * Uint8Array (raw bytes) or a base64 string (raw or a `data:` URL). Supported:
+   * PNG, JPG, SVG, GIF (SVGs are sanitized). Max 10 MB.
+   *
+   * @example
+   * ```ts
+   * const { url } = await omen.assets.upload(pngBuffer, { name: 'Apple', contentType: 'image/png' });
+   * ```
+   */
+  async upload(data, options = {}) {
+    const fileData = typeof data === "string" ? data : Buffer.from(data).toString("base64");
+    const res = await this.http.request(`/api/v1/apps/${this.appId}/assets`, {
+      method: "POST",
+      body: { fileData, ...options }
+    });
+    return res.asset;
+  }
+  /** List the app's assets, newest first. Paginate with `nextCursor`. */
+  async list(options = {}) {
+    return this.http.request(`/api/v1/apps/${this.appId}/assets`, {
+      query: { limit: options.limit, cursor: options.cursor }
+    });
+  }
+  /** Get one asset's metadata. */
+  async get(id) {
+    const res = await this.http.request(`/api/v1/apps/${this.appId}/assets/${id}`);
+    return res.asset;
+  }
+  /** Evict an asset (hard delete — row + bytes). Never purged on a timer; deletion is yours to control. */
+  async delete(id) {
+    return this.http.request(`/api/v1/apps/${this.appId}/assets/${id}`, { method: "DELETE" });
+  }
+};
+
+// src/namespaces/images.ts
+var ImagesNamespace = class {
+  constructor(http, appId) {
+    this.http = http;
+    this.appId = appId;
+  }
+  /**
+   * Generate one image and host it app-owned.
+   *
+   * @example
+   * ```ts
+   * const { asset, cost, poolBalance } = await omen.images.generate({
+   *   prompt: 'a friendly red apple with a smiling face',
+   *   aspectRatio: '4:3',
+   *   style: 'storybook',
+   *   idempotencyKey: `apple:${pageId}`,
+   * });
+   * console.log(asset.url); // embed anywhere
+   * ```
+   *
+   * @example Recurring character across story pages — pass an identity reference:
+   * ```ts
+   * await omen.images.generate({
+   *   prompt: 'the same fox, now jumping over a log',
+   *   aspectRatio: '3:4',
+   *   referenceImages: [{ data: foxPngBase64, tag: 'identity' }],
+   * });
+   * ```
+   */
+  async generate(options) {
+    const { idempotencyKey, ...body } = options;
+    return this.http.request(`/api/v1/apps/${this.appId}/generate/image`, {
+      method: "POST",
+      body,
+      headers: idempotencyKey ? { "Idempotency-Key": idempotencyKey } : void 0
+    });
+  }
+};
+
 // src/index.ts
 var OmenClient = class {
   /** User profiles and friend lists. */
@@ -841,6 +921,10 @@ var OmenClient = class {
   emails;
   /** Shared Omen avatar in your app: editor tokens + render URLs (F262). */
   avatar;
+  /** Host app-owned content art — upload + serve from a public immutable URL (F264). */
+  assets;
+  /** Generate content art billed to your prepaid Sparks pool, hosted app-owned (F264). */
+  images;
   constructor(options) {
     if (!options.token) throw new Error("OmenClient: token is required");
     if (!options.appId) throw new Error("OmenClient: appId is required");
@@ -857,6 +941,8 @@ var OmenClient = class {
     this.sparks = new SparksNamespace(http, options.appId);
     this.emails = new EmailsNamespace(http, options.appId);
     this.avatar = new AvatarNamespace(options.appId, baseUrl);
+    this.assets = new AssetsNamespace(http, options.appId);
+    this.images = new ImagesNamespace(http, options.appId);
   }
 };
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omen.dog/sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Official server-side TypeScript SDK for the Omen platform",
   "license": "MIT",
   "main": "./dist/index.js",