@howells/stow-server 0.3.1 → 0.5.0

package/dist/index.d.mts

@@ -174,11 +174,16 @@ interface ListFilesItem {
     colorProfile?: FileColorProfile | null;
     colors?: FileColor[];
     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 +213,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 +244,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 +378,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;
@@ -654,6 +684,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 +694,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,24 +714,33 @@ 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.
      * Requires a searchable bucket.
      */
-    extractColors(key: string): Promise<TaskTriggerResult>;
+    extractColors(key: string, options?: {
+        bucket?: string;
+    }): Promise<TaskTriggerResult>;
     /**
      * Extract dimensions (width/height) from an image or video file.
      */
-    extractDimensions(key: string): Promise<TaskTriggerResult>;
+    extractDimensions(key: string, options?: {
+        bucket?: string;
+    }): Promise<TaskTriggerResult>;
     /**
      * Generate a vector embedding for an image file.
      * Requires a searchable bucket.
      */
-    embed(key: string): Promise<TaskTriggerResult>;
+    embed(key: string, options?: {
+        bucket?: string;
+    }): Promise<TaskTriggerResult>;
     /**
      * Replace a file's content by fetching from a new URL.
      *
@@ -829,4 +872,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 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

@@ -174,11 +174,16 @@ interface ListFilesItem {
     colorProfile?: FileColorProfile | null;
     colors?: FileColor[];
     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 +213,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 +244,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 +378,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;
@@ -654,6 +684,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 +694,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,24 +714,33 @@ 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.
      * Requires a searchable bucket.
      */
-    extractColors(key: string): Promise<TaskTriggerResult>;
+    extractColors(key: string, options?: {
+        bucket?: string;
+    }): Promise<TaskTriggerResult>;
     /**
      * Extract dimensions (width/height) from an image or video file.
      */
-    extractDimensions(key: string): Promise<TaskTriggerResult>;
+    extractDimensions(key: string, options?: {
+        bucket?: string;
+    }): Promise<TaskTriggerResult>;
     /**
      * Generate a vector embedding for an image file.
      * Requires a searchable bucket.
      */
-    embed(key: string): Promise<TaskTriggerResult>;
+    embed(key: string, options?: {
+        bucket?: string;
+    }): Promise<TaskTriggerResult>;
     /**
      * Replace a file's content by fetching from a new URL.
      *
@@ -829,4 +872,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 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

@@ -105,6 +105,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({
@@ -115,9 +132,12 @@ var listFilesSchema = import_zod.z.object({
       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 +212,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(),
@@ -615,6 +637,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 +654,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 +686,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" },
@@ -672,9 +706,10 @@ var StowServer = class {
    * Extract color palette from an image file.
    * Requires a searchable bucket.
    */
-  extractColors(key) {
+  extractColors(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/colors`;
     return this.request(
-      `/api/files/${encodeURIComponent(key)}/extract-colors`,
+      this.withBucket(path, options?.bucket),
       { method: "POST" },
       taskTriggerResultSchema
     );
@@ -682,9 +717,10 @@ var StowServer = class {
   /**
    * Extract dimensions (width/height) from an image or video file.
    */
-  extractDimensions(key) {
+  extractDimensions(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/dimensions`;
     return this.request(
-      `/api/files/${encodeURIComponent(key)}/extract-dimensions`,
+      this.withBucket(path, options?.bucket),
       { method: "POST" },
       taskTriggerResultSchema
     );
@@ -693,9 +729,10 @@ var StowServer = class {
    * Generate a vector embedding for an image file.
    * Requires a searchable bucket.
    */
-  embed(key) {
+  embed(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/embedding`;
     return this.request(
-      `/api/files/${encodeURIComponent(key)}/embed`,
+      this.withBucket(path, options?.bucket),
       { method: "POST" },
       taskTriggerResultSchema
     );

package/dist/index.mjs

@@ -80,6 +80,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({
@@ -90,9 +107,12 @@ var listFilesSchema = z.object({
       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 +187,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(),
@@ -590,6 +612,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 +629,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 +661,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" },
@@ -647,9 +681,10 @@ var StowServer = class {
    * Extract color palette from an image file.
    * Requires a searchable bucket.
    */
-  extractColors(key) {
+  extractColors(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/colors`;
     return this.request(
-      `/api/files/${encodeURIComponent(key)}/extract-colors`,
+      this.withBucket(path, options?.bucket),
       { method: "POST" },
       taskTriggerResultSchema
     );
@@ -657,9 +692,10 @@ var StowServer = class {
   /**
    * Extract dimensions (width/height) from an image or video file.
    */
-  extractDimensions(key) {
+  extractDimensions(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/dimensions`;
     return this.request(
-      `/api/files/${encodeURIComponent(key)}/extract-dimensions`,
+      this.withBucket(path, options?.bucket),
       { method: "POST" },
       taskTriggerResultSchema
     );
@@ -668,9 +704,10 @@ var StowServer = class {
    * Generate a vector embedding for an image file.
    * Requires a searchable bucket.
    */
-  embed(key) {
+  embed(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/embedding`;
     return this.request(
-      `/api/files/${encodeURIComponent(key)}/embed`,
+      this.withBucket(path, options?.bucket),
       { method: "POST" },
       taskTriggerResultSchema
     );

package/package.json

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