naro-js 0.1.0

package/dist/query/builder.d.ts

@@ -0,0 +1,211 @@
+import { type NaroError } from "../errors.js";
+import type { ColumnName, FilterValue, NaroResponse, OrderOptions } from "../types.js";
+import type { FilterNode, Order, Query, Returning, Row as WireRow } from "../wire.js";
+import { type FilterOperatorName } from "./filters.js";
+import type { ColumnList, Selected } from "./selected.js";
+/**
+ * Spec §9: the most rows one select reads, whether by `limit` or `range`.
+ * data-core's MAX_LIMIT; `wire.test.ts` checks that the two agree.
+ */
+export declare const MAX_LIMIT = 1000;
+/** Sends a finished AST and reads `{ data }` or `{ error }` (see client.ts). */
+export type Runner = (query: Query) => Promise<NaroResponse<unknown>>;
+/**
+ * Everything a chain has said so far. Builders never change it: each call
+ * returns a new builder holding a new state, so a builder kept in a variable
+ * and extended twice gives two independent queries (spec §15: thenable
+ * builders; reuse must not leak filters).
+ */
+type State = {
+    table: string;
+    /** The first mistake the builder caught; the query is answered with it. */
+    problem: NaroError | null;
+    filters: readonly FilterNode[];
+    columns: string[] | "*";
+    order: readonly Order[];
+    limit?: number;
+    offset?: number;
+    single?: "one" | "maybe";
+    action?: "update" | "delete";
+    rows?: WireRow[];
+    values?: WireRow;
+    returning?: Returning;
+    allowUnfiltered?: true;
+};
+declare abstract class Builder<Result> implements PromiseLike<NaroResponse<Result>> {
+    protected readonly run: Runner;
+    protected readonly state: State;
+    constructor(run: Runner, state: State);
+    protected abstract build(): Query;
+    /** A new builder of the same kind with `patch` applied. */
+    protected next(patch: Partial<State>): this;
+    protected fail(path: string, reason: string): this;
+    /** Keeps the first problem: it is the one the user has to fix first. */
+    protected failWith(problem: NaroError): this;
+    /**
+     * Runs the query. Every `await` sends a new request with the same AST.
+     * Never rejects: failures resolve as `{ data: null, error }`.
+     */
+    then<Fulfilled = NaroResponse<Result>, Rejected = never>(onfulfilled?: ((value: NaroResponse<Result>) => Fulfilled | PromiseLike<Fulfilled>) | null, onrejected?: ((reason: unknown) => Rejected | PromiseLike<Rejected>) | null): Promise<Fulfilled | Rejected>;
+    private execute;
+    /** A mutation's `.select()`: RETURNING these columns. */
+    protected withReturning(columns: string | undefined): this;
+}
+/** What `.or()`, `.and()` and `.not()` hand a callback, and want back. */
+export type FilterGroupCallback<Row> = (group: FilterGroup<Row>) => FilterGroup<Row>;
+/**
+ * The filter methods, on every select, update and delete — and on the `q` of
+ * `.or((q) => …)`, `.and((q) => …)` and `.not((q) => …)`, where the
+ * conditions `q` collects become the group's (Phase 2-1, spec P2-1 §4).
+ */
+export interface FilterGroup<Row> {
+    eq(column: ColumnName<Row>, value: FilterValue): FilterGroup<Row>;
+    neq(column: ColumnName<Row>, value: FilterValue): FilterGroup<Row>;
+    gt(column: ColumnName<Row>, value: FilterValue): FilterGroup<Row>;
+    gte(column: ColumnName<Row>, value: FilterValue): FilterGroup<Row>;
+    lt(column: ColumnName<Row>, value: FilterValue): FilterGroup<Row>;
+    lte(column: ColumnName<Row>, value: FilterValue): FilterGroup<Row>;
+    in(column: ColumnName<Row>, values: readonly FilterValue[]): FilterGroup<Row>;
+    is(column: ColumnName<Row>, value: boolean | null): FilterGroup<Row>;
+    like(column: ColumnName<Row>, pattern: string): FilterGroup<Row>;
+    ilike(column: ColumnName<Row>, pattern: string): FilterGroup<Row>;
+    contains(column: ColumnName<Row>, values: ArrayValues): FilterGroup<Row>;
+    containedBy(column: ColumnName<Row>, values: ArrayValues): FilterGroup<Row>;
+    overlaps(column: ColumnName<Row>, values: ArrayValues): FilterGroup<Row>;
+    match(query: MatchQuery<Row>): FilterGroup<Row>;
+    filter(column: ColumnName<Row>, operator: FilterOperatorName | `not.${FilterOperatorName}`, value: RawFilterValue): FilterGroup<Row>;
+    not(column: ColumnName<Row>, operator: FilterOperatorName, value: RawFilterValue): FilterGroup<Row>;
+    not(group: FilterGroupCallback<Row>): FilterGroup<Row>;
+    or(filters: string | FilterGroupCallback<Row>): FilterGroup<Row>;
+    and(filters: string | FilterGroupCallback<Row>): FilterGroup<Row>;
+}
+/** What `contains`, `containedBy` and `overlaps` compare with: strings and numbers. */
+export type ArrayValues = readonly (string | number)[];
+/** `.match({ column: value, … })`: an `eq` for each. */
+export type MatchQuery<Row> = {
+    [Column in ColumnName<Row>]?: FilterValue;
+};
+/**
+ * A value for `.filter()` and `.not()`: a value or a list, or a string in
+ * PostgREST's syntax where the operator needs one (`"(1,2)"` for `in`,
+ * `"{a,b}"` for `cs`, `"null"` for `is`).
+ */
+export type RawFilterValue = FilterValue | readonly FilterValue[];
+declare abstract class FilterBuilder<Row, Result> extends Builder<Result> implements FilterGroup<Row> {
+    /** One more entry in the top-level list, which is an AND. */
+    private add;
+    private condition;
+    eq(column: ColumnName<Row>, value: FilterValue): this;
+    neq(column: ColumnName<Row>, value: FilterValue): this;
+    gt(column: ColumnName<Row>, value: FilterValue): this;
+    gte(column: ColumnName<Row>, value: FilterValue): this;
+    lt(column: ColumnName<Row>, value: FilterValue): this;
+    lte(column: ColumnName<Row>, value: FilterValue): this;
+    /** An empty list matches nothing. */
+    in(column: ColumnName<Row>, values: readonly FilterValue[]): this;
+    /** `IS NULL`, `IS TRUE` or `IS FALSE` — any non-zero number is true, NULL neither. */
+    is(column: ColumnName<Row>, value: boolean | null): this;
+    /**
+     * Case-sensitive, `%` and `_` as in SQL; `*` is `%` too, as in PostgREST,
+     * so a literal `*` cannot be matched.
+     */
+    like(column: ColumnName<Row>, pattern: string): this;
+    /** Case-insensitive for ASCII letters; `%`, `_` and `*` as in `like`. */
+    ilike(column: ColumnName<Row>, pattern: string): this;
+    /**
+     * The column — TEXT holding a JSON array — has every one of the values.
+     * A row that is not a JSON array is no match; NULL is neither.
+     */
+    contains(column: ColumnName<Row>, values: ArrayValues): this;
+    /** Every element of the column's JSON array is one of the values (`[]` is). */
+    containedBy(column: ColumnName<Row>, values: ArrayValues): this;
+    /** The column's JSON array has at least one of the values. */
+    overlaps(column: ColumnName<Row>, values: ArrayValues): this;
+    /** An `eq` for each key, in key order. */
+    match(query: MatchQuery<Row>): this;
+    /**
+     * Any operator by name, Supabase's escape hatch: `filter("id", "in",
+     * "(1,2)")`, `filter("tags", "cs", "{a}")`, `filter("n", "not.gte", 10)`.
+     * A string value is PostgREST syntax where the operator needs one, and text
+     * otherwise.
+     */
+    filter(column: ColumnName<Row>, operator: FilterOperatorName | `not.${FilterOperatorName}`, value: RawFilterValue): this;
+    /**
+     * NOT of one condition — `not("deleted_at", "is", null)`, with the
+     * arguments `.filter()` takes — or of the conditions a callback adds, ANDed.
+     * As in SQL and PostgREST, a row whose column is NULL matches neither a
+     * condition nor its `not`: `not("status", "eq", "draft")` leaves NULL out.
+     */
+    not(column: ColumnName<Row>, operator: FilterOperatorName, value: RawFilterValue): this;
+    not(group: FilterGroupCallback<Row>): this;
+    /**
+     * Rows matching at least one of the conditions: a callback,
+     * `or((q) => q.eq("status", "draft").lt("price", 10))`, or Supabase's
+     * string, `or("status.eq.draft,price.lt.10")`, whose values are text.
+     */
+    or(filters: string | FilterGroupCallback<Row>): this;
+    /** Rows matching all of the conditions, as a group: for use inside `or`. */
+    and(filters: string | FilterGroupCallback<Row>): this;
+    private logic;
+    /**
+     * The conditions `build` adds, or why there are none to use. `build` gets
+     * a builder of this kind with no filters; FilterGroup shows only its filter
+     * methods, and only its conditions and first problem are read back.
+     */
+    private group;
+    protected filtersPart(): {
+        filters?: FilterNode[];
+    };
+}
+/**
+ * `naro.from(table).select(…)` — resolves to the rows, or one row. `Row` is
+ * the table's (what filters and `order` name), `Picked` the columns chosen.
+ */
+export declare class SelectBuilder<Row, Result = Row[], Picked = Row> extends FilterBuilder<Row, Result> {
+    /** Call again to sort by more columns, in call order. */
+    order(column: ColumnName<Row>, options?: OrderOptions): this;
+    /** At most `count` rows (1–1,000; a select without one reads up to 1,000). */
+    limit(count: number): this;
+    offset(count: number): this;
+    /**
+     * Rows `from` to `to`, both inclusive and counted from 0 — at most 1,000
+     * of them. Sent as `offset` and `limit`, so it is checked here: past the
+     * cap the worker would name `limit`, which the app never called.
+     */
+    range(from: number, to: number): this;
+    /** Exactly one row, or NOT_SINGLE_ROW. */
+    single(): SelectBuilder<Row, Picked, Picked>;
+    /** One row or null; more than one is NOT_SINGLE_ROW. */
+    maybeSingle(): SelectBuilder<Row, Picked | null, Picked>;
+    protected build(): Query;
+}
+/** `naro.from(table).insert(…)` — resolves to null, or the rows with `.select()`. */
+export declare class InsertBuilder<Row, Result = null> extends Builder<Result> {
+    /** Return the inserted rows (all columns, or the ones named). */
+    select<Columns extends string = "*">(columns?: ColumnList<Row, Columns>): InsertBuilder<Row, Selected<Row, Columns>[]>;
+    protected build(): Query;
+}
+/**
+ * `naro.from(table).update(…)` and `.delete()` — resolve to null, or the rows
+ * with `.select()`. Without a filter the worker refuses them (FILTER_REQUIRED)
+ * unless `.all()` says so on purpose, and only the service key may.
+ */
+export declare class MutationBuilder<Row, Result = null> extends FilterBuilder<Row, Result> {
+    /** Return the changed rows (all columns, or the ones named). */
+    select<Columns extends string = "*">(columns?: ColumnList<Row, Columns>): MutationBuilder<Row, Selected<Row, Columns>[]>;
+    /** Apply to every row with no filter at all. Service key only. */
+    all(): this;
+    protected build(): Query;
+}
+/** `naro.from(table)` — pick the action. */
+export declare class TableBuilder<Row, Insert, Update> {
+    #private;
+    constructor(run: Runner, table: string);
+    /** `"*"` (the default) or `"id, title"`. */
+    select<Columns extends string = "*">(columns?: ColumnList<Row, Columns>): SelectBuilder<Row, Selected<Row, Columns>[], Selected<Row, Columns>>;
+    /** One row or several; one request, one transaction. */
+    insert(rows: Insert | readonly Insert[]): InsertBuilder<Row>;
+    update(values: Update): MutationBuilder<Row>;
+    delete(): MutationBuilder<Row>;
+}
+export {};

package/dist/query/columns.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `select("id, title")` → `["id", "title"]`; `select()` or `select("*")` →
+ * `"*"`. Names are comma-separated and trimmed. A name with a comma or edge
+ * spaces goes in double quotes, with `""` for a quote inside it:
+ * `select('"a, b", c')` → `["a, b", "c"]`. Whether a column exists is the
+ * worker's call; this only refuses what can never be a name.
+ */
+export type ParsedColumns = {
+    ok: true;
+    columns: string[] | "*";
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function parseColumns(input: string | undefined): ParsedColumns;

package/dist/query/filters.d.ts

@@ -0,0 +1,63 @@
+import type { Filter, FilterNode, FilterOperator } from "../wire.js";
+/**
+ * data-core's MAX_FILTER_DEPTH; `wire.test.ts` checks that the two agree.
+ * Checked here only so a string of 10,000 `and(` cannot exhaust the stack;
+ * the worker counts the whole tree.
+ */
+export declare const MAX_FILTER_DEPTH = 4;
+/** The operator names `.filter()` and `.not()` take: the wire's and PostgREST's `cs`, `cd`, `ov`. */
+export type FilterOperatorName = FilterOperator | "cs" | "cd" | "ov";
+export type Parsed<T> = {
+    ok: true;
+    node: T;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * `tokens`: words the caller gives a value of its own — where a value or a
+ * list element goes, the word unquoted and alone stands for that value. The
+ * CLI reads a policy's `auth.uid()` this way (P2-2); the SDK passes none.
+ * The same word unquoted without its `()` or in another case is refused
+ * rather than read as text (사용자 리뷰 반영): `user_id.neq.auth.uid` would
+ * otherwise hold for every row.
+ *
+ * `group`: whether the items sit in a group of the caller's, `.or()`'s or
+ * `.and()`'s, which counts as the first of the four levels (the default).
+ * The CLI's condition has none when it is one item (사용자 리뷰 반영): it
+ * sends that item alone, so four groups inside it are four, not five.
+ */
+export type ParseOptions = {
+    tokens?: Readonly<Record<string, unknown>>;
+    group?: boolean;
+};
+/**
+ * PostgREST's `*` for `%` in a `like` / `ilike` pattern, everywhere a pattern
+ * is taken (사용자 리뷰 반영: `.like()` and `.ilike()` too, so ported
+ * supabase-js code matches). As in PostgREST, a literal `*` cannot be matched.
+ */
+export declare function likePattern(pattern: string): string;
+/**
+ * `value` as one quoted filter-string value: `\` and `"` escaped, in that
+ * order, and the whole in double quotes. Whatever the text — `,` `.` `(` `)`,
+ * quotes, backslashes — the parser reads it back as exactly this one value,
+ * so text from user input cannot close the quote early and add a condition
+ * (적대적 리뷰 반영). Quoted, a value stays text everywhere, a number in a
+ * `cs.{…}` list included. It does not escape a `like` pattern's `%`, `_` or
+ * `*`, which keep their meaning.
+ */
+export declare function quoteFilterValue(value: string): string;
+/**
+ * `.or(text)` / `.and(text)`: the items, in the method's own group. The group
+ * counts as the first of the four levels. With `group: false` (the CLI), one
+ * item comes back alone and counts from zero; several still come in `kind`.
+ */
+export declare function parseLogic(text: unknown, kind: "or" | "and", options?: ParseOptions): Parsed<FilterNode>;
+/**
+ * `.filter(column, operator, value)` and `.not(column, operator, value)`. A
+ * string value is PostgREST syntax where the operator needs one — a list for
+ * `in` and the array operators, a keyword for `is`, `*` for `like`, and
+ * `true` / `false` for `eq` and `neq` — and plain text otherwise. Anything
+ * else is sent as it is, for the worker to check.
+ */
+export declare function conditionOf(column: string, name: unknown, value: unknown): Parsed<Filter>;

package/dist/query/selected.d.ts

@@ -0,0 +1,35 @@
+import type { ColumnName } from "../types.js";
+/** What `columns.ts` trims around a name, as far as the types can see. */
+type Space = " " | "\t" | "\n" | "\r";
+type Trim<Text extends string> = Text extends `${Space}${infer Rest}` ? Trim<Rest> : Text extends `${infer Rest}${Space}` ? Trim<Rest> : Text;
+/** Tail-recursive with an accumulator, so a long list stays within TS's limit. */
+type Split<Text extends string, Names extends string = never> = Text extends `${infer Name},${infer Rest}` ? Split<Rest, Names | Trim<Name>> : Names | Trim<Text>;
+/**
+ * The names a column list asks for; `"*"` for every column; `null` when the
+ * types cannot read it — a string that is not a literal, or a quoted name
+ * (`'"a, b", c'`), which only the runtime parser unquotes.
+ */
+type Requested<Columns extends string> = string extends Columns ? null : Columns extends `${string}"${string}` ? null : Trim<Columns> extends "*" ? "*" : Split<Columns>;
+/** An untyped row (`Record<string, unknown>`) has every column. */
+type IsUntyped<Row> = string extends ColumnName<Row> ? true : false;
+/** The names in the list that are not columns of the row. */
+type Unknown<Row, Columns extends string> = IsUntyped<Row> extends true ? never : Requested<Columns> extends infer Names ? [Names] extends [null] ? never : [Names] extends ["*"] ? never : Exclude<Names, ColumnName<Row>> : never;
+/**
+ * The type of `select()`'s argument: the list itself when every name is a
+ * column, and otherwise a string it cannot match, which names the culprit —
+ * `Argument of type '"id, nope"' is not assignable to parameter of type
+ * '"Unknown column 'nope'"'`. TypeScript infers `Columns` from the argument
+ * through both branches, so the list is checked where it is written. An
+ * empty name (`"id,"`) and `*` among names are not columns either: the
+ * runtime refuses both unsent.
+ */
+export type ColumnList<Row, Columns extends string> = [
+    Unknown<Row, Columns>
+] extends [never] ? Columns : `Unknown column '${Extract<Unknown<Row, Columns>, string>}'`;
+/**
+ * The row a select or a returning resolves to: the whole row for `"*"`,
+ * nothing given, a list the types cannot read or an untyped row, and the
+ * picked columns otherwise. Never `never`.
+ */
+export type Selected<Row, Columns extends string> = IsUntyped<Row> extends true ? Row : Requested<Columns> extends infer Names ? [Names] extends [null] ? Row : [Names] extends ["*"] ? Row : Pick<Row, Extract<Names, keyof Row>> : Row;
+export {};

package/dist/runtime.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A page with a DOM: `window` and `document` both. Decides only where the
+ * token is kept by default (localStorage there, memory elsewhere); whether a
+ * service key is allowed is `isKnownServer`'s question, which is stricter.
+ */
+export declare function isBrowser(scope?: object): boolean;
+/**
+ * Whether a service key may be used here (spec §7): only where the runtime
+ * says it is a server and nothing says it is a user's device. Anything else —
+ * a browser tab, a web worker, React Native, a runtime the SDK does not
+ * recognise — is refused, since a key that reached any of them has shipped.
+ */
+export declare function isKnownServer(scope?: object): boolean;

package/dist/types.d.ts

@@ -0,0 +1,186 @@
+import type { NaroError } from "./errors.js";
+import type { Value } from "./wire.js";
+/**
+ * What every query resolves to (spec §15). The two halves never mix, so
+ * checking `error` narrows `data`.
+ */
+export type NaroResponse<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: NaroError;
+};
+/**
+ * A table's types. `naro gen types` writes all three; by hand, `Insert` and
+ * `Update` may be left out and default to `Partial<Row>`.
+ */
+export type GenericTable = {
+    Row: object;
+    Insert?: object;
+    Update?: object;
+};
+/** A view's types: it is read, never written. */
+export type GenericView = {
+    Row: object;
+};
+/** The default: any table, any column, rows of unknown values. */
+export type UntypedDatabase = {
+    tables: Record<string, {
+        Row: Record<string, unknown>;
+        Insert: Record<string, unknown>;
+        Update: Record<string, unknown>;
+    }>;
+    views: Record<never, never>;
+};
+/** True for `any` alone: `createClient<any>()` reads as the untyped client. */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/** `Database["tables"]`, where there is one. */
+export type TablesOf<Database> = IsAny<Database> extends true ? UntypedDatabase["tables"] : Database extends {
+    tables: infer Tables;
+} ? Tables : Record<never, never>;
+/** `Database["views"]`, or none. */
+export type ViewsOf<Database> = Database extends {
+    views: infer Views;
+} ? Views : Record<never, never>;
+/**
+ * `createClient<Database>()` takes what `naro gen types` writes (spec
+ * 2026-09-24 P2-3 §2): `{ tables: { [name]: { Row; Insert; Update } };
+ * views: { [name]: { Row } } }`. Mapped types, not index signatures, so an
+ * `interface` fits too; `views` may be left out by hand. Phase 1's flat
+ * `{ [table]: { Row } }` has no `tables` and is refused, not read as `any`.
+ */
+export type DatabaseShape<Database> = {
+    tables: {
+        [Table in keyof TablesOf<Database>]: GenericTable;
+    };
+    views?: {
+        [View in keyof ViewsOf<Database>]: GenericView;
+    };
+};
+/**
+ * The names `from()` takes: the tables. Not the views — the Data API reads
+ * no view, and answers one with 404 TABLE_NOT_FOUND (spec P2-3 §5.2).
+ */
+export type TableName<Database> = Extract<keyof TablesOf<Database>, string>;
+export type ColumnName<Row> = Extract<keyof Row, string>;
+export type RowOf<Table> = Table extends {
+    Row: infer Row extends object;
+} ? Row : never;
+export type InsertOf<Table> = Table extends {
+    Insert: infer Insert extends object;
+} ? Insert : Partial<RowOf<Table>>;
+export type UpdateOf<Table> = Table extends {
+    Update: infer Update extends object;
+} ? Update : Partial<RowOf<Table>>;
+/** A value `eq`, `neq`, `gt`… compare with. */
+export type FilterValue = Value;
+export type OrderOptions = {
+    /** Default true. */
+    ascending?: boolean;
+    /** 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. */
+export type User = {
+    id: string;
+    email: string;
+    name: string;
+    emailVerified: boolean;
+    image?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    [field: string]: unknown;
+};
+/** Better Auth's session, as JSON. */
+export type Session = {
+    id: string;
+    userId: string;
+    expiresAt: string;
+    createdAt: string;
+    updatedAt: string;
+    [field: string]: unknown;
+};
+/**
+ * Auth results keep `data` an object even on failure, so
+ * `const { data: { user } } = await naro.auth.getUser()` never destructures
+ * null (spec §1, §15).
+ */
+export type AuthResponse<T> = {
+    data: T;
+    error: NaroError | null;
+};
+export type UserResponse = AuthResponse<{
+    user: User | null;
+}>;
+export type SessionResponse = AuthResponse<{
+    session: Session | null;
+    user: User | null;
+}>;
+export type SignOutResponse = {
+    data: null;
+    error: NaroError | null;
+};
+export type SignUpCredentials = {
+    email: string;
+    password: string;
+    /** Better Auth requires a name; omitted, the email's local part is sent. */
+    name?: string;
+    /**
+     * Where the confirmation link sends the browser back to, when the project
+     * sends one (P2-6): a URL on an allowed origin. Omitted, the project's own
+     * origin.
+     */
+    redirectTo?: string;
+};
+export type SignInCredentials = {
+    email: string;
+    password: string;
+};
+export type OAuthProvider = "google" | "github";
+export type SignInWithOAuthOptions = {
+    provider: OAuthProvider;
+    /**
+     * Where the provider's callback sends the browser back to: an allowed
+     * origin of the project (`naro backend auth redirects add`). Omitted in a
+     * browser, the current page.
+     */
+    redirectTo?: string;
+    /** Answer the sign-in URL without navigating to it. */
+    skipBrowserRedirect?: boolean;
+};
+/**
+ * `url` is where the browser goes to sign in — the worker's
+ * `/_naro/v1/auth/authorize/<provider>`, which goes on to the provider; null
+ * when it could not start.
+ */
+export type OAuthResponse = AuthResponse<{
+    provider: OAuthProvider;
+    url: string | null;
+}>;
+/** What brought the browser back: a provider, a confirmation link, a reset link. */
+export type AuthFlowType = "oauth" | "email_verification" | "recovery";
+/**
+ * `getSessionFromUrl()`: `type` null when the URL carried nothing of Naro's.
+ * `recovery` holds no session — the page asks for a new password and calls
+ * `updateUser({ password })`.
+ */
+export type UrlSessionResponse = AuthResponse<{
+    session: Session | null;
+    user: User | null;
+    type: AuthFlowType | null;
+}>;
+export type EmailRedirectOptions = {
+    /** A URL on an allowed origin of the project; omitted, its own origin. */
+    redirectTo?: string;
+};
+/** What `updateUser` changes: the password, in the recovery flow. */
+export type UserAttributes = {
+    password: string;
+};
+/** A call that answers nothing but whether it worked. */
+export type AuthActionResponse = {
+    data: null;
+    error: NaroError | null;
+};
+export {};

package/dist/wire.d.ts

@@ -0,0 +1,61 @@
+export type Value = string | number | boolean | null;
+/** Objects and arrays are stored as their JSON text. */
+export type Row = Record<string, Value | object>;
+export type FilterOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "is" | "like" | "ilike" | "contains" | "containedBy" | "overlaps";
+/** One condition: a leaf of a filter tree. */
+export type Filter = {
+    operator: FilterOperator;
+    column: string;
+    value: Value | Value[];
+};
+/** A condition or a group of them (Phase 2-1). `filters` itself is an AND. */
+export type FilterNode = Filter | {
+    or: FilterNode[];
+} | {
+    and: FilterNode[];
+} | {
+    not: FilterNode;
+};
+export type Order = {
+    column: string;
+    ascending: boolean;
+    nullsFirst?: boolean;
+};
+export type Returning = string[] | "*";
+export type SelectQuery = {
+    version: 1;
+    action: "select";
+    table: string;
+    columns: string[] | "*";
+    filters?: FilterNode[];
+    order?: Order[];
+    limit?: number;
+    offset?: number;
+    single?: "one" | "maybe";
+};
+export type InsertQuery = {
+    version: 1;
+    action: "insert";
+    table: string;
+    rows: Row[];
+    returning?: Returning;
+};
+export type UpdateQuery = {
+    version: 1;
+    action: "update";
+    table: string;
+    values: Row;
+    filters?: FilterNode[];
+    returning?: Returning;
+    allowUnfiltered?: true;
+};
+export type DeleteQuery = {
+    version: 1;
+    action: "delete";
+    table: string;
+    filters?: FilterNode[];
+    returning?: Returning;
+    allowUnfiltered?: true;
+};
+export type Query = SelectQuery | InsertQuery | UpdateQuery | DeleteQuery;
+export type QueryAction = Query["action"];

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "naro-js",
+  "version": "0.1.0",
+  "description": "Auth and data for your Naro project, from the browser or the server.",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "miniflare": "5.20260815.0-alpha",
+    "tsup": "8.5.0",
+    "typescript": "7.0.2",
+    "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"
+  },
+  "scripts": {
+    "build": "tsup && pnpm build:types",
+    "build:types": "tsc --project tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit && tsc --project tsconfig.build.json --noEmit"
+  }
+}