@trylight/app 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,242 @@
+import { PgTable, type PgColumnBuilderBase, type PgTableWithColumns, type PgTableExtraConfigValue } from "drizzle-orm/pg-core";
+import type { BuildColumns, BuildExtraConfigColumns } from "drizzle-orm";
+import { z } from "zod/v4";
+/** Where one value was read: the page, and the words on it that say so. */
+export declare const fieldSource: z.ZodObject<{
+    url: z.ZodURL;
+    evidence: z.ZodString;
+}, z.core.$strip>;
+export type FieldSource = z.infer<typeof fieldSource>;
+/** The site a source's url names, as people read it: "https://www.acme.com/about" is "acme.com". */
+export declare function siteOf(source: FieldSource): string;
+/** A row's `field_sources`: where each of its values was read, by column. */
+export type FieldSources = Partial<Record<string, FieldSource>>;
+/**
+ * Who may use a table through `app.table(...)`. Reads always go through the
+ * app's door: members only, or anyone with the link on a public app. Writes
+ * are either people signed in to the app ("door") or only the org's agents,
+ * through `mii db write` ("agents").
+ */
+export type Access = {
+    readonly read: "door";
+    readonly write: "door" | "agents";
+};
+/** Every entity has these; the platform fills them in. */
+declare function standardColumns(): {
+    id: import("drizzle-orm").HasDefault<import("drizzle-orm").IsPrimaryKey<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgUUIDBuilderInitial<"">>>>;
+    created_at: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampStringBuilderInitial<"">>>;
+    updated_at: import("drizzle-orm").HasDefault<import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampStringBuilderInitial<"">>>>;
+    /** The signed-in person who created it from the app; null for agent writes. */
+    created_by: import("drizzle-orm/pg-core").PgTextBuilderInitial<"", [string, ...string[]]>;
+    field_sources: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm").$Type<import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"">, Partial<Record<string, {
+        url: string;
+        evidence: string;
+    }>>>>>;
+};
+type StandardColumns = ReturnType<typeof standardColumns>;
+/** The columns the platform sets, as a zod omit mask: never in a create or update. */
+export declare const PLATFORM_COLUMNS: {
+    id: true;
+    created_at: true;
+    updated_at: true;
+    created_by: true;
+};
+export type PlatformColumn = keyof typeof PLATFORM_COLUMNS;
+/**
+ * A table of the app, as a Drizzle table with `id`, `created_at`,
+ * `updated_at`, `created_by` and `field_sources` added.
+ *
+ * ```ts
+ * export const companies = entity("companies", {
+ *   name: text().notNull(),
+ *   employees: integer()
+ * }, { read: "door", write: "door" });
+ * ```
+ */
+export declare function entity<TName extends string, TColumns extends Record<string, PgColumnBuilderBase>>(name: TName, columns: TColumns, access: Access, extra?: (self: BuildExtraConfigColumns<TName, StandardColumns & TColumns, "pg">) => PgTableExtraConfigValue[]): PgTableWithColumns<{
+    name: TName;
+    schema: undefined;
+    columns: BuildColumns<TName, StandardColumns & TColumns, "pg">;
+    dialect: "pg";
+}> & {
+    readonly $access: Access;
+};
+/** Any entity table: what the route and the client handle generically. */
+export type Entity = PgTable & {
+    readonly $access: Access;
+    readonly $inferSelect: {
+        field_sources: FieldSources;
+    };
+    readonly $inferInsert: {
+        field_sources?: FieldSources;
+    };
+};
+export declare function isEntity(value: unknown): value is Entity;
+/**
+ * Every change a person makes through `app.table(...)`, with who made it, in
+ * the same transaction as the change. `changes` is the new row for a create,
+ * the old row for a delete, and `{ column: { from, to } }` for an update.
+ */
+export declare const lightChanges: PgTableWithColumns<{
+    name: "light_changes";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "light_changes";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        table_name: import("drizzle-orm/pg-core").PgColumn<{
+            name: "table_name";
+            tableName: "light_changes";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        row_id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "row_id";
+            tableName: "light_changes";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        action: import("drizzle-orm/pg-core").PgColumn<{
+            name: "action";
+            tableName: "light_changes";
+            dataType: "string";
+            columnType: "PgText";
+            data: "create" | "update" | "delete";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["create", "update", "delete"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        changes: import("drizzle-orm/pg-core").PgColumn<{
+            name: "changes";
+            tableName: "light_changes";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, unknown>;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, unknown>;
+        }>;
+        actor_kind: import("drizzle-orm/pg-core").PgColumn<{
+            name: "actor_kind";
+            tableName: "light_changes";
+            dataType: "string";
+            columnType: "PgText";
+            data: "person" | "agent";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["person", "agent"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        actor_id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "actor_id";
+            tableName: "light_changes";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        actor_name: import("drizzle-orm/pg-core").PgColumn<{
+            name: "actor_name";
+            tableName: "light_changes";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        created_at: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "light_changes";
+            dataType: "string";
+            columnType: "PgTimestampString";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+export {};

package/dist/schema.js

@@ -0,0 +1,81 @@
+// What an app's tables are made of: `db/schema/*.ts` declares each with
+// `entity()`, a Drizzle table that also says who may read and write it from
+// the app. Imported by drizzle-kit and the browser's types, so nothing here
+// may touch a database or the DOM.
+import { is } from "drizzle-orm";
+import { PgTable, index, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { z } from "zod/v4";
+/** Where one value was read: the page, and the words on it that say so. */
+export const fieldSource = z.object({
+    url: z.url({ protocol: /^https?$/ }),
+    evidence: z.string().min(1)
+});
+/** The site a source's url names, as people read it: "https://www.acme.com/about" is "acme.com". */
+export function siteOf(source) {
+    return source.url.replace(/^https?:\/\/(www\.)?/, "").replace(/[/?#].*$/s, "");
+}
+/** Every entity has these; the platform fills them in. */
+function standardColumns() {
+    return {
+        id: uuid().primaryKey().defaultRandom(),
+        created_at: timestamp({ withTimezone: true, mode: "string" })
+            .notNull()
+            .defaultNow(),
+        updated_at: timestamp({ withTimezone: true, mode: "string" })
+            .notNull()
+            .defaultNow()
+            .$onUpdate(() => new Date().toISOString()),
+        /** The signed-in person who created it from the app; null for agent writes. */
+        created_by: text(),
+        field_sources: jsonb().$type().notNull().default({})
+    };
+}
+/** The columns the platform sets, as a zod omit mask: never in a create or update. */
+export const PLATFORM_COLUMNS = {
+    id: true,
+    created_at: true,
+    updated_at: true,
+    created_by: true
+};
+/**
+ * A table of the app, as a Drizzle table with `id`, `created_at`,
+ * `updated_at`, `created_by` and `field_sources` added.
+ *
+ * ```ts
+ * export const companies = entity("companies", {
+ *   name: text().notNull(),
+ *   employees: integer()
+ * }, { read: "door", write: "door" });
+ * ```
+ */
+export function entity(name, columns, access, extra) {
+    const standard = standardColumns();
+    const taken = Object.keys(columns).filter((key) => key in standard);
+    if (taken.length > 0) {
+        throw new Error(`${name}: ${taken.join(", ")} ${taken.length === 1 ? "is" : "are"} added by entity(); leave ${taken.length === 1 ? "it" : "them"} out.`);
+    }
+    const all = { ...standard, ...columns };
+    const table = pgTable(name, all, extra);
+    return Object.assign(table, { $access: access });
+}
+export function isEntity(value) {
+    return is(value, PgTable) && "$access" in value;
+}
+/**
+ * Every change a person makes through `app.table(...)`, with who made it, in
+ * the same transaction as the change. `changes` is the new row for a create,
+ * the old row for a delete, and `{ column: { from, to } }` for an update.
+ */
+export const lightChanges = pgTable("light_changes", {
+    id: uuid().primaryKey().defaultRandom(),
+    table_name: text().notNull(),
+    row_id: uuid().notNull(),
+    action: text({ enum: ["create", "update", "delete"] }).notNull(),
+    changes: jsonb().$type().notNull(),
+    actor_kind: text({ enum: ["person", "agent"] }).notNull(),
+    actor_id: text(),
+    actor_name: text().notNull(),
+    created_at: timestamp({ withTimezone: true, mode: "string" })
+        .notNull()
+        .defaultNow()
+}, (t) => [index("light_changes_row_idx").on(t.table_name, t.row_id)]);

package/dist/server/entities.d.ts

@@ -0,0 +1,12 @@
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { SessionState } from "./session.js";
+export type Actor = {
+    id: string | null;
+    name: string;
+};
+export type EntitiesOptions = {
+    schema: Record<string, unknown>;
+    db: () => PostgresJsDatabase<Record<string, unknown>>;
+    session: (request: Request) => Promise<SessionState>;
+};
+export declare function createEntitiesHandler(options: EntitiesOptions): (request: Request) => Promise<Response>;

package/dist/server/entities.js

@@ -0,0 +1,270 @@
+// The one route behind `app.table(...)`: list, get, create, update and delete
+// on any entity table, each request checked against the table's own Zod
+// schema and the app's door, and every change recorded in light_changes with
+// who made it, in the same transaction.
+import { and, asc, desc, eq, getTableColumns, getTableName, inArray, isNull } from "drizzle-orm";
+import { isDeepStrictEqual } from "node:util";
+import { createSchemaFactory } from "drizzle-zod";
+import { isSameOrigin } from "@shubh90/app-runtime/chat/server";
+import { z } from "zod/v4";
+import { ENTITIES_PATH, LIST_LIMIT } from "../entities.js";
+import { PLATFORM_COLUMNS, fieldSource, isEntity, lightChanges } from "../schema.js";
+import { env } from "./env.js";
+/** Who writes when the app runs with no sign-in at all: a bare local dev server. */
+const LOCAL_DEVELOPER = { id: null, name: "Local developer" };
+// Postgres's integrity violations: the person's request, not a failure, told with Postgres's reason.
+const UNIQUE_VIOLATION = "23505";
+const FOREIGN_KEY_VIOLATION = "23503";
+const CHECK_VIOLATION = "23514";
+const NOT_NULL_VIOLATION = "23502";
+/** A duplicate or a missing reference: the row conflicts with others. */
+const CONFLICT_CODES = new Set([UNIQUE_VIOLATION, FOREIGN_KEY_VIOLATION]);
+/** A value its column refuses: the request is wrong on its own. */
+const INVALID_CODES = new Set([CHECK_VIOLATION, NOT_NULL_VIOLATION]);
+// JSON carries a date as its ISO string; a date-mode timestamp column takes it.
+const { createInsertSchema, createSelectSchema, createUpdateSchema } = createSchemaFactory({
+    coerce: { date: true }
+});
+/** Where a request points: a whole table, or one row of it. */
+const target = z.union([
+    z.tuple([z.string()]).transform(([table]) => ({ table, id: null })),
+    z.tuple([z.string(), z.uuid()]).transform(([table, id]) => ({ table, id }))
+]);
+const postgresError = z.object({ cause: z.object({ code: z.string(), message: z.string() }) });
+export function createEntitiesHandler(options) {
+    const tables = new Map(Object.values(options.schema)
+        .filter(isEntity)
+        .map((entity) => [getTableName(entity), tableRules(entity)]));
+    return async (request) => {
+        const url = new URL(request.url);
+        // Every org app shares one site (*.miis.run): only this app's pages may use it.
+        if (!isSameOrigin(request, url)) {
+            return refuse(403, "cross_site", "Only this app's own pages can use its data.");
+        }
+        // No Plaza to sign in with: only a bare local dev server serves (as the
+        // local developer). A deployment or a sandbox missing its sign-in config serves nothing.
+        const { configured, local } = env();
+        if (!configured && !local) {
+            return refuse(503, "auth_not_configured", "Sign-in isn't configured for this app.");
+        }
+        const path = target.safeParse(url.pathname.slice(ENTITIES_PATH.length + 1).split("/"));
+        const table = path.success ? tables.get(path.data.table) : undefined;
+        if (!path.success || table === undefined) {
+            return refuse(404, "not_found", `Nothing is at ${url.pathname}.`);
+        }
+        const session = await options.session(request);
+        const db = options.db();
+        const id = path.data.id;
+        const method = request.method;
+        if (method === "GET") {
+            // Members-only: someone signed in; anyone with the link (and a local dev server): anyone.
+            if (session.user === null && session.mode === "members") {
+                return refuse(401, "not_signed_in", "Sign in to use this app.");
+            }
+            return id === null ? list(db, table, url) : answer(() => get(db, table, id));
+        }
+        if (table.entity.$access.write === "agents") {
+            return refuse(403, "agents_only", `${table.name} is written by the org's agents, not from the app.`);
+        }
+        const actor = local ? LOCAL_DEVELOPER : signedIn(session);
+        if (actor === null)
+            return refuse(401, "not_signed_in", "Sign in to change this app's data.");
+        if (id === null && method === "POST") {
+            const data = await readBody(request, table.create);
+            if (!data.success)
+                return refuse(400, "invalid", z.prettifyError(data.error));
+            return answer(() => create(db, table, actor, data.data), 201);
+        }
+        if (id !== null && method === "PATCH") {
+            const patch = await readBody(request, table.update);
+            if (!patch.success)
+                return refuse(400, "invalid", z.prettifyError(patch.error));
+            return answer(() => update(db, table, actor, id, patch.data));
+        }
+        if (id !== null && method === "DELETE")
+            return answer(() => remove(db, table, actor, id));
+        return refuse(405, "method", `${method} isn't something ${url.pathname} does.`);
+    };
+}
+/** A table's checks, built once from its Drizzle columns. */
+function tableRules(entity) {
+    const columns = getTableColumns(entity);
+    const names = Object.keys(columns);
+    const column = (name) => {
+        const found = columns[name];
+        if (found === undefined)
+            throw new Error(`No column ${name}.`);
+        return found;
+    };
+    // Only the table's own columns have sources, and each is a {url, evidence}.
+    const sources = z.partialRecord(z.literal(names), fieldSource).optional();
+    /** What a person may send: the table's columns less the platform's, strictly. */
+    const writable = (shape) => z
+        .object({
+        ...Object.fromEntries(Object.entries(shape).filter(([key]) => !(key in PLATFORM_COLUMNS))),
+        field_sources: sources
+    })
+        .strict();
+    const match = Object.fromEntries(Object.entries(createSelectSchema(entity).shape).map(([key, value]) => [key, z.union([value, z.array(value)])]));
+    return {
+        name: getTableName(entity),
+        entity,
+        column,
+        id: column("id"),
+        create: writable(createInsertSchema(entity).shape),
+        update: writable(createUpdateSchema(entity).shape),
+        list: z
+            .object({
+            where: z.object(match).partial().strict().default({}),
+            sort: z.literal([...names, ...names.map((name) => `-${name}`)]).default("-created_at"),
+            limit: z.int().min(1).max(LIST_LIMIT).default(LIST_LIMIT),
+            offset: z.int().min(0).default(0)
+        })
+            .strict()
+    };
+}
+async function list(db, table, url) {
+    const q = url.searchParams.get("q");
+    const query = table.list.safeParse(q === null ? {} : readJson(q));
+    if (!query.success)
+        return refuse(400, "invalid", z.prettifyError(query.error));
+    const { where, sort, limit, offset } = query.data;
+    const order = sort.startsWith("-") ? desc(table.column(sort.slice(1))) : asc(table.column(sort));
+    const conditions = Object.entries(where).map(([name, value]) => {
+        const column = table.column(name);
+        if (value === null)
+            return isNull(column);
+        if (Array.isArray(value))
+            return inArray(column, value);
+        return eq(column, value);
+    });
+    const rows = await db
+        .select()
+        .from(table.entity)
+        .where(and(...conditions))
+        // The id breaks ties, so paging with offset never repeats or skips a row.
+        .orderBy(order, asc(table.id))
+        .limit(limit)
+        .offset(offset);
+    return Response.json(rows);
+}
+async function get(db, table, id) {
+    return atMostOne(await db.select().from(table.entity).where(eq(table.id, id)));
+}
+async function create(db, table, actor, data) {
+    return db.transaction(async (tx) => {
+        const row = exactlyOne(await tx
+            .insert(table.entity)
+            .values({ ...data, created_by: actor.id })
+            .returning());
+        await audit(tx, table, rowId(row), "create", row, actor);
+        return row;
+    });
+}
+async function update(db, table, actor, id, patch) {
+    return db.transaction(async (tx) => {
+        const before = atMostOne(await tx.select().from(table.entity).where(eq(table.id, id)).for("update"));
+        if (before === null)
+            return null;
+        const changed = Object.keys(patch).filter((key) => !isDeepStrictEqual(patch[key], before[key]));
+        // A value a person sets is no longer what its source said; sources sent are merged in.
+        const field_sources = { ...withoutSources(before.field_sources, changed), ...patch.field_sources };
+        const row = exactlyOne(await tx
+            .update(table.entity)
+            .set({ ...patch, field_sources })
+            .where(eq(table.id, id))
+            .returning());
+        const changes = Object.fromEntries([...changed, "field_sources"]
+            .filter((key) => !isDeepStrictEqual(before[key], row[key]))
+            .map((key) => [key, { from: before[key], to: row[key] }]));
+        if (Object.keys(changes).length > 0)
+            await audit(tx, table, id, "update", changes, actor);
+        return row;
+    });
+}
+async function remove(db, table, actor, id) {
+    return db.transaction(async (tx) => {
+        const row = atMostOne(await tx.delete(table.entity).where(eq(table.id, id)).returning());
+        if (row === null)
+            return null;
+        await audit(tx, table, id, "delete", row, actor);
+        return { id };
+    });
+}
+function audit(tx, table, rowId, action, changes, actor) {
+    return tx.insert(lightChanges).values({
+        table_name: table.name,
+        row_id: rowId,
+        action,
+        changes,
+        actor_kind: "person",
+        actor_id: actor.id,
+        actor_name: actor.name
+    });
+}
+/** The row a statement by primary key touched, or null when there is none. */
+function atMostOne(rows) {
+    const [row = null, ...more] = rows;
+    if (more.length > 0)
+        throw new Error(`Expected at most one row, got ${rows.length}.`);
+    return row;
+}
+/** The row an insert or an update that found its row returned. */
+function exactlyOne(rows) {
+    const row = atMostOne(rows);
+    if (row === null)
+        throw new Error("Expected a row back, got none.");
+    return row;
+}
+// What's stored may come from an agent's own write: read as it is, never refused here.
+const storedSources = z.record(z.string(), z.unknown());
+const storedId = z.object({ id: z.uuid() });
+function rowId(row) {
+    return storedId.parse(row).id;
+}
+function withoutSources(stored, columns) {
+    const sources = storedSources.parse(stored);
+    return Object.fromEntries(Object.entries(sources).filter(([column]) => !columns.includes(column)));
+}
+function signedIn(session) {
+    return session.user === null ? null : { id: session.user.id, name: session.user.name };
+}
+/**
+ * Runs a read or write and answers it: the row, 404 for none, 409 for a
+ * duplicate or a missing reference, 400 for a value a check or NOT NULL refuses.
+ */
+async function answer(run, status = 200) {
+    try {
+        const result = await run();
+        if (result === null)
+            return refuse(404, "not_found", "That row doesn't exist.");
+        return Response.json(result, { status });
+    }
+    catch (error) {
+        // Drizzle wraps the driver's error; Postgres's code and words are its cause.
+        const refused = postgresError.safeParse(error);
+        if (refused.success && CONFLICT_CODES.has(refused.data.cause.code)) {
+            return refuse(409, "conflict", refused.data.cause.message);
+        }
+        if (refused.success && INVALID_CODES.has(refused.data.cause.code)) {
+            return refuse(400, "invalid", refused.data.cause.message);
+        }
+        throw error;
+    }
+}
+/** A request body read with its table's schema; text that isn't JSON is refused by the schema too. */
+async function readBody(request, schema) {
+    return schema.safeParse(readJson(await request.text()));
+}
+/** JSON as sent, or the text itself for a schema to refuse. */
+function readJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function refuse(status, code, error) {
+    return Response.json({ error, code }, { status });
+}

package/dist/server/env.d.ts

@@ -0,0 +1,11 @@
+/** Read when asked, not at import: a build imports this without a runtime env. */
+export declare function env(): {
+    databaseUrl: string | undefined;
+    /** Sign-in needs Plaza, this app's id in it, and a database for sessions. */
+    configured: boolean;
+    /**
+     * A bare local dev server: no Plaza and no app id at all (the platform
+     * gives every sandbox and deployment its MII_APP_ID), and not production.
+     */
+    local: boolean;
+};

package/dist/server/env.js

@@ -0,0 +1,24 @@
+// The server env the SDK reads, in one schema: what the platform injects
+// (Vercel env, the sandbox's .env.local).
+import { z } from "zod/v4";
+const serverEnv = z
+    .object({
+    DATABASE_URL: z.string().min(1).optional(),
+    MII_PLAZA_URL: z.url().optional(),
+    MII_APP_ID: z.string().min(1).optional(),
+    NODE_ENV: z.string().optional()
+})
+    .transform((env) => ({
+    databaseUrl: env.DATABASE_URL,
+    /** Sign-in needs Plaza, this app's id in it, and a database for sessions. */
+    configured: Boolean(env.MII_PLAZA_URL && env.MII_APP_ID && env.DATABASE_URL),
+    /**
+     * A bare local dev server: no Plaza and no app id at all (the platform
+     * gives every sandbox and deployment its MII_APP_ID), and not production.
+     */
+    local: !env.MII_PLAZA_URL && !env.MII_APP_ID && env.NODE_ENV !== "production"
+}));
+/** Read when asked, not at import: a build imports this without a runtime env. */
+export function env() {
+    return serverEnv.parse(process.env);
+}

package/dist/server/index.d.ts

@@ -0,0 +1,27 @@
+import { type PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import { type Contracts } from "@shubh90/app-runtime/invoke/server";
+export type { SessionState, SessionUser, SignIn } from "./session.js";
+export { cookieAttributes, safeNext, SESSION_COOKIE } from "@shubh90/app-runtime/auth/core";
+export { defineContracts, InvocationError, type Contracts } from "@shubh90/app-runtime/invoke/server";
+export { createHealthHandler, createSentryTunnelHandler } from "@shubh90/app-runtime/server";
+export declare function createLightServer<S extends Record<string, unknown>, C extends Contracts>(options: {
+    schema: S;
+    contracts: C;
+}): {
+    auth: import("@shubh90/app-runtime/auth/core").MiiAuthCore;
+    session: (request: Request) => Promise<import("./session.js").SessionState>;
+    /** Whether sign-in is configured (a bare local dev server has none). */
+    configured: () => boolean;
+    /** Email and password, checked by Plaza; the session to set as a cookie, or why not. */
+    signIn: (email: string, password: string) => Promise<import("./session.js").SignIn>;
+    /** The app's database, typed by its schema: `light.db.select().from(companies)`. */
+    readonly db: PostgresJsDatabase<S>;
+    /** `/api/light/entities/*`: what `app.table(...)` calls. */
+    entities: (request: Request) => Promise<Response>;
+    /** Server-side starts and reads of the app's contracts. */
+    invoke: import("@shubh90/app-runtime/invoke/server").MiiInvoke<C>;
+    /** `/api/mii/invoke/*`: the contract buttons, forwarded to Plaza as the person. */
+    invokeRoute: (request: Request) => Promise<Response>;
+    /** `/api/mii/chat/*`: the chat bubble's calls to the org's agents. */
+    chatRoute: (request: Request) => Promise<Response>;
+};