@howells/stow-server 0.2.0 → 0.3.1

package/dist/index.d.mts

@@ -21,11 +21,13 @@
  * console.log(result.url);
  * ```
  */
+/** Error thrown when the Stow API returns a non-success response. */
 declare class StowError extends Error {
     readonly status: number;
     readonly code?: string;
     constructor(message: string, status: number, code?: string);
 }
+/** Configuration for creating a {@link StowServer} instance. */
 interface StowServerConfig {
     apiKey: string;
     baseUrl?: string;
@@ -36,6 +38,7 @@ interface StowServerConfig {
     /** Request timeout in ms (default 30000) */
     timeout?: number;
 }
+/** Response returned after an upload, confirm, or replace operation. */
 interface UploadResult {
     contentType: string;
     /** True when upload short-circuited to an existing file by content hash dedupe. */
@@ -45,6 +48,7 @@ interface UploadResult {
     size: number;
     url: string | null;
 }
+/** Bucket metadata returned by bucket APIs. */
 interface BucketResult {
     allowedTypes?: string[] | null;
     createdAt?: string;
@@ -59,9 +63,11 @@ interface BucketResult {
     storageQuota?: number | null;
     usageBytes?: number;
 }
+/** Result payload from `listBuckets()`. */
 interface ListBucketsResult {
     buckets: BucketResult[];
 }
+/** Input payload for `createBucket()`. */
 interface CreateBucketRequest {
     allowedTypes?: string[];
     description?: string;
@@ -73,6 +79,7 @@ interface CreateBucketRequest {
     storageQuota?: number;
     webhookUrl?: string;
 }
+/** Partial update payload for `updateBucket()`. */
 interface UpdateBucketRequest {
     allowedTypes?: string[] | null;
     description?: string | null;
@@ -84,6 +91,7 @@ interface UpdateBucketRequest {
     storageQuota?: number | null;
     webhookUrl?: string | null;
 }
+/** Account and credential details for the active API key. */
 interface WhoamiResult {
     key?: {
         name: string;
@@ -99,16 +107,19 @@ interface WhoamiResult {
         email: string;
     };
 }
+/** Query parameters for signed image transform URLs. */
 interface TransformOptions {
     format?: "webp" | "avif" | "jpeg" | "png";
     height?: number;
     quality?: number;
     width?: number;
 }
+/** Paginated file listing payload. */
 interface ListFilesResult {
     files: ListFilesItem[];
     nextCursor: string | null;
 }
+/** One extracted palette color for a file. */
 interface FileColor {
     hex: string;
     hsl: {
@@ -130,6 +141,7 @@ interface FileColor {
     position: number;
     proportion: number;
 }
+/** Aggregated color profile metadata extracted from a file. */
 interface FileColorProfile {
     accent: {
         hex: string;
@@ -157,6 +169,7 @@ interface FileColorProfile {
         dominantFamily: string | null;
     };
 }
+/** File item returned from list/search APIs. */
 interface ListFilesItem {
     colorProfile?: FileColorProfile | null;
     colors?: FileColor[];
@@ -169,6 +182,7 @@ interface ListFilesItem {
     url: string | null;
     width?: number | null;
 }
+/** Result payload returned from `drop()`. */
 interface DropResult {
     contentType: string;
     filename: string;
@@ -176,6 +190,7 @@ interface DropResult {
     size: number;
     url: string;
 }
+/** Drop entity returned from drop listing APIs. */
 interface Drop {
     contentType: string;
     createdAt: string;
@@ -185,6 +200,7 @@ interface Drop {
     size: number;
     url: string;
 }
+/** Result payload from `listDrops()`. */
 interface ListDropsResult {
     drops: Drop[];
     usage: {
@@ -192,6 +208,7 @@ interface ListDropsResult {
         limit: number;
     };
 }
+/** Full file detail payload returned by `getFile()`. */
 interface FileResult {
     colorProfile: FileColorProfile | null;
     colors: FileColor[];
@@ -206,11 +223,13 @@ interface FileResult {
     url: string | null;
     width: number | null;
 }
+/** Input for creating a taste profile. */
 interface ProfileCreateRequest {
     bucket?: string;
     fileKeys?: string[];
     name?: string;
 }
+/** Cluster summary within a taste profile. */
 interface ProfileClusterResult {
     description: string | null;
     id: string;
@@ -218,8 +237,20 @@ interface ProfileClusterResult {
     name: string | null;
     nameGeneratedAt: string | null;
     signalCount: number;
+    /**
+     * Optional taxonomy terms inferred for the cluster centroid.
+     * Absent when taxonomy data is unavailable for the bucket/profile.
+     */
+    tags?: Array<{
+        group: string;
+        groupSlug: string;
+        similarity: number;
+        tag: string;
+        tagSlug: string;
+    }>;
     totalWeight: number;
 }
+/** Taste profile detail payload. */
 interface ProfileResult {
     clusters?: ProfileClusterResult[];
     createdAt: string;
@@ -230,58 +261,70 @@ interface ProfileResult {
     updatedAt: string;
     vector: number[] | null;
 }
+/** Input for recomputing profile clusters. */
 interface ReclusterRequest {
     clusterCount?: number;
 }
+/** Result payload from cluster recomputation. */
 interface ReclusterResult {
     clustered: boolean;
     clusters: ProfileClusterResult[];
     profileId: string;
     totalSignals: number;
 }
+/** Input for updating cluster display metadata. */
 interface RenameClusterRequest {
     description?: string;
     name?: string;
 }
+/** Result payload when adding/removing files from a profile. */
 interface ProfileFilesResult {
     fileCount: number;
     id: string;
 }
+/** Supported signal types used to tune taste profiles. */
 type ProfileSignalType = "view" | "view_long" | "click" | "like" | "save" | "choose" | "purchase" | "share" | "dismiss" | "skip" | "reject" | "report" | "custom";
+/** One signal item submitted to profile signal APIs. */
 interface ProfileSignalInput {
     context?: Record<string, unknown>;
     fileKey: string;
     type: ProfileSignalType;
     weight?: number;
 }
+/** Persisted profile signal entry returned by the API. */
 interface ProfileSignalResult {
     fileKey: string;
     id: string;
     type: ProfileSignalType;
     weight: number;
 }
+/** Result payload when listing or appending profile signals. */
 interface ProfileSignalsResponse {
     profileId: string;
     signals: ProfileSignalResult[];
     totalSignals: number;
     vectorUpdated: boolean;
 }
+/** Result payload after removing profile signals. */
 interface DeleteProfileSignalsResult {
     profileId: string;
     removed: number;
     totalSignals: number;
     vectorUpdated: boolean;
 }
-interface ReprocessResult {
+/** Result payload from task trigger endpoints. */
+interface TaskTriggerResult {
     key: string;
-    triggered: string[];
+    triggered: string;
 }
+/** Result payload from replace operations. */
 interface ReplaceResult {
     contentType: string;
     key: string;
     size: number;
     triggered: string[];
 }
+/** Shared structured filters for semantic search endpoints. */
 interface SearchFilters {
     color?: {
         dominantFamily?: string[];
@@ -305,7 +348,9 @@ interface SearchFilters {
     taxonomies?: string[];
     taxonomyGroups?: string[];
 }
+/** Optional enrichment blocks that can be included in search responses. */
 type SearchIncludeField = "tags" | "taxonomies" | "colors" | "colorProfile";
+/** Input payload for text-based semantic search. */
 interface TextSearchRequest {
     bucket?: string;
     filters?: SearchFilters;
@@ -333,6 +378,7 @@ interface PresignDedupeResult {
 }
 /** Presign response is either a new upload or a dedup hit. Check `result.dedupe` to differentiate. */
 type PresignResult = PresignNewResult | PresignDedupeResult;
+/** Input payload for requesting presigned upload URLs. */
 interface PresignRequest {
     /** Override the default bucket */
     bucket?: string;
@@ -347,6 +393,7 @@ interface PresignRequest {
     /** File size in bytes */
     size: number;
 }
+/** Input payload for confirming a direct upload. */
 interface ConfirmUploadRequest {
     /** Request AI-generated alt text for images */
     altText?: boolean;
@@ -355,8 +402,6 @@ interface ConfirmUploadRequest {
     /** SHA-256 hex digest of file content. Stored with the file record for future dedup lookups. */
     contentHash?: string;
     contentType: string;
-    /** Fire KV sync in background instead of blocking. Saves ~100ms per upload. */
-    deferKvSync?: boolean;
     /** Request AI-generated description for images */
     describe?: boolean;
     fileKey: string;
@@ -368,6 +413,7 @@ interface ConfirmUploadRequest {
     /** Request AI-generated title for images */
     title?: boolean;
 }
+/** Input payload for similarity search. */
 interface SimilarSearchRequest {
     /** Bucket name or ID to scope search */
     bucket?: string;
@@ -390,6 +436,7 @@ interface SimilarSearchRequest {
     /** Search directly with a vector (1024 dimensions) */
     vector?: number[];
 }
+/** Input payload for diversity-aware search. */
 interface DiverseSearchRequest {
     /** Bucket name or ID to scope search */
     bucket?: string;
@@ -414,6 +461,7 @@ interface DiverseSearchRequest {
     /** Search directly with a vector (1024 dimensions) as the relevance seed */
     vector?: number[];
 }
+/** One semantic search result item. */
 interface SearchResultItem {
     bucketId: string;
     colorProfile?: FileColorProfile | null;
@@ -441,15 +489,18 @@ interface SearchResultItem {
     }>;
     width?: number | null;
 }
+/** Metadata describing server-side filter pruning. */
 interface FilteredMetadata {
     candidatesScanned: number;
     requested: number;
     returned: number;
 }
+/** Result payload returned by similarity/diversity search endpoints. */
 interface SimilarSearchResult {
     filtered?: FilteredMetadata;
     results: SearchResultItem[];
 }
+/** Input payload for color similarity search. */
 interface ColorSearchRequest {
     /** Bucket name or ID to scope search */
     bucket?: string;
@@ -468,6 +519,7 @@ interface ColorSearchRequest {
         b: number;
     };
 }
+/** One color search result item. */
 interface ColorSearchResultItem {
     bucketId: string;
     colorDistance: number;
@@ -486,9 +538,11 @@ interface ColorSearchResultItem {
         proportion: number;
     };
 }
+/** Result payload for color similarity search. */
 interface ColorSearchResult {
     results: ColorSearchResultItem[];
 }
+/** Server-side SDK client for Stow's API. */
 declare class StowServer {
     private readonly apiKey;
     private readonly baseUrl;
@@ -631,12 +685,19 @@ declare class StowServer {
         bucket?: string;
     }): Promise<FileResult>;
     /**
-     * Reprocess a file: reset all derived data (embeddings, colors, dimensions,
-     * AI metadata, taxonomies) and re-trigger processing tasks.
+     * Extract color palette from an image file.
+     * Requires a searchable bucket.
      */
-    reprocessFile(key: string, options?: {
-        bucket?: string;
-    }): Promise<ReprocessResult>;
+    extractColors(key: string): Promise<TaskTriggerResult>;
+    /**
+     * Extract dimensions (width/height) from an image or video file.
+     */
+    extractDimensions(key: string): Promise<TaskTriggerResult>;
+    /**
+     * Generate a vector embedding for an image file.
+     * Requires a searchable bucket.
+     */
+    embed(key: string): Promise<TaskTriggerResult>;
     /**
      * Replace a file's content by fetching from a new URL.
      *
@@ -768,4 +829,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 ReprocessResult, type SearchFilters, type SearchIncludeField, type SearchResultItem, type SimilarSearchRequest, type SimilarSearchResult, StowError, StowServer, type StowServerConfig, 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 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 };

package/dist/index.d.ts

@@ -21,11 +21,13 @@
  * console.log(result.url);
  * ```
  */
+/** Error thrown when the Stow API returns a non-success response. */
 declare class StowError extends Error {
     readonly status: number;
     readonly code?: string;
     constructor(message: string, status: number, code?: string);
 }
+/** Configuration for creating a {@link StowServer} instance. */
 interface StowServerConfig {
     apiKey: string;
     baseUrl?: string;
@@ -36,6 +38,7 @@ interface StowServerConfig {
     /** Request timeout in ms (default 30000) */
     timeout?: number;
 }
+/** Response returned after an upload, confirm, or replace operation. */
 interface UploadResult {
     contentType: string;
     /** True when upload short-circuited to an existing file by content hash dedupe. */
@@ -45,6 +48,7 @@ interface UploadResult {
     size: number;
     url: string | null;
 }
+/** Bucket metadata returned by bucket APIs. */
 interface BucketResult {
     allowedTypes?: string[] | null;
     createdAt?: string;
@@ -59,9 +63,11 @@ interface BucketResult {
     storageQuota?: number | null;
     usageBytes?: number;
 }
+/** Result payload from `listBuckets()`. */
 interface ListBucketsResult {
     buckets: BucketResult[];
 }
+/** Input payload for `createBucket()`. */
 interface CreateBucketRequest {
     allowedTypes?: string[];
     description?: string;
@@ -73,6 +79,7 @@ interface CreateBucketRequest {
     storageQuota?: number;
     webhookUrl?: string;
 }
+/** Partial update payload for `updateBucket()`. */
 interface UpdateBucketRequest {
     allowedTypes?: string[] | null;
     description?: string | null;
@@ -84,6 +91,7 @@ interface UpdateBucketRequest {
     storageQuota?: number | null;
     webhookUrl?: string | null;
 }
+/** Account and credential details for the active API key. */
 interface WhoamiResult {
     key?: {
         name: string;
@@ -99,16 +107,19 @@ interface WhoamiResult {
         email: string;
     };
 }
+/** Query parameters for signed image transform URLs. */
 interface TransformOptions {
     format?: "webp" | "avif" | "jpeg" | "png";
     height?: number;
     quality?: number;
     width?: number;
 }
+/** Paginated file listing payload. */
 interface ListFilesResult {
     files: ListFilesItem[];
     nextCursor: string | null;
 }
+/** One extracted palette color for a file. */
 interface FileColor {
     hex: string;
     hsl: {
@@ -130,6 +141,7 @@ interface FileColor {
     position: number;
     proportion: number;
 }
+/** Aggregated color profile metadata extracted from a file. */
 interface FileColorProfile {
     accent: {
         hex: string;
@@ -157,6 +169,7 @@ interface FileColorProfile {
         dominantFamily: string | null;
     };
 }
+/** File item returned from list/search APIs. */
 interface ListFilesItem {
     colorProfile?: FileColorProfile | null;
     colors?: FileColor[];
@@ -169,6 +182,7 @@ interface ListFilesItem {
     url: string | null;
     width?: number | null;
 }
+/** Result payload returned from `drop()`. */
 interface DropResult {
     contentType: string;
     filename: string;
@@ -176,6 +190,7 @@ interface DropResult {
     size: number;
     url: string;
 }
+/** Drop entity returned from drop listing APIs. */
 interface Drop {
     contentType: string;
     createdAt: string;
@@ -185,6 +200,7 @@ interface Drop {
     size: number;
     url: string;
 }
+/** Result payload from `listDrops()`. */
 interface ListDropsResult {
     drops: Drop[];
     usage: {
@@ -192,6 +208,7 @@ interface ListDropsResult {
         limit: number;
     };
 }
+/** Full file detail payload returned by `getFile()`. */
 interface FileResult {
     colorProfile: FileColorProfile | null;
     colors: FileColor[];
@@ -206,11 +223,13 @@ interface FileResult {
     url: string | null;
     width: number | null;
 }
+/** Input for creating a taste profile. */
 interface ProfileCreateRequest {
     bucket?: string;
     fileKeys?: string[];
     name?: string;
 }
+/** Cluster summary within a taste profile. */
 interface ProfileClusterResult {
     description: string | null;
     id: string;
@@ -218,8 +237,20 @@ interface ProfileClusterResult {
     name: string | null;
     nameGeneratedAt: string | null;
     signalCount: number;
+    /**
+     * Optional taxonomy terms inferred for the cluster centroid.
+     * Absent when taxonomy data is unavailable for the bucket/profile.
+     */
+    tags?: Array<{
+        group: string;
+        groupSlug: string;
+        similarity: number;
+        tag: string;
+        tagSlug: string;
+    }>;
     totalWeight: number;
 }
+/** Taste profile detail payload. */
 interface ProfileResult {
     clusters?: ProfileClusterResult[];
     createdAt: string;
@@ -230,58 +261,70 @@ interface ProfileResult {
     updatedAt: string;
     vector: number[] | null;
 }
+/** Input for recomputing profile clusters. */
 interface ReclusterRequest {
     clusterCount?: number;
 }
+/** Result payload from cluster recomputation. */
 interface ReclusterResult {
     clustered: boolean;
     clusters: ProfileClusterResult[];
     profileId: string;
     totalSignals: number;
 }
+/** Input for updating cluster display metadata. */
 interface RenameClusterRequest {
     description?: string;
     name?: string;
 }
+/** Result payload when adding/removing files from a profile. */
 interface ProfileFilesResult {
     fileCount: number;
     id: string;
 }
+/** Supported signal types used to tune taste profiles. */
 type ProfileSignalType = "view" | "view_long" | "click" | "like" | "save" | "choose" | "purchase" | "share" | "dismiss" | "skip" | "reject" | "report" | "custom";
+/** One signal item submitted to profile signal APIs. */
 interface ProfileSignalInput {
     context?: Record<string, unknown>;
     fileKey: string;
     type: ProfileSignalType;
     weight?: number;
 }
+/** Persisted profile signal entry returned by the API. */
 interface ProfileSignalResult {
     fileKey: string;
     id: string;
     type: ProfileSignalType;
     weight: number;
 }
+/** Result payload when listing or appending profile signals. */
 interface ProfileSignalsResponse {
     profileId: string;
     signals: ProfileSignalResult[];
     totalSignals: number;
     vectorUpdated: boolean;
 }
+/** Result payload after removing profile signals. */
 interface DeleteProfileSignalsResult {
     profileId: string;
     removed: number;
     totalSignals: number;
     vectorUpdated: boolean;
 }
-interface ReprocessResult {
+/** Result payload from task trigger endpoints. */
+interface TaskTriggerResult {
     key: string;
-    triggered: string[];
+    triggered: string;
 }
+/** Result payload from replace operations. */
 interface ReplaceResult {
     contentType: string;
     key: string;
     size: number;
     triggered: string[];
 }
+/** Shared structured filters for semantic search endpoints. */
 interface SearchFilters {
     color?: {
         dominantFamily?: string[];
@@ -305,7 +348,9 @@ interface SearchFilters {
     taxonomies?: string[];
     taxonomyGroups?: string[];
 }
+/** Optional enrichment blocks that can be included in search responses. */
 type SearchIncludeField = "tags" | "taxonomies" | "colors" | "colorProfile";
+/** Input payload for text-based semantic search. */
 interface TextSearchRequest {
     bucket?: string;
     filters?: SearchFilters;
@@ -333,6 +378,7 @@ interface PresignDedupeResult {
 }
 /** Presign response is either a new upload or a dedup hit. Check `result.dedupe` to differentiate. */
 type PresignResult = PresignNewResult | PresignDedupeResult;
+/** Input payload for requesting presigned upload URLs. */
 interface PresignRequest {
     /** Override the default bucket */
     bucket?: string;
@@ -347,6 +393,7 @@ interface PresignRequest {
     /** File size in bytes */
     size: number;
 }
+/** Input payload for confirming a direct upload. */
 interface ConfirmUploadRequest {
     /** Request AI-generated alt text for images */
     altText?: boolean;
@@ -355,8 +402,6 @@ interface ConfirmUploadRequest {
     /** SHA-256 hex digest of file content. Stored with the file record for future dedup lookups. */
     contentHash?: string;
     contentType: string;
-    /** Fire KV sync in background instead of blocking. Saves ~100ms per upload. */
-    deferKvSync?: boolean;
     /** Request AI-generated description for images */
     describe?: boolean;
     fileKey: string;
@@ -368,6 +413,7 @@ interface ConfirmUploadRequest {
     /** Request AI-generated title for images */
     title?: boolean;
 }
+/** Input payload for similarity search. */
 interface SimilarSearchRequest {
     /** Bucket name or ID to scope search */
     bucket?: string;
@@ -390,6 +436,7 @@ interface SimilarSearchRequest {
     /** Search directly with a vector (1024 dimensions) */
     vector?: number[];
 }
+/** Input payload for diversity-aware search. */
 interface DiverseSearchRequest {
     /** Bucket name or ID to scope search */
     bucket?: string;
@@ -414,6 +461,7 @@ interface DiverseSearchRequest {
     /** Search directly with a vector (1024 dimensions) as the relevance seed */
     vector?: number[];
 }
+/** One semantic search result item. */
 interface SearchResultItem {
     bucketId: string;
     colorProfile?: FileColorProfile | null;
@@ -441,15 +489,18 @@ interface SearchResultItem {
     }>;
     width?: number | null;
 }
+/** Metadata describing server-side filter pruning. */
 interface FilteredMetadata {
     candidatesScanned: number;
     requested: number;
     returned: number;
 }
+/** Result payload returned by similarity/diversity search endpoints. */
 interface SimilarSearchResult {
     filtered?: FilteredMetadata;
     results: SearchResultItem[];
 }
+/** Input payload for color similarity search. */
 interface ColorSearchRequest {
     /** Bucket name or ID to scope search */
     bucket?: string;
@@ -468,6 +519,7 @@ interface ColorSearchRequest {
         b: number;
     };
 }
+/** One color search result item. */
 interface ColorSearchResultItem {
     bucketId: string;
     colorDistance: number;
@@ -486,9 +538,11 @@ interface ColorSearchResultItem {
         proportion: number;
     };
 }
+/** Result payload for color similarity search. */
 interface ColorSearchResult {
     results: ColorSearchResultItem[];
 }
+/** Server-side SDK client for Stow's API. */
 declare class StowServer {
     private readonly apiKey;
     private readonly baseUrl;
@@ -631,12 +685,19 @@ declare class StowServer {
         bucket?: string;
     }): Promise<FileResult>;
     /**
-     * Reprocess a file: reset all derived data (embeddings, colors, dimensions,
-     * AI metadata, taxonomies) and re-trigger processing tasks.
+     * Extract color palette from an image file.
+     * Requires a searchable bucket.
      */
-    reprocessFile(key: string, options?: {
-        bucket?: string;
-    }): Promise<ReprocessResult>;
+    extractColors(key: string): Promise<TaskTriggerResult>;
+    /**
+     * Extract dimensions (width/height) from an image or video file.
+     */
+    extractDimensions(key: string): Promise<TaskTriggerResult>;
+    /**
+     * Generate a vector embedding for an image file.
+     * Requires a searchable bucket.
+     */
+    embed(key: string): Promise<TaskTriggerResult>;
     /**
      * Replace a file's content by fetching from a new URL.
      *
@@ -768,4 +829,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 ReprocessResult, type SearchFilters, type SearchIncludeField, type SearchResultItem, type SimilarSearchRequest, type SimilarSearchResult, StowError, StowServer, type StowServerConfig, 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 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 };

package/dist/index.js

@@ -122,9 +122,9 @@ var listFilesSchema = import_zod.z.object({
   ),
   nextCursor: import_zod.z.string().nullable()
 });
-var reprocessResultSchema = import_zod.z.object({
+var taskTriggerResultSchema = import_zod.z.object({
   key: import_zod.z.string(),
-  triggered: import_zod.z.array(import_zod.z.string())
+  triggered: import_zod.z.string()
 });
 var replaceResultSchema = import_zod.z.object({
   key: import_zod.z.string(),
@@ -201,7 +201,16 @@ var profileClusterResultSchema = import_zod.z.object({
   description: import_zod.z.string().nullable(),
   signalCount: import_zod.z.number().int(),
   totalWeight: import_zod.z.number(),
-  nameGeneratedAt: import_zod.z.string().nullable()
+  nameGeneratedAt: import_zod.z.string().nullable(),
+  tags: import_zod.z.array(
+    import_zod.z.object({
+      tag: import_zod.z.string(),
+      tagSlug: import_zod.z.string(),
+      group: import_zod.z.string(),
+      groupSlug: import_zod.z.string(),
+      similarity: import_zod.z.number()
+    })
+  ).optional()
 });
 var profileResultSchema = import_zod.z.object({
   id: import_zod.z.string(),
@@ -579,7 +588,6 @@ var StowServer = class {
       bucket,
       metadata,
       skipVerify,
-      deferKvSync,
       contentHash,
       title,
       describe,
@@ -596,7 +604,6 @@ var StowServer = class {
           contentType,
           ...metadata ? { metadata } : {},
           ...skipVerify ? { skipVerify } : {},
-          ...deferKvSync ? { deferKvSync } : {},
           ...contentHash ? { contentHash } : {},
           ...title ? { title } : {},
           ...describe ? { describe } : {},
@@ -662,15 +669,35 @@ var StowServer = class {
     );
   }
   /**
-   * Reprocess a file: reset all derived data (embeddings, colors, dimensions,
-   * AI metadata, taxonomies) and re-trigger processing tasks.
+   * Extract color palette from an image file.
+   * Requires a searchable bucket.
    */
-  reprocessFile(key, options) {
-    const path = `/api/files/${encodeURIComponent(key)}/reprocess`;
+  extractColors(key) {
     return this.request(
-      this.withBucket(path, options?.bucket),
+      `/api/files/${encodeURIComponent(key)}/extract-colors`,
+      { method: "POST" },
+      taskTriggerResultSchema
+    );
+  }
+  /**
+   * Extract dimensions (width/height) from an image or video file.
+   */
+  extractDimensions(key) {
+    return this.request(
+      `/api/files/${encodeURIComponent(key)}/extract-dimensions`,
+      { method: "POST" },
+      taskTriggerResultSchema
+    );
+  }
+  /**
+   * Generate a vector embedding for an image file.
+   * Requires a searchable bucket.
+   */
+  embed(key) {
+    return this.request(
+      `/api/files/${encodeURIComponent(key)}/embed`,
       { method: "POST" },
-      reprocessResultSchema
+      taskTriggerResultSchema
     );
   }
   /**

package/dist/index.mjs

@@ -97,9 +97,9 @@ var listFilesSchema = z.object({
   ),
   nextCursor: z.string().nullable()
 });
-var reprocessResultSchema = z.object({
+var taskTriggerResultSchema = z.object({
   key: z.string(),
-  triggered: z.array(z.string())
+  triggered: z.string()
 });
 var replaceResultSchema = z.object({
   key: z.string(),
@@ -176,7 +176,16 @@ var profileClusterResultSchema = z.object({
   description: z.string().nullable(),
   signalCount: z.number().int(),
   totalWeight: z.number(),
-  nameGeneratedAt: z.string().nullable()
+  nameGeneratedAt: z.string().nullable(),
+  tags: z.array(
+    z.object({
+      tag: z.string(),
+      tagSlug: z.string(),
+      group: z.string(),
+      groupSlug: z.string(),
+      similarity: z.number()
+    })
+  ).optional()
 });
 var profileResultSchema = z.object({
   id: z.string(),
@@ -554,7 +563,6 @@ var StowServer = class {
       bucket,
       metadata,
       skipVerify,
-      deferKvSync,
       contentHash,
       title,
       describe,
@@ -571,7 +579,6 @@ var StowServer = class {
           contentType,
           ...metadata ? { metadata } : {},
           ...skipVerify ? { skipVerify } : {},
-          ...deferKvSync ? { deferKvSync } : {},
           ...contentHash ? { contentHash } : {},
           ...title ? { title } : {},
           ...describe ? { describe } : {},
@@ -637,15 +644,35 @@ var StowServer = class {
     );
   }
   /**
-   * Reprocess a file: reset all derived data (embeddings, colors, dimensions,
-   * AI metadata, taxonomies) and re-trigger processing tasks.
+   * Extract color palette from an image file.
+   * Requires a searchable bucket.
    */
-  reprocessFile(key, options) {
-    const path = `/api/files/${encodeURIComponent(key)}/reprocess`;
+  extractColors(key) {
     return this.request(
-      this.withBucket(path, options?.bucket),
+      `/api/files/${encodeURIComponent(key)}/extract-colors`,
+      { method: "POST" },
+      taskTriggerResultSchema
+    );
+  }
+  /**
+   * Extract dimensions (width/height) from an image or video file.
+   */
+  extractDimensions(key) {
+    return this.request(
+      `/api/files/${encodeURIComponent(key)}/extract-dimensions`,
+      { method: "POST" },
+      taskTriggerResultSchema
+    );
+  }
+  /**
+   * Generate a vector embedding for an image file.
+   * Requires a searchable bucket.
+   */
+  embed(key) {
+    return this.request(
+      `/api/files/${encodeURIComponent(key)}/embed`,
       { method: "POST" },
-      reprocessResultSchema
+      taskTriggerResultSchema
     );
   }
   /**

package/package.json

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