naro-js 0.4.0 → 0.6.0

package/README.md

@@ -79,6 +79,7 @@ await naro.from("posts").delete().eq("id", 10);
   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).
+- Live changes, broadcast and presence — see [Realtime](#realtime).
 
 ## Policies
 
@@ -271,12 +272,14 @@ await naro.auth.updateUser({ password: newPassword });
   redirects off them. `getSessionFromUrl()` never shows text from the URL:
   its errors carry the SDK's own messages.
 - A provider email the provider has not verified is refused
-  (`OAUTH_PROVIDER_EMAIL_NOT_VERIFIED`): verify it with the provider first.
+  (`OAUTH_PROVIDER_EMAIL_NOT_VERIFIED`, or `OAUTH_ACCOUNT_NOT_LINKED` when an
+  account with that address already exists): verify it with the provider first.
   An account with the same email is linked only when both sides have it
   confirmed (`OAUTH_ACCOUNT_NOT_LINKED` otherwise).
 - A confirmation link opens no session. If someone else signed up with the
   address before its owner confirmed it — or the owner's Google or GitHub
-  sign-in was refused for that unconfirmed account
+  sign-in, with an address the provider verified, was refused for that
+  unconfirmed account
   (`OAUTH_ACCOUNT_NOT_LINKED`) — confirming clears that password
   (`PASSWORD_RESET_REQUIRED`): set one with `resetPasswordForEmail`.
 - `updateUser({ password })` sets a new password in the recovery flow only
@@ -483,15 +486,78 @@ await avatars.remove([`${user.id}/old.png`]);
 const { data: link } = await naro.storage
   .from("docs")
   .createSignedUrl("team-1/plan.pdf", 600);
+const { data: links } = await naro.storage
+  .from("docs")
+  .createSignedUrls(["team-1/a.pdf", "team-1/b.pdf"], 600);
+const { data: plans } = await naro.storage
+  .from("docs")
+  .list("team-1", { search: "plan" });
+const { data: copied } = await naro.storage
+  .from("docs")
+  .copy("team-1/plan.pdf", "team-2/plan.pdf", { upsert: true });
+await naro.storage
+  .from("docs")
+  .move("team-1/plan.pdf", "team-1/archive/plan.pdf");
 ```
 
-- `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`.
+- `upload`, `update`, `download`, `info`, `exists`, `list`, `remove`, `move`,
+  `copy`, `createSignedUrl`, `createSignedUrls` and `getPublicUrl` take
+  supabase-js's arguments and answer its shapes (`FileObject` in
+  snake_case), as `{ data, error }`, with two exceptions. 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`. supabase-js's `copy` answers `{ path }` with the
+  bucket in front of the name; naro-js's `copy` answers
+  `{ id, path, fullPath }`, as `upload` does, with `path` the name inside
+  the bucket.
+- `createSignedUrls(paths, expiresIn, { download })` signs 1 to 100 paths in
+  one request (naro-js 0.5.0) and answers one `{ path, signedUrl, error }`
+  per path, in the order given — a path given twice is answered twice. A
+  file that is not there, or that the caller cannot read, has
+  `signedUrl: null` and the `error`
+  `Object <path> was not found in bucket <bucket>.` — the same words for
+  both. `signedUrl` is absolute, as `createSignedUrl`'s. The paths go in the
+  body unchecked: a bad one fails the call with `INVALID_REQUEST`
+  (`details.path` `paths[<i>]`). Unlike supabase-js, `download` goes in the
+  request — the token covers it — so adding `&download` to a URL afterwards
+  answers `400 INVALID_SIGNATURE`.
+- `list(prefix, { search })` keeps the names directly below `prefix` that
+  start with `search`. As in Supabase, `%` and `_` are plain characters, not
+  wildcards. Unlike Supabase, only ASCII letters ignore case (Postgres folds
+  case by the database's locale) and `search` takes up to 256 characters. A
+  folder shows when a name under it starts with `search`.
+- `move(from, to)` and `copy(from, to, { upsert })` work inside one bucket
+  (naro-js 0.6.0), on files up to 5 GiB − 5 MiB (`413 OBJECT_TOO_LARGE`
+  `Objects over 5,363,466,240 bytes (5 GiB − 5 MiB) cannot be copied or moved.`).
+  A move keeps the file — its `id` and owner — under the new name and never
+  replaces a file that is there (`409 OBJECT_EXISTS`); the file's signed
+  links stop working at its old name (a link is bound to the name, the
+  file's `id` and its bytes, so moving it back can open them again). A copy
+  to a new name is a new file of the caller's, held to the bucket's limits
+  as they are now; `upsert: true` replaces one that is there, which keeps
+  its owner. Both are
+  judged by the policies as in Supabase: a move needs SELECT and UPDATE on the
+  file, and SELECT and the UPDATE check on its new name; a copy needs SELECT
+  on the source and INSERT on the copy (with `upsert: true`, replacing a file
+  takes what an upload's `upsert` takes). While a file is moved, or copied to
+  a new name, the project needs room for one more copy of it (a copy that
+  replaces a file with `upsert: true` needs only the growth), so in a project
+  that is almost full they can answer `507 STORAGE_QUOTA_EXCEEDED`. `copy`
+  answers `{ id, path, fullPath }`, not supabase-js's `{ path }` (see
+  above). Unlike supabase-js, a `destinationBucket` other than the bucket
+  answers `400 INVALID_REQUEST`.
+- A backend whose Storage was turned on before these came answers
+  `createSignedUrls`, `move` and `copy` with `404 NOT_FOUND` and a `search`
+  with `400 INVALID_REQUEST` (`details.path` `search`, `details.reason`
+  `search is not supported yet`): update it once with `naro backend enable`.
+- A public file is kept at Naro's edge for up to 5 minutes (or for its own
+  `cacheControl`, when that is shorter): after it is deleted, moved or
+  replaced, or its bucket is made private, `getPublicUrl`'s URL (for a moved
+  file, the old name's) can still serve the old bytes that long. Put a
+  version in names that change (`avatar-<time>.png`) or keep `cacheControl`
+  short. Signed URLs are not kept at the edge: replacing or deleting a file
+  ends its signed links at once, and moving it ends them at its old name.
 - 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
@@ -540,6 +606,38 @@ await naro.storage.from("videos").upload(`${user.id}/talk.mp4`, file, {
 });
 ```
 
+- `createSignedUploadUrl(path, { upsert })` and
+  `uploadToSignedUrl(path, token, body, options)` are supabase-js's signed
+  upload (naro-js 0.5.0). A server with the service key — or anyone the
+  policies let upload there, anon or a signed-in user — makes a token for
+  one path; a page with only the anon key uploads by it. The token stands
+  in for the policies; the bucket's and the plan's limits and the
+  project's usage stops still apply. It works for 2 hours. Made with
+  `upsert: true` it may replace the file until then; without it a second
+  upload answers `409 OBJECT_EXISTS`.
+  `uploadToSignedUrl` sends no session, takes `contentType`,
+  `cacheControl`, `onProgress` and `signal` as `upload` does, and answers
+  `{ path, fullPath }`. Over 50 MiB it goes in parts with the token on
+  every step (the `x-naro-upload-token` header), and once started may
+  finish after the 2 hours. A token that is not the path's answers
+  `400 INVALID_SIGNATURE` (one no URL can carry is refused so before a
+  request), an expired one `400 SIGNED_URL_EXPIRED`. A token is neither
+  used up nor revocable: until its 2 hours end it can create its file again
+  after the file is deleted, and it keeps working if the user it was made
+  for is deleted or banned.
+
+```ts
+// On the server, with the service key:
+const { data, error } = await admin.storage
+  .from("avatars")
+  .createSignedUploadUrl(`${userId}/me.png`, { upsert: true });
+if (error) throw new Error(error.message);
+// In the browser, with the anon key:
+await naro.storage
+  .from("avatars")
+  .uploadToSignedUrl(data.path, data.token, file);
+```
+
 - 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
@@ -564,6 +662,201 @@ await naro.storage.from("videos").upload(`${user.id}/talk.mp4`, file, {
   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`).
+- Not yet: resuming an upload in another session, and bucket methods
+  (buckets are made with `naro storage bucket`).
+
+## Realtime
+
+Row changes, broadcast and presence over one WebSocket per page, called the
+way supabase-js's `channel()` is (naro-js 0.6.0). Turn it on for the project
+(the backend must be on) and publish the tables whose changes subscribers
+get:
+
+```sh
+naro realtime enable
+naro realtime tables add messages
+```
+
+```ts
+const room = naro.channel("room:1", {
+  config: { private: true, presence: { key: user.id } },
+});
+
+room
+  .on(
+    "postgres_changes",
+    { event: "INSERT", table: "messages", filter: "room_id=eq.1" },
+    (change) => append(change.new),
+  )
+  .on("broadcast", { event: "cursor" }, ({ payload }) => moveCursor(payload))
+  .on("presence", { event: "sync" }, () => render(room.presenceState()))
+  .on("system", {}, (notice) => {
+    // BULK_CHANGE, EVENTS_DROPPED: some changes did not come as rows.
+    if (notice.extension === "postgres_changes") refetchMessages();
+  })
+  .subscribe(async (status, error) => {
+    if (status === "SUBSCRIBED") {
+      refetchMessages(); // what changed while it was away does not come again
+      await room.track({ online_at: new Date().toISOString() });
+    }
+    if (status === "CHANNEL_ERROR") console.warn(error?.code, error?.message);
+  });
+
+await room.send({
+  type: "broadcast",
+  event: "cursor",
+  payload: { x: 10, y: 20 },
+});
+await naro.removeChannel(room);
+```
+
+- What becomes an event: Realtime publishes changes made through the Data
+  API (naro-js, any key). Writes your app makes with env.DB, naro db query
+  and the table editor are not published; send them with the realtime
+  broadcast API if clients need to know. Nor are the changes a trigger or a
+  cascade makes to other rows. A table publishes within about 10 seconds of
+  `naro realtime tables add`; a channel joined under a table's old name
+  receives nothing after a rename — join again with the new one.
+- A subscriber receives a row change only if its select policies on the
+  table let it read the row (for a `DELETE`, the row as it was); without a
+  select policy only the service key does. Broadcast and presence need a
+  private channel (`{ private: true }`) and policies on `realtime.messages`:
+  `select` to join and receive, `insert` to send and track, with
+  `realtime.topic()` as the channel's name. A policy that reads another
+  table — a members table — reads it through that table's own select
+  policies, so that table needs one too, or every private join is refused.
+  Declare a type (`TEXT`, `INTEGER`, `REAL`) on every column a select policy
+  reads.
+- Nothing that changed while the connection was away comes again: read again
+  when the channel says `SUBSCRIBED`. `BULK_CHANGE` (one request changed over
+  1,000 rows or 8 MiB) and `EVENTS_DROPPED` reach `.on("system", {}, …)` with
+  `extension: "postgres_changes"`, and both mean: read the table again.
+  Changes can arrive out of order, even two writes of one client: order by
+  `commit_timestamp`.
+- Every call returns `{ data, error }` and none throws. `subscribe(callback)`
+  hears `SUBSCRIBED`, `CHANNEL_ERROR` (with the error), `TIMED_OUT` and
+  `CLOSED`. The connection opens at the first `subscribe()` and closes with
+  the last channel; a join goes once the server has taken who the connection
+  is — on a page a sign-in link or provider sent back to, after that sign-in
+  has landed — and a sign-in, a sign-out or a renewed session reaches the
+  open connection at once.
+- Make one client per page and share it: a sign-in or sign-out through one
+  `createClient()` reaches only its own connection, and another client of the
+  same project keeps who it was until its next connection.
+- `send()` on a joined channel waits, as `track()` does, while a sign-in or
+  sign-out is on its way, and goes over HTTP if the join went meanwhile. A
+  payload over the plan's limit answers `PAYLOAD_TOO_LARGE`; a message whose
+  frame is over that limit plus 16 KiB answers `INVALID_MESSAGE`
+  (`is larger than N bytes`), and later ones over N on that connection get
+  the same answer without being sent.
+- Close codes: 1000 (a plain close, from the server or a proxy), 4000, 4001,
+  4003, 4004 and 4410 stop it — call `subscribe()` again; it connects after
+  the backoff, counted from the stop, so a `subscribe()` in the
+  `CHANNEL_ERROR` callback does not spin. 4029 comes back after 5 seconds at
+  least (60 to 70 for `IP_RATE_LIMITED`); 4503 after 0 to 10 seconds, every
+  time; anything else after 1, 2, 5 and then 10 seconds, each times 0.5 to
+  1.5 — after a 4008 the steps start over only once the connection outlived
+  a heartbeat. Removing the last channel and subscribing again keeps the wait
+  the server asked for. A 4401 signs out
+  only when the server refused the session it sent with `INVALID_SESSION`
+  and that session is still the one stored; one without that answer — a tab
+  open for days — keeps the session and connects again with it.
+- `unsubscribe()` and `removeChannel()` return the server's first answer to
+  the leave. A leave refused for now (`TOO_MANY_JOINS`, `INTERNAL_ERROR`,
+  `CONNECTION_STATE_TOO_LARGE`, `TIMED_OUT`) is sent again until the server
+  takes it, and a `subscribe()` of the same name and privacy joins after
+  that. While such a leave holds its place under the server's caps (4
+  channels of a connection on one table's changes, 100 a connection), a join
+  of another name refused by one (`INVALID_CHANNEL_CONFIG`,
+  `TOO_MANY_CHANNELS`) waits for it and joins, instead of stopping. That can
+  happen right after a `removeChannel()`: while your sends wait their turn
+  (below), your leave waits behind them, but another channel's join goes
+  first, so that join may hear the cap once (`CHANNEL_ERROR`) before it
+  joins. Removing the last channel closes the connection: `removeChannel()`
+  then answers `{ data: null, error: null }`, and a `send()` or `track()`
+  still waiting gets `ABORTED`
+  (`The realtime connection was closed by the app (it removed its last channel) before the Naro realtime server answered.`).
+  Do not use a removed channel again: `channel()` makes a new one.
+- Presence: `track()` works on a joined channel (`NOT_JOINED` before), with a
+  JSON object of up to 10 keys and 1 KiB and no key starting with `naro_` or
+  `phx_`: the server answers a bigger one, or one with such a key,
+  `PRESENCE_TOO_LARGE`
+  (`Presence state must be a JSON object with up to 10 keys and 1 KiB, and no key starting with naro_ or phx_.`),
+  and naro-js refuses what is not a JSON object before it is sent
+  (`INVALID_MESSAGE`, `needs a presence payload object`). Each entry carries
+  `naro_user_id`, the one value the server sets. After a reconnect the last
+  state is tracked again for the same session only: after a sign-in, a
+  sign-out or a renewed session, call `track()` again in the `SUBSCRIBED`
+  callback. The last state is the last `track()` called, even one the
+  connection dropped before its answer or that had none in time; a
+  `track()` whose join went before it was sent (`NOT_JOINED`) leaves none. While a sign-in or sign-out is on its way, `track()` waits for
+  the server to take it, and an `untrack()` behind such a call waits its
+  turn, so they go in the order called (if the join goes meanwhile,
+  `track()` answers `NOT_JOINED`). The `join` and
+  `leave` callbacks get `event`, `key`, `newPresences` or `leftPresences`
+  and `currentPresences`, as in supabase-js; a join's `currentPresences` are
+  the key's presences before it. A channel that stops lets go of its presences
+  with a `leave` for each key and a `sync` before `CHANNEL_ERROR`; only
+  `unsubscribe()` clears them without a word. A channel stopped by a close
+  that does not reconnect or a join refused for good keeps what it tracked
+  for a `subscribe()` again in the same session; one the server closed lets
+  go of it — track again in `SUBSCRIBED`.
+- One connection sends 100 frames at once and then 10 a second (the server
+  closes one past 120 at once or 10 a second with 4008): more wait their
+  turn, so 70 presence channels coming back — a join and a track each —
+  take about 4 seconds. The server also closes a connection it refused 10
+  times in a minute (`TOO_MANY_JOINS`, `TOO_MANY_MESSAGES`,
+  `TOO_MANY_PRESENCE_MESSAGES`): the joins, the tracks sent again and the
+  retries naro-js makes of its own go only while those refusals in the last
+  minute and the requests sent and still waiting for an answer are fewer
+  than 6 — or, while none of naro-js's own waits for an answer, one at a
+  time while those refusals alone are fewer than 6, so your requests in
+  flight on a slow link do not keep another channel from joining. Your own
+  `send()`, `track()`, `untrack()` and `unsubscribe()` are not held for
+  refusals; they go after naro-js's own frames, which do not wait behind
+  them. A sign-in or sign-out goes before them too, but not before your
+  `track()` and `untrack()` still waiting their turn (the server would hold
+  that presence for the new user), so behind those it can wait up to
+  `timeoutMs`. One that would not go within `timeoutMs` — an app sending
+  faster than 10 a second, a cursor on every mousemove — is refused at once
+  and not sent: `CLIENT_FLOODING`
+  (`This connection is sending messages faster than a connection may (10 a second), so this one was not sent. Send less often.`)
+  with `lost: false`; send it again later. A leave is never refused.
+  `send()`, `track()` and `untrack()` also answer `lost`: `true` when the
+  connection closed before the server answered, so the message may have
+  been delivered, or not. When the server closes a connection that sent too
+  fast (4008), the calls still waiting answer `CLIENT_FLOODING`
+  (`This connection sent messages faster than a connection may.`) with
+  `lost: true`: sent again, such a message may arrive twice. Keep such sends
+  to 10 a second for all of a client's channels together.
+- Unlike supabase-js: broadcast and presence listeners match one event name
+  exactly, case included — `{ event: "*" }` hears nothing; `DELETE` events
+  pass the select policies too; a subscription takes one filter (`eq`, `neq`,
+  `lt`, `lte`, `gt`, `gte`, `in`); settings naro does not take
+  (`broadcast.replay`) are refused with `INVALID_CHANNEL_CONFIG`; `send()` and
+  the rest answer `{ data, error }` (`send()`, `track()` and `untrack()` with
+  `lost` too), not `'ok' | 'timed out' | 'error'`.
+- The service key receives every change of a published table, whatever the
+  policies say: keep it on your server (`createClient` refuses it in a
+  browser). A server that writes with `env.DB` broadcasts with
+  `POST /_naro/v1/realtime/broadcast` and the API key: up to 100 messages and
+  1 MiB, all sent or none (202).
+- `createClient({ realtime: { WebSocket, heartbeatIntervalMs, timeoutMs } })`
+  — a heartbeat every 25,000 ms and answers within 10,000 ms by default, each
+  in whole milliseconds from 1 to 2,147,483,647 (the longest a timer waits).
+  `timeoutMs` counts from when a frame goes; your own frame waits its turn
+  for about as long at most, or is refused at once (`CLIENT_FLOODING`).
+  Browsers, Deno, Bun, Cloudflare Workers and Node 22 or later have a
+  WebSocket; a runtime without one (Node 20) reports `WEBSOCKET_UNAVAILABLE`
+  until you pass `ws`'s. naro-js listens for the `error` `ws` emits when a
+  connection is closed before it opens, so that close does not end the
+  process.
+
+```ts
+import WebSocket from "ws";
+
+const naro = createClient({ url, anonKey, realtime: { WebSocket } });
+```
+
+The whole guide, with the policies, the close codes and the limits:
+https://naro.sh/docs/realtime

package/dist/auth/storage.d.ts

@@ -18,6 +18,8 @@ export declare function memoryStorage(): AuthStorage;
 export declare function defaultStorage(): AuthStorage;
 /** One token per project URL, so two clients on one page do not collide. */
 export declare function storageKey(baseUrl: string): string;
+/** The access JWT of the signed-in session, beside the session token. */
+export declare function accessJwtKey(baseUrl: string): string;
 /**
  * The PKCE verifiers of the provider sign-ins this browser began, one per
  * flow (P2-6 §6, `flows.ts`), kept where the token is.
@@ -43,13 +45,14 @@ export declare class TokenStore {
     set(token: string): Promise<void>;
     clear(): Promise<void>;
     /**
-     * Clears only if the stored token is still the one that was rejected. A
-     * request that left with an old token can come back after the user signed
-     * in again; its INVALID_SESSION must not sign the new session out. The
-     * read and the removal are one operation: with an async storage, a sign-in
-     * that lands between them would otherwise be the token removed.
+     * Clears only if the stored token is still the one that was rejected, and
+     * says whether it did. A request that left with an old token can come back
+     * after the user signed in again; its INVALID_SESSION must not sign the
+     * new session out. The read and the removal are one operation: with an
+     * async storage, a sign-in that lands between them would otherwise be the
+     * token removed.
      */
-    clearIf(token: string): Promise<void>;
+    clearIf(token: string): Promise<boolean>;
     /**
      * Reads the value, hands it to `transform` and stores what that returns
      * (null clears it), as one operation — the per-flow verifiers
@@ -58,4 +61,13 @@ export declare class TokenStore {
     update(transform: (current: string | null) => string | null): Promise<void>;
     /** Stores `next` only if `expected` is still stored, as one operation. */
     replaceIf(expected: string, next: string): Promise<void>;
+    /**
+     * Calls `listener` after every write of the token — a sign-in, a
+     * sign-out, a renewed session, a cleared INVALID_SESSION — from inside the
+     * write's turn, so a `get()` it starts reads the value just written — or
+     * that of a write already queued behind it, which calls the listener
+     * again. The Realtime connection (Realtime 3-2d) uses it to tell the hub.
+     * What a listener throws is its own: the write has happened and stands.
+     */
+    subscribe(listener: () => void): () => void;
 }

package/dist/client.d.ts

@@ -2,6 +2,8 @@ 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 type { RealtimeChannel } from "./realtime/channel.js";
+import type { RealtimeChannelOptions, RealtimeOptions, RealtimeResult } from "./realtime/types.js";
 import { StorageClient } from "./storage/client.js";
 import type { DatabaseShape, InsertOf, RowOf, TableName, TablesOf, UntypedDatabase, UpdateOf } from "./types.js";
 type CommonOptions = {
@@ -23,6 +25,12 @@ type CommonOptions = {
     };
     /** Replaces the global fetch (tests, custom runtimes). */
     fetch?: FetchLike;
+    /**
+     * Realtime (first-release design 2026-10-16 §9.1, original spec §15):
+     * the WebSocket class where the runtime has none, and the heartbeat and
+     * answer timings. Optional everywhere a WebSocket is global.
+     */
+    realtime?: RealtimeOptions;
 };
 export type ClientOptions = CommonOptions & ({
     anonKey: string;
@@ -44,6 +52,7 @@ export declare const CONFIG_MESSAGES: {
     readonly bothKeys: "Pass createClient an anonKey or a serviceKey, not both.";
     readonly serviceKeyOffServer: "A Naro service key (naro_sk_…) skips every policy, so createClient accepts it only on a server (Node, Deno, Bun, Cloudflare Workers, an edge runtime), never in a browser, a web worker or a React Native app. Use the anon key (naro_pk_…) here and keep the service key on your server.";
     readonly fetch: "This runtime has no fetch. Pass one to createClient({ fetch }).";
+    readonly realtime: "createClient's realtime options take a WebSocket class, and heartbeatIntervalMs and timeoutMs in whole milliseconds from 1 to 2147483647.";
 };
 export declare class NaroClient<Database extends DatabaseShape<Database>> {
     #private;
@@ -61,6 +70,21 @@ export declare class NaroClient<Database extends DatabaseShape<Database>> {
     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]>>;
+    /**
+     * A Realtime channel (original spec §15): `.on()` listeners, then
+     * `.subscribe()`. The same name and privacy give the same channel until
+     * `removeChannel`. Nothing connects until the first `subscribe()`.
+     */
+    channel(name: string, options?: RealtimeChannelOptions): RealtimeChannel<Database>;
+    /** The channels made with `channel()` and not yet removed. */
+    getChannels(): RealtimeChannel<Database>[];
+    /**
+     * Leaves the channel and forgets it, so `channel()` of its name makes a new
+     * one; the connection closes with the last channel.
+     */
+    removeChannel(channel: RealtimeChannel<Database>): Promise<RealtimeResult>;
+    /** `removeChannel()` for every channel; the connection closes. */
+    removeAllChannels(): Promise<RealtimeResult>;
 }
 /**
  * The one entry point (spec §15). Throws only for a configuration mistake —

package/dist/errors.d.ts

@@ -54,7 +54,77 @@ export declare function invalidProvider(): NaroError;
 export declare function serviceKeyRequired(): NaroError;
 /** No `crypto.subtle`: an http page that is not localhost. */
 export declare function cryptoUnavailable(): NaroError;
+/** The service key off a server (spec §7); `CONFIG_MESSAGES.serviceKeyOffServer` is this. */
+export declare const SERVICE_KEY_OFF_SERVER_MESSAGE = "A Naro service key (naro_sk_\u2026) skips every policy, so createClient accepts it only on a server (Node, Deno, Bun, Cloudflare Workers, an edge runtime), never in a browser, a web worker or a React Native app. Use the anon key (naro_pk_\u2026) here and keep the service key on your server.";
+/** No WebSocket in this runtime, and none passed to createClient. */
+export declare function websocketUnavailable(): NaroError;
+/**
+ * The server did not answer a join, a request or the opening in `ms`. Whole
+ * seconds, never fewer than one: a `timeoutMs` under 500 must not read
+ * "within 0 seconds".
+ */
+export declare function realtimeTimedOut(ms: number): NaroError;
+/** A drop the connection answers by connecting again. */
+export declare function realtimeClosed(code: number): NaroError;
+/**
+ * The app's own close: naro-js closes the connection when its last channel
+ * is removed, and what still waited for an answer hears this. Called off,
+ * as an upload's `signal` calls it off — not a drop, and nothing reconnects.
+ */
+export declare function realtimeDisconnected(): NaroError;
+/**
+ * A close the connection does not answer by connecting again, when the
+ * server's `system` frame did not say why first: the reason is the close's
+ * own or, with none, NETWORK_ERROR.
+ */
+export declare function realtimeStopped(code: number, reason: string): NaroError;
+/** The WebSocket constructor threw: its message quotes the URL, so only its name is kept. */
+export declare function socketRefused(error: unknown): NaroError;
+/**
+ * The hub's INVALID_CHANNEL, raised before sending (`reason` is
+ * channelNameProblem's): its words, copied from data-core's catalog.
+ */
+export declare function invalidChannel(reason: string): NaroError;
+/**
+ * The hub's INVALID_CHANNEL_CONFIG, raised before sending: for a join
+ * config JSON cannot carry (a BigInt, a cycle), which no frame could hold.
+ */
+export declare function invalidChannelConfig(path: string, reason: string): NaroError;
+/** `createClient`'s refusal of a service key off a server, for the call that reaches the socket late. */
+export declare function serviceKeyOffServer(): NaroError;
+/**
+ * The hub's NOT_JOINED, raised before sending. A name that passed
+ * channelNameProblem has at most 128 code points, which the hub quotes
+ * whole (its `realtimeName` cuts at 128), so the two read the same.
+ */
+export declare function notJoined(channel: string): NaroError;
+/** The hub's INVALID_MESSAGE for a `send` that is not a broadcast. */
+export declare function invalidBroadcast(): NaroError;
+/**
+ * The hub's INVALID_MESSAGE for a track whose state is not a JSON object,
+ * raised before sending: one JSON cannot carry (a BigInt, a cycle) would
+ * otherwise read as a connection that could not send.
+ */
+export declare function invalidPresence(): NaroError;
+/**
+ * The hub's INVALID_MESSAGE for a frame over its size limit — the plan's
+ * broadcast payload plus 16 KiB, in UTF-8 bytes — which it refuses before
+ * reading the frame's `ref` (data-core `tooLargeReason`).
+ */
+export declare function frameTooLarge(limit: number): NaroError;
+/**
+ * A frame of the app's that would not go within `timeoutMs`, at the rate
+ * the hub takes frames from one connection (`perSecond`), behind those
+ * still to go: refused here, and not sent (PR #328 re-review). The hub's own
+ * word for a connection over that rate is its 4008 close, CLIENT_FLOODING;
+ * an app that sends faster than that for long hears this instead.
+ */
+export declare function clientFlooding(perSecond: number): NaroError;
+/** The server closed a channel (`phx_close`) without saying why first. */
+export declare function channelClosed(): NaroError;
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** `{ code, message, details? }` with nothing else; null if it is not one. */
+export declare function asError(value: unknown): NaroError | null;
 /**
  * The error a response carries, or null when it carries none. Every error
  * under `/_naro/v1` comes as `{ data: null, error: { code, message,

package/dist/http.d.ts

@@ -13,6 +13,13 @@ export type HttpConfig = {
     apiKey: string;
     fetch: FetchLike | undefined;
     tokens: TokenStore;
+    /**
+     * The short-lived access JWT the sign-in answers carry. Data and Storage
+     * requests send it; the auth and Realtime routes send the session token
+     * in `tokens` (`storeFor`).
+     * Without it (not signed in) those requests go as anon.
+     */
+    accessJwt?: TokenStore;
 };
 export type CallOptions = {
     method: "GET" | "POST" | "PUT" | "DELETE";
@@ -20,6 +27,11 @@ export type CallOptions = {
     path: string;
     /** Sent as JSON. */
     body?: unknown;
+    /**
+     * Headers beside `apikey` and the JSON type — a signed upload's
+     * `x-naro-upload-token` (Storage 3-1e-2). `apikey` is always the client's.
+     */
+    headers?: Record<string, string>;
     /** Whether to send the stored session token. */
     withToken: boolean;
     /**

package/dist/index.d.ts

@@ -6,7 +6,9 @@ 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 { RealtimeChannel } from "./realtime/channel.js";
+export type { PostgresChangesEvent, PostgresChangesFilter, RealtimeBroadcastMessage, RealtimeChannelOptions, RealtimeChannelState, RealtimeOptions, RealtimePostgresChangesPayload, RealtimePresenceEntry, RealtimePresenceJoinPayload, RealtimePresenceLeavePayload, RealtimePresenceState, RealtimeResult, RealtimeSendResult, RealtimeStatus, RealtimeStatusCallback, RealtimeSystemMessage, WebSocketConstructor, } from "./realtime/types.js";
+export type { CopyOptions, CreateSignedUploadUrlOptions, DownloadOption, FileObject, FolderEntry, ListOptions, MoveOptions, MoveResult, SignedUploadResult, SignedUploadUrl, SignedUrlEntry, 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";