@lunora/studio 1.0.0-alpha.36 → 1.0.0-alpha.360

package/dist/packem_shared/app.d-D425h1XO.d.mts

@@ -0,0 +1,352 @@
+import { LunoraAdminClient } from '@lunora/client/admin';
+import { ReactElement } from 'react';
+import { I18n } from '@lingui/core';
+import { FunctionUsagePanel, AnalyticsSqlQueryResult } from '@lunora/bindings/analytics-sql';
+import { CronJobInfo, ScheduleRecord } from '@lunora/client';
+interface AnalyticsPanelProps {
+  /**
+   * Resolve one usage panel. The panel sends only its key; the host's runner
+   * calls an action that builds the statement server-side with
+   * `functionUsageQuery(panel)` from `@lunora/bindings/analytics-sql` and runs it
+   * through `ctx.analyticsSql`. That action reads account analytics, so it must
+   * be admin-gated, and it must take the panel key, never SQL: an action that
+   * ran caller-supplied SQL could read every dataset in the account. Studio passes
+   * its analyticsSqlQuery prop through here; with none, the panel renders an empty
+   * state and makes no network call.
+   */
+  readonly runQuery?: (panel: FunctionUsagePanel) => Promise<AnalyticsSqlQueryResult>;
+}
+interface CronTriggersPanelProps {
+  /**
+   * Load the code-defined cron triggers. Defaults to `client.getCronJobs`,
+   * which hits the worker's admin-gated `/_lunora/admin/cron-jobs` endpoint —
+   * so the panel works out of the box under `<LunoraProvider>`, provided the
+   * worker is built with a `cronJobs` map and `adminToken`. Override it to
+   * source triggers from elsewhere (e.g. tests).
+   */
+  readonly loadCronJobs?: () => Promise<CronJobInfo[]>;
+  /**
+   * Manually fire one cron job by name. Defaults to `client.runCronJob`, which
+   * hits the admin-gated `POST /_lunora/admin/cron-jobs/run` endpoint (the same
+   * dispatch the scheduled trigger runs). When a custom {@link CronTriggersPanelProps.loadCronJobs}
+   * is supplied without a `runCronJob`, the "Run now" control is hidden — useful
+   * for a read-only view.
+   */
+  readonly runCronJob?: (name: string) => Promise<{
+    name: string;
+    ran: boolean;
+  }>;
+}
+interface ScheduledJobsProps {
+  /**
+   * Cancel a pending job by id. Defaults to `client.cancelScheduledJob` when
+   * {@link ScheduledJobsProps.loadJobs} is also left to the client. When a
+   * custom `loadJobs` is supplied without a `cancelJob`, the cancel control is
+   * hidden — useful for a read-only view.
+   */
+  readonly cancelJob?: (id: string) => Promise<{
+    cancelled: boolean;
+  }>;
+  /**
+   * Load the pending scheduled jobs. Defaults to `client.listScheduledJobs`,
+   * which hits the worker's admin-gated `/_lunora/admin/scheduled` endpoint —
+   * so the panel works out of the box under `<LunoraProvider>`, provided the
+   * worker is built with a `schedulerDO` namespace and `adminToken`. Override
+   * it to source jobs from elsewhere.
+   */
+  readonly loadJobs?: () => Promise<ScheduleRecord[]>;
+}
+/**
+ * View — and cancel — the functions queued via `runAfter` / `runAt` on the
+ * scheduler. Cron *triggers* are static wrangler config and don't appear here;
+ * this lists the dynamic, in-flight schedule only.
+ *
+ * Works out of the box under `<LunoraProvider>` via the client's scheduler
+ * admin methods; pass {@link ScheduledJobsProps.loadJobs} /
+ * {@link ScheduledJobsProps.cancelJob} to override the transport.
+ */
+declare const ScheduledJobs: ({ cancelJob, loadJobs }?: ScheduledJobsProps) => ReactElement;
+interface SchedulePanelProps {
+  /** Override how the Cron triggers sub-view loads triggers; see {@link CronTriggersPanel}. */
+  readonly loadCronJobs?: CronTriggersPanelProps["loadCronJobs"];
+  /** Override how the Scheduled jobs sub-view cancels a job; see {@link ScheduledJobs}. */
+  readonly scheduledCancel?: ScheduledJobsProps["cancelJob"];
+  /** Override how the Scheduled jobs sub-view loads jobs; see {@link ScheduledJobs}. */
+  readonly scheduledLoad?: ScheduledJobsProps["loadJobs"];
+}
+/**
+ * The statuses a privacy request moves through, and which of them are terminal.
+ *
+ * `@lunora/privacy` stores them and the Studio's Privacy requests page renders them.
+ * The Studio must not depend on the runtime package, so both read the list from here
+ * and the bundler inlines it into each. A status added here reaches both, and the
+ * Studio's exhaustive badge map fails to compile until it has a variant.
+ */
+/** Every status, in lifecycle order. */
+declare const REQUEST_STATUSES: readonly ["received", "grace", "processing", "ready", "completed", "failed", "cancelled", "expired"];
+type RequestStatus = (typeof REQUEST_STATUSES)[number];
+type RequestType = "erasure" | "export";
+/**
+ * Timestamps are epoch milliseconds. `extendedDueAt` is set only when the deadline was extended, so
+ * the effective deadline is `extendedDueAt ?? dueAt`.
+ */
+interface PrivacyRequestRow {
+  readonly dueAt: number;
+  readonly extendedDueAt?: null | number;
+  readonly id: string;
+  readonly receivedAt: number;
+  readonly status: RequestStatus;
+  readonly subjectId: string;
+  readonly type: RequestType;
+}
+/** What the Studio's Privacy requests page reads and writes. */
+interface PrivacyRequestsSource {
+  /** The open requests, in any order; the page sorts nothing. */
+  listOpenPrivacyRequests: () => Promise<ReadonlyArray<PrivacyRequestRow>>;
+  /** Re-run a failed request. Rejects with the server's message on failure. */
+  retryPrivacyRequest: (id: string) => Promise<unknown>;
+}
+/** Which client method a {@link FunctionDescriptor} is invoked through. */
+type FunctionKind = "action" | "mutation" | "query";
+/**
+ * One argument of a registered function, derived from its `v.*` validator by the
+ * worker's `/_lunora/admin/functions` endpoint. A compact signature shape.
+ */
+interface FunctionArgumentDescriptor {
+  /** Element validator kind for an `array` arg (one level), e.g. `string`. */
+  element?: string;
+  /** The (optional-unwrapped) validator kind, e.g. `string`, `id`, `object`. */
+  kind: string;
+  /** The argument name. */
+  name: string;
+  /** True when the arg is wrapped in `v.optional(...)`. */
+  optional: boolean;
+  /** True when the arg is marked `v.sensitive`: its value is never kept in run history. */
+  sensitive?: true;
+  /** Target table for an `id` arg (`v.id("table")`). */
+  table?: string;
+}
+/**
+ * Runtime descriptor for a registered Lunora function. The function's `kind` is
+ * a compile-time-only phantom on `FunctionReference`, so the runner needs it
+ * spelled out here to know which client method to call. `args` carries the
+ * function's argument signature (absent on responses from an older worker).
+ */
+interface FunctionDescriptor {
+  args?: FunctionArgumentDescriptor[];
+  kind: FunctionKind;
+  /** The `<file>:<function>` identifier, e.g. `messages:list`. */
+  path: string;
+}
+/** Outcome of a single `FunctionRunner` invocation. */
+type RunStatus = "error" | "idle" | "running" | "success";
+interface StudioProps {
+  /**
+   * Resolve one Analytics tab panel by its key (`"volume"`, `"latency"`,
+   * `"hotShards"`). Supply a runner that calls an action in your app which
+   * builds the statement server-side and runs it through `ctx.analyticsSql`:
+   *
+   * ```ts
+   * // lunora/studio-analytics.ts
+   * export const usagePanel = action.input({ panel: v.string() }).action(async ({ args, ctx }) => {
+   *     assertAdmin(ctx); // your own admin check: this reads account analytics
+   *     if (!isFunctionUsagePanel(args.panel)) throw new LunoraError("BAD_REQUEST", "unknown panel");
+   *     const { params, query } = functionUsageQuery(args.panel);
+   *     return ctx.analyticsSql.query(query, params);
+   * });
+   * ```
+   *
+   * The action MUST be admin-gated and MUST take the panel key, never SQL: an
+   * action running caller-supplied SQL could read every dataset in the account.
+   * Without a runner the Analytics tab renders an empty state and issues no
+   * request.
+   *
+   * Pass a STABLE reference — a module-level function, or one held in a
+   * `useCallback`/ref. It is read while building the tab router, so a fresh
+   * inline arrow on every render rebuilds the router and remounts the panel
+   * tree, losing in-progress query state. The same holds for `scheduledLoad`,
+   * `scheduledCancel` and `scheduledCron`.
+   */
+  readonly analyticsSqlQuery?: AnalyticsPanelProps["runQuery"];
+  /**
+   * URL path prefix the studio is mounted under, passed to the router as its
+   * `basepath`. Defaults to `/` (mounted at the origin root). The `@lunora/vite`
+   * dev route serves the studio under `/__lunora`, so it sets this — without
+   * it the router treats `/__lunora` as unknown and bounces to `/data`, escaping
+   * the mount.
+   */
+  readonly basePath?: string;
+  /**
+   * App-owned top-bar + sidebar-footer chrome (theme toggle, admin-token
+   * popover, rules banner). The batteries-included `StudioApp` supplies
+   * this; composing `<Studio>` bare omits those affordances. See {@link StudioChrome}.
+   */
+  readonly chrome?: StudioChrome;
+  /**
+   * Show the data tab's write controls (insert/edit/delete rows). Off by
+   * default; see {@link TableEditor}.
+   *
+   * **This HIDES THE CONTROLS. It does not make anything read-only.** The
+   * write RPCs are gated server-side by `LUNORA_ADMIN_TOKEN` alone — one
+   * all-or-nothing check in `handleAdminRpc`, with no read/write scoping — and
+   * `renderStudioHtml({ adminToken })` already ships that bearer to the
+   * browser. So a viewer handed a studio deployed with `dataEditable: false`
+   * still holds a credential that can write; the buttons are simply absent
+   * from the page. Treat it as an affordance switch for a trusted operator,
+   * never as an authorization boundary. The same holds for
+   * {@link StudioProps.schemaEditable} and {@link StudioProps.runAsIdentity}.
+   */
+  readonly dataEditable?: boolean;
+  /**
+   * Functions exposed in the runner tab. The runner tab only appears when at
+   * least one descriptor is supplied (a query/mutation/action's `kind` is
+   * compile-time-only, so it must be named here).
+   */
+  readonly functions?: FunctionDescriptor[];
+  /** Reuse an existing Lingui instance (wins over `locale`). */
+  readonly i18n?: I18n;
+  /** Shard key every shard-scoped panel targets on first load. */
+  readonly initialShardKey?: string;
+  /** Active locale for the studio's own UI strings. Defaults to `en`. */
+  readonly locale?: string;
+  /**
+   * Inline OpenAPI 3.1 document rendered by the API tab's reference sub-view.
+   * Thread the generated `_generated/openapi.json` here to render it
+   * without a round-trip. When omitted the reference fetches the worker's
+   * admin-gated `GET /_lunora/admin/openapi` endpoint via the client.
+   */
+  readonly openApiSpec?: unknown;
+  /**
+   * Inline OpenRPC 1.x document rendered by the API tab's reference sub-view
+   * when the OpenRPC format is selected. Thread the generated
+   * `_generated/openrpc.json` here to render it without a round-trip. When
+   * omitted the OpenRPC view fetches the worker's admin-gated
+   * `GET /_lunora/admin/openrpc` endpoint via the client.
+   */
+  readonly openRpcSpec?: unknown;
+  /**
+   * The app's data-subject request source for the Privacy requests page, built
+   * from the app's own admin functions (`listOpenPrivacyRequests`,
+   * `retryPrivacyRequest`). Without one the page renders a "not configured" state
+   * and issues no request. Pass a STABLE reference, as for `analyticsSqlQuery`.
+   */
+  readonly privacyRequests?: PrivacyRequestsSource;
+  /**
+   * Allow the function runner to execute a function AS a chosen authenticated
+   * identity (the "Run as identity" tool), so an operator can test auth + RLS
+   * behavior. Security-sensitive: it forges identity on an admin-gated RPC, so
+   * the host MUST set this only on a trusted loopback-dev gate (the same gate
+   * as `dataEditable`) — never in a production/static deploy. Off by default;
+   * see {@link FunctionRunner}.
+   *
+   * Like {@link StudioProps.dataEditable}, leaving it off only hides the tool.
+   * The RPC behind it stays reachable to anyone holding the admin token the
+   * page already carries — the gate is the token, not this flag.
+   */
+  readonly runAsIdentity?: boolean;
+  /**
+   * Override how the schedule tab cancels a job. Defaults to the client's
+   * scheduler admin endpoint; see {@link SchedulePanel}.
+   */
+  readonly scheduledCancel?: SchedulePanelProps["scheduledCancel"];
+  /**
+   * Override how the schedule tab's Cron triggers sub-view loads triggers.
+   * Defaults to the client's `/_lunora/admin/cron-jobs` endpoint; see
+   * {@link SchedulePanel}.
+   */
+  readonly scheduledCron?: SchedulePanelProps["loadCronJobs"];
+  /**
+   * Override how the schedule tab loads jobs. Defaults to the client's
+   * scheduler admin endpoint, so the tab works without extra wiring.
+   */
+  readonly scheduledLoad?: SchedulePanelProps["scheduledLoad"];
+  /**
+   * Show the visual schema editor overlay on the schema diagram (add table /
+   * column / index, written back to `lunora/schema.ts` + codegen). Off by
+   * default. Only the loopback-only dev hosts set this — the write path needs
+   * the project's filesystem + toolchain, so a static deploy leaves it off.
+   *
+   * Like {@link StudioProps.dataEditable}, it hides the overlay rather than
+   * making the diagram read-only: what actually stops a schema write in a
+   * static deploy is that the host has no filesystem to write to, not this
+   * flag.
+   */
+  readonly schemaEditable?: boolean;
+}
+/**
+ * Top-bar + sidebar-footer chrome the `StudioApp` owns (theme + admin
+ * token state, the rules banner) but which renders *inside* the router-owned
+ * {@link StudioLayout} (the header and sidebar footer). The layout is a route
+ * component with no props, so it reads this from context rather than threading
+ * it through the router. Absent (composing `<Studio>` bare) the layout simply
+ * omits those affordances.
+ */
+interface StudioChrome {
+  readonly clearToken: () => void;
+  readonly onTokenChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+  readonly rulesInstalled?: boolean;
+  readonly token: string;
+}
+/**
+ * The composable studio. {@link StudioShell} reads its strings from `useT`,
+ * which needs a `StudioI18nProvider` above it.
+ *
+ * When an `i18n` instance or a `locale` is supplied, this owns a provider so the
+ * studio localises itself standalone. When neither is given it renders the
+ * shell bare and inherits whatever provider is already in scope — the host app's
+ * (`StudioApp` owns one for the top bar too) or the shared default — instead
+ * of nesting a second, redundant provider.
+ */
+declare const Studio: ({ i18n, locale, ...shellProps }: StudioProps) => ReactElement;
+interface StudioAppProps {
+  /**
+   * Admin bearer token to send with every admin request. When omitted the app
+   * renders a small prompt so an operator can paste it at runtime — handy in
+   * dev where you don't want to bake the token into a bundle.
+   */
+  readonly adminToken?: string;
+  /**
+   * URL path prefix the studio is mounted under (router `basepath`). Defaults
+   * to `/`. The `@lunora/vite` dev route sets `/__lunora`. Forwarded to the
+   * composed {@link Studio}.
+   */
+  readonly basePath?: string;
+  /**
+   * Base URL of the Lunora worker the studio talks to. Defaults to the
+   * current origin, which is correct when the studio is served from the
+   * same worker (the `@lunora/vite` dev route) or proxied to it.
+   */
+  readonly baseUrl?: string;
+  /**
+   * Inject a pre-built client instead of constructing one from `baseUrl` +
+   * the admin token. Used by the dev mock harness (and embeddings that own
+   * the client) so the chrome renders against a supplied client; when set,
+   * `baseUrl`/`adminToken` are ignored and this client is never closed here.
+   */
+  readonly client?: LunoraAdminClient;
+  /** UI language for the studio's own strings. Defaults to `en`. */
+  readonly locale?: string;
+  /**
+   * Whether the project's Lunora agent skills ("rules") are installed. When
+   * explicitly `false`, the studio shows a one-line banner pointing at
+   * `lunora rules install`. The loopback dev hosts inject this; a static deploy
+   * leaves it unset (no banner).
+   */
+  readonly rulesInstalled?: boolean;
+  /** Forwarded to the composed {@link Studio} (functions, initialShardKey, scheduled overrides). */
+  readonly studio?: Omit<StudioProps, "children" | "chrome" | "i18n" | "locale">;
+}
+/**
+ * A fully self-contained studio page: it constructs a {@link LunoraAdminClient}
+ * pointed at the worker, wires it through a `<LunoraProvider>`, manages the
+ * admin token + theme, and renders the composed {@link Studio} — handing it the
+ * top-bar/sidebar {@link StudioChrome} (theme toggle, admin-token popover, rules
+ * banner) so those affordances render inside the sidebar shell.
+ *
+ * Mount this directly (the standalone app and the `@lunora/vite` dev route both
+ * do) when you want the batteries-included page rather than composing panels
+ * yourself. For embedding into an existing admin UI, use the individual panels
+ * or `<Studio>` under your own provider instead.
+ */
+declare const StudioApp: ({ adminToken, basePath, baseUrl, client: injectedClient, rulesInstalled, studio, locale }?: StudioAppProps) => ReactElement;
+export { FunctionDescriptor as F, PrivacyRequestRow as P, RunStatus as R, StudioAppProps as S, FunctionKind as a, PrivacyRequestsSource as b, ScheduledJobs as c, ScheduledJobsProps as d, Studio as e, StudioApp as f, StudioProps as g };