@howells/stow-server 0.5.0 → 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,6 +178,7 @@ interface FileColorProfile {
 interface ListFilesItem {
     colorProfile?: FileColorProfile | null;
     colors?: FileColor[];
+    contentType?: string;
     duration?: number | null;
     embeddingStatus?: string | null;
     height?: number | null;
@@ -667,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.
      *
@@ -741,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.
      *
@@ -872,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 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 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,6 +178,7 @@ interface FileColorProfile {
 interface ListFilesItem {
     colorProfile?: FileColorProfile | null;
     colors?: FileColor[];
+    contentType?: string;
     duration?: number | null;
     embeddingStatus?: string | null;
     height?: number | null;
@@ -667,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.
      *
@@ -741,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.
      *
@@ -872,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 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 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(),
@@ -129,6 +133,7 @@ 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(),
@@ -562,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.
    *
@@ -737,6 +769,42 @@ var StowServer = class {
       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" },
+      taskTriggerResultSchema
+    );
+  }
   /**
    * Replace a file's content by fetching from a new URL.
    *

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(),
@@ -104,6 +108,7 @@ 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(),
@@ -537,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.
    *
@@ -712,6 +744,42 @@ var StowServer = class {
       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" },
+      taskTriggerResultSchema
+    );
+  }
   /**
    * Replace a file's content by fetching from a new URL.
    *

package/package.json

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