@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.1

package/apps/storefront/src/lib/apps/integrationsTab.ts

@@ -0,0 +1,547 @@
+/** Browser controller for the admin managed-analytics surface. */
+import type {
+  AdapterConfigValue,
+  AdapterDefinition,
+  ApiErrorEnvelope,
+  CreateIntegrationInstallRequest,
+  CreateIntegrationInstallResponse,
+  DeleteIntegrationInstallRequest,
+  DeleteIntegrationInstallResponse,
+  GetAdapterDefinitionRequest,
+  GetAdapterDefinitionResponse,
+  IntegrationInstall,
+  IntegrationRevisionV1,
+  ListAdapterDefinitionsRequest,
+  ListAdapterDefinitionsResponse,
+  ListIntegrationInstallsRequest,
+  ListIntegrationInstallsResponse,
+  ListIntegrationRevisionsRequest,
+  ListIntegrationRevisionsResponse,
+  ManagedAnalyticsApiV1Client,
+  ReviseIntegrationInstallRequest,
+  ReviseIntegrationInstallResponse,
+  SetIntegrationInstallStatusRequest,
+  SetIntegrationInstallStatusResponse,
+} from "@tot/public-runtime";
+import { APPROVED_MARKETING_ACTION_NAMES } from "@tot/public-runtime";
+import type { IntegrationAdminReadModel, IntegrationReadModelItem } from "./integrationReadModel";
+import { describeAuthorityTier } from "./integrationsView";
+
+type AdminManagedClient = Pick<ManagedAnalyticsApiV1Client,
+  "listAdapterDefinitions" | "getAdapterDefinition" | "listIntegrationInstalls" |
+  "listIntegrationRevisions" | "createIntegrationInstall" |
+  "reviseIntegrationInstall" | "setIntegrationInstallStatus" |
+  "deleteIntegrationInstall">;
+
+function el(tag: string, className?: string, text?: string): HTMLElement {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function withTenant(base: string, tenant?: string): string {
+  if (!tenant) return base;
+  const separator = base.includes("?") ? "&" : "?";
+  return `${base}${separator}tenant=${encodeURIComponent(tenant)}`;
+}
+
+async function json<T>(response: Response): Promise<T> {
+  try { return await response.json() as T; }
+  catch { return {} as T; }
+}
+
+/** Typed HTTP implementation of the frozen client; method names are the route suffixes. */
+export class ManagedAnalyticsHttpClient implements AdminManagedClient {
+  constructor(private readonly base: string, private readonly tenant?: string) {}
+  private async post<T>(method: string, request: unknown): Promise<T> {
+    const response = await fetch(withTenant(`${this.base}/${method}`, this.tenant), {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify(request),
+    });
+    const body = await json<T>(response);
+    if (!body || typeof body !== "object" || (!("data" in body) && !("error" in body))) {
+      throw new TypeError("Managed analytics response was not a contract envelope.");
+    }
+    return body;
+  }
+  listAdapterDefinitions(request: ListAdapterDefinitionsRequest) { return this.post<ListAdapterDefinitionsResponse>("listAdapterDefinitions", request); }
+  getAdapterDefinition(request: GetAdapterDefinitionRequest) { return this.post<GetAdapterDefinitionResponse>("getAdapterDefinition", request); }
+  listIntegrationInstalls(request: ListIntegrationInstallsRequest) { return this.post<ListIntegrationInstallsResponse>("listIntegrationInstalls", request); }
+  listIntegrationRevisions(request: ListIntegrationRevisionsRequest) { return this.post<ListIntegrationRevisionsResponse>("listIntegrationRevisions", request); }
+  createIntegrationInstall(request: CreateIntegrationInstallRequest) { return this.post<CreateIntegrationInstallResponse>("createIntegrationInstall", request); }
+  reviseIntegrationInstall(request: ReviseIntegrationInstallRequest) { return this.post<ReviseIntegrationInstallResponse>("reviseIntegrationInstall", request); }
+  setIntegrationInstallStatus(request: SetIntegrationInstallStatusRequest) { return this.post<SetIntegrationInstallStatusResponse>("setIntegrationInstallStatus", request); }
+  deleteIntegrationInstall(request: DeleteIntegrationInstallRequest) { return this.post<DeleteIntegrationInstallResponse>("deleteIntegrationInstall", request); }
+}
+
+function isError(value: unknown): value is ApiErrorEnvelope {
+  return !!value && typeof value === "object" && "error" in value;
+}
+
+function key(prefix: string): string {
+  const random = globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  return `${prefix}-${random}`.replace(/[^A-Za-z0-9._:-]/g, "-").slice(0, 128);
+}
+
+interface PendingMutation {
+  operation: string;
+  request: object;
+}
+
+export class PendingManagedMutationError extends Error {
+  constructor(readonly operation: string) {
+    super(`A ${operation} retry is still pending.`);
+  }
+}
+
+/**
+ * Keeps one canonical mutation per resource until an error/success envelope is
+ * received. A thrown transport leaves the exact key and body available for the
+ * operator's retry; a different mutation cannot overtake it.
+ */
+export class ManagedMutationLedger {
+  private readonly pending = new Map<string, PendingMutation>();
+
+  prepare<T extends object>(resource: string, operation: string, request: T): T {
+    const existing = this.pending.get(resource);
+    if (existing) {
+      if (existing.operation !== operation) throw new PendingManagedMutationError(existing.operation);
+      return existing.request as T;
+    }
+    const canonical = JSON.parse(JSON.stringify(request)) as T;
+    this.pending.set(resource, { operation, request: canonical });
+    return canonical;
+  }
+
+  complete(resource: string, operation: string): void {
+    if (this.pending.get(resource)?.operation === operation) this.pending.delete(resource);
+  }
+
+  operation(resource: string): string | undefined { return this.pending.get(resource)?.operation; }
+
+  /** Clear only entries whose effect is proven by a fresh authoritative read. */
+  reconcile(provesCommitted: (resource: string, pending: Readonly<PendingMutation>) => boolean): number {
+    let cleared = 0;
+    for (const [resource, pending] of this.pending) {
+      if (!provesCommitted(resource, pending)) continue;
+      this.pending.delete(resource);
+      cleared += 1;
+    }
+    return cleared;
+  }
+}
+
+function requestRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function sameConfiguration(
+  left: Record<string, AdapterConfigValue>,
+  right: Record<string, AdapterConfigValue>,
+): boolean {
+  const leftKeys = Object.keys(left).sort();
+  const rightKeys = Object.keys(right).sort();
+  return leftKeys.length === rightKeys.length &&
+    leftKeys.every((key, index) => key === rightKeys[index] && left[key] === right[key]);
+}
+
+/**
+ * Reconcile an ambiguous mutation only when a fresh list/read proves its exact
+ * effect. Mere refresh success is not enough: an uncommitted request keeps its
+ * original idempotency key and canonical body for the next retry.
+ */
+export function reconcileManagedMutationLedger(
+  ledger: ManagedMutationLedger,
+  hydrated: ReadonlyMap<string, ManagedInstallView>,
+  installsListComplete: boolean,
+): number {
+  return ledger.reconcile((_resource, pending) => {
+    const request = requestRecord(pending.request);
+    const body = requestRecord(request?.body);
+    const expectedRevision = request?.expectedRevision;
+    if (!body || typeof expectedRevision !== "number") return false;
+
+    if (pending.operation === "create") {
+      const adapterId = body.adapterId;
+      const adapterVersion = body.adapterVersion;
+      const configuration = requestRecord(body.configuration) as Record<string, AdapterConfigValue> | null;
+      if (typeof adapterId !== "string" || typeof adapterVersion !== "string" || !configuration) return false;
+      return [...hydrated.values()].some((view) =>
+        view.install.adapterId === adapterId &&
+        view.revisions !== null &&
+        view.revisions.some((revision) =>
+          revision.sequence === 1 &&
+          revision.adapterVersion === adapterVersion &&
+          sameConfiguration(revision.configuration, configuration),
+        ),
+      );
+    }
+
+    const installId = body.installId;
+    if (typeof installId !== "string") return false;
+    const view = hydrated.get(installId);
+
+    if (pending.operation === "revise" || pending.operation === "rollback-stage") {
+      const adapterVersion = body.adapterVersion;
+      const configuration = requestRecord(body.configuration) as Record<string, AdapterConfigValue> | null;
+      if (!view || view.revisions === null || typeof adapterVersion !== "string" || !configuration) return false;
+      return view.install.revision > expectedRevision && view.revisions.some((revision) =>
+        revision.sequence === expectedRevision + 1 &&
+        revision.adapterVersion === adapterVersion &&
+        sameConfiguration(revision.configuration, configuration),
+      );
+    }
+
+    if (pending.operation === "publish" || pending.operation === "suspend" || pending.operation === "rollback-publish") {
+      const intendedStatus = body.status;
+      if (!view || view.install.revision !== expectedRevision + 1 || view.install.status !== intendedStatus) return false;
+      if (intendedStatus === "disabled") return true;
+      if (intendedStatus !== "enabled" || view.revisions === null || !view.install.activeRevisionId) return false;
+      return !view.revisions.some((revision) => revision.status === "draft") &&
+        view.revisions.some((revision) =>
+          revision.revisionId === view.install.activeRevisionId && revision.status === "active",
+        );
+    }
+
+    if (pending.operation === "remove") return installsListComplete && !view;
+    return false;
+  });
+}
+
+function destination(revision: IntegrationRevisionV1 | undefined): string {
+  const value = revision?.configuration.destinationId;
+  return typeof value === "string" ? value : "";
+}
+
+function statusMessage(error: ApiErrorEnvelope): string {
+  return `${error.error.message} [${error.error.code}]`;
+}
+
+function manualEventVocabulary(card: AdapterDefinition): string[] {
+  return card.eventTypes.flatMap((eventType) => eventType === "storefront.action.activated.v1"
+    ? [...APPROVED_MARKETING_ACTION_NAMES]
+    : [eventType]);
+}
+
+export interface ManagedInstallView {
+  install: IntegrationInstall;
+  definition: AdapterDefinition | null;
+  revisions: IntegrationRevisionV1[] | null;
+  degraded?: "catalog_definition_unavailable" | "revision_history_unavailable";
+}
+
+/** MigrationDraft v1 intentionally resolves adapterVersion from the catalog. */
+export async function resolveMigrationDraftInstallInput(
+  client: Pick<ManagedAnalyticsApiV1Client, "getAdapterDefinition">,
+  draft: { proposedAdapterId: string; proposedConfiguration: Record<string, AdapterConfigValue> },
+): Promise<CreateIntegrationInstallRequest["body"] | ApiErrorEnvelope> {
+  const found = await client.getAdapterDefinition({ apiVersion: "v1", query: { adapterId: draft.proposedAdapterId } });
+  if (isError(found)) return found;
+  return {
+    adapterId: found.data.adapterId,
+    adapterVersion: found.data.adapterVersion,
+    configuration: { ...draft.proposedConfiguration },
+    status: "disabled",
+  };
+}
+
+export function renderCatalog(container: HTMLElement, cards: AdapterDefinition[], canManage = true, busyAdapters: ReadonlySet<string> = new Set(), installedAdapters: ReadonlySet<string> = new Set()): void {
+  container.textContent = "";
+  for (const card of cards) {
+    const wrap = el("article", "integrations-adapter-card");
+    wrap.dataset.adapterId = card.adapterId;
+    const busy = busyAdapters.has(card.adapterId);
+    const installed = installedAdapters.has(card.adapterId);
+    wrap.setAttribute("aria-busy", busy ? "true" : "false");
+    const head = el("div", "integrations-adapter-head");
+    head.append(el("strong", undefined, card.displayName), el("span", "chip", `v${card.adapterVersion}`));
+    wrap.append(head, el("p", "subtle", card.description));
+    const meta = el("dl", "integrations-adapter-meta");
+    for (const [label, value] of [
+      ["Adapter", card.adapterId],
+      ["Collection origins", card.collectionOrigins.join(" ") || "none"],
+      ["Consent", card.consentPurposes.join(", ") || "none"],
+      ["Manual events", manualEventVocabulary(card).join(", ") || "none"],
+    ]) meta.append(el("dt", undefined, label), el("dd", "publish-mono", value));
+    wrap.appendChild(meta);
+    const form = el("div", "integrations-adapter-config");
+    const input = document.createElement("input");
+    input.type = "text";
+    input.autocomplete = "off";
+    input.placeholder = card.configuration[0]?.label ?? "Destination ID";
+    input.setAttribute("aria-label", `${card.displayName} destination ID`);
+    input.dataset.adapterIdInput = card.adapterId;
+    input.disabled = !canManage || card.availability !== "available" || busy || installed;
+    const button = el("button", "btn", installed ? "Already configured" : "Configure disabled") as HTMLButtonElement;
+    button.type = "button";
+    button.dataset.configureAdapter = card.adapterId;
+    button.disabled = input.disabled;
+    form.append(input, button);
+    const result = el("p", "note integrations-adapter-result");
+    result.dataset.adapterResult = card.adapterId;
+    result.setAttribute("role", "status");
+    result.setAttribute("aria-live", "polite");
+    result.hidden = !busy;
+    if (busy) result.textContent = "Creating managed install…";
+    wrap.append(form, result);
+    container.appendChild(wrap);
+  }
+}
+
+export function renderManagedInventory(tbody: HTMLElement, views: ManagedInstallView[], canManage = true, busyInstalls: ReadonlySet<string> = new Set()): void {
+  tbody.textContent = "";
+  if (!views.length) {
+    const row = document.createElement("tr");
+    const cell = el("td", "subtle", "No managed analytics installs yet.");
+    cell.setAttribute("colspan", "5"); row.appendChild(cell); tbody.appendChild(row); return;
+  }
+  for (const view of views) {
+    const { install, definition, revisions } = view;
+    const busy = busyInstalls.has(install.installId);
+    const row = document.createElement("tr");
+    row.dataset.managedInstallId = install.installId;
+    row.setAttribute("aria-busy", busy ? "true" : "false");
+    const identity = el("td");
+    identity.append(el("strong", undefined, definition?.displayName ?? install.adapterId), el("span", "subtle", definition ? `${install.adapterId} · v${definition.adapterVersion}` : "Catalog definition unavailable"));
+    row.appendChild(identity);
+    const state = el("td");
+    state.append(el("span", `chip ${install.status === "enabled" ? "green" : ""}`.trim(), install.status), el("span", "subtle", `CAS ${install.revision}`));
+    row.appendChild(state);
+    const history = el("td");
+    const ordered = [...(revisions ?? [])].sort((a, b) => b.sequence - a.sequence);
+    if (view.degraded) history.appendChild(el("span", "publish-diff-blocked", view.degraded === "catalog_definition_unavailable" ? "Catalog definition unavailable; changes are disabled." : "Revision history unavailable; changes are disabled."));
+    for (const revision of ordered) history.appendChild(el("span", "subtle", `#${revision.sequence} ${revision.status} · ${revision.adapterVersion}`));
+    if (ordered[0]) history.appendChild(el("span", "subtle", `Activity ${ordered[0].createdAt}`));
+    row.appendChild(history);
+    const configuration = el("td");
+    const edit = el("div", "integrations-inline");
+    const input = document.createElement("input");
+    input.type = "text"; input.autocomplete = "off"; input.value = destination(ordered.find((r) => r.status === "draft") ?? ordered.find((r) => r.status === "active"));
+    input.setAttribute("aria-label", `${definition?.displayName ?? install.adapterId} revised destination ID`);
+    input.dataset.reviseDestination = install.installId; input.disabled = !canManage || busy || !!view.degraded;
+    const revise = el("button", "btn", "Stage revision") as HTMLButtonElement;
+    revise.type = "button"; revise.dataset.managedAction = "revise"; revise.dataset.installId = install.installId; revise.disabled = !canManage || busy || !!view.degraded;
+    edit.append(input, revise); configuration.appendChild(edit); row.appendChild(configuration);
+    const actions = el("td", "action"); const bar = el("div", "integrations-actions");
+    const setButton = (label: string, action: string, applicable = true, primary = false) => { const button = el("button", `btn${primary ? " primary" : ""}`, label) as HTMLButtonElement; button.type = "button"; button.dataset.managedAction = action; button.dataset.installId = install.installId; button.disabled = !canManage || busy || !!view.degraded || !applicable; bar.appendChild(button); };
+    const hasDraft = ordered.some((revision) => revision.status === "draft");
+    const canResume = install.status === "disabled" && !hasDraft && install.activeRevisionId !== null;
+    setButton(hasDraft ? "Publish draft revision" : canResume ? "Resume active revision" : "Publish unavailable", "publish", hasDraft || canResume, true);
+    setButton("Suspend active revision", "suspend", install.status === "enabled");
+    const superseded = ordered.filter((r) => r.status === "superseded");
+    const rollback = document.createElement("select"); rollback.dataset.rollbackRevision = install.installId; rollback.setAttribute("aria-label", `${definition?.displayName ?? install.adapterId} rollback revision`); rollback.disabled = !canManage || busy || !!view.degraded || !superseded.length;
+    const placeholder = document.createElement("option"); placeholder.value = ""; placeholder.textContent = "Select prior revision"; rollback.appendChild(placeholder);
+    for (const revision of superseded) { const option = document.createElement("option"); option.value = revision.revisionId; option.textContent = `#${revision.sequence} · ${revision.adapterVersion}`; rollback.appendChild(option); }
+    bar.appendChild(rollback); setButton("Stage and publish selected rollback", "rollback", superseded.length > 0);
+    const confirm = document.createElement("input"); confirm.type = "text"; confirm.placeholder = `Type ${install.adapterId}`; confirm.setAttribute("aria-label", `Type ${install.adapterId} to confirm removal`); confirm.dataset.removeConfirmation = install.installId; confirm.disabled = !canManage || busy || !!view.degraded; bar.appendChild(confirm);
+    setButton("Remove managed install", "remove");
+    const busyStatus = el("span", "subtle", busy ? "Change in progress…" : ""); busyStatus.setAttribute("role", "status"); busyStatus.setAttribute("aria-live", "polite"); bar.appendChild(busyStatus);
+    actions.appendChild(bar); row.appendChild(actions); tbody.appendChild(row);
+  }
+}
+
+/** Existing tenant-local inventory is deliberately rendered without actions. */
+export function consentSummary(item: IntegrationReadModelItem) {
+  const required = item.effectiveAuthority?.consentPurposeIds ?? [];
+  const eligible = item.effective?.consentEligible ?? [];
+  const set = new Set(eligible);
+  return { required: [...required], eligible: [...eligible], unmet: required.filter((p) => !set.has(p as never)) };
+}
+
+export function buildInventoryRow(item: IntegrationReadModelItem): HTMLTableRowElement {
+  const row = document.createElement("tr"); row.dataset.localInstallRow = "";
+  const name = el("td"); name.append(el("strong", undefined, item.purpose), el("span", "subtle", `${item.appId} · tenant-local`)); row.appendChild(name);
+  row.append(el("td", undefined, item.status), el("td", undefined, describeAuthorityTier(item.authorityTier)));
+  row.appendChild(el("td", undefined, item.effective ? `${item.effective.version} (${item.effective.stage})` : "Nothing serving"));
+  const consent = consentSummary(item); row.appendChild(el("td", undefined, consent.required.length ? `Needs: ${consent.required.join(", ")}` : "No consent dependency"));
+  return row;
+}
+
+function renderLocal(tbody: HTMLElement, model: IntegrationAdminReadModel): void {
+  tbody.textContent = "";
+  if (!model.items.length) { const row = document.createElement("tr"); const cell = el("td", "subtle", "No other tenant-local integrations."); cell.setAttribute("colspan", "5"); row.appendChild(cell); tbody.appendChild(row); return; }
+  for (const item of model.items) tbody.appendChild(buildInventoryRow(item));
+}
+
+export function initIntegrationsTab(): void {
+  const panel = document.querySelector<HTMLElement>("[data-integrations-panel]");
+  if (!panel) return;
+  const base = panel.dataset.managedEndpoint;
+  if (!base) return;
+  const tenant = panel.dataset.targetTenant || undefined;
+  const canManage = panel.dataset.canManage === "true";
+  const client = new ManagedAnalyticsHttpClient(base, tenant);
+  const status = panel.querySelector<HTMLElement>("[data-integrations-status]");
+  const catalogNode = panel.querySelector<HTMLElement>("[data-managed-integrations-catalog]");
+  const managedBody = panel.querySelector<HTMLElement>("[data-managed-integrations-body]");
+  const localBody = panel.querySelector<HTMLElement>("[data-local-integrations-body]");
+  let catalog = new Map<string, AdapterDefinition>();
+  let views = new Map<string, ManagedInstallView>();
+  const ledger = new ManagedMutationLedger();
+  const busyInstalls = new Set<string>();
+  const busyAdapters = new Set<string>();
+  const announce = (message: string, tone: "" | "error" = "", focus = false) => { if (!status) return; status.textContent = message; status.dataset.tone = tone; if (focus) status.focus(); };
+  const renderManaged = () => { if (managedBody) renderManagedInventory(managedBody, [...views.values()], canManage, busyInstalls); };
+  const renderAdapters = () => { if (catalogNode) renderCatalog(catalogNode, [...catalog.values()], canManage, busyAdapters, new Set([...views.values()].map((view) => view.install.adapterId))); };
+  const setInstallBusy = (installId: string, busy: boolean) => {
+    if (busy) busyInstalls.add(installId); else busyInstalls.delete(installId);
+    const row = panel!.querySelector<HTMLElement>(`[data-managed-install-id="${CSS.escape(installId)}"]`);
+    if (row && busy) {
+      row.setAttribute("aria-busy", "true");
+      row.querySelectorAll<HTMLButtonElement | HTMLInputElement | HTMLSelectElement>("button,input,select").forEach((control) => { control.disabled = true; });
+      const live = row.querySelector<HTMLElement>('[role="status"]'); if (live) live.textContent = "Change in progress…";
+    } else if (!busy) renderManaged();
+  };
+  const setAdapterBusy = (adapterId: string, busy: boolean) => {
+    if (busy) busyAdapters.add(adapterId); else busyAdapters.delete(adapterId);
+    const card = panel!.querySelector<HTMLElement>(`[data-adapter-id="${CSS.escape(adapterId)}"]`);
+    card?.setAttribute("aria-busy", busy ? "true" : "false");
+    const installed = [...views.values()].some((view) => view.install.adapterId === adapterId);
+    card?.querySelectorAll<HTMLButtonElement | HTMLInputElement>("button,input").forEach((control) => { control.disabled = busy || installed || !canManage || catalog.get(adapterId)?.availability !== "available"; });
+  };
+  async function definitive<TRequest extends object, TResponse>(resource: string, operation: string, request: TRequest, invoke: (prepared: TRequest) => Promise<TResponse>): Promise<TResponse> {
+    const prepared = ledger.prepare(resource, operation, request);
+    const result = await invoke(prepared);
+    ledger.complete(resource, operation);
+    return result;
+  }
+
+  async function loadManaged(): Promise<void> {
+    announce("Loading managed analytics…");
+    try {
+      const [definitions, installs] = await Promise.all([
+        client.listAdapterDefinitions({ apiVersion: "v1", query: { limit: 100 } }),
+        client.listIntegrationInstalls({ apiVersion: "v1", query: { limit: 100 } }),
+      ]);
+      if (isError(definitions)) { announce(statusMessage(definitions), "error"); return; }
+      if (isError(installs)) { announce(statusMessage(installs), "error"); return; }
+      catalog = new Map(definitions.data.items.map((item) => [item.adapterId, item]));
+      const loaded = await Promise.all(installs.data.items.map(async (install) => {
+        const definition = catalog.get(install.adapterId);
+        if (!definition) return { install, definition: null, revisions: null, degraded: "catalog_definition_unavailable" as const };
+        try {
+          const revisions = await client.listIntegrationRevisions({ apiVersion: "v1", query: { installId: install.installId, limit: 100 } });
+          return isError(revisions)
+            ? { install, definition, revisions: null, degraded: "revision_history_unavailable" as const }
+            : { install, definition, revisions: revisions.data.items };
+        } catch {
+          return { install, definition, revisions: null, degraded: "revision_history_unavailable" as const };
+        }
+      }));
+      views = new Map(loaded.map((item) => [item.install.installId, item]));
+      reconcileManagedMutationLedger(ledger, views, !installs.data.nextCursor);
+      renderAdapters();
+      renderManaged();
+      const degraded = loaded.filter((item) => item.degraded).length;
+      announce(degraded
+        ? `${loaded.length} managed install(s); ${degraded} could not be fully loaded. Changes are disabled for degraded rows.`
+        : `${loaded.length} managed install(s) · ${catalog.size} reviewed adapters`, degraded ? "error" : "");
+    } catch { announce("The managed analytics service could not be reached.", "error"); }
+  }
+
+  async function loadLocal(): Promise<void> {
+    const endpoint = panel!.dataset.localReadmodelEndpoint;
+    if (!endpoint || !localBody) return;
+    try {
+      const query = new URLSearchParams(); if (tenant) query.set("tenant", tenant); query.set("stage", panel!.dataset.stage || "staged");
+      const response = await fetch(`${endpoint}?${query}`, { headers: { accept: "application/json" } });
+      const body = await json<{ readModel?: IntegrationAdminReadModel }>(response);
+      if (response.ok && body.readModel) renderLocal(localBody, body.readModel);
+    } catch { localBody.textContent = "Tenant-local inventory unavailable."; }
+  }
+
+  async function mutation(action: string, installId: string): Promise<void> {
+    const view = views.get(installId); if (!view) return;
+    if (!canManage) { announce("Owner or admin access is required.", "error", true); return; }
+    if (!view.definition || !view.revisions || view.degraded) { announce("This install could not be fully loaded; changes are disabled.", "error", true); return; }
+    if (busyInstalls.has(installId)) return;
+    const resource = `install:${installId}`;
+    const expectedRevision = view.install.revision;
+    let locked = false;
+    announce("Applying managed analytics change…");
+    try {
+      if (action === "revise") {
+        const input = panel!.querySelector<HTMLInputElement>(`[data-revise-destination="${CSS.escape(installId)}"]`);
+        const retrying = ledger.operation(resource) === "revise";
+        if (!retrying && !input?.value.trim()) { announce("Enter a destination ID before staging a revision.", "error", true); return; }
+        const request: ReviseIntegrationInstallRequest = { apiVersion: "v1", idempotencyKey: key("admin-revise"), expectedRevision, body: { installId, adapterVersion: view.definition.adapterVersion, configuration: { destinationId: input?.value.trim() ?? "" } } };
+        setInstallBusy(installId, true); locked = true;
+        const result = await definitive(resource, "revise", request, (prepared) => client.reviseIntegrationInstall(prepared));
+        if (isError(result)) { await loadManaged(); announce(statusMessage(result), "error", true); return; }
+      } else if (action === "publish" || action === "suspend") {
+        const request: SetIntegrationInstallStatusRequest = { apiVersion: "v1", idempotencyKey: key(`admin-${action}`), expectedRevision, body: { installId, status: action === "publish" ? "enabled" : "disabled" } };
+        setInstallBusy(installId, true); locked = true;
+        const result = await definitive(resource, action, request, (prepared) => client.setIntegrationInstallStatus(prepared));
+        if (isError(result)) { await loadManaged(); announce(statusMessage(result), "error", true); return; }
+      } else if (action === "remove") {
+        const confirm = panel!.querySelector<HTMLInputElement>(`[data-remove-confirmation="${CSS.escape(installId)}"]`);
+        const retrying = ledger.operation(resource) === "remove";
+        if (!retrying && confirm?.value !== view.install.adapterId) { announce(`Type ${view.install.adapterId} exactly to confirm removal.`, "error", true); return; }
+        const request: DeleteIntegrationInstallRequest = { apiVersion: "v1", idempotencyKey: key("admin-remove"), expectedRevision, body: { installId } };
+        setInstallBusy(installId, true); locked = true;
+        const result = await definitive(resource, "remove", request, (prepared) => client.deleteIntegrationInstall(prepared));
+        if (isError(result)) { await loadManaged(); announce(statusMessage(result), "error", true); return; }
+      } else if (action === "rollback") {
+        setInstallBusy(installId, true); locked = true;
+        let publishRevision: number;
+        if (ledger.operation(resource) === "rollback-publish") {
+          const published = await definitive(resource, "rollback-publish", {} as SetIntegrationInstallStatusRequest, (prepared) => client.setIntegrationInstallStatus(prepared));
+          if (isError(published)) { await loadManaged(); announce(`Rollback is staged but not published. ${statusMessage(published)}`, "error", true); return; }
+          await loadManaged(); announce("Managed analytics rollback published.", "", true); return;
+        }
+        const select = panel!.querySelector<HTMLSelectElement>(`[data-rollback-revision="${CSS.escape(installId)}"]`);
+        const target = view.revisions.find((revision) => revision.revisionId === select?.value && revision.status === "superseded");
+        const retrying = ledger.operation(resource) === "rollback-stage";
+        if (!retrying && !target) { announce("Select a superseded revision to roll back to.", "error", true); return; }
+        const stageRequest: ReviseIntegrationInstallRequest = { apiVersion: "v1", idempotencyKey: key("admin-rollback-stage"), expectedRevision, body: { installId, adapterVersion: target?.adapterVersion ?? view.definition.adapterVersion, configuration: { ...(target?.configuration ?? {}) } } };
+        const staged = await definitive(resource, "rollback-stage", stageRequest, (prepared) => client.reviseIntegrationInstall(prepared));
+        if (isError(staged)) { await loadManaged(); announce(statusMessage(staged), "error", true); return; }
+        publishRevision = staged.data.install.revision;
+        const publishRequest: SetIntegrationInstallStatusRequest = { apiVersion: "v1", idempotencyKey: key("admin-rollback-publish"), expectedRevision: publishRevision, body: { installId, status: "enabled" } };
+        const published = await definitive(resource, "rollback-publish", publishRequest, (prepared) => client.setIntegrationInstallStatus(prepared));
+        if (isError(published)) { await loadManaged(); announce(`Rollback is staged but not published. ${statusMessage(published)}`, "error", true); return; }
+      }
+      await loadManaged(); announce("Managed analytics change saved.", "", true);
+    } catch (cause) {
+      announce(cause instanceof PendingManagedMutationError
+        ? `Retry the pending ${cause.operation} action before starting another change.`
+        : "The response was not confirmed. Retry the same action; its idempotency key and request will be reused.", "error", true);
+    } finally { if (locked) setInstallBusy(installId, false); }
+  }
+
+  async function configure(adapterId: string): Promise<void> {
+    const definition = catalog.get(adapterId); const resultNode = panel!.querySelector<HTMLElement>(`[data-adapter-result="${CSS.escape(adapterId)}"]`); const input = panel!.querySelector<HTMLInputElement>(`[data-adapter-id-input="${CSS.escape(adapterId)}"]`);
+    if (!definition || !resultNode) return; resultNode.hidden = false;
+    if (!canManage) { resultNode.dataset.tone = "error"; resultNode.textContent = "Owner or admin access is required."; return; }
+    const resource = `adapter:${adapterId}`;
+    const retrying = ledger.operation(resource) === "create";
+    if (!retrying && [...views.values()].some((view) => view.install.adapterId === adapterId)) { resultNode.dataset.tone = "error"; resultNode.textContent = "This adapter is already configured."; return; }
+    if (!retrying && !input?.value.trim()) { resultNode.dataset.tone = "error"; resultNode.textContent = "Enter a destination ID."; return; }
+    if (busyAdapters.has(adapterId)) return;
+    resultNode.textContent = "Creating disabled install…"; resultNode.dataset.tone = "";
+    try {
+      const request: CreateIntegrationInstallRequest = { apiVersion: "v1", idempotencyKey: key("admin-create"), expectedRevision: 0, body: { adapterId: definition.adapterId, adapterVersion: definition.adapterVersion, configuration: { destinationId: input?.value.trim() ?? "" }, status: "disabled" } };
+      setAdapterBusy(adapterId, true);
+      const response = await definitive(resource, "create", request, (prepared) => client.createIntegrationInstall(prepared));
+      if (isError(response)) { resultNode.dataset.tone = "error"; resultNode.textContent = statusMessage(response); return; }
+      resultNode.textContent = "Disabled install created. Review its draft revision, then publish."; await loadManaged();
+    } catch (cause) {
+      resultNode.dataset.tone = "error";
+      resultNode.textContent = cause instanceof PendingManagedMutationError
+        ? `Retry the pending ${cause.operation} action first.`
+        : "The response was not confirmed. Retry Configure; the same idempotency key and request will be reused.";
+    } finally { setAdapterBusy(adapterId, false); }
+  }
+
+  panel.addEventListener("click", (event) => {
+    const target = event.target instanceof Element ? event.target : null; if (!target) return;
+    const action = target.closest<HTMLButtonElement>("[data-managed-action]"); if (action && !action.disabled && action.dataset.installId) { void mutation(action.dataset.managedAction!, action.dataset.installId); return; }
+    const configureButton = target.closest<HTMLButtonElement>("[data-configure-adapter]"); if (configureButton && !configureButton.disabled) void configure(configureButton.dataset.configureAdapter!);
+  });
+  panel.querySelector("[data-integrations-refresh]")?.addEventListener("click", () => { void loadManaged(); void loadLocal(); });
+  void loadManaged(); void loadLocal();
+}

package/apps/storefront/src/lib/apps/integrationsView.ts

@@ -0,0 +1,106 @@
+/**
+ * View-model contract for the `/admin#integrations` surface specified in
+ * docs/private-apps/admin-integrations-ia.md (`ext-admin-01`). Types only —
+ * no transport, no D1, no route wiring. `ext-admin-02-read-model-api` fills
+ * these shapes from real tenant-scoped data (desired config, materialized
+ * plan, installed app version, environment, consent, CSP diff, assurance,
+ * diagnostics, rollback availability); `ext-admin-07-tenant-lifecycle`
+ * implements the actions `IntegrationLifecycleAction` names. Both consume
+ * this file rather than inventing their own shape mid-implementation.
+ *
+ * `IntegrationInstallStatus` is a coarser admin-display status than
+ * `AppInstallStatus` (registryService.ts: active/suspended/uninstalled) —
+ * it folds in candidate/preview/error states the merchant-facing inventory
+ * needs to show that the install-record status alone doesn't carry. The
+ * read-model API derives one from the other; they are not the same enum.
+ */
+import type { IntegrationEnvironment } from "@tot/public-runtime";
+
+/**
+ * Four authority tiers (0014 I1 `integration-authority-four-tiers`,
+ * refined by 0016). This is the ACTUAL authority a surface grants, resolved
+ * server-side from surface × tenant-tier — never an app's declared intent.
+ */
+export type IntegrationAuthorityTier =
+  | "platform-adapter"
+  | "sandbox-broker"
+  | "server"
+  | "elevated-parent";
+
+/** Three-party field/asset ownership (0014 C2 `integration-ownership-three-party`). */
+export type IntegrationOwner = "storefront" | "tenant" | "vendor";
+
+/** Merchant-facing inventory/detail status. Distinct from `AppInstallStatus` — see file header. */
+export type IntegrationInstallStatus =
+  | "configuring"
+  | "preview-ready"
+  | "live"
+  | "suspended"
+  | "error";
+
+/** IA §5–9 lifecycle actions. `ext-admin-07` authorizes and executes each. */
+export type IntegrationLifecycleAction =
+  | "preview"
+  | "publish"
+  | "rollback"
+  | "suspend"
+  | "resume"
+  | "uninstall";
+
+/** One row of the IA §4 inventory table. */
+export interface IntegrationInventoryItem {
+  installId: string;
+  appId: string;
+  /** Plain-language purpose, e.g. "Sends page and purchase events to Google Ads/Analytics" — never an internal adapter name. */
+  purpose: string;
+  status: IntegrationInstallStatus;
+  environment: IntegrationEnvironment;
+  authorityTier: IntegrationAuthorityTier;
+  lastActivity: { actor: string; at: string } | null;
+}
+
+/** IA §5 panel-3 effective (not desired) permissions/CSP/data view. */
+export interface IntegrationEffectiveAuthority {
+  authorityTier: IntegrationAuthorityTier;
+  /** Exact origins the CSP compiler emits for this install — never a wildcard or raw header (0014 E2). */
+  cspOrigins: string[];
+  /** True only if this install holds an elevated PII scope beyond the anonymous/minimal default (0014 M2). */
+  hasElevatedPiiScope: boolean;
+  /** Consent purpose ids this install's delivery depends on; empty means no dependency configured yet. */
+  consentPurposeIds: string[];
+}
+
+/** IA §5 panel-5 developer-mode diagnostics. */
+export interface IntegrationDiagnosticIssue {
+  severity: "blocking" | "warning";
+  /** Plain-language summary a merchant's locked/summary view can show as-is. */
+  summary: string;
+  /** Full text a developer's "Copy details" action serializes verbatim. */
+  copyableDetail: string;
+}
+
+export interface IntegrationDetailView extends IntegrationInventoryItem {
+  /** Owner of each editable field, by field name — drives the IA §10 ownership display. */
+  fieldOwners: Record<string, IntegrationOwner>;
+  effectiveAuthority: IntegrationEffectiveAuthority;
+  diagnostics: IntegrationDiagnosticIssue[];
+  /** Present only once a version has gone live at least once (IA §7 rollback availability). */
+  rollbackAvailable: boolean;
+}
+
+/**
+ * Plain-language label for an authority tier, for the inventory/detail chip.
+ * Pure — no lookups, so both server render and any client re-render agree.
+ */
+export function describeAuthorityTier(tier: IntegrationAuthorityTier): string {
+  switch (tier) {
+    case "platform-adapter":
+      return "Built-in adapter";
+    case "sandbox-broker":
+      return "Sandboxed (boxed)";
+    case "server":
+      return "Server-side";
+    case "elevated-parent":
+      return "Elevated parent access";
+  }
+}