gemstack 0.2.5 → 0.3.0

data/templates/resource/controller/test/controllers/%plural%_controller_test.rb.tt

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+class <%= spec.plural_class %>ControllerTest < GemStack::TestCase
+  # Valid values derived from <%= class_name %>'s field declarations — edit freely.
+  def create_<%= spec.file_name %> = <%= class_name %>.create(GemStack::DB::Testing.sample_attributes(<%= class_name %>))
+  def payload = GemStack::DB::Testing.sample_payload(<%= class_name %>)
+<% if spec.action?(:index) -%>
+
+  def test_index
+    create_<%= spec.file_name %>
+    get_json "/api/<%= spec.url_segment %>"
+
+    assert_status 200
+    assert_equal 1, json_body["data"].size
+    assert_equal({ "page" => 1, "per_page" => 25, "total" => 1, "total_pages" => 1 }, json_body["meta"])
+  end
+<% end -%>
+<% if spec.action?(:show) -%>
+
+  def test_show
+    <%= spec.variable %> = create_<%= spec.file_name %>
+    get_json "/api/<%= spec.url_segment %>/#{<%= spec.variable %>.id}"
+
+    assert_status 200
+    assert_equal <%= spec.variable %>.id, json_body["id"]
+  end
+
+  def test_show_missing
+    get_json "/api/<%= spec.url_segment %>/0"
+
+    assert_error 404, "not_found"
+  end
+<% end -%>
+<% if spec.action?(:create) -%>
+
+  def test_create
+    post_json "/api/<%= spec.url_segment %>", payload
+
+    assert_status 201
+    assert <%= class_name %>[json_body["id"]]
+  end
+<% if fields.any?(&:required?) -%>
+
+  def test_create_with_invalid_input
+    post_json "/api/<%= spec.url_segment %>", {}
+
+    assert_error 422, "validation_failed"
+    assert_equal ["is required"], json_body["errors"]["<%= fields.find(&:required?).column %>"]
+  end
+<% end -%>
+<% end -%>
+<% if spec.action?(:update) -%>
+
+  def test_update
+    <%= spec.variable %> = create_<%= spec.file_name %>
+    patch_json "/api/<%= spec.url_segment %>/#{<%= spec.variable %>.id}", payload
+
+    assert_status 200
+    assert_equal <%= spec.variable %>.id, json_body["id"]
+  end
+<% end -%>
+<% if spec.action?(:destroy) -%>
+
+  def test_destroy
+    <%= spec.variable %> = create_<%= spec.file_name %>
+    delete_json "/api/<%= spec.url_segment %>/#{<%= spec.variable %>.id}"
+
+    assert_status 204
+    assert_nil <%= class_name %>[<%= spec.variable %>.id]
+  end
+<% end -%>
+end

data/templates/resource/frontend/frontend/app/%url_segment%/[id]/edit/page.tsx.tt

@@ -0,0 +1,45 @@
+"use client";
+
+import Link from "next/link";
+import { useParams, useRouter } from "next/navigation";
+import { <%= class_name %>Form } from "@/components/<%= spec.url_segment %>/<%= class_name %>Form";
+import { <%= spec.action?(:show) ? "use#{class_name}, " : "" %>useUpdate<%= class_name %> } from "@/lib/queries/<%= spec.url_segment %>";
+
+export default function Edit<%= class_name %>Page() {
+  const { id } = useParams<{ id: string }>();
+  const router = useRouter();
+<% if spec.action?(:show) -%>
+  const <%= spec.variable %> = use<%= class_name %>(id);
+<% end -%>
+  const update = useUpdate<%= class_name %>(id);
+
+  return (
+    <main className="page">
+      <p>
+        <Link href="/<%= spec.url_segment %><%= spec.action?(:show) ? "/${id}" : "" %>">← Back</Link>
+      </p>
+      <h1>Edit <%= spec.human.downcase %></h1>
+<% if spec.action?(:show) -%>
+      {<%= spec.variable %>.isPending && <p className="muted">Loading…</p>}
+      {<%= spec.variable %>.data && (
+        <<%= class_name %>Form
+          <%= spec.variable %>={<%= spec.variable %>.data}
+          submitLabel="Save changes"
+          onSubmit={async (input) => {
+            await update.mutateAsync(input);
+            router.push(`/<%= spec.url_segment %>/${id}`);
+          }}
+        />
+      )}
+<% else -%>
+      <<%= class_name %>Form
+        submitLabel="Save changes"
+        onSubmit={async (input) => {
+          await update.mutateAsync(input);
+          router.push("/<%= spec.url_segment %>");
+        }}
+      />
+<% end -%>
+    </main>
+  );
+}

data/templates/resource/frontend/frontend/app/%url_segment%/[id]/page.tsx.tt

@@ -0,0 +1,49 @@
+"use client";
+
+import Link from "next/link";
+import { useParams<%= spec.action?(:destroy) ? ", useRouter" : "" %> } from "next/navigation";
+import { <%= class_name %>Card } from "@/components/<%= spec.url_segment %>/<%= class_name %>Card";
+import { <%= ["use#{class_name}", (spec.action?(:destroy) ? "useDelete#{class_name}" : nil)].compact.join(", ") %> } from "@/lib/queries/<%= spec.url_segment %>";
+
+export default function <%= class_name %>Page() {
+  const { id } = useParams<{ id: string }>();
+  const <%= spec.variable %> = use<%= class_name %>(id);
+<% if spec.action?(:destroy) -%>
+  const router = useRouter();
+  const remove = useDelete<%= class_name %>();
+
+  async function handleDelete() {
+    if (!window.confirm("Delete this <%= spec.human.downcase %>?")) return;
+    await remove.mutateAsync(id);
+    router.push("/<%= spec.url_segment %>");
+  }
+<% end -%>
+
+  return (
+    <main className="page">
+      <p>
+        <Link href="/<%= spec.url_segment %>">← <%= spec.human_plural %></Link>
+      </p>
+      {<%= spec.variable %>.isPending && <p className="muted">Loading…</p>}
+      {<%= spec.variable %>.isError && <p className="form-error">{<%= spec.variable %>.error.message}</p>}
+      {<%= spec.variable %>.data && (
+        <>
+          <h1><%= spec.human %> #{<%= spec.variable %>.data.id}</h1>
+          <<%= class_name %>Card <%= spec.variable %>={<%= spec.variable %>.data} />
+          <div className="actions">
+<% if spec.action?(:update) -%>
+            <Link className="button" href={`/<%= spec.url_segment %>/${id}/edit`}>
+              Edit
+            </Link>
+<% end -%>
+<% if spec.action?(:destroy) -%>
+            <button className="button button-danger" type="button" onClick={handleDelete} disabled={remove.isPending}>
+              Delete
+            </button>
+<% end -%>
+          </div>
+        </>
+      )}
+    </main>
+  );
+}

data/templates/resource/frontend/frontend/app/%url_segment%/new/page.tsx.tt

@@ -0,0 +1,27 @@
+"use client";
+
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { <%= class_name %>Form } from "@/components/<%= spec.url_segment %>/<%= class_name %>Form";
+import { useCreate<%= class_name %> } from "@/lib/queries/<%= spec.url_segment %>";
+
+export default function New<%= class_name %>Page() {
+  const router = useRouter();
+  const create = useCreate<%= class_name %>();
+
+  return (
+    <main className="page">
+      <p>
+        <Link href="/<%= spec.url_segment %>">← <%= spec.human_plural %></Link>
+      </p>
+      <h1>New <%= spec.human.downcase %></h1>
+      <<%= class_name %>Form
+        submitLabel="Create <%= spec.human.downcase %>"
+        onSubmit={async (input) => {
+          const <%= spec.variable %> = await create.mutateAsync(input);
+          router.push(<%= spec.action?(:show) ? "`/#{spec.url_segment}/${#{spec.variable}.id}`" : "\"/#{spec.url_segment}\"" %>);
+        }}
+      />
+    </main>
+  );
+}

data/templates/resource/frontend/frontend/app/%url_segment%/page.tsx.tt

@@ -0,0 +1,51 @@
+"use client";
+
+import Link from "next/link";
+import { useSearchParams } from "next/navigation";
+import { Suspense } from "react";
+import { <%= class_name %>Table } from "@/components/<%= spec.url_segment %>/<%= class_name %>Table";
+import { use<%= spec.plural_class %> } from "@/lib/queries/<%= spec.url_segment %>";
+
+export default function <%= spec.plural_class %>Page() {
+  return (
+    <main className="page">
+      <header className="page-header">
+        <h1><%= spec.human_plural %></h1>
+<% if spec.action?(:create) -%>
+        <Link className="button" href="/<%= spec.url_segment %>/new">
+          New <%= spec.human.downcase %>
+        </Link>
+<% end -%>
+      </header>
+      {/* useSearchParams needs a Suspense boundary for static rendering. */}
+      <Suspense>
+        <<%= spec.plural_class %>List />
+      </Suspense>
+    </main>
+  );
+}
+
+// The current page lives in the URL (?page=2), so it survives reloads and can be shared.
+function <%= spec.plural_class %>List() {
+  const page = Math.max(1, Number(useSearchParams().get("page")) || 1);
+  const <%= spec.plural %> = use<%= spec.plural_class %>(page);
+
+  if (<%= spec.plural %>.isPending) return <p className="muted">Loading…</p>;
+  if (<%= spec.plural %>.isError) return <p className="form-error">Could not load <%= spec.human_plural.downcase %>: {<%= spec.plural %>.error.message}</p>;
+
+  const { data, meta } = <%= spec.plural %>.data;
+  return (
+    <>
+      <<%= class_name %>Table <%= spec.plural %>={data} />
+      {meta.total_pages > 1 && (
+        <nav className="actions" aria-label="Pagination">
+          {page > 1 && <Link href={`?page=${page - 1}`}>← Previous</Link>}
+          <span className="muted">
+            Page {meta.page} of {meta.total_pages}
+          </span>
+          {page < meta.total_pages && <Link href={`?page=${page + 1}`}>Next →</Link>}
+        </nav>
+      )}
+    </>
+  );
+}

data/templates/resource/frontend/frontend/components/%url_segment%/%class_name%Card.tsx.tt

@@ -0,0 +1,15 @@
+import { display } from "@/lib/format";
+import type { <%= class_name %> } from "@/lib/api/generated";
+
+export function <%= class_name %>Card({ <%= spec.variable %> }: { <%= spec.variable %>: <%= class_name %> }) {
+  return (
+    <dl className="card">
+<% fields.each do |field| -%>
+      <dt><%= field.label %></dt>
+      <dd>{display(<%= spec.variable %>.<%= field.column %>)}</dd>
+<% end -%>
+      <dt>Created</dt>
+      <dd>{new Date(<%= spec.variable %>.created_at).toLocaleString()}</dd>
+    </dl>
+  );
+}

data/templates/resource/frontend/frontend/components/%url_segment%/%class_name%Form.tsx.tt

@@ -0,0 +1,98 @@
+"use client";
+
+import { useState, type ChangeEvent, type FormEvent } from "react";
+import { ApiError } from "@/lib/gemstack/client";
+import type { FieldErrors } from "@/lib/format";
+import type { <%= class_name %>, <%= input_type %> } from "@/lib/api/generated";
+
+type Values = {
+<% fields.each do |field| -%>
+  <%= field.column %>: <%= ts_value_type(field) %>;
+<% end -%>
+};
+
+function initialValues(record?: <%= class_name %>): Values {
+  return {
+<% fields.each do |field| -%>
+    <%= field.column %>: <%= form_initial(field) %>,
+<% end -%>
+  };
+}
+<% if uses_json? -%>
+
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+<% end -%>
+
+// Form values are strings; the API validates and coerces them (see <%= class_name %>.input_schema).
+function toInput(values: Values): <%= input_type %> {
+  return {
+<% fields.each do |field| -%>
+    <%= field.column %>: <%= form_output(field) %>,
+<% end -%>
+  } as unknown as <%= input_type %>;
+}
+
+export function <%= class_name %>Form({
+  <%= spec.variable %>,
+  submitLabel,
+  onSubmit,
+}: {
+  <%= spec.variable %>?: <%= class_name %>;
+  submitLabel: string;
+  onSubmit: (input: <%= input_type %>) => Promise<unknown>;
+}) {
+  const [values, setValues] = useState<Values>(() => initialValues(<%= spec.variable %>));
+  const [errors, setErrors] = useState<FieldErrors>({});
+  const [formError, setFormError] = useState<string | null>(null);
+  const [pending, setPending] = useState(false);
+
+  const set = (key: keyof Values) => (event: ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => {
+    const target = event.target;
+    const value = target instanceof HTMLInputElement && target.type === "checkbox" ? target.checked : target.value;
+    // Checkboxes give booleans, other inputs strings — matching each field's type in Values.
+    setValues((current) => ({ ...current, [key]: value }) as Values);
+  };
+
+  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    setPending(true);
+    setErrors({});
+    setFormError(null);
+    try {
+      await onSubmit(toInput(values));
+    } catch (error) {
+      if (error instanceof ApiError) {
+        setErrors(error.errors);
+        setFormError(Object.keys(error.errors).length ? null : error.message);
+      } else {
+        setFormError("Something went wrong. Please try again.");
+      }
+    } finally {
+      setPending(false);
+    }
+  }
+
+  return (
+    <form className="form" onSubmit={handleSubmit} noValidate>
+      {formError && <p className="form-error" role="alert">{formError}</p>}
+<% fields.each do |field| -%>
+      <div className="field">
+        <label htmlFor="<%= field.column %>"><%= field.label %></label>
+        <%= form_control(field) %>
+        {errors.<%= field.column %>?.map((message) => (
+          <p key={message} className="field-error">{message}</p>
+        ))}
+      </div>
+<% end -%>
+      <button className="button" type="submit" disabled={pending}>
+        {pending ? "Saving…" : submitLabel}
+      </button>
+    </form>
+  );
+}

data/templates/resource/frontend/frontend/components/%url_segment%/%class_name%Table.tsx.tt

@@ -0,0 +1,36 @@
+import Link from "next/link";
+import { display } from "@/lib/format";
+import type { <%= class_name %> } from "@/lib/api/generated";
+
+export function <%= class_name %>Table({ <%= spec.plural %> }: { <%= spec.plural %>: <%= class_name %>[] }) {
+  if (<%= spec.plural %>.length === 0) return <p className="muted">No <%= spec.human_plural.downcase %> yet.</p>;
+
+  return (
+    <table className="table">
+      <thead>
+        <tr>
+<% table_fields.each do |field| -%>
+          <th><%= field.label %></th>
+<% end -%>
+<% if spec.action?(:show) -%>
+          <th aria-label="Actions" />
+<% end -%>
+        </tr>
+      </thead>
+      <tbody>
+        {<%= spec.plural %>.map((<%= spec.variable %>) => (
+          <tr key={<%= spec.variable %>.id}>
+<% table_fields.each do |field| -%>
+            <td>{display(<%= spec.variable %>.<%= field.column %>)}</td>
+<% end -%>
+<% if spec.action?(:show) -%>
+            <td>
+              <Link href={`/<%= spec.url_segment %>/${<%= spec.variable %>.id}`}>View</Link>
+            </td>
+<% end -%>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}

data/templates/resource/frontend/frontend/lib/format.ts

@@ -0,0 +1,12 @@
+// Display helpers shared by generated components.
+
+/** Human-readable text for any API value. */
+export function display(value: unknown): string {
+  if (value === null || value === undefined || value === "") return "—";
+  if (typeof value === "boolean") return value ? "Yes" : "No";
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}
+
+/** Field errors from an ApiError, keyed by attribute name. */
+export type FieldErrors = Record<string, string[]>;

data/templates/resource/frontend/frontend/lib/queries/%url_segment%.ts.tt

@@ -0,0 +1,64 @@
+"use client";
+
+// TanStack Query hooks for <%= spec.human_plural.downcase %>, built on the generated API client.
+import { keepPreviousData, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { <%= spec.client_name %> } from "@/lib/api/generated";
+import type { <%= [class_name, (spec.action?(:create) ? "#{class_name}Input" : nil), (spec.action?(:update) ? "#{class_name}UpdateInput" : nil)].compact.join(", ") %> } from "@/lib/api/generated";
+
+export const <%= spec.variable %>Keys = {
+  all: ["<%= spec.plural %>"] as const,
+  detail: (id: string | number) => ["<%= spec.plural %>", String(id)] as const,
+};
+<% if spec.action?(:index) -%>
+
+// perPage: records per page; omit it to use the API's default (config.http.pagination.per_page).
+export function use<%= spec.plural_class %>(page = 1, perPage?: number) {
+  return useQuery({
+    queryKey: [...<%= spec.variable %>Keys.all, "page", page, perPage],
+    queryFn: () => <%= spec.client_name %>.list({ page, per_page: perPage }),
+    placeholderData: keepPreviousData, // keep the current page visible while the next one loads
+  });
+}
+<% end -%>
+<% if spec.action?(:show) -%>
+
+export function use<%= class_name %>(id: string | number) {
+  return useQuery({ queryKey: <%= spec.variable %>Keys.detail(id), queryFn: () => <%= spec.client_name %>.get(id) });
+}
+<% end -%>
+<% if spec.action?(:create) -%>
+
+export function useCreate<%= class_name %>() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (data: <%= class_name %>Input) => <%= spec.client_name %>.create(data),
+    onSuccess: (<%= spec.variable %>: <%= class_name %>) => {
+      queryClient.setQueryData(<%= spec.variable %>Keys.detail(<%= spec.variable %>.id), <%= spec.variable %>);
+      return queryClient.invalidateQueries({ queryKey: <%= spec.variable %>Keys.all });
+    },
+  });
+}
+<% end -%>
+<% if spec.action?(:update) -%>
+
+export function useUpdate<%= class_name %>(id: string | number) {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (data: <%= class_name %>UpdateInput) => <%= spec.client_name %>.update(id, data),
+    onSuccess: (<%= spec.variable %>: <%= class_name %>) => {
+      queryClient.setQueryData(<%= spec.variable %>Keys.detail(id), <%= spec.variable %>);
+      return queryClient.invalidateQueries({ queryKey: <%= spec.variable %>Keys.all });
+    },
+  });
+}
+<% end -%>
+<% if spec.action?(:destroy) -%>
+
+export function useDelete<%= class_name %>() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (id: string | number) => <%= spec.client_name %>.delete(id),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: <%= spec.variable %>Keys.all }),
+  });
+}
+<% end -%>

data/templates/resource/migration/db/migrations/%timestamp%_create_%table%.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  change do
+    create_table(:<%= spec.table %>) do
+      primary_key :id, type: :Bignum
+<% fields.each do |field| -%>
+      <%= migration_column(field) %>
+<% end -%>
+      column :created_at, :timestamptz, null: false
+      column :updated_at, :timestamptz, null: false
+<% fields.select { |f| f.index && !f.unique }.each do |field| -%>
+
+      index :<%= field.column %>
+<% end -%>
+    end
+  end
+end

data/templates/resource/model/app/models/%file_name%.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < ApplicationModel
+<% fields.each do |field| -%>
+  <%= model_field(field) %>
+<% end -%>
+<% fields.select(&:unique).each do |field| -%>
+
+  validates :<%= field.column %>, uniqueness: true
+<% end -%>
+<% spec.references.each do |field| -%>
+
+  belongs_to :<%= field.name %>
+<% end -%>
+end

data/templates/resource/model/test/models/%file_name%_test.rb.tt

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+class <%= class_name %>Test < GemStack::TestCase
+  def sample = GemStack::DB::Testing.sample_attributes(<%= class_name %>)
+
+  def test_valid_with_sample_attributes
+    <%= spec.variable %> = <%= class_name %>.new(sample)
+
+    assert_predicate <%= spec.variable %>, :valid?, <%= spec.variable %>.errors.to_h.inspect
+  end
+
+  def test_create
+    <%= spec.variable %> = <%= class_name %>.create(sample)
+
+    assert <%= spec.variable %>.id
+    assert <%= spec.variable %>.created_at
+  end
+<% fields.select(&:required?).each do |field| -%>
+
+  def test_requires_<%= field.column %>
+    <%= spec.variable %> = <%= class_name %>.new(sample.except(:<%= field.column %>))
+
+    refute_predicate <%= spec.variable %>, :valid?
+    assert_includes <%= spec.variable %>.errors[:<%= field.column %>], "is required"
+  end
+<% end -%>
+end

data/templates/resource/serializer/app/serializers/%file_name%_serializer.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# What the API returns for a <%= class_name %>. Only listed attributes are exposed;
+# their types (from <%= class_name %>'s fields) drive the generated TypeScript types.
+class <%= class_name %>Serializer < ApplicationSerializer
+  attributes :id, <%= fields.map { |f| ":#{f.column}" }.join(", ") %>, :created_at, :updated_at
+end

data/templates/storage/app/controllers/uploads_controller.rb.tt

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# POST /api/uploads — step 1 of a direct upload (frontend/lib/upload.ts):
+# validates the file's type and size and returns a short-lived URL the
+# browser PUTs the file to. Save the returned signed_id on your record:
+#
+#   product.update(image_key: GemStack::Storage.key_for_signed_id(input[:image]))
+#   GemStack::Storage.url(product.image_key)   # signed download URL
+#
+# Allowed types and the size limit: config.storage (docs/storage.md).
+class UploadsController < ApplicationController
+<% if auth? -%>
+  before :require_login
+<% else -%>
+  # Anyone can upload until you add authentication (gemstack add auth), then:
+  # before :require_login
+<% end -%>
+  rate_limit to: 60, within: 3600, only: :create if respond_to?(:rate_limit)
+
+  accepts :create do
+    required :filename, :string, max_length: 255
+    required :content_type, :string, max_length: 100
+    required :byte_size, :integer, gt: 0
+  end
+  returns :create, UploadSerializer
+
+  def create
+    upload = GemStack::Storage.direct_upload(**input.slice(:filename, :content_type, :byte_size))
+    result = UploadSerializer::Result.new(signed_id: upload[:signed_id], url: upload[:url],
+                                          http_method: upload[:method], headers: upload[:headers])
+    render result, status: :created, serializer: UploadSerializer
+  end
+end

data/templates/storage/app/serializers/upload_serializer.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Where and how the browser sends the file (see UploadsController).
+class UploadSerializer < ApplicationSerializer
+  Result = Data.define(:signed_id, :url, :http_method, :headers)
+
+  attribute :signed_id, :string
+  attribute :url, :string
+  attribute(:method, :string) { |upload| upload.http_method }
+  attribute :headers, :json
+end

data/templates/storage/frontend/lib/upload.ts

@@ -0,0 +1,52 @@
+"use client";
+
+// Direct uploads (generated by `gemstack add storage`): the file goes from the
+// browser straight to storage (S3, or the Ruby disk endpoint in development).
+//
+//   const { signedId } = await uploadFile(file, { onProgress: (p) => setProgress(p) });
+//   await products.update(id, { image: signedId });
+import { useMutation } from "@tanstack/react-query";
+import { uploads } from "@/lib/api/generated";
+
+export interface UploadResult {
+  /** Send this to the API to attach the file to a record. */
+  signedId: string;
+}
+
+export interface UploadOptions {
+  /** 0–1 while uploading. */
+  onProgress?: (fraction: number) => void;
+  signal?: AbortSignal;
+}
+
+export async function uploadFile(file: File, options: UploadOptions = {}): Promise<UploadResult> {
+  const upload = await uploads.create({
+    filename: file.name,
+    content_type: file.type || "application/octet-stream",
+    byte_size: file.size,
+  });
+  await send(upload.url, upload.method, upload.headers as Record<string, string>, file, options);
+  return { signedId: upload.signed_id };
+}
+
+// XMLHttpRequest rather than fetch: it reports upload progress.
+function send(url: string, method: string, headers: Record<string, string>, file: File, options: UploadOptions) {
+  return new Promise<void>((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open(method, url);
+    for (const [name, value] of Object.entries(headers)) xhr.setRequestHeader(name, value);
+    xhr.upload.onprogress = (event) => {
+      if (event.lengthComputable) options.onProgress?.(event.loaded / event.total);
+    };
+    xhr.onload = () => (xhr.status < 300 ? resolve() : reject(new Error(`Upload failed (HTTP ${xhr.status})`)));
+    xhr.onerror = () => reject(new Error("Upload failed: network error"));
+    xhr.onabort = () => reject(new DOMException("Upload aborted", "AbortError"));
+    options.signal?.addEventListener("abort", () => xhr.abort());
+    xhr.send(file);
+  });
+}
+
+/** uploadFile as a TanStack Query mutation: const upload = useUpload(); upload.mutateAsync(file). */
+export function useUpload(options: Omit<UploadOptions, "signal"> = {}) {
+  return useMutation({ mutationFn: (file: File) => uploadFile(file, options) });
+}