@howells/stow-server 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,302 @@
+/**
+ * Stow Server SDK
+ *
+ * Server-side SDK for Node.js environments.
+ * Use this to upload files, generate presigned URLs, and manage files from your server.
+ *
+ * @example
+ * ```typescript
+ * import { StowServer } from "@howells/stow-server";
+ *
+ * // Scoped API key — bucket is implicit
+ * const stow = new StowServer(process.env.STOW_API_KEY!);
+ *
+ * // Global API key — specify bucket
+ * const stow = new StowServer({
+ *   apiKey: process.env.STOW_API_KEY!,
+ *   bucket: "my-blog",
+ * });
+ *
+ * const result = await stow.uploadFromUrl("https://example.com/image.jpg", "image.jpg");
+ * console.log(result.url);
+ * ```
+ */
+declare class StowError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    constructor(message: string, status: number, code?: string);
+}
+interface StowServerConfig {
+    apiKey: string;
+    baseUrl?: string;
+    /** Default bucket name or ID. Required for global API keys. */
+    bucket?: string;
+}
+interface UploadResult {
+    key: string;
+    url: string | null;
+    size: number;
+    contentType: string;
+    metadata?: Record<string, string>;
+}
+interface TransformOptions {
+    width?: number;
+    height?: number;
+    quality?: number;
+    format?: "webp" | "avif" | "jpeg" | "png";
+}
+interface ListFilesResult {
+    files: Array<{
+        key: string;
+        size: number;
+        lastModified: string;
+        url: string | null;
+        metadata?: Record<string, string>;
+    }>;
+    nextCursor: string | null;
+}
+interface DropResult {
+    shortId: string;
+    url: string;
+    filename: string;
+    size: number;
+    contentType: string;
+}
+interface Drop {
+    id: string;
+    shortId: string;
+    url: string;
+    filename: string;
+    size: number;
+    contentType: string;
+    createdAt: string;
+}
+interface ListDropsResult {
+    drops: Drop[];
+    usage: {
+        bytes: number;
+        limit: number;
+    };
+}
+interface PresignResult {
+    /** The file key that will be created */
+    fileKey: string;
+    /** URL to PUT the file to */
+    uploadUrl: string;
+    /** The R2 key for the file */
+    r2Key: string;
+    /** URL to call to confirm the upload */
+    confirmUrl: string;
+}
+interface PresignRequest {
+    filename: string;
+    contentType: string;
+    /** File size in bytes */
+    size: number;
+    /** Optional route/folder */
+    route?: string;
+    /** Override the default bucket */
+    bucket?: string;
+    /** Custom metadata to attach to the file */
+    metadata?: Record<string, string>;
+}
+interface ConfirmUploadRequest {
+    fileKey: string;
+    size: number;
+    contentType: string;
+    /** Override the default bucket */
+    bucket?: string;
+    /** Custom metadata to attach to the file */
+    metadata?: Record<string, string>;
+}
+interface SimilarSearchRequest {
+    /** Find files similar to this file key */
+    fileKey?: string;
+    /** Search directly with a vector (1024 dimensions) */
+    vector?: number[];
+    /** Bucket name or ID to scope search */
+    bucket?: string;
+    /** Max results (default 10, max 50) */
+    limit?: number;
+}
+interface SimilarSearchResult {
+    results: Array<{
+        id: string;
+        key: string;
+        bucketId: string;
+        originalFilename: string | null;
+        size: number;
+        contentType: string;
+        metadata: Record<string, string> | null;
+        embeddingStatus: string | null;
+        similarity: number;
+        createdAt: string;
+    }>;
+}
+declare class StowServer {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly bucket?;
+    constructor(config: StowServerConfig | string);
+    /**
+     * Get the base URL for this instance (used by client SDK)
+     */
+    getBaseUrl(): string;
+    /**
+     * Resolve the effective bucket for this request.
+     * Per-call override > constructor default.
+     */
+    private resolveBucket;
+    /**
+     * Append bucket query param to a URL path if set.
+     */
+    private withBucket;
+    /**
+     * Make an API request with proper error handling
+     */
+    private request;
+    /**
+     * Upload a file directly from the server
+     */
+    uploadFile(file: Buffer | Blob, options?: {
+        filename?: string;
+        contentType?: string;
+        route?: string;
+        /** Override the default bucket for this request */
+        bucket?: string;
+        /** Custom metadata to attach to the file */
+        metadata?: Record<string, string>;
+    }): Promise<UploadResult>;
+    /**
+     * Upload a file from a URL (server-side fetch + upload)
+     */
+    uploadFromUrl(url: string, filename: string, options?: {
+        bucket?: string;
+        metadata?: Record<string, string>;
+    }): Promise<UploadResult>;
+    /**
+     * 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: PresignRequest): Promise<PresignResult>;
+    /**
+     * Confirm a presigned upload after the client has uploaded to R2.
+     * This creates the file record in the database.
+     */
+    confirmUpload(request: ConfirmUploadRequest): Promise<UploadResult>;
+    /**
+     * List files in the bucket
+     */
+    listFiles(options?: {
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+        bucket?: string;
+        /** Filter by tag slug */
+        tag?: string;
+    }): Promise<ListFilesResult>;
+    /**
+     * Delete a file by key
+     */
+    deleteFile(key: string, options?: {
+        bucket?: string;
+    }): Promise<void>;
+    /**
+     * Update metadata on an existing file
+     */
+    updateFileMetadata(key: string, metadata: Record<string, string>, options?: {
+        bucket?: string;
+    }): Promise<{
+        key: string;
+        metadata: Record<string, string>;
+    }>;
+    /**
+     * 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: string, options?: TransformOptions): string;
+    /**
+     * Tags namespace for creating, listing, and deleting tags
+     */
+    get tags(): {
+        list: () => Promise<{
+            tags: Array<{
+                id: string;
+                name: string;
+                slug: string;
+                color: string | null;
+                createdAt: string;
+            }>;
+        }>;
+        create: (params: {
+            name: string;
+            color?: string;
+        }) => Promise<{
+            id: string;
+            name: string;
+            slug: string;
+            color: string | null;
+            createdAt: string;
+        }>;
+        delete: (id: string) => Promise<void>;
+    };
+    private listTags;
+    private createTag;
+    private deleteTag;
+    /**
+     * Add tags to a file
+     */
+    addTags(key: string, tagIds: string[], options?: {
+        bucket?: string;
+    }): Promise<void>;
+    /**
+     * Remove a tag from a file
+     */
+    removeTag(key: string, tagId: string, options?: {
+        bucket?: string;
+    }): Promise<void>;
+    /**
+     * Search namespace for vector similarity search
+     */
+    get search(): {
+        similar: (params: SimilarSearchRequest) => Promise<SimilarSearchResult>;
+    };
+    private searchSimilar;
+    /**
+     * 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
+     * ```
+     */
+    drop(file: Buffer | Blob, options?: {
+        filename?: string;
+        contentType?: string;
+    }): Promise<DropResult>;
+    /**
+     * List all drops for the authenticated user
+     */
+    listDrops(): Promise<ListDropsResult>;
+    /**
+     * Delete a drop by ID
+     */
+    deleteDrop(id: string): Promise<void>;
+}
+
+export { type ConfirmUploadRequest, type Drop, type DropResult, type ListDropsResult, type ListFilesResult, type PresignRequest, type PresignResult, type SimilarSearchRequest, type SimilarSearchResult, StowError, StowServer, type StowServerConfig, type TransformOptions, type UploadResult };