@howells/stow-server 0.1.1 → 0.1.2

package/dist/index.d.mts

@@ -31,19 +31,23 @@ 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;
+    key: string;
     metadata?: Record<string, string>;
+    size: number;
+    url: string | null;
 }
 interface TransformOptions {
-    width?: number;
+    format?: "webp" | "avif" | "jpeg" | "png";
     height?: number;
     quality?: number;
-    format?: "webp" | "avif" | "jpeg" | "png";
+    width?: number;
 }
 interface ListFilesResult {
     files: Array<{
@@ -56,20 +60,20 @@ interface ListFilesResult {
     nextCursor: string | 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,46 +82,68 @@ interface ListDropsResult {
         limit: number;
     };
 }
-interface PresignResult {
+/** 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;
+    /** URL to PUT the file to */
+    uploadUrl: 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;
     /** 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;
+    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;
 }
 interface SimilarSearchRequest {
-    /** Find files similar to this file key */
-    fileKey?: string;
-    /** Search directly with a vector (1024 dimensions) */
-    vector?: number[];
     /** Bucket name or ID to scope search */
     bucket?: string;
+    /** Find files similar to this file key */
+    fileKey?: string;
     /** 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 SimilarSearchResult {
     results: Array<{
@@ -133,10 +159,42 @@ interface SimilarSearchResult {
         createdAt: string;
     }>;
 }
+interface FileResult {
+    contentType: string;
+    createdAt: string;
+    embeddingStatus: string | null;
+    key: string;
+    metadata: Record<string, string> | null;
+    size: number;
+    url: string | null;
+}
+interface ProfileCreateRequest {
+    bucket?: string;
+    fileKeys?: string[];
+    name?: string;
+}
+interface ProfileResult {
+    createdAt: string;
+    fileCount: number;
+    id: string;
+    name: string | null;
+    updatedAt: string;
+}
+interface ProfileFilesResult {
+    fileCount: number;
+    id: string;
+}
+interface TextSearchRequest {
+    bucket?: string;
+    limit?: number;
+    query: string;
+}
 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)
@@ -152,9 +210,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
      */
@@ -173,6 +236,8 @@ 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>;
     }): Promise<UploadResult>;
     /**
      * Get a presigned URL for direct client-side upload.
@@ -215,6 +280,12 @@ declare class StowServer {
         key: string;
         metadata: Record<string, string>;
     }>;
+    /**
+     * Get a single file by key
+     */
+    getFile(key: string, options?: {
+        bucket?: string;
+    }): Promise<FileResult>;
     /**
      * Get a transform URL for an image.
      *
@@ -271,8 +342,10 @@ declare class StowServer {
      */
     get search(): {
         similar: (params: SimilarSearchRequest) => Promise<SimilarSearchResult>;
+        text: (params: TextSearchRequest) => Promise<SimilarSearchResult>;
     };
     private searchSimilar;
+    private searchText;
     /**
      * Upload a file as a drop (quick share)
      *
@@ -297,6 +370,21 @@ 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>;
+    };
+    private createProfile;
+    private getProfile;
+    private deleteProfile;
+    private addProfileFiles;
+    private removeProfileFiles;
 }
 
-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 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 };

package/dist/index.d.ts

@@ -31,19 +31,23 @@ 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;
+    key: string;
     metadata?: Record<string, string>;
+    size: number;
+    url: string | null;
 }
 interface TransformOptions {
-    width?: number;
+    format?: "webp" | "avif" | "jpeg" | "png";
     height?: number;
     quality?: number;
-    format?: "webp" | "avif" | "jpeg" | "png";
+    width?: number;
 }
 interface ListFilesResult {
     files: Array<{
@@ -56,20 +60,20 @@ interface ListFilesResult {
     nextCursor: string | 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,46 +82,68 @@ interface ListDropsResult {
         limit: number;
     };
 }
-interface PresignResult {
+/** 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;
+    /** URL to PUT the file to */
+    uploadUrl: 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;
     /** 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;
+    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;
 }
 interface SimilarSearchRequest {
-    /** Find files similar to this file key */
-    fileKey?: string;
-    /** Search directly with a vector (1024 dimensions) */
-    vector?: number[];
     /** Bucket name or ID to scope search */
     bucket?: string;
+    /** Find files similar to this file key */
+    fileKey?: string;
     /** 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 SimilarSearchResult {
     results: Array<{
@@ -133,10 +159,42 @@ interface SimilarSearchResult {
         createdAt: string;
     }>;
 }
+interface FileResult {
+    contentType: string;
+    createdAt: string;
+    embeddingStatus: string | null;
+    key: string;
+    metadata: Record<string, string> | null;
+    size: number;
+    url: string | null;
+}
+interface ProfileCreateRequest {
+    bucket?: string;
+    fileKeys?: string[];
+    name?: string;
+}
+interface ProfileResult {
+    createdAt: string;
+    fileCount: number;
+    id: string;
+    name: string | null;
+    updatedAt: string;
+}
+interface ProfileFilesResult {
+    fileCount: number;
+    id: string;
+}
+interface TextSearchRequest {
+    bucket?: string;
+    limit?: number;
+    query: string;
+}
 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)
@@ -152,9 +210,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
      */
@@ -173,6 +236,8 @@ 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>;
     }): Promise<UploadResult>;
     /**
      * Get a presigned URL for direct client-side upload.
@@ -215,6 +280,12 @@ declare class StowServer {
         key: string;
         metadata: Record<string, string>;
     }>;
+    /**
+     * Get a single file by key
+     */
+    getFile(key: string, options?: {
+        bucket?: string;
+    }): Promise<FileResult>;
     /**
      * Get a transform URL for an image.
      *
@@ -271,8 +342,10 @@ declare class StowServer {
      */
     get search(): {
         similar: (params: SimilarSearchRequest) => Promise<SimilarSearchResult>;
+        text: (params: TextSearchRequest) => Promise<SimilarSearchResult>;
     };
     private searchSimilar;
+    private searchText;
     /**
      * Upload a file as a drop (quick share)
      *
@@ -297,6 +370,21 @@ 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>;
+    };
+    private createProfile;
+    private getProfile;
+    private deleteProfile;
+    private addProfileFiles;
+    private removeProfileFiles;
 }
 
-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 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 };

package/dist/index.js

@@ -78,12 +78,24 @@ var listDropsSchema = import_zod.z.object({
   drops: import_zod.z.array(dropSchema),
   usage: import_zod.z.object({ bytes: import_zod.z.number(), limit: import_zod.z.number() })
 });
-var presignResultSchema = import_zod.z.object({
+var presignNewResultSchema = import_zod.z.object({
   fileKey: import_zod.z.string(),
   uploadUrl: import_zod.z.string(),
   r2Key: import_zod.z.string(),
-  confirmUrl: import_zod.z.string()
+  confirmUrl: import_zod.z.string(),
+  dedupe: import_zod.z.literal(false).optional()
 });
+var presignDedupeResultSchema = import_zod.z.object({
+  dedupe: import_zod.z.literal(true),
+  key: import_zod.z.string(),
+  url: import_zod.z.string().nullable(),
+  size: import_zod.z.number(),
+  contentType: import_zod.z.string()
+});
+var presignResultSchema = import_zod.z.union([
+  presignDedupeResultSchema,
+  presignNewResultSchema
+]);
 var confirmResultSchema = import_zod.z.object({
   key: import_zod.z.string(),
   url: import_zod.z.string().nullable(),
@@ -91,18 +103,44 @@ var confirmResultSchema = import_zod.z.object({
   contentType: import_zod.z.string(),
   metadata: import_zod.z.record(import_zod.z.string(), import_zod.z.string()).optional()
 });
+var fileResultSchema = import_zod.z.object({
+  key: import_zod.z.string(),
+  size: import_zod.z.number(),
+  contentType: import_zod.z.string(),
+  url: import_zod.z.string().nullable(),
+  metadata: import_zod.z.record(import_zod.z.string(), import_zod.z.string()).nullable(),
+  embeddingStatus: import_zod.z.string().nullable(),
+  createdAt: import_zod.z.string()
+});
+var profileResultSchema = import_zod.z.object({
+  id: import_zod.z.string(),
+  name: import_zod.z.string().nullable(),
+  fileCount: import_zod.z.number(),
+  createdAt: import_zod.z.string(),
+  updatedAt: import_zod.z.string()
+});
+var profileFilesResultSchema = import_zod.z.object({
+  id: import_zod.z.string(),
+  fileCount: import_zod.z.number()
+});
 var StowServer = class {
   apiKey;
   baseUrl;
   bucket;
+  timeout;
+  retries;
   constructor(config) {
     if (typeof config === "string") {
       this.apiKey = config;
       this.baseUrl = "https://app.stow.sh";
+      this.timeout = 3e4;
+      this.retries = 3;
     } else {
       this.apiKey = config.apiKey;
       this.baseUrl = config.baseUrl || "https://app.stow.sh";
       this.bucket = config.bucket;
+      this.timeout = config.timeout ?? 3e4;
+      this.retries = config.retries ?? 3;
     }
   }
   /**
@@ -130,24 +168,66 @@ var StowServer = class {
     return `${path}${sep}bucket=${encodeURIComponent(b)}`;
   }
   /**
-   * 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.
    */
   async request(path, options, schema) {
-    const response = await fetch(`${this.baseUrl}${path}`, {
-      ...options,
-      headers: {
-        ...options.headers,
-        "x-api-key": this.apiKey
+    const maxAttempts = this.retries + 1;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      if (options.signal) {
+        options.signal.addEventListener("abort", () => controller.abort());
+      }
+      try {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+          ...options,
+          signal: controller.signal,
+          headers: {
+            ...options.headers,
+            "x-api-key": this.apiKey
+          }
+        });
+        const data = await response.json();
+        if (!response.ok) {
+          const error = errorSchema.safeParse(data);
+          const message = error.success ? error.data.error : "Request failed";
+          const code = error.success ? error.data.code : void 0;
+          const isRetryable = response.status === 429 || response.status >= 500;
+          if (isRetryable && attempt < maxAttempts - 1) {
+            await this.sleep(1e3 * 2 ** attempt);
+            continue;
+          }
+          throw new StowError(message, response.status, code);
+        }
+        return schema ? schema.parse(data) : data;
+      } catch (err) {
+        if (err instanceof StowError) {
+          throw err;
+        }
+        if (err instanceof DOMException || err instanceof Error && err.name === "AbortError") {
+          throw new StowError("Request timed out", 408, "TIMEOUT");
+        }
+        if (attempt < maxAttempts - 1) {
+          await this.sleep(1e3 * 2 ** attempt);
+          continue;
+        }
+        throw new StowError(
+          err instanceof Error ? err.message : "Network error",
+          0,
+          "NETWORK_ERROR"
+        );
+      } finally {
+        clearTimeout(timeoutId);
       }
-    });
-    const data = await response.json();
-    if (!response.ok) {
-      const error = errorSchema.safeParse(data);
-      const message = error.success ? error.data.error : "Request failed";
-      const code = error.success ? error.data.code : void 0;
-      throw new StowError(message, response.status, code);
     }
-    return schema ? schema.parse(data) : data;
+    throw new StowError("Max retries exceeded", 0, "MAX_RETRIES");
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
   }
   /**
    * Upload a file directly from the server
@@ -192,7 +272,8 @@ var StowServer = class {
         body: JSON.stringify({
           url,
           filename,
-          ...options?.metadata ? { metadata: options.metadata } : {}
+          ...options?.metadata ? { metadata: options.metadata } : {},
+          ...options?.headers ? { headers: options.headers } : {}
         })
       },
       uploadResultSchema
@@ -215,7 +296,7 @@ var StowServer = class {
    * 4. Client calls confirmUpload to finalize
    */
   getPresignedUrl(request) {
-    const { filename, contentType, size, route, bucket, metadata } = request;
+    const { filename, contentType, size, route, bucket, metadata, contentHash } = request;
     return this.request(
       this.withBucket("/api/presign", bucket),
       {
@@ -226,7 +307,8 @@ var StowServer = class {
           contentType,
           size,
           route,
-          ...metadata ? { metadata } : {}
+          ...metadata ? { metadata } : {},
+          ...contentHash ? { contentHash } : {}
         })
       },
       presignResultSchema
@@ -237,7 +319,16 @@ var StowServer = class {
    * This creates the file record in the database.
    */
   confirmUpload(request) {
-    const { fileKey, size, contentType, bucket, metadata } = request;
+    const {
+      fileKey,
+      size,
+      contentType,
+      bucket,
+      metadata,
+      skipVerify,
+      deferKvSync,
+      contentHash
+    } = request;
     return this.request(
       this.withBucket("/api/presign/confirm", bucket),
       {
@@ -247,7 +338,10 @@ var StowServer = class {
           fileKey,
           size,
           contentType,
-          ...metadata ? { metadata } : {}
+          ...metadata ? { metadata } : {},
+          ...skipVerify ? { skipVerify } : {},
+          ...deferKvSync ? { deferKvSync } : {},
+          ...contentHash ? { contentHash } : {}
         })
       },
       confirmResultSchema
@@ -297,6 +391,17 @@ var StowServer = class {
       body: JSON.stringify({ metadata })
     });
   }
+  /**
+   * Get a single file by key
+   */
+  async getFile(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}`;
+    return this.request(
+      this.withBucket(path, options?.bucket),
+      { method: "GET" },
+      fileResultSchema
+    );
+  }
   /**
    * Get a transform URL for an image.
    *
@@ -387,7 +492,8 @@ var StowServer = class {
    */
   get search() {
     return {
-      similar: (params) => this.searchSimilar(params)
+      similar: (params) => this.searchSimilar(params),
+      text: (params) => this.searchText(params)
     };
   }
   searchSimilar(params) {
@@ -397,6 +503,18 @@ var StowServer = class {
       body: JSON.stringify({
         ...params.fileKey ? { fileKey: params.fileKey } : {},
         ...params.vector ? { vector: params.vector } : {},
+        ...params.profileId ? { profileId: params.profileId } : {},
+        ...params.bucket ? { bucket: params.bucket } : {},
+        ...params.limit ? { limit: params.limit } : {}
+      })
+    });
+  }
+  searchText(params) {
+    return this.request("/api/search/text", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        query: params.query,
         ...params.bucket ? { bucket: params.bucket } : {},
         ...params.limit ? { limit: params.limit } : {}
       })
@@ -469,6 +587,76 @@ var StowServer = class {
       method: "DELETE"
     });
   }
+  // ============================================================
+  // PROFILES - Taste/preference profiles from file collections
+  // ============================================================
+  /**
+   * Profiles namespace for managing taste profiles
+   */
+  get profiles() {
+    return {
+      create: (params) => this.createProfile(params),
+      get: (id) => this.getProfile(id),
+      delete: (id) => this.deleteProfile(id),
+      addFiles: (id, fileKeys, bucket) => this.addProfileFiles(id, fileKeys, bucket),
+      removeFiles: (id, fileKeys, bucket) => this.removeProfileFiles(id, fileKeys, bucket)
+    };
+  }
+  createProfile(params) {
+    return this.request(
+      "/api/profiles",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          ...params?.name ? { name: params.name } : {},
+          ...params?.fileKeys ? { fileKeys: params.fileKeys } : {},
+          ...params?.bucket ? { bucket: params.bucket } : {}
+        })
+      },
+      profileResultSchema
+    );
+  }
+  getProfile(id) {
+    return this.request(
+      `/api/profiles/${encodeURIComponent(id)}`,
+      { method: "GET" },
+      profileResultSchema
+    );
+  }
+  async deleteProfile(id) {
+    await this.request(`/api/profiles/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+  }
+  addProfileFiles(id, fileKeys, bucket) {
+    return this.request(
+      `/api/profiles/${encodeURIComponent(id)}/files`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          fileKeys,
+          ...bucket ? { bucket } : {}
+        })
+      },
+      profileFilesResultSchema
+    );
+  }
+  removeProfileFiles(id, fileKeys, bucket) {
+    return this.request(
+      `/api/profiles/${encodeURIComponent(id)}/files`,
+      {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          fileKeys,
+          ...bucket ? { bucket } : {}
+        })
+      },
+      profileFilesResultSchema
+    );
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -53,12 +53,24 @@ var listDropsSchema = z.object({
   drops: z.array(dropSchema),
   usage: z.object({ bytes: z.number(), limit: z.number() })
 });
-var presignResultSchema = z.object({
+var presignNewResultSchema = z.object({
   fileKey: z.string(),
   uploadUrl: z.string(),
   r2Key: z.string(),
-  confirmUrl: z.string()
+  confirmUrl: z.string(),
+  dedupe: z.literal(false).optional()
 });
+var presignDedupeResultSchema = z.object({
+  dedupe: z.literal(true),
+  key: z.string(),
+  url: z.string().nullable(),
+  size: z.number(),
+  contentType: z.string()
+});
+var presignResultSchema = z.union([
+  presignDedupeResultSchema,
+  presignNewResultSchema
+]);
 var confirmResultSchema = z.object({
   key: z.string(),
   url: z.string().nullable(),
@@ -66,18 +78,44 @@ var confirmResultSchema = z.object({
   contentType: z.string(),
   metadata: z.record(z.string(), z.string()).optional()
 });
+var fileResultSchema = z.object({
+  key: z.string(),
+  size: z.number(),
+  contentType: z.string(),
+  url: z.string().nullable(),
+  metadata: z.record(z.string(), z.string()).nullable(),
+  embeddingStatus: z.string().nullable(),
+  createdAt: z.string()
+});
+var profileResultSchema = z.object({
+  id: z.string(),
+  name: z.string().nullable(),
+  fileCount: z.number(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+var profileFilesResultSchema = z.object({
+  id: z.string(),
+  fileCount: z.number()
+});
 var StowServer = class {
   apiKey;
   baseUrl;
   bucket;
+  timeout;
+  retries;
   constructor(config) {
     if (typeof config === "string") {
       this.apiKey = config;
       this.baseUrl = "https://app.stow.sh";
+      this.timeout = 3e4;
+      this.retries = 3;
     } else {
       this.apiKey = config.apiKey;
       this.baseUrl = config.baseUrl || "https://app.stow.sh";
       this.bucket = config.bucket;
+      this.timeout = config.timeout ?? 3e4;
+      this.retries = config.retries ?? 3;
     }
   }
   /**
@@ -105,24 +143,66 @@ var StowServer = class {
     return `${path}${sep}bucket=${encodeURIComponent(b)}`;
   }
   /**
-   * 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.
    */
   async request(path, options, schema) {
-    const response = await fetch(`${this.baseUrl}${path}`, {
-      ...options,
-      headers: {
-        ...options.headers,
-        "x-api-key": this.apiKey
+    const maxAttempts = this.retries + 1;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      if (options.signal) {
+        options.signal.addEventListener("abort", () => controller.abort());
+      }
+      try {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+          ...options,
+          signal: controller.signal,
+          headers: {
+            ...options.headers,
+            "x-api-key": this.apiKey
+          }
+        });
+        const data = await response.json();
+        if (!response.ok) {
+          const error = errorSchema.safeParse(data);
+          const message = error.success ? error.data.error : "Request failed";
+          const code = error.success ? error.data.code : void 0;
+          const isRetryable = response.status === 429 || response.status >= 500;
+          if (isRetryable && attempt < maxAttempts - 1) {
+            await this.sleep(1e3 * 2 ** attempt);
+            continue;
+          }
+          throw new StowError(message, response.status, code);
+        }
+        return schema ? schema.parse(data) : data;
+      } catch (err) {
+        if (err instanceof StowError) {
+          throw err;
+        }
+        if (err instanceof DOMException || err instanceof Error && err.name === "AbortError") {
+          throw new StowError("Request timed out", 408, "TIMEOUT");
+        }
+        if (attempt < maxAttempts - 1) {
+          await this.sleep(1e3 * 2 ** attempt);
+          continue;
+        }
+        throw new StowError(
+          err instanceof Error ? err.message : "Network error",
+          0,
+          "NETWORK_ERROR"
+        );
+      } finally {
+        clearTimeout(timeoutId);
       }
-    });
-    const data = await response.json();
-    if (!response.ok) {
-      const error = errorSchema.safeParse(data);
-      const message = error.success ? error.data.error : "Request failed";
-      const code = error.success ? error.data.code : void 0;
-      throw new StowError(message, response.status, code);
     }
-    return schema ? schema.parse(data) : data;
+    throw new StowError("Max retries exceeded", 0, "MAX_RETRIES");
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
   }
   /**
    * Upload a file directly from the server
@@ -167,7 +247,8 @@ var StowServer = class {
         body: JSON.stringify({
           url,
           filename,
-          ...options?.metadata ? { metadata: options.metadata } : {}
+          ...options?.metadata ? { metadata: options.metadata } : {},
+          ...options?.headers ? { headers: options.headers } : {}
         })
       },
       uploadResultSchema
@@ -190,7 +271,7 @@ var StowServer = class {
    * 4. Client calls confirmUpload to finalize
    */
   getPresignedUrl(request) {
-    const { filename, contentType, size, route, bucket, metadata } = request;
+    const { filename, contentType, size, route, bucket, metadata, contentHash } = request;
     return this.request(
       this.withBucket("/api/presign", bucket),
       {
@@ -201,7 +282,8 @@ var StowServer = class {
           contentType,
           size,
           route,
-          ...metadata ? { metadata } : {}
+          ...metadata ? { metadata } : {},
+          ...contentHash ? { contentHash } : {}
         })
       },
       presignResultSchema
@@ -212,7 +294,16 @@ var StowServer = class {
    * This creates the file record in the database.
    */
   confirmUpload(request) {
-    const { fileKey, size, contentType, bucket, metadata } = request;
+    const {
+      fileKey,
+      size,
+      contentType,
+      bucket,
+      metadata,
+      skipVerify,
+      deferKvSync,
+      contentHash
+    } = request;
     return this.request(
       this.withBucket("/api/presign/confirm", bucket),
       {
@@ -222,7 +313,10 @@ var StowServer = class {
           fileKey,
           size,
           contentType,
-          ...metadata ? { metadata } : {}
+          ...metadata ? { metadata } : {},
+          ...skipVerify ? { skipVerify } : {},
+          ...deferKvSync ? { deferKvSync } : {},
+          ...contentHash ? { contentHash } : {}
         })
       },
       confirmResultSchema
@@ -272,6 +366,17 @@ var StowServer = class {
       body: JSON.stringify({ metadata })
     });
   }
+  /**
+   * Get a single file by key
+   */
+  async getFile(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}`;
+    return this.request(
+      this.withBucket(path, options?.bucket),
+      { method: "GET" },
+      fileResultSchema
+    );
+  }
   /**
    * Get a transform URL for an image.
    *
@@ -362,7 +467,8 @@ var StowServer = class {
    */
   get search() {
     return {
-      similar: (params) => this.searchSimilar(params)
+      similar: (params) => this.searchSimilar(params),
+      text: (params) => this.searchText(params)
     };
   }
   searchSimilar(params) {
@@ -372,6 +478,18 @@ var StowServer = class {
       body: JSON.stringify({
         ...params.fileKey ? { fileKey: params.fileKey } : {},
         ...params.vector ? { vector: params.vector } : {},
+        ...params.profileId ? { profileId: params.profileId } : {},
+        ...params.bucket ? { bucket: params.bucket } : {},
+        ...params.limit ? { limit: params.limit } : {}
+      })
+    });
+  }
+  searchText(params) {
+    return this.request("/api/search/text", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        query: params.query,
         ...params.bucket ? { bucket: params.bucket } : {},
         ...params.limit ? { limit: params.limit } : {}
       })
@@ -444,6 +562,76 @@ var StowServer = class {
       method: "DELETE"
     });
   }
+  // ============================================================
+  // PROFILES - Taste/preference profiles from file collections
+  // ============================================================
+  /**
+   * Profiles namespace for managing taste profiles
+   */
+  get profiles() {
+    return {
+      create: (params) => this.createProfile(params),
+      get: (id) => this.getProfile(id),
+      delete: (id) => this.deleteProfile(id),
+      addFiles: (id, fileKeys, bucket) => this.addProfileFiles(id, fileKeys, bucket),
+      removeFiles: (id, fileKeys, bucket) => this.removeProfileFiles(id, fileKeys, bucket)
+    };
+  }
+  createProfile(params) {
+    return this.request(
+      "/api/profiles",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          ...params?.name ? { name: params.name } : {},
+          ...params?.fileKeys ? { fileKeys: params.fileKeys } : {},
+          ...params?.bucket ? { bucket: params.bucket } : {}
+        })
+      },
+      profileResultSchema
+    );
+  }
+  getProfile(id) {
+    return this.request(
+      `/api/profiles/${encodeURIComponent(id)}`,
+      { method: "GET" },
+      profileResultSchema
+    );
+  }
+  async deleteProfile(id) {
+    await this.request(`/api/profiles/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+  }
+  addProfileFiles(id, fileKeys, bucket) {
+    return this.request(
+      `/api/profiles/${encodeURIComponent(id)}/files`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          fileKeys,
+          ...bucket ? { bucket } : {}
+        })
+      },
+      profileFilesResultSchema
+    );
+  }
+  removeProfileFiles(id, fileKeys, bucket) {
+    return this.request(
+      `/api/profiles/${encodeURIComponent(id)}/files`,
+      {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          fileKeys,
+          ...bucket ? { bucket } : {}
+        })
+      },
+      profileFilesResultSchema
+    );
+  }
 };
 export {
   StowError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/stow-server",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Server-side SDK for Stow file storage",
   "license": "MIT",
   "repository": {
@@ -40,10 +40,10 @@
   },
   "devDependencies": {
     "@stow/typescript-config": "workspace:*",
-    "@types/node": "^25.2.1",
-    "tsup": "^8.0.0",
-    "typescript": "^5.0.0",
-    "vitest": "^4.0.0",
+    "@types/node": "^25.2.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
     "zod": "^4.3.6"
   }
 }