naro-js 0.1.0 → 0.3.0

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/path.d.ts

@@ -0,0 +1,76 @@
+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 refuses first.
+ */
+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 tooLarge: "Uploads over 50 MiB are not supported yet.";
+    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;
+export declare function objectTooLarge(): 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;
+/** 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,58 @@
+/** 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;
+};
+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/dist/types.d.ts

@@ -81,10 +81,19 @@ export type OrderOptions = {
     /** Where NULLs go. Omitted, SQLite's default: first ascending, last descending. */
     nullsFirst?: boolean;
 };
-/** Better Auth's user (spec §13), as JSON: dates are ISO strings. */
+/**
+ * The signed-in user, as naro Auth answers it (spec §13): dates are ISO
+ * strings. `email` is null for a user created with only a username
+ * (`auth.admin.createUser({ username, password })`).
+ */
 export type User = {
     id: string;
-    email: string;
+    email: string | null;
+    /**
+     * Lowercased; null for a user without one. Absent from a backend whose
+     * Naro worker predates usernames (`naro backend enable` updates it).
+     */
+    username?: string | null;
     name: string;
     emailVerified: boolean;
     image?: string | null;
@@ -92,7 +101,7 @@ export type User = {
     updatedAt: string;
     [field: string]: unknown;
 };
-/** Better Auth's session, as JSON. */
+/** The session, as naro Auth answers it. */
 export type Session = {
     id: string;
     userId: string;
@@ -124,7 +133,16 @@ export type SignOutResponse = {
 export type SignUpCredentials = {
     email: string;
     password: string;
-    /** Better Auth requires a name; omitted, the email's local part is sent. */
+    /**
+     * A name to sign in by as well as the email (spec 2026-09-26 §2.3): 3–30
+     * letters, digits, `_` and `.`, stored lowercased. One that is taken
+     * answers 409 USERNAME_TAKEN.
+     */
+    username?: string;
+    /**
+     * Every user has a display name; omitted, the username is sent, or else
+     * the email's local part.
+     */
     name?: string;
     /**
      * Where the confirmation link sends the browser back to, when the project
@@ -133,8 +151,17 @@ export type SignUpCredentials = {
      */
     redirectTo?: string;
 };
+/**
+ * An email and its password, or a username and its password (spec
+ * 2026-09-26 §2.3). A username is matched in any case.
+ */
 export type SignInCredentials = {
     email: string;
+    username?: undefined;
+    password: string;
+} | {
+    username: string;
+    email?: undefined;
     password: string;
 };
 export type OAuthProvider = "google" | "github";
@@ -183,4 +210,59 @@ export type AuthActionResponse = {
     data: null;
     error: NaroError | null;
 };
+/**
+ * A user as `naro.auth.admin` answers it — never a password or a hash.
+ * `email` is null for a user created with only a username.
+ */
+export type AdminUser = {
+    id: string;
+    email: string | null;
+    /** Lowercased; null for a user without one. */
+    username: string | null;
+    emailVerified: boolean;
+    /** ISO 8601. */
+    createdAt: string;
+};
+/**
+ * `auth.admin.createUser()`: an email, a username or both, and a password
+ * of at least the project's minimum length (6 unless
+ * `naro backend auth password --min-length` changed it). The user is
+ * confirmed — signs in at once, even where sign-in waits for a confirmed
+ * email — unless `emailConfirm: false`, which needs an email. (Supabase's
+ * `email_confirm` is false by default; here confirmed is the default.)
+ */
+export type AdminUserAttributes = {
+    email?: string;
+    username?: string;
+    password: string;
+    emailConfirm?: boolean;
+};
+/** `auth.admin.listUsers()`: page 1 and 50 a page unless given; at most 1000. */
+export type PageParams = {
+    page?: number;
+    perPage?: number;
+};
+export type AdminUserResponse = AuthResponse<{
+    user: AdminUser | null;
+}>;
+/** A page of users, newest first, and how many there are in all. */
+export type AdminUserListResponse = AuthResponse<{
+    users: AdminUser[];
+    total: number;
+}>;
+/**
+ * The codes sign-up, sign-in and `auth.admin` answer that an app branches
+ * on. `NaroError.code` can be any other string too.
+ */
+export type AuthErrorCode = 
+/** Sign-ups are closed: only `auth.admin.createUser` makes users. */
+"SIGNUPS_DISABLED"
+/** Sign-up or `createUser` with a username someone has, in any case. */
+ | "USERNAME_TAKEN" | "USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL"
+/** "Use at least {n} characters." — the project's minimum. */
+ | "PASSWORD_TOO_SHORT" | "PASSWORD_TOO_LONG" | "USERNAME_TOO_SHORT" | "USERNAME_TOO_LONG" | "INVALID_USERNAME" | "INVALID_EMAIL" | "INVALID_EMAIL_OR_PASSWORD" | "INVALID_USERNAME_OR_PASSWORD" | "EMAIL_NOT_VERIFIED" | "INVALID_SESSION"
+/** `auth.admin` without the service key. */
+ | "PERMISSION_DENIED"
+/** `auth.admin.deleteUser` with an id that is no user. */
+ | "USER_NOT_FOUND" | "RATE_LIMITED" | "WRITE_QUOTA_EXCEEDED";
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "naro-js",
-  "version": "0.1.0",
-  "description": "Auth and data for your Naro project, from the browser or the server.",
+  "version": "0.3.0",
+  "description": "Auth, data and files for your Naro project, from the browser or the server.",
   "type": "module",
   "sideEffects": false,
   "files": [
@@ -25,8 +25,8 @@
     "vitest": "3.2.7",
     "@next-deploy/backend-worker": "0.1.0",
     "@next-deploy/config": "0.1.0",
-    "@next-deploy/sdk": "0.1.0",
-    "@next-deploy/data-core": "0.1.0"
+    "@next-deploy/data-core": "0.1.0",
+    "@next-deploy/sdk": "0.1.0"
   },
   "scripts": {
     "build": "tsup && pnpm build:types",