lecodes-sdk 0.19.0

package/dist/types/scene/editorPlugins.d.ts

@@ -0,0 +1,82 @@
+import type { InspectorUI } from "../core/InspectorUI";
+/** A geometry hit under the viewport pointer, handed to tools. Physics builds raycast the scene's
+ *  meshes (precise); otherwise (and on misses) the hit falls back to the ground plane (y = 0). */
+export type EditorRayHit = {
+    point: [number, number, number];
+    normal: [number, number, number];
+    /** Absolute path of the scene-file node the hit belongs to ("city/in1/pt1") — null for
+     *  ground-plane fallback hits. */
+    node: string | null;
+};
+/**
+ * The editor scripting API handed to windows and tools. Nodes are addressed by ABSOLUTE PATH —
+ * '/'-joined names from the scene root; a root node's path is its bare name. Doc-op methods write
+ * the scene DOCUMENT through the editor's normal commit path (undo, file, live patching all
+ * included); they return false / no-op when the document can't take the edit (sibling-name
+ * collision, unknown path).
+ */
+export type EditorApi = {
+    /** The currently selected node path (or `path::part` key for asset internals), null when
+     *  nothing is selected. */
+    readonly selection: string | null;
+    select(path: string | null): void;
+    /** The scene document's nodes: absolute path, sibling-unique display name, source kind
+     *  (mesh / model / light / group / …). */
+    nodes(): {
+        path: string;
+        name: string;
+        kind: string;
+    }[];
+    /** First unused "base", "base2", "base3", … name among the SIBLINGS under `parentPath`
+     *  (scene root when omitted). */
+    uniqueName(base: string, parentPath?: string): string;
+    /** Add a ROOT node from plain def data (scene-file grammar; a string `model` value means an
+     *  asset path). `name` may not contain '/' or ':'. One undo step unless grouped by `transact`. */
+    addNode(name: string, def: Record<string, unknown>): boolean;
+    /** Write one def prop (transforms apply live; anything else patches/re-runs the node). */
+    setProp(path: string, key: string, value: unknown): boolean;
+    removeNode(path: string): void;
+    /** Duplicate a node; returns the copy's path (null when it can't). */
+    duplicate(path: string): string | null;
+    /** Raycast the scene under a viewport pixel (same hit rules as tool clicks). */
+    raycast(screenX: number, screenY: number): EditorRayHit | null;
+    /** Group every doc edit inside `fn` into ONE undo step. */
+    transact(fn: () => void): void;
+    /** Read one def prop of a node as document data (`asset()` refs come as `{ $asset: "./x" }`);
+     *  undefined when the node or key doesn't exist. */
+    getProp(path: string, key: string): unknown;
+    /** Write a BINARY asset file for a node (a terrain's `.terrain`, a baked mask…). `ref` = the
+     *  node's existing def-relative `asset()` ref to overwrite, or null to create `./<name>` at the
+     *  project root (a free name is picked on collisions). Resolves to the ref to store in the node's
+     *  def (`{ $asset: ref }` via `setProp`), null when the host can't write files. Not a doc edit —
+     *  it is not undoable; keep the doc pointing at the file. */
+    writeAsset(path: string, ref: string | null, name: string, bytes: Uint8Array): Promise<string | null>;
+};
+export type EditorWindowFn = (ui: InspectorUI, editor: EditorApi) => void;
+export type EditorToolHooks = {
+    /** CSS cursor for the viewport while this tool is active (default "crosshair"). */
+    cursor?: string;
+    /** A short glyph (one character / emoji) for the tool's toolbar button — tools without one all
+     *  share the generic wand icon, so any editor with two or more tools should set it. */
+    icon?: string;
+    /** A viewport click while the tool is active — `hit` is the raycast result under the pointer.
+     *  Viewport clicks route to the tool while it is active. */
+    onViewportClick?(hit: EditorRayHit, editor: EditorApi): void;
+    /** Drag tools (brushes): a primary-button drag in the viewport routes here instead of orbiting
+     *  the camera — start / every pointer move (with the hit under it, null while off-world) /
+     *  release. A tool with `onDragStart` gets NO `onViewportClick` for the same gesture. */
+    onDragStart?(hit: EditorRayHit, editor: EditorApi): void;
+    onDrag?(hit: EditorRayHit | null, editor: EditorApi): void;
+    onDragEnd?(editor: EditorApi): void;
+    /** The pointer moved over the viewport with no button down (throttled to the frame) — draw a
+     *  brush cursor through `Gizmos`; null when nothing is under it. */
+    onHover?(hit: EditorRayHit | null, editor: EditorApi): void;
+};
+/** Register an editor panel — a collapsible overlay docked over the viewport (the inspector rail
+ *  stays selection-scoped). A window that emits `ui.toolButton` for a tool becomes that tool's
+ *  settings panel: activating the tool expands and highlights it. `render` re-runs immediate-mode
+ *  on every interaction — same protocol as `static inspector` cards. */
+export declare const registerEditorWindow: (title: string, render: EditorWindowFn) => void;
+/** Register a viewport tool — a toolbar entry beside move/rotate/scale (activate it there or via
+ *  `ui.toolButton(label, name)`). While active, viewport clicks arrive as raycast hits. */
+export declare const registerEditorTool: (name: string, hooks: EditorToolHooks) => void;

package/dist/types/scene/gizmos.d.ts

@@ -0,0 +1,56 @@
+import { type Mat4Like } from "../math/mat4";
+import type { Vec3Like } from "../math/vec";
+/** The anchor of a gizmo call: any object with an engine entity id (a `Node`). */
+export type GizmoAnchor = {
+    readonly id: number;
+};
+export type GizmoStyle = {
+    /** CSS hex color (`#rgb` / `#rrggbb`); default a neutral light gray. */
+    color?: string;
+    /** 0..1, default 1. */
+    alpha?: number;
+    /** Anchor: points are in this node's LOCAL frame (scale ignored); the lines follow the node
+     *  live, are pickable (a click selects the node) and turn the selection accent when it is
+     *  selected. Omit for world-space lines (not pickable). */
+    node?: GizmoAnchor | null;
+};
+/** One color batch of LINES (flat `[x,y,z, x,y,z]` per segment) — what a host hands the engine.
+ *  With `entityId` the segments are in that entity's local frame (see GizmoStyle.node). */
+export type GizmoBatch = {
+    color: string;
+    alpha: number;
+    segments: number[];
+    entityId?: number;
+};
+/** The per-run collector (owned by the scene loader's EditorRun). Batches are keyed by style so a
+ *  hundred same-colored segments cost one draw. */
+export declare class GizmoBuffer {
+    batches: GizmoBatch[];
+    private _byStyle;
+    clear(): void;
+    segments(style: GizmoStyle | undefined): number[];
+}
+/**
+ * Editor-only line drawing, available inside generator `rebuild()`, `make()` factories and editor
+ * tool hooks. Points are WORLD space. Drawn by the scene editor's viewport overlay (depth-test
+ * off — a path through a wall is still a path); invisible everywhere else.
+ */
+export declare const Gizmos: {
+    /** One segment from `a` to `b`. */
+    line(a: Vec3Like, b: Vec3Like, style?: GizmoStyle): void;
+    /** Consecutive segments through `points`; `closed` joins the last point back to the first. */
+    polyline(points: readonly Vec3Like[], style?: GizmoStyle & {
+        closed?: boolean;
+    }): void;
+    /** A wireframe camera frustum looking down −Z: the four edges from the origin to a rect
+     *  `length` metres ahead sized by `fov` (vertical, degrees) × `aspect` (default 16:9), plus an
+     *  "up" fin above the rect. Anchor it (`{ node }`) for a camera node's marker — the frustum
+     *  then follows the node's pose; `matrix` places an unanchored one in world space. */
+    frustum(fov: number, style?: GizmoStyle & {
+        aspect?: number;
+        length?: number;
+        matrix?: Mat4Like;
+    }): void;
+    /** A three-axis cross centred on `p` (a point marker); `size` = half extent, default 0.1. */
+    cross(p: Vec3Like, size?: number, style?: GizmoStyle): void;
+};

package/dist/types/scene/grammar.d.ts

@@ -0,0 +1,56 @@
+import type { Aspect, AspectCtor } from "../core/Aspect";
+import type { Node } from "../gl/Node";
+/** One aspect to attach, created by `use(Ctor, props)`. */
+export type AspectEntry<A extends Aspect<any, any> = Aspect<any, any>> = {
+    ctor: AspectCtor<A>;
+    props?: Partial<A>;
+};
+/** Reference an aspect in a scene file: `aspects: [use(Physics, { motion: 'static' })]`. Props are
+ *  typechecked against the aspect's fields, exactly like `node.aspect(Ctor, props)`. */
+export declare const use: <A extends Aspect<any, any>>(ctor: AspectCtor<A>, props?: Partial<A>) => AspectEntry<A>;
+/** A `make(fn, args)` source entry — see {@link make}. `N` is the node family the factory returns
+ *  (3D `Node` by default; a `.scene2d.ts` file's factories return `Node2D`). */
+export type MakeEntry<A extends Record<string, unknown> = Record<string, unknown>, N = Node> = {
+    fn: (args: A) => N | Promise<N>;
+    args?: A;
+};
+/**
+ * A code-created source in a scene file: `tower: { make: make(buildTower, { floors: 5 }), … }`.
+ * The factory runs after every scene node exists (so `ref()` args resolve, forward references
+ * included) and its returned subtree mounts under the def node — the def's transform stays
+ * editor-owned, so moving the node never re-calls the factory. Args must be literal data (same
+ * grammar as aspect props); in the editor they edit as fields, and an arg change re-CALLS the
+ * factory live — the code is already in the bundle, so no compile happens. Keep factories pure
+ * builders: same args → same subtree, no side effects outside the returned nodes.
+ */
+export declare const make: <A extends Record<string, unknown>, N>(fn: (args: A) => N | Promise<N>, args?: A) => MakeEntry<A, N>;
+/**
+ * Reference another scene node by PATH in an aspect's props:
+ * `use(Road, { from: ref('pointA'), to: ref('lane/pointB') })`. Resolves to the live node when
+ * aspects attach — after EVERY node of the scene exists, so declaration order doesn't matter.
+ * Resolution is scoped upward from the host node (like variable scoping): the host's own children
+ * first, then its siblings, then each ancestor's scope up to the scene root. The FIRST segment
+ * binds the scope; the remaining segments descend from there. Refs address def nodes only (no
+ * `::`/`name[i]` asset-internal segments); an unknown path resolves to `null` (type your aspect
+ * field `Node | null`). Scene files only — hand-written code passes nodes directly:
+ * `node.aspect(Road, { from: nodes.pointA })`.
+ */
+export declare const ref: <T = Node>(path: string) => T;
+export declare const isNodeRef: (v: unknown) => v is {
+    $ref: string;
+};
+/** Resolve one ref string against a path-keyed nodes record, scoped upward from `hostPath` (own
+ *  children → parent's scope (siblings + the host itself) → each ancestor scope → root, `""`).
+ *  The ref's FIRST segment binds the scope — a match there is final even when the rest of the
+ *  path doesn't exist (lexical shadowing). Returns the target's ABSOLUTE path, or null.
+ *  `Object.hasOwn`, not indexing: a node named `constructor` must not resolve via the prototype. */
+export declare const resolveRefPath: (nodes: Record<string, unknown>, hostPath: string, ref: string) => string | null;
+/** Swap `ref()` markers in aspect props for the live nodes (top level + one array level deep),
+ *  resolved scoped-upward from `hostPath` ("" = root scope only — the 2D flat-map case). */
+export declare const resolveRefs: <N>(props: Record<string, unknown> | undefined, nodes: Record<string, N>, hostPath?: string) => Record<string, unknown> | undefined;
+/** ABSOLUTE paths of the nodes a props record's ref() values resolve to (editor dep tracking).
+ *  An unresolved ref contributes no dep — the handle re-derives deps after structural changes. */
+export declare const collectRefDeps: (props: Record<string, unknown>, nodes: Record<string, unknown>, hostPath: string) => Set<string>;
+/** The edit-mode flag an editor host sets before running the bundle (shared by both formats). */
+export declare const EDIT_FLAG = "__lecodesSceneEdit";
+export declare const isEditMode: () => boolean;

package/dist/types/scene/level.d.ts

@@ -0,0 +1,98 @@
+import { Node } from "../gl/Node";
+import { type Vec3Like } from "../math/vec";
+/** One placement handed to a `build` function (all coordinates local to the group). */
+export type LevelSpot = {
+    /** 0-based placement index. */
+    index: number;
+    /** Local position the node will be placed at (before jitter was already applied). */
+    position: [number, number, number];
+    /** Yaw in degrees the node will face (already resolved from the `yaw` option). */
+    yaw: number;
+    /** Deterministic per-call random stream (seeded) — use for per-spot variation. */
+    rng: () => number;
+};
+/** What to place: a GLB url (loaded once, cloned per spot), or a builder function. A builder
+ *  returning `null` skips that spot (thin a line, punch a gap in a grid). */
+export type LevelBuild = string | ((spot: LevelSpot) => Node | null | Promise<Node | null>);
+/** Static collision for url builds: 'mesh' = exact triangles, 'convex' = convex hull,
+ *  'box' = auto box from the mesh bounds, 'none' (default) = no collider. */
+export type LevelCollider = "mesh" | "convex" | "box" | "none";
+type PlaceCommon = {
+    build: LevelBuild;
+    /** Static Shape+Physics attached to url-built nodes (default 'none'). Function builds attach
+     *  their own aspects instead. */
+    collider?: LevelCollider;
+    /** Facing: degrees, 'random', 'face' (forward +Z toward the helper's direction), or 'align'
+     *  (the model's X length-axis along the direction — what fence/wall panels want). Each helper
+     *  picks its natural default. */
+    yaw?: number | "random" | "face" | "align";
+    /** Random XZ offset per spot, meters: a radius, or [maxX, maxZ]. */
+    jitter?: number | [number, number];
+    /** Seed for the deterministic random stream (default 1). */
+    seed?: number;
+    /** Child name prefix (default: the url's basename, else 'item'). */
+    name?: string;
+};
+export type LevelLineOptions = PlaceCommon & {
+    from: Vec3Like;
+    to: Vec3Like;
+    /** Fixed number of placements (endpoints included when count > 1)… */
+    count?: number;
+    /** …or a spacing in meters (placements from `from` toward `to`, last one ≤ `to`). */
+    step?: number;
+};
+export type LevelGridOptions = PlaceCommon & {
+    /** Grid center (default [0,0,0]). */
+    center?: Vec3Like;
+    cols: number;
+    rows: number;
+    /** Cell size in meters: one number or [alongX, alongZ]. */
+    spacing: number | [number, number];
+};
+export type LevelRingOptions = PlaceCommon & {
+    /** Ring center (default [0,0,0]). */
+    center?: Vec3Like;
+    radius: number;
+    count: number;
+    /** Start angle in degrees (default 0 = +X). */
+    start?: number;
+    /** Arc to cover in degrees (default 360 = full ring, end exclusive). */
+    arc?: number;
+    /** 'face' orientation for rings: toward the center ('in', default) or away ('out'). */
+    facing?: "in" | "out";
+};
+export type LevelScatterOptions = PlaceCommon & {
+    /** Rectangle center (default [0,0,0]). */
+    center?: Vec3Like;
+    /** Rectangle extent in meters: [sizeX, sizeZ] or one number for a square. */
+    size: number | [number, number];
+    count: number;
+    /** Minimum distance between any two placements (rejection-sampled; the helper places as many
+     *  as fit within the attempt budget and logs when it falls short). */
+    minSpacing?: number;
+    /** Keep-out circles `{ x, z, r }` (local), or a predicate — return true to REJECT a point. */
+    avoid?: {
+        x: number;
+        z: number;
+        r: number;
+    }[] | ((x: number, z: number) => boolean);
+    /** Y for every placement (default 0 — scatter is planar; vary height in a build fn). */
+    y?: number;
+};
+export type LevelPlaceOptions = PlaceCommon & {
+    /** Explicit spots: [x, y, z] or [x, y, z, yawDegrees]. */
+    at: (readonly number[])[];
+};
+/** Procedural level building — see the module header. All helpers return a Promise<Node> group to
+ *  return from a `make()` factory (or add to a scene from plain code). */
+export declare const Level: {
+    line: (opts: LevelLineOptions) => Promise<Node>;
+    grid: (opts: LevelGridOptions) => Promise<Node>;
+    ring: (opts: LevelRingOptions) => Promise<Node>;
+    scatter: (opts: LevelScatterOptions) => Promise<Node>;
+    place: (opts: LevelPlaceOptions) => Promise<Node>;
+    /** The seeded PRNG the helpers use (mulberry32) — for custom generators that must stay
+     *  deterministic alongside them. */
+    rng: (seed: number) => (() => number);
+};
+export {};

package/dist/types/scene/material.d.ts

@@ -0,0 +1,76 @@
+import type { ColorInput } from "../core/color";
+import { Material, type LitMaterialOptions, type UnlitMaterialOptions } from "../gl/Material";
+import type { Node } from "../gl/Node";
+/** A shader parameter value as scene files write it: number, boolean, `#colour`, texture URL
+ *  (`asset('./x.png')`), or a numeric vector. */
+export type MaterialParamValue = number | boolean | string | number[];
+type WithMapUrl<T> = Omit<T, "map"> & {
+    /** Base-colour texture — a `Texture`, a `Canvas`, or `asset('./x.png')` (a URL string). */
+    map?: LitMaterialOptions["map"] | string;
+};
+export type LitMaterialDef = WithMapUrl<LitMaterialOptions>;
+export type UnlitMaterialDef = WithMapUrl<UnlitMaterialOptions>;
+/** A custom Filament shader (`asset('./x.mat')` — compiled by the platform / `lecodes shaders`)
+ *  plus its parameter values. */
+export type ShaderMaterialDef = {
+    shader: string;
+    params?: Record<string, MaterialParamValue>;
+};
+export type MaterialDef = {
+    lit: LitMaterialDef;
+} | {
+    unlit: UnlitMaterialDef;
+} | {
+    shadow: ColorInput;
+} | ShaderMaterialDef
+/** A material asset (`import m from './x.material'`) — one shared instance. */
+ | MaterialHandle
+/** A code-level Material instance — valid at runtime; the editor shows it read-only. */
+ | Material;
+/** The data forms of MaterialDef (everything but a live instance / handle). */
+export type MaterialData = Exclude<MaterialDef, MaterialHandle | Material>;
+/** Push one parameter into a live material. Textures load asynchronously — the returned promise
+ *  settles once the value is applied (immediately for scalars). */
+export declare const applyMaterialParam: (material: Material, name: string, value: MaterialParamValue | null) => Promise<void>;
+/** Build a live Material from a data def. Resolves once every texture it names has loaded. */
+export declare const createMaterialFromData: (def: MaterialData) => Promise<Material>;
+/**
+ * A material asset: the default export of a `*.material.ts` file. `load()` yields ONE shared
+ * `Material` (cached); scene files hand the handle to `material:` and the loader resolves it.
+ * The editor edits the asset live through `setParam` / `reset` — every node the handle was
+ * applied to follows (`_users`).
+ */
+export declare class MaterialHandle {
+    def: MaterialData;
+    private _instance;
+    private _loading;
+    /** Every (node, slot) this handle was applied to through a scene — the editor re-assigns them
+     *  when the asset's shader changes. */
+    readonly _users: Set<{
+        node: Node;
+        slot: number;
+    }>;
+    constructor(def: MaterialData);
+    /** The shared material instance (built on first use). */
+    load(): Promise<Material>;
+    /** The live instance, if built yet. */
+    get material(): Material | null;
+    /** Editor: assign this material to `node`'s `slot`, remembering the user. */
+    _applyTo(node: Node, slot: number): Promise<Material>;
+    /** Editor: one parameter value, applied live to the shared instance (a texture loads in). */
+    setParam(name: string, value: MaterialParamValue | null): void;
+    /** Editor: replace the whole definition (a shader/kind switch) — rebuilds the instance and
+     *  re-assigns every user. */
+    reset(def: MaterialData): Promise<Material>;
+}
+/** Resolve any `material:` value to a live Material (a handle's shared instance, a data def's
+ *  fresh one, a code instance as is). */
+export declare const resolveMaterialDef: (def: MaterialDef) => Promise<Material>;
+/** Resolve and assign a `material:` value to one slot of a node (tracking handle users). */
+export declare const assignMaterialDef: (node: Node, slot: number, def: MaterialDef) => Promise<Material>;
+/**
+ * Define a material as data — the default export of a `*.material.ts` file. Import it into scene
+ * files (`material: handle`) or code (`const m = await handle.load()`).
+ */
+export declare const defineMaterial: (def: MaterialData) => MaterialHandle;
+export {};

package/dist/types/server/auth/appConfig.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The project's `app.json` subset the server runtime reads (name, auth providers).
+ *
+ * This module is a placeholder the COMPILER REPLACES: `compileServerBundle({ app })` puts a module with the
+ * real values at this same path in chisel's file map (project files win over SDK files), so every SDK module
+ * that imports `app` gets the project's config as a plain dependency — no globals, no evaluation-order games.
+ * Outside a compiled bundle (tests, tooling) `globalThis.__lecodesApp` can stand in.
+ */
+export type AuthProvider = "email" | "google" | "apple" | "yandex" | "vk";
+export type AppConfig = {
+    name?: string;
+    auth?: {
+        providers?: AuthProvider[];
+    };
+};
+export declare const app: AppConfig;

package/dist/types/server/auth/global.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The `auth` server global (docs/backend-plan.md §3.4) — the BUNDLE side. State (`auth.user`,
+ * `auth.session`) is read from the current request, which the host resolved before the endpoint ran;
+ * operations (`auth.email.*`, `auth.oauth.url`, `signIn/signOut`, `sessions`) forward to the host's
+ * `AuthOps` on `globalThis.__lecodesAuth` (a seam: the compiled bundle carries its own SDK copy). Nothing
+ * here touches the db or a secret; `auth.model.*` are pure schema factories.
+ */
+import type { Model, Query } from "../db/types";
+import { type AuthProvider, type SessionFields, type UserFields } from "./models";
+import type { AuthUser, OAuthCredential } from "./types";
+/** The schema of the two built-in models, for typing `auth.sessions` (developer extras aren't visible here). */
+type AuthSchema = {
+    User: Model<UserFields>;
+    Session: Model<SessionFields>;
+};
+export declare const auth: {
+    /** The signed-in user (built-in fields; custom ones via `db.user`) or `null`. Request-scoped. */
+    readonly user: AuthUser | null;
+    /** The device session — exists from the first request, before any login. */
+    readonly session: {
+        readonly id: number;
+    };
+    /**
+     * The signed-in user, or `throw new ApiError(401)`; with `match`, every given field must equal the user's
+     * (`{ role: "admin" }`, `{ plan: "pro" }`) or it's a 403.
+     */
+    requireUser(match?: Record<string, unknown>): AuthUser;
+    email: {
+        /** Emails a 6-digit code to `email` (always resolves — no "email exists" oracle; rate-limited). Needs `"email"` in app.json providers. */
+        sendCode: (email: string) => Promise<void>;
+        /** The only email sign-in: checks the code sent to this device session, finds/creates the `User`, binds the session. */
+        verify: (email: string, code: string) => Promise<AuthUser>;
+    };
+    oauth: {
+        /** A one-time sign-in URL for the platform's OAuth broker (`"google" | "apple" | "yandex" | "vk"`), bound to this device session — open it in the browser. */
+        url: (provider: Exclude<AuthProvider, "email">) => Promise<string>;
+        /**
+         * Sign in with a credential a NATIVE provider SDK produced in the app (client `OAuth.signIn(provider)`):
+         * the platform verifies it with the provider, finds/links/creates the `User`, binds this session. The
+         * in-app counterpart of the browser broker — same accounts either way.
+         */
+        signIn: (provider: Exclude<AuthProvider, "email">, credential: OAuthCredential) => Promise<AuthUser>;
+    };
+    /** Escape hatch for developer-verified identities (Telegram initData, SSO): binds this session to `userId`. */
+    signIn: (userId: number) => Promise<AuthUser>;
+    /** Unbinds the user; the device stays a guest with the same `session.id` (token rotated). */
+    signOut: () => Promise<void>;
+    /** The current user's sessions ("my devices"): a `db.session` query — `await`, `.select()`, `.where(...).updateMany({ revoked: true })`. */
+    readonly sessions: Query<AuthSchema, "Session">;
+    /** Schema-time factories — see ./models.ts. */
+    model: {
+        user: <E extends import("../db/types").Fields = {}>(extra?: E) => import("./models").AuthModel<UserFields & E>;
+        session: <E extends import("../db/types").Fields = {}>(extra?: E) => import("./models").AuthModel<SessionFields & E>;
+    };
+};
+export type { AuthUser };

package/dist/types/server/auth/models.d.ts

@@ -0,0 +1,164 @@
+/**
+ * `auth.model.user({...})` / `auth.model.session()` — the ONLY place auth touches the schema
+ * (docs/backend-plan.md §3.4 / decision 10). Both return ordinary `model(...)`s: the developer registers
+ * them in `defineDb({ User, Session, … })` under exactly those keys (other models relate to them with
+ * `t.one("User")` / `t.one("Session")`), and `defineDb` adds `Session` itself when it isn't declared —
+ * a device session exists from the first request, before any login, so every project db has one.
+ *
+ * Provider identity columns (`googleId`, `appleId`) follow `app.json` `auth.providers`, which the
+ * compiler hands the server bundle through ./appConfig.ts (a module it replaces at compile time).
+ */
+import { type Field } from "../db/fields";
+import type { Fields, Model } from "../db/types";
+import { type AppConfig, type AuthProvider } from "./appConfig";
+export type { AppConfig, AuthProvider };
+/** The project's `app.json` subset: the compiled-in module, else the test/tooling seam, else empty. */
+export declare const appConfig: () => AppConfig;
+export declare const enabledProviders: () => AuthProvider[];
+/** The model name the auth runtime binds to. */
+export declare const AUTH_USER_MODEL = "User";
+export declare const AUTH_SESSION_MODEL = "Session";
+/** Marker on the two auth models (`model()` objects are otherwise plain). */
+export type AuthModelKind = "user" | "session";
+export type AuthModel<F extends Fields> = Model<F> & {
+    readonly __auth: AuthModelKind;
+};
+/** Built-in `User` fields (what `auth.user` is typed with). */
+export declare const userFields: () => {
+    email: Field<string, {
+        kind: "scalar";
+        scalar: "string";
+        optional: true;
+        hasDefault: false;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+    name: Field<string, {
+        kind: "scalar";
+        scalar: "string";
+        optional: true;
+        hasDefault: false;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+    avatar: Field<string, {
+        kind: "scalar";
+        scalar: "string";
+        optional: true;
+        hasDefault: false;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+    /** Plain string column, `"user"` by default — `auth.requireUser({ role: "admin" })` is field equality. */
+    role: Field<string, {
+        kind: "scalar";
+        scalar: "string";
+        optional: false;
+        hasDefault: true;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+    createdAt: Field<number, {
+        kind: "scalar";
+        scalar: "date";
+        optional: false;
+        hasDefault: true;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+};
+export type UserFields = ReturnType<typeof userFields>;
+/** Built-in `Session` fields. `user` is added by `defineDb` when a `User` model exists (schema-time, so a
+ *  db without an auth user model has sessions without a user column). */
+export declare const sessionFields: () => {
+    /** sha256 of the bearer token the device holds — the token itself is never stored. */
+    tokenHash: Field<string, import("../db/fields").Meta<{
+        kind: "scalar";
+        scalar: "string";
+    }>>;
+    createdAt: Field<number, {
+        kind: "scalar";
+        scalar: "date";
+        optional: false;
+        hasDefault: true;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+    lastSeenAt: Field<number, {
+        kind: "scalar";
+        scalar: "date";
+        optional: false;
+        hasDefault: true;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+    revoked: Field<boolean, {
+        kind: "scalar";
+        scalar: "bool";
+        optional: false;
+        hasDefault: true;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+    pendingEmail: Field<string, {
+        kind: "scalar";
+        scalar: "string";
+        optional: true;
+        hasDefault: false;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+    codeHash: Field<string, {
+        kind: "scalar";
+        scalar: "string";
+        optional: true;
+        hasDefault: false;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+    codeExpires: Field<number, {
+        kind: "scalar";
+        scalar: "date";
+        optional: true;
+        hasDefault: false;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+    codeAttempts: Field<number, {
+        kind: "scalar";
+        scalar: "int";
+        optional: false;
+        hasDefault: true;
+        array: false;
+        isId: false;
+        model: "";
+    }>;
+};
+export type SessionFields = ReturnType<typeof sessionFields> & {
+    user: ReturnType<typeof sessionUserField>;
+};
+export declare const sessionUserField: () => Field<never, {
+    kind: "one";
+    scalar: "";
+    optional: true;
+    hasDefault: false;
+    array: false;
+    isId: false;
+    model: "User";
+}>;
+/** `auth.model.user({...extra})` — the built-in user (+ provider ids from app.json) plus the developer's fields. */
+export declare const authUserModel: <E extends Fields = {}>(extra?: E) => AuthModel<UserFields & E>;
+/** `auth.model.session({...extra})` — declare it only to relate to sessions (`t.one("Session")`) or to add fields. */
+export declare const authSessionModel: <E extends Fields = {}>(extra?: E) => AuthModel<SessionFields & E>;
+export declare const isAuthModel: (m: unknown, kind?: AuthModelKind) => m is AuthModel<any>;