@naru-pub/sdk 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @naru-pub/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The [Naru](https://naru.pub) Data SDK as an npm package: a Naru site's
+collections, its own queries and mutations, live queries and members, from
+its pages; and, under `@naru-pub/sdk/functions`, the types of the site's own
+code in `_naru/`. The [reference](https://naru.pub/docs/sdk/1.1.0) and the
+guides on naru.pub cover what it does.
+
+The package is the very file Naru serves at
+`https://sdk.naru.pub/sdk/<version>/naru.js`, with its declarations. A page
+without a build step imports that address and needs nothing from here:
+
+```html
+<script type="module">
+  import { createNaru } from "https://sdk.naru.pub/sdk/1.1.0/naru.js";
+</script>
+```
+
+A project with a bundler, a type checker or a Node program installs it:
+
+```bash
+npm install @naru-pub/sdk
+```
+
+```ts
+import { createNaru, NaruError } from "@naru-pub/sdk";
+import type { Query, Mutation } from "@naru-pub/sdk/functions";
+```
+
+Outside a page on `<site>.naru.pub`, say which site:
+`createNaru({ site: "demo" })`. Node needs version 22 or later for live
+queries (its built-in WebSocket).
+
+## Bundled or loaded from Naru
+
+Bundled, a site keeps the SDK it was built with until it is built again.
+Loaded from `sdk.naru.pub`, at `/sdk/1/` it gets the SDK's fixes as Naru serves them, and either way
+[naru-dev](https://www.npmjs.com/package/@naru-pub/dev) can point it at your machine. To keep that
+while importing from the package, mark it external and give it the address
+of the installed version, for example in Vite:
+
+```js
+import { readFileSync } from "node:fs";
+
+const { version } = JSON.parse(
+  readFileSync("node_modules/@naru-pub/sdk/package.json", "utf8"),
+);
+const sdk = `https://sdk.naru.pub/sdk/${version.replace(/-.*/, "")}/naru.js`;
+
+export default {
+  plugins: [
+    {
+      name: "naru-sdk",
+      enforce: "pre",
+      resolveId: (id) =>
+        id === "@naru-pub/sdk" ? { id: sdk, external: true } : null,
+    },
+  ],
+};
+```
+
+## Versions
+
+The package's version is the SDK's: `1.1.0` is `/sdk/1.1.0/naru.js`. While
+an SDK version is still being built, the file Naru serves at its address
+can change and a published package cannot, so it is published as
+prereleases, `<version>-dev.1` and on, under the dist-tag `dev`.
+
+## Publishing
+
+From the Naru repository (maintainers): run `pnpm sdk:build` in
+`control-plane/` if the SDK changed, set `version` in `sdk/package.json`
+(`scripts/build.mjs` refuses a release of an SDK version still being built,
+and a prerelease of a frozen one), commit, and push a tag `sdk-v<version>`;
+`.github/workflows/publish-sdk.yml` checks and stages it with the
+`NPM_TOKEN` secret, and it goes live once approved with 2FA (`npm stage
+approve <stage-id>`, or the Staged Packages tab on npmjs.com).
+`scripts/check-package.sh <dir>` does the same check locally.
+
+## License
+
+AGPL-3.0-only, as Naru.

package/dist/functions.d.ts

@@ -0,0 +1,206 @@
+/**
+ * What Naru hands a site's own code (SDK 1.1.0): queries in
+ * `_naru/queries/`, mutations in `_naru/mutations/` and routes in
+ * `_naru/routes.js`, run on Naru over the tables `_naru/migrations/*.sql`
+ * create. For type checking only; nothing here exists at run time.
+ *
+ * ```ts
+ * import type { Query, Mutation } from "./functions.d.ts";
+ * export const posts: Query<{ board: string }> = async (ctx, { board }) =>
+ *   (await ctx.sql`SELECT id, title FROM posts WHERE board = ${board}`).rows;
+ * ```
+ *
+ * The code runs in QuickJS, not a browser or Node. Its globals are the
+ * language's own (Object, Array, JSON, Math, Date, RegExp, Map, Set, WeakMap,
+ * WeakSet, WeakRef, Promise, Proxy, Reflect, Symbol, BigInt, Iterator,
+ * ArrayBuffer, DataView, the typed arrays, the Error types, the URI
+ * functions, parseInt and the like) and: URL and URLSearchParams, as
+ * browsers have them; structuredClone, for primitives, plain objects and
+ * arrays, Date, RegExp, Map, Set, ArrayBuffer and Uint8Array (anything else
+ * throws a DataCloneError); Math.random; Date.now, the server's clock (prefer
+ * `ctx.now`; local time is the server's, so use UTC methods);
+ * performance.now, queueMicrotask and DOMException. There is no Intl
+ * (toLocaleString formats as English), TextEncoder, TextDecoder, atob, btoa,
+ * crypto, console, fetch, setTimeout or other timers, WebAssembly, require or
+ * process, whatever your editor's lib types say.
+ *
+ * Written by hand beside the generated naru.d.ts, whose `Json` this repeats
+ * so this file stands on its own.
+ * @packageDocumentation
+ */
+
+export type Json =
+  null | boolean | number | string | Json[] | { [key: string]: Json };
+
+/** The failure codes `ctx.fail` takes, as pages receive them in `error.code`. */
+export type ErrorCode =
+  | "CONFLICT"
+  | "QUOTA_EXCEEDED"
+  | "AUTH_REQUIRED"
+  | "ACCESS_DENIED"
+  | "NOT_FOUND"
+  | "RATE_LIMITED"
+  | "INVALID_REQUEST"
+  | "UNAVAILABLE";
+
+/**
+ * The member who called: their ID on this site, the same on every visit.
+ * What they may do is the site's to keep, in its own tables.
+ */
+export interface CallingMember {
+  readonly id: string;
+}
+
+/** A value site SQL binds or returns (a boolean binds as 1 or 0). */
+export type SqlValue = string | number | boolean | Uint8Array | null;
+/** What `ctx.sql` answers: the statement's rows, and how many it changed. */
+export interface SqlResult<Row> {
+  rows: Row[];
+  changes: number;
+}
+
+/**
+ * A query's or route's `ctx`: who calls, and the site's own tables through
+ * `sql`. Anyone may call one, signed in or not, so its code decides what
+ * each caller may see. A query's `sql` only reads. A call runs in one
+ * transaction, for tens of milliseconds in 32 MiB, makes at most 100
+ * database operations, 1,000 URL parses and 2,000 Math.random() draws,
+ * reads at most 500,000 rows in all, and returns at most 1 MiB of JSON. Every method's promise must be
+ * used (awaited, returned or chained), or the call fails.
+ */
+export interface QueryCtx {
+  /** The signed-in member, or null for the owner and visitors. */
+  readonly member: CallingMember | null;
+  /** The site's owner called. A visitor, signed in to nothing, has neither. */
+  readonly owner: boolean;
+  /** The site's owner's Naru login, whoever calls: the site's own name. */
+  readonly ownerName: string;
+  /** The call's time in milliseconds, fixed for the whole call. */
+  readonly now: number;
+  /**
+   * Refuses the request: nothing the call wrote is kept, and the page's
+   * `error.message` is `message` (1–1000 characters) as written, so write it
+   * for visitors. `details`, at most 4 KiB of JSON, arrives as
+   * `error.details`.
+   */
+  fail(code: ErrorCode, message: string, details?: Json): never;
+  /**
+   * One statement of SQL against the site's own tables, which its
+   * `_naru/migrations/*.sql` create. As a tag, ``ctx.sql`... ${value}` ``
+   * binds every interpolated value as a parameter; given text and values,
+   * it runs a query builder's compiled statement. SELECT, INSERT, UPDATE and
+   * DELETE run; a query only reads. Naru's own tables, pragmas, triggers,
+   * transactions and recursion are refused, but Naru's view
+   * `_naru_uploads (id, url, member, name, type, size, created_at)`, the
+   * site's finished uploads (`member` null for the owner's), may be read
+   * and joined. A statement is stopped once
+   * SQLite works on one step of it for 3 seconds; one stopped 3 times within
+   * a minute is paused for 5 minutes. It binds at most 100 values, returns at most 1,000 rows and 1 MiB, BLOB columns as
+   * Uint8Arrays, and counts as one database operation; a call's statements
+   * read at most 500,000 rows. A value a UNIQUE column already holds fails
+   * the call with CONFLICT, `details.unique` naming the column; any other
+   * mistake SQLite refuses, with its message.
+   *
+   * To stay fast, read a table whole at most once and reach every other
+   * table by key (join on an indexed column):
+   *
+   * - A list as one value: `WHERE id IN (SELECT value FROM json_each(?))`,
+   *   bound as `JSON.stringify(ids)`.
+   * - A row's JSON column: `FROM visits, json_each(visits.hours) j`.
+   * - An ordered aggregate per row: `(SELECT json_group_array(title) FROM
+   *   (SELECT title FROM titles WHERE ch = c.id ORDER BY ord))`, with an
+   *   index on `titles (ch, ord)`.
+   * - Past 1,000 rows: `WHERE id > ? ORDER BY id LIMIT 1000`, then again
+   *   after the last `id`.
+   */
+  sql<Row = Record<string, SqlValue>>(
+    strings: TemplateStringsArray,
+    ...values: SqlValue[]
+  ): Promise<SqlResult<Row>>;
+  sql<Row = Record<string, SqlValue>>(
+    text: string,
+    values?: SqlValue[],
+  ): Promise<SqlResult<Row>>;
+  /**
+   * Guests' passwords, kept by the site as hashes. `verify` allows ten wrong
+   * passwords an hour for each `key` (such as "post:42"), whoever tries,
+   * then fails with RATE_LIMITED. A call makes at most 3 password checks.
+   */
+  passwords: {
+    verify(password: string, hash: string, key: string): Promise<boolean>;
+  };
+}
+
+/** A mutation's `ctx`: a query's, writing, and notifying members. */
+export interface MutationCtx extends QueryCtx {
+  passwords: QueryCtx["passwords"] & {
+    /** A hash of `password` (1–256 characters) to keep in a table. */
+    hash(password: string): Promise<string>;
+  };
+  /**
+   * Notifies these members (at most 1,000 a call) in the Naru app, once the
+   * mutation returns: on their devices if they allowed the site there, or in
+   * the app's inbox until they do. Unknown, pending and banned members are
+   * skipped, and the site is not told who has the app. `path` (default "/")
+   * is a page of this site, opened when the notification is tapped. A title
+   * longer than 100 characters or a body longer than 500 is cut to fit.
+   * Notifications are best effort: one Naru cannot queue is dropped, and the
+   * mutation goes on. Member ids that are not ids, a blank title or another
+   * site's address still throw.
+   */
+  notify(
+    members: string[],
+    message: { title: string; body?: string; path?: string },
+  ): Promise<null>;
+}
+
+/** `export async function name(ctx, args)` in `_naru/queries/` or `_naru/mutations/`. */
+export type Query<Args = Json, Result = Json> = (
+  ctx: QueryCtx,
+  args: Args,
+) => Result | Promise<Result>;
+export type Mutation<Args = Json, Result = Json> = (
+  ctx: MutationCtx,
+  args: Args,
+) => Result | Promise<Result>;
+
+/** What a route is asked. */
+export interface RouteRequest {
+  /** The path as asked, still percent-encoded. */
+  path: string;
+  /** The subdomain or custom domain it was asked on, such as `https://alice.naru.pub`. */
+  origin: string;
+  /** The query string's values, the last of a repeated name. */
+  query: Record<string, string>;
+}
+/**
+ * What a route answers: a string of HTML, a body of one of these types, one
+ * of the site's files with `head` added to its `<head>` when it is HTML, or a
+ * redirect to a path or an `https://` URL. `status` is 200–599 (a redirect's
+ * 301, 302, 303, 307 or 308, by default 302); `cache` the seconds (0–300) the
+ * edge may keep the page, by default 0.
+ */
+export type RouteAnswer =
+  | string
+  | ({ status?: number; cache?: number } & (
+      | {
+          body: string;
+          type:
+            | "text/html"
+            | "text/plain"
+            | "text/css"
+            | "text/calendar"
+            | "text/xml"
+            | "application/xml"
+            | "application/rss+xml"
+            | "application/atom+xml"
+            | "application/json";
+        }
+      | { file: string; head?: string }
+      | { redirect: string }
+    ));
+/** `export default async function (ctx, request)` in `_naru/routes.js`. */
+export type Route = (
+  ctx: QueryCtx,
+  request: RouteRequest,
+) => RouteAnswer | Promise<RouteAnswer>;

package/dist/naru.d.ts

@@ -0,0 +1,349 @@
+/**
+ * Naru Data SDK 1.1.0: browser SDK for data owned by one Naru site: 1.0.0's
+ * collections, with the site's own tables reached through its queries and
+ * mutations, live queries, and its members.
+ * @packageDocumentation
+ */
+
+export type Json =
+  null | boolean | number | string | Json[] | { [key: string]: Json };
+
+/** @internal */
+declare const revisionBrand: unique symbol;
+/** An opaque concurrency token. Store and return it unchanged. */
+export type Revision = string & { readonly [revisionBrand]: true };
+
+/** A read or successful write: user data stays separate from server metadata. */
+export interface Document<T = Json> {
+  id: string;
+  data: T;
+  createdAt: string;
+  updatedAt: string;
+  revision: Revision;
+}
+
+export interface Page<T = Json> {
+  documents: Document<T>[];
+  nextCursor: string | null;
+  totalCount?: number;
+}
+
+/**
+ * Why an operation failed. The list is closed for v1: a code a later server
+ * adds reaches this version as the nearest code here.
+ */
+export type NaruErrorCode =
+  | "CONFLICT"
+  | "QUOTA_EXCEEDED"
+  | "AUTH_REQUIRED"
+  | "ACCESS_DENIED"
+  | "NOT_FOUND"
+  | "RATE_LIMITED"
+  | "INVALID_REQUEST"
+  | "UNAVAILABLE";
+
+/**
+ * A Naru operation that could not be completed. Check it with `instanceof`.
+ *
+ * `message` is a short Korean sentence a visitor can read, so a page may show
+ * it as is (`status.textContent = error.message`): a query's or mutation's
+ * own `ctx.fail` message, or Naru's wording for `code`. `cause` is a network
+ * failure's original error. What Naru answered is in the browser's network tab.
+ */
+export declare class NaruError extends Error {
+  private constructor();
+  readonly code: NaruErrorCode;
+  /**
+   * The JSON a query or mutation passed as `ctx.fail(code, message, details)`,
+   * such as `{ reason: "sold_out" }`; or, when a member's request is refused
+   * because the site has not approved them, `{ membership: "pending" }` or
+   * `{ membership: "banned" }`; or, for a `CONFLICT` because another
+   * document already holds a value of one of the collection's unique
+   * fields, `{ unique: "<field>" }`. Undefined for every other failure.
+   */
+  readonly details?: Json;
+}
+
+/** Top-level user fields, combined with AND. */
+export type Filter = Record<
+  string,
+  | string
+  | number
+  | boolean
+  | null
+  | {
+      gt?: string | number;
+      gte?: string | number;
+      lt?: string | number;
+      lte?: string | number;
+    }
+>;
+
+/** One or two keys: a user field by name, or document metadata. */
+export type Sort =
+  | readonly [
+      readonly [
+        string | { metadata: "id" | "createdAt" | "updatedAt" },
+        "asc" | "desc",
+      ],
+    ]
+  | readonly [
+      readonly [
+        string | { metadata: "id" | "createdAt" | "updatedAt" },
+        "asc" | "desc",
+      ],
+      readonly [
+        string | { metadata: "id" | "createdAt" | "updatedAt" },
+        "asc" | "desc",
+      ],
+    ];
+
+export interface ListOptions {
+  filter?: Filter;
+  sort?: Sort;
+  /** Default 50; maximum 100. */
+  size?: number;
+  /** Opaque cursor returned by the preceding page. */
+  after?: string | null;
+  includeTotal?: boolean;
+  signal?: AbortSignal;
+}
+
+/** Write only at this revision, or only if the document does not exist yet. */
+export type WriteCondition = { revision: Revision } | { absent: true };
+
+export interface PublicCollection<T = Json> {
+  get(id: string, options?: { signal?: AbortSignal }): Promise<Document<T>>;
+  list(options?: ListOptions): Promise<Page<T>>;
+  /** How many documents match `filter`, or the whole collection. */
+  count(options?: { filter?: Filter; signal?: AbortSignal }): Promise<number>;
+  /**
+   * Every page of a query in turn, following `nextCursor` from `after` (or
+   * the start). Not a snapshot: writes in between can shift later pages.
+   */
+  pages(options?: ListOptions): AsyncIterable<Page<T>>;
+  add(data: T, options?: { signal?: AbortSignal }): Promise<Document<T>>;
+}
+
+export interface AdminCollection<T = Json> extends PublicCollection<T> {
+  /** Replaces the whole document or creates it. */
+  set(
+    id: string,
+    data: T,
+    options?: { condition?: WriteCondition; signal?: AbortSignal },
+  ): Promise<Document<T>>;
+  /** Deleting a missing document succeeds unless a condition was supplied. */
+  delete(
+    id: string,
+    options?: { condition?: { revision: Revision }; signal?: AbortSignal },
+  ): Promise<void>;
+}
+
+/** A visitor signed in to this site with their Naru account. */
+export interface Member extends SiteCode, LiveQueries {
+  /**
+   * This member's ID on this site, the same on every visit: `ctx.member.id`
+   * in the site's queries and mutations. It is not their Naru account name.
+   */
+  readonly id: string;
+  media: {
+    /**
+     * Stores a file publicly, in the site's media. Large photos may be shrunk
+     * first. A HEIC photo this browser cannot convert throws a `TypeError`
+     * before anything is sent.
+     */
+    upload(
+      file: File | Blob,
+      options?: {
+        signal?: AbortSignal;
+        /** As for an owner's upload. */
+        onProgress?: (
+          progress:
+            | { phase: "preparing" }
+            | { phase: "uploading"; loaded: number; total: number }
+            | { phase: "finishing" },
+        ) => void;
+      },
+    ): Promise<{
+      id: string;
+      url: string;
+      name: string;
+      contentType: string;
+      size: number;
+    }>;
+  };
+  /**
+   * Signs out on every page of this site. This handle stops working at once,
+   * even if the revoke request fails.
+   */
+  signOut(): Promise<void>;
+}
+
+/**
+ * The site's queries and mutations: its own code over its own tables, which its `_naru/migrations/` create. Anyone may call them,
+ * signed in or not; the code decides what each caller may see and do from
+ * `ctx.member` and `ctx.owner`.
+ */
+export interface SiteCode {
+  /**
+   * Runs `"<module/path>:<name>"`, an export of the site's
+   * `_naru/queries/<module/path>.js`, and resolves with what it returned. A
+   * query only reads (`ctx.sql`), so it counts against the caller's read
+   * budget.
+   */
+  query<R = Json>(
+    name: string,
+    args?: Json,
+    options?: { signal?: AbortSignal },
+  ): Promise<R>;
+  /**
+   * Runs an export of `_naru/mutations/<module/path>.js` in one transaction:
+   * what it wrote is kept only if it returns, and a throw, `ctx.fail` or a
+   * limit changes nothing.
+   */
+  mutate<R = Json>(
+    name: string,
+    args?: Json,
+    options?: { signal?: AbortSignal },
+  ): Promise<R>;
+}
+
+/**
+ * The owner signed in on this page. Its queries and mutations see
+ * `ctx.member` null and `ctx.owner` true, whatever collections this sign-in
+ * approved, and are not counted against the site's budget.
+ */
+export interface Admin extends SiteCode, LiveQueries {
+  collection<T = Json>(name: string): AdminCollection<T>;
+  /**
+   * Commits every write or none. Conditions guard individual documents. Does
+   * not retry. Resolves, in the order written, with what each `set` stored and
+   * `null` for each `delete`.
+   */
+  batch(
+    writes: readonly (
+      | {
+          collection: string;
+          set: { id: string; data: unknown; condition?: WriteCondition };
+        }
+      | {
+          collection: string;
+          delete: { id: string; condition?: { revision: Revision } };
+        }
+    )[],
+    options?: { signal?: AbortSignal },
+  ): Promise<
+    ({
+      id: string;
+      revision: Revision;
+      createdAt: string;
+      updatedAt: string;
+    } | null)[]
+  >;
+  media: {
+    /**
+     * Stores a file publicly. Large photos may be shrunk first. A HEIC photo
+     * this browser cannot convert throws a `TypeError` before anything is sent.
+     * Like every upload, it stays until the owner deletes it in the media
+     * library, since media may be linked from anywhere; Naru notes which of the site's documents name its URL
+     * (in any field, HTML included), and the media library marks it when
+     * none does.
+     */
+    upload(
+      file: File | Blob,
+      options?: {
+        signal?: AbortSignal;
+        /**
+         * Called as the upload moves along: `preparing` while a photo is
+         * shrunk and the upload authorized, `uploading` with the bytes sent
+         * so far of the `total` actually sent (after shrinking), then
+         * `finishing` while storage confirms and Naru records the file.
+         * `loaded` can reach `total` before storage has answered.
+         */
+        onProgress?: (
+          progress:
+            | { phase: "preparing" }
+            | { phase: "uploading"; loaded: number; total: number }
+            | { phase: "finishing" },
+        ) => void;
+      },
+    ): Promise<{
+      id: string;
+      url: string;
+      name: string;
+      contentType: string;
+      size: number;
+    }>;
+  };
+  /** This handle stops working at once, even if the revoke request fails. */
+  signOut(): Promise<void>;
+}
+
+/** A live query, kept current until closed. */
+export interface Live {
+  close(): void;
+}
+
+/** Live queries: a query's answer, kept current. */
+export interface LiveQueries {
+  /**
+   * Runs `"<module/path>:<query>"` from the site's `_naru/queries/` as
+   * `query()` does, calls `onResult` with its answer, and again whenever a
+   * write changes a table it read and the answer with it, until closed.
+   * After the connection drops it is asked again, so the latest answer
+   * arrives once it is back. A failure, now or later, goes to `onError`.
+   * A connection holds at most 20. `args` left `undefined` is `null`, as
+   * `query()`'s are.
+   */
+  subscribe<R = Json>(
+    name: string,
+    args: Json | undefined,
+    onResult: (result: R) => void,
+    options?: { onError?(error: NaruError): void },
+  ): Live;
+}
+
+/**
+ * A page's client. Its queries and mutations run as a visitor, signed in to
+ * nothing: they see `ctx.member` null and `ctx.owner` false, are limited per
+ * visitor address, and count against the site's budget.
+ */
+export interface NaruClient extends SiteCode, LiveQueries {
+  /** Visitor access, even when signed in. */
+  collection<T = Json>(name: string): PublicCollection<T>;
+  auth: {
+    /**
+     * The admin client for this page, or null. A sign-in stays on this page
+     * in every tab until it ends. A sign-in that was denied, went stale or
+     * could not be exchanged also resolves null.
+     */
+    session(): Promise<Admin | null>;
+    /** Redirects to Naru for approval. */
+    signIn(options?: {
+      /**
+       * The collections this page manages directly. None, for a page that
+       * manages the site through its queries and mutations as the owner.
+       */
+      collections?: readonly string[];
+    }): Promise<void>;
+  };
+  members: {
+    /**
+     * The member signed in to this site, or null. A sign-in stays on every
+     * page and tab of the site until it ends. Finishes a sign-in when Naru has
+     * just redirected back; one that was denied or could not be exchanged
+     * resolves null.
+     */
+    session(): Promise<Member | null>;
+    /**
+     * Redirects to Naru, where the visitor signs in with a Naru account (or
+     * makes one), and back to this page.
+     */
+    signIn(): Promise<void>;
+  };
+}
+
+/** Creates a client bound to one site. */
+export declare function createNaru(options?: { site?: string }): NaruClient;
+
+export {};