@pylonsync/react 0.11.1 → 0.11.4

package/dist/db.d.ts

@@ -1,6 +1,6 @@
 import { SyncEngine, type Row, type SyncEngineConfig } from "@pylonsync/sync";
 import { type QueryOptions, type UseQueryReturn, type UseQueryOneReturn, type UseReactiveQueryReturn, type UseMutationReturn, type UseInfiniteQueryReturn, type AggregateSpec, type UseAggregateReturn, type SearchSpec, type UseSearchReturn } from "./hooks";
-import { type UploadedFile } from "./index";
+import { type UploadedFile, type UploadFileOptions } from "./index";
 /**
  * Initialize the pylon client. Call once at app startup.
  *
@@ -172,11 +172,8 @@ export declare const db: {
      * ```
      */
     streamFn(name: string, args?: Record<string, unknown>): AsyncGenerator<string, unknown, unknown>;
-    /** Upload a file to /api/files/upload. */
-    uploadFile(input: File | Blob | ArrayBuffer | Uint8Array, options?: {
-        filename?: string;
-        contentType?: string;
-    }): Promise<UploadedFile>;
-    /** Upload via multipart/form-data with extra fields. */
+    /** Upload a file through /api/files/init, a PUT, and /api/files/confirm. */
+    uploadFile(input: File | Blob | ArrayBuffer | Uint8Array, options?: UploadFileOptions): Promise<UploadedFile>;
+    /** @deprecated Use `uploadFile`; extra fields were never stored. */
     uploadFileMultipart(file: File | Blob, fields?: Record<string, string>): Promise<UploadedFile>;
 };

package/dist/index.d.ts

@@ -237,32 +237,50 @@ export declare function listFns(): Promise<{
 }[]>;
 export interface UploadedFile {
     id: string;
+    /** Where to read the file. Store this on your row. */
     url: string;
     size: number;
 }
 /**
- * Upload a file (File/Blob or raw bytes) to /api/files/upload.
+ * Who can read an uploaded file through `url`.
+ *   - "private" (default): only the uploader.
+ *   - "public": anyone, signed in or not. Use it for content every visitor
+ *     sees, such as feed photos or listing images.
+ * Writes and deletes stay with the uploader either way. On a CDN-backed
+ * store (Stack0, a public bucket) every file is served by its URL, so the
+ * setting only changes reads that go through `/api/files/<id>`.
+ */
+export type FileVisibility = "private" | "public";
+export interface UploadFileOptions {
+    filename?: string;
+    contentType?: string;
+    token?: string;
+    visibility?: FileVisibility;
+}
+/**
+ * Upload a file (File, Blob, or raw bytes) in three steps:
+ *   1. POST /api/files/init with the name, type, size, and visibility;
+ *   2. PUT the bytes to the returned upload URL;
+ *   3. POST /api/files/confirm, which returns `{ id, url, size }`.
  *
- * For File / Blob inputs this sends a single raw binary request with the
- * filename and content-type as headers (the server short-circuits on this
- * shape so uploads avoid being coerced through string-based handling).
+ * The upload URL is either pylon's own receiver (local disk), which needs
+ * the session like any API call, or a presigned storage URL, whose
+ * signature is the credential. The session is never sent to a presigned
+ * URL on another origin.
  *
  * @example
  * ```ts
- * const uploaded = await uploadFile(fileFromInput);
- * console.log(uploaded.url, uploaded.id, uploaded.size);
+ * const photo = await uploadFile(fileFromInput, { visibility: "public" });
+ * await db.insert("Post", { imageUrl: photo.url, caption });
  * ```
  */
-export declare function uploadFile(input: File | Blob | ArrayBuffer | Uint8Array, options?: {
-    filename?: string;
-    contentType?: string;
-    token?: string;
-}): Promise<UploadedFile>;
+export declare function uploadFile(input: File | Blob | ArrayBuffer | Uint8Array, options?: UploadFileOptions): Promise<UploadedFile>;
 /**
- * Upload via multipart/form-data. Useful when the app needs to pass extra
- * fields alongside the file (captions, categories, etc.), though only the
- * first file part is stored today.
+ * @deprecated The multipart endpoint was removed in pylon 0.3.91 and never
+ * stored the extra fields. This uploads the file with `uploadFile` and
+ * ignores `fields`; send those to your own function instead.
  */
-export declare function uploadFileMultipart(file: File | Blob, fields?: Record<string, string>, options?: {
+export declare function uploadFileMultipart(file: File | Blob, _fields?: Record<string, string>, options?: {
     token?: string;
+    visibility?: FileVisibility;
 }): Promise<UploadedFile>;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.11.1",
+  "version": "0.11.4",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
@@ -14,8 +14,8 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.11.1",
-    "@pylonsync/sync": "0.11.1"
+    "@pylonsync/sdk": "0.11.4",
+    "@pylonsync/sync": "0.11.4"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/db.ts

@@ -31,6 +31,7 @@ import {
   uploadFile,
   uploadFileMultipart,
   type UploadedFile,
+  type UploadFileOptions,
 } from "./index";
 
 // ---------------------------------------------------------------------------
@@ -331,15 +332,15 @@ export const db = {
     return streamFn(name, args);
   },
 
-  /** Upload a file to /api/files/upload. */
+  /** Upload a file through /api/files/init, a PUT, and /api/files/confirm. */
   uploadFile(
     input: File | Blob | ArrayBuffer | Uint8Array,
-    options?: { filename?: string; contentType?: string }
+    options?: UploadFileOptions
   ): Promise<UploadedFile> {
     return uploadFile(input, options);
   },
 
-  /** Upload via multipart/form-data with extra fields. */
+  /** @deprecated Use `uploadFile`; extra fields were never stored. */
   uploadFileMultipart(
     file: File | Blob,
     fields?: Record<string, string>

package/src/index.ts

@@ -73,6 +73,7 @@ import {
   defaultStorage,
   pylonFetch,
   pylonFetchRaw,
+  PylonHttpError,
   type Storage as PylonStorage,
 } from "@pylonsync/sync";
 import { peekActiveEngine } from "./engine-registry";
@@ -911,94 +912,131 @@ export async function listFns(): Promise<
 
 export interface UploadedFile {
   id: string;
+  /** Where to read the file. Store this on your row. */
   url: string;
   size: number;
 }
 
 /**
- * Upload a file (File/Blob or raw bytes) to /api/files/upload.
+ * Who can read an uploaded file through `url`.
+ *   - "private" (default): only the uploader.
+ *   - "public": anyone, signed in or not. Use it for content every visitor
+ *     sees, such as feed photos or listing images.
+ * Writes and deletes stay with the uploader either way. On a CDN-backed
+ * store (Stack0, a public bucket) every file is served by its URL, so the
+ * setting only changes reads that go through `/api/files/<id>`.
+ */
+export type FileVisibility = "private" | "public";
+
+export interface UploadFileOptions {
+  filename?: string;
+  contentType?: string;
+  token?: string;
+  visibility?: FileVisibility;
+}
+
+/**
+ * Upload a file (File, Blob, or raw bytes) in three steps:
+ *   1. POST /api/files/init with the name, type, size, and visibility;
+ *   2. PUT the bytes to the returned upload URL;
+ *   3. POST /api/files/confirm, which returns `{ id, url, size }`.
  *
- * For File / Blob inputs this sends a single raw binary request with the
- * filename and content-type as headers (the server short-circuits on this
- * shape so uploads avoid being coerced through string-based handling).
+ * The upload URL is either pylon's own receiver (local disk), which needs
+ * the session like any API call, or a presigned storage URL, whose
+ * signature is the credential. The session is never sent to a presigned
+ * URL on another origin.
  *
  * @example
  * ```ts
- * const uploaded = await uploadFile(fileFromInput);
- * console.log(uploaded.url, uploaded.id, uploaded.size);
+ * const photo = await uploadFile(fileFromInput, { visibility: "public" });
+ * await db.insert("Post", { imageUrl: photo.url, caption });
  * ```
  */
 export async function uploadFile(
   input: File | Blob | ArrayBuffer | Uint8Array,
-  options: {
-    filename?: string;
-    contentType?: string;
-    token?: string;
-  } = {}
+  options: UploadFileOptions = {}
 ): Promise<UploadedFile> {
   let body: BodyInit;
+  let size: number;
   let filename = options.filename;
   let contentType = options.contentType;
 
   if (typeof File !== "undefined" && input instanceof File) {
     body = input;
+    size = input.size;
     filename ??= input.name;
     contentType ??= input.type || "application/octet-stream";
   } else if (typeof Blob !== "undefined" && input instanceof Blob) {
     body = input;
+    size = input.size;
     contentType ??= input.type || "application/octet-stream";
   } else if (input instanceof ArrayBuffer) {
     body = input;
+    size = input.byteLength;
   } else {
     // Newer TS lib types refuse `Uint8Array<ArrayBufferLike>` as BodyInit
     // directly even though every runtime accepts it. Hand fetch the
     // underlying ArrayBuffer slice to sidestep the type narrowing.
     const u8 = input as Uint8Array;
     body = u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength) as ArrayBuffer;
+    size = u8.byteLength;
   }
 
   filename ??= "upload";
   contentType ??= "application/octet-stream";
 
-  return pylonFetch<UploadedFile>(
-    {
-      baseUrl: getBaseUrl(),
-      getToken: () => options.token ?? currentAuthToken() ?? undefined,
-    },
-    "/api/files/upload",
+  const transport = {
+    baseUrl: getBaseUrl(),
+    getToken: () => options.token ?? currentAuthToken() ?? undefined,
+  };
+
+  const slot = await pylonFetch<{ uploadUrl: string; assetId: string }>(
+    transport,
+    "/api/files/init",
     {
       method: "POST",
-      body,
-      headers: {
-        "Content-Type": contentType,
-        "X-Filename": filename,
+      json: {
+        filename,
+        mimeType: contentType,
+        size,
+        visibility: options.visibility ?? "private",
       },
     },
   );
+
+  const base = new URL(getBaseUrl() || "http://localhost");
+  const target = new URL(slot.uploadUrl, base);
+  const put =
+    target.origin === base.origin
+      ? await pylonFetchRaw(transport, `${target.pathname}${target.search}`, {
+          method: "PUT",
+          body,
+          headers: { "Content-Type": contentType },
+        })
+      : await fetch(target.toString(), {
+          method: "PUT",
+          body,
+          headers: { "Content-Type": contentType },
+        });
+  if (!put.ok) {
+    throw new PylonHttpError(`Upload of ${filename} failed: ${put.status}`, put.status);
+  }
+
+  return pylonFetch<UploadedFile>(transport, "/api/files/confirm", {
+    method: "POST",
+    json: { assetId: slot.assetId },
+  });
 }
 
 /**
- * Upload via multipart/form-data. Useful when the app needs to pass extra
- * fields alongside the file (captions, categories, etc.), though only the
- * first file part is stored today.
+ * @deprecated The multipart endpoint was removed in pylon 0.3.91 and never
+ * stored the extra fields. This uploads the file with `uploadFile` and
+ * ignores `fields`; send those to your own function instead.
  */
 export async function uploadFileMultipart(
   file: File | Blob,
-  fields: Record<string, string> = {},
-  options: { token?: string } = {}
+  _fields: Record<string, string> = {},
+  options: { token?: string; visibility?: FileVisibility } = {}
 ): Promise<UploadedFile> {
-  const form = new FormData();
-  for (const [k, v] of Object.entries(fields)) {
-    form.append(k, v);
-  }
-  form.append("file", file);
-
-  return pylonFetch<UploadedFile>(
-    {
-      baseUrl: getBaseUrl(),
-      getToken: () => options.token ?? currentAuthToken() ?? undefined,
-    },
-    "/api/files/upload",
-    { method: "POST", body: form },
-  );
+  return uploadFile(file, options);
 }

package/src/uploadFile.test.ts

@@ -0,0 +1,78 @@
+// `uploadFile` used to POST to /api/files/upload, which the runtime removed in
+// 0.3.91 and answers with 410, so every `<FileUpload>` failed. These tests pin
+// the three-step flow and the one credential rule that matters: the session
+// goes to pylon, never to a presigned storage URL on another origin.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { getBaseUrl, uploadFile } from "./index";
+
+type Seen = { url: string; method: string; headers: Record<string, string>; body: unknown };
+
+describe("uploadFile", () => {
+  const realFetch = globalThis.fetch;
+  const realWindow = (globalThis as { window?: unknown }).window;
+  let seen: Seen[];
+  let uploadUrl: string;
+  // Whatever origin the client resolves to. Another test file in the same
+  // process may have configured one, and this test must not set one itself:
+  // configureClient is process-wide and would leak into those tests.
+  let base: string;
+
+  beforeEach(() => {
+    seen = [];
+    uploadUrl = "/api/files/local-put/f_1";
+    (globalThis as { window?: unknown }).window = { location: { origin: "https://app.example" } };
+    base = getBaseUrl();
+    globalThis.fetch = (async (input: any, init: any = {}) => {
+      const url = String(input?.url ?? input);
+      seen.push({ url, method: init.method ?? "GET", headers: (init.headers ?? {}) as Record<string, string>, body: init.body });
+      const json = (value: unknown) => new Response(JSON.stringify(value), { status: 200, headers: { "content-type": "application/json" } });
+      if (url.endsWith("/api/files/init")) return json({ uploadUrl, assetId: "f_1" });
+      if (url.endsWith("/api/files/confirm")) return json({ id: "f_1", url: "/api/files/f_1", size: 5 });
+      return new Response(null, { status: 200 });
+    }) as typeof fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = realFetch;
+    (globalThis as { window?: unknown }).window = realWindow;
+  });
+
+  test("init, put, confirm, with the visibility on init", async () => {
+    const file = new File(["hello"], "cat.png", { type: "image/png" });
+    const out = await uploadFile(file, { visibility: "public", token: "tok" });
+    expect(out).toEqual({ id: "f_1", url: "/api/files/f_1", size: 5 });
+    expect(seen.map((r) => `${r.method} ${r.url}`)).toEqual([
+      `POST ${base}/api/files/init`,
+      `PUT ${base}/api/files/local-put/f_1`,
+      `POST ${base}/api/files/confirm`,
+    ]);
+    expect(JSON.parse(String(seen[0].body))).toEqual({ filename: "cat.png", mimeType: "image/png", size: 5, visibility: "public" });
+    expect(seen[1].headers.Authorization).toBe("Bearer tok");
+    expect(seen[1].headers["Content-Type"]).toBe("image/png");
+    expect(JSON.parse(String(seen[2].body))).toEqual({ assetId: "f_1" });
+  });
+
+  test("defaults to private", async () => {
+    await uploadFile(new Uint8Array([1, 2, 3]), { token: "tok" });
+    expect(JSON.parse(String(seen[0].body))).toEqual({ filename: "upload", mimeType: "application/octet-stream", size: 3, visibility: "private" });
+  });
+
+  test("a presigned URL on another origin gets no session", async () => {
+    uploadUrl = "https://bucket.s3.example/f_1?X-Amz-Signature=abc";
+    await uploadFile(new Blob(["hi"], { type: "text/plain" }), { token: "tok" });
+    expect(seen[1].url).toBe("https://bucket.s3.example/f_1?X-Amz-Signature=abc");
+    expect(seen[1].headers.Authorization).toBeUndefined();
+  });
+
+  test("a refused PUT throws before confirm", async () => {
+    globalThis.fetch = (async (input: any, init: any = {}) => {
+      const url = String(input?.url ?? input);
+      seen.push({ url, method: init.method ?? "GET", headers: {}, body: init.body });
+      if (url.endsWith("/api/files/init")) return new Response(JSON.stringify({ uploadUrl, assetId: "f_1" }), { status: 200 });
+      return new Response("nope", { status: 404 });
+    }) as typeof fetch;
+    await expect(uploadFile(new Uint8Array([1]), { token: "tok" })).rejects.toThrow("failed: 404");
+    expect(seen.some((r) => r.url.endsWith("/api/files/confirm"))).toBe(false);
+  });
+});