@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/activity/ai-activity-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/activity/ai-activity-actions.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The AI actions an activity log can carry (AGL-2929).\n *\n * Every other action in `orgs/{orgId}/activity` and `hosts/{hostId}/activity`\n * is a prose sentence written at the call site — \"Saved the screen\". The AI\n * rows are CODES instead, because they are read by more than a person: the\n * org feed's \"AI\" chip, the staff audit facet and the actor table all need\n * to recognize an AI row without parsing a sentence, and a sentence that\n * three writers phrase three ways is three rows that look unrelated.\n *\n * One list, so the writers in `ai-activity.ts`, the feed presenter and the\n * staff facet cannot disagree about what counts as AI. A code missing from\n * `AI_ACTIVITY_ACTION_LABELS` fails the type, not the reader.\n */\n\nimport type { AiJobOutputResource } from '../model/ai-jobs.types'\nimport {\n  pluginStaffAuditActionGroup,\n  pluginStaffAuditActionGroupLabel,\n  registerPluginActivityActions,\n  type PluginActivityScope,\n} from '@aglyn/aglyn/plugin-manager/plugin-activity-actions'\n\n/** The action code each AI writer stores. */\nexport const AI_ACTIVITY_ACTIONS = {\n  jobCreated: 'ai.job.created',\n  jobOutput: 'ai.job.output',\n  jobCanceled: 'ai.job.canceled',\n  jobNeedsInput: 'ai.job.needs_input',\n  editApplied: 'ai.edit.applied',\n  seoApplied: 'ai.seo.applied',\n  assistSection: 'ai.assist.section',\n  overageHardCap: 'ai.overage.hardCap',\n  overageCap: 'ai.overage.cap',\n  allotmentChanged: 'ai.allotment.changed',\n  permissionChanged: 'ai.permission.changed',\n  addonPurchased: 'ai.addon.purchased',\n  addonRemoved: 'ai.addon.removed',\n} as const\n\nexport type AiActivityAction =\n  (typeof AI_ACTIVITY_ACTIONS)[keyof typeof AI_ACTIVITY_ACTIONS]\n\n/** What a person reads for each code, in the feed and the actor table. */\nexport const AI_ACTIVITY_ACTION_LABELS: Record<AiActivityAction, string> = {\n  'ai.job.created': 'Started an AI generation',\n  'ai.job.output': 'AI generated',\n  'ai.job.canceled': 'Canceled an AI generation',\n  'ai.job.needs_input': 'AI generation paused for input',\n  'ai.edit.applied': 'Applied AI edits',\n  'ai.seo.applied': 'Applied AI SEO fixes as drafts',\n  'ai.assist.section': 'AI generated a section',\n  'ai.overage.hardCap': 'AI stop-at-band switch',\n  'ai.overage.cap': 'AI overage ceiling',\n  'ai.allotment.changed': 'AI allotment changed',\n  'ai.permission.changed': 'AI permission changed',\n  'ai.addon.purchased': 'Added the AI add-on',\n  'ai.addon.removed': 'Removed the AI add-on',\n}\n\n/** Every code, in catalog order — what a filter sends as `isAnyOf`. */\nexport const AI_ACTIVITY_ACTION_LIST: readonly AiActivityAction[] =\n  Object.values(AI_ACTIVITY_ACTIONS)\n\n/** The feed's filter chip and the staff facet's group, by one name. */\nexport const AI_ACTIVITY_FILTER_LABEL = 'AI'\n\n/**\n * Why a generation stopped and asked for a person (AGL-2904): the plan's\n * band ran out, the org's own ceiling refused, the monthly message cap or\n * the job's own token budget did — or, on the Free taste (AGL-2925), one of\n * its own precautions: the account's credits, its daily request cap, a\n * pause after declined briefs, or the platform's day of free spend. Those\n * are the meter's `AssistRefusedBy` less its `null`, so a ceiling the meter\n * can name is one the feed can label. The last three are the job's own: its\n * plan is ready for review, or an answer broke a building rule on its re-ask\n * (AGL-2935), or the site is at an allowance its plan sets for what the job\n * writes (AGL-2909).\n */\nexport type AiJobNeedsInputReason =\n  | 'band'\n  | 'cap'\n  | 'messages'\n  | 'budget'\n  | 'allotment'\n  | 'account'\n  | 'requests'\n  | 'refusals'\n  | 'platform'\n  | 'plan'\n  | 'doctrine'\n  | 'limit'\n\nexport const AI_JOB_NEEDS_INPUT_REASON_LABELS: Record<\n  AiJobNeedsInputReason,\n  string\n> = {\n  plan: 'its plan is ready for review',\n  doctrine: 'its answer broke a building rule twice',\n  limit: 'the site reached an allowance of its plan',\n  band: 'the included AI band is used up',\n  cap: 'the overage ceiling was reached',\n  messages: 'the monthly message cap was reached',\n  budget: 'the job budget was reached',\n  allotment: 'the creator’s or the site’s AI allotment is used up',\n  account: 'the account’s free AI credits are used up',\n  requests: 'the daily free request cap was reached',\n  refusals: 'free generation is paused for the day after declined briefs',\n  platform: 'free AI generation is paused for the day',\n}\n\n/**\n * The feed target types a generation job's output can be filed under: the\n * kinds both activity logs know, so the org row and its host copy share a\n * shape.\n */\nexport type AiOutputTargetType =\n  | 'screen'\n  | 'layout'\n  | 'component'\n  | 'template'\n  | 'workflow'\n  | 'content'\n  | 'theme'\n\n/**\n * Where the feed files each resource kind a job can write (AGL-2904).\n *\n * A job names its output by the resource it wrote, and the activity logs\n * know a narrower set of targets. The map is total, so a resource kind\n * added to the job document must say where the feed shows it before the\n * machine can log it. `reusableComponent` is the feed's `component`; a\n * `text` output is copy, which the feed files as `content`; a `theme`\n * proposal is filed under the site's theme, which the host feed links to the\n * Theme section (AGL-2938); the kinds whose runners have not shipped are\n * content of the site too, and are filed there until a target of their own\n * exists.\n */\nconst AI_OUTPUT_TARGET_TYPES: Record<AiJobOutputResource, AiOutputTargetType> = {\n  screen: 'screen',\n  reusableComponent: 'component',\n  layout: 'layout',\n  template: 'template',\n  form: 'content',\n  emailScreen: 'content',\n  campaign: 'content',\n  product: 'content',\n  experiment: 'content',\n  workflow: 'workflow',\n  // An SEO proposal (AGL-2910) is about the site's content, and is filed there.\n  seo: 'content',\n  text: 'content',\n  theme: 'theme',\n  // An insight answer (AGL-2915) is about the site's figures; the feed row\n  // names it and never what it says.\n  insight: 'content',\n  // A CRM proposal (AGL-2917) writes nothing; the feed files it with content.\n  crm: 'content',\n}\n\nexport function aiOutputTargetType(resource: AiJobOutputResource): AiOutputTargetType {\n  return AI_OUTPUT_TARGET_TYPES[resource]\n}\n\n/** Whether a stored action is one of the AI codes above. */\nexport function isAiActivityAction(action: unknown): action is AiActivityAction {\n  return (\n    typeof action === 'string' &&\n    (AI_ACTIVITY_ACTION_LIST as readonly string[]).includes(action)\n  )\n}\n\n/** The readable label for an AI code; `undefined` for any other action. */\nexport function aiActivityActionLabel(action: unknown): string | undefined {\n  return isAiActivityAction(action)\n    ? AI_ACTIVITY_ACTION_LABELS[action]\n    : undefined\n}\n\n/**\n * Staff audit rows that are ABOUT AI without carrying an `ai.` code: the\n * customer's overage controls already write `billing.assistOverage.*`, and\n * the platform's free-spend auto-pause writes `platform.aiFreeSpend.*`\n * (AGL-2925). The audit page's facet folds them under the same group as the\n * codes, because \"what did we do about AI this week\" is one question.\n */\nexport const AI_STAFF_AUDIT_ACTION_PREFIXES: readonly string[] = [\n  'ai.',\n  'billing.assistOverage.',\n  'platform.aiFreeSpend.',\n]\n\n/** The facet group an `adminAudit` action belongs to. */\nexport const STAFF_AUDIT_AI_GROUP = 'ai'\n\n/**\n * Which log each code is written to. The job and edit codes land in both\n * the org feed and the host's copy; the billing and permission codes are\n * org-level facts and land in the org feed alone.\n */\nconst AI_ACTIVITY_ACTION_SCOPES: Record<\n  AiActivityAction,\n  PluginActivityScope | readonly PluginActivityScope[]\n> = {\n  'ai.job.created': ['org', 'host'],\n  'ai.job.output': ['org', 'host'],\n  'ai.job.canceled': ['org', 'host'],\n  'ai.job.needs_input': ['org', 'host'],\n  'ai.edit.applied': ['org', 'host'],\n  'ai.seo.applied': ['org', 'host'],\n  'ai.assist.section': ['org', 'host'],\n  'ai.overage.hardCap': 'org',\n  'ai.overage.cap': 'org',\n  'ai.allotment.changed': 'org',\n  'ai.permission.changed': 'org',\n  'ai.addon.purchased': 'org',\n  'ai.addon.removed': 'org',\n}\n\n/**\n * The catalog, declared through the generic activity-action seam\n * (AGL-2940) so the feed's chip, the actor table's filter and the staff\n * facet read it from the registry beside every other plugin's codes.\n * `registerAiDeclarations` calls it, in both apps and in the browser.\n */\nexport function registerAiActivityActions(): void {\n  registerPluginActivityActions({\n    pluginId: 'ai',\n    group: {\n      id: STAFF_AUDIT_AI_GROUP,\n      label: AI_ACTIVITY_FILTER_LABEL,\n      staffAuditPrefixes: AI_STAFF_AUDIT_ACTION_PREFIXES.filter(\n        (prefix) => prefix !== 'ai.',\n      ),\n      // The staff cards opening on an org (AGL-2930) and on one account\n      // (AGL-2928): reads of spend and attribution, and nothing altered.\n      staffAuditAccessActions: ['org.ai-viewed', 'user.ai-usage-viewed'],\n    },\n    actions: AI_ACTIVITY_ACTION_LIST.map((key) => ({\n      key,\n      label: AI_ACTIVITY_ACTION_LABELS[key],\n      scope: AI_ACTIVITY_ACTION_SCOPES[key],\n    })),\n  })\n}\n\n/**\n * The group the staff audit facet files an action under: `ai` for every\n * AI row, otherwise the action's leading namespace (`billing`, `org`,\n * `plugins`). Roughly seventy distinct actions write to `adminAudit`, so\n * the facet offers namespaces rather than a seventy-entry menu. Answered\n * by the registry, so every plugin's group is filed the same way.\n */\nexport function staffAuditActionGroup(action: unknown): string {\n  return pluginStaffAuditActionGroup(action)\n}\n\n/** How a facet group reads in the menu: `ai` → `AI`, `billing` → `billing`. */\nexport function staffAuditActionGroupLabel(group: string): string {\n  return pluginStaffAuditActionGroupLabel(group)\n}\n"],"names":["pluginStaffAuditActionGroup","pluginStaffAuditActionGroupLabel","registerPluginActivityActions","AI_ACTIVITY_ACTIONS","jobCreated","jobOutput","jobCanceled","jobNeedsInput","editApplied","seoApplied","assistSection","overageHardCap","overageCap","allotmentChanged","permissionChanged","addonPurchased","addonRemoved","AI_ACTIVITY_ACTION_LABELS","AI_ACTIVITY_ACTION_LIST","Object","values","AI_ACTIVITY_FILTER_LABEL","AI_JOB_NEEDS_INPUT_REASON_LABELS","plan","doctrine","limit","band","cap","messages","budget","allotment","account","requests","refusals","platform","AI_OUTPUT_TARGET_TYPES","screen","reusableComponent","layout","template","form","emailScreen","campaign","product","experiment","workflow","seo","text","theme","insight","crm","aiOutputTargetType","resource","isAiActivityAction","action","includes","aiActivityActionLabel","undefined","AI_STAFF_AUDIT_ACTION_PREFIXES","STAFF_AUDIT_AI_GROUP","AI_ACTIVITY_ACTION_SCOPES","registerAiActivityActions","pluginId","group","id","label","staffAuditPrefixes","filter","prefix","staffAuditAccessActions","actions","map","key","scope","staffAuditActionGroup","staffAuditActionGroupLabel"],"mappings":"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"}

package/src/lib/activity/ai-activity.d.ts

@@ -0,0 +1,219 @@
+/**
+ * @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.
+ */
+/**
+ * The AI writers over the two customer-visible activity logs (AGL-2929).
+ *
+ * Every generation, applied edit and control change lands in
+ * `orgs/{orgId}/activity` (and, for a host-scoped output, in
+ * `hosts/{hostId}/activity`) through {@link logOrgActivity} and
+ * {@link logHostActivity} — never a collection of its own, so the retention
+ * `docs/DATA_RETENTION.md` already promises for the activity logs covers
+ * these rows without a new entry, and the one permission-gated route that
+ * serves the org feed serves them.
+ *
+ * Each helper owns ONE action code from `AI_ACTIVITY_ACTIONS` and the shape
+ * of its target, so a caller cannot store a code the viewers do not know or
+ * a target the presenter cannot label. What varies per row is folded into
+ * `target.name`, which is the only free text the row carries: the feed reads
+ * `<label> — <name>`, and a name like `screen · 240-character brief · Acme`
+ * is what makes two jobs distinguishable in a list of them.
+ *
+ * Attribution follows `logOrgActivity`'s rule: `uid` is nullable because
+ * some of these acts HAVE no actor — a job paused by the band with nobody
+ * present, an add-on Stripe removed at the period end — and naming the last
+ * person who touched the thing would file an act under someone who did not
+ * perform it. A caller passes what it verified and nothing more.
+ *
+ * The control-change writers answer whether a row was written: a control set
+ * to the value it already had is not a change, and a feed that said "AI
+ * overage ceiling — $25" twice for one decision would read as two decisions.
+ */
+import type { HostActivityActor } from '@aglyn/aglyn/app-utils/activity-presenter';
+import { type AiJobNeedsInputReason } from './ai-activity-actions';
+import type { OrgSeatAddons } from '@aglyn/aglyn/server';
+import { type HostActivityTarget, type OrgActivityTarget } from '@aglyn/tenant-data-admin/server/organizations';
+/** Who performed the act — `uid: null` when nobody was present. */
+export interface AiActivityActor {
+    uid: string | null;
+    email?: string | null;
+}
+/** The resource kinds a generation job can produce. */
+export type AiOutputResourceType = Extract<OrgActivityTarget['type'], HostActivityTarget['type']>;
+/**
+ * `ai.job.created` — a generation job was briefed (AGL-2904).
+ *
+ * Names the job's kind, how long the brief was and the site it targets, so
+ * the row says what was asked for without storing the brief itself.
+ */
+export declare function logAiJobCreated(orgId: string, actor: AiActivityActor, job: {
+    jobId: string;
+    /** What the job builds — a screen, a site, a section. */
+    kind: string;
+    briefLength: number;
+    hostId?: string | null;
+    hostName?: string | null;
+}): Promise<void>;
+/**
+ * `ai.job.output` — one resource a job produced, one row per output.
+ *
+ * The org row names the resource, and a host-scoped output is copied into
+ * the site's own feed so a site's activity shows what was generated on it.
+ * The copy needs a uid: the host log's contract has no anonymous actor, so a
+ * job that finished with nobody present still lands in the org feed and
+ * only there.
+ */
+export declare function logAiJobOutput(orgId: string, actor: AiActivityActor, output: {
+    jobId: string;
+    hostId?: string | null;
+    resource: {
+        type: AiOutputResourceType;
+        id: string;
+        name?: string | null;
+        versionId?: string | null;
+    };
+}): Promise<void>;
+/** `ai.job.canceled` — a job was stopped before it finished. */
+export declare function logAiJobCanceled(orgId: string, actor: AiActivityActor, job: {
+    jobId: string;
+    kind?: string | null;
+    name?: string | null;
+}): Promise<void>;
+/**
+ * `ai.job.needs_input` — a job stopped and asked for a person, and why.
+ * Usually actorless: the band, the ceiling or the budget stopped it, not a
+ * member.
+ */
+export declare function logAiJobNeedsInput(orgId: string, actor: AiActivityActor, job: {
+    jobId: string;
+    kind?: string | null;
+    reason: AiJobNeedsInputReason;
+}): Promise<void>;
+/**
+ * `ai.edit.applied` — a proposal's edits landed on a besigner document
+ * (AGL-2906).
+ *
+ * The edits are applied in the author's own editor, as unsaved changes, so
+ * no server sees them land. The row is written by the door the editor
+ * reports the apply to, and only once that door has found the proposal on an
+ * exchange the same member had about the same document — so it stands on a
+ * proposal the server issued rather than on the client's word alone. Op
+ * counts are folded into the name (`Home · 3 set, 1 insert`); the edits
+ * themselves are the site's content and are not logged.
+ */
+export declare function logAiEditApplied(hostId: string, actor: HostActivityActor, edit: {
+    /** The kind of document the edits landed on. */
+    type: 'screen' | 'component' | 'layout';
+    id: string;
+    name?: string | null;
+    versionId: string;
+    /** Edits applied, by operation — `{ set: 3, insert: 1 }`. */
+    opCounts: Record<string, number>;
+}): Promise<void>;
+/**
+ * `ai.seo.applied` — a site audit's fixes were applied as drafts (AGL-2910).
+ *
+ * Written by the door that applied them. The name carries the counts — new
+ * unpublished versions, listings staged for a person to save — and never
+ * the text proposed, which is the site's content. Org feed, and the site's
+ * own feed when a person is named.
+ */
+export declare function logAiSeoApplied(orgId: string, actor: AiActivityActor, apply: {
+    jobId: string;
+    hostId: string;
+    hostName?: string | null;
+    versions: number;
+    staged: number;
+}): Promise<void>;
+/**
+ * `ai.assist.section` — the assist door returned a section subtree.
+ *
+ * Into the site's feed when the request named a site, else the org's, so
+ * the act is never unlogged for want of a host. Element rewrites are not
+ * logged here at all — too chatty — and the per-user rollup carries their
+ * count. The instruction is the customer's own copy and is not stored.
+ */
+export declare function logAiAssistSection(actor: AiActivityActor, section: {
+    orgId: string;
+    hostId?: string | null;
+    hostName?: string | null;
+    nodeCount: number;
+}): Promise<void>;
+/** The two overage controls a customer holds (AGL-2653, AGL-2898). */
+export type AiOverageControlChange = {
+    control: 'hardCap';
+    before: boolean;
+    after: boolean;
+} | {
+    control: 'cap';
+    before: number | null;
+    after: number | null;
+};
+/**
+ * `ai.overage.hardCap` / `ai.overage.cap` — a control moved.
+ *
+ * The routes already write `adminAudit`; this is the org-feed row that
+ * lets the customer see who set the control. Answers `false`, and writes
+ * nothing, when the value did not move.
+ */
+export declare function logAiOverageControl(orgId: string, actor: AiActivityActor, change: AiOverageControlChange): Promise<boolean>;
+/**
+ * `ai.allotment.changed` — a manager set, changed or removed an AI allotment
+ * (AGL-2942): a member's, a collaborator's on one site, a site's, or the
+ * org-wide model restriction. The subject is the row's target; what it was
+ * set to is the name, in credits, never dollars.
+ */
+export declare function logAiAllotmentChanged(orgId: string, actor: AiActivityActor, change: {
+    subject: {
+        type: 'org' | 'member' | 'host';
+        id?: string | null;
+        name?: string | null;
+    };
+    /** `null` when the allotment was removed. */
+    after: {
+        credits: number | null;
+        mode: 'hard' | 'soft';
+        models: readonly string[] | null;
+    } | null;
+}): Promise<void>;
+/**
+ * `ai.permission.changed` — an AI permission moved on a role, a member's
+ * override, a collaborator's site toggle or the org's default. The subject
+ * is the row's target; the permission and its direction are the name.
+ */
+export declare function logAiPermissionChanged(orgId: string, actor: AiActivityActor, change: {
+    subject: {
+        type: 'org' | 'role' | 'member' | 'host';
+        id?: string | null;
+        name?: string | null;
+    };
+    /** The permission key that moved — `ai.assist`, `ai.generate`. */
+    permission: string;
+    granted: boolean;
+}): Promise<void>;
+/**
+ * `ai.addon.purchased` / `ai.addon.removed` — the AI add-on came or went.
+ *
+ * Decided off the mirrored `seatAddons` maps rather than told, because the
+ * add-ons route mirrors the purchase at once and the webhook re-derives the
+ * same map on every subscription event: comparing before and after is what
+ * keeps a redelivery, or the webhook confirming a purchase the route already
+ * logged, from writing the row twice. Answers `false` when nothing moved.
+ */
+export declare function logAiAddonChanged(orgId: string, actor: AiActivityActor, change: {
+    before: OrgSeatAddons | null | undefined;
+    after: OrgSeatAddons | null | undefined;
+}): Promise<boolean>;

package/src/lib/activity/ai-activity.js

@@ -0,0 +1,251 @@
+/**
+ * @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.
+ */ /**
+ * The AI writers over the two customer-visible activity logs (AGL-2929).
+ *
+ * Every generation, applied edit and control change lands in
+ * `orgs/{orgId}/activity` (and, for a host-scoped output, in
+ * `hosts/{hostId}/activity`) through {@link logOrgActivity} and
+ * {@link logHostActivity} — never a collection of its own, so the retention
+ * `docs/DATA_RETENTION.md` already promises for the activity logs covers
+ * these rows without a new entry, and the one permission-gated route that
+ * serves the org feed serves them.
+ *
+ * Each helper owns ONE action code from `AI_ACTIVITY_ACTIONS` and the shape
+ * of its target, so a caller cannot store a code the viewers do not know or
+ * a target the presenter cannot label. What varies per row is folded into
+ * `target.name`, which is the only free text the row carries: the feed reads
+ * `<label> — <name>`, and a name like `screen · 240-character brief · Acme`
+ * is what makes two jobs distinguishable in a list of them.
+ *
+ * Attribution follows `logOrgActivity`'s rule: `uid` is nullable because
+ * some of these acts HAVE no actor — a job paused by the band with nobody
+ * present, an add-on Stripe removed at the period end — and naming the last
+ * person who touched the thing would file an act under someone who did not
+ * perform it. A caller passes what it verified and nothing more.
+ *
+ * The control-change writers answer whether a row was written: a control set
+ * to the value it already had is not a change, and a feed that said "AI
+ * overage ceiling — $25" twice for one decision would read as two decisions.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { AI_ACTIVITY_ACTIONS, AI_JOB_NEEDS_INPUT_REASON_LABELS } from "./ai-activity-actions.js";
+import { aiAddonName, aiAddonUnits } from "@aglyn/aglyn/app-utils/plan-entitlements";
+import { logHostActivity, logOrgActivity } from "@aglyn/tenant-data-admin/server/organizations";
+/** The pieces a target name is built from, blanks dropped. */ const named = (...parts)=>parts.map((part)=>part === null || part === undefined ? '' : String(part).trim()).filter(Boolean).join(' · ');
+/** A verified uid, or nothing: the host log has no anonymous actor. */ const hostActor = (actor)=>{
+    var _actor_email;
+    return actor.uid ? {
+        uid: actor.uid,
+        email: (_actor_email = actor.email) != null ? _actor_email : null
+    } : null;
+};
+/**
+ * `ai.job.created` — a generation job was briefed (AGL-2904).
+ *
+ * Names the job's kind, how long the brief was and the site it targets, so
+ * the row says what was asked for without storing the brief itself.
+ */ export async function logAiJobCreated(orgId, actor, job) {
+    var _job_hostName;
+    await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.jobCreated, {
+        type: 'aiJob',
+        id: job.jobId,
+        name: named(job.kind, `${Math.max(0, Math.floor(job.briefLength))}-character brief`, (_job_hostName = job.hostName) != null ? _job_hostName : job.hostId)
+    });
+}
+/**
+ * `ai.job.output` — one resource a job produced, one row per output.
+ *
+ * The org row names the resource, and a host-scoped output is copied into
+ * the site's own feed so a site's activity shows what was generated on it.
+ * The copy needs a uid: the host log's contract has no anonymous actor, so a
+ * job that finished with nobody present still lands in the org feed and
+ * only there.
+ */ export async function logAiJobOutput(orgId, actor, output) {
+    const target = _extends({
+        type: output.resource.type,
+        id: output.resource.id
+    }, output.resource.name ? {
+        name: output.resource.name
+    } : {}, output.resource.versionId ? {
+        versionId: output.resource.versionId
+    } : {});
+    await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.jobOutput, target);
+    const onHost = hostActor(actor);
+    if (output.hostId && onHost) {
+        await logHostActivity(output.hostId, onHost, AI_ACTIVITY_ACTIONS.jobOutput, target);
+    }
+}
+/** `ai.job.canceled` — a job was stopped before it finished. */ export async function logAiJobCanceled(orgId, actor, job) {
+    await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.jobCanceled, _extends({
+        type: 'aiJob',
+        id: job.jobId
+    }, named(job.kind, job.name) ? {
+        name: named(job.kind, job.name)
+    } : {}));
+}
+/**
+ * `ai.job.needs_input` — a job stopped and asked for a person, and why.
+ * Usually actorless: the band, the ceiling or the budget stopped it, not a
+ * member.
+ */ export async function logAiJobNeedsInput(orgId, actor, job) {
+    await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.jobNeedsInput, {
+        type: 'aiJob',
+        id: job.jobId,
+        name: named(job.kind, AI_JOB_NEEDS_INPUT_REASON_LABELS[job.reason])
+    });
+}
+/**
+ * `ai.edit.applied` — a proposal's edits landed on a besigner document
+ * (AGL-2906).
+ *
+ * The edits are applied in the author's own editor, as unsaved changes, so
+ * no server sees them land. The row is written by the door the editor
+ * reports the apply to, and only once that door has found the proposal on an
+ * exchange the same member had about the same document — so it stands on a
+ * proposal the server issued rather than on the client's word alone. Op
+ * counts are folded into the name (`Home · 3 set, 1 insert`); the edits
+ * themselves are the site's content and are not logged.
+ */ export async function logAiEditApplied(hostId, actor, edit) {
+    const counts = Object.entries(edit.opCounts).filter(([, count])=>Number.isFinite(count) && count > 0).map(([op, count])=>`${Math.floor(count)} ${op}`).join(', ');
+    await logHostActivity(hostId, actor, AI_ACTIVITY_ACTIONS.editApplied, {
+        type: edit.type,
+        id: edit.id,
+        name: named(edit.name, counts),
+        versionId: edit.versionId
+    });
+}
+/**
+ * `ai.seo.applied` — a site audit's fixes were applied as drafts (AGL-2910).
+ *
+ * Written by the door that applied them. The name carries the counts — new
+ * unpublished versions, listings staged for a person to save — and never
+ * the text proposed, which is the site's content. Org feed, and the site's
+ * own feed when a person is named.
+ */ export async function logAiSeoApplied(orgId, actor, apply) {
+    var _apply_hostName;
+    const versions = Math.max(0, Math.floor(apply.versions));
+    const staged = Math.max(0, Math.floor(apply.staged));
+    const target = {
+        type: 'aiJob',
+        id: apply.jobId,
+        name: named((_apply_hostName = apply.hostName) != null ? _apply_hostName : apply.hostId, `${versions} draft ${versions === 1 ? 'version' : 'versions'}`, `${staged} ${staged === 1 ? 'listing' : 'listings'} to review`)
+    };
+    await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.seoApplied, target);
+    const onHost = hostActor(actor);
+    if (onHost) {
+        await logHostActivity(apply.hostId, onHost, AI_ACTIVITY_ACTIONS.seoApplied, {
+            type: 'host',
+            id: apply.hostId,
+            name: target.name
+        });
+    }
+}
+/**
+ * `ai.assist.section` — the assist door returned a section subtree.
+ *
+ * Into the site's feed when the request named a site, else the org's, so
+ * the act is never unlogged for want of a host. Element rewrites are not
+ * logged here at all — too chatty — and the per-user rollup carries their
+ * count. The instruction is the customer's own copy and is not stored.
+ */ export async function logAiAssistSection(actor, section) {
+    var _section_hostName;
+    const nodes = Math.max(0, Math.floor(section.nodeCount));
+    const size = `${nodes} ${nodes === 1 ? 'element' : 'elements'}`;
+    const onHost = hostActor(actor);
+    if (section.hostId && onHost) {
+        await logHostActivity(section.hostId, onHost, AI_ACTIVITY_ACTIONS.assistSection, {
+            type: 'host',
+            id: section.hostId,
+            name: named(section.hostName, size)
+        });
+        return;
+    }
+    await logOrgActivity(section.orgId, actor, AI_ACTIVITY_ACTIONS.assistSection, {
+        type: 'org',
+        name: named((_section_hostName = section.hostName) != null ? _section_hostName : section.hostId, size)
+    });
+}
+const usd = (value)=>`$${value.toLocaleString('en-US')}`;
+/**
+ * `ai.overage.hardCap` / `ai.overage.cap` — a control moved.
+ *
+ * The routes already write `adminAudit`; this is the org-feed row that
+ * lets the customer see who set the control. Answers `false`, and writes
+ * nothing, when the value did not move.
+ */ export async function logAiOverageControl(orgId, actor, change) {
+    if (change.before === change.after) return false;
+    if (change.control === 'hardCap') {
+        await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.overageHardCap, {
+            type: 'org',
+            name: change.after ? 'On' : 'Off'
+        });
+        return true;
+    }
+    await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.overageCap, {
+        type: 'org',
+        name: change.after === null ? 'Cleared' : usd(change.after)
+    });
+    return true;
+}
+/**
+ * `ai.allotment.changed` — a manager set, changed or removed an AI allotment
+ * (AGL-2942): a member's, a collaborator's on one site, a site's, or the
+ * org-wide model restriction. The subject is the row's target; what it was
+ * set to is the name, in credits, never dollars.
+ */ export async function logAiAllotmentChanged(orgId, actor, change) {
+    var _after_models;
+    const after = change.after;
+    await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.allotmentChanged, _extends({
+        type: change.subject.type
+    }, change.subject.id ? {
+        id: change.subject.id
+    } : {}, {
+        name: named(change.subject.name, after === null ? 'removed' : after.credits === null ? null : `${after.credits.toLocaleString('en-US')} credits a month (${after.mode})`, (after == null ? void 0 : (_after_models = after.models) == null ? void 0 : _after_models.length) ? `${after.models.length} models allowed` : null)
+    }));
+}
+/**
+ * `ai.permission.changed` — an AI permission moved on a role, a member's
+ * override, a collaborator's site toggle or the org's default. The subject
+ * is the row's target; the permission and its direction are the name.
+ */ export async function logAiPermissionChanged(orgId, actor, change) {
+    await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.permissionChanged, _extends({
+        type: change.subject.type
+    }, change.subject.id ? {
+        id: change.subject.id
+    } : {}, {
+        name: named(change.subject.name, `${change.permission} ${change.granted ? 'granted' : 'revoked'}`)
+    }));
+}
+/**
+ * `ai.addon.purchased` / `ai.addon.removed` — the AI add-on came or went.
+ *
+ * Decided off the mirrored `seatAddons` maps rather than told, because the
+ * add-ons route mirrors the purchase at once and the webhook re-derives the
+ * same map on every subscription event: comparing before and after is what
+ * keeps a redelivery, or the webhook confirming a purchase the route already
+ * logged, from writing the row twice. Answers `false` when nothing moved.
+ */ export async function logAiAddonChanged(orgId, actor, change) {
+    const before = aiAddonUnits(change.before);
+    const after = aiAddonUnits(change.after);
+    if (before === after) return false;
+    await logOrgActivity(orgId, actor, after === 1 ? AI_ACTIVITY_ACTIONS.addonPurchased : AI_ACTIVITY_ACTIONS.addonRemoved, {
+        type: 'subscription',
+        name: aiAddonName()
+    });
+    return true;
+}
+
+//# sourceMappingURL=ai-activity.js.map

package/src/lib/activity/ai-activity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/activity/ai-activity.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The AI writers over the two customer-visible activity logs (AGL-2929).\n *\n * Every generation, applied edit and control change lands in\n * `orgs/{orgId}/activity` (and, for a host-scoped output, in\n * `hosts/{hostId}/activity`) through {@link logOrgActivity} and\n * {@link logHostActivity} — never a collection of its own, so the retention\n * `docs/DATA_RETENTION.md` already promises for the activity logs covers\n * these rows without a new entry, and the one permission-gated route that\n * serves the org feed serves them.\n *\n * Each helper owns ONE action code from `AI_ACTIVITY_ACTIONS` and the shape\n * of its target, so a caller cannot store a code the viewers do not know or\n * a target the presenter cannot label. What varies per row is folded into\n * `target.name`, which is the only free text the row carries: the feed reads\n * `<label> — <name>`, and a name like `screen · 240-character brief · Acme`\n * is what makes two jobs distinguishable in a list of them.\n *\n * Attribution follows `logOrgActivity`'s rule: `uid` is nullable because\n * some of these acts HAVE no actor — a job paused by the band with nobody\n * present, an add-on Stripe removed at the period end — and naming the last\n * person who touched the thing would file an act under someone who did not\n * perform it. A caller passes what it verified and nothing more.\n *\n * The control-change writers answer whether a row was written: a control set\n * to the value it already had is not a change, and a feed that said \"AI\n * overage ceiling — $25\" twice for one decision would read as two decisions.\n */\n\nimport type { HostActivityActor } from '@aglyn/aglyn/app-utils/activity-presenter'\nimport {\n  AI_ACTIVITY_ACTIONS,\n  AI_JOB_NEEDS_INPUT_REASON_LABELS,\n  type AiJobNeedsInputReason,\n} from './ai-activity-actions'\nimport {\n  aiAddonName,\n  aiAddonUnits,\n} from '@aglyn/aglyn/app-utils/plan-entitlements'\nimport type { OrgSeatAddons } from '@aglyn/aglyn/server'\nimport {\n  logHostActivity,\n  logOrgActivity,\n  type HostActivityTarget,\n  type OrgActivityTarget,\n} from '@aglyn/tenant-data-admin/server/organizations'\n\n/** Who performed the act — `uid: null` when nobody was present. */\nexport interface AiActivityActor {\n  uid: string | null\n  email?: string | null\n}\n\n/** The resource kinds a generation job can produce. */\nexport type AiOutputResourceType = Extract<\n  OrgActivityTarget['type'],\n  HostActivityTarget['type']\n>\n\n/** The pieces a target name is built from, blanks dropped. */\nconst named = (...parts: Array<string | number | null | undefined>): string =>\n  parts\n    .map((part) => (part === null || part === undefined ? '' : String(part).trim()))\n    .filter(Boolean)\n    .join(' · ')\n\n/** A verified uid, or nothing: the host log has no anonymous actor. */\nconst hostActor = (actor: AiActivityActor): HostActivityActor | null =>\n  actor.uid ? { uid: actor.uid, email: actor.email ?? null } : null\n\n/**\n * `ai.job.created` — a generation job was briefed (AGL-2904).\n *\n * Names the job's kind, how long the brief was and the site it targets, so\n * the row says what was asked for without storing the brief itself.\n */\nexport async function logAiJobCreated(\n  orgId: string,\n  actor: AiActivityActor,\n  job: {\n    jobId: string\n    /** What the job builds — a screen, a site, a section. */\n    kind: string\n    briefLength: number\n    hostId?: string | null\n    hostName?: string | null\n  },\n): Promise<void> {\n  await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.jobCreated, {\n    type: 'aiJob',\n    id: job.jobId,\n    name: named(\n      job.kind,\n      `${Math.max(0, Math.floor(job.briefLength))}-character brief`,\n      job.hostName ?? job.hostId,\n    ),\n  })\n}\n\n/**\n * `ai.job.output` — one resource a job produced, one row per output.\n *\n * The org row names the resource, and a host-scoped output is copied into\n * the site's own feed so a site's activity shows what was generated on it.\n * The copy needs a uid: the host log's contract has no anonymous actor, so a\n * job that finished with nobody present still lands in the org feed and\n * only there.\n */\nexport async function logAiJobOutput(\n  orgId: string,\n  actor: AiActivityActor,\n  output: {\n    jobId: string\n    hostId?: string | null\n    resource: {\n      type: AiOutputResourceType\n      id: string\n      name?: string | null\n      versionId?: string | null\n    }\n  },\n): Promise<void> {\n  const target = {\n    type: output.resource.type,\n    id: output.resource.id,\n    ...(output.resource.name ? { name: output.resource.name } : {}),\n    ...(output.resource.versionId ? { versionId: output.resource.versionId } : {}),\n  }\n  await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.jobOutput, target)\n  const onHost = hostActor(actor)\n  if (output.hostId && onHost) {\n    await logHostActivity(output.hostId, onHost, AI_ACTIVITY_ACTIONS.jobOutput, target)\n  }\n}\n\n/** `ai.job.canceled` — a job was stopped before it finished. */\nexport async function logAiJobCanceled(\n  orgId: string,\n  actor: AiActivityActor,\n  job: { jobId: string; kind?: string | null; name?: string | null },\n): Promise<void> {\n  await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.jobCanceled, {\n    type: 'aiJob',\n    id: job.jobId,\n    ...(named(job.kind, job.name) ? { name: named(job.kind, job.name) } : {}),\n  })\n}\n\n/**\n * `ai.job.needs_input` — a job stopped and asked for a person, and why.\n * Usually actorless: the band, the ceiling or the budget stopped it, not a\n * member.\n */\nexport async function logAiJobNeedsInput(\n  orgId: string,\n  actor: AiActivityActor,\n  job: { jobId: string; kind?: string | null; reason: AiJobNeedsInputReason },\n): Promise<void> {\n  await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.jobNeedsInput, {\n    type: 'aiJob',\n    id: job.jobId,\n    name: named(job.kind, AI_JOB_NEEDS_INPUT_REASON_LABELS[job.reason]),\n  })\n}\n\n/**\n * `ai.edit.applied` — a proposal's edits landed on a besigner document\n * (AGL-2906).\n *\n * The edits are applied in the author's own editor, as unsaved changes, so\n * no server sees them land. The row is written by the door the editor\n * reports the apply to, and only once that door has found the proposal on an\n * exchange the same member had about the same document — so it stands on a\n * proposal the server issued rather than on the client's word alone. Op\n * counts are folded into the name (`Home · 3 set, 1 insert`); the edits\n * themselves are the site's content and are not logged.\n */\nexport async function logAiEditApplied(\n  hostId: string,\n  actor: HostActivityActor,\n  edit: {\n    /** The kind of document the edits landed on. */\n    type: 'screen' | 'component' | 'layout'\n    id: string\n    name?: string | null\n    versionId: string\n    /** Edits applied, by operation — `{ set: 3, insert: 1 }`. */\n    opCounts: Record<string, number>\n  },\n): Promise<void> {\n  const counts = Object.entries(edit.opCounts)\n    .filter(([, count]) => Number.isFinite(count) && count > 0)\n    .map(([op, count]) => `${Math.floor(count)} ${op}`)\n    .join(', ')\n  await logHostActivity(hostId, actor, AI_ACTIVITY_ACTIONS.editApplied, {\n    type: edit.type,\n    id: edit.id,\n    name: named(edit.name, counts),\n    versionId: edit.versionId,\n  })\n}\n\n/**\n * `ai.seo.applied` — a site audit's fixes were applied as drafts (AGL-2910).\n *\n * Written by the door that applied them. The name carries the counts — new\n * unpublished versions, listings staged for a person to save — and never\n * the text proposed, which is the site's content. Org feed, and the site's\n * own feed when a person is named.\n */\nexport async function logAiSeoApplied(\n  orgId: string,\n  actor: AiActivityActor,\n  apply: {\n    jobId: string\n    hostId: string\n    hostName?: string | null\n    versions: number\n    staged: number\n  },\n): Promise<void> {\n  const versions = Math.max(0, Math.floor(apply.versions))\n  const staged = Math.max(0, Math.floor(apply.staged))\n  const target = {\n    type: 'aiJob' as const,\n    id: apply.jobId,\n    name: named(\n      apply.hostName ?? apply.hostId,\n      `${versions} draft ${versions === 1 ? 'version' : 'versions'}`,\n      `${staged} ${staged === 1 ? 'listing' : 'listings'} to review`,\n    ),\n  }\n  await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.seoApplied, target)\n  const onHost = hostActor(actor)\n  if (onHost) {\n    await logHostActivity(apply.hostId, onHost, AI_ACTIVITY_ACTIONS.seoApplied, {\n      type: 'host',\n      id: apply.hostId,\n      name: target.name,\n    })\n  }\n}\n\n/**\n * `ai.assist.section` — the assist door returned a section subtree.\n *\n * Into the site's feed when the request named a site, else the org's, so\n * the act is never unlogged for want of a host. Element rewrites are not\n * logged here at all — too chatty — and the per-user rollup carries their\n * count. The instruction is the customer's own copy and is not stored.\n */\nexport async function logAiAssistSection(\n  actor: AiActivityActor,\n  section: {\n    orgId: string\n    hostId?: string | null\n    hostName?: string | null\n    nodeCount: number\n  },\n): Promise<void> {\n  const nodes = Math.max(0, Math.floor(section.nodeCount))\n  const size = `${nodes} ${nodes === 1 ? 'element' : 'elements'}`\n  const onHost = hostActor(actor)\n  if (section.hostId && onHost) {\n    await logHostActivity(section.hostId, onHost, AI_ACTIVITY_ACTIONS.assistSection, {\n      type: 'host',\n      id: section.hostId,\n      name: named(section.hostName, size),\n    })\n    return\n  }\n  await logOrgActivity(section.orgId, actor, AI_ACTIVITY_ACTIONS.assistSection, {\n    type: 'org',\n    name: named(section.hostName ?? section.hostId, size),\n  })\n}\n\n/** The two overage controls a customer holds (AGL-2653, AGL-2898). */\nexport type AiOverageControlChange =\n  | { control: 'hardCap'; before: boolean; after: boolean }\n  | { control: 'cap'; before: number | null; after: number | null }\n\nconst usd = (value: number): string => `$${value.toLocaleString('en-US')}`\n\n/**\n * `ai.overage.hardCap` / `ai.overage.cap` — a control moved.\n *\n * The routes already write `adminAudit`; this is the org-feed row that\n * lets the customer see who set the control. Answers `false`, and writes\n * nothing, when the value did not move.\n */\nexport async function logAiOverageControl(\n  orgId: string,\n  actor: AiActivityActor,\n  change: AiOverageControlChange,\n): Promise<boolean> {\n  if (change.before === change.after) return false\n  if (change.control === 'hardCap') {\n    await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.overageHardCap, {\n      type: 'org',\n      name: change.after ? 'On' : 'Off',\n    })\n    return true\n  }\n  await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.overageCap, {\n    type: 'org',\n    name: change.after === null ? 'Cleared' : usd(change.after),\n  })\n  return true\n}\n\n/**\n * `ai.allotment.changed` — a manager set, changed or removed an AI allotment\n * (AGL-2942): a member's, a collaborator's on one site, a site's, or the\n * org-wide model restriction. The subject is the row's target; what it was\n * set to is the name, in credits, never dollars.\n */\nexport async function logAiAllotmentChanged(\n  orgId: string,\n  actor: AiActivityActor,\n  change: {\n    subject: {\n      type: 'org' | 'member' | 'host'\n      id?: string | null\n      name?: string | null\n    }\n    /** `null` when the allotment was removed. */\n    after: {\n      credits: number | null\n      mode: 'hard' | 'soft'\n      models: readonly string[] | null\n    } | null\n  },\n): Promise<void> {\n  const after = change.after\n  await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.allotmentChanged, {\n    type: change.subject.type,\n    ...(change.subject.id ? { id: change.subject.id } : {}),\n    name: named(\n      change.subject.name,\n      after === null\n        ? 'removed'\n        : after.credits === null\n          ? null\n          : `${after.credits.toLocaleString('en-US')} credits a month (${after.mode})`,\n      after?.models?.length ? `${after.models.length} models allowed` : null,\n    ),\n  })\n}\n\n/**\n * `ai.permission.changed` — an AI permission moved on a role, a member's\n * override, a collaborator's site toggle or the org's default. The subject\n * is the row's target; the permission and its direction are the name.\n */\nexport async function logAiPermissionChanged(\n  orgId: string,\n  actor: AiActivityActor,\n  change: {\n    subject: {\n      type: 'org' | 'role' | 'member' | 'host'\n      id?: string | null\n      name?: string | null\n    }\n    /** The permission key that moved — `ai.assist`, `ai.generate`. */\n    permission: string\n    granted: boolean\n  },\n): Promise<void> {\n  await logOrgActivity(orgId, actor, AI_ACTIVITY_ACTIONS.permissionChanged, {\n    type: change.subject.type,\n    ...(change.subject.id ? { id: change.subject.id } : {}),\n    name: named(\n      change.subject.name,\n      `${change.permission} ${change.granted ? 'granted' : 'revoked'}`,\n    ),\n  })\n}\n\n/**\n * `ai.addon.purchased` / `ai.addon.removed` — the AI add-on came or went.\n *\n * Decided off the mirrored `seatAddons` maps rather than told, because the\n * add-ons route mirrors the purchase at once and the webhook re-derives the\n * same map on every subscription event: comparing before and after is what\n * keeps a redelivery, or the webhook confirming a purchase the route already\n * logged, from writing the row twice. Answers `false` when nothing moved.\n */\nexport async function logAiAddonChanged(\n  orgId: string,\n  actor: AiActivityActor,\n  change: {\n    before: OrgSeatAddons | null | undefined\n    after: OrgSeatAddons | null | undefined\n  },\n): Promise<boolean> {\n  const before = aiAddonUnits(change.before)\n  const after = aiAddonUnits(change.after)\n  if (before === after) return false\n  await logOrgActivity(\n    orgId,\n    actor,\n    after === 1 ? AI_ACTIVITY_ACTIONS.addonPurchased : AI_ACTIVITY_ACTIONS.addonRemoved,\n    { type: 'subscription', name: aiAddonName() },\n  )\n  return true\n}\n"],"names":["AI_ACTIVITY_ACTIONS","AI_JOB_NEEDS_INPUT_REASON_LABELS","aiAddonName","aiAddonUnits","logHostActivity","logOrgActivity","named","parts","map","part","undefined","String","trim","filter","Boolean","join","hostActor","actor","uid","email","logAiJobCreated","orgId","job","jobCreated","type","id","jobId","name","kind","Math","max","floor","briefLength","hostName","hostId","logAiJobOutput","output","target","resource","versionId","jobOutput","onHost","logAiJobCanceled","jobCanceled","logAiJobNeedsInput","jobNeedsInput","reason","logAiEditApplied","edit","counts","Object","entries","opCounts","count","Number","isFinite","op","editApplied","logAiSeoApplied","apply","versions","staged","seoApplied","logAiAssistSection","section","nodes","nodeCount","size","assistSection","usd","value","toLocaleString","logAiOverageControl","change","before","after","control","overageHardCap","overageCap","logAiAllotmentChanged","allotmentChanged","subject","credits","mode","models","length","logAiPermissionChanged","permissionChanged","permission","granted","logAiAddonChanged","addonPurchased","addonRemoved"],"mappings":"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"}

package/src/lib/billing/ai-overage-charge.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @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 { type AiOverageClaim, type AiOverageClaimRefusal } from './ai-overage-ledger';
+import type { AiOverageOrg } from './ai-overage-standing';
+/**
+ * The Stripe product the overage line is billed against.
+ *
+ * A product rather than a bare amount because the PRODUCT carries the tax
+ * code the account's automatic tax computes from. Created in test mode
+ * first and in live mode only with the owner's yes; until the variable is
+ * set, no charge is attempted and the reason says so rather than failing
+ * against Stripe.
+ */
+export declare const AI_OVERAGE_PRODUCT_ENV = "STRIPE_PRODUCT_AI_OVERAGE";
+/** The metadata key the reconcile search matches a claim on. */
+export declare const AI_OVERAGE_CHARGE_METADATA_KEY = "chargeId";
+/** What one attempt did, for logs, the sweep's report and specs. */
+export interface AiOverageChargeOutcome {
+    charged: boolean;
+    chargeId: string | null;
+    invoiceId: string | null;
+    /** Why nothing was charged, when nothing was. */
+    skipped: AiOverageClaimRefusal | 'before-cutover' | 'no-stripe-customer' | 'no-product' | null;
+    /** Stripe's message when a charge was attempted and failed. */
+    error: string | null;
+}
+/** What the caller must hand over; nothing here reads the org document. */
+export interface AiOverageChargeRequest {
+    orgId: string;
+    org: AiOverageOrg;
+    month: string;
+    /** The workspace's Stripe customer, resolved by the caller from billing. */
+    stripeCustomerId: string | null;
+    now?: Date;
+}
+/**
+ * The line as the customer reads it on the invoice.
+ *
+ * Credits and retail dollars only. Provider cost never reaches a customer
+ * surface, and an invoice is the most customer-facing surface there is.
+ */
+export declare function aiOverageInvoiceDescription(claim: AiOverageClaim): string;
+/**
+ * Charges the workspace when its unbilled overage has reached the threshold.
+ *
+ * Called from `after()` once a metered turn's batch has committed, never on
+ * the request's await path: the tokens are already spent, and making a
+ * customer wait on a Stripe round trip to be handed an answer they have
+ * already paid for is the wrong trade. A charge that does not happen because
+ * the process ended is picked up by the reconcile sweep or by the next turn.
+ */
+export declare function maybeChargeAiOverage(firestore: FirebaseFirestore.Firestore, request: AiOverageChargeRequest): Promise<AiOverageChargeOutcome>;
+/**
+ * Bills the remainder of a month that has ended.
+ *
+ * The month's last charge, and the only one that bills below the threshold —
+ * there is nothing more to accrue, so anything Stripe will accept is worth
+ * settling. A remainder under Stripe's minimum is left unbilled rather than
+ * sent as an invoice that can never be paid.
+ */
+export declare function closeOutAiOverage(firestore: FirebaseFirestore.Firestore, request: AiOverageChargeRequest): Promise<AiOverageChargeOutcome>;
+/**
+ * Asks Stripe what became of a claim that never reported an outcome.
+ *
+ * The case is a process that died between claiming and charging, or between
+ * charging and recording. The claim id is on the invoice's metadata, so the
+ * question "did this claim ever become an invoice" has an answer even though
+ * this process never saw one.
+ *
+ * Stripe's search index is eventually consistent, so "not found" means NOT
+ * FOUND YET. A claim is only released after a grace period long enough for
+ * the index to have caught up; releasing early would create a second invoice
+ * for dollars that are already billed.
+ */
+export declare function reconcileAiOverageCharge(firestore: FirebaseFirestore.Firestore, request: {
+    orgId: string;
+    month: string;
+    chargeId: string;
+    claimedAgeMs: number;
+}, options?: {
+    graceMs?: number;
+}): Promise<{
+    resolved: boolean;
+    invoiceId: string | null;
+    released: boolean;
+}>;
+/** The path a claimed charge's audit row lives at, for the sweep's query. */
+export declare function aiOverageChargesPath(orgId: string): string;