@trylight/app 0.3.7 → 0.3.9

package/README.md

@@ -60,8 +60,10 @@ every `POLL_MS` while the tab is visible, at once on focus and reconnect. The
 route answers from `light_changes` with the tables changed since the cursor
 (looking `CHANGES_OVERLAP` behind it, for transactions that committed after
 the last poll read) and the next cursor; never rows. Each changed table's
-queries are invalidated by its key (except a table this tab is writing: the
-write's own refetch follows it), and the route loaders reloaded. `light_changes`' `created_at` index is made
+queries are invalidated: those under its key, and those that list its table in
+`meta.tables` (a query that reads several tables, e.g. a server function's
+join), except a table this tab is writing (the write's own refetch follows
+it); the route loaders are reloaded. `light_changes`' `created_at` index is made
 after every migrate (`src/db/audit.ts`). The poll is one `ChangeFeed`; a pushed
 transport can replace it.
 

package/dist/auth/lookup.d.ts

@@ -1,7 +1,7 @@
 import type { AuthContext } from "./context.js";
 import { type PlazaSession } from "./plaza.js";
 /** The cookie holding this app's own session. Nothing of the platform's is read here. */
-export { SESSION_COOKIE } from "../platform/contract.js";
+export { APP_SESSION_COOKIE as SESSION_COOKIE } from "../brand.generated.js";
 /**
  * How often a session asks the platform whether it still stands. Someone removed from
  * the org is signed out of the app within this long; their chat stops at once,

package/dist/auth/lookup.js

@@ -1,7 +1,7 @@
 import { createHash, randomBytes } from "node:crypto";
 import { checkPlazaSession, revokePlazaSession } from "./plaza.js";
 /** The cookie holding this app's own session. Nothing of the platform's is read here. */
-export { SESSION_COOKIE } from "../platform/contract.js";
+export { APP_SESSION_COOKIE as SESSION_COOKIE } from "../brand.generated.js";
 /**
  * How often a session asks the platform whether it still stands. Someone removed from
  * the org is signed out of the app within this long; their chat stops at once,

package/dist/brand.generated.d.ts

@@ -1,2 +1,4 @@
 /** The platform app's origins, current domain first. */
 export declare const APP_ORIGINS: readonly string[];
+/** The cookie holding an app's own session. */
+export declare const APP_SESSION_COOKIE = "mii_session";

package/dist/brand.generated.js

@@ -1,3 +1,5 @@
 // Generated from config/brand.json by scripts/write-brand.ts. Do not edit.
 /** The platform app's origins, current domain first. */
 export const APP_ORIGINS = ["https://trylight.ai", "https://plaza.miis.run"];
+/** The cookie holding an app's own session. */
+export const APP_SESSION_COOKIE = "mii_session";

package/dist/client.d.ts

@@ -2,6 +2,14 @@ import { type QueryKey } from "@tanstack/react-query";
 import type { Contracts } from "./invoke/server.js";
 import { EntityError, type ListOptions, type NewRow, type Patch, type Row } from "./entities.js";
 import type { Entity } from "./schema.js";
+declare module "@tanstack/react-query" {
+    interface Register {
+        /** `tables`: the tables a query reads when it isn't keyed under one (a server function's join); a write to any refetches it. */
+        queryMeta: {
+            tables: readonly Entity[];
+        };
+    }
+}
 export { EntityError, LIST_LIMIT, type ListOptions, type NewRow, type Sort, type Patch, type Row, type Where } from "./entities.js";
 export type { FieldSource, FieldSources } from "./schema.js";
 export { siteOf } from "./schema.js";
@@ -68,7 +76,8 @@ declare function tableClient<T extends Entity>(entity: T): {
     /**
      * The query key everything this table caches sits under. A page's own
      * query over the table (a server function's totals) keyed under it is
-     * refetched after every write too.
+     * refetched after every write too; one over several tables names them in
+     * `meta.tables` instead.
      */
     key: string[];
     list: (options?: ListOptions<Row<T>>) => Promise<Row<T>[]>;

package/dist/client.js

@@ -13,6 +13,7 @@ import { z } from "zod/v4";
 import { ENTITIES_PATH } from "./platform/contract.js";
 import { EntityError, LIST_LIMIT, tableQueryKey } from "./entities.js";
 import { fetchThroughRestart } from "./platform/restart.js";
+import { reads } from "./platform/live-data.js";
 export { EntityError, LIST_LIMIT } from "./entities.js";
 export { siteOf } from "./schema.js";
 export { imageSrc } from "./images.js";
@@ -124,8 +125,9 @@ function putBack(client, id, before) {
 }
 /** One entity table's rows: plain calls, and TanStack Query hooks over them. */
 function tableClient(entity) {
-    const base = `${ENTITIES_PATH}/${getTableName(entity)}`;
-    const all = tableQueryKey(getTableName(entity));
+    const table = getTableName(entity);
+    const base = `${ENTITIES_PATH}/${table}`;
+    const all = tableQueryKey(table);
     const keys = {
         all,
         list: (options) => [...all, "list", options],
@@ -168,7 +170,7 @@ function tableClient(entity) {
         const client = useQueryClient();
         const refetch = async () => {
             if (client.isMutating({ mutationKey: keys.write }) === 1)
-                await client.invalidateQueries({ queryKey: keys.all });
+                await client.invalidateQueries({ predicate: (query) => reads(query, table) });
         };
         return (_data, error) => {
             if (error === null)
@@ -180,7 +182,8 @@ function tableClient(entity) {
         /**
          * The query key everything this table caches sits under. A page's own
          * query over the table (a server function's totals) keyed under it is
-         * refetched after every write too.
+         * refetched after every write too; one over several tables names them in
+         * `meta.tables` instead.
          */
         key: keys.all,
         list,

package/dist/invoke/server.d.ts

@@ -20,7 +20,7 @@ export type MiiInvoke<C extends Contracts> = {
     readonly handler: (request: Request) => Promise<Response>;
     /**
      * Start a contract from a POST server function, as the person whose request
-     * it is answering, and return the run's id without waiting for it: for work
+     * it is answering (on a public app, a visitor with no session), and return the run's id without waiting for it: for work
      * that must be recorded with its run (a job row that names it). A page
      * follows it with `resume(id)`. Refusals reject with InvocationError, with
      * the codes a button's press gets.

package/dist/invoke/server.js

@@ -6,7 +6,8 @@ import { isSameOrigin, readCookie } from "../chat/server.js";
 import { errorBody } from "../request-error.js";
 import { isUuid } from "../uuid.js";
 import { failedRun, InvocationError } from "./error.js";
-import { INVOKE_BASE_PATH } from "../platform/contract.js";
+import { APP_CALLER_HEADERS, INVOKE_BASE_PATH } from "../platform/contract.js";
+import { env } from "../server/env.js";
 export { InvocationError };
 function routeOf(request) {
     const { pathname } = new URL(request.url);
@@ -21,6 +22,14 @@ function routeOf(request) {
     const [, id = ""] = read;
     return { kind: "read", id };
 }
+function platformPath(route) {
+    switch (route.kind) {
+        case "start":
+            return "/invocations";
+        case "read":
+            return `/invocations/${route.id}`;
+    }
+}
 const invokeBody = z.object({ key: z.string(), input: z.unknown() });
 const plazaInvocation = z.object({
     id: z.string(),
@@ -67,28 +76,40 @@ function startBody(contract, key, rawInput) {
     return JSON.stringify({ contractId: contract.id, input: input.data, outputSchema: contract.outputSchema });
 }
 /**
- * The person behind a request to this app: the session cookie, from one of
+ * The caller behind a request to this app: the session cookie, from one of
  * this app's own pages. Every org app shares one site with every other
  * (*.<domain>), so a page on another org's app can send this app's cookie along.
  */
-async function signedIn(auth, request) {
+async function callerOf(auth, request) {
     if (!isSameOrigin(request, new URL(request.url))) {
         throw new InvocationError(403, "cross_site", "Contracts can only be invoked from this app's own pages.");
     }
     const token = readCookie(request.headers.get("cookie"), auth.SESSION_COOKIE);
-    if (token === null)
-        throw new InvocationError(401, "not_signed_in", "Sign in to use this.");
+    if (token === null) {
+        const { appSecret } = env();
+        if (appSecret === null)
+            throw new InvocationError(401, "not_signed_in", "Sign in to use this.");
+        return { kind: "visitor", appId: miiAuthConfig().appId, secret: appSecret };
+    }
     const session = await auth.resolveSessionWithPlaza(token);
     if (session === null)
         throw new InvocationError(401, "sign_in_again", "Sign out and back in to use it here.");
-    return { token, plazaToken: session.plazaToken };
+    return { kind: "person", token, plazaToken: session.plazaToken };
+}
+function callerHeaders(caller) {
+    switch (caller.kind) {
+        case "person":
+            return { Authorization: `Bearer ${caller.plazaToken}` };
+        case "visitor":
+            return { [APP_CALLER_HEADERS.appId]: caller.appId, [APP_CALLER_HEADERS.secret]: caller.secret };
+    }
 }
-/** One call to the platform's contract API as the person; a refused token ends their session. Rejects only when the platform can't be reached. */
-async function callPlaza(auth, person, call) {
+/** One call to the platform's contract API as the caller; a refused token ends a person's session. Rejects only when the platform can't be reached. */
+async function callPlaza(auth, caller, call) {
     const answer = await fetch(call.target, {
         method: call.method,
         headers: {
-            Authorization: `Bearer ${person.plazaToken}`,
+            ...callerHeaders(caller),
             ...(call.body === null ? {} : { "Content-Type": "application/json" })
         },
         body: call.body,
@@ -96,17 +117,17 @@ async function callPlaza(auth, person, call) {
         redirect: "manual",
         signal: call.signal
     });
-    if (answer.status === 401 || answer.status === 403) {
-        await auth.revokeSession(person.token, answer.status === 403 ? "not_a_member" : "token_rejected");
+    if (caller.kind === "person" && (answer.status === 401 || answer.status === 403)) {
+        await auth.revokeSession(caller.token, answer.status === 403 ? "not_a_member" : "token_rejected");
     }
     return answer;
 }
 const plazaTarget = (path) => new URL(`${miiAuthConfig().plazaUrl}/api/app-contracts/v1${path}`);
-/** One call to the platform as the person, read as JSON. A refusal, or no answer, rejects with InvocationError. */
-async function askPlaza(auth, person, call) {
+/** One call to the platform as the caller, read as JSON. A refusal, or no answer, rejects with InvocationError. */
+async function askPlaza(auth, caller, call) {
     let answer;
     try {
-        answer = await callPlaza(auth, person, call);
+        answer = await callPlaza(auth, caller, call);
     }
     catch (error) {
         if (call.signal !== null && call.signal.aborted)
@@ -143,10 +164,10 @@ export function createMiiInvoke(auth, contracts, { reportError = (error, context
         if (route.kind === "read" && !isUuid(route.id)) {
             return refuse(404, "not_found", "Invocation not found.");
         }
-        let person;
+        let caller;
         let body = null;
         try {
-            person = await signedIn(auth, request);
+            caller = await callerOf(auth, request);
             if (route.kind === "start")
                 body = await readInvoke(request, declared);
         }
@@ -155,7 +176,7 @@ export function createMiiInvoke(auth, contracts, { reportError = (error, context
                 throw error;
             return refuse(error.status, error.code, error.message);
         }
-        const target = plazaTarget(route.kind === "start" ? "/invocations" : `/invocations/${route.id}`);
+        const target = plazaTarget(platformPath(route));
         // How long the platform may hold a read of a pending invocation. This app's own
         // function limit has to outlast it (see the README).
         const wait = new URL(request.url).searchParams.get("wait");
@@ -164,7 +185,7 @@ export function createMiiInvoke(auth, contracts, { reportError = (error, context
         let answer;
         try {
             // The browser giving up ends the platform's hold too.
-            answer = await callPlaza(auth, person, { method: request.method, target, body, signal: request.signal });
+            answer = await callPlaza(auth, caller, { method: request.method, target, body, signal: request.signal });
         }
         catch (error) {
             if (!request.signal.aborted)
@@ -190,17 +211,17 @@ export function createMiiInvoke(auth, contracts, { reportError = (error, context
         return respond(answer.status, plazaInvocation.parse(await answer.json()), declared, reportError);
     };
     const start = async ({ request, key, input, signal = null }) => {
-        const person = await signedIn(auth, request);
+        const caller = await callerOf(auth, request);
         const body = startBody(declared.get(key), key, input);
-        const answer = await askPlaza(auth, person, { method: "POST", target: plazaTarget("/invocations"), body, signal });
+        const answer = await askPlaza(auth, caller, { method: "POST", target: plazaTarget("/invocations"), body, signal });
         return { id: plazaInvocation.parse(answer).id };
     };
     const result = async (key, id, request) => {
-        const person = await signedIn(auth, request);
+        const caller = await callerOf(auth, request);
         const contract = contracts[key];
         if (!isUuid(id))
             throw new InvocationError(404, "not_found", "Invocation not found.");
-        const invocation = plazaInvocation.parse(await askPlaza(auth, person, { method: "GET", target: plazaTarget(`/invocations/${id}`), body: null, signal: null }));
+        const invocation = plazaInvocation.parse(await askPlaza(auth, caller, { method: "GET", target: plazaTarget(`/invocations/${id}`), body: null, signal: null }));
         if (invocation.contractId !== contract.id) {
             throw new InvocationError(404, "not_found", `Invocation ${id} is not a run of "${key}".`);
         }

package/dist/platform/contract.d.ts

@@ -16,6 +16,13 @@ export declare const PLATFORM_AUTH_PATHS: {
     /** "Continue with Google / Microsoft": the platform signs the person in and returns with a one-time code. */
     socialSignIn: string;
 };
+/** An app's server calling the platform as the app, for a visitor with no session: which app, and its secret. */
+export declare const APP_CALLER_HEADERS: {
+    appId: string;
+    secret: string;
+};
+/** The server env that secret is provisioned in. */
+export declare const APP_SECRET_ENV = "PLATFORM_APP_SECRET";
 /** The platform's chat API: an app's chat route forwards any path beneath it, so a new widget route needs no SDK release. */
 export declare const PLATFORM_CHAT_PATH = "/api/app-chat/v1/chat";
 /** What this app's chat server forwards beyond the first contract: the widget, served to every app version, offers only these. */
@@ -24,7 +31,6 @@ export declare const CHAT_FEATURES_HEADER = "X-Mii-Chat-Features";
 export declare const STARTING_HEADER = "x-mii-app-starting";
 /** Every TanStack query the SDK owns sits under this key. */
 export declare const QUERY_ROOT = "light";
-export declare const SESSION_COOKIE = "mii_session";
 export declare const STORAGE_KEYS: {
     /** sessionStorage: the build this tab already reloaded for after a missing chunk, so a second miss on it can't loop. */
     chunkRetryBuildId: string;

package/dist/platform/contract.js

@@ -2,7 +2,7 @@
 // apps and the platform's pane depend on every value here: rename freely, never
 // change a value without both sides moving.
 const NAMESPACE = "light";
-/** The platform's former name: the pane protocol, the session cookie and two routes still carry it. */
+/** The platform's former name: the pane protocol and two routes still carry it. */
 const LEGACY_NAMESPACE = "mii";
 export const ENTITIES_PATH = `/api/${NAMESPACE}/entities`;
 export const CHANGES_PATH = `${ENTITIES_PATH}/_changes`;
@@ -22,6 +22,10 @@ export const PLATFORM_AUTH_PATHS = {
     /** "Continue with Google / Microsoft": the platform signs the person in and returns with a one-time code. */
     socialSignIn: "/api/app-auth/social"
 };
+/** An app's server calling the platform as the app, for a visitor with no session: which app, and its secret. */
+export const APP_CALLER_HEADERS = { appId: "x-app-id", secret: "x-app-secret" };
+/** The server env that secret is provisioned in. */
+export const APP_SECRET_ENV = "PLATFORM_APP_SECRET";
 /** The platform's chat API: an app's chat route forwards any path beneath it, so a new widget route needs no SDK release. */
 export const PLATFORM_CHAT_PATH = "/api/app-chat/v1/chat";
 /** What this app's chat server forwards beyond the first contract: the widget, served to every app version, offers only these. */
@@ -30,7 +34,6 @@ export const CHAT_FEATURES_HEADER = "X-Mii-Chat-Features";
 export const STARTING_HEADER = `x-${LEGACY_NAMESPACE}-app-starting`;
 /** Every TanStack query the SDK owns sits under this key. */
 export const QUERY_ROOT = NAMESPACE;
-export const SESSION_COOKIE = `${LEGACY_NAMESPACE}_session`;
 export const STORAGE_KEYS = {
     /** sessionStorage: the build this tab already reloaded for after a missing chunk, so a second miss on it can't loop. */
     chunkRetryBuildId: `${NAMESPACE}:chunk-retry-build-id`,

package/dist/platform/live-data.d.ts

@@ -1,4 +1,4 @@
-import { type QueryClient } from "@tanstack/react-query";
+import { type Query, type QueryClient } from "@tanstack/react-query";
 import { z } from "zod/v4";
 declare const changes: z.ZodObject<{
     cursor: z.ZodString;
@@ -20,9 +20,12 @@ export type ChangeFeed = (onChanged: (tables: string[]) => void) => () => void;
 export declare function pollChanges(queries: QueryClient, fetchChanges: (since: string | null) => Promise<Poll>): ChangeFeed;
 export declare function fetchChanges(since: string | null): Promise<Poll>;
 /**
- * Each changed table's on-screen queries refetch, and the route loaders. A
- * table this tab is writing is left to its write, whose own refetch follows
- * it (client.ts's settle) and brings these changes too.
+ * Each changed table's on-screen queries refetch, in one go: those keyed under
+ * it, and those that read it among others and say so in `meta.tables`. A table
+ * this tab is writing is left to its write, whose own refetch follows it
+ * (client.ts's settle) and brings these changes too.
  */
 export declare function refreshTables(queries: QueryClient, tables: string[]): void;
+/** Whether a query shows `table`'s rows: keyed under it, or listing it in `meta.tables` (typed in client.ts). */
+export declare function reads(query: Query, table: string): boolean;
 export {};

package/dist/platform/live-data.js

@@ -4,7 +4,8 @@
 // of a change is a ChangeFeed; today a poll of `_changes` that TanStack Query
 // itself runs (refetchInterval while the tab is visible, at once on focus and
 // reconnect), later a pushed one (SSE) behind the same type.
-import { QueryObserver } from "@tanstack/react-query";
+import { QueryObserver, partialMatchKey } from "@tanstack/react-query";
+import { getTableName } from "drizzle-orm";
 import { z } from "zod/v4";
 import { EntityError, tableQueryKey } from "../entities.js";
 import { CHANGES_PATH, QUERY_ROOT } from "./contract.js";
@@ -73,14 +74,18 @@ export async function fetchChanges(since) {
     return changes.parse(await response.json());
 }
 /**
- * Each changed table's on-screen queries refetch, and the route loaders. A
- * table this tab is writing is left to its write, whose own refetch follows
- * it (client.ts's settle) and brings these changes too.
+ * Each changed table's on-screen queries refetch, in one go: those keyed under
+ * it, and those that read it among others and say so in `meta.tables`. A table
+ * this tab is writing is left to its write, whose own refetch follows it
+ * (client.ts's settle) and brings these changes too.
  */
 export function refreshTables(queries, tables) {
-    for (const table of tables) {
-        const key = tableQueryKey(table);
-        if (queries.isMutating({ mutationKey: [...key, "write"] }) === 0)
-            void queries.invalidateQueries({ queryKey: key });
-    }
+    const quiet = tables.filter((table) => queries.isMutating({ mutationKey: [...tableQueryKey(table), "write"] }) === 0);
+    if (quiet.length > 0)
+        void queries.invalidateQueries({ predicate: (query) => quiet.some((table) => reads(query, table)) });
+}
+/** Whether a query shows `table`'s rows: keyed under it, or listing it in `meta.tables` (typed in client.ts). */
+export function reads(query, table) {
+    // eslint-disable-next-line no-restricted-syntax -- TanStack's meta is optional: most queries name no tables
+    return partialMatchKey(query.queryKey, tableQueryKey(table)) || query.meta?.tables.some((entity) => getTableName(entity) === table) === true;
 }

package/dist/server/env.d.ts

@@ -2,6 +2,7 @@
 export declare function env(): {
     databaseUrl: string | undefined;
     unpooledDatabaseUrl: string | undefined;
+    appSecret: string | null;
     /** Sign-in needs the platform, this app's id in it, and a database for sessions. */
     configured: boolean;
     /**

package/dist/server/env.js

@@ -1,6 +1,7 @@
 // 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";
+import { APP_SECRET_ENV } from "../platform/contract.js";
 const serverEnv = z
     .object({
     DATABASE_URL: z.string().min(1).optional(),
@@ -8,11 +9,14 @@ const serverEnv = z
     DATABASE_URL_UNPOOLED: z.string().min(1).optional(),
     MII_PLAZA_URL: z.url().optional(),
     MII_APP_ID: z.string().min(1).optional(),
+    /** What this app's server presents to call the platform as the app, for a visitor with no session. */
+    [APP_SECRET_ENV]: z.string().min(1).nullable().default(null),
     NODE_ENV: z.string().optional()
 })
     .transform((env) => ({
     databaseUrl: env.DATABASE_URL,
     unpooledDatabaseUrl: env.DATABASE_URL_UNPOOLED,
+    appSecret: env[APP_SECRET_ENV],
     /** Sign-in needs the platform, this app's id in it, and a database for sessions. */
     configured: Boolean(env.MII_PLAZA_URL && env.MII_APP_ID && env.DATABASE_URL),
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trylight/app",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "The Light SDK every v2 org app depends on: entities (Drizzle tables with a typed client), sign-in, contracts and in-app chat.",
   "license": "UNLICENSED",
   "type": "module",