@howells/stow-server 0.3.2 → 0.6.0

package/dist/index.d.mts

@@ -48,6 +48,11 @@ interface UploadResult {
     size: number;
     url: string | null;
 }
+/** Response returned when an upload is queued for async processing. */
+interface QueuedResult {
+    jobId: string;
+    status: "queued";
+}
 /** Bucket metadata returned by bucket APIs. */
 interface BucketResult {
     allowedTypes?: string[] | null;
@@ -173,12 +178,18 @@ interface FileColorProfile {
 interface ListFilesItem {
     colorProfile?: FileColorProfile | null;
     colors?: FileColor[];
+    contentType?: string;
     duration?: number | null;
+    embeddingStatus?: string | null;
     height?: number | null;
     key: string;
     lastModified: string;
     metadata?: Record<string, string>;
     size: number;
+    /** Tags attached to this file. Present when `include: ["tags"]` is requested. */
+    tags?: FileTag[];
+    /** Taxonomy classifications. Present when `include: ["taxonomies"]` is requested. */
+    taxonomies?: FileTaxonomy[];
     url: string | null;
     width?: number | null;
 }
@@ -208,6 +219,25 @@ interface ListDropsResult {
         limit: number;
     };
 }
+/** A tag attached to a file, returned when `include: ["tags"]` is requested. */
+interface FileTag {
+    color: string | null;
+    id: string;
+    name: string;
+    slug: string;
+}
+/** A taxonomy classification for a file, returned when `include: ["taxonomies"]` is requested. */
+interface FileTaxonomy {
+    group: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+    id: string;
+    name: string;
+    similarity: number;
+    slug: string;
+}
 /** Full file detail payload returned by `getFile()`. */
 interface FileResult {
     colorProfile: FileColorProfile | null;
@@ -220,6 +250,10 @@ interface FileResult {
     key: string;
     metadata: Record<string, string> | null;
     size: number;
+    /** Tags attached to this file. Present when `include: ["tags"]` is requested. */
+    tags?: FileTag[];
+    /** Taxonomy classifications. Present when `include: ["taxonomies"]` is requested. */
+    taxonomies?: FileTaxonomy[];
     url: string | null;
     width: number | null;
 }
@@ -350,6 +384,8 @@ interface SearchFilters {
 }
 /** Optional enrichment blocks that can be included in search responses. */
 type SearchIncludeField = "tags" | "taxonomies" | "colors" | "colorProfile";
+/** Optional enrichment blocks that can be included in file get/list responses. */
+type FileIncludeField = "tags" | "taxonomies";
 /** Input payload for text-based semantic search. */
 interface TextSearchRequest {
     bucket?: string;
@@ -637,6 +673,25 @@ declare class StowServer {
         /** Request AI-generated alt text for images */
         altText?: boolean;
     }): Promise<UploadResult>;
+    /**
+     * Queue a URL upload for async processing via BullMQ.
+     *
+     * Unlike `uploadFromUrl()`, this returns immediately with a job ID.
+     * The actual fetch, validation, and upload happen in a background worker.
+     * Use this for bulk imports where you don't need immediate confirmation.
+     */
+    queueUploadFromUrl(url: string, filename: string, options?: {
+        bucket?: string;
+        metadata?: Record<string, string>;
+        /** Headers to forward when fetching the URL (e.g. User-Agent, Referer) */
+        headers?: Record<string, string>;
+        /** Request AI-generated title for images */
+        title?: boolean;
+        /** Request AI-generated description for images */
+        describe?: boolean;
+        /** Request AI-generated alt text for images */
+        altText?: boolean;
+    }): Promise<QueuedResult>;
     /**
      * Get a presigned URL for direct client-side upload.
      *
@@ -654,6 +709,8 @@ declare class StowServer {
     confirmUpload(request: ConfirmUploadRequest): Promise<UploadResult>;
     /**
      * List files in the bucket
+     *
+     * @param options.include - Optional enrichment fields: `"tags"`, `"taxonomies"`
      */
     listFiles(options?: {
         prefix?: string;
@@ -662,6 +719,8 @@ declare class StowServer {
         bucket?: string;
         /** Filter by tag slug */
         tag?: string;
+        /** Enrichment fields to include in each file item */
+        include?: FileIncludeField[];
     }): Promise<ListFilesResult>;
     /**
      * Delete a file by key
@@ -680,9 +739,12 @@ declare class StowServer {
     }>;
     /**
      * Get a single file by key
+     *
+     * @param options.include - Optional enrichment fields: `"tags"`, `"taxonomies"`
      */
     getFile(key: string, options?: {
         bucket?: string;
+        include?: FileIncludeField[];
     }): Promise<FileResult>;
     /**
      * Extract color palette from an image file.
@@ -704,6 +766,27 @@ declare class StowServer {
     embed(key: string, options?: {
         bucket?: string;
     }): Promise<TaskTriggerResult>;
+    /**
+     * Generate a title for an image file using AI vision.
+     * Requires a searchable bucket.
+     */
+    generateTitle(key: string, options?: {
+        bucket?: string;
+    }): Promise<TaskTriggerResult>;
+    /**
+     * Generate a description for an image file using AI vision.
+     * Requires a searchable bucket.
+     */
+    generateDescription(key: string, options?: {
+        bucket?: string;
+    }): Promise<TaskTriggerResult>;
+    /**
+     * Generate alt text for an image file using AI vision.
+     * Requires a searchable bucket.
+     */
+    generateAltText(key: string, options?: {
+        bucket?: string;
+    }): Promise<TaskTriggerResult>;
     /**
      * Replace a file's content by fetching from a new URL.
      *
@@ -835,4 +918,4 @@ declare class StowServer {
     private renameProfileCluster;
 }
 
-export { type BucketResult, type ColorSearchRequest, type ColorSearchResult, type ColorSearchResultItem, type ConfirmUploadRequest, type CreateBucketRequest, type DeleteProfileSignalsResult, type DiverseSearchRequest, type Drop, type DropResult, type FileColor, type FileColorProfile, type FileResult, type FilteredMetadata, type ListBucketsResult, type ListDropsResult, type ListFilesItem, type ListFilesResult, type PresignDedupeResult, type PresignNewResult, type PresignRequest, type PresignResult, type ProfileClusterResult, type ProfileCreateRequest, type ProfileFilesResult, type ProfileResult, type ProfileSignalInput, type ProfileSignalResult, type ProfileSignalType, type ProfileSignalsResponse, type ReclusterRequest, type ReclusterResult, type RenameClusterRequest, type ReplaceResult, type SearchFilters, type SearchIncludeField, type SearchResultItem, type SimilarSearchRequest, type SimilarSearchResult, StowError, StowServer, type StowServerConfig, type TaskTriggerResult, type TextSearchRequest, type TransformOptions, type UpdateBucketRequest, type UploadResult, type WhoamiResult };
+export { type BucketResult, type ColorSearchRequest, type ColorSearchResult, type ColorSearchResultItem, type ConfirmUploadRequest, type CreateBucketRequest, type DeleteProfileSignalsResult, type DiverseSearchRequest, type Drop, type DropResult, type FileColor, type FileColorProfile, type FileIncludeField, type FileResult, type FileTag, type FileTaxonomy, type FilteredMetadata, type ListBucketsResult, type ListDropsResult, type ListFilesItem, type ListFilesResult, type PresignDedupeResult, type PresignNewResult, type PresignRequest, type PresignResult, type ProfileClusterResult, type ProfileCreateRequest, type ProfileFilesResult, type ProfileResult, type ProfileSignalInput, type ProfileSignalResult, type ProfileSignalType, type ProfileSignalsResponse, type QueuedResult, type ReclusterRequest, type ReclusterResult, type RenameClusterRequest, type ReplaceResult, type SearchFilters, type SearchIncludeField, type SearchResultItem, type SimilarSearchRequest, type SimilarSearchResult, StowError, StowServer, type StowServerConfig, type TaskTriggerResult, type TextSearchRequest, type TransformOptions, type UpdateBucketRequest, type UploadResult, type WhoamiResult };

package/dist/index.d.ts

@@ -48,6 +48,11 @@ interface UploadResult {
     size: number;
     url: string | null;
 }
+/** Response returned when an upload is queued for async processing. */
+interface QueuedResult {
+    jobId: string;
+    status: "queued";
+}
 /** Bucket metadata returned by bucket APIs. */
 interface BucketResult {
     allowedTypes?: string[] | null;
@@ -173,12 +178,18 @@ interface FileColorProfile {
 interface ListFilesItem {
     colorProfile?: FileColorProfile | null;
     colors?: FileColor[];
+    contentType?: string;
     duration?: number | null;
+    embeddingStatus?: string | null;
     height?: number | null;
     key: string;
     lastModified: string;
     metadata?: Record<string, string>;
     size: number;
+    /** Tags attached to this file. Present when `include: ["tags"]` is requested. */
+    tags?: FileTag[];
+    /** Taxonomy classifications. Present when `include: ["taxonomies"]` is requested. */
+    taxonomies?: FileTaxonomy[];
     url: string | null;
     width?: number | null;
 }
@@ -208,6 +219,25 @@ interface ListDropsResult {
         limit: number;
     };
 }
+/** A tag attached to a file, returned when `include: ["tags"]` is requested. */
+interface FileTag {
+    color: string | null;
+    id: string;
+    name: string;
+    slug: string;
+}
+/** A taxonomy classification for a file, returned when `include: ["taxonomies"]` is requested. */
+interface FileTaxonomy {
+    group: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+    id: string;
+    name: string;
+    similarity: number;
+    slug: string;
+}
 /** Full file detail payload returned by `getFile()`. */
 interface FileResult {
     colorProfile: FileColorProfile | null;
@@ -220,6 +250,10 @@ interface FileResult {
     key: string;
     metadata: Record<string, string> | null;
     size: number;
+    /** Tags attached to this file. Present when `include: ["tags"]` is requested. */
+    tags?: FileTag[];
+    /** Taxonomy classifications. Present when `include: ["taxonomies"]` is requested. */
+    taxonomies?: FileTaxonomy[];
     url: string | null;
     width: number | null;
 }
@@ -350,6 +384,8 @@ interface SearchFilters {
 }
 /** Optional enrichment blocks that can be included in search responses. */
 type SearchIncludeField = "tags" | "taxonomies" | "colors" | "colorProfile";
+/** Optional enrichment blocks that can be included in file get/list responses. */
+type FileIncludeField = "tags" | "taxonomies";
 /** Input payload for text-based semantic search. */
 interface TextSearchRequest {
     bucket?: string;
@@ -637,6 +673,25 @@ declare class StowServer {
         /** Request AI-generated alt text for images */
         altText?: boolean;
     }): Promise<UploadResult>;
+    /**
+     * Queue a URL upload for async processing via BullMQ.
+     *
+     * Unlike `uploadFromUrl()`, this returns immediately with a job ID.
+     * The actual fetch, validation, and upload happen in a background worker.
+     * Use this for bulk imports where you don't need immediate confirmation.
+     */
+    queueUploadFromUrl(url: string, filename: string, options?: {
+        bucket?: string;
+        metadata?: Record<string, string>;
+        /** Headers to forward when fetching the URL (e.g. User-Agent, Referer) */
+        headers?: Record<string, string>;
+        /** Request AI-generated title for images */
+        title?: boolean;
+        /** Request AI-generated description for images */
+        describe?: boolean;
+        /** Request AI-generated alt text for images */
+        altText?: boolean;
+    }): Promise<QueuedResult>;
     /**
      * Get a presigned URL for direct client-side upload.
      *
@@ -654,6 +709,8 @@ declare class StowServer {
     confirmUpload(request: ConfirmUploadRequest): Promise<UploadResult>;
     /**
      * List files in the bucket
+     *
+     * @param options.include - Optional enrichment fields: `"tags"`, `"taxonomies"`
      */
     listFiles(options?: {
         prefix?: string;
@@ -662,6 +719,8 @@ declare class StowServer {
         bucket?: string;
         /** Filter by tag slug */
         tag?: string;
+        /** Enrichment fields to include in each file item */
+        include?: FileIncludeField[];
     }): Promise<ListFilesResult>;
     /**
      * Delete a file by key
@@ -680,9 +739,12 @@ declare class StowServer {
     }>;
     /**
      * Get a single file by key
+     *
+     * @param options.include - Optional enrichment fields: `"tags"`, `"taxonomies"`
      */
     getFile(key: string, options?: {
         bucket?: string;
+        include?: FileIncludeField[];
     }): Promise<FileResult>;
     /**
      * Extract color palette from an image file.
@@ -704,6 +766,27 @@ declare class StowServer {
     embed(key: string, options?: {
         bucket?: string;
     }): Promise<TaskTriggerResult>;
+    /**
+     * Generate a title for an image file using AI vision.
+     * Requires a searchable bucket.
+     */
+    generateTitle(key: string, options?: {
+        bucket?: string;
+    }): Promise<TaskTriggerResult>;
+    /**
+     * Generate a description for an image file using AI vision.
+     * Requires a searchable bucket.
+     */
+    generateDescription(key: string, options?: {
+        bucket?: string;
+    }): Promise<TaskTriggerResult>;
+    /**
+     * Generate alt text for an image file using AI vision.
+     * Requires a searchable bucket.
+     */
+    generateAltText(key: string, options?: {
+        bucket?: string;
+    }): Promise<TaskTriggerResult>;
     /**
      * Replace a file's content by fetching from a new URL.
      *
@@ -835,4 +918,4 @@ declare class StowServer {
     private renameProfileCluster;
 }
 
-export { type BucketResult, type ColorSearchRequest, type ColorSearchResult, type ColorSearchResultItem, type ConfirmUploadRequest, type CreateBucketRequest, type DeleteProfileSignalsResult, type DiverseSearchRequest, type Drop, type DropResult, type FileColor, type FileColorProfile, type FileResult, type FilteredMetadata, type ListBucketsResult, type ListDropsResult, type ListFilesItem, type ListFilesResult, type PresignDedupeResult, type PresignNewResult, type PresignRequest, type PresignResult, type ProfileClusterResult, type ProfileCreateRequest, type ProfileFilesResult, type ProfileResult, type ProfileSignalInput, type ProfileSignalResult, type ProfileSignalType, type ProfileSignalsResponse, type ReclusterRequest, type ReclusterResult, type RenameClusterRequest, type ReplaceResult, type SearchFilters, type SearchIncludeField, type SearchResultItem, type SimilarSearchRequest, type SimilarSearchResult, StowError, StowServer, type StowServerConfig, type TaskTriggerResult, type TextSearchRequest, type TransformOptions, type UpdateBucketRequest, type UploadResult, type WhoamiResult };
+export { type BucketResult, type ColorSearchRequest, type ColorSearchResult, type ColorSearchResultItem, type ConfirmUploadRequest, type CreateBucketRequest, type DeleteProfileSignalsResult, type DiverseSearchRequest, type Drop, type DropResult, type FileColor, type FileColorProfile, type FileIncludeField, type FileResult, type FileTag, type FileTaxonomy, type FilteredMetadata, type ListBucketsResult, type ListDropsResult, type ListFilesItem, type ListFilesResult, type PresignDedupeResult, type PresignNewResult, type PresignRequest, type PresignResult, type ProfileClusterResult, type ProfileCreateRequest, type ProfileFilesResult, type ProfileResult, type ProfileSignalInput, type ProfileSignalResult, type ProfileSignalType, type ProfileSignalsResponse, type QueuedResult, type ReclusterRequest, type ReclusterResult, type RenameClusterRequest, type ReplaceResult, type SearchFilters, type SearchIncludeField, type SearchResultItem, type SimilarSearchRequest, type SimilarSearchResult, StowError, StowServer, type StowServerConfig, type TaskTriggerResult, type TextSearchRequest, type TransformOptions, type UpdateBucketRequest, type UploadResult, type WhoamiResult };

package/dist/index.js

@@ -72,6 +72,10 @@ var uploadResultSchema = import_zod.z.object({
   metadata: import_zod.z.record(import_zod.z.string(), import_zod.z.string()).optional(),
   deduped: import_zod.z.boolean().optional()
 });
+var queuedResultSchema = import_zod.z.object({
+  status: import_zod.z.literal("queued"),
+  jobId: import_zod.z.string()
+});
 var bucketSchema = import_zod.z.object({
   id: import_zod.z.string(),
   name: import_zod.z.string(),
@@ -105,6 +109,23 @@ var whoamiSchema = import_zod.z.object({
     permissions: import_zod.z.record(import_zod.z.string(), import_zod.z.boolean())
   }).optional()
 });
+var fileTagSchema = import_zod.z.object({
+  id: import_zod.z.string(),
+  name: import_zod.z.string(),
+  slug: import_zod.z.string(),
+  color: import_zod.z.string().nullable()
+});
+var fileTaxonomySchema = import_zod.z.object({
+  id: import_zod.z.string(),
+  name: import_zod.z.string(),
+  slug: import_zod.z.string(),
+  similarity: import_zod.z.number(),
+  group: import_zod.z.object({
+    id: import_zod.z.string(),
+    name: import_zod.z.string(),
+    slug: import_zod.z.string()
+  })
+});
 var listFilesSchema = import_zod.z.object({
   files: import_zod.z.array(
     import_zod.z.object({
@@ -112,12 +133,16 @@ var listFilesSchema = import_zod.z.object({
       size: import_zod.z.number(),
       lastModified: import_zod.z.string(),
       url: import_zod.z.string().nullable(),
+      contentType: import_zod.z.string().optional(),
       width: import_zod.z.number().nullable().optional(),
       height: import_zod.z.number().nullable().optional(),
       duration: import_zod.z.number().nullable().optional(),
+      embeddingStatus: import_zod.z.string().nullable().optional(),
       metadata: import_zod.z.record(import_zod.z.string(), import_zod.z.string()).optional(),
       colorProfile: fileColorProfileSchema.nullable().optional(),
-      colors: import_zod.z.array(fileColorSchema).optional()
+      colors: import_zod.z.array(fileColorSchema).optional(),
+      tags: import_zod.z.array(fileTagSchema).optional(),
+      taxonomies: import_zod.z.array(fileTaxonomySchema).optional()
     })
   ),
   nextCursor: import_zod.z.string().nullable()
@@ -192,7 +217,9 @@ var fileResultSchema = import_zod.z.object({
   colorProfile: fileColorProfileSchema.nullable(),
   colors: import_zod.z.array(fileColorSchema),
   embeddingStatus: import_zod.z.string().nullable(),
-  createdAt: import_zod.z.string()
+  createdAt: import_zod.z.string(),
+  tags: import_zod.z.array(fileTagSchema).optional(),
+  taxonomies: import_zod.z.array(fileTaxonomySchema).optional()
 });
 var profileClusterResultSchema = import_zod.z.object({
   id: import_zod.z.string(),
@@ -540,6 +567,33 @@ var StowServer = class {
       ...result.metadata ? { metadata: result.metadata } : {}
     };
   }
+  /**
+   * Queue a URL upload for async processing via BullMQ.
+   *
+   * Unlike `uploadFromUrl()`, this returns immediately with a job ID.
+   * The actual fetch, validation, and upload happen in a background worker.
+   * Use this for bulk imports where you don't need immediate confirmation.
+   */
+  async queueUploadFromUrl(url, filename, options) {
+    return this.request(
+      this.withBucket("/api/upload", options?.bucket),
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          url,
+          filename,
+          async: true,
+          ...options?.metadata ? { metadata: options.metadata } : {},
+          ...options?.headers ? { headers: options.headers } : {},
+          ...options?.title ? { title: true } : {},
+          ...options?.describe ? { describe: true } : {},
+          ...options?.altText ? { altText: true } : {}
+        })
+      },
+      queuedResultSchema
+    );
+  }
   /**
    * Get a presigned URL for direct client-side upload.
    *
@@ -615,6 +669,8 @@ var StowServer = class {
   }
   /**
    * List files in the bucket
+   *
+   * @param options.include - Optional enrichment fields: `"tags"`, `"taxonomies"`
    */
   listFiles(options) {
     const params = new URLSearchParams();
@@ -630,6 +686,9 @@ var StowServer = class {
     if (options?.tag) {
       params.set("tag", options.tag);
     }
+    if (options?.include?.length) {
+      params.set("include", options.include.join(","));
+    }
     const path = `/api/files?${params}`;
     return this.request(
       this.withBucket(path, options?.bucket),
@@ -659,9 +718,16 @@ var StowServer = class {
   }
   /**
    * Get a single file by key
+   *
+   * @param options.include - Optional enrichment fields: `"tags"`, `"taxonomies"`
    */
   getFile(key, options) {
-    const path = `/api/files/${encodeURIComponent(key)}`;
+    const params = new URLSearchParams();
+    if (options?.include?.length) {
+      params.set("include", options.include.join(","));
+    }
+    const qs = params.toString();
+    const path = `/api/files/${encodeURIComponent(key)}${qs ? `?${qs}` : ""}`;
     return this.request(
       this.withBucket(path, options?.bucket),
       { method: "GET" },
@@ -673,7 +739,7 @@ var StowServer = class {
    * Requires a searchable bucket.
    */
   extractColors(key, options) {
-    const path = `/api/files/${encodeURIComponent(key)}/extract-colors`;
+    const path = `/api/files/${encodeURIComponent(key)}/colors`;
     return this.request(
       this.withBucket(path, options?.bucket),
       { method: "POST" },
@@ -684,7 +750,7 @@ var StowServer = class {
    * Extract dimensions (width/height) from an image or video file.
    */
   extractDimensions(key, options) {
-    const path = `/api/files/${encodeURIComponent(key)}/extract-dimensions`;
+    const path = `/api/files/${encodeURIComponent(key)}/dimensions`;
     return this.request(
       this.withBucket(path, options?.bucket),
       { method: "POST" },
@@ -696,7 +762,43 @@ var StowServer = class {
    * Requires a searchable bucket.
    */
   embed(key, options) {
-    const path = `/api/files/${encodeURIComponent(key)}/embed`;
+    const path = `/api/files/${encodeURIComponent(key)}/embedding`;
+    return this.request(
+      this.withBucket(path, options?.bucket),
+      { method: "POST" },
+      taskTriggerResultSchema
+    );
+  }
+  /**
+   * Generate a title for an image file using AI vision.
+   * Requires a searchable bucket.
+   */
+  generateTitle(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/title`;
+    return this.request(
+      this.withBucket(path, options?.bucket),
+      { method: "POST" },
+      taskTriggerResultSchema
+    );
+  }
+  /**
+   * Generate a description for an image file using AI vision.
+   * Requires a searchable bucket.
+   */
+  generateDescription(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/description`;
+    return this.request(
+      this.withBucket(path, options?.bucket),
+      { method: "POST" },
+      taskTriggerResultSchema
+    );
+  }
+  /**
+   * Generate alt text for an image file using AI vision.
+   * Requires a searchable bucket.
+   */
+  generateAltText(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/alt-text`;
     return this.request(
       this.withBucket(path, options?.bucket),
       { method: "POST" },

package/dist/index.mjs

@@ -47,6 +47,10 @@ var uploadResultSchema = z.object({
   metadata: z.record(z.string(), z.string()).optional(),
   deduped: z.boolean().optional()
 });
+var queuedResultSchema = z.object({
+  status: z.literal("queued"),
+  jobId: z.string()
+});
 var bucketSchema = z.object({
   id: z.string(),
   name: z.string(),
@@ -80,6 +84,23 @@ var whoamiSchema = z.object({
     permissions: z.record(z.string(), z.boolean())
   }).optional()
 });
+var fileTagSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  color: z.string().nullable()
+});
+var fileTaxonomySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  similarity: z.number(),
+  group: z.object({
+    id: z.string(),
+    name: z.string(),
+    slug: z.string()
+  })
+});
 var listFilesSchema = z.object({
   files: z.array(
     z.object({
@@ -87,12 +108,16 @@ var listFilesSchema = z.object({
       size: z.number(),
       lastModified: z.string(),
       url: z.string().nullable(),
+      contentType: z.string().optional(),
       width: z.number().nullable().optional(),
       height: z.number().nullable().optional(),
       duration: z.number().nullable().optional(),
+      embeddingStatus: z.string().nullable().optional(),
       metadata: z.record(z.string(), z.string()).optional(),
       colorProfile: fileColorProfileSchema.nullable().optional(),
-      colors: z.array(fileColorSchema).optional()
+      colors: z.array(fileColorSchema).optional(),
+      tags: z.array(fileTagSchema).optional(),
+      taxonomies: z.array(fileTaxonomySchema).optional()
     })
   ),
   nextCursor: z.string().nullable()
@@ -167,7 +192,9 @@ var fileResultSchema = z.object({
   colorProfile: fileColorProfileSchema.nullable(),
   colors: z.array(fileColorSchema),
   embeddingStatus: z.string().nullable(),
-  createdAt: z.string()
+  createdAt: z.string(),
+  tags: z.array(fileTagSchema).optional(),
+  taxonomies: z.array(fileTaxonomySchema).optional()
 });
 var profileClusterResultSchema = z.object({
   id: z.string(),
@@ -515,6 +542,33 @@ var StowServer = class {
       ...result.metadata ? { metadata: result.metadata } : {}
     };
   }
+  /**
+   * Queue a URL upload for async processing via BullMQ.
+   *
+   * Unlike `uploadFromUrl()`, this returns immediately with a job ID.
+   * The actual fetch, validation, and upload happen in a background worker.
+   * Use this for bulk imports where you don't need immediate confirmation.
+   */
+  async queueUploadFromUrl(url, filename, options) {
+    return this.request(
+      this.withBucket("/api/upload", options?.bucket),
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          url,
+          filename,
+          async: true,
+          ...options?.metadata ? { metadata: options.metadata } : {},
+          ...options?.headers ? { headers: options.headers } : {},
+          ...options?.title ? { title: true } : {},
+          ...options?.describe ? { describe: true } : {},
+          ...options?.altText ? { altText: true } : {}
+        })
+      },
+      queuedResultSchema
+    );
+  }
   /**
    * Get a presigned URL for direct client-side upload.
    *
@@ -590,6 +644,8 @@ var StowServer = class {
   }
   /**
    * List files in the bucket
+   *
+   * @param options.include - Optional enrichment fields: `"tags"`, `"taxonomies"`
    */
   listFiles(options) {
     const params = new URLSearchParams();
@@ -605,6 +661,9 @@ var StowServer = class {
     if (options?.tag) {
       params.set("tag", options.tag);
     }
+    if (options?.include?.length) {
+      params.set("include", options.include.join(","));
+    }
     const path = `/api/files?${params}`;
     return this.request(
       this.withBucket(path, options?.bucket),
@@ -634,9 +693,16 @@ var StowServer = class {
   }
   /**
    * Get a single file by key
+   *
+   * @param options.include - Optional enrichment fields: `"tags"`, `"taxonomies"`
    */
   getFile(key, options) {
-    const path = `/api/files/${encodeURIComponent(key)}`;
+    const params = new URLSearchParams();
+    if (options?.include?.length) {
+      params.set("include", options.include.join(","));
+    }
+    const qs = params.toString();
+    const path = `/api/files/${encodeURIComponent(key)}${qs ? `?${qs}` : ""}`;
     return this.request(
       this.withBucket(path, options?.bucket),
       { method: "GET" },
@@ -648,7 +714,7 @@ var StowServer = class {
    * Requires a searchable bucket.
    */
   extractColors(key, options) {
-    const path = `/api/files/${encodeURIComponent(key)}/extract-colors`;
+    const path = `/api/files/${encodeURIComponent(key)}/colors`;
     return this.request(
       this.withBucket(path, options?.bucket),
       { method: "POST" },
@@ -659,7 +725,7 @@ var StowServer = class {
    * Extract dimensions (width/height) from an image or video file.
    */
   extractDimensions(key, options) {
-    const path = `/api/files/${encodeURIComponent(key)}/extract-dimensions`;
+    const path = `/api/files/${encodeURIComponent(key)}/dimensions`;
     return this.request(
       this.withBucket(path, options?.bucket),
       { method: "POST" },
@@ -671,7 +737,43 @@ var StowServer = class {
    * Requires a searchable bucket.
    */
   embed(key, options) {
-    const path = `/api/files/${encodeURIComponent(key)}/embed`;
+    const path = `/api/files/${encodeURIComponent(key)}/embedding`;
+    return this.request(
+      this.withBucket(path, options?.bucket),
+      { method: "POST" },
+      taskTriggerResultSchema
+    );
+  }
+  /**
+   * Generate a title for an image file using AI vision.
+   * Requires a searchable bucket.
+   */
+  generateTitle(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/title`;
+    return this.request(
+      this.withBucket(path, options?.bucket),
+      { method: "POST" },
+      taskTriggerResultSchema
+    );
+  }
+  /**
+   * Generate a description for an image file using AI vision.
+   * Requires a searchable bucket.
+   */
+  generateDescription(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/description`;
+    return this.request(
+      this.withBucket(path, options?.bucket),
+      { method: "POST" },
+      taskTriggerResultSchema
+    );
+  }
+  /**
+   * Generate alt text for an image file using AI vision.
+   * Requires a searchable bucket.
+   */
+  generateAltText(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/alt-text`;
     return this.request(
       this.withBucket(path, options?.bucket),
       { method: "POST" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/stow-server",
-  "version": "0.3.2",
+  "version": "0.6.0",
   "description": "Server-side SDK for Stow file storage",
   "license": "MIT",
   "repository": {