lumiverse-spindle-types 0.4.53 → 0.4.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.4.53",
+  "version": "0.4.55",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/api.ts

@@ -359,6 +359,10 @@ export interface ImageGenRequestDTO {
   model?: string;
   /** Provider-specific parameters. Merged with the connection's default_parameters. */
   parameters?: Record<string, unknown>;
+  /** Optional character ownership tag for the persisted result image. */
+  owner_character_id?: string;
+  /** Optional chat ownership tag for the persisted result image. */
+  owner_chat_id?: string;
   /** For operator-scoped extensions. */
   userId?: string;
 }
@@ -374,6 +378,79 @@ export interface ImageGenResultDTO {
   imageUrl?: string;
 }
 
+// ─── Image DTOs ─────────────────────────────────────────────────────────
+
+export type ImageSpecificityDTO = "full" | "sm" | "lg";
+
+export interface ImageListOptionsDTO {
+  limit?: number;
+  offset?: number;
+  /** Which image URL size should be returned in each DTO. */
+  specificity?: ImageSpecificityDTO;
+  /** Restrict results to images created by the current extension. */
+  onlyOwned?: boolean;
+  /** Restrict results to images tagged to a specific character. */
+  characterId?: string;
+  /** Restrict results to images tagged to a specific chat. */
+  chatId?: string;
+  /** For operator-scoped extensions. */
+  userId?: string;
+}
+
+export interface ImageGetOptionsDTO {
+  /** Which image URL size should be returned in the DTO. */
+  specificity?: ImageSpecificityDTO;
+  /** Restrict lookup to images created by the current extension. */
+  onlyOwned?: boolean;
+  /** Restrict lookup to images tagged to a specific character. */
+  characterId?: string;
+  /** Restrict lookup to images tagged to a specific chat. */
+  chatId?: string;
+  /** For operator-scoped extensions. */
+  userId?: string;
+}
+
+/** Safe representation of an image exposed to extensions. */
+export interface ImageDTO {
+  id: string;
+  original_filename: string;
+  mime_type: string;
+  width: number | null;
+  height: number | null;
+  has_thumbnail: boolean;
+  /** Relative authenticated URL for this image, already sized to `specificity`. */
+  url: string;
+  specificity: ImageSpecificityDTO;
+  owner_extension_identifier: string | null;
+  owner_character_id: string | null;
+  owner_chat_id: string | null;
+  created_at: number;
+}
+
+/** Upload payload for `spindle.images.upload()` */
+export interface ImageUploadDTO {
+  /** Raw image bytes. */
+  data: Uint8Array;
+  /** Optional filename used to preserve the extension/MIME when storing the image. */
+  filename?: string;
+  /** Optional content type. Defaults to image/png when not inferable. */
+  mime_type?: string;
+  /** Optional character ownership tag for the persisted image. */
+  owner_character_id?: string;
+  /** Optional chat ownership tag for the persisted image. */
+  owner_chat_id?: string;
+}
+
+export interface ImageUploadFromDataUrlOptionsDTO {
+  originalFilename?: string;
+  /** Optional character ownership tag for the persisted image. */
+  owner_character_id?: string;
+  /** Optional chat ownership tag for the persisted image. */
+  owner_chat_id?: string;
+  /** For operator-scoped extensions. */
+  userId?: string;
+}
+
 // ─── Character DTOs ─────────────────────────────────────────────────────
 
 /**
@@ -1854,6 +1931,39 @@ export type WorkerToHost =
   | { type: "image_gen_connections_list"; requestId: string; userId?: string }
   | { type: "image_gen_connections_get"; requestId: string; connectionId: string; userId?: string }
   | { type: "image_gen_models"; requestId: string; connectionId: string; userId?: string }
+  // ─── Images (gated: "images") ────────────────────────────────────────
+  | {
+      type: "images_list";
+      requestId: string;
+      limit?: number;
+      offset?: number;
+      specificity?: ImageSpecificityDTO;
+      onlyOwned?: boolean;
+      characterId?: string;
+      chatId?: string;
+      userId?: string;
+    }
+  | {
+      type: "images_get";
+      requestId: string;
+      imageId: string;
+      specificity?: ImageSpecificityDTO;
+      onlyOwned?: boolean;
+      characterId?: string;
+      chatId?: string;
+      userId?: string;
+    }
+  | { type: "images_upload"; requestId: string; input: ImageUploadDTO; userId?: string }
+  | {
+      type: "images_upload_from_data_url";
+      requestId: string;
+      dataUrl: string;
+      originalFilename?: string;
+      owner_character_id?: string;
+      owner_chat_id?: string;
+      userId?: string;
+    }
+  | { type: "images_delete"; requestId: string; imageId: string; userId?: string }
   // ─── Theme (gated: "app_manipulation") ──────────────────────────────────
   | { type: "theme_apply"; requestId: string; overrides: ThemeOverrideDTO; userId?: string }
   | { type: "theme_apply_palette"; requestId: string; palette: ThemePaletteConfigDTO | null; userId?: string }

package/src/index.ts

@@ -63,12 +63,18 @@ export type {
   DryRunTokenCountDTO,
   ChatMemoryChunkDTO,
   ChatMemoryResultDTO,
-  ImageGenConnectionDTO,
-  ImageGenParameterSchemaDTO,
-  ImageGenProviderDTO,
-  ImageGenRequestDTO,
-  ImageGenResultDTO,
-  ThemeOverrideDTO,
+   ImageGenConnectionDTO,
+   ImageGenParameterSchemaDTO,
+    ImageGenProviderDTO,
+    ImageGenRequestDTO,
+    ImageGenResultDTO,
+    ImageGetOptionsDTO,
+    ImageDTO,
+    ImageListOptionsDTO,
+    ImageSpecificityDTO,
+    ImageUploadDTO,
+    ImageUploadFromDataUrlOptionsDTO,
+    ThemeOverrideDTO,
   ThemeInfoDTO,
   ThemePaletteConfigDTO,
   ThemeVariablesConfigDTO,

package/src/permissions.ts

@@ -35,6 +35,7 @@ export type SpindlePermission =
   | "personas"
   | "push_notification"
   | "image_gen"
+  | "images"
   | "generation_parameters"
   | "macro_interceptor";
 
@@ -57,6 +58,7 @@ export const ALL_PERMISSIONS: readonly SpindlePermission[] = [
   "personas",
   "push_notification",
   "image_gen",
+  "images",
   "generation_parameters",
   "macro_interceptor",
 ] as const;

package/src/spindle-api.ts

@@ -45,6 +45,11 @@ import type {
   ImageGenResultDTO,
   ImageGenConnectionDTO,
   ImageGenProviderDTO,
+  ImageGetOptionsDTO,
+  ImageDTO,
+  ImageListOptionsDTO,
+  ImageUploadDTO,
+  ImageUploadFromDataUrlOptionsDTO,
   ThemeOverrideDTO,
   ThemeInfoDTO,
   ThemePaletteConfigDTO,
@@ -633,6 +638,22 @@ export interface SpindleAPI {
     getModels(connectionId: string, userId?: string): Promise<Array<{ id: string; label: string }>>;
   };
 
+  /**
+   * Image CRUD (permission: "images").
+   * Manage images stored in Lumiverse's image system on behalf of the user.
+   * For user-scoped extensions, userId is inferred from the extension owner.
+   * For operator-scoped extensions, pass userId to scope to a specific user.
+   */
+  images: {
+    list(options?: ImageListOptionsDTO): Promise<{ data: ImageDTO[]; total: number }>;
+    get(imageId: string, userId?: string): Promise<ImageDTO | null>;
+    get(imageId: string, options?: ImageGetOptionsDTO): Promise<ImageDTO | null>;
+    upload(input: ImageUploadDTO, userId?: string): Promise<ImageDTO>;
+    uploadFromDataUrl(dataUrl: string, originalFilename?: string, userId?: string): Promise<ImageDTO>;
+    uploadFromDataUrl(dataUrl: string, options?: ImageUploadFromDataUrlOptionsDTO): Promise<ImageDTO>;
+    delete(imageId: string, userId?: string): Promise<boolean>;
+  };
+
   /**
    * Local (transient), global (user-scoped), and chat (persisted) variable access
    * (free tier — no permission needed).