@opengeni/api-router 3.0.1 → 3.1.2

package/dist/site-publishing/service.d.ts

@@ -0,0 +1,264 @@
+import { type ErrorCode, type Permission, type SiteHostMapRecord, type SiteHostnameAvailability, type SitePublication, type UpsertSitePublicationRequest } from "@opengeni/contracts";
+import type { AccessGrant } from "@opengeni/contracts";
+import { type ApiRouteDeps } from "@opengeni/core";
+import { SitePublishingError, type PublishedSiteRecord, type SiteDataSite, type SiteHostnameEdgeState, type SitePublicationRecord, type SitePublishingScope, type StoredSiteLimitProfile } from "@opengeni/db";
+import { ApiHttpError } from "../http/api-error.js";
+import { type SiteContentScanner } from "./content-scanner.js";
+import { type SiteEdgeSync } from "./edge-sync.js";
+/**
+ * Published Sites: publication management, the host map, and the work that
+ * follows a change (edge sync, content scan). Postgres is the source of truth;
+ * the edge copies are rebuildable and written after commit, never blocking it.
+ */
+export type SitePublishingDeps = Pick<ApiRouteDeps, "db" | "settings" | "objectStorage"> & Partial<Pick<ApiRouteDeps, "managedEmailTransport">>;
+/** The configured Sites domain, or null when publishing is off (unset or invalid). */
+export declare function configuredSitesDomain(settings: ApiRouteDeps["settings"]): string | null;
+export declare function sitePublishingError(status: number, code: ErrorCode, detail: string, message: string, extra?: Record<string, unknown>): ApiHttpError;
+/** The Sites domain, or 404 when this deployment does not publish Sites. */
+export declare function requireSitesDomain(settings: ApiRouteDeps["settings"]): string;
+export declare function sitePublishingHttpError(error: SitePublishingError): ApiHttpError;
+export declare function runSitePublishing<T>(fn: () => Promise<T>): Promise<T>;
+export type SitePublishingEffects = {
+    edgeSync: SiteEdgeSync;
+    scanner: SiteContentScanner;
+    /** Wait for every scheduled effect (tests and graceful shutdown). */
+    flush(): Promise<void>;
+    /**
+     * Run `run` in the background, at most `SITE_EFFECT_CONCURRENCY` at a time;
+     * the rest wait in a bounded queue (beyond it a task is dropped and logged:
+     * edge copies self-heal and expire, scans and notices are best effort).
+     * Returns false when the task was dropped, so callers can release what
+     * they reserved for it.
+     */
+    schedule(name: string, run: () => Promise<void>): boolean;
+    /** Hostnames with an edge sync running or queued, and what it still owes. */
+    edgeLabels: Map<string, {
+        again: boolean;
+        purge: boolean;
+        siteIdHint: string | null;
+    }>;
+};
+/** Background effects running at once per process. */
+export declare const SITE_EFFECT_CONCURRENCY = 4;
+/**
+ * The app's in-process dispatch, registered with the site-runtime routes, so
+ * publication changes can cancel a Site's conversations through the ordinary
+ * session routes. Without it (the operator script) cancellation is skipped.
+ */
+export declare function setSitePublishingDispatch(settings: ApiRouteDeps["settings"], dispatch: (request: Request) => Promise<Response>): void;
+export declare function sitePublishingDispatch(settings: ApiRouteDeps["settings"]): ((request: Request) => Promise<Response>) | null;
+type SitePublishingEffectsOptions = {
+    fetch?: typeof fetch;
+    backoffMs?: number;
+    scanner?: SiteContentScanner;
+    /** Waiting tasks before new ones are dropped (tests fill a small queue). */
+    queueLimit?: number;
+};
+/** The effects for this deployment's settings (one set per settings object). */
+export declare function sitePublishingEffects(settings: ApiRouteDeps["settings"]): SitePublishingEffects;
+/** Replace the effects for a settings object (tests: a fake fetch or scanner). */
+export declare function configureSitePublishingEffects(settings: ApiRouteDeps["settings"], options: SitePublishingEffectsOptions): SitePublishingEffects;
+/** Whether a Site may be served at all: active and visible to its workspace. */
+export declare function siteServable(site: Pick<PublishedSiteRecord, "status" | "visibility">): boolean;
+export declare function siteHostMapRecord(settings: ApiRouteDeps["settings"], domain: string, publication: SitePublicationRecord, site: PublishedSiteRecord): SiteHostMapRecord;
+/**
+ * The host-map record a hostname should have now: the live Site's, else a
+ * tombstone (unpublished, no version) with a fresh generation, so it replaces
+ * whatever the edge holds for that hostname. Null when no Site is known.
+ */
+export declare function siteHostnameEdgeRecord(settings: ApiRouteDeps["settings"], domain: string, state: SiteHostnameEdgeState, siteIdHint: string | null): SiteHostMapRecord | null;
+/**
+ * Sync one hostname to the edge: read what it should hold (under the
+ * hostname's lock, in a short transaction that commits before any HTTP),
+ * write the live Site's record or a tombstone, purge the edge cache when
+ * asked, and record the generation the edge holds. Then re-read the label's
+ * live generation; if it moved while the HTTP calls ran, write again (up to
+ * `SITE_EDGE_SYNC_ROUNDS` times). No database transaction or lock is held
+ * during the Cloudflare calls. A no-op without edge settings.
+ */
+export declare function syncSiteHostnameEdge(deps: SitePublishingDeps, label: string, options?: {
+    purge?: boolean;
+    siteIdHint?: string | null;
+}): Promise<"synced" | "skipped" | "disabled">;
+/**
+ * After commit: rewrite the edge copy of each hostname (the Site's label and
+ * a released previous one), and purge their edge cache when asked
+ * (takedown, unpublish). A no-op without edge settings; failures are retried
+ * and logged, and a missed sync heals on the next host lookup. Lost if the
+ * process stops first: the KV TTL then bounds how long the edge stays stale.
+ * One sync per hostname at a time; background effects run with bounded
+ * concurrency (`SITE_EFFECT_CONCURRENCY`).
+ */
+export declare function scheduleSiteEdgeSync(deps: SitePublishingDeps, labels: ReadonlyArray<string | null | undefined>, options?: {
+    purge?: boolean;
+    siteIdHint?: string | null;
+}): void;
+/**
+ * Self-heal: the edge copy of a live hostname is behind its publication
+ * (a sync was lost or failed). Schedules one sync per hostname at most every
+ * 30 seconds, and at most `SITE_EDGE_HEALS_PER_MINUTE` in all, per process;
+ * none while a sync for that hostname is already running.
+ */
+export declare function healSiteEdgeIfStale(deps: SitePublishingDeps, publication: Pick<SitePublicationRecord, "label" | "generation" | "edgeSyncedGeneration" | "siteId">): void;
+/**
+ * After commit: scan the URLs in the published version's HTML with the
+ * configured scanner and record the findings. Never blocks publishing; the
+ * `none` scanner records nothing.
+ */
+export declare function scheduleSiteContentScan(deps: SitePublishingDeps, scope: SitePublishingScope, siteId: string, versionId: string | null): void;
+/**
+ * A Site changed outside publishing (new version, rollback, archive, audience):
+ * advance its publication generation and resync the edge, and scan a newly
+ * current version. A no-op when the Site is not published. Never throws.
+ */
+export declare function notifySitePublicationChanged(deps: SitePublishingDeps, scope: SitePublishingScope, siteId: string, options?: {
+    scanVersionId?: string | null;
+}): Promise<void>;
+/**
+ * The one hook every Site artifact mutation runs, from the API routes and
+ * the agent tools alike (publish, rollback, archive, restore): a published
+ * Site follows its Site. `scan` scans the version that became current
+ * (publish and rollback). Replays changed nothing and do nothing.
+ */
+export declare function afterSiteArtifactMutation<T extends {
+    replayed?: boolean;
+    artifact: {
+        id: string;
+        accountId: string;
+        workspaceId: string;
+    };
+    version?: {
+        id: string;
+    } | null;
+}>(deps: SitePublishingDeps, result: T, options?: {
+    scan?: boolean;
+}): Promise<T>;
+/**
+ * Refuse a new version of a published (active) Site while the Opengeni-wide
+ * platform brake is engaged. Sites that are not published, rollbacks and
+ * unpublishing are never braked.
+ */
+export declare function requireSiteVersionPublishOpen(deps: SitePublishingDeps, scope: SitePublishingScope, siteId: string): Promise<void>;
+/** The authority Site agent sessions run with: sessions only, nothing else. */
+export declare const SITE_RUNTIME_AGENT_PERMISSIONS: readonly Permission[];
+/**
+ * A request to an ordinary session route as the Site's service principal
+ * (`site:<siteId>`), with a 60-second delegated token carrying only session
+ * permissions, for in-process dispatch. The Site headers ride along so the
+ * API's Site frame guard and provenance see which Site acts.
+ * `extraPermissions` adds what one request must delegate onward (a
+ * conversation start delegates its Site data tools' permissions).
+ */
+export declare function siteServiceSessionRequest(deps: Pick<SitePublishingDeps, "settings">, scope: SitePublishingScope, site: {
+    id: string;
+    versionId: string | null;
+}, input: {
+    origin: string;
+    method: string;
+    path: string;
+    body?: unknown;
+    label: string;
+    extraPermissions?: readonly Permission[];
+}): Promise<Request>;
+/**
+ * Stop a Site's viewers after a takedown, unpublish or narrower access:
+ * revoke every site-session now, and after commit cancel the Site's agent
+ * conversations that may still be working (in-flight turns and queued
+ * messages), as the Site itself through the ordinary control route. The
+ * gateway refuses new work at once regardless: every site-runtime call
+ * re-checks the publication. Without an in-process dispatch (the operator
+ * script) the cancellation is skipped and logged; per-conversation caps
+ * still bound what running turns can spend.
+ */
+export declare function stopSiteViewers(deps: SitePublishingDeps, scope: SitePublishingScope, siteId: string, options: {
+    revokeSessions?: boolean;
+    cancelConversations?: boolean;
+    /** Cancel only conversations holding tools outside these (see `siteAgentToolsNarrowed`). */
+    toolsNarrowedTo?: {
+        tools: readonly string[];
+        everyoneTools: boolean;
+    };
+    reason: string;
+}): Promise<{
+    revokedSessions: number;
+}>;
+/**
+ * Tell the platform about an abuse report or a flagged content scan: always a
+ * structured log line (`site_abuse_notice`), and, when OPENGENI_SITES_ABUSE_EMAIL
+ * is set, an email through the deployment's managed email transport (at most
+ * one per Site per hour, best effort, after the request). The operator's
+ * cross-workspace queue (`scripts/operator/site-moderation-queue.ts`) lists
+ * everything open.
+ */
+export declare function notifySiteAbuse(deps: SitePublishingDeps, input: {
+    scope: SitePublishingScope;
+    siteId: string;
+    hostname: string;
+    kind: "report" | "flagged_scan";
+    detail: string;
+}): void;
+export type SiteManagement = {
+    scope: SitePublishingScope;
+    site: SiteDataSite;
+    record: PublishedSiteRecord;
+    manager: boolean;
+    admin: boolean;
+    owner: boolean;
+    subjectId: string | null;
+};
+/**
+ * Publication changes come from people and their own agents, never from a
+ * Site page: refuse a request that carries a validated Site origin (a Site or
+ * frame page reaching the API through a host) and an agent started from a
+ * Site page, or acting in a turn one sent (the Site clamp).
+ */
+export declare function requireSitePublicationWriter(deps: SitePublishingDeps, grant: AccessGrant): Promise<void>;
+export declare const SITE_AGENT_OTHER_SITE_MESSAGE = "An agent started from a Site page can change only its own Site and Sites it created";
+/**
+ * Whether `grant` may change a Site's content (new versions, rollback,
+ * archive, restore, audience). An agent started from a Site page may only
+ * for a Site it was started from, or one an agent in its own session tree
+ * created with the artifact tools (the Site's first version records that
+ * session). It never rewrites another Site the person can edit, published
+ * or not, so a page cannot spread itself through the person's drafts. Other
+ * callers are not limited here.
+ */
+export declare function siteAgentMayChangeArtifact(deps: SitePublishingDeps, grant: AccessGrant, artifactId: string): Promise<boolean>;
+/** `siteAgentMayChangeArtifact`, refusing with 403 `site_agent_forbidden`. */
+export declare function requireSiteAgentMayChangeArtifact(deps: SitePublishingDeps, grant: AccessGrant, artifactId: string): Promise<void>;
+/**
+ * Resolve a Site for publication management. The caller must see the Site
+ * (its audience); managers are the Site Data managers (owner, workspace admin,
+ * an agent acting for one, or a person-less key with artifacts:publish).
+ * `mutate` callers must also pass `requireSitePublicationWriter`.
+ */
+export declare function resolveSiteManagement(deps: SitePublishingDeps, grant: AccessGrant, siteId: string, options?: {
+    mutate?: boolean;
+}): Promise<SiteManagement>;
+export declare function requireSiteManager(management: SiteManagement): void;
+export declare function siteLimitInputs(deps: SitePublishingDeps, scope: SitePublishingScope, publication: Pick<SitePublicationRecord, "limitProfile"> | null): Promise<{
+    site: StoredSiteLimitProfile | null;
+    workspace: StoredSiteLimitProfile | null;
+}>;
+/** The publication as the management API returns it. */
+export declare function sitePublicationView(deps: SitePublishingDeps, scope: SitePublishingScope, publication: SitePublicationRecord): Promise<SitePublication>;
+/** Hostname availability for this Site (the label rules, then global uniqueness and the hold). */
+export declare function siteHostnameAvailability(deps: SitePublishingDeps, scope: SitePublishingScope, label: string, siteId: string | null): Promise<SiteHostnameAvailability>;
+/**
+ * Create or change a Site's publication. The caller is a manager; a Site must
+ * be active and visible to its workspace to be served; public access needs the
+ * deployment to allow it; changing the limit profile needs a workspace admin.
+ */
+export declare function upsertSitePublicationForManager(deps: SitePublishingDeps, grant: AccessGrant, management: SiteManagement, request: UpsertSitePublicationRequest): Promise<{
+    publication: SitePublication;
+    created: boolean;
+}>;
+/**
+ * Why a publication change must stop current viewers, or null: unpublished,
+ * a narrower access mode, a removed invitation, or the assistant turned off
+ * (conversations only).
+ */
+export declare function siteAccessNarrowed(before: Pick<SitePublicationRecord, "status" | "access" | "invitedEmails" | "agent">, after: Pick<SitePublicationRecord, "status" | "access" | "invitedEmails" | "agent">): "unpublished" | "access_narrowed" | "agent_disabled" | null;
+/** Whether a Site's workspace tools narrowed: a tool removed. */
+export declare function siteAgentToolsNarrowed(before: Pick<SitePublicationRecord["agent"], "tools">, after: Pick<SitePublicationRecord["agent"], "tools">): boolean;
+export {};

package/dist/site-publishing/session-events.d.ts

@@ -0,0 +1,22 @@
+/** The event types a Site viewer can receive with their content. */
+export declare const SITE_VISIBLE_SESSION_EVENT_TYPES: ReadonlySet<string>;
+export type SiteSessionEventPayloadMode = "summary" | "none";
+/**
+ * Project one event for a Site viewer, or null when it is not an event at all.
+ * Hidden events become an omitted placeholder at the same sequence.
+ */
+export declare function siteSessionEventProjection(event: unknown, options?: {
+    payload?: SiteSessionEventPayloadMode;
+}): Record<string, unknown> | null;
+/** Rewrites a session event stream (SSE or a finite SSE batch) frame by frame. */
+export declare function siteSessionEventSseTransform(): TransformStream<Uint8Array, Uint8Array>;
+/** A forwarded event stream, answered with the Site-safe projection. */
+export declare function siteSessionEventStreamResponse(response: Response): Response;
+/** A forwarded event page, answered with the Site-safe projection. */
+export declare function siteSessionEventPageResponse(response: Response, options?: {
+    payload?: SiteSessionEventPayloadMode;
+}): Promise<Response>;
+/** A page of already projected events with monitoring-read headers. */
+export declare function siteSessionEventPage(events: readonly Record<string, unknown>[], options?: {
+    payload?: SiteSessionEventPayloadMode;
+}, upstream?: Headers): Response;

package/dist/site-publishing/session-views.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Site-safe views of the session reads and command results a published
+ * Site's viewer gets back: the conversation's own text, states and versions,
+ * never the workspace behind it (account and workspace ids, workflow and
+ * attempt ids, tools, sandboxes, metadata, lineage, initiators, people's
+ * subject ids, pause reasons, credentials or human-input answers). Each view
+ * keeps the field shapes the SDK expects, with empty lists and objects where
+ * a field is withheld. Event pages and streams use the event projection in
+ * `session-events.ts`; sessions use `siteSessionProjection`.
+ */
+type Fields = Record<string, unknown>;
+/** A conversation's effective control: its state and versions, and a resume of itself only. */
+export declare function siteControlView(value: unknown): Fields | null;
+/** A turn: its message text, model, place and state. */
+export declare function siteTurnView(value: unknown): Fields | null;
+/** The conversation's queue: its own turns, without machine inputs. */
+export declare function siteQueueView(value: unknown): Fields | null;
+/** A composer draft: text and model only (Site drafts carry nothing else). */
+export declare function siteDraftView(value: unknown): Fields | null;
+/**
+ * A human-input request: its questions without secret specs or review
+ * references, and never the answers or who gave them (a Site does not
+ * answer; answers belong to whoever did, in the console).
+ */
+export declare function siteHumanInputRequestView(value: unknown): Fields | null;
+/** `{ requests }` from the human-input list. */
+export declare function siteHumanInputListView(value: unknown): Fields;
+/** A queue command result (move, edit, delete, steer). */
+export declare function siteQueueMutationView(value: unknown): Fields | null;
+/** An accepted message (composer submit, steer): the event, turn and routing. */
+export declare function siteAcceptedMessageView(value: unknown): Fields | null;
+/** A control result: the receipt and the conversation's control. */
+export declare function siteControlResultView(value: unknown): Fields | null;
+/** An accepted event (`POST /events`): the Site event projection. */
+export declare function siteAcceptedEventView(value: unknown): Fields | null;
+export {};

package/dist/site-publishing/viewer.d.ts

@@ -0,0 +1,40 @@
+import type { SiteAccessMode, SiteViewer } from "@opengeni/contracts";
+import type { Settings } from "@opengeni/config";
+/**
+ * Who may open a published Site. The API decides this on sign-in and again
+ * on every site-runtime call; the gateway's own checks are only a convenience.
+ */
+export type SiteViewerAccessSettings = Pick<Settings, "sitesPublicEnabled" | "sitesLoginOnly">;
+/** Public access needs the deployment switch; without it a public Site is members-only. */
+export declare function effectiveSiteAccess(access: SiteAccessMode, settings: SiteViewerAccessSettings): SiteAccessMode;
+/**
+ * The kind of a signed-in viewer, or null when the Site does not admit them:
+ * workspace members always; invited email addresses (verified) for invited
+ * and public Sites; anyone signed in for public Sites.
+ */
+export declare function signedInSiteViewerKind(input: {
+    access: SiteAccessMode;
+    member: boolean;
+    email: string | null;
+    invitedEmails: readonly string[];
+}): "member" | "invited" | "user" | null;
+/** Anonymous guests reach only public Sites, and never on a login-only deployment. */
+export declare function siteGuestsAllowed(access: SiteAccessMode, settings: SiteViewerAccessSettings): boolean;
+/** Gateway-minted visitor ids: opaque, URL-safe, bounded. */
+export declare const SITE_VISITOR_ID: RegExp;
+export type SiteRuntimeViewer = {
+    kind: SiteViewer["kind"];
+    /** `user:<subject>` or `guest:<visitor>`: the Site Data owner and conversation owner. */
+    principal: string;
+    subjectId: string | null;
+    name: string | null;
+    email: string | null;
+    /** The site-session row when signed in. */
+    sessionId: string | null;
+    /**
+     * Set while a workspace member previews the Site as another role ("View
+     * as visitor"): the viewer is then exactly that role, never more.
+     */
+    viewAs?: "invited" | "public" | null;
+};
+export declare function publicSiteViewer(viewer: SiteRuntimeViewer): SiteViewer;

package/dist/site-session-origin.d.ts

@@ -1,6 +1,31 @@
-import type { ApiRouteDeps } from "@opengeni/core";
-/** Validates a caller-asserted Site association, not browser execution or authority. */
-export declare function resolveSiteSessionOrigin(db: ApiRouteDeps["db"], workspaceId: string, siteId?: string, versionId?: string): Promise<{
-    siteId: string;
-    title: string;
-} | null>;
+import type { AccessGrant } from "@opengeni/contracts";
+import { type SiteFrameHeaders } from "@opengeni/contracts/site-session-http";
+import { type ApiRouteDeps, type SiteSessionOrigin } from "@opengeni/core";
+/** The host-set frame marker and per-frame id a Site request carried. */
+export type SiteFrameMarker = {
+    marker?: string | null | undefined;
+    frameId?: string | null | undefined;
+};
+/**
+ * Validates a host-asserted Site association, not browser execution or
+ * authority. A published Site (id and version) must be visible to the caller.
+ * A request carrying only the host's frame marker came from a frame without a
+ * published Site (inline HTML, a Codemode preview): it is recorded as that
+ * frame (`siteId: null`, `frame`, `frameId`), never as a published Site.
+ */
+export declare function resolveSiteSessionOrigin(db: ApiRouteDeps["db"], grant: AccessGrant, siteId?: string, versionId?: string, frame?: SiteFrameMarker): Promise<SiteSessionOrigin | null>;
+/**
+ * The strict origin of a request a host marked as coming from a Site frame:
+ * an unverifiable published Site fails the request (400/404) instead of
+ * running it without provenance.
+ */
+export declare function resolveSiteRequestOrigin(db: ApiRouteDeps["db"], grant: AccessGrant, frame: SiteFrameHeaders): Promise<SiteSessionOrigin>;
+/**
+ * Run a follow-up command (Send or Steer) inside the request's Site scope when
+ * the published Site bridge supplied a valid origin, so its turn records the
+ * `site` surface. Provenance only: a missing or unverifiable origin leaves the
+ * command unscoped instead of rejecting a message that is otherwise valid.
+ * Requests a host marked as Site frames already run inside their validated
+ * origin (apps/api/src/site-frame-guard.ts), which this keeps.
+ */
+export declare function withOptionalSiteCommandOrigin<T>(db: ApiRouteDeps["db"], grant: AccessGrant, siteId: string | undefined, versionId: string | undefined, run: () => Promise<T>): Promise<T>;

package/dist/site-sql/format.d.ts

@@ -0,0 +1,47 @@
+import { type SiteDbSchemaEntry, type SiteSqlValue } from "@opengeni/contracts";
+/**
+ * Site SQL export and import formats, so a Site's data can always leave
+ * Cloudflare: a SQL dump (schema, then INSERT statements), CSV for one table,
+ * and JSON rows per table. Blobs travel as `{ "$base64": "..." }` in JSON,
+ * X'..' literals in SQL and base64 text in CSV. SQL and JSON keep every value
+ * as stored; CSV turns every value into text (an empty cell is NULL on
+ * import) and blobs into base64.
+ */
+export type SiteSqlExportTable = {
+    name: string;
+    columns: string[];
+    rows: unknown[][];
+};
+/** Rows per INSERT statement of a SQL dump. */
+export declare const SITE_SQL_INSERT_ROWS = 500;
+/**
+ * Most bytes per INSERT statement of a SQL dump: Durable Object SQLite
+ * refuses statements over 100 KB. A single row past this still gets its own
+ * statement (and needs a JSON import to load back).
+ */
+export declare const SITE_SQL_INSERT_BYTES = 90000;
+/** One value as a SQLite literal. */
+export declare function siteSqlLiteral(value: unknown): string;
+/** Schema entries that belong to one table (its own entry, its indexes and triggers), or all. */
+export declare function siteSqlSchemaEntries(schema: readonly SiteDbSchemaEntry[], table?: string): SiteDbSchemaEntry[];
+/** The schema statements of a dump, tables first, each ending with a semicolon. */
+export declare function siteSqlSchemaStatements(schema: readonly SiteDbSchemaEntry[]): string[];
+/**
+ * INSERT statements for one exported page of a table: up to
+ * SITE_SQL_INSERT_ROWS rows and SITE_SQL_INSERT_BYTES bytes each, one
+ * statement per line.
+ */
+export declare function siteSqlInsertStatements(table: SiteSqlExportTable): string[];
+/** A CSV cell for an exported value (formula-safe, like Site Data exports). */
+export declare function siteSqlCsvCell(value: unknown): string;
+export declare function siteSqlCsvLine(values: readonly unknown[]): string;
+/** Rows as objects keyed by column, for JSON exports. */
+export declare function siteSqlRowObjects(table: SiteSqlExportTable): Array<Record<string, unknown>>;
+/**
+ * Rows of a JSON import as column lists and value rows: the columns are every
+ * key any row uses, in first-seen order; a missing key is NULL.
+ */
+export declare function siteSqlImportRows(rows: ReadonlyArray<Record<string, SiteSqlValue>>): {
+    columns: string[];
+    values: SiteSqlValue[][];
+};

package/dist/site-sql/gateway.d.ts

@@ -0,0 +1,50 @@
+import { type SiteDbOperation } from "@opengeni/contracts";
+import type { Settings } from "@opengeni/config";
+/**
+ * The API's client for a Site's Durable Object, through the Site gateway's
+ * internal route (`POST <origin>/_og/internal/site-db/<siteId>/<operation>`).
+ * Requests are signed like gateway -> API requests, in the other direction:
+ * HMAC-SHA256 with the shared gateway secret over `siteGatewayCanonicalString`
+ * (the internal path, the gateway's host, the body digest and the time; no
+ * viewer fields). Every request names a fresh id the Durable Object refuses
+ * to see twice. Nothing here decides who may do what: the service does that
+ * before calling.
+ */
+export type SiteSqlGatewayConfig = {
+    origin: string;
+    secret: string;
+    timeoutMs: number;
+};
+export type SiteSqlGatewaySettings = Pick<Settings, "sitesCloudflareStorageEnabled" | "sitesGatewayInternalOrigin" | "sitesGatewaySecret" | "sitesSqlTimeoutMs">;
+/**
+ * The gateway to call, or null when no gateway origin and secret are
+ * configured. This alone lets the API reach Durable Objects that already
+ * exist (export, inspect, dropping data); offering Site SQL also needs the
+ * flag (siteSqlOffered).
+ */
+export declare function siteSqlGatewayConfig(settings: SiteSqlGatewaySettings): SiteSqlGatewayConfig | null;
+/**
+ * Whether this deployment offers Site SQL: the flag is on and the gateway is
+ * configured. Turning it on, migrating, rebuilding, importing and running
+ * SQL need this; export, inspect and dropping a database only need the
+ * gateway.
+ */
+export declare function siteSqlOffered(settings: SiteSqlGatewaySettings): boolean;
+/** A refusal or failure from the gateway or the Durable Object. */
+export declare class SiteDbCallError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** True when the operation may have run (a timeout or lost response). */
+    readonly outcomeUnknown: boolean;
+    constructor(status: number, code: string, message: string, 
+    /** True when the operation may have run (a timeout or lost response). */
+    outcomeUnknown?: boolean);
+}
+export type SiteDbFetch = (input: string, init: RequestInit) => Promise<Response>;
+/** Sign one internal request. Exported for tests. */
+export declare function signSiteDbRequest(config: Pick<SiteSqlGatewayConfig, "origin" | "secret">, siteId: string, operation: SiteDbOperation, body: string, nowSeconds?: number): {
+    url: string;
+    headers: Record<string, string>;
+};
+/** Call one Durable Object operation and return its JSON. */
+export declare function callSiteDb<T>(config: SiteSqlGatewayConfig, siteId: string, operation: SiteDbOperation, payload: Record<string, unknown>, fetchImpl?: SiteDbFetch): Promise<T>;