naro-js 0.5.0 → 0.6.0

package/dist/realtime/channel.d.ts

@@ -0,0 +1,64 @@
+import type { DatabaseShape, RowOf, TableName, TablesOf, UntypedDatabase } from "../types.js";
+import type { PostgresChangesFilter, RealtimeBroadcastMessage, RealtimeChannelOptions, RealtimeChannelState, RealtimePostgresChangesPayload, RealtimePresenceJoinPayload, RealtimePresenceLeavePayload, RealtimePresenceState, RealtimeResult, RealtimeSendResult, RealtimeStatusCallback, RealtimeSystemMessage } from "./types.js";
+/** The row type a change of `Table` carries: the generated Row, or any for `*` and untyped clients. */
+type ChangeRow<Database, Table> = Table extends TableName<Database> ? RowOf<TablesOf<Database>[Table]> : Record<string, unknown>;
+export declare function warnInDevelopment(message: string): void;
+/**
+ * One subscription as the join carries it (original spec §7.3): keys this
+ * server does not take go too, so the hub names them (결정 15); an empty
+ * filter is none.
+ */
+export declare function changeSpec(filter: PostgresChangesFilter): Record<string, unknown>;
+/** The wire's `data` (Supabase's `type`, `record`, `old_record`) as supabase-js hands it over. */
+export declare function changePayload(data: Record<string, unknown>): RealtimePostgresChangesPayload;
+export declare class RealtimeChannel<Database extends DatabaseShape<Database> = UntypedDatabase> {
+    #private;
+    readonly name: string;
+    readonly topic: string;
+    readonly isPrivate: boolean;
+    readonly options: RealtimeChannelOptions;
+    get state(): RealtimeChannelState;
+    /**
+     * A listener (original spec §15), as supabase-js names them. Row changes
+     * and presence count from the next join; broadcast and system at once.
+     */
+    on<Table extends TableName<Database> | "*" = TableName<Database> | "*">(type: "postgres_changes", filter: PostgresChangesFilter<Table>, callback: (payload: RealtimePostgresChangesPayload<ChangeRow<Database, Table>>) => void): this;
+    on(type: "broadcast", filter: {
+        event: string;
+    }, callback: (message: RealtimeBroadcastMessage) => void): this;
+    on(type: "presence", filter: {
+        event: "sync";
+    }, callback: () => void): this;
+    on(type: "presence", filter: {
+        event: "join";
+    }, callback: (payload: RealtimePresenceJoinPayload) => void): this;
+    on(type: "presence", filter: {
+        event: "leave";
+    }, callback: (payload: RealtimePresenceLeavePayload) => void): this;
+    on(type: "system", filter: Record<string, never>, callback: (message: RealtimeSystemMessage) => void): this;
+    subscribe(callback?: RealtimeStatusCallback): this;
+    unsubscribe(): Promise<RealtimeResult>;
+    /**
+     * Broadcasts `message` on the join, or over HTTP before it: the server's
+     * answer, `lost` when the connection went before it (RealtimeSendResult).
+     */
+    send(message: RealtimeBroadcastMessage): Promise<RealtimeSendResult>;
+    /**
+     * Tracks `state` as this connection's presence here (original spec
+     * §11.1): the hub's answer. Only on a join — before it, NOT_JOINED, and
+     * nothing is kept for later (결정 18). It goes as its JSON reads back, and
+     * that copy, not the app's object, is what a later join sends again.
+     * While who the connection is is not settled (a new token in flight, a
+     * retry), it waits until it is (정정 (k)): the hub may yet refuse the new
+     * token for now and keep the last user, whose presence it would be.
+     */
+    track(state: Record<string, unknown>): Promise<RealtimeSendResult>;
+    /**
+     * Takes this connection's presence off the channel: the hub's answer, or
+     * none when not joined. After the app's tracks that wait, if any.
+     */
+    untrack(): Promise<RealtimeSendResult>;
+    /** The presences of the channel, by key (결정 16): a copy. */
+    presenceState(): RealtimePresenceState;
+}
+export {};

package/dist/realtime/client.d.ts

@@ -0,0 +1,18 @@
+import type { AuthClient } from "../auth/client.js";
+import type { HttpConfig } from "../http.js";
+import type { DatabaseShape, UntypedDatabase } from "../types.js";
+import { RealtimeChannel } from "./channel.js";
+import type { RealtimeChannelOptions, RealtimeOptions, RealtimeResult } from "./types.js";
+export declare class RealtimeClient<Database extends DatabaseShape<Database> = UntypedDatabase> {
+    #private;
+    constructor(input: {
+        http: HttpConfig;
+        auth: AuthClient;
+        service: boolean;
+        options: RealtimeOptions;
+    });
+    channel(name: string, options?: RealtimeChannelOptions): RealtimeChannel<Database>;
+    getChannels(): RealtimeChannel<Database>[];
+    removeChannel(channel: RealtimeChannel<Database>): Promise<RealtimeResult>;
+    removeAllChannels(): Promise<RealtimeResult>;
+}

package/dist/realtime/close.d.ts

@@ -0,0 +1,44 @@
+/** 1, 2, 5, then 10 seconds, each times 0.5–1.5 (original spec §15). */
+export declare const BACKOFF_STEPS_MS: readonly [1000, 2000, 5000, 10000];
+/** 4029's floor: a refused client must not knock faster (design §8.5). */
+export declare const RATE_LIMITED_MIN_MS = 5000;
+/** The dispatcher's per-address window is a fixed minute (3-2c-2 결정 9). */
+export declare const IP_LIMIT_WAIT_MS = 60000;
+/**
+ * A restart closes everyone at once, so every 4503 return waits 0–10 s (design
+ * D6). The wait does not grow with the attempt count or the unopened tries:
+ * during a lasting BACKEND_UNAVAILABLE a client comes back about every 5 s on
+ * average, without slowing down.
+ */
+export declare const RESTART_JITTER_MS = 10000;
+/** Tries in a row that never opened before the client slows down (known-issues #271). */
+export declare const UNOPENED_SLOWDOWN_AFTER = 6;
+export declare const UNOPENED_DELAY_MS = 60000;
+export type CloseAction = {
+    kind: "stop";
+} | {
+    kind: "retry";
+    minMs: number;
+} | {
+    kind: "session";
+} | {
+    kind: "restart";
+} | {
+    kind: "wait";
+    ms: number;
+};
+/**
+ * `reason` is the close's reason, or the code of the `system` frame sent
+ * just before it — the two are the same string (data-core `closeFrame`, the
+ * dispatcher's `realtime-refuse.ts`). A code this table does not know is
+ * tried again like 4500: a server newer than this SDK can always refuse again.
+ */
+export declare function closeAction(code: number, reason: string): CloseAction;
+export declare function backoffMs(attempt: number, random: () => number): number;
+/** How long to wait before the next try after `action`. */
+export declare function delayAfter(action: Exclude<CloseAction, {
+    kind: "stop";
+}>, state: {
+    attempt: number;
+    unopened: number;
+}, random: () => number): number;

package/dist/realtime/identity.d.ts

@@ -0,0 +1,68 @@
+import type { TokenStore } from "../auth/storage.js";
+import { type RealtimeSocket } from "./socket.js";
+export type IdentityConfig = {
+    tokens: TokenStore;
+    accessJwt: TokenStore | undefined;
+    service: boolean;
+    socket: () => RealtimeSocket;
+    /** Private channels the connection holds: each is judged again on a change. */
+    privateChannels: () => number;
+    /**
+     * The connection is live (`isLive()`) again: the joins that waited may go.
+     * Called whenever it becomes live — on every connection, and after every
+     * store read that ended in a settled identity — whether or not anything
+     * changed (a write of the same value, a retry with nothing to tell) and
+     * whether or not the hub took it (a refusal not tried again settles it
+     * too). The receiver must be idempotent.
+     */
+    onLive: () => void;
+    /**
+     * `auth.ready()`: resolves once a sign-in the page URL carried has been
+     * traded for its session (or failed). Each read of the store waits for it.
+     */
+    ready: () => Promise<unknown>;
+};
+/** A connection may change its token as fast as its private channels are judged again: 100 at once, then 2 a second (3-2c-1). */
+export declare function rejudgeWaitMs(privateChannels: number): number;
+export declare class Identity {
+    #private;
+    constructor(config: IdentityConfig);
+    /** The token the hub took on this connection; null for anon or before its answer. */
+    confirmed(): string | null;
+    /**
+     * The token the hub will hold once what was sent is handled — the last
+     * frame in flight, or else the one it took: the hub handles the
+     * connection's frames in order, so a frame sent now is judged for it.
+     * A frame in flight may yet be refused; the hub then keeps `confirmed()`.
+     */
+    heldToken(): string | null;
+    /**
+     * Nothing about who the connection is is pending — no read, no frame in
+     * flight, no retry, no refusal: a join sent now is judged for the identity
+     * the hub settled on, the stored one unless it refused that for good on
+     * this connection (결정 24).
+     */
+    isLive(): boolean;
+    /**
+     * A new connection: anon until told. Resolves once the stored token is
+     * sent, or found to need no frame; `onLive` says when the hub took it.
+     */
+    opened(): Promise<void>;
+    /** The stored token may have changed: tell the open connection what is new. */
+    changed(): Promise<void>;
+    /**
+     * A 4401: forget the stored session only if the hub answered
+     * INVALID_SESSION to it by name, and it is still stored — a sign-in since
+     * then keeps its new token (결정 3). A 4401 with no such answer clears
+     * nothing (plan 2026-10-28 정정): the hub keeps the expiry it read when it
+     * took the token (known-issues #183) while the backend's sign-in slides
+     * the session's under the same token, so a tab open for days is closed
+     * with a session that is still good. The next connection tells the token
+     * again, and hears INVALID_SESSION — and clears it — if it really is
+     * dead. The access JWT goes with the session it was minted for, so only
+     * when that session went.
+     */
+    refused(): Promise<void>;
+    /** The connection is gone: what it was told is forgotten. */
+    closed(): void;
+}

package/dist/realtime/presence.d.ts

@@ -0,0 +1,27 @@
+import type { RealtimePresenceEntry, RealtimePresenceState } from "./types.js";
+/**
+ * What join and leave say, as supabase-js's RealtimePresence does: a join's
+ * `currentPresences` are what the key held before it (none for a key's
+ * first), a leave's what it holds after it (plan 정정 (j)).
+ */
+export type PresenceEmit = {
+    join(key: string, newPresences: RealtimePresenceEntry[], currentPresences: RealtimePresenceEntry[]): void;
+    leave(key: string, leftPresences: RealtimePresenceEntry[], currentPresences: RealtimePresenceEntry[]): void;
+    sync(): void;
+};
+export declare class Presence {
+    #private;
+    state(): RealtimePresenceState;
+    /** A new join, or the connection dropped: what is here stays until its presence_state. */
+    unsync(): void;
+    clear(): void;
+    /**
+     * No presence_state will say what is here any more (a join that may not
+     * read presence, one refused, the server's close, a stop — plan 정정
+     * (k)): each key leaves, then sync — said only when someone was here. A
+     * diff waits for the next presence_state.
+     */
+    leaveAll(emit: PresenceEmit): void;
+    applyState(payload: unknown, emit: PresenceEmit): void;
+    applyDiff(payload: unknown, emit: PresenceEmit): void;
+}

package/dist/realtime/protocol.d.ts

@@ -0,0 +1,78 @@
+export declare const REALTIME_PROTOCOL_VERSION = "1.0.0";
+export declare const PHOENIX_TOPIC = "phoenix";
+export declare const REALTIME_TOPIC_PREFIX = "realtime:";
+/**
+ * The heartbeat byte for byte: the runtime answers exactly this for the hub
+ * (`setWebSocketAutoResponse`), so it never wakes a hibernating hub. Any other
+ * spelling is an ordinary frame that wakes it every 25 seconds.
+ */
+export declare const HEARTBEAT_REQUEST = "{\"topic\":\"phoenix\",\"event\":\"heartbeat\",\"payload\":{},\"ref\":\"hb\"}";
+export declare const HEARTBEAT_REF = "hb";
+export declare const MAX_CHANNEL_NAME_LENGTH = 128;
+/**
+ * One connection's frame bucket on the hub (data-core realtime-limits.ts):
+ * 10 a second, 120 deep, full at the open. A frame over it closes the
+ * connection with 4008 (CLIENT_FLOODING); the heartbeat does not count —
+ * the runtime answers it. socket.ts paces its frames to it.
+ */
+export declare const CONNECTION_FRAMES_PER_SECOND = 10;
+export declare const CONNECTION_FRAME_BURST = 120;
+/**
+ * The refusals the hub warns a connection for beside the refusal — the
+ * project's joins, message and presence budgets (its `warn`: `tooManyJoins`,
+ * also for its queue of ordered frames full, and the broadcast and presence
+ * handlers) — and `FLOOD_WARNINGS` of them within `FLOOD_WINDOW_MS` close the
+ * connection with 4008 (data-core realtime-limits.ts). wire.test.ts reads
+ * the hub's source for every warning it gives.
+ */
+export declare const WARNED_CODES: ReadonlySet<string>;
+export declare const FLOOD_WARNINGS = 10;
+export declare const FLOOD_WINDOW_MS = 60000;
+/** The most channels of one connection on one table's changes, `*` on every table (3-2c-1). */
+export declare const MAX_CHANGE_CHANNELS_PER_TABLE = 4;
+/**
+ * The hub's INVALID_CHANNEL_CONFIG reason at `config.postgres_changes[<i>].table`
+ * for a join over `MAX_CHANGE_CHANNELS_PER_TABLE` (data-core
+ * `JOIN_CONFIG_REASONS.changeChannels`): a cap a leave still owed may hold a
+ * place under (channel.ts).
+ */
+export declare const CHANGE_CHANNELS_REASON: string;
+/** One frame of the server, its fields checked; anything else is null. */
+export type ServerFrame = {
+    topic: string;
+    event: string;
+    payload: Record<string, unknown>;
+    ref: string | null;
+    /** The join a channel frame is about (3-2a P11); null on the phoenix topic. */
+    joinRef: string | null;
+};
+export declare function readServerFrame(data: unknown): ServerFrame | null;
+/**
+ * The limit a size refusal names (data-core `tooLargeReason`: "is larger
+ * than N bytes"), or null for any other reason. The hub measures a frame
+ * before it reads it, so this refusal comes on the phoenix topic with no
+ * `ref` (`parseClientFrame`); the SDK matches it to its frames by size.
+ */
+export declare function frameLimitOf(reason: unknown): number | null;
+/**
+ * A text's length in UTF-8 bytes, as the hub measures a frame: a copy of
+ * data-core's `utf8ByteLength` (values.ts) — a lone surrogate is 3 bytes.
+ */
+export declare function utf8Length(text: string): number;
+/** One client frame as text; channel frames carry their join's `join_ref`. */
+export declare function clientFrame(topic: string, event: string, payload: Record<string, unknown>, ref: string | null, joinRef?: string): string;
+/**
+ * Why a channel name is not valid, as `INVALID_CHANNEL`'s reason: it
+ * finishes "The channel name is not valid: it …". The name is measured in
+ * code points and kept as it is — no trimming, no Unicode normalisation —
+ * but the characters that make a name look like another (control and
+ * bidirectional marks) are refused. A control character is reported before
+ * a bidirectional one wherever they stand.
+ */
+export declare function channelNameProblem(name: string): string | undefined;
+/**
+ * The connection's URL (original spec §6.3): a browser's WebSocket cannot
+ * send headers, so the key rides in the query, encoded. Nothing logs it;
+ * an error never quotes it (socket.ts).
+ */
+export declare function socketUrl(baseUrl: string, apiKey: string): string;

package/dist/realtime/socket.d.ts

@@ -0,0 +1,96 @@
+import { type NaroError } from "../errors.js";
+import { type ServerFrame } from "./protocol.js";
+import type { RealtimeOptions } from "./types.js";
+export type Reply = {
+    ok: true;
+    response: Record<string, unknown>;
+} | {
+    ok: false;
+    error: NaroError;
+    lost: boolean;
+};
+export type SocketEvents = {
+    /** Open: client.ts sends the identity first, then the joins. */
+    opened(): void;
+    /** A frame no request waits for (channel frames). */
+    frame(frame: ServerFrame): void;
+    /** Closed, and coming back after a wait. */
+    dropped(error: NaroError, status: "CHANNEL_ERROR" | "TIMED_OUT"): void;
+    /** Closed for good, until a channel subscribes again. */
+    stopped(error: NaroError): void;
+    /** A 4401: the conditional delete; the wait begins when it is done, or after `timeoutMs`. */
+    sessionRefused(): Promise<void>;
+};
+export type SocketConfig = {
+    baseUrl: string;
+    apiKey: string;
+    service: boolean;
+    options: RealtimeOptions;
+    events: SocketEvents;
+};
+/**
+ * Whose frame a request is, which sets its turn (`request()`): the app's
+ * call (the default), behind the frames waiting and refused when it would
+ * not go within `timeoutMs`; a frame the SDK sends of its own accord, before
+ * the app's; the identity's `access_token`, the same, but after the app's
+ * presence frames still to go.
+ */
+export type Turn = "app" | "sdk" | "identity";
+/**
+ * Runs a handler: what it throws is thrown again on its own (결정 22), and
+ * the caller goes on — a socket mid-close, a timer, a promise's handler.
+ */
+export declare function safely(callback: () => void): void;
+export declare class RealtimeSocket {
+    #private;
+    constructor(config: SocketConfig);
+    get generation(): number;
+    get timeoutMs(): number;
+    isOpen(): boolean;
+    nextRef(): string;
+    /**
+     * Opens unless a connection is open, opening or due — once the wait the
+     * last close or stop set is over. After the app's own close the counts
+     * start over; after a stop they go on, as after a drop.
+     */
+    connect(): void;
+    /** The last channel went: close for good, with no event. */
+    disconnect(): void;
+    /**
+     * Lets go of the open connection and comes back as after a drop (1006),
+     * the channels told: for a connection that holds an identity the app no
+     * longer means and cannot change (identity.ts). Nothing unless open.
+     */
+    reconnect(): void;
+    /**
+     * The hub answered this connection: the next drop waits from the first
+     * step — unless the last close was 4008 and no heartbeat was answered
+     * since (`#flooded`).
+     */
+    served(): void;
+    /**
+     * A frame, in its `turn` (the app's unless said), and the `phx_reply`
+     * with its `ref` within `timeoutMs` of when it went — or, for one over the
+     * size limit the hub named on this connection, that refusal at once and
+     * nothing sent; for an app's frame but a leave that would not go within
+     * `timeoutMs`, CLIENT_FLOODING at once and nothing sent.
+     */
+    request(topic: string, event: string, payload: Record<string, unknown>, options?: {
+        joinRef?: string;
+        ref?: string;
+        turn?: Turn;
+    }): Promise<Reply>;
+    /**
+     * Runs `go` once a frame the SDK sends of its own accord may go: at once
+     * when nothing waits before it and there is room — the warnings of the
+     * last minute and the requests in flight fewer than `SDK_WARNING_ROOM`
+     * (the app's frames still waiting their turn are not in flight yet, and
+     * go after the SDK's), or the warnings fewer and none of the SDK's own
+     * unanswered — or else when there is, in the order asked. The
+     * frame itself is sent with `turn: "sdk"`. `key` names the sender:
+     * asked again before it ran, it keeps its place and runs the newer `go`,
+     * which reads its own state again then. Nothing while the connection is
+     * not open, and forgotten with it: the sender tries again when it is live.
+     */
+    whenRoom(key: object, go: () => void): void;
+}

package/dist/realtime/types.d.ts

@@ -0,0 +1,89 @@
+import type { NaroError } from "../errors.js";
+/** What `subscribe`'s callback hears (original spec §15). */
+export type RealtimeStatus = "SUBSCRIBED" | "CHANNEL_ERROR" | "TIMED_OUT" | "CLOSED";
+export type RealtimeChannelState = "closed" | "joining" | "joined" | "leaving" | "errored";
+export type RealtimeStatusCallback = (status: RealtimeStatus, error?: NaroError) => void;
+export type RealtimeResult = {
+    data: null;
+    error: NaroError | null;
+};
+/**
+ * What `send()`, `track()` and `untrack()` answer. `lost` is true when the
+ * connection closed before the server answered: the frame may have been
+ * delivered, or not. So `CLIENT_FLOODING` with `lost: false` was refused
+ * here and not sent — send it again later — and with `lost: true` the
+ * server closed the connection (4008) and this one may have gone through.
+ */
+export type RealtimeSendResult = RealtimeResult & {
+    lost: boolean;
+};
+export type RealtimeChannelOptions = {
+    config?: {
+        private?: boolean;
+        broadcast?: {
+            self?: boolean;
+            ack?: boolean;
+        };
+        presence?: {
+            key?: string;
+            enabled?: boolean;
+        };
+    };
+};
+export type PostgresChangesEvent = "*" | "INSERT" | "UPDATE" | "DELETE";
+export type PostgresChangesFilter<Table extends string = string> = {
+    event: PostgresChangesEvent;
+    schema?: "public";
+    table?: Table | "*";
+    filter?: string;
+};
+export type RealtimePostgresChangesPayload<Row extends object = Record<string, unknown>> = {
+    schema: "public";
+    table: string;
+    commit_timestamp: string;
+    eventType: "INSERT" | "UPDATE" | "DELETE";
+    new: Row | Record<string, never>;
+    old: Partial<Row>;
+    errors: string[] | null;
+};
+export type RealtimeBroadcastMessage = {
+    type: "broadcast";
+    event: string;
+    payload: Record<string, unknown>;
+};
+/** BULK_CHANGE, EVENTS_DROPPED and the reason a channel closed (original spec §7.4). */
+export type RealtimeSystemMessage = {
+    status: "ok" | "error";
+    extension: string;
+    code: string;
+    message: string;
+    channel: string | null;
+};
+export type RealtimePresenceEntry = Record<string, unknown> & {
+    presence_ref: string;
+    /** The signed-in user who tracked it, or null: the one value the server sets. */
+    naro_user_id: string | null;
+};
+export type RealtimePresenceState = Record<string, RealtimePresenceEntry[]>;
+/** A presence join as supabase-js's listeners hear it. */
+export type RealtimePresenceJoinPayload = {
+    event: "join";
+    key: string;
+    newPresences: RealtimePresenceEntry[];
+    /** What the key held before this join, as supabase-js says it; [] for its first. */
+    currentPresences: RealtimePresenceEntry[];
+};
+export type RealtimePresenceLeavePayload = {
+    event: "leave";
+    key: string;
+    leftPresences: RealtimePresenceEntry[];
+    /** What the key holds after this leave; [] when it was the last. */
+    currentPresences: RealtimePresenceEntry[];
+};
+/** The global WebSocket, or `ws`'s: any class built from a URL. */
+export type WebSocketConstructor = new (url: string) => unknown;
+export type RealtimeOptions = {
+    WebSocket?: WebSocketConstructor;
+    heartbeatIntervalMs?: number;
+    timeoutMs?: number;
+};

package/dist/storage/client.d.ts

@@ -1,7 +1,7 @@
 import type { AuthClient } from "../auth/client.js";
 import { type HttpConfig } from "../http.js";
 import type { NaroResponse } from "../types.js";
-import type { CreateSignedUploadUrlOptions, DownloadOption, FileObject, FolderEntry, ListOptions, SignedUploadResult, SignedUploadUrl, SignedUrlEntry, UpdateOptions, UploadBody, UploadOptions, UploadResult } from "./types.js";
+import type { CopyOptions, CreateSignedUploadUrlOptions, DownloadOption, FileObject, FolderEntry, ListOptions, MoveOptions, MoveResult, SignedUploadResult, SignedUploadUrl, SignedUrlEntry, UpdateOptions, UploadBody, UploadOptions, UploadResult } from "./types.js";
 /** One bucket's objects: supabase-js's StorageFileApi. */
 export declare class StorageFileApi {
     #private;
@@ -40,9 +40,33 @@ export declare class StorageFileApi {
     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[]>>;
+    /**
+     * Renames an object inside its bucket (Storage 3-1i): the same object — its
+     * id and owner — under `toPath`, its old name gone. It never replaces an
+     * object that is there (`OBJECT_EXISTS`), takes files up to 5 GiB − 5 MiB
+     * (`OBJECT_TOO_LARGE`), and needs room in the project for a second copy
+     * until it is done (`STORAGE_QUOTA_EXCEEDED`). Its signed links stop
+     * working at the old name: a link is bound to the name, the object's id
+     * and its bytes, so moving it back can open them again. A backend whose
+     * Storage was turned on before this method came answers `NOT_FOUND`:
+     * update it with `naro backend enable`.
+     */
+    move(fromPath: string, toPath: string, options?: MoveOptions): Promise<NaroResponse<MoveResult>>;
+    /**
+     * Copies an object inside its bucket (Storage 3-1i): the source's bytes,
+     * type and cache-control under `toPath` — a new object of the caller's,
+     * or with `upsert: true` the one that is there, which keeps its owner.
+     * Files up to 5 GiB − 5 MiB, within the bucket's limits as they are now.
+     * It answers `{ id, path, fullPath }` — `path` is the name inside the
+     * bucket; supabase-js's copy puts the bucket in front of it. A backend
+     * whose Storage was turned on before this method came answers
+     * `NOT_FOUND`: update it with `naro backend enable`.
+     */
+    copy(fromPath: string, toPath: string, options?: CopyOptions): Promise<NaroResponse<UploadResult>>;
     /**
      * A link to the object for `expiresIn` seconds (1–604,800). It stops
-     * working once the object is replaced or removed.
+     * working once the object is replaced or removed, and while the object is
+     * moved away from `path` (moved back, it can open it again).
      */
     createSignedUrl(path: string, expiresIn: number, options?: DownloadOption): Promise<NaroResponse<{
         signedUrl: string;

package/dist/storage/types.d.ts

@@ -115,3 +115,22 @@ export type SignedUrlEntry = {
     signedUrl: string | null;
     error: string | null;
 };
+/** `move`'s options (Storage 3-1i): supabase-js's. */
+export type MoveOptions = {
+    /**
+     * Taken as supabase-js sends it. Objects move within one bucket: another
+     * bucket answers `INVALID_REQUEST` (`details.path` "destinationBucket").
+     */
+    destinationBucket?: string;
+};
+/** `copy`'s options (Storage 3-1i). */
+export type CopyOptions = {
+    /** As `MoveOptions`'s: one bucket only. */
+    destinationBucket?: string;
+    /** Replace an object at the destination. Default false: `OBJECT_EXISTS`. */
+    upsert?: boolean;
+};
+/** What `move` answers: supabase-js's words. */
+export type MoveResult = {
+    message: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naro-js",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Auth, data and files for your Naro project, from the browser or the server.",
   "type": "module",
   "sideEffects": false,
@@ -23,8 +23,8 @@
     "tsup": "8.5.0",
     "typescript": "7.0.2",
     "vitest": "3.2.7",
-    "@next-deploy/config": "0.1.0",
     "@next-deploy/backend-worker": "0.1.0",
+    "@next-deploy/config": "0.1.0",
     "@next-deploy/data-core": "0.1.0",
     "@next-deploy/sdk": "0.1.0"
   },