@aglyn/plugins-ai 1.0.0-beta.246 → 1.0.0-beta.249

package/src/lib/jobs/ai-job-tracking-step.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { dropPluginSiteCache } from '@aglyn/aglyn/plugin-manager/plugin-site-cache';
+import type { PluginAiCapabilityArgsSchema } from '@aglyn/aglyn/plugin-manager/plugin-ai-capabilities';
+import { getLockdownVerdict } from '@aglyn/tenant-data-admin/server/lockdown';
+import { resolveOrgIdForHost } from '@aglyn/tenant-data-admin/server/organizations';
+import { type Firestore } from 'firebase-admin/firestore';
+import { type AiJobAdmission } from './ai-job-admission';
+import type { AiJobStepRunner } from './ai-job-text-step';
+/**
+ * The `tracking` step (AGL-3751): the site's analytics and advertising tags,
+ * as the console's Setup → Tracking card sets them — Google Analytics, Google
+ * Tag Manager, and the Meta, Google Ads, LinkedIn, TikTok and Pinterest tags —
+ * as a first-class build operation, so "connect Google Analytics G-4R7KX2PQ9Z"
+ * is one item on Assist's plan card.
+ *
+ * NO MODEL. The planner already wrote the ids as the item's arguments; this
+ * holds each to the pattern the card's field (and the tenant's loader) holds
+ * it to and writes it, so it costs no credits.
+ *
+ * ── Only the card's own fields, and only public ids ──────────────────────
+ *
+ * Every field written is one the Tracking card writes, under the same name:
+ * `analytics.gaMeasurementId`, `analytics.gtmContainerId` and
+ * `analytics.adTags.{meta,google-ads,linkedin,tiktok,pinterest}`, each tested
+ * by the same expression (`GA_MEASUREMENT_ID_PATTERN` and its siblings in
+ * `visitor-consent.ts`). Each is an id that is printed in every page's HTML
+ * anyway, never a credential. Removing one deletes the field, as the card's
+ * cleared box does (`CLEARABLE_TRACKING_PATHS`).
+ *
+ * NEVER: the consent banner (`consent.*` — turning it off, its mode, or the
+ * advertising question), search indexing, verification tokens, and anything
+ * that needs a secret the person pastes — the Ad conversions card's access
+ * tokens, Zapier, order webhooks' signing secrets. Those are not arguments.
+ * The tags load only where the consent banner lets them, exactly as a tag the
+ * card saved does: the tenant gates on the stored ids, not on who wrote them.
+ *
+ * ── Live on confirm, who may, idempotent ─────────────────────────────────
+ *
+ * As the `settings` step (AGL-3748): a tag has no draft, so the plan card's
+ * confirm is the agreement and the write is live. One transaction re-reads
+ * the host, re-checks the role, writes only what differs with a site-wide
+ * publish outbox entry, and the site's cached pages are dropped after. The
+ * gate is the Firestore rules' for the host document (`canWriteHostContent`,
+ * `hostWritesFrozen`): an admin, editor or author, while no lockdown freezes
+ * the site, its org or the platform.
+ */
+export declare const AI_TRACKING_KIND: "tracking";
+/** ASSUMED: the least time the step needs — the site, the org and one transaction. */
+export declare const AI_JOB_TRACKING_STEP_MINIMUM_MS = 5000;
+export declare const AI_TRACKING_NO_SITE_COPY = "Open the site whose tracking should change.";
+export declare const AI_TRACKING_ROLE_COPY = "Changing the site\u2019s tracking needs the admin, editor or author role on this site.";
+export declare const AI_TRACKING_LOCKED_COPY = "This site is not accepting changes right now.";
+export declare const AI_TRACKING_NOTHING_COPY = "The request named no tracking id this could set or remove.";
+/** Where a person finds what the op changed: the card that edits it. */
+export declare const AI_TRACKING_WHERE = "Setup \u2192 Tracking";
+/** The output's fixed id: one site's tracking, whatever changed. */
+export declare const AI_TRACKING_OUTPUT_ID = "tracking";
+/** One tag the card sets: its argument, its stored field, its name, and its pattern. */
+export interface AiTrackingTag {
+    arg: string;
+    path: string;
+    label: string;
+    pattern: RegExp;
+    /** What the card's field says the id looks like. */
+    shape: string;
+    /** Asked when a request names this tag and no usable id, from the card's helper text. */
+    ask: string;
+    /** Words that name this tag in an item's name. */
+    named: RegExp;
+}
+/** The Tracking card's fields, in its order (`trackingSchema`, host-settings-scope.tsx). */
+export declare const AI_TRACKING_TAGS: readonly AiTrackingTag[];
+/** Asked when an item names no tag at all. */
+export declare const AI_TRACKING_WHICH_COPY = "Which tag should be connected, and what is its ID? Google Analytics, Google Tag Manager, the Meta pixel, Google Ads, LinkedIn, TikTok or Pinterest.";
+/** The item's arguments, as the planner fills them in. Every one optional. */
+export declare const AI_TRACKING_ARGS_SCHEMA: PluginAiCapabilityArgsSchema;
+/** What an item asks: ids to set by field, and fields to clear. */
+export interface AiTrackingRequest {
+    set: Record<string, string>;
+    remove: string[];
+}
+export interface AiTrackingRead {
+    request: AiTrackingRequest;
+    /** A sentence per value that could not be used, so the rest still are. */
+    problems: string[];
+}
+/** The item's arguments read: what may be written, and a sentence for each that may not. */
+export declare function aiTrackingRequestOf(inputs: Readonly<Record<string, unknown>> | null | undefined): AiTrackingRead;
+/**
+ * The question a planned tracking change asks the person, or `null` when it
+ * sets or removes something (AGL-3751). An item with no usable id — the
+ * planner kept "add my Meta pixel" with no id, or an id of the wrong shape —
+ * is never built: it asks for the id of the tag its arguments or its name
+ * name, in the card's own words, and says why an id given was not one.
+ */
+export declare function aiTrackingMissingInput(item: {
+    name?: string;
+    why?: string;
+    args: Readonly<Record<string, unknown>>;
+}): string | null;
+/** Whether a read request asks for anything at all. */
+export declare function aiTrackingRequestEmpty(request: AiTrackingRequest): boolean;
+/** One change to the host document, with the sentence that says it was made. */
+export interface AiTrackingChange {
+    path: string;
+    /** The id to store, or `null` to delete the field. */
+    value: string | null;
+    said: string;
+}
+/** Every change the request asks, in the card's order, before comparing with what is stored. */
+export declare function aiTrackingChanges(request: AiTrackingRequest): AiTrackingChange[];
+/**
+ * What the person should know about the tags the site now carries, in the
+ * card's own words: where the consent banner is off, nothing of ours gates
+ * them; and a container beside a direct Google tag counts everything twice.
+ */
+export declare function aiTrackingWarnings(host: Record<string, unknown>): string[];
+export type AiTrackingWrite = {
+    ok: true;
+    done: string[];
+    changed: string[];
+    warnings: string[];
+    outboxId: string | null;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The tags written, in one transaction that reads the host as it is stored
+ * NOW: the member still holds a write role, and only the values that differ
+ * from what is stored are written, with a site-wide publish outbox entry
+ * beside them so the live site's cached pages are dropped.
+ */
+export declare function writeAiSiteTracking(firestore: Firestore, input: {
+    hostId: string;
+    uid: string;
+    request: AiTrackingRequest;
+    now: Date;
+}): Promise<AiTrackingWrite>;
+/** Why this member may not change this site's tracking now, or `null`. */
+export declare function aiTrackingAccessRefusal(input: {
+    host: FirebaseFirestore.DocumentSnapshot;
+    uid: string;
+    org: object | null;
+}, deps?: {
+    lockdown?: typeof getLockdownVerdict;
+}): Promise<string | null>;
+/** The output's note: what changed, that it is live, how consent gates it, and what was not done. */
+export declare function aiTrackingOutputNote(done: readonly string[], warnings: readonly string[], notDone: readonly string[], changedAny: boolean): string;
+export interface AiJobTrackingStepDeps {
+    write?: typeof writeAiSiteTracking;
+    lockdown?: typeof getLockdownVerdict;
+    dropCache?: typeof dropPluginSiteCache;
+}
+export declare function createAiJobTrackingStep(deps?: AiJobTrackingStepDeps): AiJobStepRunner;
+export declare const runAiJobTrackingStep: AiJobStepRunner;
+export interface AiTrackingJobAdmissionDeps {
+    ownerOf?: typeof resolveOrgIdForHost;
+    lockdown?: typeof getLockdownVerdict;
+}
+/**
+ * A tracking change is admitted on a site of the job's own org, for a member
+ * who may write its settings now, where the request names at least one tag
+ * this can set or remove. Refused in those words before anything is written.
+ */
+export declare function createAiTrackingJobAdmission(deps?: AiTrackingJobAdmissionDeps): AiJobAdmission;
+export declare const aiTrackingJobAdmission: AiJobAdmission;
+/** Registers the tracking step and its door (AGL-3751). */
+export declare function registerAiTrackingJob(): void;