@agent-finops/core 0.9.0 → 0.9.2

package/dist/receiptShare.d.ts

@@ -0,0 +1,185 @@
+import { z } from "zod";
+import { type ResultCard } from "./resultCard.js";
+/**
+ * Post-launch transport groundwork only.
+ *
+ * This module does not upload, send, persist, authenticate, render markup, or
+ * expose a CLI command. It defines the bounded aggregate payload that a future
+ * opt-in receipt route may accept after its own waitlist, durable-rate-limit,
+ * retention, and mail-provider controls exist.
+ */
+export declare const RECEIPT_SHARE_V0_VERSION: "0.1.0";
+export declare const RECEIPT_SHARE_CARD_V0_KIND: "aibill.receipt_share_card";
+export declare const RECEIPT_EMAIL_REQUEST_V0_KIND: "aibill.receipt_email_request";
+export declare const receiptShareCutV0Schema: z.ZodObject<{
+    template: z.ZodEnum<{
+        route_lower_cost_model: "route_lower_cost_model";
+        narrow_context: "narrow_context";
+        cache_repeated_work: "cache_repeated_work";
+        use_batch_api: "use_batch_api";
+    }>;
+    modeledOpportunityUsd: z.ZodNumber;
+    evidence: z.ZodLiteral<"modeled_not_verified">;
+}, z.core.$strict>;
+export declare const receiptShareCardV0Schema: z.ZodObject<{
+    kind: z.ZodLiteral<"aibill.receipt_share_card">;
+    schemaVersion: z.ZodLiteral<"0.1.0">;
+    currency: z.ZodLiteral<"USD">;
+    windowDays: z.ZodNumber;
+    mode: z.ZodEnum<{
+        "local-logs": "local-logs";
+        connected: "connected";
+        mixed: "mixed";
+    }>;
+    financials: z.ZodObject<{
+        subscriptionCommitted: z.ZodObject<{
+            amountUsd: z.ZodNullable<z.ZodNumber>;
+            pricedSubs: z.ZodNumber;
+            totalSubs: z.ZodNumber;
+        }, z.core.$strict>;
+        apiEquivalent: z.ZodObject<{
+            amountUsd: z.ZodNullable<z.ZodNumber>;
+            financialEvidence: z.ZodEnum<{
+                estimated: "estimated";
+                missing: "missing";
+            }>;
+        }, z.core.$strict>;
+        providerBilled: z.ZodObject<{
+            amountUsd: z.ZodNullable<z.ZodNumber>;
+            financialEvidence: z.ZodEnum<{
+                missing: "missing";
+                verified: "verified";
+            }>;
+        }, z.core.$strict>;
+        blended: z.ZodNull;
+        blendPolicy: z.ZodLiteral<"never_blended">;
+    }, z.core.$strict>;
+    providerCount: z.ZodNumber;
+    recordCount: z.ZodNumber;
+    confidence: z.ZodEnum<{
+        estimated: "estimated";
+        missing: "missing";
+        verified: "verified";
+        detected_unverified: "detected_unverified";
+    }>;
+    cuts: z.ZodArray<z.ZodObject<{
+        template: z.ZodEnum<{
+            route_lower_cost_model: "route_lower_cost_model";
+            narrow_context: "narrow_context";
+            cache_repeated_work: "cache_repeated_work";
+            use_batch_api: "use_batch_api";
+        }>;
+        modeledOpportunityUsd: z.ZodNumber;
+        evidence: z.ZodLiteral<"modeled_not_verified">;
+    }, z.core.$strict>>;
+    contentBoundary: z.ZodObject<{
+        rawHistoryIncluded: z.ZodLiteral<false>;
+        localIdentifiersIncluded: z.ZodLiteral<false>;
+        clientMarkupIncluded: z.ZodLiteral<false>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const receiptEmailRequestV0Schema: z.ZodObject<{
+    kind: z.ZodLiteral<"aibill.receipt_email_request">;
+    schemaVersion: z.ZodLiteral<"0.1.0">;
+    recipientEmail: z.ZodString;
+    consent: z.ZodLiteral<"email_and_aggregate_card_via_mail_provider">;
+    card: z.ZodObject<{
+        kind: z.ZodLiteral<"aibill.receipt_share_card">;
+        schemaVersion: z.ZodLiteral<"0.1.0">;
+        currency: z.ZodLiteral<"USD">;
+        windowDays: z.ZodNumber;
+        mode: z.ZodEnum<{
+            "local-logs": "local-logs";
+            connected: "connected";
+            mixed: "mixed";
+        }>;
+        financials: z.ZodObject<{
+            subscriptionCommitted: z.ZodObject<{
+                amountUsd: z.ZodNullable<z.ZodNumber>;
+                pricedSubs: z.ZodNumber;
+                totalSubs: z.ZodNumber;
+            }, z.core.$strict>;
+            apiEquivalent: z.ZodObject<{
+                amountUsd: z.ZodNullable<z.ZodNumber>;
+                financialEvidence: z.ZodEnum<{
+                    estimated: "estimated";
+                    missing: "missing";
+                }>;
+            }, z.core.$strict>;
+            providerBilled: z.ZodObject<{
+                amountUsd: z.ZodNullable<z.ZodNumber>;
+                financialEvidence: z.ZodEnum<{
+                    missing: "missing";
+                    verified: "verified";
+                }>;
+            }, z.core.$strict>;
+            blended: z.ZodNull;
+            blendPolicy: z.ZodLiteral<"never_blended">;
+        }, z.core.$strict>;
+        providerCount: z.ZodNumber;
+        recordCount: z.ZodNumber;
+        confidence: z.ZodEnum<{
+            estimated: "estimated";
+            missing: "missing";
+            verified: "verified";
+            detected_unverified: "detected_unverified";
+        }>;
+        cuts: z.ZodArray<z.ZodObject<{
+            template: z.ZodEnum<{
+                route_lower_cost_model: "route_lower_cost_model";
+                narrow_context: "narrow_context";
+                cache_repeated_work: "cache_repeated_work";
+                use_batch_api: "use_batch_api";
+            }>;
+            modeledOpportunityUsd: z.ZodNumber;
+            evidence: z.ZodLiteral<"modeled_not_verified">;
+        }, z.core.$strict>>;
+        contentBoundary: z.ZodObject<{
+            rawHistoryIncluded: z.ZodLiteral<false>;
+            localIdentifiersIncluded: z.ZodLiteral<false>;
+            clientMarkupIncluded: z.ZodLiteral<false>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ReceiptShareCutV0 = z.infer<typeof receiptShareCutV0Schema>;
+export type ReceiptShareCardV0 = z.infer<typeof receiptShareCardV0Schema>;
+export type ReceiptEmailRequestV0 = z.infer<typeof receiptEmailRequestV0Schema>;
+export type BuildReceiptShareCardV0Input = {
+    resultCard: ResultCard;
+    providerCount: number;
+    recordCount: number;
+    confidence: ReceiptShareCardV0["confidence"];
+    cuts: ReceiptShareCutV0[];
+};
+/**
+ * Projects the canonical local result card into a smaller aggregate-only
+ * transport card. Subscription labels, project rows, runways, record IDs,
+ * source metadata, prompts, paths, and raw history are intentionally omitted.
+ */
+export declare function buildReceiptShareCardV0(input: BuildReceiptShareCardV0Input): ReceiptShareCardV0;
+export declare const RECEIPT_EMAIL_MAX_SENDS_PER_EMAIL_24H: 1;
+export declare const RECEIPT_EMAIL_MAX_SENDS_PER_IP_24H: 10;
+declare const receiptEmailDeliveryStateV0Schema: z.ZodObject<{
+    waitlistMember: z.ZodBoolean;
+    emailSendsLast24Hours: z.ZodNumber;
+    ipSendsLast24Hours: z.ZodNumber;
+}, z.core.$strict>;
+export type ReceiptEmailDeliveryDecisionV0 = {
+    status: "join_first";
+    httpStatus: 403;
+} | {
+    status: "rate_limited";
+    httpStatus: 429;
+    scope: "email" | "ip";
+} | {
+    status: "accepted";
+    httpStatus: 202;
+};
+/**
+ * Pure authorization policy for a future route. Counters must come from a
+ * durable shared store; this function creates no in-memory limiter and has no
+ * persistence or network side effects.
+ */
+export declare function decideReceiptEmailDeliveryV0(state: z.input<typeof receiptEmailDeliveryStateV0Schema>): ReceiptEmailDeliveryDecisionV0;
+export {};
+//# sourceMappingURL=receiptShare.d.ts.map

package/dist/receiptShare.js

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import { resultCardSchema, resultCardTotalsSchema } from "./resultCard.js";
+/**
+ * Post-launch transport groundwork only.
+ *
+ * This module does not upload, send, persist, authenticate, render markup, or
+ * expose a CLI command. It defines the bounded aggregate payload that a future
+ * opt-in receipt route may accept after its own waitlist, durable-rate-limit,
+ * retention, and mail-provider controls exist.
+ */
+export const RECEIPT_SHARE_V0_VERSION = "0.1.0";
+export const RECEIPT_SHARE_CARD_V0_KIND = "aibill.receipt_share_card";
+export const RECEIPT_EMAIL_REQUEST_V0_KIND = "aibill.receipt_email_request";
+const boundedUsdSchema = z.number().finite().nonnegative().max(1_000_000_000);
+export const receiptShareCutV0Schema = z.object({
+    template: z.enum([
+        "route_lower_cost_model",
+        "narrow_context",
+        "cache_repeated_work",
+        "use_batch_api"
+    ]),
+    modeledOpportunityUsd: boundedUsdSchema.positive(),
+    evidence: z.literal("modeled_not_verified")
+}).strict();
+export const receiptShareCardV0Schema = z.object({
+    kind: z.literal(RECEIPT_SHARE_CARD_V0_KIND),
+    schemaVersion: z.literal(RECEIPT_SHARE_V0_VERSION),
+    currency: z.literal("USD"),
+    windowDays: z.number().int().min(1).max(365),
+    // Demo/sample payloads are intentionally ineligible for real delivery.
+    mode: z.enum(["local-logs", "connected", "mixed"]),
+    /** Canonical three-basis stack, including blended:null/never_blended. */
+    financials: resultCardTotalsSchema,
+    providerCount: z.number().int().positive().max(64),
+    recordCount: z.number().int().positive().max(1_000_000),
+    confidence: z.enum(["verified", "estimated", "detected_unverified", "missing"]),
+    /** Fixed templates only: no client-provided title, model, operation, or markup. */
+    cuts: z.array(receiptShareCutV0Schema).max(3),
+    contentBoundary: z.object({
+        rawHistoryIncluded: z.literal(false),
+        localIdentifiersIncluded: z.literal(false),
+        clientMarkupIncluded: z.literal(false)
+    }).strict()
+}).strict().superRefine((card, context) => {
+    if (card.providerCount > card.recordCount) {
+        context.addIssue({
+            code: "custom",
+            path: ["providerCount"],
+            message: "Provider count cannot exceed aggregate record count."
+        });
+    }
+});
+// Deliberately ASCII and single-line. The future route must additionally use
+// the already-waitlisted normalized address as its authorization identity.
+const receiptRecipientEmailV0Schema = z.string()
+    .trim()
+    .toLowerCase()
+    .min(3)
+    .max(254)
+    .regex(/^[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/u);
+export const receiptEmailRequestV0Schema = z.object({
+    kind: z.literal(RECEIPT_EMAIL_REQUEST_V0_KIND),
+    schemaVersion: z.literal(RECEIPT_SHARE_V0_VERSION),
+    recipientEmail: receiptRecipientEmailV0Schema,
+    /** Names both pieces of data and the third-party transit boundary. */
+    consent: z.literal("email_and_aggregate_card_via_mail_provider"),
+    card: receiptShareCardV0Schema
+}).strict();
+/**
+ * Projects the canonical local result card into a smaller aggregate-only
+ * transport card. Subscription labels, project rows, runways, record IDs,
+ * source metadata, prompts, paths, and raw history are intentionally omitted.
+ */
+export function buildReceiptShareCardV0(input) {
+    const resultCard = resultCardSchema.parse(input.resultCard);
+    return receiptShareCardV0Schema.parse({
+        kind: RECEIPT_SHARE_CARD_V0_KIND,
+        schemaVersion: RECEIPT_SHARE_V0_VERSION,
+        currency: "USD",
+        windowDays: resultCard.windowDays,
+        mode: resultCard.mode,
+        financials: resultCard.totals,
+        providerCount: input.providerCount,
+        recordCount: input.recordCount,
+        confidence: input.confidence,
+        cuts: input.cuts,
+        contentBoundary: {
+            rawHistoryIncluded: false,
+            localIdentifiersIncluded: false,
+            clientMarkupIncluded: false
+        }
+    });
+}
+export const RECEIPT_EMAIL_MAX_SENDS_PER_EMAIL_24H = 1;
+export const RECEIPT_EMAIL_MAX_SENDS_PER_IP_24H = 10;
+const receiptEmailDeliveryStateV0Schema = z.object({
+    waitlistMember: z.boolean(),
+    emailSendsLast24Hours: z.number().int().nonnegative().max(1_000_000),
+    ipSendsLast24Hours: z.number().int().nonnegative().max(1_000_000)
+}).strict();
+/**
+ * Pure authorization policy for a future route. Counters must come from a
+ * durable shared store; this function creates no in-memory limiter and has no
+ * persistence or network side effects.
+ */
+export function decideReceiptEmailDeliveryV0(state) {
+    const parsed = receiptEmailDeliveryStateV0Schema.parse(state);
+    if (!parsed.waitlistMember)
+        return { status: "join_first", httpStatus: 403 };
+    if (parsed.emailSendsLast24Hours >= RECEIPT_EMAIL_MAX_SENDS_PER_EMAIL_24H) {
+        return { status: "rate_limited", httpStatus: 429, scope: "email" };
+    }
+    if (parsed.ipSendsLast24Hours >= RECEIPT_EMAIL_MAX_SENDS_PER_IP_24H) {
+        return { status: "rate_limited", httpStatus: 429, scope: "ip" };
+    }
+    return { status: "accepted", httpStatus: 202 };
+}
+//# sourceMappingURL=receiptShare.js.map

package/dist/runtimeCommands.d.ts

@@ -18,4 +18,19 @@ export declare const AIBILL_IMPROVE_DELIVERY_V0: AibillImproveDeliveryV0;
 export declare function aibillCommandV0(args: string, delivery?: AibillImproveDeliveryV0): string;
 /** One privacy-safe command shared by terminal, MCP, and Glance. */
 export declare function aibillImproveCommandV0(delivery?: AibillImproveDeliveryV0): string;
+/**
+ * Version-pinned command for machine-composed lines (M4c): a command an AI
+ * client relays to a human must be reproducible and must not silently
+ * resolve to a different release, so `draft_improve_command` pins to the
+ * composing package's own version (`npx aibill@<version> …`). A version
+ * that is not a plain semver falls back to the unpinned published command
+ * rather than composing an unrunnable line. In source-preview builds the
+ * checkout command needs no pin.
+ *
+ * Release gate (n2): the coordinated release must also prove the pinned
+ * version EXISTS on the public registry and supports the composed flags —
+ * the packed-install gate described on AIBILL_IMPROVE_DELIVERY_V0 is the
+ * natural home for that check; QA 24 asserts only that the pin is present.
+ */
+export declare function aibillPinnedCommandV0(args: string, version: string, delivery?: AibillImproveDeliveryV0): string;
 //# sourceMappingURL=runtimeCommands.d.ts.map

package/dist/runtimeCommands.js

@@ -24,4 +24,27 @@ export function aibillCommandV0(args, delivery = AIBILL_IMPROVE_DELIVERY_V0) {
 export function aibillImproveCommandV0(delivery = AIBILL_IMPROVE_DELIVERY_V0) {
     return aibillCommandV0(delivery === "source_preview" ? "improve --path ." : "improve", delivery);
 }
+/** Published semver shape a composed pin must have (charset-safe by regex). */
+const pinnableVersionPattern = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+/**
+ * Version-pinned command for machine-composed lines (M4c): a command an AI
+ * client relays to a human must be reproducible and must not silently
+ * resolve to a different release, so `draft_improve_command` pins to the
+ * composing package's own version (`npx aibill@<version> …`). A version
+ * that is not a plain semver falls back to the unpinned published command
+ * rather than composing an unrunnable line. In source-preview builds the
+ * checkout command needs no pin.
+ *
+ * Release gate (n2): the coordinated release must also prove the pinned
+ * version EXISTS on the public registry and supports the composed flags —
+ * the packed-install gate described on AIBILL_IMPROVE_DELIVERY_V0 is the
+ * natural home for that check; QA 24 asserts only that the pin is present.
+ */
+export function aibillPinnedCommandV0(args, version, delivery = AIBILL_IMPROVE_DELIVERY_V0) {
+    const commandArgs = args.trim();
+    if (delivery === "source_preview" || !pinnableVersionPattern.test(version)) {
+        return aibillCommandV0(commandArgs, delivery);
+    }
+    return `npx aibill@${version}${commandArgs.length > 0 ? ` ${commandArgs}` : ""}`;
+}
 //# sourceMappingURL=runtimeCommands.js.map

package/dist/schema.d.ts

@@ -18,6 +18,7 @@ export declare const spendSourceSchema: z.ZodObject<{
         missing: "missing";
     }>;
     observedFrom: z.ZodString;
+    account: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type SpendSource = z.infer<typeof spendSourceSchema>;
 /**
@@ -65,6 +66,7 @@ export declare const usageRecordSchema: z.ZodObject<{
             missing: "missing";
         }>;
         observedFrom: z.ZodString;
+        account: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     model: z.ZodString;
     inputTokens: z.ZodNumber;

package/dist/schema.js

@@ -11,7 +11,15 @@ export const spendSourceSchema = z.object({
     name: z.string().min(1),
     provider: z.string().min(1),
     confidence: costConfidenceSchema,
-    observedFrom: z.string().min(1)
+    observedFrom: z.string().min(1),
+    /**
+     * Stable per-account identity within one provider (an organization, team,
+     * or enterprise slice). Derived from the user-chosen credential reference
+     * or an explicit --org/--enterprise/--account-id flag — never from secret
+     * material. Absent on local-agent records and on provider records synced
+     * before multi-account support (treated as one unnamed legacy slice).
+     */
+    account: z.string().min(1).optional()
 });
 /**
  * What one normalized usage record represents.

package/dist/sourceRegistry.js

@@ -62,10 +62,17 @@ export const providerCatalog = [
         label: "GitHub Copilot",
         preferredSourceType: "provider_api",
         preferredAccessMethod: "api",
-        verifiedFields: ["Copilot usage metrics", "seat assignments and reported plan types"],
+        // AI-credit billing (gross/discount/net) is implemented and shipped;
+        // billed dollars stay estimated until an AI_SPEND_COPILOT_RECONCILE_*
+        // reconciliation matches the billing page figure. Legacy premium-request
+        // billing is deliberately never fetched.
+        verifiedFields: [
+            "Copilot usage metrics",
+            "seat assignments and reported plan types",
+            "AI-credit gross, discount, and net billing usage report"
+        ],
         missingFields: [
             "GitHub admin token reference and organization or enterprise slug",
-            "AI-credit gross, discount, and net billing",
             "license invoice settlement"
         ]
     },
@@ -177,7 +184,7 @@ export const providerConnectorCatalog = [
         fallbackAuthModes: [],
         scopes: ["fine-grained Administration: read", "organization or enterprise billing access"],
         tokenStorage: "local_reference_only",
-        setupHint: "Use a local env reference to a GitHub token with read-only organization or enterprise Copilot metrics and seat access; AI-credit billing is not implemented."
+        setupHint: "Use a local env reference to a GitHub token with read-only organization or enterprise Copilot metrics, seat, and AI-credit billing usage access; billed AI-credit dollars stay estimated until an AI_SPEND_COPILOT_RECONCILE_* reconciliation matches the billing page figure."
     },
     {
         provider: "cursor",

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@agent-finops/core",
-  "version": "0.9.0",
+  "version": "0.9.2",
+  "funding": "https://asktilden.com",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",