@wenathlan/saddle 2.0.154 → 2.0.155

package/dist/db.d.ts

@@ -1,569 +0,0 @@
-/**
- * db.ts — node:sqlite data layer for the saddle web node (v7-BACK).
- *
- * the whole persistence surface of a node (main or clone) lives in this
- * module: one sqlite database opened through the native node:sqlite
- * DatabaseSync driver, the embedded migrations (executeschema), prepared
- * statements memoized once per process and one small function api per
- * table. the file is created with mode 0o600 right after open because it
- * carries password hashes and session token hashes.
- *
- * contexts (13): dbopen, filemode, rowtypes, executeschema, users,
- * sessions, nodes, sandboxes, sandboxfiles, events, audit, labels, counts.
- *
- * rules: lowercase identifiers, english jsdoc in third person, no emoji,
- * try/catch on every fallible path with the standardized {code,message}
- * error shape, node:* modules only, zero dependencies.
- */
-import { DatabaseSync } from 'node:sqlite';
-/** one users row: the password hash and salt never leave the server. */
-export type UserRow = {
-    id: string;
-    username: string;
-    passwordhash: string;
-    salt: string;
-    role: string;
-    createdat: string;
-    lastlogin: string | null;
-};
-/** one sessions row (only the sha256 token hash is persisted). */
-export type SessionRow = {
-    tokenhash: string;
-    userid: string;
-    createdat: string;
-    expiresat: string;
-    ip: string | null;
-    useragent: string | null;
-};
-/** one mesh registry nodes row. */
-export type NodeRow = {
-    id: string;
-    url: string;
-    rolename: string | null;
-    region: string | null;
-    lastheartbeat: string | null;
-    status: string | null;
-    registeredat: string;
-    meta: string | null;
-};
-/** one sandboxes lifecycle row: the identity columns are always written
- * non-null by createsandboxrecord; the usage counters and the optional
- * per-sandbox quota stay nullable until their first stamp. */
-export type SandboxRow = {
-    id: string;
-    userid: string | null;
-    model: string;
-    vcpus: number;
-    ramgb: number;
-    gpu: string;
-    state: string;
-    createdat: string;
-    expiresat: string | null;
-    files: number | null;
-    bytes: number | null;
-    quotabytes: number | null;
-};
-/** one sandboxfiles row projection (contents stay out of listfiles). */
-export type SandboxFileRow = {
-    path: string;
-    size: number;
-    updatedat: string;
-};
-/** one stored workspace file document (content decoded from the blob cell). */
-export type SandboxFileDoc = {
-    path: string;
-    content: string;
-    size: number;
-    updatedat: string;
-};
-/** the workspace usage counters of one sandbox. */
-export type WorkspaceUsage = {
-    files: number;
-    bytes: number;
-};
-/** one events row: the payload stays the raw json text cell until the
- * events poll parses it into the view document. */
-export type EventRow = {
-    id: number;
-    topic: string | null;
-    payload: string | null;
-    nodeid: string | null;
-    createdat: string;
-};
-/** one audit row (register, login, logout, sandbox lifecycle, mesh
- * registration). */
-export type AuditRow = {
-    id: number;
-    userid: string | null;
-    action: string | null;
-    detail: string | null;
-    ip: string | null;
-    createdat: string;
-};
-/** one onboarding_states row (the entry-flow gates of a visitor). */
-export type OnboardingStateRow = {
-    id: number;
-    visitor: string;
-    introseen: number;
-    onboardingseen: number;
-    updatedAt: string;
-};
-/** the boolean projection of the onboarding flags the gateway serves. */
-export type OnboardingFlags = {
-    introseen: boolean;
-    onboardingseen: boolean;
-};
-/** one labels row: the interface copy store. the id is the page.widget.key
- * path, the text rides the english source of truth (labels.ts), and the
- * translated flag protects a runtime translation from the seed overwrite.
- * the shape mirrors the browser seed rows in labels.ts one to one. */
-export type LabelRow = {
-    id: string;
-    text: string;
-    revision: number;
-    updatedAt: string;
-    translated?: boolean;
-};
-/** the standardized database error: the machine readable code plus the
- * non-enumerable internal and publicmessage properties set by dberror. */
-export type DbError = Error & {
-    code: string;
-    internal?: string;
-    publicMessage?: string;
-};
-/** users row attributes accepted by createuser; the id and createdat are
- * optional so the mesh forward path can pin the main node's values. */
-export type UserFields = {
-    id?: string;
-    username: string;
-    passwordhash: string;
-    salt: string;
-    role?: string;
-    createdat?: string;
-};
-/** the stored user projection returned by createuser. */
-export type UserProjection = {
-    id: string;
-    username: string;
-    role: string;
-    createdat: string;
-};
-/** sessions row attributes accepted by createsession. */
-export type SessionFields = {
-    tokenhash: string;
-    userid: string;
-    expiresat: string;
-    ip?: string;
-    useragent?: string;
-    createdat?: string;
-};
-/** node announcement accepted by registernode. */
-export type NodeAnnouncement = {
-    url: string;
-    rolename?: string;
-    region?: string;
-    meta?: string;
-};
-/** sandbox projection accepted by createsandboxrecord. */
-export type SandboxRecordFields = {
-    id: string;
-    userid?: string;
-    model?: string;
-    vcpus?: number;
-    ramgb?: number;
-    gpu?: string;
-    state: string;
-    createdat?: string;
-    expiresat?: string;
-    quotabytes?: number | null;
-};
-/** event envelope accepted by addevent. */
-export type EventFields = {
-    topic: string;
-    payload?: unknown;
-    nodeid?: string;
-    createdat?: string;
-};
-/** audit envelope accepted by addaudit. */
-export type AuditFields = {
-    userid?: string | null;
-    action: string;
-    detail?: string;
-    ip?: string;
-    createdat?: string;
-};
-/** write receipt returned by writefile. */
-export type WriteReceipt = {
-    path: string;
-    size: number;
-    updatedat: string;
-};
-/** the database file path resolved once at module load. */
-export declare const dbpath: string;
-/**
- * resolves the per-sandbox workspace quota in bytes once per call: the
- * saddle_sandbox_quota_bytes environment variable wins (any positive
- * integer), otherwise the 16 mib default documented in the readme.
- *
- * @returns the quota in bytes.
- */
-export declare function sandboxquota(): number;
-/**
- * creates one user row; the id is a fresh uuid unless the caller pins
- * one (the mesh forward path caches the main node's user rows with
- * their original ids so clone sessions resolve).
- *
- * @param fields the user attributes.
- * @returns the stored user projection.
- */
-export declare function createuser(fields: UserFields): UserProjection;
-/**
- * finds one user by username.
- *
- * @param username the exact username.
- * @returns the full row or null when absent.
- */
-export declare function finduserbyname(username: string): UserRow | null;
-/**
- * finds one user by id.
- *
- * @param id the user id.
- * @returns the full row or null when absent.
- */
-export declare function finduserbyid(id: string): UserRow | null;
-/**
- * lists every user ordered by creation time; the route layer projects
- * out the password hash and salt columns.
- *
- * @returns the full user rows.
- */
-export declare function listusers(): UserRow[];
-/**
- * stamps the last login column with the given timestamp.
- *
- * @param id the user id.
- * @param isotime the iso timestamp.
- * @returns void.
- */
-export declare function updatelastlogin(id: string, isotime: string): void;
-/**
- * persists one session; only the sha256 token hash is stored, never the
- * bearer token itself.
- *
- * @param fields the session attributes.
- * @returns void.
- */
-export declare function createsession(fields: SessionFields): void;
-/**
- * finds one session row by token hash; expiry is enforced by the caller
- * (auth.ts) so clones can forward remote sessions verbatim.
- *
- * @param tokenhash the sha256 hex of the bearer token.
- * @returns the session row or null.
- */
-export declare function findsession(tokenhash: string): SessionRow | null;
-/**
- * deletes one session by token hash.
- *
- * @param tokenhash the sha256 hex of the bearer token.
- * @returns true when a row was removed.
- */
-export declare function deletesession(tokenhash: string): boolean;
-/**
- * removes every expired session (iso strings compare lexicographically).
- * the main node schedules this sweep at boot.
- *
- * @returns the count of removed rows.
- */
-export declare function cleansessions(): number;
-/**
- * registers or re-registers one node keyed by its url: an existing row
- * for the same url is refreshed (new heartbeat, online status) instead
- * of duplicated, so clones can re-register after a restart.
- *
- * @param fields the node announcement.
- * @returns the registry row.
- */
-export declare function registernode(fields: NodeAnnouncement): {
-    id: string;
-    url: string;
-    status: string;
-};
-/**
- * stamps one node heartbeat.
- *
- * @param id the node id.
- * @param isotime the heartbeat timestamp.
- * @returns true when the node id exists.
- */
-export declare function heartbeatnode(id: string, isotime: string): boolean;
-/**
- * lists every registered node ordered by registration time.
- *
- * @returns the node rows.
- */
-export declare function listnodes(): NodeRow[];
-/**
- * persists one sandbox lifecycle row mirroring the in-memory record.
- *
- * @param fields the sandbox projection.
- * @returns void.
- */
-export declare function createsandboxrecord(fields: SandboxRecordFields): void;
-/**
- * updates the state column of one sandbox row (running, destroyed, ...).
- *
- * @param id the sandbox id.
- * @param state the new state.
- * @returns void.
- */
-export declare function updatesandboxstate(id: string, state: string): void;
-/**
- * lists every sandbox row, newest first.
- *
- * @param limit the row cap.
- * @returns the sandbox rows.
- */
-export declare function listsandboxes(limit?: number): SandboxRow[];
-/**
- * lists the sandbox rows owned by one user, newest first.
- *
- * @param userid the owner id.
- * @param limit the row cap.
- * @returns the sandbox rows.
- */
-export declare function listsandboxesbyuser(userid: string, limit?: number): SandboxRow[];
-/**
- * finds one sandbox row by id; the files surface resolves ownership
- * through this lookup even when the in-memory record is gone (expired
- * sandbox or restarted process).
- *
- * @param id the sandbox id.
- * @returns the sandbox row or null.
- */
-export declare function findsandboxbyid(id: string): SandboxRow | null;
-/**
- * stamps the workspace usage counters of one sandbox row.
- *
- * @param id the sandbox id.
- * @param files the file count.
- * @param bytes the total content bytes.
- * @returns void.
- */
-export declare function updatesandboxusage(id: string, files: number, bytes: number): void;
-/**
- * writes (or overwrites) one workspace file; the sandbox quota caps the
- * summed size of every file of the sandbox and an over-quota write
- * throws the standardized "quota exceeded" error without touching the
- * stored rows.
- *
- * @param sandboxid the sandbox id.
- * @param path the normalized absolute path.
- * @param content the file text (null and undefined write as empty).
- * @param customquota the optional per-sandbox quota in bytes, always
- *   capped by the node maximum.
- * @returns the write receipt.
- */
-export declare function writefile(sandboxid: string, path: string, content: string | null | undefined, customquota?: number): WriteReceipt;
-/**
- * reads one workspace file.
- *
- * @param sandboxid the sandbox id.
- * @param path the normalized absolute path.
- * @returns the file document or null when absent.
- */
-export declare function readfile(sandboxid: string, path: string): SandboxFileDoc | null;
-/**
- * lists every workspace file of one sandbox ordered by path; contents
- * stay out of the projection.
- *
- * @param sandboxid the sandbox id.
- * @returns the file rows.
- */
-export declare function listfiles(sandboxid: string): SandboxFileRow[];
-/**
- * deletes one workspace file.
- *
- * @param sandboxid the sandbox id.
- * @param path the normalized absolute path.
- * @returns true when a row was removed.
- */
-export declare function deletefile(sandboxid: string, path: string): boolean;
-/**
- * removes every workspace file of one sandbox; the purge path of the
- * delete endpoint calls this so a destroyed sandbox leaves nothing
- * behind.
- *
- * @param sandboxid the sandbox id.
- * @returns the count of removed rows.
- */
-export declare function deletesandboxfiles(sandboxid: string): number;
-/**
- * sums the workspace usage of one sandbox.
- *
- * @param sandboxid the sandbox id.
- * @returns the usage counters.
- */
-export declare function sandboxusage(sandboxid: string): WorkspaceUsage;
-/**
- * appends one event row; the payload is stored as a json string.
- *
- * @param fields the event envelope.
- * @returns the inserted event id.
- */
-export declare function addevent(fields: EventFields): number;
-/**
- * lists the events with id greater than the cursor, oldest first, so
- * the dashboard can poll /api/v1/events?since=<lastid>.
- *
- * @param since the exclusive id cursor.
- * @param limit the row cap.
- * @returns the event rows.
- */
-export declare function listevents(since?: number, limit?: number): EventRow[];
-/**
- * appends one audit row (register, login, logout, sandbox lifecycle,
- * mesh registration).
- *
- * @param fields the audit envelope.
- * @returns the inserted audit id.
- */
-export declare function addaudit(fields: AuditFields): number;
-/**
- * lists the audit trail, newest first.
- *
- * @param limit the row cap.
- * @returns the audit rows.
- */
-export declare function listaudit(limit?: number): AuditRow[];
-/**
- * reads the onboarding stage flags of one visitor (parameterized; null
- * when the visitor never touched the flow). the platform gateway serves
- * these over GET /api/v1/onboarding for the browser accessor
- * onboardingstate.ts.
- *
- * @param visitor the stable visitor id.
- * @returns the flags, or null when no row exists.
- */
-export declare function getonboardingstate(visitor: string): OnboardingFlags | null;
-/**
- * marks one onboarding stage seen for a visitor — idempotent seen-wins
- * upsert: the flags only ever move forward, so a replayed stage (or an
- * out-of-order gateway write) never unsees an earlier one.
- *
- * @param visitor the stable visitor id.
- * @param stage the stage being marked seen ("intro" or "onboarding"; the
- *   onboarding stage implies the intro — the flow order).
- * @returns the flags as they stand after the write.
- */
-export declare function setonboardingstage(visitor: string, stage: 'intro' | 'onboarding'): OnboardingFlags;
-/**
- * writes one label row (idempotent upsert; the caller owns the revision).
- *
- * @param id the page.widget.key path of the label.
- * @param text the surface text.
- * @param revision the manifest revision the text carries.
- * @param translated true when the row carries a runtime translation.
- * @returns the stored label projection.
- */
-export declare function savelabel(id: string, text: string, revision: number, translated?: boolean): LabelRow;
-/**
- * reads one label row by its page.widget.key path.
- *
- * @param id the label id.
- * @returns the row or null when absent.
- */
-export declare function readlabel(id: string): LabelRow | null;
-/**
- * reads every label row of the store ordered by id.
- *
- * @returns the label rows.
- */
-export declare function readalllabels(): LabelRow[];
-/**
- * ingests the english manifest of labels.ts into the labels table — the
- * db-side twin of the browser seedlabels: idempotent, the changed rows
- * refresh, and the translated rows stay protected from the overwrite.
- *
- * @returns the seeded and protected row counts.
- */
-export declare function seedlabelrows(): Promise<{
-    seeded: number;
-    protected: number;
-}>;
-/**
- * the overview counts consumed by get /api/v1/admin/overview.
- *
- * @returns the counts.
- */
-export declare function counts(): {
-    users: number;
-    sessions: number;
-    nodes: number;
-    sandboxes: number;
-    events: number;
-    audit: number;
-};
-/**
- * runs the cheapest possible query so /api/v1/health can report whether
- * the database connection answers.
- *
- * @returns true when the round trip succeeds.
- */
-export declare function healthcheck(): boolean;
-/**
- * applies the embedded schema migrations; exported for tools and tests
- * that want to reset or verify the schema explicitly.
- *
- * @param target an optional database handle (defaults to the module
- *   connection).
- * @returns void.
- */
-export declare function executeschema(target?: DatabaseSync): void;
-/** the store singleton: every api function plus close and dispose. */
-declare const store: {
-    dbpath: string;
-    createuser: typeof createuser;
-    finduserbyname: typeof finduserbyname;
-    finduserbyid: typeof finduserbyid;
-    listusers: typeof listusers;
-    updatelastlogin: typeof updatelastlogin;
-    createsession: typeof createsession;
-    findsession: typeof findsession;
-    deletesession: typeof deletesession;
-    cleansessions: typeof cleansessions;
-    registernode: typeof registernode;
-    heartbeatnode: typeof heartbeatnode;
-    listnodes: typeof listnodes;
-    createsandboxrecord: typeof createsandboxrecord;
-    updatesandboxstate: typeof updatesandboxstate;
-    updatesandboxusage: typeof updatesandboxusage;
-    findsandboxbyid: typeof findsandboxbyid;
-    listsandboxes: typeof listsandboxes;
-    listsandboxesbyuser: typeof listsandboxesbyuser;
-    writefile: typeof writefile;
-    readfile: typeof readfile;
-    listfiles: typeof listfiles;
-    deletefile: typeof deletefile;
-    deletesandboxfiles: typeof deletesandboxfiles;
-    sandboxusage: typeof sandboxusage;
-    sandboxquota: typeof sandboxquota;
-    addevent: typeof addevent;
-    listevents: typeof listevents;
-    addaudit: typeof addaudit;
-    listaudit: typeof listaudit;
-    getonboardingstate: typeof getonboardingstate;
-    setonboardingstage: typeof setonboardingstage;
-    savelabel: typeof savelabel;
-    readlabel: typeof readlabel;
-    readalllabels: typeof readalllabels;
-    seedlabelrows: typeof seedlabelrows;
-    counts: typeof counts;
-    healthcheck: typeof healthcheck;
-    executeschema: typeof executeschema;
-    /** closes the connection (idempotent). */
-    close(): void;
-    /** explicit resource management: `using` support for node >= 24. */
-    [Symbol.dispose](): void;
-};
-export default store;