@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/usage/staff-org-ai.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/usage/staff-org-ai.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// Imported from BOTH graphs — the staff card (client) and the App Route that\n// serves it — so it may import neither entry barrel, for the reason\n// `margin-utilization.ts` states at its own head.\nimport type { AiJobStatus } from '../model/ai-jobs.types'\nimport type { AglynOrgBilling, OrgPlan } from '@aglyn/aglyn/foundation'\nimport {\n  ASSIST_PROVIDER_COST_FIELD,\n  assistBandRefuses,\n  assistCreditsFromUsd,\n  assistProviderCostUsd,\n  assistMonthOverage,\n  assistOverageCapReached,\n  assistUsdFromCredits,\n  resolveAssistCreditBudget,\n  resolveAssistHardCap,\n  resolveAssistOverageCapUsd,\n} from '@aglyn/aglyn/app-utils/assist-credits'\nimport {\n  AI_ADDON_CREDITS_PER_MONTH,\n  hasAiAddon,\n  isUncappedPlanComp,\n  PLAN_ENTITLEMENTS,\n  resolveEffectivePlan,\n  resolvePlanPricing,\n  type DiscountMarginRating,\n} from '@aglyn/aglyn/app-utils/plan-entitlements'\nimport type { AssistRefusalCounts } from './assist-refusals'\nimport {\n  AI_USAGE_MONTH_KINDS_FIELD,\n  aiCacheHitRate,\n  readAiKindMonths,\n  type AiKindMonth,\n  type AiTokenTotals,\n} from '../model/ai-tokens'\n\n/**\n * THE STAFF AI CARD'S FIGURES (AGL-2930), composed from the same helpers the\n * meter, the invoice and the customer's own billing page read.\n *\n * Nothing here runs a query and nothing here holds a rate of its own. The\n * pool is `resolveAssistCreditBudget`, the overage is `assistMonthOverage`,\n * the ceiling is `assistOverageCapReached` — the ONE derivation each of those\n * already is — so the card cannot show a staff member a different band,\n * rate or ceiling from the one the gate refused a customer at.\n */\n\n/** The four ways the reservation refuses, plus their sum. */\nexport type StaffOrgAiRefusals = AssistRefusalCounts\n\nexport interface StaffOrgAiAddon {\n  /** Bought and on a subscription still paying for it — `hasAiAddon`. */\n  on: boolean\n  /** The add-on's list price on this plan, or null where the plan sells none. */\n  priceUsd: number | null\n  /** ISO instant the subscription item was created, when Stripe could say. */\n  since: string | null\n  /**\n   * Where `since` came from, so an absent date is legible: `stripe` answered,\n   * the org has no Stripe subscription to ask, or Stripe could not be asked\n   * (no key on this deployment, or the lookup failed).\n   */\n  sinceSource: 'stripe' | 'no-subscription' | 'unavailable'\n}\n\nexport interface StaffOrgAiPool {\n  /** The plan's own band, from the catalogue row. */\n  planCredits: number\n  /** A staff override of the band, or null when none is written. */\n  overrideCredits: number | null\n  /** The add-on's band, 0 without the add-on. */\n  addonCredits: number\n  /** The whole pool as the meter resolves it, or null where no band applies. */\n  totalCredits: number | null\n  /**\n   * Whether an uncapped staff comp is why no band applies (AGL-3049) — a\n   * boolean, so \"no band because uncapped\" crosses JSON as itself rather\n   * than as the `null` an `Infinity` would become. Absent from a route older\n   * than the flag.\n   */\n  uncapped?: boolean\n  /** Credits drawn this month, rounded up from the measured spend. */\n  usedCredits: number\n  /**\n   * What the month DREW, at the catalog's billed rates — the dollars\n   * `usedCredits` is rounded up from, and the figure the overage line is\n   * priced off. Not a cost (AGL-3015).\n   */\n  billedUsd: number\n  /**\n   * What the month COST US, at the provider's own rates: the one figure a\n   * margin or a spend alert may be taken against.\n   */\n  providerUsd: number\n  /** Left in the pool, clamped at zero, or null where no band applies. */\n  remainingCredits: number | null\n  /** Where `usedCredits` lands at month end at the pace so far. */\n  projectedCredits: number\n  /** `projectedCredits` back in dollars — billed, as the credits were. */\n  projectedUsd: number\n  /** Model turns and docs-deflected turns, off the month document. */\n  messages: number\n  deflected: number\n}\n\nexport interface StaffOrgAiOverage {\n  overageCredits: number\n  rateUsdPer1k: number | null\n  accruedUsd: number\n  /** Whether credits past the band are sold at all on this org. */\n  sellsOverage: boolean\n  /** The org's own band switch — `assistOverage.hardCap`. */\n  hardCap: boolean\n  /** The org's own dollar ceiling on overage — `assistOverage.capUsd`. */\n  capUsd: number | null\n  capReached: boolean\n  /** Whether the band is a wall for any reason (the switch, or no rate). */\n  bandRefuses: boolean\n}\n\nexport interface StaffOrgAiMargin {\n  /** The add-on's list price when it is on, else 0. */\n  addonRevenueUsd: number\n  /**\n   * The dollar value of the plan's own band — what the plan price sets aside\n   * for assist. Each plan band is sized against the billed rate (a thousand\n   * credits are a dollar), so this is the share of the subscription that was\n   * sold as AI, and it belongs on the REVENUE side beside the add-on's price.\n   */\n  planAssistShareUsd: number\n  /** Overage priced at the plan's rate, which the invoice will bill. */\n  overageRevenueUsd: number\n  /** The three above, summed. */\n  revenueUsd: number\n  /** What the month cost us: measured provider spend, never what it drew. */\n  spendUsd: number\n  /**\n   * Spend past what the add-on and the plan's assist share bring in — the\n   * condition the card renders red. Overage revenue is left OUT of the\n   * comparison on purpose: it is billed at a margin, so an org deep in\n   * overage is not the one losing money.\n   */\n  underwater: boolean\n  /** The staff review threshold and the multiple of it the spend has reached. */\n  thresholdUsd: number\n  multiple: number\n  /** The whole-org contribution margin, when a usage rollup exists. */\n  contribution: {\n    month: string | null\n    marginPct: number | null\n    rating: DiscountMarginRating | null\n  }\n}\n\n/** The job model's own status set: the card renders every one by name. */\nexport type StaffOrgAiJobStatus = AiJobStatus\n\nexport interface StaffOrgAiJob {\n  id: string\n  kind: string\n  status: StaffOrgAiJobStatus | string\n  creditsReserved: number\n  creditsSpent: number\n  createdAt: string | null\n  createdBy: string | null\n}\n\nexport interface StaffOrgAiJobs {\n  counts: Record<StaffOrgAiJobStatus, number>\n  recent: StaffOrgAiJob[]\n  /** True when the scan stopped at its ceiling — the counts are a floor. */\n  truncated: boolean\n}\n\n/** One row of the per-user rollup (AGL-2928), as the staff card lists it. */\nexport interface StaffOrgAiUser {\n  uid: string\n  /** The roster's name for them — display name, else email, else the uid. */\n  name: string\n  credits: number\n  /** The measured provider spend behind `credits`; staff may see dollars. */\n  estCostUsd: number\n  /** Of the org's measured spend for the month, in `[0, 1]`. */\n  share: number\n  requests: number\n  refusals: number\n  byKind: Record<string, number>\n  byHost: Record<string, number>\n}\n\n/** One kind of model request this month, as the card lists it (AGL-2937). */\nexport interface StaffOrgAiKindTokens extends AiKindMonth {\n  /**\n   * What one request of this kind COST US on average; `null` with none. The\n   * provider figure, not what the kind drew — the reader is sizing a step\n   * against a bill, and a marked-up model would otherwise make the step look\n   * dearer to run than it is (AGL-3015).\n   */\n  costPerRequestUsd: number | null\n  /** The share of this kind's prompt tokens the cache served — `aiCacheHitRate`. */\n  cacheHitRate: number | null\n}\n\n/** The month's tokens (AGL-2937): its totals, its cache hit rate, and each kind. */\nexport interface StaffOrgAiTokens {\n  /** The month document's own four totals. */\n  total: AiTokenTotals\n  cacheHitRate: number | null\n  /** Dearest first; empty for a month written before kinds were kept. */\n  kinds: StaffOrgAiKindTokens[]\n}\n\nexport interface StaffOrgAiResponse {\n  month: string\n  addon: StaffOrgAiAddon\n  pool: StaffOrgAiPool\n  overage: StaffOrgAiOverage\n  refusals: StaffOrgAiRefusals\n  /** Null when the jobs read failed — distinct from an org with no jobs. */\n  jobs: StaffOrgAiJobs | null\n  /** The dearest people this month; empty when nobody's month is written. */\n  users: StaffOrgAiUser[]\n  margin: StaffOrgAiMargin\n  /** Tokens by kind (AGL-2937); absent from a route older than the card. */\n  tokens?: StaffOrgAiTokens\n}\n\nconst finite = (value: unknown): number => {\n  const parsed = Number(value ?? 0)\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0\n}\n\n/** The UTC day-of-month and month length `projectMonthEnd` scales by. */\nexport function monthProgress(now: Date): { elapsed: number; length: number } {\n  const year = now.getUTCFullYear()\n  const month = now.getUTCMonth()\n  return {\n    elapsed: now.getUTCDate(),\n    length: new Date(Date.UTC(year, month + 1, 0)).getUTCDate(),\n  }\n}\n\n/**\n * Where a month-to-date figure lands at month end at the pace so far.\n *\n * Linear, on whole UTC days, and deliberately no cleverer: the reader is\n * asking \"will this org clear its band\" and a straight line answers that\n * within the margin the question needs. Day one projects the first day's\n * spend across the month, which over-reads a burst — the direction a\n * monitoring figure should err in.\n */\nexport function projectMonthEnd(usedSoFar: number, now: Date): number {\n  const { elapsed, length } = monthProgress(now)\n  if (!(usedSoFar > 0) || elapsed <= 0) return 0\n  return Math.ceil((usedSoFar / elapsed) * length)\n}\n\n/** The staff override of the assist band, or null when none is written. */\nfunction assistBandOverride(\n  org: Partial<AglynOrgBilling> | null | undefined,\n): number | null {\n  const raw = (org?.entitlements as Record<string, unknown> | undefined)?.[\n    'assistCreditsPerMonth'\n  ]\n  if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0) return null\n  return Math.floor(raw)\n}\n\nexport function composeStaffOrgAiPool(\n  org: Partial<AglynOrgBilling> | null | undefined,\n  monthDoc: Record<string, unknown> | null | undefined,\n  now: Date,\n): StaffOrgAiPool {\n  const plan = resolveEffectivePlan(org) as OrgPlan\n  const addon = hasAiAddon(org)\n  // Two questions, two figures (AGL-3015). What the workspace DREW is the\n  // billed figure, because that is what its credits came out of and what its\n  // band is measured in. What the month COST US is the provider figure, and\n  // it is the only one a margin below may be taken against.\n  const billedUsd = finite(monthDoc?.['estCostUsd'])\n  const providerUsd = assistProviderCostUsd(\n    billedUsd,\n    monthDoc?.[ASSIST_PROVIDER_COST_FIELD],\n  )\n  const usedCredits = assistCreditsFromUsd(billedUsd)\n  const totalCredits = resolveAssistCreditBudget(org)\n  const projectedCredits = projectMonthEnd(usedCredits, now)\n  return {\n    planCredits: finite(PLAN_ENTITLEMENTS[plan]?.assistCreditsPerMonth),\n    overrideCredits: assistBandOverride(org),\n    addonCredits: addon ? AI_ADDON_CREDITS_PER_MONTH[plan] : 0,\n    totalCredits,\n    uncapped: isUncappedPlanComp(org),\n    usedCredits,\n    billedUsd,\n    providerUsd,\n    remainingCredits:\n      totalCredits === null ? null : Math.max(0, totalCredits - usedCredits),\n    projectedCredits,\n    projectedUsd: assistUsdFromCredits(projectedCredits),\n    messages: Math.floor(finite(monthDoc?.['messages'])),\n    deflected: Math.floor(finite(monthDoc?.['deflected'])),\n  }\n}\n\n/**\n * The month's tokens as the card reads them: the totals the month document\n * has always kept, and its `kinds` map (`model/ai-tokens.ts`) with the cost\n * per request and the cache hit rate worked out per kind.\n */\nexport function composeStaffOrgAiTokens(\n  monthDoc: Record<string, unknown> | null | undefined,\n): StaffOrgAiTokens {\n  const total: AiTokenTotals = {\n    input: Math.floor(finite(monthDoc?.['inputTokens'])),\n    cached: Math.floor(finite(monthDoc?.['cacheReadTokens'])),\n    cacheWrite: Math.floor(finite(monthDoc?.['cacheWriteTokens'])),\n    output: Math.floor(finite(monthDoc?.['outputTokens'])),\n  }\n  return {\n    total,\n    cacheHitRate: aiCacheHitRate(total),\n    kinds: readAiKindMonths(monthDoc?.[AI_USAGE_MONTH_KINDS_FIELD]).map((row) => ({\n      ...row,\n      costPerRequestUsd:\n        row.requests > 0\n          ? Math.round((row.providerCostUsd / row.requests) * 1_000_000) / 1_000_000\n          : null,\n      cacheHitRate: aiCacheHitRate(row.tokens),\n    })),\n  }\n}\n\n/**\n * Takes the BILLED figure, never the provider one (AGL-3015): every line\n * here is what the customer owes — credits past the band, the rate they sell\n * at, the dollars accrued, whether the org's own cap is reached — and an\n * invoice priced off our cost would bill a different month than the meter\n * the customer reads.\n */\nexport function composeStaffOrgAiOverage(\n  org: Partial<AglynOrgBilling> | null | undefined,\n  billedUsd: number,\n): StaffOrgAiOverage {\n  const overage = assistMonthOverage(org, billedUsd)\n  return {\n    overageCredits: overage.overageCredits,\n    rateUsdPer1k: overage.overageRateUsd,\n    accruedUsd: overage.overageMonthlyUsd,\n    sellsOverage: overage.bandCredits !== null && overage.overageRateUsd !== null,\n    hardCap: resolveAssistHardCap(org),\n    capUsd: resolveAssistOverageCapUsd(org),\n    capReached: assistOverageCapReached(org, billedUsd),\n    bandRefuses: assistBandRefuses(org),\n  }\n}\n\nexport function composeStaffOrgAiAddon(\n  org: Partial<AglynOrgBilling> | null | undefined,\n  since: Pick<StaffOrgAiAddon, 'since' | 'sinceSource'>,\n): StaffOrgAiAddon {\n  return {\n    on: hasAiAddon(org),\n    // What this workspace would be charged — none for a staff comp, which\n    // has no subscription to carry the item (AGL-3034).\n    priceUsd: resolvePlanPricing(org).aiAddonMonthlyUsd ?? null,\n    ...since,\n  }\n}\n\nexport function composeStaffOrgAiMargin(input: {\n  org: Partial<AglynOrgBilling> | null | undefined\n  pool: StaffOrgAiPool\n  overage: StaffOrgAiOverage\n  addon: StaffOrgAiAddon\n  thresholdUsd: number\n  multiple: number\n  contribution: StaffOrgAiMargin['contribution']\n}): StaffOrgAiMargin {\n  const { pool, overage, addon } = input\n  const addonRevenueUsd = addon.on ? finite(addon.priceUsd) : 0\n  // The band the PLAN sells — the override, when one is written, is what the\n  // customer was actually given, so it is the figure the price is carrying.\n  const planAssistShareUsd = assistUsdFromCredits(\n    pool.overrideCredits ?? pool.planCredits,\n  )\n  const overageRevenueUsd = overage.accruedUsd\n  // THE ONE PLACE THE TWO RATES MEET (AGL-3015). Revenue is what the\n  // customer pays — an add-on price, a band sized in credits, overage at the\n  // retail rate — and spend is what the provider charges us. Taking both\n  // sides off one figure was what made a fully-drawn band read as exactly\n  // break-even no matter what the tokens actually cost.\n  const revenueUsd =\n    Math.round((addonRevenueUsd + planAssistShareUsd + overageRevenueUsd) * 100) /\n    100\n  return {\n    addonRevenueUsd,\n    planAssistShareUsd,\n    overageRevenueUsd,\n    revenueUsd,\n    spendUsd: pool.providerUsd,\n    underwater: pool.providerUsd > addonRevenueUsd + planAssistShareUsd,\n    thresholdUsd: input.thresholdUsd,\n    multiple: input.multiple,\n    contribution: input.contribution,\n  }\n}\n\nexport const STAFF_ORG_AI_JOB_STATUSES: readonly StaffOrgAiJobStatus[] = [\n  'queued',\n  'running',\n  'needs_input',\n  'needs_review',\n  'done',\n  'failed',\n  'canceled',\n]\n\n/** Zero-filled counts, so the card renders every status by name. */\nexport function emptyJobCounts(): Record<StaffOrgAiJobStatus, number> {\n  return Object.fromEntries(\n    STAFF_ORG_AI_JOB_STATUSES.map((status) => [status, 0]),\n  ) as Record<StaffOrgAiJobStatus, number>\n}\n"],"names":["ASSIST_PROVIDER_COST_FIELD","assistBandRefuses","assistCreditsFromUsd","assistProviderCostUsd","assistMonthOverage","assistOverageCapReached","assistUsdFromCredits","resolveAssistCreditBudget","resolveAssistHardCap","resolveAssistOverageCapUsd","AI_ADDON_CREDITS_PER_MONTH","hasAiAddon","isUncappedPlanComp","PLAN_ENTITLEMENTS","resolveEffectivePlan","resolvePlanPricing","AI_USAGE_MONTH_KINDS_FIELD","aiCacheHitRate","readAiKindMonths","finite","value","parsed","Number","isFinite","monthProgress","now","year","getUTCFullYear","month","getUTCMonth","elapsed","getUTCDate","length","Date","UTC","projectMonthEnd","usedSoFar","Math","ceil","assistBandOverride","org","raw","entitlements","floor","composeStaffOrgAiPool","monthDoc","plan","addon","billedUsd","providerUsd","usedCredits","totalCredits","projectedCredits","planCredits","assistCreditsPerMonth","overrideCredits","addonCredits","uncapped","remainingCredits","max","projectedUsd","messages","deflected","composeStaffOrgAiTokens","total","input","cached","cacheWrite","output","cacheHitRate","kinds","map","row","costPerRequestUsd","requests","round","providerCostUsd","tokens","composeStaffOrgAiOverage","overage","overageCredits","rateUsdPer1k","overageRateUsd","accruedUsd","overageMonthlyUsd","sellsOverage","bandCredits","hardCap","capUsd","capReached","bandRefuses","composeStaffOrgAiAddon","since","on","priceUsd","aiAddonMonthlyUsd","composeStaffOrgAiMargin","pool","addonRevenueUsd","planAssistShareUsd","overageRevenueUsd","revenueUsd","spendUsd","underwater","thresholdUsd","multiple","contribution","STAFF_ORG_AI_JOB_STATUSES","emptyJobCounts","Object","fromEntries","status"],"mappings":"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"}

package/src/lib/usage/staff-org-usage-ai.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @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 { AglynOrgBilling } from '@aglyn/aglyn';
+/**
+ * THE STAFF ORG USAGE TABLE'S AI FIGURES (AGL-2984).
+ *
+ * The staff org usage table — on the staff org page and in the Organizations
+ * list's Usage dialog — draws this plugin's three columns through its
+ * `staffOrgUsageColumn` zone, and the org page draws the credit pool line
+ * above it. These are the texts they draw, apart from React so each shape
+ * is pinned on its own.
+ */
+/** The AI fields of one monthly rollup row, as the org usage route serves it. */
+export interface StaffOrgUsageAiMonth {
+    /**
+     * Provider spend for the month in dollars (AGL-2280). Its own column rather
+     * than folded into the metering estimate: this is a real provider bill.
+     */
+    assistCostUsd?: number | null;
+    /**
+     * The credit view of the same spend (AGL-2930): what the month drew
+     * against the band, and the part past it that was billed. `null` on a
+     * rollup written before the credit meter existed — a `0` there would
+     * state, as measurement, that the org used no AI in a month nobody
+     * measured.
+     */
+    assistCredits?: number | null;
+    assistOverageUsd?: number | null;
+}
+/**
+ * The Assist column's text. Four decimals, not two: spend arrives in
+ * thousandths of a dollar per exchange, and `$0.00` for a month that really
+ * cost eight cents is a silence.
+ */
+export declare function assistCostCell(value: number | null | undefined): string;
+/** A recorded count, or the dash that says the rollup predates it. */
+export declare function aiCreditsCell(value: number | null | undefined): string;
+/** A billed dollar figure, or the dash that says the rollup predates it. */
+export declare function aiOverageCell(value: number | null | undefined): string;
+/**
+ * The org's AI credit pool (AGL-2899): whether the AI add-on is on, the
+ * credits the add-on contributes, and the whole band the Assist column is
+ * drawn against.
+ */
+export interface StaffAssistPool {
+    aiAddon: boolean;
+    /** The add-on's band alone; 0 without the add-on. */
+    addonCredits: number;
+    /** Plan band plus add-on band, or null where the plan sells no band. */
+    creditsPerMonth: number | null;
+    /**
+     * Present, and true, only where an uncapped staff comp lifts the band
+     * (AGL-3049) — the other reason `creditsPerMonth` is null.
+     */
+    uncapped?: true;
+}
+/**
+ * The pool as the meter resolves it from the org document: the plan's band
+ * plus the add-on's, folded by `resolveOrgEntitlements`, with the add-on
+ * read off the EFFECTIVE plan through `hasAiAddon` — so a dead
+ * subscription's add-on reads as off here exactly as it does on the
+ * customer's own meter.
+ */
+export declare function staffAssistPool(org: Partial<AglynOrgBilling> | null | undefined): StaffAssistPool;
+/**
+ * The pool as one line: the reader of the Assist column needs to know what
+ * band the dollars are drawn against, and whether an add-on is part of it.
+ */
+export declare function assistPoolSentence(pool: StaffAssistPool): string;

package/src/lib/usage/staff-org-usage-ai.js

@@ -0,0 +1,59 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { AI_ADDON_CREDITS_PER_MONTH, aiAddonName, hasAiAddon, isUncappedPlanComp, resolveEffectivePlan, resolveOrgEntitlements } from "@aglyn/aglyn/app-utils/plan-entitlements";
+/**
+ * The Assist column's text. Four decimals, not two: spend arrives in
+ * thousandths of a dollar per exchange, and `$0.00` for a month that really
+ * cost eight cents is a silence.
+ */ export function assistCostCell(value) {
+    return `$${Number(value != null ? value : 0).toFixed(4)}`;
+}
+/** A recorded count, or the dash that says the rollup predates it. */ export function aiCreditsCell(value) {
+    return value == null ? '—' : Math.round(value).toLocaleString();
+}
+/** A billed dollar figure, or the dash that says the rollup predates it. */ export function aiOverageCell(value) {
+    return value == null ? '—' : `$${Number(value).toFixed(2)}`;
+}
+/**
+ * The pool as the meter resolves it from the org document: the plan's band
+ * plus the add-on's, folded by `resolveOrgEntitlements`, with the add-on
+ * read off the EFFECTIVE plan through `hasAiAddon` — so a dead
+ * subscription's add-on reads as off here exactly as it does on the
+ * customer's own meter.
+ */ export function staffAssistPool(org) {
+    const aiAddon = hasAiAddon(org);
+    const creditsPerMonth = resolveOrgEntitlements(org).assistCreditsPerMonth;
+    return _extends({
+        aiAddon,
+        addonCredits: aiAddon ? AI_ADDON_CREDITS_PER_MONTH[resolveEffectivePlan(org)] : 0,
+        // Finite only: an uncapped comp resolves the band `UNLIMITED`, which is
+        // no band to name a figure for.
+        creditsPerMonth: Number.isFinite(creditsPerMonth) && creditsPerMonth > 0 ? creditsPerMonth : null
+    }, isUncappedPlanComp(org) ? {
+        uncapped: true
+    } : {});
+}
+/**
+ * The pool as one line: the reader of the Assist column needs to know what
+ * band the dollars are drawn against, and whether an add-on is part of it.
+ */ export function assistPoolSentence(pool) {
+    const band = pool.creditsPerMonth !== null ? `${pool.creditsPerMonth.toLocaleString()} AI credits/mo` : pool.uncapped ? 'no AI credit band (uncapped staff comp)' : 'no AI credit band';
+    const name = aiAddonName();
+    return pool.aiAddon ? `${name} add-on on — ${band}, ${pool.addonCredits.toLocaleString()} ` + 'of them from the add-on.' : `${name} add-on off — ${band}.`;
+}
+
+//# sourceMappingURL=staff-org-usage-ai.js.map

package/src/lib/usage/staff-org-usage-ai.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/usage/staff-org-usage-ai.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\nimport type { AglynOrgBilling } from '@aglyn/aglyn'\nimport {\n  AI_ADDON_CREDITS_PER_MONTH,\n  aiAddonName,\n  hasAiAddon,\n  isUncappedPlanComp,\n  resolveEffectivePlan,\n  resolveOrgEntitlements,\n} from '@aglyn/aglyn/app-utils/plan-entitlements'\n\n/**\n * THE STAFF ORG USAGE TABLE'S AI FIGURES (AGL-2984).\n *\n * The staff org usage table — on the staff org page and in the Organizations\n * list's Usage dialog — draws this plugin's three columns through its\n * `staffOrgUsageColumn` zone, and the org page draws the credit pool line\n * above it. These are the texts they draw, apart from React so each shape\n * is pinned on its own.\n */\n\n/** The AI fields of one monthly rollup row, as the org usage route serves it. */\nexport interface StaffOrgUsageAiMonth {\n  /**\n   * Provider spend for the month in dollars (AGL-2280). Its own column rather\n   * than folded into the metering estimate: this is a real provider bill.\n   */\n  assistCostUsd?: number | null\n  /**\n   * The credit view of the same spend (AGL-2930): what the month drew\n   * against the band, and the part past it that was billed. `null` on a\n   * rollup written before the credit meter existed — a `0` there would\n   * state, as measurement, that the org used no AI in a month nobody\n   * measured.\n   */\n  assistCredits?: number | null\n  assistOverageUsd?: number | null\n}\n\n/**\n * The Assist column's text. Four decimals, not two: spend arrives in\n * thousandths of a dollar per exchange, and `$0.00` for a month that really\n * cost eight cents is a silence.\n */\nexport function assistCostCell(value: number | null | undefined): string {\n  return `$${Number(value ?? 0).toFixed(4)}`\n}\n\n/** A recorded count, or the dash that says the rollup predates it. */\nexport function aiCreditsCell(value: number | null | undefined): string {\n  return value == null ? '—' : Math.round(value).toLocaleString()\n}\n\n/** A billed dollar figure, or the dash that says the rollup predates it. */\nexport function aiOverageCell(value: number | null | undefined): string {\n  return value == null ? '—' : `$${Number(value).toFixed(2)}`\n}\n\n/**\n * The org's AI credit pool (AGL-2899): whether the AI add-on is on, the\n * credits the add-on contributes, and the whole band the Assist column is\n * drawn against.\n */\nexport interface StaffAssistPool {\n  aiAddon: boolean\n  /** The add-on's band alone; 0 without the add-on. */\n  addonCredits: number\n  /** Plan band plus add-on band, or null where the plan sells no band. */\n  creditsPerMonth: number | null\n  /**\n   * Present, and true, only where an uncapped staff comp lifts the band\n   * (AGL-3049) — the other reason `creditsPerMonth` is null.\n   */\n  uncapped?: true\n}\n\n/**\n * The pool as the meter resolves it from the org document: the plan's band\n * plus the add-on's, folded by `resolveOrgEntitlements`, with the add-on\n * read off the EFFECTIVE plan through `hasAiAddon` — so a dead\n * subscription's add-on reads as off here exactly as it does on the\n * customer's own meter.\n */\nexport function staffAssistPool(\n  org: Partial<AglynOrgBilling> | null | undefined,\n): StaffAssistPool {\n  const aiAddon = hasAiAddon(org)\n  const creditsPerMonth = resolveOrgEntitlements(org).assistCreditsPerMonth\n  return {\n    aiAddon,\n    addonCredits: aiAddon\n      ? AI_ADDON_CREDITS_PER_MONTH[resolveEffectivePlan(org)]\n      : 0,\n    // Finite only: an uncapped comp resolves the band `UNLIMITED`, which is\n    // no band to name a figure for.\n    creditsPerMonth:\n      Number.isFinite(creditsPerMonth) && creditsPerMonth > 0\n        ? creditsPerMonth\n        : null,\n    ...(isUncappedPlanComp(org) ? { uncapped: true as const } : {}),\n  }\n}\n\n/**\n * The pool as one line: the reader of the Assist column needs to know what\n * band the dollars are drawn against, and whether an add-on is part of it.\n */\nexport function assistPoolSentence(pool: StaffAssistPool): string {\n  const band =\n    pool.creditsPerMonth !== null\n      ? `${pool.creditsPerMonth.toLocaleString()} AI credits/mo`\n      : pool.uncapped\n        ? 'no AI credit band (uncapped staff comp)'\n        : 'no AI credit band'\n  const name = aiAddonName()\n  return pool.aiAddon\n    ? `${name} add-on on — ${band}, ${pool.addonCredits.toLocaleString()} ` +\n        'of them from the add-on.'\n    : `${name} add-on off — ${band}.`\n}\n"],"names":["AI_ADDON_CREDITS_PER_MONTH","aiAddonName","hasAiAddon","isUncappedPlanComp","resolveEffectivePlan","resolveOrgEntitlements","assistCostCell","value","Number","toFixed","aiCreditsCell","Math","round","toLocaleString","aiOverageCell","staffAssistPool","org","aiAddon","creditsPerMonth","assistCreditsPerMonth","addonCredits","isFinite","uncapped","assistPoolSentence","pool","band","name"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SACEA,0BAA0B,EAC1BC,WAAW,EACXC,UAAU,EACVC,kBAAkB,EAClBC,oBAAoB,EACpBC,sBAAsB,QACjB,2CAA0C;AA8BjD;;;;CAIC,GACD,OAAO,SAASC,eAAeC,KAAgC;IAC7D,OAAO,CAAC,CAAC,EAAEC,OAAOD,gBAAAA,QAAS,GAAGE,OAAO,CAAC,IAAI;AAC5C;AAEA,oEAAoE,GACpE,OAAO,SAASC,cAAcH,KAAgC;IAC5D,OAAOA,SAAS,OAAO,MAAMI,KAAKC,KAAK,CAACL,OAAOM,cAAc;AAC/D;AAEA,0EAA0E,GAC1E,OAAO,SAASC,cAAcP,KAAgC;IAC5D,OAAOA,SAAS,OAAO,MAAM,CAAC,CAAC,EAAEC,OAAOD,OAAOE,OAAO,CAAC,IAAI;AAC7D;AAoBA;;;;;;CAMC,GACD,OAAO,SAASM,gBACdC,GAAgD;IAEhD,MAAMC,UAAUf,WAAWc;IAC3B,MAAME,kBAAkBb,uBAAuBW,KAAKG,qBAAqB;IACzE,OAAO;QACLF;QACAG,cAAcH,UACVjB,0BAA0B,CAACI,qBAAqBY,KAAK,GACrD;QACJ,wEAAwE;QACxE,gCAAgC;QAChCE,iBACEV,OAAOa,QAAQ,CAACH,oBAAoBA,kBAAkB,IAClDA,kBACA;OACFf,mBAAmBa,OAAO;QAAEM,UAAU;IAAc,IAAI,CAAC;AAEjE;AAEA;;;CAGC,GACD,OAAO,SAASC,mBAAmBC,IAAqB;IACtD,MAAMC,OACJD,KAAKN,eAAe,KAAK,OACrB,GAAGM,KAAKN,eAAe,CAACL,cAAc,GAAG,cAAc,CAAC,GACxDW,KAAKF,QAAQ,GACX,4CACA;IACR,MAAMI,OAAOzB;IACb,OAAOuB,KAAKP,OAAO,GACf,GAAGS,KAAK,aAAa,EAAED,KAAK,EAAE,EAAED,KAAKJ,YAAY,CAACP,cAAc,GAAG,CAAC,CAAC,GACnE,6BACF,GAAGa,KAAK,cAAc,EAAED,KAAK,CAAC,CAAC;AACrC"}

package/src/lib/usage/staff-orgs-ai-spend.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @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 STAFF ORGANIZATIONS LIST'S AI SPEND COLUMN, AS DATA (AGL-2984).
+ *
+ * The list draws this plugin's column through its `staffOrgsListColumn`
+ * zone: one read of the page's orgs through `/api/ai/admin/orgs-spend`, a
+ * cell per row, and a header that sorts the page by the figures. The parts
+ * all three share live here — the wire, the number a sort compares, the text
+ * a cell shows, and the request's id list — free of React and of the Admin
+ * SDK, so the route, the hook and the specs read one definition.
+ */
+/** The most org ids one request may name — past the list's largest page. */
+export declare const STAFF_ORGS_AI_SPEND_MAX_IDS = 100;
+/** What `/api/ai/admin/orgs-spend` answers. */
+export interface StaffOrgsAiSpendWire {
+    /** The month the figures describe, `YYYY-MM` in UTC. */
+    month: string;
+    /**
+     * This month's provider spend in USD, by org id. `null` where the org has
+     * no usage document for the month or the read failed, never `0`: "spent
+     * nothing" and "not measured" stay distinct, and the column exists to find
+     * the org that IS spending.
+     */
+    spendUsd: Record<string, number | null>;
+}
+/**
+ * What a sort compares: a NUMBER, or `null` for an unmeasured org. The text
+ * a cell shows would sort `$10.0000` before `$9.0000`.
+ */
+export declare function aiSpendSortValue(value: unknown): number | null;
+/**
+ * What a cell shows: four decimals, because a month that really cost eight
+ * cents must not read as `$0.00`, and a dash for an unmeasured org — never
+ * `$0`.
+ */
+export declare function aiSpendCell(value: unknown): string;
+/** Dearest first; an unmeasured org last. */
+export declare function byAiSpendDesc(a: unknown, b: unknown): number;
+/** Cheapest first; an unmeasured org still last. */
+export declare function byAiSpendAsc(a: unknown, b: unknown): number;
+/**
+ * The list's rows in a direction by their org's spend — the comparator the
+ * column's header hands the list. A row whose org the answer does not name
+ * reads as unmeasured.
+ */
+export declare function aiSpendRowComparator(spendUsd: Readonly<Record<string, number | null>>, direction: 'asc' | 'desc'): (a: {
+    $id?: unknown;
+}, b: {
+    $id?: unknown;
+}) => number;
+/**
+ * The query string asking for a set of orgs. Each id is encoded on its own
+ * before the join, so an id holding the separator survives the split.
+ */
+export declare function staffOrgsAiSpendQuery(orgIds: readonly string[]): string;
+/** The org ids a request names, or why it names none a read should serve. */
+export interface StaffOrgIdsAsk {
+    /** Distinct and in the order asked; empty when the ask is refused. */
+    orgIds: string[];
+    /** Why the ask is refused, or `null` when it is not. */
+    error: string | null;
+}
+/**
+ * The org ids a request names. An empty ask, more than
+ * {@link STAFF_ORGS_AI_SPEND_MAX_IDS} ids, and an id no org document could
+ * have are refused before any of them reaches a read.
+ */
+export declare function parseStaffOrgIds(raw: unknown): StaffOrgIdsAsk;

package/src/lib/usage/staff-orgs-ai-spend.js

@@ -0,0 +1,114 @@
+/**
+ * @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 STAFF ORGANIZATIONS LIST'S AI SPEND COLUMN, AS DATA (AGL-2984).
+ *
+ * The list draws this plugin's column through its `staffOrgsListColumn`
+ * zone: one read of the page's orgs through `/api/ai/admin/orgs-spend`, a
+ * cell per row, and a header that sorts the page by the figures. The parts
+ * all three share live here — the wire, the number a sort compares, the text
+ * a cell shows, and the request's id list — free of React and of the Admin
+ * SDK, so the route, the hook and the specs read one definition.
+ */ /** The most org ids one request may name — past the list's largest page. */ export const STAFF_ORGS_AI_SPEND_MAX_IDS = 100;
+/**
+ * What a sort compares: a NUMBER, or `null` for an unmeasured org. The text
+ * a cell shows would sort `$10.0000` before `$9.0000`.
+ */ export function aiSpendSortValue(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/**
+ * What a cell shows: four decimals, because a month that really cost eight
+ * cents must not read as `$0.00`, and a dash for an unmeasured org — never
+ * `$0`.
+ */ export function aiSpendCell(value) {
+    const spend = aiSpendSortValue(value);
+    return spend === null ? '—' : `$${spend.toFixed(4)}`;
+}
+/**
+ * Two spends in a direction, with the unmeasured LAST in both: an org that
+ * has not touched AI this month belongs at the bottom of a column whose
+ * point is finding the one that has, whichever way it is read.
+ */ function compareAiSpend(a, b, direction) {
+    const left = aiSpendSortValue(a);
+    const right = aiSpendSortValue(b);
+    if (left === null && right === null) return 0;
+    if (left === null) return 1;
+    if (right === null) return -1;
+    return direction === 'desc' ? right - left : left - right;
+}
+/** Dearest first; an unmeasured org last. */ export function byAiSpendDesc(a, b) {
+    return compareAiSpend(a, b, 'desc');
+}
+/** Cheapest first; an unmeasured org still last. */ export function byAiSpendAsc(a, b) {
+    return compareAiSpend(a, b, 'asc');
+}
+/**
+ * The list's rows in a direction by their org's spend — the comparator the
+ * column's header hands the list. A row whose org the answer does not name
+ * reads as unmeasured.
+ */ export function aiSpendRowComparator(spendUsd, direction) {
+    const spendOf = (row)=>{
+        var _ref;
+        return spendUsd[String((_ref = row == null ? void 0 : row.$id) != null ? _ref : '')];
+    };
+    return (a, b)=>compareAiSpend(spendOf(a), spendOf(b), direction);
+}
+/** Between ids in the `orgIds` parameter. */ const ORG_ID_SEPARATOR = ',';
+/**
+ * The query string asking for a set of orgs. Each id is encoded on its own
+ * before the join, so an id holding the separator survives the split.
+ */ export function staffOrgsAiSpendQuery(orgIds) {
+    return new URLSearchParams({
+        orgIds: orgIds.map((orgId)=>encodeURIComponent(orgId)).join(ORG_ID_SEPARATOR)
+    }).toString();
+}
+/** A document id Firestore accepts for an org. */ function isOrgDocumentId(id) {
+    return id.length > 0 && id.length <= 1500 && !id.includes('/') && id !== '.' && id !== '..' && !/^__.*__$/.test(id);
+}
+/**
+ * The org ids a request names. An empty ask, more than
+ * {@link STAFF_ORGS_AI_SPEND_MAX_IDS} ids, and an id no org document could
+ * have are refused before any of them reaches a read.
+ */ export function parseStaffOrgIds(raw) {
+    const refuse = (error)=>({
+            orgIds: [],
+            error
+        });
+    const orgIds = new Set();
+    for (const part of String(raw != null ? raw : '').split(ORG_ID_SEPARATOR)){
+        if (!part) continue;
+        let orgId;
+        try {
+            orgId = decodeURIComponent(part);
+        } catch (unused) {
+            return refuse('Invalid orgIds');
+        }
+        if (!isOrgDocumentId(orgId)) return refuse('Invalid orgIds');
+        orgIds.add(orgId);
+        if (orgIds.size > STAFF_ORGS_AI_SPEND_MAX_IDS) {
+            return refuse(`At most ${STAFF_ORGS_AI_SPEND_MAX_IDS} orgIds`);
+        }
+    }
+    if (orgIds.size === 0) return refuse('Missing orgIds');
+    return {
+        orgIds: [
+            ...orgIds
+        ],
+        error: null
+    };
+}
+
+//# sourceMappingURL=staff-orgs-ai-spend.js.map

package/src/lib/usage/staff-orgs-ai-spend.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/usage/staff-orgs-ai-spend.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 STAFF ORGANIZATIONS LIST'S AI SPEND COLUMN, AS DATA (AGL-2984).\n *\n * The list draws this plugin's column through its `staffOrgsListColumn`\n * zone: one read of the page's orgs through `/api/ai/admin/orgs-spend`, a\n * cell per row, and a header that sorts the page by the figures. The parts\n * all three share live here — the wire, the number a sort compares, the text\n * a cell shows, and the request's id list — free of React and of the Admin\n * SDK, so the route, the hook and the specs read one definition.\n */\n\n/** The most org ids one request may name — past the list's largest page. */\nexport const STAFF_ORGS_AI_SPEND_MAX_IDS = 100\n\n/** What `/api/ai/admin/orgs-spend` answers. */\nexport interface StaffOrgsAiSpendWire {\n  /** The month the figures describe, `YYYY-MM` in UTC. */\n  month: string\n  /**\n   * This month's provider spend in USD, by org id. `null` where the org has\n   * no usage document for the month or the read failed, never `0`: \"spent\n   * nothing\" and \"not measured\" stay distinct, and the column exists to find\n   * the org that IS spending.\n   */\n  spendUsd: Record<string, number | null>\n}\n\n/**\n * What a sort compares: a NUMBER, or `null` for an unmeasured org. The text\n * a cell shows would sort `$10.0000` before `$9.0000`.\n */\nexport function aiSpendSortValue(value: unknown): number | null {\n  return typeof value === 'number' && Number.isFinite(value) ? value : null\n}\n\n/**\n * What a cell shows: four decimals, because a month that really cost eight\n * cents must not read as `$0.00`, and a dash for an unmeasured org — never\n * `$0`.\n */\nexport function aiSpendCell(value: unknown): string {\n  const spend = aiSpendSortValue(value)\n  return spend === null ? '—' : `$${spend.toFixed(4)}`\n}\n\n/**\n * Two spends in a direction, with the unmeasured LAST in both: an org that\n * has not touched AI this month belongs at the bottom of a column whose\n * point is finding the one that has, whichever way it is read.\n */\nfunction compareAiSpend(\n  a: unknown,\n  b: unknown,\n  direction: 'asc' | 'desc',\n): number {\n  const left = aiSpendSortValue(a)\n  const right = aiSpendSortValue(b)\n  if (left === null && right === null) return 0\n  if (left === null) return 1\n  if (right === null) return -1\n  return direction === 'desc' ? right - left : left - right\n}\n\n/** Dearest first; an unmeasured org last. */\nexport function byAiSpendDesc(a: unknown, b: unknown): number {\n  return compareAiSpend(a, b, 'desc')\n}\n\n/** Cheapest first; an unmeasured org still last. */\nexport function byAiSpendAsc(a: unknown, b: unknown): number {\n  return compareAiSpend(a, b, 'asc')\n}\n\n/**\n * The list's rows in a direction by their org's spend — the comparator the\n * column's header hands the list. A row whose org the answer does not name\n * reads as unmeasured.\n */\nexport function aiSpendRowComparator(\n  spendUsd: Readonly<Record<string, number | null>>,\n  direction: 'asc' | 'desc',\n): (a: { $id?: unknown }, b: { $id?: unknown }) => number {\n  const spendOf = (row: { $id?: unknown }) => spendUsd[String(row?.$id ?? '')]\n  return (a, b) => compareAiSpend(spendOf(a), spendOf(b), direction)\n}\n\n/** Between ids in the `orgIds` parameter. */\nconst ORG_ID_SEPARATOR = ','\n\n/**\n * The query string asking for a set of orgs. Each id is encoded on its own\n * before the join, so an id holding the separator survives the split.\n */\nexport function staffOrgsAiSpendQuery(orgIds: readonly string[]): string {\n  return new URLSearchParams({\n    orgIds: orgIds\n      .map((orgId) => encodeURIComponent(orgId))\n      .join(ORG_ID_SEPARATOR),\n  }).toString()\n}\n\n/** A document id Firestore accepts for an org. */\nfunction isOrgDocumentId(id: string): boolean {\n  return (\n    id.length > 0 &&\n    id.length <= 1500 &&\n    !id.includes('/') &&\n    id !== '.' &&\n    id !== '..' &&\n    !/^__.*__$/.test(id)\n  )\n}\n\n/** The org ids a request names, or why it names none a read should serve. */\nexport interface StaffOrgIdsAsk {\n  /** Distinct and in the order asked; empty when the ask is refused. */\n  orgIds: string[]\n  /** Why the ask is refused, or `null` when it is not. */\n  error: string | null\n}\n\n/**\n * The org ids a request names. An empty ask, more than\n * {@link STAFF_ORGS_AI_SPEND_MAX_IDS} ids, and an id no org document could\n * have are refused before any of them reaches a read.\n */\nexport function parseStaffOrgIds(raw: unknown): StaffOrgIdsAsk {\n  const refuse = (error: string): StaffOrgIdsAsk => ({ orgIds: [], error })\n  const orgIds = new Set<string>()\n  for (const part of String(raw ?? '').split(ORG_ID_SEPARATOR)) {\n    if (!part) continue\n    let orgId: string\n    try {\n      orgId = decodeURIComponent(part)\n    } catch {\n      return refuse('Invalid orgIds')\n    }\n    if (!isOrgDocumentId(orgId)) return refuse('Invalid orgIds')\n    orgIds.add(orgId)\n    if (orgIds.size > STAFF_ORGS_AI_SPEND_MAX_IDS) {\n      return refuse(`At most ${STAFF_ORGS_AI_SPEND_MAX_IDS} orgIds`)\n    }\n  }\n  if (orgIds.size === 0) return refuse('Missing orgIds')\n  return { orgIds: [...orgIds], error: null }\n}\n"],"names":["STAFF_ORGS_AI_SPEND_MAX_IDS","aiSpendSortValue","value","Number","isFinite","aiSpendCell","spend","toFixed","compareAiSpend","a","b","direction","left","right","byAiSpendDesc","byAiSpendAsc","aiSpendRowComparator","spendUsd","spendOf","row","String","$id","ORG_ID_SEPARATOR","staffOrgsAiSpendQuery","orgIds","URLSearchParams","map","orgId","encodeURIComponent","join","toString","isOrgDocumentId","id","length","includes","test","parseStaffOrgIds","raw","refuse","error","Set","part","split","decodeURIComponent","add","size"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;CASC,GAED,0EAA0E,GAC1E,OAAO,MAAMA,8BAA8B,IAAG;AAe9C;;;CAGC,GACD,OAAO,SAASC,iBAAiBC,KAAc;IAC7C,OAAO,OAAOA,UAAU,YAAYC,OAAOC,QAAQ,CAACF,SAASA,QAAQ;AACvE;AAEA;;;;CAIC,GACD,OAAO,SAASG,YAAYH,KAAc;IACxC,MAAMI,QAAQL,iBAAiBC;IAC/B,OAAOI,UAAU,OAAO,MAAM,CAAC,CAAC,EAAEA,MAAMC,OAAO,CAAC,IAAI;AACtD;AAEA;;;;CAIC,GACD,SAASC,eACPC,CAAU,EACVC,CAAU,EACVC,SAAyB;IAEzB,MAAMC,OAAOX,iBAAiBQ;IAC9B,MAAMI,QAAQZ,iBAAiBS;IAC/B,IAAIE,SAAS,QAAQC,UAAU,MAAM,OAAO;IAC5C,IAAID,SAAS,MAAM,OAAO;IAC1B,IAAIC,UAAU,MAAM,OAAO,CAAC;IAC5B,OAAOF,cAAc,SAASE,QAAQD,OAAOA,OAAOC;AACtD;AAEA,2CAA2C,GAC3C,OAAO,SAASC,cAAcL,CAAU,EAAEC,CAAU;IAClD,OAAOF,eAAeC,GAAGC,GAAG;AAC9B;AAEA,kDAAkD,GAClD,OAAO,SAASK,aAAaN,CAAU,EAAEC,CAAU;IACjD,OAAOF,eAAeC,GAAGC,GAAG;AAC9B;AAEA;;;;CAIC,GACD,OAAO,SAASM,qBACdC,QAAiD,EACjDN,SAAyB;IAEzB,MAAMO,UAAU,CAACC;;eAA2BF,QAAQ,CAACG,eAAOD,uBAAAA,IAAKE,GAAG,mBAAI,IAAI;;IAC5E,OAAO,CAACZ,GAAGC,IAAMF,eAAeU,QAAQT,IAAIS,QAAQR,IAAIC;AAC1D;AAEA,2CAA2C,GAC3C,MAAMW,mBAAmB;AAEzB;;;CAGC,GACD,OAAO,SAASC,sBAAsBC,MAAyB;IAC7D,OAAO,IAAIC,gBAAgB;QACzBD,QAAQA,OACLE,GAAG,CAAC,CAACC,QAAUC,mBAAmBD,QAClCE,IAAI,CAACP;IACV,GAAGQ,QAAQ;AACb;AAEA,gDAAgD,GAChD,SAASC,gBAAgBC,EAAU;IACjC,OACEA,GAAGC,MAAM,GAAG,KACZD,GAAGC,MAAM,IAAI,QACb,CAACD,GAAGE,QAAQ,CAAC,QACbF,OAAO,OACPA,OAAO,QACP,CAAC,WAAWG,IAAI,CAACH;AAErB;AAUA;;;;CAIC,GACD,OAAO,SAASI,iBAAiBC,GAAY;IAC3C,MAAMC,SAAS,CAACC,QAAmC,CAAA;YAAEf,QAAQ,EAAE;YAAEe;QAAM,CAAA;IACvE,MAAMf,SAAS,IAAIgB;IACnB,KAAK,MAAMC,QAAQrB,OAAOiB,cAAAA,MAAO,IAAIK,KAAK,CAACpB,kBAAmB;QAC5D,IAAI,CAACmB,MAAM;QACX,IAAId;QACJ,IAAI;YACFA,QAAQgB,mBAAmBF;QAC7B,EAAE,eAAM;YACN,OAAOH,OAAO;QAChB;QACA,IAAI,CAACP,gBAAgBJ,QAAQ,OAAOW,OAAO;QAC3Cd,OAAOoB,GAAG,CAACjB;QACX,IAAIH,OAAOqB,IAAI,GAAG7C,6BAA6B;YAC7C,OAAOsC,OAAO,CAAC,QAAQ,EAAEtC,4BAA4B,OAAO,CAAC;QAC/D;IACF;IACA,IAAIwB,OAAOqB,IAAI,KAAK,GAAG,OAAOP,OAAO;IACrC,OAAO;QAAEd,QAAQ;eAAIA;SAAO;QAAEe,OAAO;IAAK;AAC5C"}