@howells/stow-server 0.1.0

package/dist/index.js

@@ -0,0 +1,477 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  StowError: () => StowError,
+  StowServer: () => StowServer
+});
+module.exports = __toCommonJS(index_exports);
+var import_zod = require("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 = import_zod.z.object({
+  key: import_zod.z.string(),
+  url: import_zod.z.string().nullable(),
+  size: import_zod.z.number(),
+  contentType: import_zod.z.string().optional(),
+  metadata: import_zod.z.record(import_zod.z.string(), import_zod.z.string()).optional()
+});
+var listFilesSchema = import_zod.z.object({
+  files: import_zod.z.array(
+    import_zod.z.object({
+      key: import_zod.z.string(),
+      size: import_zod.z.number(),
+      lastModified: import_zod.z.string(),
+      url: import_zod.z.string().nullable(),
+      metadata: import_zod.z.record(import_zod.z.string(), import_zod.z.string()).optional()
+    })
+  ),
+  nextCursor: import_zod.z.string().nullable()
+});
+var errorSchema = import_zod.z.object({
+  error: import_zod.z.string(),
+  code: import_zod.z.string().optional()
+});
+var dropResultSchema = import_zod.z.object({
+  shortId: import_zod.z.string(),
+  url: import_zod.z.string(),
+  filename: import_zod.z.string(),
+  size: import_zod.z.number(),
+  contentType: import_zod.z.string()
+});
+var dropSchema = import_zod.z.object({
+  id: import_zod.z.string(),
+  shortId: import_zod.z.string(),
+  url: import_zod.z.string(),
+  filename: import_zod.z.string(),
+  size: import_zod.z.number(),
+  contentType: import_zod.z.string(),
+  createdAt: import_zod.z.string()
+});
+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({
+  fileKey: import_zod.z.string(),
+  uploadUrl: import_zod.z.string(),
+  r2Key: import_zod.z.string(),
+  confirmUrl: import_zod.z.string()
+});
+var confirmResultSchema = import_zod.z.object({
+  key: import_zod.z.string(),
+  url: import_zod.z.string().nullable(),
+  size: import_zod.z.number(),
+  contentType: import_zod.z.string(),
+  metadata: import_zod.z.record(import_zod.z.string(), import_zod.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"
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StowError,
+  StowServer
+});