@howells/stow-server 0.1.2 → 0.3.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 taskTriggerResultSchema = z.object({
+  key: z.string(),
+  triggered: 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()
@@ -56,7 +134,6 @@ var listDropsSchema = z.object({
 var presignNewResultSchema = z.object({
   fileKey: z.string(),
   uploadUrl: z.string(),
-  r2Key: z.string(),
   confirmUrl: z.string(),
   dedupe: z.literal(false).optional()
 });
@@ -83,14 +160,31 @@ var fileResultSchema = z.object({
   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()
 });
@@ -98,6 +192,38 @@ 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;
@@ -124,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.
@@ -149,6 +357,7 @@ var StowServer = class {
    * - 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 maxAttempts = this.retries + 1;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
@@ -183,6 +392,13 @@ var StowServer = class {
         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");
         }
@@ -208,32 +424,58 @@ var StowServer = class {
    * 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)
@@ -248,7 +490,10 @@ var StowServer = class {
           url,
           filename,
           ...options?.metadata ? { metadata: options.metadata } : {},
-          ...options?.headers ? { headers: options.headers } : {}
+          ...options?.headers ? { headers: options.headers } : {},
+          ...options?.title ? { title: true } : {},
+          ...options?.describe ? { describe: true } : {},
+          ...options?.altText ? { altText: true } : {}
         })
       },
       uploadResultSchema
@@ -271,7 +516,15 @@ var StowServer = class {
    * 4. Client calls confirmUpload to finalize
    */
   getPresignedUrl(request) {
-    const { filename, contentType, size, route, bucket, metadata, contentHash } = request;
+    const {
+      filename,
+      contentType,
+      size,
+      route,
+      bucket,
+      metadata,
+      contentHash
+    } = request;
     return this.request(
       this.withBucket("/api/presign", bucket),
       {
@@ -302,7 +555,10 @@ var StowServer = class {
       metadata,
       skipVerify,
       deferKvSync,
-      contentHash
+      contentHash,
+      title,
+      describe,
+      altText
     } = request;
     return this.request(
       this.withBucket("/api/presign/confirm", bucket),
@@ -316,7 +572,10 @@ var StowServer = class {
           ...metadata ? { metadata } : {},
           ...skipVerify ? { skipVerify } : {},
           ...deferKvSync ? { deferKvSync } : {},
-          ...contentHash ? { contentHash } : {}
+          ...contentHash ? { contentHash } : {},
+          ...title ? { title } : {},
+          ...describe ? { describe } : {},
+          ...altText ? { altText } : {}
         })
       },
       confirmResultSchema
@@ -358,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",
@@ -369,7 +628,7 @@ var StowServer = class {
   /**
    * Get a single file by key
    */
-  async getFile(key, options) {
+  getFile(key, options) {
     const path = `/api/files/${encodeURIComponent(key)}`;
     return this.request(
       this.withBucket(path, options?.bucket),
@@ -377,6 +636,60 @@ var StowServer = class {
       fileResultSchema
     );
   }
+  /**
+   * Extract color palette from an image file.
+   * Requires a searchable bucket.
+   */
+  extractColors(key) {
+    return this.request(
+      `/api/files/${encodeURIComponent(key)}/extract-colors`,
+      { method: "POST" },
+      taskTriggerResultSchema
+    );
+  }
+  /**
+   * Extract dimensions (width/height) from an image or video file.
+   */
+  extractDimensions(key) {
+    return this.request(
+      `/api/files/${encodeURIComponent(key)}/extract-dimensions`,
+      { method: "POST" },
+      taskTriggerResultSchema
+    );
+  }
+  /**
+   * Generate a vector embedding for an image file.
+   * Requires a searchable bucket.
+   */
+  embed(key) {
+    return this.request(
+      `/api/files/${encodeURIComponent(key)}/embed`,
+      { method: "POST" },
+      taskTriggerResultSchema
+    );
+  }
+  /**
+   * 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.
    *
@@ -388,25 +701,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
@@ -468,10 +779,13 @@ var StowServer = class {
   get search() {
     return {
       similar: (params) => this.searchSimilar(params),
-      text: (params) => this.searchText(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" },
@@ -479,19 +793,62 @@ var StowServer = class {
         ...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 } : {}
+        ...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,
-        ...params.bucket ? { bucket: params.bucket } : {},
-        ...params.limit ? { limit: params.limit } : {}
+        ...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 } : {}
       })
     });
   }
@@ -532,7 +889,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" },
@@ -574,7 +931,12 @@ var StowServer = class {
       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)
+      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) {
@@ -632,6 +994,55 @@ var StowServer = class {
       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,