@howells/stow-server 0.1.2 → 0.2.0

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

@@ -38,11 +38,67 @@ interface StowServerConfig {
 }
 interface UploadResult {
     contentType: string;
+    /** True when upload short-circuited to an existing file by content hash dedupe. */
+    deduped?: boolean;
     key: string;
     metadata?: Record<string, string>;
     size: number;
     url: string | null;
 }
+interface BucketResult {
+    allowedTypes?: string[] | null;
+    createdAt?: string;
+    description?: string | null;
+    fileCount?: number;
+    fileCountLimit?: number | null;
+    id: string;
+    isPublic?: boolean;
+    maxFileSize?: number | null;
+    name: string;
+    searchable?: boolean;
+    storageQuota?: number | null;
+    usageBytes?: number;
+}
+interface ListBucketsResult {
+    buckets: BucketResult[];
+}
+interface CreateBucketRequest {
+    allowedTypes?: string[];
+    description?: string;
+    fileCountLimit?: number;
+    isPublic?: boolean;
+    maxFileSize?: number;
+    name: string;
+    searchable?: boolean;
+    storageQuota?: number;
+    webhookUrl?: string;
+}
+interface UpdateBucketRequest {
+    allowedTypes?: string[] | null;
+    description?: string | null;
+    fileCountLimit?: number | null;
+    isPublic?: boolean;
+    maxFileSize?: number | null;
+    name?: string;
+    searchable?: boolean;
+    storageQuota?: number | null;
+    webhookUrl?: string | null;
+}
+interface WhoamiResult {
+    key?: {
+        name: string;
+        permissions: Record<string, boolean>;
+        scope: string;
+    };
+    stats: {
+        bucketCount: number;
+        totalBytes: number;
+        totalFiles: number;
+    };
+    user: {
+        email: string;
+    };
+}
 interface TransformOptions {
     format?: "webp" | "avif" | "jpeg" | "png";
     height?: number;
@@ -50,15 +106,69 @@ interface TransformOptions {
     width?: number;
 }
 interface ListFilesResult {
-    files: Array<{
-        key: string;
-        size: number;
-        lastModified: string;
-        url: string | null;
-        metadata?: Record<string, string>;
-    }>;
+    files: ListFilesItem[];
     nextCursor: string | null;
 }
+interface FileColor {
+    hex: string;
+    hsl: {
+        h: number;
+        s: number;
+        l: number;
+    };
+    name: string | null;
+    oklab: {
+        L: number;
+        a: number;
+        b: number;
+    } | null;
+    oklch: {
+        l: number;
+        c: number;
+        h: number;
+    } | null;
+    position: number;
+    proportion: number;
+}
+interface FileColorProfile {
+    accent: {
+        hex: string;
+        name: string | null;
+        oklab: {
+            L: number;
+            a: number;
+            b: number;
+        } | null;
+        oklch: {
+            l: number;
+            c: number;
+            h: number;
+        } | null;
+    } | null;
+    backgroundHex: string | null;
+    colorCount: number;
+    extractedAt: string;
+    palette: {
+        mood: string;
+        brightness: number;
+        temperature: number;
+        vibrancy: number;
+        complexity: number;
+        dominantFamily: string | null;
+    };
+}
+interface ListFilesItem {
+    colorProfile?: FileColorProfile | null;
+    colors?: FileColor[];
+    duration?: number | null;
+    height?: number | null;
+    key: string;
+    lastModified: string;
+    metadata?: Record<string, string>;
+    size: number;
+    url: string | null;
+    width?: number | null;
+}
 interface DropResult {
     contentType: string;
     filename: string;
@@ -82,6 +192,127 @@ interface ListDropsResult {
         limit: number;
     };
 }
+interface FileResult {
+    colorProfile: FileColorProfile | null;
+    colors: FileColor[];
+    contentType: string;
+    createdAt: string;
+    duration: number | null;
+    embeddingStatus: string | null;
+    height: number | null;
+    key: string;
+    metadata: Record<string, string> | null;
+    size: number;
+    url: string | null;
+    width: number | null;
+}
+interface ProfileCreateRequest {
+    bucket?: string;
+    fileKeys?: string[];
+    name?: string;
+}
+interface ProfileClusterResult {
+    description: string | null;
+    id: string;
+    index: number;
+    name: string | null;
+    nameGeneratedAt: string | null;
+    signalCount: number;
+    totalWeight: number;
+}
+interface ProfileResult {
+    clusters?: ProfileClusterResult[];
+    createdAt: string;
+    fileCount: number;
+    id: string;
+    name: string | null;
+    signalCount: number;
+    updatedAt: string;
+    vector: number[] | null;
+}
+interface ReclusterRequest {
+    clusterCount?: number;
+}
+interface ReclusterResult {
+    clustered: boolean;
+    clusters: ProfileClusterResult[];
+    profileId: string;
+    totalSignals: number;
+}
+interface RenameClusterRequest {
+    description?: string;
+    name?: string;
+}
+interface ProfileFilesResult {
+    fileCount: number;
+    id: string;
+}
+type ProfileSignalType = "view" | "view_long" | "click" | "like" | "save" | "choose" | "purchase" | "share" | "dismiss" | "skip" | "reject" | "report" | "custom";
+interface ProfileSignalInput {
+    context?: Record<string, unknown>;
+    fileKey: string;
+    type: ProfileSignalType;
+    weight?: number;
+}
+interface ProfileSignalResult {
+    fileKey: string;
+    id: string;
+    type: ProfileSignalType;
+    weight: number;
+}
+interface ProfileSignalsResponse {
+    profileId: string;
+    signals: ProfileSignalResult[];
+    totalSignals: number;
+    vectorUpdated: boolean;
+}
+interface DeleteProfileSignalsResult {
+    profileId: string;
+    removed: number;
+    totalSignals: number;
+    vectorUpdated: boolean;
+}
+interface ReprocessResult {
+    key: string;
+    triggered: string[];
+}
+interface ReplaceResult {
+    contentType: string;
+    key: string;
+    size: number;
+    triggered: string[];
+}
+interface SearchFilters {
+    color?: {
+        dominantFamily?: string[];
+        mood?: string[];
+        temperature?: {
+            min?: number;
+            max?: number;
+        };
+        brightness?: {
+            min?: number;
+            max?: number;
+        };
+        vibrancy?: {
+            min?: number;
+            max?: number;
+        };
+    };
+    contentType?: string[];
+    metadata?: Record<string, string>;
+    tags?: string[];
+    taxonomies?: string[];
+    taxonomyGroups?: string[];
+}
+type SearchIncludeField = "tags" | "taxonomies" | "colors" | "colorProfile";
+interface TextSearchRequest {
+    bucket?: string;
+    filters?: SearchFilters;
+    include?: SearchIncludeField[];
+    limit?: number;
+    query: string;
+}
 /** Normal presign response — client must PUT to uploadUrl then call confirm. */
 interface PresignNewResult {
     /** URL to call to confirm the upload */
@@ -89,8 +320,6 @@ interface PresignNewResult {
     dedupe?: false;
     /** The file key that will be created */
     fileKey: string;
-    /** The R2 key for the file */
-    r2Key: string;
     /** URL to PUT the file to */
     uploadUrl: string;
 }
@@ -119,6 +348,8 @@ interface PresignRequest {
     size: number;
 }
 interface ConfirmUploadRequest {
+    /** Request AI-generated alt text for images */
+    altText?: boolean;
     /** Override the default bucket */
     bucket?: string;
     /** SHA-256 hex digest of file content. Stored with the file record for future dedup lookups. */
@@ -126,18 +357,32 @@ interface ConfirmUploadRequest {
     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;
     /** Custom metadata to attach to the file */
     metadata?: Record<string, string>;
     size: number;
     /** Skip R2 HEAD verification — trust the presign PUT. Saves ~100ms per upload. */
     skipVerify?: boolean;
+    /** Request AI-generated title for images */
+    title?: boolean;
 }
 interface SimilarSearchRequest {
     /** Bucket name or ID to scope search */
     bucket?: string;
+    /** Use a specific cluster centroid instead of the profile master vector. Requires profileId. */
+    clusterId?: string;
+    /** Blend multiple cluster centroids as query vector. Requires profileId. */
+    clusterIds?: string[];
+    /** File keys to exclude from results (e.g. already-seen items). Max 200. */
+    excludeKeys?: string[];
     /** Find files similar to this file key */
     fileKey?: string;
+    /** Structured post-filters (taxonomy, tag, color, content type, metadata) */
+    filters?: SearchFilters;
+    /** Opt-in enrichment fields to include in results */
+    include?: SearchIncludeField[];
     /** Max results (default 10, max 50) */
     limit?: number;
     /** Search using a taste profile's vector */
@@ -145,49 +390,104 @@ interface SimilarSearchRequest {
     /** Search directly with a vector (1024 dimensions) */
     vector?: number[];
 }
-interface SimilarSearchResult {
-    results: Array<{
-        id: string;
-        key: string;
-        bucketId: string;
-        originalFilename: string | null;
-        size: number;
-        contentType: string;
-        metadata: Record<string, string> | null;
-        embeddingStatus: string | null;
-        similarity: number;
-        createdAt: string;
-    }>;
+interface DiverseSearchRequest {
+    /** Bucket name or ID to scope search */
+    bucket?: string;
+    /** Use a specific cluster centroid instead of the profile master vector. Requires profileId. */
+    clusterId?: string;
+    /** Blend multiple cluster centroids as query vector. Requires profileId. */
+    clusterIds?: string[];
+    /** File keys to exclude from results (e.g. already-seen items). Max 200. */
+    excludeKeys?: string[];
+    /** Find diverse files seeded by this file key */
+    fileKey?: string;
+    /** Structured post-filters (taxonomy, tag, color, content type, metadata) */
+    filters?: SearchFilters;
+    /** Opt-in enrichment fields to include in results */
+    include?: SearchIncludeField[];
+    /** Tradeoff between relevance and diversity (0–1, default 0.5). 0 = pure diversity, 1 = pure similarity. */
+    lambda?: number;
+    /** Max results (default 10, max 50) */
+    limit?: number;
+    /** Search using a taste profile's vector as the relevance seed */
+    profileId?: string;
+    /** Search directly with a vector (1024 dimensions) as the relevance seed */
+    vector?: number[];
 }
-interface FileResult {
+interface SearchResultItem {
+    bucketId: string;
+    colorProfile?: FileColorProfile | null;
+    colors?: FileColor[];
     contentType: string;
     createdAt: string;
+    duration?: number | null;
     embeddingStatus: string | null;
+    height?: number | null;
+    id: string;
     key: string;
     metadata: Record<string, string> | null;
+    originalFilename: string | null;
+    similarity: number;
     size: number;
-    url: string | null;
+    tags?: Array<{
+        slug: string;
+        name: string;
+    }>;
+    taxonomies?: Array<{
+        slug: string;
+        name: string;
+        group: string;
+        similarity: number;
+    }>;
+    width?: number | null;
 }
-interface ProfileCreateRequest {
+interface FilteredMetadata {
+    candidatesScanned: number;
+    requested: number;
+    returned: number;
+}
+interface SimilarSearchResult {
+    filtered?: FilteredMetadata;
+    results: SearchResultItem[];
+}
+interface ColorSearchRequest {
+    /** Bucket name or ID to scope search */
     bucket?: string;
-    fileKeys?: string[];
-    name?: string;
+    /** Only search the dominant (first) color per file */
+    dominantOnly?: boolean;
+    /** Target color as hex (e.g. "#FF0000") */
+    hex?: string;
+    /** Max results (default 10, max 50) */
+    limit?: number;
+    /** Minimum color proportion in the palette (0–1, default 0.05) */
+    minProportion?: number;
+    /** Target color in OKLab space */
+    oklab?: {
+        L: number;
+        a: number;
+        b: number;
+    };
 }
-interface ProfileResult {
+interface ColorSearchResultItem {
+    bucketId: string;
+    colorDistance: number;
+    contentType: string;
     createdAt: string;
-    fileCount: number;
-    id: string;
-    name: string | null;
-    updatedAt: string;
-}
-interface ProfileFilesResult {
-    fileCount: number;
     id: string;
+    key: string;
+    matchedColor: {
+        hex: string;
+        oklab: {
+            L: number;
+            a: number;
+            b: number;
+        } | null;
+        position: number;
+        proportion: number;
+    };
 }
-interface TextSearchRequest {
-    bucket?: string;
-    limit?: number;
-    query: string;
+interface ColorSearchResult {
+    results: ColorSearchResultItem[];
 }
 declare class StowServer {
     private readonly apiKey;
@@ -200,6 +500,38 @@ declare class StowServer {
      * Get the base URL for this instance (used by client SDK)
      */
     getBaseUrl(): string;
+    /**
+     * Return account usage and API key info for the current credential.
+     */
+    whoami(): Promise<WhoamiResult>;
+    /**
+     * List all buckets available to the current organization.
+     */
+    listBuckets(): Promise<ListBucketsResult>;
+    /**
+     * Create a new bucket.
+     */
+    createBucket(request: CreateBucketRequest): Promise<BucketResult>;
+    /**
+     * Get bucket details by id.
+     */
+    getBucket(id: string): Promise<BucketResult>;
+    /**
+     * Update bucket settings by id.
+     */
+    updateBucket(id: string, updates: UpdateBucketRequest): Promise<BucketResult>;
+    /**
+     * Rename/update a bucket by current bucket name.
+     */
+    updateBucketByName(name: string, updates: UpdateBucketRequest): Promise<BucketResult>;
+    /**
+     * Rename a bucket by current bucket name.
+     */
+    renameBucket(name: string, newName: string): Promise<BucketResult>;
+    /**
+     * Delete a bucket by id.
+     */
+    deleteBucket(id: string): Promise<void>;
     /**
      * Resolve the effective bucket for this request.
      * Per-call override > constructor default.
@@ -229,6 +561,12 @@ declare class StowServer {
         bucket?: string;
         /** Custom metadata to attach to the file */
         metadata?: 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<UploadResult>;
     /**
      * Upload a file from a URL (server-side fetch + upload)
@@ -238,6 +576,12 @@ declare class StowServer {
         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<UploadResult>;
     /**
      * Get a presigned URL for direct client-side upload.
@@ -286,6 +630,25 @@ declare class StowServer {
     getFile(key: string, options?: {
         bucket?: string;
     }): Promise<FileResult>;
+    /**
+     * Reprocess a file: reset all derived data (embeddings, colors, dimensions,
+     * AI metadata, taxonomies) and re-trigger processing tasks.
+     */
+    reprocessFile(key: string, options?: {
+        bucket?: string;
+    }): Promise<ReprocessResult>;
+    /**
+     * Replace a file's content by fetching from a new URL.
+     *
+     * Keeps the same file key but replaces the stored object and resets all
+     * derived data (dimensions, embeddings, colors, AI metadata). Processing
+     * tasks are re-dispatched as if the file were newly uploaded.
+     */
+    replaceFile(key: string, url: string, options?: {
+        bucket?: string;
+        /** Headers to forward when fetching the URL (e.g. User-Agent, Referer) */
+        headers?: Record<string, string>;
+    }): Promise<ReplaceResult>;
     /**
      * Get a transform URL for an image.
      *
@@ -342,10 +705,14 @@ declare class StowServer {
      */
     get search(): {
         similar: (params: SimilarSearchRequest) => Promise<SimilarSearchResult>;
+        diverse: (params?: DiverseSearchRequest) => Promise<SimilarSearchResult>;
         text: (params: TextSearchRequest) => Promise<SimilarSearchResult>;
+        color: (params: ColorSearchRequest) => Promise<ColorSearchResult>;
     };
     private searchSimilar;
+    private searchDiverse;
     private searchText;
+    private searchColor;
     /**
      * Upload a file as a drop (quick share)
      *
@@ -379,12 +746,26 @@ declare class StowServer {
         delete: (id: string) => Promise<void>;
         addFiles: (id: string, fileKeys: string[], bucket?: string) => Promise<ProfileFilesResult>;
         removeFiles: (id: string, fileKeys: string[], bucket?: string) => Promise<ProfileFilesResult>;
+        signal: (id: string, signals: ProfileSignalInput[], bucket?: string) => Promise<ProfileSignalsResponse>;
+        deleteSignals: (id: string, signalIds: string[]) => Promise<DeleteProfileSignalsResult>;
+        clusters: (id: string) => Promise<{
+            profileId: string;
+            signalCount: number;
+            clusters: ProfileClusterResult[];
+        }>;
+        recluster: (id: string, params?: ReclusterRequest) => Promise<ReclusterResult>;
+        renameCluster: (profileId: string, clusterId: string, params: RenameClusterRequest) => Promise<ProfileClusterResult>;
     };
     private createProfile;
     private getProfile;
     private deleteProfile;
     private addProfileFiles;
     private removeProfileFiles;
+    private signalProfile;
+    private deleteProfileSignals;
+    private getProfileClusters;
+    private reclusterProfile;
+    private renameProfileCluster;
 }
 
-export { type ConfirmUploadRequest, type Drop, type DropResult, type FileResult, type ListDropsResult, type ListFilesResult, type PresignDedupeResult, type PresignNewResult, type PresignRequest, type PresignResult, type ProfileCreateRequest, type ProfileFilesResult, type ProfileResult, type SimilarSearchRequest, type SimilarSearchResult, StowError, StowServer, type StowServerConfig, type TextSearchRequest, type TransformOptions, type UploadResult };
+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 };