@howells/stow-server 0.1.0

package/dist/index.mjs

@@ -0,0 +1,451 @@
+// src/index.ts
+import { z } from "zod";
+var StowError = class extends Error {
+  status;
+  code;
+  constructor(message, status, code) {
+    super(message);
+    this.name = "StowError";
+    this.status = status;
+    this.code = code;
+  }
+};
+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()
+});
+var listFilesSchema = z.object({
+  files: z.array(
+    z.object({
+      key: z.string(),
+      size: z.number(),
+      lastModified: z.string(),
+      url: z.string().nullable(),
+      metadata: z.record(z.string(), z.string()).optional()
+    })
+  ),
+  nextCursor: z.string().nullable()
+});
+var errorSchema = z.object({
+  error: z.string(),
+  code: z.string().optional()
+});
+var dropResultSchema = z.object({
+  shortId: z.string(),
+  url: z.string(),
+  filename: z.string(),
+  size: z.number(),
+  contentType: z.string()
+});
+var dropSchema = z.object({
+  id: z.string(),
+  shortId: z.string(),
+  url: z.string(),
+  filename: z.string(),
+  size: z.number(),
+  contentType: z.string(),
+  createdAt: z.string()
+});
+var listDropsSchema = z.object({
+  drops: z.array(dropSchema),
+  usage: z.object({ bytes: z.number(), limit: z.number() })
+});
+var presignResultSchema = z.object({
+  fileKey: z.string(),
+  uploadUrl: z.string(),
+  r2Key: z.string(),
+  confirmUrl: z.string()
+});
+var confirmResultSchema = z.object({
+  key: z.string(),
+  url: z.string().nullable(),
+  size: z.number(),
+  contentType: z.string(),
+  metadata: z.record(z.string(), z.string()).optional()
+});
+var StowServer = class {
+  apiKey;
+  baseUrl;
+  bucket;
+  constructor(config) {
+    if (typeof config === "string") {
+      this.apiKey = config;
+      this.baseUrl = "https://stow.sh";
+    } else {
+      this.apiKey = config.apiKey;
+      this.baseUrl = config.baseUrl || "https://stow.sh";
+      this.bucket = config.bucket;
+    }
+  }
+  /**
+   * Get the base URL for this instance (used by client SDK)
+   */
+  getBaseUrl() {
+    return this.baseUrl;
+  }
+  /**
+   * Resolve the effective bucket for this request.
+   * Per-call override > constructor default.
+   */
+  resolveBucket(override) {
+    return override ?? this.bucket;
+  }
+  /**
+   * Append bucket query param to a URL path if set.
+   */
+  withBucket(path, bucket) {
+    const b = this.resolveBucket(bucket);
+    if (!b) {
+      return path;
+    }
+    const sep = path.includes("?") ? "&" : "?";
+    return `${path}${sep}bucket=${encodeURIComponent(b)}`;
+  }
+  /**
+   * Make an API request with proper error handling
+   */
+  async request(path, options, schema) {
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      ...options,
+      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;
+      throw new StowError(message, response.status, code);
+    }
+    return schema ? schema.parse(data) : data;
+  }
+  /**
+   * 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);
+    }
+    if (options?.metadata) {
+      formData.append("metadata", JSON.stringify(options.metadata));
+    }
+    const result = await this.request(
+      this.withBucket("/api/upload", options?.bucket),
+      {
+        method: "POST",
+        body: formData
+      },
+      uploadResultSchema
+    );
+    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)
+   */
+  async uploadFromUrl(url, filename, options) {
+    const result = await this.request(
+      this.withBucket("/api/upload", options?.bucket),
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          url,
+          filename,
+          ...options?.metadata ? { metadata: options.metadata } : {}
+        })
+      },
+      uploadResultSchema
+    );
+    return {
+      key: result.key,
+      url: result.url,
+      size: result.size,
+      contentType: result.contentType || "application/octet-stream",
+      ...result.metadata ? { metadata: result.metadata } : {}
+    };
+  }
+  /**
+   * Get a presigned URL for direct client-side 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
+   */
+  getPresignedUrl(request) {
+    const { filename, contentType, size, route, bucket, metadata } = request;
+    return this.request(
+      this.withBucket("/api/presign", bucket),
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          filename,
+          contentType,
+          size,
+          route,
+          ...metadata ? { metadata } : {}
+        })
+      },
+      presignResultSchema
+    );
+  }
+  /**
+   * Confirm a presigned upload after the client has uploaded to R2.
+   * This creates the file record in the database.
+   */
+  confirmUpload(request) {
+    const { fileKey, size, contentType, bucket, metadata } = request;
+    return this.request(
+      this.withBucket("/api/presign/confirm", bucket),
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          fileKey,
+          size,
+          contentType,
+          ...metadata ? { metadata } : {}
+        })
+      },
+      confirmResultSchema
+    );
+  }
+  /**
+   * List files in the bucket
+   */
+  listFiles(options) {
+    const params = new URLSearchParams();
+    if (options?.prefix) {
+      params.set("prefix", options.prefix);
+    }
+    if (options?.limit) {
+      params.set("limit", options.limit.toString());
+    }
+    if (options?.cursor) {
+      params.set("cursor", options.cursor);
+    }
+    if (options?.tag) {
+      params.set("tag", options.tag);
+    }
+    const path = `/api/files?${params}`;
+    return this.request(
+      this.withBucket(path, options?.bucket),
+      { method: "GET" },
+      listFilesSchema
+    );
+  }
+  /**
+   * Delete a file by key
+   */
+  async deleteFile(key, options) {
+    const path = `/api/files/${encodeURIComponent(key)}`;
+    await this.request(this.withBucket(path, options?.bucket), {
+      method: "DELETE"
+    });
+  }
+  /**
+   * Update metadata on an existing file
+   */
+  async updateFileMetadata(key, metadata, options) {
+    const path = `/api/files/${encodeURIComponent(key)}`;
+    return this.request(this.withBucket(path, options?.bucket), {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ metadata })
+    });
+  }
+  /**
+   * 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) {
+    const params = new URLSearchParams();
+    if (options?.width) {
+      params.set("w", options.width.toString());
+    }
+    if (options?.height) {
+      params.set("h", options.height.toString());
+    }
+    if (options?.quality) {
+      params.set("q", options.quality.toString());
+    }
+    if (options?.format) {
+      params.set("f", options.format);
+    }
+    const query = params.toString();
+    if (!query) {
+      return url;
+    }
+    const separator = url.includes("?") ? "&" : "?";
+    return `${url}${separator}${query}`;
+  }
+  // ============================================================
+  // TAGS - Org-scoped labels for file organization
+  // ============================================================
+  /**
+   * Tags namespace for creating, listing, and deleting tags
+   */
+  get tags() {
+    return {
+      list: () => this.listTags(),
+      create: (params) => this.createTag(params),
+      delete: (id) => this.deleteTag(id)
+    };
+  }
+  listTags() {
+    return this.request("/api/tags", { method: "GET" });
+  }
+  createTag(params) {
+    return this.request("/api/tags", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(params)
+    });
+  }
+  async deleteTag(id) {
+    await this.request(`/api/tags/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+  }
+  // ============================================================
+  // FILE TAGGING
+  // ============================================================
+  /**
+   * Add tags to a file
+   */
+  async addTags(key, tagIds, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/tags`;
+    await this.request(this.withBucket(path, options?.bucket), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ tagIds })
+    });
+  }
+  /**
+   * Remove a tag from a file
+   */
+  async removeTag(key, tagId, options) {
+    const path = `/api/files/${encodeURIComponent(key)}/tags/${encodeURIComponent(tagId)}`;
+    await this.request(this.withBucket(path, options?.bucket), {
+      method: "DELETE"
+    });
+  }
+  // ============================================================
+  // SEARCH - Vector similarity search
+  // ============================================================
+  /**
+   * Search namespace for vector similarity search
+   */
+  get search() {
+    return {
+      similar: (params) => this.searchSimilar(params)
+    };
+  }
+  searchSimilar(params) {
+    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 } : {}
+      })
+    });
+  }
+  // ============================================================
+  // DROPS - Quick share without buckets
+  // ============================================================
+  /**
+   * Upload a file as a drop (quick share)
+   *
+   * Drops are simpler than bucket uploads - just upload and get a URL.
+   * No bucket setup required. 1GB storage limit per user.
+   *
+   * @example
+   * ```typescript
+   * const drop = await stow.drop(buffer, { filename: "screenshot.png" });
+   * console.log(drop.url); // https://d.stow.sh/x7kQ3m
+   * ```
+   */
+  async drop(file, options) {
+    const contentType = options?.contentType || "application/octet-stream";
+    const filename = options?.filename || "file";
+    const buffer = Buffer.isBuffer(file) ? file : Buffer.from(await file.arrayBuffer());
+    const presign = await this.request("/api/drops/presign", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        filename,
+        contentType,
+        size: buffer.length
+      })
+    });
+    const putRes = await fetch(presign.uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": contentType },
+      body: buffer
+    });
+    if (!putRes.ok) {
+      throw new StowError("Failed to upload to storage", putRes.status);
+    }
+    return this.request(
+      "/api/drops/presign/confirm",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          shortId: presign.shortId,
+          r2Key: presign.r2Key,
+          size: buffer.length,
+          contentType,
+          filename,
+          ...presign.uploadToken ? { uploadToken: presign.uploadToken } : {}
+        })
+      },
+      dropResultSchema
+    );
+  }
+  /**
+   * List all drops for the authenticated user
+   */
+  listDrops() {
+    return this.request("/api/drops", { method: "GET" }, listDropsSchema);
+  }
+  /**
+   * Delete a drop by ID
+   */
+  async deleteDrop(id) {
+    await this.request(`/api/drops/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+  }
+};
+export {
+  StowError,
+  StowServer
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@howells/stow-server",
+  "version": "0.1.0",
+  "description": "Server-side SDK for Stow file storage",
+  "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"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "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"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@stow/typescript-config": "workspace:*",
+    "@types/node": "^25.2.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.0",
+    "zod": "^4.3.6"
+  }
+}