@howells/stow-server 0.3.0 → 0.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Stow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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;
 }
+/** Result payload from task trigger endpoints. */
 interface TaskTriggerResult {
     key: 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;
@@ -634,16 +688,22 @@ declare class StowServer {
      * 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.
      *

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;
 }
+/** Result payload from task trigger endpoints. */
 interface TaskTriggerResult {
     key: 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;
@@ -634,16 +688,22 @@ declare class StowServer {
      * 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.
      *

package/dist/index.js

@@ -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 } : {},
@@ -665,9 +672,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)}/extract-colors`;
     return this.request(
-      `/api/files/${encodeURIComponent(key)}/extract-colors`,
+      this.withBucket(path, options?.bucket),
       { method: "POST" },
       taskTriggerResultSchema
     );
@@ -675,9 +683,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)}/extract-dimensions`;
     return this.request(
-      `/api/files/${encodeURIComponent(key)}/extract-dimensions`,
+      this.withBucket(path, options?.bucket),
       { method: "POST" },
       taskTriggerResultSchema
     );
@@ -686,9 +695,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)}/embed`;
     return this.request(
-      `/api/files/${encodeURIComponent(key)}/embed`,
+      this.withBucket(path, options?.bucket),
       { method: "POST" },
       taskTriggerResultSchema
     );

package/dist/index.mjs

@@ -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 } : {},
@@ -640,9 +647,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)}/extract-colors`;
     return this.request(
-      `/api/files/${encodeURIComponent(key)}/extract-colors`,
+      this.withBucket(path, options?.bucket),
       { method: "POST" },
       taskTriggerResultSchema
     );
@@ -650,9 +658,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)}/extract-dimensions`;
     return this.request(
-      `/api/files/${encodeURIComponent(key)}/extract-dimensions`,
+      this.withBucket(path, options?.bucket),
       { method: "POST" },
       taskTriggerResultSchema
     );
@@ -661,9 +670,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)}/embed`;
     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.0",
+  "version": "0.3.2",
   "description": "Server-side SDK for Stow file storage",
   "license": "MIT",
   "repository": {
@@ -29,21 +29,21 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "peerDependencies": {
     "zod": "^3.0.0 || ^4.0.0"
   },
   "devDependencies": {
-    "@stow/typescript-config": "workspace:*",
     "@types/node": "^25.3.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18",
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "@stow/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}