naro-js 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # naro-js
 
-Auth and data for your [Naro](https://naro.sh) project, from the browser or
+Auth, data and files for your [Naro](https://naro.sh) project, from the browser or
 the server. A project's backend brings its own database; this client signs
 users in and reads and writes it through the project's policies. No SQL, no
 database credentials, no dependencies.
@@ -78,6 +78,45 @@ await naro.from("posts").delete().eq("id", 10);
 - Admin accounts, closed sign-ups, sign-in by username and the password
   length — see [Admin accounts and closed sign-ups](#admin-accounts-and-closed-sign-ups).
 - Email and social sign-in — see [Sign-in flows](#sign-in-flows).
+- Files — see [Storage](#storage).
+
+## Policies
+
+What a request may do is decided by the table's policies — Postgres's
+row-level security, as in Supabase. A table without a policy refuses every
+anon and signed-in request (only the service key gets through), so write a
+table's policies in the migration that creates it: `create policy` after the
+`create table`, in the same file. `naro db push` applies them with the table,
+all or nothing.
+
+```sql
+-- migrations/0002_todos.sql: each signed-in user reads and changes their own rows.
+create table todos (
+  id integer primary key,
+  user_id uuid not null,
+  title text not null
+);
+create policy "own rows" on todos for all to authenticated
+  using ((select auth.uid()) = user_id)
+  with check ((select auth.uid()) = user_id);
+
+-- migrations/0003_posts.sql: anyone reads, signed in or not.
+create table posts (id integer primary key, title text not null);
+create policy "read" on posts for select to anon, authenticated using (true);
+
+-- migrations/0004_reports.sql: an app only its admins sign in to. First run
+-- naro backend auth signups off and create the admin accounts: authenticated
+-- then means exactly those accounts.
+create table reports (id integer primary key, body text not null);
+create policy "admins" on reports for all to authenticated using (true) with check (true);
+```
+
+A request no policy lets through, and a written row that fails a check,
+answer `403 PERMISSION_DENIED`; rows a policy's `using` does not pass are left
+out without an error. The `naro-cli` README lists what a
+migration accepts and refuses (`DISABLE ROW LEVEL SECURITY`, `GRANT`,
+`REVOKE` and `ALTER POLICY` are refused), the warnings it answers with, and
+`naro policy set`, a shorthand for the common rules.
 
 ## Admin accounts and closed sign-ups
 
@@ -413,4 +452,118 @@ await naro.from("posts").select().contains("tags", ["a", "b"]);
 - Limits: groups nest 4 deep (`not` counts); one request holds at most 100
   conditions, 4 of them `contains` / `containedBy` / `overlaps`; one
   statement binds at most 100 values (a select's limit and offset are two of
-  them) and compiles to at most 100,000 bytes of SQL.
+  them) and compiles to at most 100,000 bytes of SQL. A `like` or `ilike`
+  pattern is at most 50 bytes of UTF-8, which is D1's limit; in `like`, a
+  literal `?` or `[` counts as 3. A longer one is `400 INVALID_QUERY` before
+  the database is asked.
+
+## Storage
+
+Files your users upload — avatars, attachments, documents — go in the
+project's Storage: Cloudflare R2 behind the same URL, under policies on
+`storage.objects` written as in Supabase. Turn it on with
+`naro storage enable` (the backend must be on), make buckets with
+`naro storage bucket create avatars --public`, and write the policies in a
+migration that `naro db push` applies:
+
+```sql
+create policy "avatars are readable" on storage.objects
+  for select to public using (bucket_id = 'avatars');
+create policy "upload into own folder" on storage.objects
+  for insert to authenticated
+  with check (bucket_id = 'avatars' and (storage.foldername(name))[1] = auth.uid()::text);
+```
+
+```ts
+const avatars = naro.storage.from("avatars");
+await avatars.upload(`${user.id}/me.png`, file, { upsert: true });
+const { data: image } = avatars.getPublicUrl(`${user.id}/me.png`); // no request
+const { data: files } = await avatars.list(user.id, { limit: 20 });
+await avatars.remove([`${user.id}/old.png`]);
+const { data: link } = await naro.storage
+  .from("docs")
+  .createSignedUrl("team-1/plan.pdf", 600);
+```
+
+- `upload`, `update`, `download`, `info`, `exists`, `list`, `remove`,
+  `createSignedUrl` and `getPublicUrl` take supabase-js's arguments and
+  answer its shapes (`FileObject` in snake_case), as `{ data, error }`.
+  One exception: supabase-js's `info` answers a camelCase object
+  (`bucketId`, `createdAt`, `size`, `contentType`, …); naro-js's `info`
+  answers the same snake_case `FileObject` as `list`, with the size and type
+  in `metadata.size` and `metadata.mimetype`.
+- An upload sends the file's own bytes, typed as the file is (`Blob.type`,
+  or `application/octet-stream`; a string is `text/plain;charset=utf-8`).
+  The body is a `Blob`, `File`, `ArrayBuffer`, typed array or string — not
+  a stream or `FormData`, and not a buffer transferred away (detached),
+  which has no bytes left: `INVALID_BODY`.
+- One request carries 50 MiB. A larger body goes in parts by itself, up to
+  the plan's largest object: 16–64 MiB parts, four at a time, each tried
+  again up to three times after `NETWORK_ERROR`, a `5xx` or
+  `OBJECT_RATE_LIMITED` (waiting 1, 2, then 4 seconds, or the seconds the
+  429 says) — not after `507 STORAGE_QUOTA_EXCEEDED`, which lasts until
+  files are deleted. A part that still fails fails the upload with its
+  error, and the upload is called off. The last step is never tried again: if its
+  answer is lost (`NETWORK_ERROR`), ask `info(path)` whether the file is
+  there; if the backend refuses it, the upload is called off too and the
+  refusal is the answer. A part answered `UPLOAD_NOT_FOUND` belongs to an
+  upload that has ended — one left unsent for about an hour has. An upload in
+  parts must finish within 24 hours of its start (R2 ends unfinished
+  multipart uploads after a day). Replacing a file in parts (`update`, or
+  `upload` with `upsert` over a file that is there) needs room in the
+  project's capacity for the old file and the new one until it completes: if
+  the two together are over it, the upload answers
+  `507 STORAGE_QUOTA_EXCEEDED` before any part is sent.
+- `onProgress: (sentBytes, totalBytes) => void` is called after each part
+  of an upload over 50 MiB, the last time with both the same. An upload of
+  50 MiB or less is one request and does not call it. A `File` is sliced
+  into the parts, never read whole first. What the callback throws — or an
+  `async` one rejects with — does not stop the upload.
+
+- `signal: AbortSignal` stops an upload (`upload` and `update`): what has
+  not been answered yet is called off, and the upload answers `ABORTED`
+  ("The upload was stopped before it finished."). An upload in parts is
+  called off on the backend too — no part starts after the signal, and
+  `onProgress` is not called again — so its name and the space it reserved
+  are free at once, not after the hour its lock lasts. Its first step is
+  never cut short (a signal during it is acted on once it answers), and once
+  its last step is sent the signal stops nothing: that step's answer is the
+  upload's. A signal already aborted sends nothing. A page closed or a
+  network lost mid-upload sends no abort: the name waits for the lock.
+
+```ts
+const stop = new AbortController();
+cancelButton.onclick = () => stop.abort();
+await naro.storage.from("videos").upload(`${user.id}/talk.mp4`, file, {
+  onProgress: (sent, total) => setPercent(Math.round((sent / total) * 100)),
+  signal: stop.signal,
+});
+```
+
+- A `contentType` or `cacheControl` no header can carry (a CR, LF or NUL
+  inside, or a character past U+00FF) is answered before a request, as the
+  backend answers one it cannot read: `INVALID_CONTENT_TYPE`, and
+  `INVALID_REQUEST` with `details.path` `cache-control`.
+- supabase-js's `upload(path, file)` sends `multipart/form-data`, which Naro
+  refuses with `400 INVALID_REQUEST`. Without naro-js, send the file's bytes
+  as the body of `POST /_naro/v1/storage/object/<bucket>/<path>`.
+- Refused before a request, with the backend's own words (`INVALID_PATH`):
+  an empty path, a `/` at either end, `//`, a `.` or `..` segment, a lone
+  surrogate (`is not valid UTF-8`: no URL can carry it), and a bucket named
+  `""`, `.`, `..`, with a lone surrogate or a word the storage routes use
+  (`The bucket name is not valid.`). Everything else is the backend's to
+  check.
+- `exists` answers `false` for `OBJECT_NOT_FOUND` and passes every other
+  error on. `getPublicUrl` makes no request and answers `{ data, error }`.
+- `objectRoute(bucket, path)` names an object the way the client does:
+  `{ ok: true, encoded }` with `<bucket>/<path>` as the object routes carry
+  it (each segment `encodeURIComponent`-ed), or `{ ok: false, error }` with
+  the client's own `INVALID_PATH` (type `ObjectRouteResult`). A tool that
+  streams an object itself builds `/_naro/v1/storage/object/<encoded>` from
+  it and gets the URL and the refusals the client would — `naro storage cp`
+  downloads that way.
+- `OBJECT_RATE_LIMITED` and `STORAGE_OPS_QUOTA_EXCEEDED` carry
+  `details.retryAfter`, in seconds.
+- Not yet: `move`, `copy`, `createSignedUrls`, `list`'s `search`, resuming
+  an upload in another session, and bucket methods (buckets are made with
+  `naro storage bucket`).

package/dist/client.d.ts

@@ -2,6 +2,7 @@ import { AuthClient } from "./auth/client.js";
 import { type AuthStorage } from "./auth/storage.js";
 import { type FetchLike } from "./http.js";
 import { TableBuilder } from "./query/builder.js";
+import { StorageClient } from "./storage/client.js";
 import type { DatabaseShape, InsertOf, RowOf, TableName, TablesOf, UntypedDatabase, UpdateOf } from "./types.js";
 type CommonOptions = {
     /**
@@ -51,6 +52,12 @@ export declare class NaroClient<Database extends DatabaseShape<Database>> {
      * service key, `auth.admin` manages users.
      */
     readonly auth: AuthClient;
+    /**
+     * Files in the project's Naro Storage (first-release design 2026-10-06
+     * §8.1): `storage.from(bucket)` uploads, downloads, lists and removes
+     * them, as supabase-js does.
+     */
+    readonly storage: StorageClient;
     constructor(options: ClientOptions);
     /** Start a query on `table`: `.select()`, `.insert()`, `.update()` or `.delete()`. */
     from<Table extends TableName<Database>>(table: Table): TableBuilder<RowOf<TablesOf<Database>[Table]>, InsertOf<TablesOf<Database>[Table]>, UpdateOf<TablesOf<Database>[Table]>>;

package/dist/errors.d.ts

@@ -25,6 +25,11 @@ export declare function networkError(cause: unknown): NaroError;
  * code exchange a page runs on load (PR #68 review 10). It is called off.
  */
 export declare function requestTimeout(ms: number): NaroError;
+/**
+ * An upload the caller's `signal` stopped (PR #111 review r1): what was not
+ * answered yet was called off. Never tried again.
+ */
+export declare function uploadAborted(): NaroError;
 /** An answer, but not one a Naro worker gives: HTML, empty, or the wrong shape. */
 export declare function invalidResponse(status: number): NaroError;
 /**

package/dist/http.d.ts

@@ -15,7 +15,7 @@ export type HttpConfig = {
     tokens: TokenStore;
 };
 export type CallOptions = {
-    method: "GET" | "POST" | "DELETE";
+    method: "GET" | "POST" | "PUT" | "DELETE";
     /** Below `/_naro/v1`, e.g. `/data/query`. */
     path: string;
     /** Sent as JSON. */
@@ -53,10 +53,44 @@ export type CallResult = {
  * §11.1), but only if it is still the token this request carried.
  */
 export declare function call(config: HttpConfig, options: CallOptions): Promise<CallResult>;
+export type SendOptions = {
+    method: "GET" | "POST" | "PUT";
+    /** Below `/_naro/v1`, e.g. `/storage/object/avatars/me.png`. */
+    path: string;
+    headers?: Record<string, string>;
+    body?: BodyInit;
+    withToken: boolean;
+    /**
+     * An upload's `signal` (PR #111 review r1): it calls the request off until
+     * its answer comes — ABORTED, not NETWORK_ERROR — and never the reading
+     * of an answer that came, which may be a success.
+     */
+    signal?: AbortSignal | undefined;
+};
+/**
+ * A failure carries the answer's HTTP status, or null when nothing answered
+ * (NETWORK_ERROR): a multipart upload tries a part again on a 5xx, whatever
+ * the body said (Storage 3-1f, plan C7).
+ */
+export type SendResult = {
+    error: NaroError;
+    status: number | null;
+} | {
+    error: null;
+    response: Response;
+};
+/**
+ * A request whose body or answer is not JSON (Storage, first-release design
+ * 2026-10-06 §8.1): an upload's bytes go as they are, a download's come
+ * back unread. The same `apikey`, bearer token and no cookies as `call`;
+ * a failing answer is read the way `call` reads one — the worker's error
+ * envelope, or INVALID_RESPONSE — and every case resolves.
+ */
+export declare function send(config: HttpConfig, options: SendOptions): Promise<SendResult>;
 /**
- * The worker's two 429s. `RATE_LIMITED` is the sign-in routes' per-address
- * limiter; `WRITE_QUOTA_EXCEEDED` (PR C) is the project over its daily
- * database write limit — Data API writes, sign-up and creating or deleting
- * users wait for 00:00 UTC, reads still work.
+ * The worker's 429s that say how long to wait. `RATE_LIMITED` is the
+ * sign-in routes' per-address limiter; `WRITE_QUOTA_EXCEEDED` (PR C) is the
+ * project over its daily database write limit — Data API writes, sign-up
+ * and creating or deleting users wait for 00:00 UTC, reads still work.
  */
 export declare const RETRY_AFTER_CODES: ReadonlySet<string>;

package/dist/index.d.ts

@@ -4,6 +4,9 @@ export type { AuthClient } from "./auth/client.js";
 export type { AuthStorage } from "./auth/storage.js";
 export type { NaroError } from "./errors.js";
 export type { FetchLike } from "./http.js";
+export type { StorageClient, StorageFileApi } from "./storage/client.js";
+export { objectRoute, type Encoded as ObjectRouteResult, } from "./storage/path.js";
+export type { DownloadOption, FileObject, FolderEntry, ListOptions, UpdateOptions, UploadBody, UploadOptions, UploadResult, } from "./storage/types.js";
 export type { ArrayValues, FilterGroup, FilterGroupCallback, InsertBuilder, MatchQuery, MutationBuilder, RawFilterValue, SelectBuilder, TableBuilder, } from "./query/builder.js";
 export { quoteFilterValue, type FilterOperatorName } from "./query/filters.js";
 export type { AdminUser, AdminUserAttributes, AdminUserListResponse, AdminUserResponse, AuthActionResponse, AuthErrorCode, AuthFlowType, AuthResponse, DatabaseShape, EmailRedirectOptions, OAuthProvider, OAuthResponse, SignInWithOAuthOptions, UrlSessionResponse, UserAttributes, GenericTable, GenericView, NaroResponse, OrderOptions, PageParams, Session, SessionResponse, SignInCredentials, SignOutResponse, SignUpCredentials, UntypedDatabase, User, UserResponse, } from "./types.js";

package/dist/index.js

@@ -14,6 +14,12 @@ function requestTimeout(ms) {
     message: `The Naro backend did not answer within ${String(Math.round(ms / 1e3))} seconds. Check the network and try again.`
   };
 }
+function uploadAborted() {
+  return {
+    code: "ABORTED",
+    message: "The upload was stopped before it finished."
+  };
+}
 function invalidResponse(status) {
   return {
     code: "INVALID_RESPONSE",
@@ -158,15 +164,79 @@ async function call(config, options) {
   const answer = { status, headers: responseHeaders, body, token };
   const error = errorFromBody(status, body);
   if (error === null) return { error: null, answer };
+  return {
+    error: await settled(config, error, responseHeaders, token),
+    answer
+  };
+}
+async function settled(config, error, headers, token) {
   if (error.code === "INVALID_SESSION" && token !== null)
     await config.tokens.clearIf(token);
-  if (RETRY_AFTER_CODES.has(error.code))
-    return { error: withRetryAfter(error, responseHeaders), answer };
-  return { error, answer };
+  return RETRY_AFTER_CODES.has(error.code) ? withRetryAfter(error, headers) : error;
+}
+async function send(config, options) {
+  const token = options.withToken ? await config.tokens.get() : null;
+  const headers = {
+    ...options.headers,
+    apikey: config.apiKey
+  };
+  if (token !== null) headers.Authorization = `Bearer ${token}`;
+  const init = {
+    method: options.method,
+    headers,
+    credentials: "omit"
+  };
+  if (options.body !== void 0) init.body = options.body;
+  const { signal } = options;
+  if (signal?.aborted) return { error: uploadAborted(), status: null };
+  const controller = signal ? new AbortController() : null;
+  const stop = () => controller?.abort();
+  if (controller) init.signal = controller.signal;
+  signal?.addEventListener("abort", stop);
+  let response;
+  try {
+    const fetchImpl = config.fetch ?? globalThis.fetch;
+    response = await fetchImpl(
+      `${config.baseUrl}/_naro/v1${options.path}`,
+      init
+    );
+  } catch (error2) {
+    return {
+      error: signal?.aborted ? uploadAborted() : networkError(error2),
+      status: null
+    };
+  } finally {
+    signal?.removeEventListener("abort", stop);
+  }
+  const { status } = response;
+  if (status >= 200 && status < 300) return { error: null, response };
+  let text;
+  try {
+    text = await response.text();
+  } catch (error2) {
+    return { error: networkError(error2), status: null };
+  }
+  let body;
+  if (text.trim() !== "") {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      return { error: invalidResponse(status), status };
+    }
+  }
+  const error = errorFromBody(status, body) ?? invalidResponse(status);
+  return {
+    error: await settled(config, error, response.headers, token),
+    status
+  };
 }
 var RETRY_AFTER_CODES = /* @__PURE__ */ new Set([
   "RATE_LIMITED",
-  "WRITE_QUOTA_EXCEEDED"
+  "WRITE_QUOTA_EXCEEDED",
+  // Storage (original spec §13): one object written twice within a second
+  // (`x-retry-after: 1`), and the daily operation limit (3-1d).
+  "OBJECT_RATE_LIMITED",
+  "STORAGE_OPS_QUOTA_EXCEEDED"
 ]);
 function withRetryAfter(error, headers) {
   const header = headers.get("x-retry-after")?.trim() ?? "";
@@ -1756,6 +1826,545 @@ var TableBuilder = class {
   }
 };
 
+// src/storage/answer.ts
+function fail(error) {
+  return { data: null, error };
+}
+var isUploadResult = (value) => isRecord(value) && typeof value.id === "string" && typeof value.path === "string" && typeof value.fullPath === "string";
+function dataOf2(status, body, guard) {
+  if (isRecord(body) && Object.hasOwn(body, "data") && guard(body.data))
+    return { data: body.data, error: null };
+  return fail(invalidResponse(status));
+}
+async function readJson(response, guard) {
+  let text;
+  try {
+    text = await response.text();
+  } catch (error) {
+    return fail(networkError(error));
+  }
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return fail(invalidResponse(response.status));
+  }
+  return dataOf2(response.status, body, guard);
+}
+
+// src/storage/multipart.ts
+var ROUTE = "/storage/upload/multipart";
+var CONCURRENCY = 4;
+var ATTEMPTS = 4;
+var BACKOFF_MS = [1e3, 2e3, 4e3];
+var UPLOAD_ID = /^[\w-][\w.-]*$/;
+var positive = (value) => typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+var planFor = (size) => (value) => isRecord(value) && typeof value.uploadId === "string" && UPLOAD_ID.test(value.uploadId) && positive(value.partSize) && positive(value.partCount) && (value.partCount - 1) * value.partSize < size && value.partCount * value.partSize >= size;
+var partAnswer = (n) => (value) => isRecord(value) && value.partNumber === n && typeof value.etag === "string" && value.etag !== "";
+var retryable = (error, status) => error.code === "NETWORK_ERROR" || error.code === "OBJECT_RATE_LIMITED" || status !== null && status >= 500 && error.code !== "STORAGE_QUOTA_EXCEEDED";
+function waitAfter(error, attempt2) {
+  const after = isRecord(error.details) ? error.details.retryAfter : void 0;
+  if (typeof after === "number") return after * 1e3;
+  if (error.code === "OBJECT_RATE_LIMITED") return 1e3;
+  return BACKOFF_MS[attempt2 - 1] ?? 4e3;
+}
+var sleepFor = (ms, signal) => new Promise((done) => {
+  if (signal?.aborted) {
+    done();
+    return;
+  }
+  const end = () => {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", end);
+    done();
+  };
+  const timer = setTimeout(end, ms);
+  signal?.addEventListener("abort", end);
+});
+async function uploadInParts(a) {
+  const { signal } = a;
+  const sleep = a.sleep ?? sleepFor;
+  if (signal?.aborted) return fail(uploadAborted());
+  const started = await call(a.http, {
+    method: a.method,
+    path: ROUTE,
+    body: {
+      bucket: a.bucket,
+      path: a.path,
+      size: a.size,
+      contentType: a.contentType,
+      cacheControl: a.cacheControl,
+      // PUT always replaces: the worker refuses `upsert` on it.
+      ...a.method === "POST" && a.upsert ? { upsert: true } : {}
+    },
+    withToken: true
+  });
+  if (started.error !== null) return fail(started.error);
+  const plan = dataOf2(
+    started.answer.status,
+    started.answer.body,
+    planFor(a.size)
+  );
+  if (plan.error !== null) return fail(plan.error);
+  const { uploadId, partSize, partCount } = plan.data;
+  const base = `${ROUTE}/${uploadId}`;
+  const progress = (sentBytes2) => {
+    if (signal?.aborted) return;
+    try {
+      const result = a.onProgress?.(sentBytes2, a.size);
+      if (isThenable(result)) result.then(void 0, () => void 0);
+    } catch {
+    }
+  };
+  const callOff = async () => {
+    await call(a.http, { method: "DELETE", path: base, withToken: true }).catch(
+      () => void 0
+    );
+  };
+  const etags = [];
+  const failure = {
+    error: signal?.aborted ? uploadAborted() : null
+  };
+  let next = 1;
+  let sentBytes = 0;
+  const onAbort = () => {
+    failure.error ??= uploadAborted();
+  };
+  const tryPart = async (n, bytes) => {
+    const sent = await send(a.http, {
+      method: "PUT",
+      path: `${base}/${String(n)}`,
+      headers: { "content-type": "application/octet-stream" },
+      body: bytes,
+      withToken: true,
+      signal
+    });
+    if (sent.error !== null) return sent;
+    const read = await readJson(sent.response, partAnswer(n));
+    if (read.error !== null)
+      return { error: read.error, status: sent.response.status };
+    return { etag: read.data.etag };
+  };
+  const sendPart = async (n) => {
+    const from = (n - 1) * partSize;
+    const to = Math.min(from + partSize, a.size);
+    const bytes = a.body instanceof Uint8Array ? a.body.subarray(from, to) : a.body.slice(from, to);
+    for (let attempt2 = 1; ; attempt2 += 1) {
+      const tried = await tryPart(n, bytes);
+      if ("etag" in tried) {
+        etags[n - 1] = tried.etag;
+        sentBytes += to - from;
+        progress(sentBytes);
+        return null;
+      }
+      if (attempt2 === ATTEMPTS || failure.error !== null || !retryable(tried.error, tried.status))
+        return tried.error;
+      await sleep(waitAfter(tried.error, attempt2), signal);
+      if (failure.error !== null) return tried.error;
+    }
+  };
+  const worker = async () => {
+    while (failure.error === null && next <= partCount) {
+      const n = next;
+      next += 1;
+      const error = await sendPart(n);
+      if (error !== null) failure.error ??= error;
+    }
+  };
+  signal?.addEventListener("abort", onAbort);
+  await Promise.all(
+    Array.from({ length: Math.min(CONCURRENCY, partCount) }, worker)
+  );
+  signal?.removeEventListener("abort", onAbort);
+  if (failure.error !== null) {
+    await callOff();
+    return fail(failure.error);
+  }
+  const completed = await call(a.http, {
+    method: "POST",
+    path: `${base}/complete`,
+    body: {
+      parts: etags.map((etag, i) => ({ partNumber: i + 1, etag }))
+    },
+    withToken: true
+  });
+  if (completed.error !== null) {
+    if (completed.answer !== null && completed.error.code !== "INVALID_RESPONSE")
+      await callOff();
+    return fail(completed.error);
+  }
+  return dataOf2(completed.answer.status, completed.answer.body, isUploadResult);
+}
+var isThenable = (value) => typeof value === "object" && value !== null && typeof value.then === "function";
+
+// src/storage/path.ts
+var MAX_SINGLE_UPLOAD_BYTES = 52428800;
+var STORAGE_MESSAGES = {
+  bucket: "The bucket name is not valid.",
+  request: "The storage request is not valid.",
+  body: "upload takes a Blob, File, ArrayBuffer, typed array or string."
+};
+var RESERVED_BUCKETS = /* @__PURE__ */ new Set([
+  "authenticated",
+  "copy",
+  "info",
+  "list",
+  "move",
+  "public",
+  "render",
+  "sign",
+  "upload"
+]);
+var DOWNLOAD_NAME_REASON = "must be a file name of up to 255 bytes";
+var LONE_SURROGATE = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/;
+var OCTET_STREAM = "application/octet-stream";
+var UTF8_TEXT = "text/plain;charset=utf-8";
+function invalidPath(reason) {
+  return {
+    code: "INVALID_PATH",
+    message: `The object path is not valid: it ${reason}.`
+  };
+}
+function encodePath(path) {
+  if (typeof path !== "string" || path === "")
+    return { ok: false, error: invalidPath("is empty") };
+  if (LONE_SURROGATE.test(path))
+    return { ok: false, error: invalidPath("is not valid UTF-8") };
+  if (path.startsWith("/") || path.endsWith("/"))
+    return { ok: false, error: invalidPath("starts or ends with /") };
+  if (path.includes("//"))
+    return { ok: false, error: invalidPath("has an empty segment (//)") };
+  const segments = path.split("/");
+  if (segments.some((segment) => segment === "." || segment === ".."))
+    return { ok: false, error: invalidPath("has a . or .. segment") };
+  return { ok: true, encoded: segments.map(encodeURIComponent).join("/") };
+}
+function downloadQuery(download) {
+  if (download === true) return { ok: true, encoded: "?download" };
+  if (typeof download !== "string") return { ok: true, encoded: "" };
+  if (LONE_SURROGATE.test(download))
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_REQUEST",
+        message: STORAGE_MESSAGES.request,
+        details: { path: "download", reason: DOWNLOAD_NAME_REASON }
+      }
+    };
+  return { ok: true, encoded: `?download=${encodeURIComponent(download)}` };
+}
+function encodeBucket(bucket) {
+  if (typeof bucket !== "string" || bucket === "" || bucket === "." || bucket === ".." || LONE_SURROGATE.test(bucket) || RESERVED_BUCKETS.has(bucket))
+    return {
+      ok: false,
+      error: { code: "INVALID_PATH", message: STORAGE_MESSAGES.bucket }
+    };
+  return { ok: true, encoded: encodeURIComponent(bucket) };
+}
+function objectRoute(bucket, path) {
+  const encodedBucket = encodeBucket(bucket);
+  if (!encodedBucket.ok) return encodedBucket;
+  const encodedPath = encodePath(path);
+  if (!encodedPath.ok) return encodedPath;
+  return {
+    ok: true,
+    encoded: `${encodedBucket.encoded}/${encodedPath.encoded}`
+  };
+}
+var isArrayBuffer = (value) => Object.prototype.toString.call(value) === "[object ArrayBuffer]";
+function isDetached(buffer) {
+  if (!isArrayBuffer(buffer)) return false;
+  const flag = buffer.detached;
+  if (typeof flag === "boolean") return flag;
+  if (buffer.byteLength > 0) return false;
+  try {
+    buffer.slice(0);
+    return false;
+  } catch {
+    return true;
+  }
+}
+var CACHE_CONTROL_REASON = "must be max-age=<seconds> from 0 to 31536000";
+var MAX_TYPE_IN_MESSAGE = 256;
+function unsendable(value) {
+  return /[\0\r\n]|[^\0-\xff]/.test(
+    value.replace(/^[\t\n\r ]+|[\t\n\r ]+$/g, "")
+  );
+}
+function headerProblem(contentType, cacheControl) {
+  if (typeof contentType === "string" && unsendable(contentType)) {
+    let shown = contentType;
+    if (shown.length > MAX_TYPE_IN_MESSAGE) {
+      shown = shown.slice(0, MAX_TYPE_IN_MESSAGE);
+      if (/[\ud800-\udbff]$/.test(shown)) shown = shown.slice(0, -1);
+    }
+    return {
+      code: "INVALID_CONTENT_TYPE",
+      message: `Content-Type ${shown} is not a media type like image/png.`
+    };
+  }
+  if (unsendable(cacheControl))
+    return {
+      code: "INVALID_REQUEST",
+      message: STORAGE_MESSAGES.request,
+      details: { path: "cache-control", reason: CACHE_CONTROL_REASON }
+    };
+  return null;
+}
+function payloadOf(body, contentType) {
+  if (typeof body === "string") {
+    const bytes = new TextEncoder().encode(body);
+    return {
+      ok: true,
+      body: bytes,
+      size: bytes.byteLength,
+      type: contentType ?? UTF8_TEXT
+    };
+  }
+  if (typeof Blob === "function" && body instanceof Blob)
+    return {
+      ok: true,
+      body,
+      size: body.size,
+      type: contentType ?? (body.type === "" ? OCTET_STREAM : body.type)
+    };
+  if (isArrayBuffer(body) && !isDetached(body))
+    return {
+      ok: true,
+      body,
+      size: body.byteLength,
+      type: contentType ?? OCTET_STREAM
+    };
+  if (ArrayBuffer.isView(body) && !isDetached(body.buffer)) {
+    const { buffer, byteOffset, byteLength } = body;
+    const bytes = isArrayBuffer(buffer) ? new Uint8Array(buffer, byteOffset, byteLength) : Uint8Array.from(new Uint8Array(buffer, byteOffset, byteLength));
+    return {
+      ok: true,
+      body: bytes,
+      size: byteLength,
+      type: contentType ?? OCTET_STREAM
+    };
+  }
+  return {
+    ok: false,
+    error: { code: "INVALID_BODY", message: STORAGE_MESSAGES.body }
+  };
+}
+
+// src/storage/client.ts
+var SIGNED_PREFIX = "/_naro/v1/storage/object/sign/";
+var isFileObject = (value) => isRecord(value) && typeof value.id === "string" && typeof value.name === "string" && isRecord(value.metadata);
+var isEntry2 = (value) => isRecord(value) && typeof value.name === "string" && (value.id === null || isFileObject(value));
+var isSigned = (value) => isRecord(value) && typeof value.signedUrl === "string" && value.signedUrl.startsWith(SIGNED_PREFIX);
+function listOf(guard) {
+  return (value) => Array.isArray(value) && value.every(guard);
+}
+var StorageFileApi = class {
+  #http;
+  #auth;
+  #bucket;
+  constructor(http, auth, bucket) {
+    this.#http = http;
+    this.#auth = auth;
+    this.#bucket = bucket;
+  }
+  /** `/storage/object/<route><bucket>/<path>`, or the refusal no request needs. */
+  #objectPath(route, path) {
+    const target = objectRoute(this.#bucket, path);
+    if (!target.ok) return target;
+    return { ok: true, path: `/storage/object/${route}${target.encoded}` };
+  }
+  /** `/storage/object/<route><bucket>`, for the routes that take names in the body. */
+  #bucketPath(route) {
+    const bucket = encodeBucket(this.#bucket);
+    if (!bucket.ok) return bucket;
+    return { ok: true, path: `/storage/object/${route}${bucket.encoded}` };
+  }
+  async #json(request, guard) {
+    await this.#auth.ready();
+    const result = await call(this.#http, { ...request, withToken: true });
+    if (result.error !== null) return fail(result.error);
+    return dataOf2(result.answer.status, result.answer.body, guard);
+  }
+  async #write(method, path, body, options, upsert) {
+    const target = this.#objectPath("", path);
+    if (!target.ok) return fail(target.error);
+    const payload = payloadOf(body, options.contentType);
+    if (!payload.ok) return fail(payload.error);
+    const cache = `max-age=${options.cacheControl ?? "3600"}`;
+    const unreadable = headerProblem(options.contentType, cache);
+    if (unreadable !== null) return fail(unreadable);
+    const { signal } = options;
+    if (signal?.aborted) return fail(uploadAborted());
+    await this.#auth.ready();
+    if (payload.size > MAX_SINGLE_UPLOAD_BYTES)
+      return uploadInParts({
+        http: this.#http,
+        method,
+        bucket: this.#bucket,
+        path,
+        // No copy: a Blob stays lazy, a Uint8Array is viewed, an ArrayBuffer wrapped.
+        body: isArrayBuffer(payload.body) ? new Uint8Array(payload.body) : payload.body,
+        size: payload.size,
+        contentType: payload.type,
+        cacheControl: cache,
+        upsert,
+        ...options.onProgress ? { onProgress: options.onProgress } : {},
+        signal
+      });
+    const headers = {
+      "content-type": payload.type,
+      "cache-control": cache
+    };
+    if (upsert) headers["x-upsert"] = "true";
+    const sent = await send(this.#http, {
+      method,
+      path: target.path,
+      headers,
+      body: payload.body,
+      withToken: true,
+      // The fetch stops with the body: the worker undoes its claim at once.
+      signal
+    });
+    if (sent.error !== null) return fail(sent.error);
+    return readJson(sent.response, isUploadResult);
+  }
+  /**
+   * A new object; with `upsert: true`, one of the same name is replaced.
+   * `null` options, as a JS caller may pass, are no options.
+   */
+  upload(path, body, options = {}) {
+    const given = options ?? {};
+    return this.#write("POST", path, body, given, given.upsert === true);
+  }
+  /** Replaces an object that is there (`OBJECT_NOT_FOUND` otherwise). */
+  update(path, body, options = {}) {
+    return this.#write("PUT", path, body, options ?? {}, false);
+  }
+  /**
+   * The object's bytes, as a Blob of the type the worker serves it under:
+   * the stored type for the images, audio, video, PDF, plain text, CSV,
+   * JSON and SVG it serves as themselves, `application/octet-stream` for
+   * anything else (HTML, scripts, archives, unknown types — `info` and
+   * `list` hold the stored type).
+   */
+  async download(path) {
+    const target = this.#objectPath("", path);
+    if (!target.ok) return fail(target.error);
+    await this.#auth.ready();
+    const sent = await send(this.#http, {
+      method: "GET",
+      path: target.path,
+      withToken: true
+    });
+    if (sent.error !== null) return fail(sent.error);
+    try {
+      return { data: await sent.response.blob(), error: null };
+    } catch (error) {
+      return fail(networkError(error));
+    }
+  }
+  async info(path) {
+    const target = this.#objectPath("info/", path);
+    if (!target.ok) return fail(target.error);
+    return this.#json({ method: "GET", path: target.path }, isFileObject);
+  }
+  /**
+   * Whether the caller can see the object: `OBJECT_NOT_FOUND` is false,
+   * every other error comes back as it is (plan C1 — asked with `info`,
+   * not HEAD, whose answer has no body to tell a missing bucket from a
+   * missing object).
+   */
+  async exists(path) {
+    const found = await this.info(path);
+    if (found.error === null) return { data: true, error: null };
+    if (found.error.code === "OBJECT_NOT_FOUND")
+      return { data: false, error: null };
+    return fail(found.error);
+  }
+  /**
+   * What is directly below `prefix` (the whole bucket by default): folders
+   * first, then files. The options go to the worker as they are given.
+   */
+  async list(prefix, options = {}) {
+    const target = this.#bucketPath("list/");
+    if (!target.ok) return fail(target.error);
+    return this.#json(
+      {
+        method: "POST",
+        path: target.path,
+        body: { ...prefix === void 0 ? {} : { prefix }, ...options }
+      },
+      listOf(isEntry2)
+    );
+  }
+  /** Removes the objects named — 1 to 1,000 — and answers the ones it removed. */
+  async remove(paths) {
+    const target = this.#bucketPath("");
+    if (!target.ok) return fail(target.error);
+    return this.#json(
+      { method: "DELETE", path: target.path, body: { prefixes: paths } },
+      listOf(isFileObject)
+    );
+  }
+  /**
+   * A link to the object for `expiresIn` seconds (1–604,800). It stops
+   * working once the object is replaced or removed.
+   */
+  async createSignedUrl(path, expiresIn, options = {}) {
+    const target = this.#objectPath("sign/", path);
+    if (!target.ok) return fail(target.error);
+    const { download } = options ?? {};
+    const signed = await this.#json(
+      {
+        method: "POST",
+        path: target.path,
+        body: {
+          expiresIn,
+          ...download === void 0 || download === false ? {} : { download }
+        }
+      },
+      isSigned
+    );
+    if (signed.error !== null) return signed;
+    return {
+      data: { signedUrl: `${this.#http.baseUrl}${signed.data.signedUrl}` },
+      error: null
+    };
+  }
+  /**
+   * A public bucket's URL for the object. No request is made, so whether
+   * the bucket is public is not checked (as in supabase-js); a path no URL
+   * can carry is INVALID_PATH (plan C3), and a download name none can carry
+   * is the worker's INVALID_REQUEST for it.
+   */
+  getPublicUrl(path, options = {}) {
+    const target = this.#objectPath("public/", path);
+    if (!target.ok) return fail(target.error);
+    const { download } = options ?? {};
+    const query = downloadQuery(download);
+    if (!query.ok) return fail(query.error);
+    return {
+      data: {
+        publicUrl: `${this.#http.baseUrl}/_naro/v1${target.path}${query.encoded}`
+      },
+      error: null
+    };
+  }
+};
+var StorageClient = class {
+  #http;
+  #auth;
+  constructor(http, auth) {
+    this.#http = http;
+    this.#auth = auth;
+  }
+  /** The objects of one bucket. */
+  from(bucket) {
+    return new StorageFileApi(this.#http, this.#auth, bucket);
+  }
+};
+
 // src/client.ts
 var CONFIG_MESSAGES = {
   url: "createClient needs the project url, like https://my-app.naro.sh.",
@@ -1815,9 +2424,13 @@ var NaroClient = class {
    * service key, `auth.admin` manages users.
    */
   auth;
+  /**
+   * Files in the project's Naro Storage (first-release design 2026-10-06
+   * §8.1): `storage.from(bucket)` uploads, downloads, lists and removes
+   * them, as supabase-js does.
+   */
+  storage;
   #run;
-  // naro.storage — Phase 3 (spec §18): R2 storage lands here, beside `auth`
-  // and `from()`. Deliberately absent in Phase 1: not implemented, not typed.
   constructor(options) {
     const baseUrl = baseUrlOf(options.url);
     const { key: apiKey, service } = apiKeyOf(options);
@@ -1842,6 +2455,7 @@ var NaroClient = class {
       serviceKey: service
     });
     this.#run = queryRunner(http, this.auth);
+    this.storage = new StorageClient(http, this.auth);
   }
   /** Start a query on `table`: `.select()`, `.insert()`, `.update()` or `.delete()`. */
   from(table) {
@@ -1854,5 +2468,6 @@ function createClient(options) {
 export {
   NaroClient,
   createClient,
+  objectRoute,
   quoteFilterValue
 };

package/dist/storage/answer.d.ts

@@ -0,0 +1,9 @@
+import { type NaroError } from "../errors.js";
+import type { NaroResponse } from "../types.js";
+import type { UploadResult } from "./types.js";
+export declare function fail<T>(error: NaroError): NaroResponse<T>;
+export declare const isUploadResult: (value: unknown) => value is UploadResult;
+/** `{ data }` of a worker's JSON answer that passes `guard`, else INVALID_RESPONSE. */
+export declare function dataOf<T>(status: number, body: unknown, guard: (value: unknown) => value is T): NaroResponse<T>;
+/** A 2xx answer `send` handed back unread, read as `dataOf` reads one. */
+export declare function readJson<T>(response: Response, guard: (value: unknown) => value is T): Promise<NaroResponse<T>>;

package/dist/storage/client.d.ts

@@ -0,0 +1,65 @@
+import type { AuthClient } from "../auth/client.js";
+import { type HttpConfig } from "../http.js";
+import type { NaroResponse } from "../types.js";
+import type { DownloadOption, FileObject, FolderEntry, ListOptions, UpdateOptions, UploadBody, UploadOptions, UploadResult } from "./types.js";
+/** One bucket's objects: supabase-js's StorageFileApi. */
+export declare class StorageFileApi {
+    #private;
+    constructor(http: HttpConfig, auth: AuthClient, bucket: string);
+    /**
+     * A new object; with `upsert: true`, one of the same name is replaced.
+     * `null` options, as a JS caller may pass, are no options.
+     */
+    upload(path: string, body: UploadBody, options?: UploadOptions): Promise<NaroResponse<UploadResult>>;
+    /** Replaces an object that is there (`OBJECT_NOT_FOUND` otherwise). */
+    update(path: string, body: UploadBody, options?: UpdateOptions): Promise<NaroResponse<UploadResult>>;
+    /**
+     * The object's bytes, as a Blob of the type the worker serves it under:
+     * the stored type for the images, audio, video, PDF, plain text, CSV,
+     * JSON and SVG it serves as themselves, `application/octet-stream` for
+     * anything else (HTML, scripts, archives, unknown types — `info` and
+     * `list` hold the stored type).
+     */
+    download(path: string): Promise<NaroResponse<Blob>>;
+    info(path: string): Promise<NaroResponse<FileObject>>;
+    /**
+     * Whether the caller can see the object: `OBJECT_NOT_FOUND` is false,
+     * every other error comes back as it is (plan C1 — asked with `info`,
+     * not HEAD, whose answer has no body to tell a missing bucket from a
+     * missing object).
+     */
+    exists(path: string): Promise<NaroResponse<boolean>>;
+    /**
+     * What is directly below `prefix` (the whole bucket by default): folders
+     * first, then files. The options go to the worker as they are given.
+     */
+    list(prefix?: string, options?: ListOptions): Promise<NaroResponse<(FileObject | FolderEntry)[]>>;
+    /** Removes the objects named — 1 to 1,000 — and answers the ones it removed. */
+    remove(paths: string[]): Promise<NaroResponse<FileObject[]>>;
+    /**
+     * A link to the object for `expiresIn` seconds (1–604,800). It stops
+     * working once the object is replaced or removed.
+     */
+    createSignedUrl(path: string, expiresIn: number, options?: DownloadOption): Promise<NaroResponse<{
+        signedUrl: string;
+    }>>;
+    /**
+     * A public bucket's URL for the object. No request is made, so whether
+     * the bucket is public is not checked (as in supabase-js); a path no URL
+     * can carry is INVALID_PATH (plan C3), and a download name none can carry
+     * is the worker's INVALID_REQUEST for it.
+     */
+    getPublicUrl(path: string, options?: DownloadOption): NaroResponse<{
+        publicUrl: string;
+    }>;
+}
+/**
+ * `naro.storage`. Buckets are made with `naro storage bucket create` or the
+ * MCP server, never from a client (original spec §6).
+ */
+export declare class StorageClient {
+    #private;
+    constructor(http: HttpConfig, auth: AuthClient);
+    /** The objects of one bucket. */
+    from(bucket: string): StorageFileApi;
+}

package/dist/storage/multipart.d.ts

@@ -0,0 +1,23 @@
+import { type HttpConfig } from "../http.js";
+import type { NaroResponse } from "../types.js";
+import type { UploadResult } from "./types.js";
+export type PartsArgs = {
+    http: HttpConfig;
+    /** POST for `upload` (a new name, or `upsert`), PUT for `update`. */
+    method: "POST" | "PUT";
+    bucket: string;
+    /** The object's name as given: the start carries it in JSON, not a URL. */
+    path: string;
+    body: Blob | Uint8Array<ArrayBuffer>;
+    size: number;
+    contentType: string;
+    /** As the upload's header says it: `max-age=<seconds>`. */
+    cacheControl: string;
+    upsert: boolean;
+    onProgress?: (sentBytes: number, totalBytes: number) => void;
+    /** The caller's: stops the upload until the complete is sent. */
+    signal?: AbortSignal | undefined;
+    /** How a retry waits — `ms`, or until the signal aborts; tests pass their own. */
+    sleep?: (ms: number, signal: AbortSignal | undefined) => Promise<void>;
+};
+export declare function uploadInParts(a: PartsArgs): Promise<NaroResponse<UploadResult>>;

package/dist/storage/path.d.ts

@@ -0,0 +1,87 @@
+import type { NaroError } from "../errors.js";
+/**
+ * The most one upload request carries (original spec §9.1): 50 MiB.
+ * data-core's MAX_SINGLE_UPLOAD_BYTES — storage/wire.test.ts holds them
+ * equal. Over it, the edge cuts the body off and the browser often cannot
+ * read the answer: the SDK sends a larger body in parts (Storage 3-1f).
+ */
+export declare const MAX_SINGLE_UPLOAD_BYTES = 52428800;
+/** The worker's words (data-core's catalog) for what the SDK refuses itself. */
+export declare const STORAGE_MESSAGES: {
+    readonly bucket: "The bucket name is not valid.";
+    readonly request: "The storage request is not valid.";
+    readonly body: "upload takes a Blob, File, ArrayBuffer, typed array or string.";
+};
+/**
+ * The words the worker's routes take as the first segment after `/object/`
+ * (data-core's STORAGE_RESERVED_WORDS): as a bucket, the URL would name
+ * another route. No bucket can have one of these names.
+ */
+export declare const RESERVED_BUCKETS: ReadonlySet<string>;
+/** Why the worker refuses a `download` name (serve.ts's DOWNLOAD_NAME_REASON). */
+export declare const DOWNLOAD_NAME_REASON = "must be a file name of up to 255 bytes";
+export type Encoded = {
+    ok: true;
+    encoded: string;
+} | {
+    ok: false;
+    error: NaroError;
+};
+export declare function invalidPath(reason: string): NaroError;
+/**
+ * An object path as a URL carries it, each segment encoded once and `/`
+ * kept as the separator — or the worker's INVALID_PATH for the paths no
+ * URL can carry as they are (original spec §13, plan C2): an empty name, a
+ * `/` at either end, `//`, a `.` or `..` segment (WHATWG URL parsing folds
+ * `..` and `%2E%2E` alike, so the worker would get another path), and a
+ * lone surrogate (`encodeURIComponent` throws on one). Every other rule is
+ * the worker's alone — one set of rules, in one place.
+ */
+export declare function encodePath(path: string): Encoded;
+/**
+ * `?download` for the object's own name, `?download=<name>` for another, or
+ * the worker's own INVALID_REQUEST for a name `encodeURIComponent` throws on
+ * (a lone surrogate: the sign route refuses the same name in its body). Every
+ * other rule on the name is the worker's alone.
+ */
+export declare function downloadQuery(download: boolean | string | undefined): Encoded;
+/**
+ * A bucket name as the URL's segment — encoded (a valid name is unchanged
+ * by it), or INVALID_PATH for the names that would not reach a bucket:
+ * empty, `.`, `..`, a lone surrogate and the routes' own words.
+ */
+export declare function encodeBucket(bucket: string): Encoded;
+/**
+ * `<bucket>/<path>` as the object routes carry it — the bucket by
+ * `encodeBucket`, the path by `encodePath` — or the INVALID_PATH either is
+ * refused with. Every object call builds its URL from it, and the package
+ * exports it for a tool that streams an object itself (naro-cli's
+ * download): it names the same URL, and is refused the same names.
+ */
+export declare function objectRoute(bucket: string, path: string): Encoded;
+/**
+ * `instanceof ArrayBuffer` is false for one made in another realm (an
+ * iframe, a vm context); the tag is the same in every realm.
+ */
+export declare const isArrayBuffer: (value: unknown) => value is ArrayBuffer;
+/** Why the worker refuses a cache-control it cannot read (its upload.ts). */
+export declare const CACHE_CONTROL_REASON = "must be max-age=<seconds> from 0 to 31536000";
+/**
+ * The upload's `contentType` and `cacheControl` as headers, or the worker's
+ * answer for a value it cannot read when no header can carry it (PR #90
+ * review 1): INVALID_CONTENT_TYPE with data-core's words (the type cut at
+ * 256 UTF-16 units, as `storageName` cuts it), and INVALID_REQUEST
+ * `cache-control`. Every other value is the worker's to judge.
+ */
+export declare function headerProblem(contentType: string | undefined, cacheControl: string): NaroError | null;
+export type Payload = {
+    ok: true;
+    body: Blob | ArrayBuffer | Uint8Array<ArrayBuffer>;
+    size: number;
+    type: string;
+} | {
+    ok: false;
+    error: NaroError;
+};
+/** The upload's body, its bytes and its type — or INVALID_BODY. */
+export declare function payloadOf(body: unknown, contentType: string | undefined): Payload;

package/dist/storage/types.d.ts

@@ -0,0 +1,77 @@
+/** An object as the worker answers it. */
+export type FileObject = {
+    id: string;
+    /** The full path from `info` and `remove`; the name below the prefix in `list`. */
+    name: string;
+    bucket_id: string;
+    /** Who uploaded it; null for the anon or the service key. */
+    owner: string | null;
+    owner_id: string | null;
+    /** The bytes' etag. */
+    version: string;
+    created_at: string;
+    updated_at: string;
+    /** `eTag`, `size`, `mimetype`, `cacheControl`, `lastModified`, `contentLength`, `httpStatusCode`. */
+    metadata: Record<string, unknown>;
+};
+/** A folder in a listing: a name and nothing else. Folders come first. */
+export type FolderEntry = {
+    name: string;
+    id: null;
+    created_at: null;
+    updated_at: null;
+    metadata: null;
+};
+/**
+ * What an upload sends: bytes whose length `fetch` knows, so it sets
+ * `Content-Length`. A string goes as UTF-8. Not a stream, not `FormData`.
+ */
+export type UploadBody = Blob | ArrayBuffer | ArrayBufferView | string;
+export type UploadOptions = {
+    /** Default: the Blob's type, `text/plain;charset=utf-8` for a string, else `application/octet-stream`. */
+    contentType?: string;
+    /** Seconds a browser may keep it, as text. Default `"3600"`. */
+    cacheControl?: string;
+    /** Replace an object of the same name. Default false. */
+    upsert?: boolean;
+    /**
+     * Called each time a part of an upload over 50 MiB is sent: the bytes
+     * sent so far and the body's size, ending with both the same. An upload
+     * of 50 MiB or less is one request and never calls it. What it throws is
+     * ignored: the upload goes on.
+     */
+    onProgress?: (sentBytes: number, totalBytes: number) => void;
+    /**
+     * Stops the upload: what has not been answered yet is called off, and the
+     * upload answers `ABORTED` ("The upload was stopped before it finished.").
+     * One over 50 MiB is called off on the backend too, so its name and the
+     * space it reserved are free at once — not after the hour its lock lasts;
+     * no part starts and `onProgress` is not called after the signal. Its
+     * first and last steps are never cut short: a signal during the first is
+     * acted on once it answers, and once the last is sent the signal stops
+     * nothing and that step's answer is the upload's. A signal already aborted
+     * sends nothing.
+     */
+    signal?: AbortSignal;
+};
+export type UpdateOptions = Omit<UploadOptions, "upsert">;
+export type UploadResult = {
+    id: string;
+    path: string;
+    fullPath: string;
+};
+export type ListOptions = {
+    /** 1–1,000; 100 by default. */
+    limit?: number;
+    /** 0–100,000. */
+    offset?: number;
+    /** Folders come first whatever the sort. Default name ascending. */
+    sortBy?: {
+        column?: "name" | "created_at" | "updated_at";
+        order?: "asc" | "desc";
+    };
+};
+/** `true` downloads under the object's own name, a string under that name. */
+export type DownloadOption = {
+    download?: boolean | string;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "naro-js",
-  "version": "0.2.0",
-  "description": "Auth and data for your Naro project, from the browser or the server.",
+  "version": "0.4.0",
+  "description": "Auth, data and files for your Naro project, from the browser or the server.",
   "type": "module",
   "sideEffects": false,
   "files": [