@howells/stow-server 2.2.0 → 2.3.0

package/dist/index.mjs

@@ -1,6 +1,9 @@
 // src/index.ts
 import { createHash } from "crypto";
+import { setTimeout as delay } from "timers/promises";
 import { z } from "zod";
+
+// src/stow-error.ts
 var StowError = class extends Error {
   status;
   code;
@@ -11,6 +14,8 @@ var StowError = class extends Error {
     this.code = code;
   }
 };
+
+// src/index.ts
 var fileColorSchema = z.object({
   position: z.number().int(),
   proportion: z.number(),
@@ -169,10 +174,7 @@ var presignDedupeResultSchema = z.object({
   size: z.number(),
   contentType: z.string()
 });
-var presignResultSchema = z.union([
-  presignDedupeResultSchema,
-  presignNewResultSchema
-]);
+var presignResultSchema = z.union([presignDedupeResultSchema, presignNewResultSchema]);
 var confirmResultSchema = z.object({
   key: z.string(),
   url: z.string().nullable(),
@@ -224,6 +226,42 @@ var profileResultSchema = z.object({
   createdAt: z.string(),
   updatedAt: z.string()
 });
+var clusterGroupResultSchema = z.object({
+  id: z.string(),
+  index: z.number().int(),
+  name: z.string().nullable(),
+  description: z.string().nullable(),
+  fileCount: z.number().int(),
+  nameGeneratedAt: z.string().nullable()
+});
+var clusterResourceResultSchema = z.object({
+  id: z.string(),
+  name: z.string().nullable(),
+  clusterCount: z.number().int(),
+  fileCount: z.number().int(),
+  clusteredAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  clusters: z.array(clusterGroupResultSchema)
+});
+var clusterFileResultSchema = z.object({
+  id: z.string(),
+  key: z.string(),
+  bucketId: z.string(),
+  originalFilename: z.string().nullable(),
+  size: z.number(),
+  contentType: z.string(),
+  metadata: z.record(z.string(), z.string()).nullable(),
+  createdAt: z.string(),
+  distance: z.number().nullable()
+});
+var clusterFilesResultSchema = z.object({
+  clusterId: z.string(),
+  files: z.array(clusterFileResultSchema),
+  limit: z.number().int(),
+  offset: z.number().int(),
+  total: z.number().int()
+});
 var profileFilesResultSchema = z.object({
   id: z.string(),
   fileCount: z.number()
@@ -271,12 +309,48 @@ var anchorResponseSchema = z.object({
 var anchorListResponseSchema = z.object({
   anchors: z.array(anchorResponseSchema)
 });
+function sleep(ms) {
+  return delay(ms);
+}
+function buildTransformUrl(url, options) {
+  if (!(options && (options.width || options.height || options.quality || options.format))) {
+    return url;
+  }
+  const parsed = new URL(url);
+  if (options.width) {
+    parsed.searchParams.set("w", String(options.width));
+  }
+  if (options.height) {
+    parsed.searchParams.set("h", String(options.height));
+  }
+  if (options.quality) {
+    parsed.searchParams.set("q", String(options.quality));
+  }
+  if (options.format) {
+    parsed.searchParams.set("f", options.format);
+  }
+  return parsed.toString();
+}
 var StowServer = class {
   apiKey;
   baseUrl;
   bucket;
   timeout;
   retries;
+  /**
+   * Pure helper for building signed transform URLs from an existing public file URL.
+   *
+   * This does not perform any network I/O and is safe to pass around as a plain
+   * function, for example to view-layer code that needs responsive image URLs.
+   */
+  getTransformUrl;
+  /**
+   * Create a server SDK instance.
+   *
+   * Pass a bare string when you only need the API key and want default values
+   * for `baseUrl`, `timeout`, and retries. Pass an object when you want a
+   * default bucket, a non-production API origin, or custom transport settings.
+   */
   constructor(config) {
     if (typeof config === "string") {
       this.apiKey = config;
@@ -290,10 +364,9 @@ var StowServer = class {
       this.timeout = config.timeout ?? 3e4;
       this.retries = config.retries ?? 3;
     }
+    this.getTransformUrl = buildTransformUrl;
   }
-  /**
-   * Get the base URL for this instance (used by client SDK)
-   */
+  /** Return the configured API origin, mainly for adapter packages such as `stow-next`. */
   getBaseUrl() {
     return this.baseUrl;
   }
@@ -407,7 +480,7 @@ var StowServer = class {
   // 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++) {
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), this.timeout);
       if (options.signal) {
@@ -429,32 +502,28 @@ var StowServer = class {
           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);
+            await 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;
+      } catch (error) {
+        if (error instanceof StowError) {
+          throw error;
         }
-        if (err instanceof z.ZodError) {
-          throw new StowError(
-            "Invalid response format",
-            500,
-            "INVALID_RESPONSE"
-          );
+        if (error instanceof z.ZodError) {
+          throw new StowError("Invalid response format", 500, "INVALID_RESPONSE");
         }
-        if (err instanceof DOMException || err instanceof Error && err.name === "AbortError") {
+        if (error instanceof DOMException || error instanceof Error && error.name === "AbortError") {
           throw new StowError("Request timed out", 408, "TIMEOUT");
         }
         if (attempt < maxAttempts - 1) {
-          await this.sleep(1e3 * 2 ** attempt);
+          await sleep(1e3 * 2 ** attempt);
           continue;
         }
         throw new StowError(
-          err instanceof Error ? err.message : "Network error",
+          error instanceof Error ? error.message : "Network error",
           0,
           "NETWORK_ERROR"
         );
@@ -464,11 +533,30 @@ var StowServer = class {
     }
     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
+   * Upload bytes from a trusted server environment.
+   *
+   * This is the highest-level server upload helper:
+   * 1. compute a SHA-256 hash for dedupe
+   * 2. request a presigned upload URL
+   * 3. PUT bytes to storage
+   * 4. confirm the upload with optional AI metadata generation
+   *
+   * Prefer this method when your code already has the file bytes in memory.
+   * Use `getPresignedUrl()` + `confirmUpload()` for direct browser uploads
+   * instead, and `uploadFromUrl()` when the source is an external URL.
+   *
+   * @example
+   * ```typescript
+   * await stow.uploadFile(buffer, {
+   *   filename: "product.jpg",
+   *   contentType: "image/jpeg",
+   *   bucket: "catalog",
+   *   metadata: { sku: "SKU-123" },
+   *   title: true,
+   *   altText: true,
+   * });
+   * ```
    */
   async uploadFile(file, options) {
     const filename = options?.filename || "file";
@@ -502,10 +590,7 @@ var StowServer = class {
       throw new StowError("Failed to upload to storage", uploadRes.status);
     }
     return this.request(
-      this.withBucket(
-        presign.confirmUrl || "/presign/confirm",
-        options?.bucket
-      ),
+      this.withBucket(presign.confirmUrl || "/presign/confirm", options?.bucket),
       {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -525,7 +610,12 @@ var StowServer = class {
     );
   }
   /**
-   * Upload a file from a URL (server-side fetch + upload)
+   * Import a remote asset by URL.
+   *
+   * Stow fetches the remote URL server-side, stores the resulting bytes, and
+   * persists the file as if it had been uploaded normally. This is useful for
+   * migrations, ingestion pipelines, or bringing third-party assets into Stow
+   * without downloading them into your own process first.
    */
   async uploadFromUrl(url, filename, options) {
     const result = await this.request(
@@ -560,7 +650,7 @@ var StowServer = class {
    * The actual fetch, validation, and upload happen in a background worker.
    * Use this for bulk imports where you don't need immediate confirmation.
    */
-  async queueUploadFromUrl(url, filename, options) {
+  queueUploadFromUrl(url, filename, options) {
     return this.request(
       this.withBucket("/upload", options?.bucket),
       {
@@ -581,24 +671,20 @@ var StowServer = class {
     );
   }
   /**
-   * Get a presigned URL for direct client-side upload.
+   * Get a presigned URL for a direct client upload.
    *
-   * This enables uploads that bypass your server entirely:
-   * 1. Client calls your endpoint
-   * 2. Your endpoint calls this method
-   * 3. Client PUTs directly to the returned uploadUrl
-   * 4. Client calls confirmUpload to finalize
+   * This is the server-side half of the browser upload flow used by
+   * `@howells/stow-client` and `@howells/stow-next`:
+   * 1. browser calls your app
+   * 2. your app calls `getPresignedUrl()`
+   * 3. browser PUTs bytes to `uploadUrl`
+   * 4. browser or your app calls `confirmUpload()`
+   *
+   * If `contentHash` matches an existing file in the target bucket, the API
+   * short-circuits with `{ dedupe: true, ... }` and no upload is required.
    */
   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("/presign", bucket),
       {
@@ -617,8 +703,12 @@ var StowServer = class {
     );
   }
   /**
-   * Confirm a presigned upload after the client has uploaded to R2.
-   * This creates the file record in the database.
+   * Confirm a direct upload after the client has finished the storage PUT.
+   *
+   * This finalizes the file record in the database and optionally triggers
+   * post-processing such as AI-generated title/description/alt text.
+   *
+   * Call this exactly once per successful presigned upload.
    */
   confirmUpload(request) {
     const {
@@ -654,9 +744,13 @@ var StowServer = class {
     );
   }
   /**
-   * List files in the bucket
+   * List files in a bucket with optional prefix filtering and enrichment blocks.
    *
-   * @param options.include - Optional enrichment fields: `"tags"`, `"taxonomies"`
+   * Use `cursor` to continue pagination from a previous page. When requesting
+   * `include`, Stow expands those relationships inline so you can avoid follow-up
+   * per-file lookups.
+   *
+   * @param options.include Optional enrichment fields: `"tags"`, `"taxonomies"`
    */
   listFiles(options) {
     const params = new URLSearchParams();
@@ -676,11 +770,7 @@ var StowServer = class {
       params.set("include", options.include.join(","));
     }
     const path = `/files?${params}`;
-    return this.request(
-      this.withBucket(path, options?.bucket),
-      { method: "GET" },
-      listFilesSchema
-    );
+    return this.request(this.withBucket(path, options?.bucket), { method: "GET" }, listFilesSchema);
   }
   /**
    * Delete a file by key
@@ -703,9 +793,12 @@ var StowServer = class {
     });
   }
   /**
-   * Get a single file by key
+   * Get one file by key.
    *
-   * @param options.include - Optional enrichment fields: `"tags"`, `"taxonomies"`
+   * This is the detailed file view and includes dimensions, embeddings status,
+   * extracted colors, and AI metadata fields when available.
+   *
+   * @param options.include Optional enrichment fields: `"tags"`, `"taxonomies"`
    */
   getFile(key, options) {
     const params = new URLSearchParams();
@@ -813,35 +906,6 @@ var StowServer = class {
       replaceResultSchema
     );
   }
-  /**
-   * Get a transform URL for an image.
-   *
-   * Appends transform query params (?w=, ?h=, ?q=, ?f=) to a file URL.
-   * Transforms are applied at the edge by the Cloudflare Worker — no
-   * server round-trip needed.
-   *
-   * @param url - Full file URL (e.g. from upload result's fileUrl)
-   * @param options - Transform options (width, height, quality, format)
-   */
-  getTransformUrl(url, options) {
-    if (!(options && (options.width || options.height || options.quality || options.format))) {
-      return url;
-    }
-    const parsed = new URL(url);
-    if (options.width) {
-      parsed.searchParams.set("w", String(options.width));
-    }
-    if (options.height) {
-      parsed.searchParams.set("h", String(options.height));
-    }
-    if (options.quality) {
-      parsed.searchParams.set("q", String(options.quality));
-    }
-    if (options.format) {
-      parsed.searchParams.set("f", options.format);
-    }
-    return parsed.toString();
-  }
   // ============================================================
   // TAGS - Org-scoped labels for file organization
   // ============================================================
@@ -856,17 +920,17 @@ var StowServer = class {
     };
   }
   listTags() {
-    return this.request("/tags", { method: "GET" });
+    return this.request(this.withBucket("/tags"), { method: "GET" });
   }
   createTag(params) {
-    return this.request("/tags", {
+    return this.request(this.withBucket("/tags"), {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(params)
     });
   }
   async deleteTag(id) {
-    await this.request(`/tags/${encodeURIComponent(id)}`, {
+    await this.request(this.withBucket(`/tags/${encodeURIComponent(id)}`), {
       method: "DELETE"
     });
   }
@@ -919,7 +983,34 @@ var StowServer = class {
   // SEARCH - Vector similarity search
   // ============================================================
   /**
-   * Search namespace for vector similarity search
+   * Semantic search namespace.
+   *
+   * Methods:
+   * - `text(...)` embeds text and finds matching files
+   * - `similar(...)` finds nearest neighbors for a file, anchor, profile, or cluster
+   * - `diverse(...)` balances similarity against result spread
+   * - `color(...)` performs palette similarity search
+   * - `image(...)` searches using an existing file or an external image URL
+   *
+   * Cluster-aware search examples:
+   *
+   * @example
+   * ```typescript
+   * const cluster = await stow.clusters.create({
+   *   bucket: "inspiration",
+   *   fileKeys,
+   *   clusterCount: 12,
+   * });
+   *
+   * const firstGroup = cluster.clusters[0];
+   * if (firstGroup) {
+   *   const related = await stow.search.similar({
+   *     bucket: "inspiration",
+   *     clusterId: firstGroup.id,
+   *     limit: 20,
+   *   });
+   * }
+   * ```
    */
   get search() {
     return {
@@ -1091,7 +1182,11 @@ var StowServer = class {
   // PROFILES - Taste/preference profiles from file collections
   // ============================================================
   /**
-   * Profiles namespace for managing taste profiles
+   * Taste-profile namespace.
+   *
+   * Profiles are long-lived preference objects. They can be seeded from files,
+   * updated through weighted signals, clustered into interpretable segments, and
+   * then reused as semantic search seeds.
    */
   get profiles() {
     return {
@@ -1107,6 +1202,49 @@ var StowServer = class {
       renameCluster: (profileId, clusterId, params, bucket) => this.renameProfileCluster(profileId, clusterId, params, bucket)
     };
   }
+  /**
+   * Curated cluster namespace.
+   *
+   * Use this when you have an explicit file set that should be grouped by visual
+   * similarity, but should not be modeled as a behavioral profile.
+   *
+   * Typical workflow:
+   * 1. `create({ fileKeys, clusterCount })`
+   * 2. poll `get(id)` until `clusteredAt` is non-null
+   * 3. inspect `clusters`
+   * 4. fetch representative files with `files(id, clusterId)`
+   * 5. optionally `renameCluster(...)`
+   * 6. use `clusterId` with `search.similar(...)` or `search.diverse(...)`
+   *
+   * @example
+   * ```typescript
+   * const resource = await stow.clusters.create({
+   *   bucket: "featured-products",
+   *   fileKeys: featuredKeys,
+   *   clusterCount: 12,
+   *   name: "Navigator groups",
+   * });
+   *
+   * const latest = await stow.clusters.get(resource.id, "featured-products");
+   * const group = latest.clusters[0];
+   * if (group) {
+   *   const representatives = await stow.clusters.files(resource.id, group.id, {
+   *     limit: 12,
+   *     offset: 0,
+   *   });
+   * }
+   * ```
+   */
+  get clusters() {
+    return {
+      create: (params) => this.createClustersResource(params),
+      get: (id, bucket) => this.getClustersResource(id, bucket),
+      recluster: (id, params, bucket) => this.reclusterClustersResource(id, params, bucket),
+      files: (id, clusterId, params, bucket) => this.getClusterFiles(id, clusterId, params, bucket),
+      renameCluster: (id, clusterId, params, bucket) => this.renameClusterGroup(id, clusterId, params, bucket),
+      delete: (id, bucket) => this.deleteClustersResource(id, bucket)
+    };
+  }
   createProfile(params) {
     return this.request(
       this.withBucket("/profiles", params?.bucket),
@@ -1129,10 +1267,9 @@ var StowServer = class {
     );
   }
   async deleteProfile(id, bucket) {
-    await this.request(
-      this.withBucket(`/profiles/${encodeURIComponent(id)}`, bucket),
-      { method: "DELETE" }
-    );
+    await this.request(this.withBucket(`/profiles/${encodeURIComponent(id)}`, bucket), {
+      method: "DELETE"
+    });
   }
   addProfileFiles(id, fileKeys, bucket) {
     return this.request(
@@ -1179,36 +1316,99 @@ var StowServer = class {
     );
   }
   getProfileClusters(id, bucket) {
+    return this.request(this.withBucket(`/profiles/${encodeURIComponent(id)}/clusters`, bucket), {
+      method: "GET"
+    });
+  }
+  reclusterProfile(id, params, bucket) {
+    return this.request(this.withBucket(`/profiles/${encodeURIComponent(id)}/clusters`, bucket), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(
+        params?.clusterCount === void 0 ? {} : { clusterCount: params.clusterCount }
+      )
+    });
+  }
+  renameProfileCluster(profileId, clusterId, params, bucket) {
     return this.request(
-      this.withBucket(`/profiles/${encodeURIComponent(id)}/clusters`, bucket),
-      { method: "GET" }
+      this.withBucket(
+        `/profiles/${encodeURIComponent(profileId)}/clusters/${encodeURIComponent(clusterId)}`,
+        bucket
+      ),
+      {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(params)
+      }
     );
   }
-  reclusterProfile(id, params, bucket) {
+  createClustersResource(params) {
     return this.request(
-      this.withBucket(`/profiles/${encodeURIComponent(id)}/clusters`, bucket),
+      "/clusters",
       {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
-          ...params?.clusterCount === void 0 ? {} : { clusterCount: params.clusterCount }
+          fileKeys: params.fileKeys,
+          ...params.clusterCount === void 0 ? {} : { clusterCount: params.clusterCount },
+          ...params.name ? { name: params.name } : {},
+          ...params.bucket ? { bucket: params.bucket } : {}
         })
-      }
+      },
+      clusterResourceResultSchema
     );
   }
-  renameProfileCluster(profileId, clusterId, params, bucket) {
+  getClustersResource(id, bucket) {
+    return this.request(
+      this.withBucket(`/clusters/${encodeURIComponent(id)}`, bucket),
+      { method: "GET" },
+      clusterResourceResultSchema
+    );
+  }
+  reclusterClustersResource(id, params, bucket) {
+    return this.request(
+      this.withBucket(`/clusters/${encodeURIComponent(id)}/recluster`, bucket),
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(
+          params?.clusterCount === void 0 ? {} : { clusterCount: params.clusterCount }
+        )
+      },
+      clusterResourceResultSchema
+    );
+  }
+  getClusterFiles(id, clusterId, params, bucket) {
+    const searchParams = new URLSearchParams();
+    if (params?.limit !== void 0) {
+      searchParams.set("limit", String(params.limit));
+    }
+    if (params?.offset !== void 0) {
+      searchParams.set("offset", String(params.offset));
+    }
+    const qs = searchParams.toString();
+    const path = `/clusters/${encodeURIComponent(id)}/clusters/${encodeURIComponent(clusterId)}/files${qs ? `?${qs}` : ""}`;
+    return this.request(this.withBucket(path, bucket), { method: "GET" }, clusterFilesResultSchema);
+  }
+  renameClusterGroup(id, clusterId, params, bucket) {
     return this.request(
       this.withBucket(
-        `/profiles/${encodeURIComponent(profileId)}/clusters/${encodeURIComponent(clusterId)}`,
+        `/clusters/${encodeURIComponent(id)}/clusters/${encodeURIComponent(clusterId)}`,
         bucket
       ),
       {
         method: "PUT",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(params)
-      }
+      },
+      clusterGroupResultSchema
     );
   }
+  async deleteClustersResource(id, bucket) {
+    await this.request(this.withBucket(`/clusters/${encodeURIComponent(id)}`, bucket), {
+      method: "DELETE"
+    });
+  }
   // ============================================================
   // ANCHORS - Named semantic reference points in vector space
   // ============================================================
@@ -1270,10 +1470,9 @@ var StowServer = class {
     );
   }
   async deleteAnchor(id, options) {
-    await this.request(
-      this.withBucket(`/anchors/${encodeURIComponent(id)}`, options?.bucket),
-      { method: "DELETE" }
-    );
+    await this.request(this.withBucket(`/anchors/${encodeURIComponent(id)}`, options?.bucket), {
+      method: "DELETE"
+    });
   }
 };
 export {

package/package.json

@@ -1,20 +1,23 @@
 {
   "name": "@howells/stow-server",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Server-side SDK for Stow file storage",
+  "keywords": [
+    "file-storage",
+    "s3",
+    "sdk",
+    "stow",
+    "upload"
+  ],
+  "homepage": "https://stow.sh",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/howells/stow.git",
     "directory": "packages/stow-server"
   },
-  "homepage": "https://stow.sh",
-  "keywords": [
-    "stow",
-    "file-storage",
-    "s3",
-    "upload",
-    "sdk"
+  "files": [
+    "dist"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -26,24 +29,21 @@
       "require": "./dist/index.js"
     }
   },
-  "files": [
-    "dist"
-  ],
-  "peerDependencies": {
-    "zod": "^3.0.0 || ^4.0.0"
-  },
   "devDependencies": {
     "@types/node": "^25.5.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.0",
+    "vite-plus": "latest",
     "zod": "^4.3.6",
     "@stow/typescript-config": "0.0.0"
   },
+  "peerDependencies": {
+    "zod": "^3.0.0 || ^4.0.0"
+  },
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "test": "vp test run",
+    "test:watch": "vp test"
   }
 }