@howells/stow-server 0.1.1 → 0.2.0

package/dist/index.mjs

@@ -1,4 +1,5 @@
 // src/index.ts
+import { createHash } from "crypto";
 import { z } from "zod";
 var StowError = class extends Error {
   status;
@@ -10,12 +11,74 @@ var StowError = class extends Error {
     this.code = code;
   }
 };
+var fileColorSchema = z.object({
+  position: z.number().int(),
+  proportion: z.number(),
+  hex: z.string(),
+  name: z.string().nullable(),
+  hsl: z.object({ h: z.number(), s: z.number(), l: z.number() }),
+  oklab: z.object({ L: z.number(), a: z.number(), b: z.number() }).nullable(),
+  oklch: z.object({ l: z.number(), c: z.number(), h: z.number() }).nullable()
+});
+var fileColorProfileSchema = z.object({
+  palette: z.object({
+    mood: z.string(),
+    brightness: z.number(),
+    temperature: z.number(),
+    vibrancy: z.number(),
+    complexity: z.number(),
+    dominantFamily: z.string().nullable()
+  }),
+  backgroundHex: z.string().nullable(),
+  accent: z.object({
+    hex: z.string(),
+    name: z.string().nullable(),
+    oklab: z.object({ L: z.number(), a: z.number(), b: z.number() }).nullable(),
+    oklch: z.object({ l: z.number(), c: z.number(), h: z.number() }).nullable()
+  }).nullable(),
+  extractedAt: z.string(),
+  colorCount: z.number().int()
+});
 var uploadResultSchema = z.object({
   key: z.string(),
   url: z.string().nullable(),
   size: z.number(),
   contentType: z.string().optional(),
-  metadata: z.record(z.string(), z.string()).optional()
+  metadata: z.record(z.string(), z.string()).optional(),
+  deduped: z.boolean().optional()
+});
+var bucketSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().nullable().optional(),
+  isPublic: z.boolean().optional(),
+  searchable: z.boolean().optional(),
+  allowedTypes: z.array(z.string()).nullable().optional(),
+  maxFileSize: z.coerce.number().nullable().optional(),
+  storageQuota: z.coerce.number().nullable().optional(),
+  fileCountLimit: z.coerce.number().nullable().optional(),
+  fileCount: z.coerce.number().optional(),
+  usageBytes: z.coerce.number().optional(),
+  createdAt: z.string().optional()
+});
+var listBucketsSchema = z.object({
+  buckets: z.array(bucketSchema)
+});
+var bucketResponseSchema = z.object({
+  bucket: bucketSchema
+});
+var whoamiSchema = z.object({
+  user: z.object({ email: z.string() }),
+  stats: z.object({
+    totalBytes: z.coerce.number(),
+    totalFiles: z.coerce.number(),
+    bucketCount: z.coerce.number()
+  }),
+  key: z.object({
+    name: z.string(),
+    scope: z.string(),
+    permissions: z.record(z.string(), z.boolean())
+  }).optional()
 });
 var listFilesSchema = z.object({
   files: z.array(
@@ -24,11 +87,26 @@ var listFilesSchema = z.object({
       size: z.number(),
       lastModified: z.string(),
       url: z.string().nullable(),
-      metadata: z.record(z.string(), z.string()).optional()
+      width: z.number().nullable().optional(),
+      height: z.number().nullable().optional(),
+      duration: z.number().nullable().optional(),
+      metadata: z.record(z.string(), z.string()).optional(),
+      colorProfile: fileColorProfileSchema.nullable().optional(),
+      colors: z.array(fileColorSchema).optional()
     })
   ),
   nextCursor: z.string().nullable()
 });
+var reprocessResultSchema = z.object({
+  key: z.string(),
+  triggered: z.array(z.string())
+});
+var replaceResultSchema = z.object({
+  key: z.string(),
+  size: z.number(),
+  contentType: z.string(),
+  triggered: z.array(z.string())
+});
 var errorSchema = z.object({
   error: z.string(),
   code: z.string().optional()
@@ -53,12 +131,23 @@ 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 +155,93 @@ 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(),
+  width: z.number().nullable(),
+  height: z.number().nullable(),
+  duration: z.number().nullable(),
+  metadata: z.record(z.string(), z.string()).nullable(),
+  colorProfile: fileColorProfileSchema.nullable(),
+  colors: z.array(fileColorSchema),
+  embeddingStatus: z.string().nullable(),
+  createdAt: z.string()
+});
+var profileClusterResultSchema = z.object({
+  id: z.string(),
+  index: z.number().int(),
+  name: z.string().nullable(),
+  description: z.string().nullable(),
+  signalCount: z.number().int(),
+  totalWeight: z.number(),
+  nameGeneratedAt: z.string().nullable()
+});
+var profileResultSchema = z.object({
+  id: z.string(),
+  name: z.string().nullable(),
+  fileCount: z.number(),
+  signalCount: z.number(),
+  vector: z.array(z.number()).nullable(),
+  clusters: z.array(profileClusterResultSchema).optional(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+var profileFilesResultSchema = z.object({
+  id: z.string(),
+  fileCount: z.number()
+});
+var profileSignalResultSchema = z.object({
+  id: z.string(),
+  fileKey: z.string(),
+  type: z.enum([
+    "view",
+    "view_long",
+    "click",
+    "like",
+    "save",
+    "choose",
+    "purchase",
+    "share",
+    "dismiss",
+    "skip",
+    "reject",
+    "report",
+    "custom"
+  ]),
+  weight: z.number()
+});
+var profileSignalsResponseSchema = z.object({
+  profileId: z.string(),
+  signals: z.array(profileSignalResultSchema),
+  totalSignals: z.number(),
+  vectorUpdated: z.boolean()
+});
+var deleteProfileSignalsResponseSchema = z.object({
+  profileId: z.string(),
+  removed: z.number(),
+  totalSignals: z.number(),
+  vectorUpdated: z.boolean()
+});
 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;
     }
   }
   /**
@@ -86,6 +250,88 @@ var StowServer = class {
   getBaseUrl() {
     return this.baseUrl;
   }
+  /**
+   * Return account usage and API key info for the current credential.
+   */
+  whoami() {
+    return this.request("/api/whoami", { method: "GET" }, whoamiSchema);
+  }
+  /**
+   * List all buckets available to the current organization.
+   */
+  listBuckets() {
+    return this.request("/api/buckets", { method: "GET" }, listBucketsSchema);
+  }
+  /**
+   * Create a new bucket.
+   */
+  async createBucket(request) {
+    const result = await this.request(
+      "/api/buckets",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(request)
+      },
+      bucketResponseSchema
+    );
+    return result.bucket;
+  }
+  /**
+   * Get bucket details by id.
+   */
+  async getBucket(id) {
+    const result = await this.request(
+      `/api/buckets/${encodeURIComponent(id)}`,
+      { method: "GET" },
+      bucketResponseSchema
+    );
+    return result.bucket;
+  }
+  /**
+   * Update bucket settings by id.
+   */
+  async updateBucket(id, updates) {
+    const result = await this.request(
+      `/api/buckets/${encodeURIComponent(id)}`,
+      {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(updates)
+      },
+      bucketResponseSchema
+    );
+    return result.bucket;
+  }
+  /**
+   * Rename/update a bucket by current bucket name.
+   */
+  async updateBucketByName(name, updates) {
+    const result = await this.request(
+      `/api/buckets/_?bucket=${encodeURIComponent(name)}`,
+      {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(updates)
+      },
+      bucketResponseSchema
+    );
+    return result.bucket;
+  }
+  /**
+   * Rename a bucket by current bucket name.
+   */
+  renameBucket(name, newName) {
+    return this.updateBucketByName(name, { name: newName });
+  }
+  /**
+   * Delete a bucket by id.
+   */
+  async deleteBucket(id) {
+    await this.request(`/api/buckets/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+  }
   /**
    * Resolve the effective bucket for this request.
    * Per-call override > constructor default.
@@ -105,55 +351,131 @@ 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.
    */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: retry + timeout + error normalization intentionally handled in one request pipeline
   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 z.ZodError) {
+          throw new StowError(
+            "Invalid response format",
+            500,
+            "INVALID_RESPONSE"
+          );
+        }
+        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
    */
   async uploadFile(file, options) {
-    const formData = new FormData();
-    const blob = Buffer.isBuffer(file) ? new Blob([new Uint8Array(file)], {
-      type: options?.contentType || "application/octet-stream"
-    }) : file;
-    formData.append("file", blob, options?.filename || "file");
-    if (options?.route) {
-      formData.append("route", options.route);
+    const filename = options?.filename || "file";
+    const buffer = Buffer.isBuffer(file) ? file : Buffer.from(await file.arrayBuffer());
+    const contentType = options?.contentType || (!Buffer.isBuffer(file) && file.type ? file.type : "application/octet-stream");
+    const contentHash = createHash("sha256").update(buffer).digest("hex");
+    const presign = await this.getPresignedUrl({
+      filename,
+      contentType,
+      size: buffer.length,
+      ...options?.route ? { route: options.route } : {},
+      ...options?.bucket ? { bucket: options.bucket } : {},
+      ...options?.metadata ? { metadata: options.metadata } : {},
+      contentHash
+    });
+    if (presign.dedupe) {
+      return {
+        key: presign.key,
+        url: presign.url,
+        size: presign.size,
+        contentType: presign.contentType,
+        deduped: true
+      };
     }
-    if (options?.metadata) {
-      formData.append("metadata", JSON.stringify(options.metadata));
+    const uploadRes = await fetch(presign.uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": contentType },
+      body: new Uint8Array(buffer)
+    });
+    if (!uploadRes.ok) {
+      throw new StowError("Failed to upload to storage", uploadRes.status);
     }
-    const result = await this.request(
-      this.withBucket("/api/upload", options?.bucket),
+    return this.request(
+      this.withBucket(
+        presign.confirmUrl || "/api/presign/confirm",
+        options?.bucket
+      ),
       {
         method: "POST",
-        body: formData
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          fileKey: presign.fileKey,
+          size: buffer.length,
+          contentType,
+          ...options?.metadata ? { metadata: options.metadata } : {},
+          contentHash,
+          skipVerify: true,
+          ...options?.title ? { title: true } : {},
+          ...options?.describe ? { describe: true } : {},
+          ...options?.altText ? { altText: true } : {}
+        })
       },
-      uploadResultSchema
+      confirmResultSchema
     );
-    return {
-      key: result.key,
-      url: result.url,
-      size: result.size,
-      contentType: result.contentType || options?.contentType || "application/octet-stream",
-      ...result.metadata ? { metadata: result.metadata } : {}
-    };
   }
   /**
    * Upload a file from a URL (server-side fetch + upload)
@@ -167,7 +489,11 @@ var StowServer = class {
         body: JSON.stringify({
           url,
           filename,
-          ...options?.metadata ? { metadata: options.metadata } : {}
+          ...options?.metadata ? { metadata: options.metadata } : {},
+          ...options?.headers ? { headers: options.headers } : {},
+          ...options?.title ? { title: true } : {},
+          ...options?.describe ? { describe: true } : {},
+          ...options?.altText ? { altText: true } : {}
         })
       },
       uploadResultSchema
@@ -190,7 +516,15 @@ 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 +535,8 @@ var StowServer = class {
           contentType,
           size,
           route,
-          ...metadata ? { metadata } : {}
+          ...metadata ? { metadata } : {},
+          ...contentHash ? { contentHash } : {}
         })
       },
       presignResultSchema
@@ -212,7 +547,19 @@ 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,
+      title,
+      describe,
+      altText
+    } = request;
     return this.request(
       this.withBucket("/api/presign/confirm", bucket),
       {
@@ -222,7 +569,13 @@ var StowServer = class {
           fileKey,
           size,
           contentType,
-          ...metadata ? { metadata } : {}
+          ...metadata ? { metadata } : {},
+          ...skipVerify ? { skipVerify } : {},
+          ...deferKvSync ? { deferKvSync } : {},
+          ...contentHash ? { contentHash } : {},
+          ...title ? { title } : {},
+          ...describe ? { describe } : {},
+          ...altText ? { altText } : {}
         })
       },
       confirmResultSchema
@@ -264,7 +617,7 @@ var StowServer = class {
   /**
    * Update metadata on an existing file
    */
-  async updateFileMetadata(key, metadata, options) {
+  updateFileMetadata(key, metadata, options) {
     const path = `/api/files/${encodeURIComponent(key)}`;
     return this.request(this.withBucket(path, options?.bucket), {
       method: "PATCH",
@@ -272,6 +625,51 @@ var StowServer = class {
       body: JSON.stringify({ metadata })
     });
   }
+  /**
+   * Get a single file by key
+   */
+  getFile(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}`;
+    return this.request(
+      this.withBucket(path, options?.bucket),
+      { method: "GET" },
+      fileResultSchema
+    );
+  }
+  /**
+   * Reprocess a file: reset all derived data (embeddings, colors, dimensions,
+   * AI metadata, taxonomies) and re-trigger processing tasks.
+   */
+  reprocessFile(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/reprocess`;
+    return this.request(
+      this.withBucket(path, options?.bucket),
+      { method: "POST" },
+      reprocessResultSchema
+    );
+  }
+  /**
+   * 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, url, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/replace`;
+    return this.request(
+      this.withBucket(path, options?.bucket),
+      {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          url,
+          ...options?.headers ? { headers: options.headers } : {}
+        })
+      },
+      replaceResultSchema
+    );
+  }
   /**
    * Get a transform URL for an image.
    *
@@ -283,25 +681,23 @@ var StowServer = class {
    * @param options - Transform options (width, height, quality, format)
    */
   getTransformUrl(url, options) {
-    const params = new URLSearchParams();
-    if (options?.width) {
-      params.set("w", options.width.toString());
+    if (!(options && (options.width || options.height || options.quality || options.format))) {
+      return url;
     }
-    if (options?.height) {
-      params.set("h", options.height.toString());
+    const parsed = new URL(url);
+    if (options.width) {
+      parsed.searchParams.set("w", String(options.width));
     }
-    if (options?.quality) {
-      params.set("q", options.quality.toString());
+    if (options.height) {
+      parsed.searchParams.set("h", String(options.height));
     }
-    if (options?.format) {
-      params.set("f", options.format);
+    if (options.quality) {
+      parsed.searchParams.set("q", String(options.quality));
     }
-    const query = params.toString();
-    if (!query) {
-      return url;
+    if (options.format) {
+      parsed.searchParams.set("f", options.format);
     }
-    const separator = url.includes("?") ? "&" : "?";
-    return `${url}${separator}${query}`;
+    return parsed.toString();
   }
   // ============================================================
   // TAGS - Org-scoped labels for file organization
@@ -362,18 +758,77 @@ var StowServer = class {
    */
   get search() {
     return {
-      similar: (params) => this.searchSimilar(params)
+      similar: (params) => this.searchSimilar(params),
+      diverse: (params) => this.searchDiverse(params ?? {}),
+      text: (params) => this.searchText(params),
+      color: (params) => this.searchColor(params)
     };
   }
   searchSimilar(params) {
+    const bucket = this.resolveBucket(params.bucket);
     return this.request("/api/search/similar", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         ...params.fileKey ? { fileKey: params.fileKey } : {},
         ...params.vector ? { vector: params.vector } : {},
-        ...params.bucket ? { bucket: params.bucket } : {},
-        ...params.limit ? { limit: params.limit } : {}
+        ...params.profileId ? { profileId: params.profileId } : {},
+        ...params.clusterId ? { clusterId: params.clusterId } : {},
+        ...params.clusterIds?.length ? { clusterIds: params.clusterIds } : {},
+        ...bucket ? { bucket } : {},
+        ...params.limit ? { limit: params.limit } : {},
+        ...params.excludeKeys?.length ? { excludeKeys: params.excludeKeys } : {},
+        ...params.filters ? { filters: params.filters } : {},
+        ...params.include?.length ? { include: params.include } : {}
+      })
+    });
+  }
+  searchDiverse(params) {
+    const bucket = this.resolveBucket(params.bucket);
+    return this.request("/api/search/diverse", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        ...params.fileKey ? { fileKey: params.fileKey } : {},
+        ...params.vector ? { vector: params.vector } : {},
+        ...params.profileId ? { profileId: params.profileId } : {},
+        ...params.clusterId ? { clusterId: params.clusterId } : {},
+        ...params.clusterIds?.length ? { clusterIds: params.clusterIds } : {},
+        ...bucket ? { bucket } : {},
+        ...params.limit ? { limit: params.limit } : {},
+        ...params.lambda !== void 0 ? { lambda: params.lambda } : {},
+        ...params.excludeKeys?.length ? { excludeKeys: params.excludeKeys } : {},
+        ...params.filters ? { filters: params.filters } : {},
+        ...params.include?.length ? { include: params.include } : {}
+      })
+    });
+  }
+  searchText(params) {
+    const bucket = this.resolveBucket(params.bucket);
+    return this.request("/api/search/text", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        query: params.query,
+        ...bucket ? { bucket } : {},
+        ...params.limit ? { limit: params.limit } : {},
+        ...params.filters ? { filters: params.filters } : {},
+        ...params.include?.length ? { include: params.include } : {}
+      })
+    });
+  }
+  searchColor(params) {
+    const bucket = this.resolveBucket(params.bucket);
+    return this.request("/api/search/color", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        ...params.hex ? { hex: params.hex } : {},
+        ...params.oklab ? { oklab: params.oklab } : {},
+        ...bucket ? { bucket } : {},
+        ...params.limit ? { limit: params.limit } : {},
+        ...params.minProportion !== void 0 ? { minProportion: params.minProportion } : {},
+        ...params.dominantOnly ? { dominantOnly: params.dominantOnly } : {}
       })
     });
   }
@@ -414,7 +869,7 @@ var StowServer = class {
       throw new StowError("Failed to upload to storage", putRes.status);
     }
     return this.request(
-      "/api/drops/presign/confirm",
+      presign.confirmUrl || "/api/drops/presign/confirm",
       {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -444,6 +899,130 @@ 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),
+      signal: (id, signals, bucket) => this.signalProfile(id, signals, bucket),
+      deleteSignals: (id, signalIds) => this.deleteProfileSignals(id, signalIds),
+      clusters: (id) => this.getProfileClusters(id),
+      recluster: (id, params) => this.reclusterProfile(id, params),
+      renameCluster: (profileId, clusterId, params) => this.renameProfileCluster(profileId, clusterId, params)
+    };
+  }
+  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
+    );
+  }
+  signalProfile(id, signals, bucket) {
+    return this.request(
+      `/api/profiles/${encodeURIComponent(id)}/signals`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          signals,
+          ...bucket ? { bucket } : {}
+        })
+      },
+      profileSignalsResponseSchema
+    );
+  }
+  deleteProfileSignals(id, signalIds) {
+    return this.request(
+      `/api/profiles/${encodeURIComponent(id)}/signals`,
+      {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ signalIds })
+      },
+      deleteProfileSignalsResponseSchema
+    );
+  }
+  getProfileClusters(id) {
+    return this.request(`/api/profiles/${encodeURIComponent(id)}/clusters`, {
+      method: "GET"
+    });
+  }
+  reclusterProfile(id, params) {
+    return this.request(`/api/profiles/${encodeURIComponent(id)}/clusters`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        ...params?.clusterCount !== void 0 ? { clusterCount: params.clusterCount } : {}
+      })
+    });
+  }
+  renameProfileCluster(profileId, clusterId, params) {
+    return this.request(
+      `/api/profiles/${encodeURIComponent(profileId)}/clusters/${encodeURIComponent(clusterId)}`,
+      {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(params)
+      }
+    );
+  }
 };
 export {
   StowError,