@howells/stow-server 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -31,45 +31,159 @@ interface StowServerConfig {
     baseUrl?: string;
     /** Default bucket name or ID. Required for global API keys. */
     bucket?: string;
+    /** Max retry attempts for 429/5xx errors (default 3, set 0 to disable) */
+    retries?: number;
+    /** Request timeout in ms (default 30000) */
+    timeout?: number;
 }
 interface UploadResult {
-    key: string;
-    url: string | null;
-    size: number;
     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 {
-    width?: number;
+    format?: "webp" | "avif" | "jpeg" | "png";
     height?: number;
     quality?: number;
-    format?: "webp" | "avif" | "jpeg" | "png";
+    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 {
-    shortId: string;
-    url: string;
+    contentType: string;
     filename: string;
+    shortId: string;
     size: number;
-    contentType: string;
+    url: string;
 }
 interface Drop {
+    contentType: string;
+    createdAt: string;
+    filename: string;
     id: string;
     shortId: string;
-    url: string;
-    filename: string;
     size: number;
-    contentType: string;
-    createdAt: string;
+    url: string;
 }
 interface ListDropsResult {
     drops: Drop[];
@@ -78,70 +192,346 @@ interface ListDropsResult {
         limit: number;
     };
 }
-interface PresignResult {
+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 */
+    confirmUrl: string;
+    dedupe?: false;
     /** The file key that will be created */
     fileKey: string;
     /** URL to PUT the file to */
     uploadUrl: string;
-    /** The R2 key for the file */
-    r2Key: string;
-    /** URL to call to confirm the upload */
-    confirmUrl: string;
 }
-interface PresignRequest {
-    filename: string;
+/** Dedup hit — file already exists in this bucket. No upload needed. */
+interface PresignDedupeResult {
     contentType: string;
-    /** File size in bytes */
+    dedupe: true;
+    key: string;
     size: number;
-    /** Optional route/folder */
-    route?: string;
+    url: string | null;
+}
+/** Presign response is either a new upload or a dedup hit. Check `result.dedupe` to differentiate. */
+type PresignResult = PresignNewResult | PresignDedupeResult;
+interface PresignRequest {
     /** Override the default bucket */
     bucket?: string;
+    /** SHA-256 hex digest of file content. When provided, Stow checks for an existing file with the same hash in the bucket and returns it immediately (dedup). */
+    contentHash?: string;
+    contentType: string;
+    filename: string;
     /** Custom metadata to attach to the file */
     metadata?: Record<string, string>;
+    /** Optional route/folder */
+    route?: string;
+    /** File size in bytes */
+    size: number;
 }
 interface ConfirmUploadRequest {
-    fileKey: string;
-    size: number;
-    contentType: string;
+    /** 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. */
+    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;
     /** 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 */
+    profileId?: string;
     /** Search directly with a vector (1024 dimensions) */
     vector?: number[];
+}
+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 SimilarSearchResult {
-    results: Array<{
-        id: string;
-        key: string;
-        bucketId: string;
-        originalFilename: string | null;
-        size: number;
-        contentType: string;
-        metadata: Record<string, string> | null;
-        embeddingStatus: string | null;
+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;
+    tags?: Array<{
+        slug: string;
+        name: string;
+    }>;
+    taxonomies?: Array<{
+        slug: string;
+        name: string;
+        group: string;
         similarity: number;
-        createdAt: string;
     }>;
+    width?: number | null;
+}
+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;
+    /** 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 ColorSearchResultItem {
+    bucketId: string;
+    colorDistance: number;
+    contentType: string;
+    createdAt: string;
+    id: string;
+    key: string;
+    matchedColor: {
+        hex: string;
+        oklab: {
+            L: number;
+            a: number;
+            b: number;
+        } | null;
+        position: number;
+        proportion: number;
+    };
+}
+interface ColorSearchResult {
+    results: ColorSearchResultItem[];
 }
 declare class StowServer {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly bucket?;
+    private readonly timeout;
+    private readonly retries;
     constructor(config: StowServerConfig | string);
     /**
      * 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.
@@ -152,9 +542,14 @@ declare class StowServer {
      */
     private withBucket;
     /**
-     * Make an API request with proper error handling
+     * Make an API request with retry, timeout, and error handling.
+     *
+     * - Retries on 429 (rate limit) and 5xx with exponential backoff (1s, 2s, 4s).
+     * - AbortController timeout (default 30s).
+     * - Consumer can pass `signal` in options to cancel.
      */
     private request;
+    private sleep;
     /**
      * Upload a file directly from the server
      */
@@ -166,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)
@@ -173,6 +574,14 @@ declare class StowServer {
     uploadFromUrl(url: string, filename: string, options?: {
         bucket?: string;
         metadata?: Record<string, string>;
+        /** Headers to forward when fetching the URL (e.g. User-Agent, Referer) */
+        headers?: Record<string, string>;
+        /** Request AI-generated title for images */
+        title?: boolean;
+        /** Request AI-generated description for images */
+        describe?: boolean;
+        /** Request AI-generated alt text for images */
+        altText?: boolean;
     }): Promise<UploadResult>;
     /**
      * Get a presigned URL for direct client-side upload.
@@ -215,6 +624,31 @@ declare class StowServer {
         key: string;
         metadata: Record<string, string>;
     }>;
+    /**
+     * Get a single file by key
+     */
+    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.
      *
@@ -271,8 +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)
      *
@@ -297,6 +737,35 @@ declare class StowServer {
      * Delete a drop by ID
      */
     deleteDrop(id: string): Promise<void>;
+    /**
+     * Profiles namespace for managing taste profiles
+     */
+    get profiles(): {
+        create: (params?: ProfileCreateRequest) => Promise<ProfileResult>;
+        get: (id: string) => Promise<ProfileResult>;
+        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 ListDropsResult, type ListFilesResult, type PresignRequest, type PresignResult, type SimilarSearchRequest, type SimilarSearchResult, StowError, StowServer, type StowServerConfig, 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 };