upthing-sdk 1.0.0 → 1.0.2

package/README.md

@@ -8,38 +8,64 @@ TypeScript SDK for [upthing.2klabs.xyz](https://upthing.2klabs.xyz) — upload f
 npm install upthing-sdk
 ```
 
-## Quick start
+## Two entry points
+
+| Import | Environment | Has `uploadFile`? |
+| ------ | ----------- | ----------------- |
+| `upthing-sdk` | Browser + Node.js | No (`fs` would break bundlers) |
+| `upthing-sdk/node` | Node.js only | Yes |
+
+Use the default import for browser/edge/client-side code (Next.js `"use client"`, React, etc.).
+Use `upthing-sdk/node` in server-only code when you need `uploadFile()`.
+
+## Quick start (Node.js)
 
 ```typescript
-import { UpThingClient } from "upthing-sdk";
+import { UpThingNodeClient } from "upthing-sdk/node";
 
-const upthing = new UpThingClient({
+const upthing = new UpThingNodeClient({
   apiKey: process.env.UPTHING_API_KEY!,
 });
 
-// Upload a file
+// Upload a file from disk
 const file = await upthing.uploadFile("./photo.jpg");
 console.log(file.url);
 // https://upthing.2klabs.xyz/f/UgjIzXI3ZolZ
 
-// Proxy an external image — get a URL you can use directly
+// Proxy an external image
 const src = upthing.proxyUrl("https://example.com/banner.jpg");
-// <img src={src} />
+```
+
+## Quick start (Browser / Next.js client)
+
+```typescript
+"use client";
+import { UpThingClient } from "upthing-sdk";
+
+// No API key needed for domain-auth proxy
+const upthing = new UpThingClient();
+
+// Use directly in JSX
+<img src={upthing.proxyUrl("https://example.com/photo.jpg", {
+  projectUuid: "07595179-..."
+})} />
 ```
 
 ## API
 
-### `new UpThingClient(options)`
+### `new UpThingClient(options?)`
+
+| Option    | Type   | Default                       |
+| --------- | ------ | ----------------------------- |
+| `apiKey`  | string | `""` (optional for proxy URL builders) |
+| `baseUrl` | string | `https://upthing.2klabs.xyz`  |
 
-| Option    | Type   | Default                          |
-| --------- | ------ | -------------------------------- |
-| `apiKey`  | string | **required**                     |
-| `baseUrl` | string | `https://upthing.2klabs.xyz`    |
+`UpThingNodeClient` (from `upthing-sdk/node`) extends `UpThingClient` and adds `uploadFile()`.
 
 ### Upload methods
 
 ```typescript
-// From a file path (Node.js)
+// From a file path (Node.js only — use UpThingNodeClient)
 await upthing.uploadFile("./photo.jpg");
 await upthing.uploadFile("./photo.jpg", { ttlSeconds: 3600 });
 
@@ -64,14 +90,14 @@ await upthing.uploadBase64(base64String, "avatar.png");
 ### Proxy
 
 ```typescript
-// Build a URL that serves the proxied image (use in <img>, fetch, etc.)
+// Build a URL for domain-auth proxy (no API key needed)
 const src = upthing.proxyUrl("https://example.com/image.jpg");
 const src = upthing.proxyUrl("https://example.com/image.jpg", {
   projectUuid: "07595179-...",
   ttlSeconds: 3600,
 });
 
-// Fetch the image bytes server-side
+// Fetch the image bytes server-side (requires API key)
 const response = await upthing.proxyFetch("https://example.com/image.jpg");
 const buffer = await response.arrayBuffer();
 ```
@@ -90,7 +116,7 @@ upthing.permanentUrl("UgjIzXI3ZolZ");
 import { UpThingSDKError } from "upthing-sdk";
 
 try {
-  await upthing.uploadFile("./huge.mp4");
+  await upthing.uploadBlob(file, "huge.mp4");
 } catch (err) {
   if (err instanceof UpThingSDKError) {
     console.error(err.status, err.message);
@@ -99,20 +125,26 @@ try {
 }
 ```
 
-## Browser usage
+Methods that require an API key (`uploadBlob`, `uploadBuffer`, `uploadBase64`, `uploadFile`, `proxyFetch`) throw immediately with a helpful message if no key was provided.
+
+## Browser / React / Next.js usage
 
 ```typescript
-const upthing = new UpThingClient({ apiKey: "ak_..." });
+"use client";
+import { UpThingClient } from "upthing-sdk";
+
+const upthing = new UpThingClient();
 
-// Proxy images directly in HTML — no async needed
-document.querySelector("img")!.src = upthing.proxyUrl("https://example.com/photo.jpg");
+// Proxy images directly in HTML — no API key needed with domain auth
+<img src={upthing.proxyUrl("https://example.com/photo.jpg")} />
 
-// Upload from a file input
+// Upload from a file input (requires API key)
+const uploader = new UpThingClient({ apiKey: "ak_..." });
 const input = document.querySelector<HTMLInputElement>("#file-input")!;
 input.addEventListener("change", async () => {
   const file = input.files?.[0];
   if (!file) return;
-  const result = await upthing.uploadBlob(file, file.name);
+  const result = await uploader.uploadBlob(file, file.name);
   console.log("Uploaded:", result.url);
 });
 ```

package/dist/index.d.ts

@@ -34,17 +34,13 @@ export declare class UpThingSDKError extends Error {
     constructor(status: number, body: UpThingError);
 }
 export interface UpThingClientOptions {
-    apiKey: string;
+    apiKey?: string;
     baseUrl?: string;
 }
 export declare class UpThingClient {
     private readonly apiKey;
     private readonly baseUrl;
-    constructor(options: UpThingClientOptions);
-    /**
-     * Upload a file from a local path (Node.js only).
-     */
-    uploadFile(filePath: string, options?: UploadOptions): Promise<UpThingFile>;
+    constructor(options?: UpThingClientOptions);
     /**
      * Upload a Blob/File (works in Node.js and browsers).
      */
@@ -66,12 +62,16 @@ export declare class UpThingClient {
     /**
      * Fetch a proxied image and return the raw Response.
      * Sends the API key via header (never exposed in the URL).
+     * Requires an API key — use proxyUrl() for domain-auth-only requests.
      */
     proxyFetch(url: string, options?: ProxyOptions): Promise<Response>;
     /**
      * Build a permanent delivery URL for a public_id.
      */
     permanentUrl(publicId: string): string;
-    private request;
+    /** @internal */
+    requireKey(method: string): void;
+    /** @internal */
+    request<T>(method: string, path: string, body?: FormData | Record<string, unknown>): Promise<T>;
 }
 export default UpThingClient;

package/dist/index.js

@@ -11,27 +11,11 @@ export class UpThingSDKError extends Error {
 export class UpThingClient {
     apiKey;
     baseUrl;
-    constructor(options) {
-        this.apiKey = options.apiKey;
+    constructor(options = {}) {
+        this.apiKey = options.apiKey ?? "";
         this.baseUrl = (options.baseUrl ?? "https://upthing.2klabs.xyz").replace(/\/$/, "");
     }
     // ── Upload ──────────────────────────────────────────────────────────
-    /**
-     * Upload a file from a local path (Node.js only).
-     */
-    async uploadFile(filePath, options) {
-        const fs = await import("fs");
-        const path = await import("path");
-        const form = new FormData();
-        const blob = new Blob([fs.readFileSync(filePath)]);
-        const name = options?.filename ?? path.basename(filePath);
-        form.append("file", blob, name);
-        if (options?.projectUuid)
-            form.append("project_uuid", options.projectUuid);
-        if (options?.ttlSeconds != null)
-            form.append("ttl_seconds", String(options.ttlSeconds));
-        return this.request("POST", "/api/upload", form).then((r) => r.file);
-    }
     /**
      * Upload a Blob/File (works in Node.js and browsers).
      */
@@ -79,8 +63,10 @@ export class UpThingClient {
     /**
      * Fetch a proxied image and return the raw Response.
      * Sends the API key via header (never exposed in the URL).
+     * Requires an API key — use proxyUrl() for domain-auth-only requests.
      */
     async proxyFetch(url, options) {
+        this.requireKey("proxyFetch");
         const target = this.proxyUrl(url, options);
         const res = await fetch(target, {
             headers: { "X-API-Key": this.apiKey },
@@ -99,7 +85,16 @@ export class UpThingClient {
         return `${this.baseUrl}/f/${publicId}`;
     }
     // ── Internal ────────────────────────────────────────────────────────
+    /** @internal */
+    requireKey(method) {
+        if (!this.apiKey) {
+            throw new Error(`UpThingClient.${method}() requires an apiKey. ` +
+                `Pass one via new UpThingClient({ apiKey: "ak_..." }).`);
+        }
+    }
+    /** @internal */
     async request(method, path, body) {
+        this.requireKey("request");
         const headers = {
             "X-API-Key": this.apiKey,
         };

package/dist/node.d.ts

@@ -0,0 +1,9 @@
+import { UpThingClient, type UploadOptions, type UpThingFile } from "./index.js";
+export declare class UpThingNodeClient extends UpThingClient {
+    /**
+     * Upload a file from a local path (Node.js only).
+     */
+    uploadFile(filePath: string, options?: UploadOptions): Promise<UpThingFile>;
+}
+export * from "./index.js";
+export default UpThingNodeClient;

package/dist/node.js

@@ -0,0 +1,22 @@
+import { UpThingClient } from "./index.js";
+import { readFileSync } from "fs";
+import { basename } from "path";
+export class UpThingNodeClient extends UpThingClient {
+    /**
+     * Upload a file from a local path (Node.js only).
+     */
+    async uploadFile(filePath, options) {
+        const form = new FormData();
+        const blob = new Blob([readFileSync(filePath)]);
+        const name = options?.filename ?? basename(filePath);
+        form.append("file", blob, name);
+        if (options?.projectUuid)
+            form.append("project_uuid", options.projectUuid);
+        if (options?.ttlSeconds != null)
+            form.append("ttl_seconds", String(options.ttlSeconds));
+        this.requireKey("uploadFile");
+        return this.request("POST", "/api/upload", form).then((r) => r.file);
+    }
+}
+export * from "./index.js";
+export default UpThingNodeClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "upthing-sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "TypeScript SDK for upthing.2klabs.xyz — upload files, proxy images",
   "type": "module",
   "main": "dist/index.js",
@@ -12,6 +12,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./node": {
+      "import": "./dist/node.js",
+      "types": "./dist/node.d.ts"
     }
   },
   "scripts": {