@agent-finops/core 0.6.0 → 0.7.0

package/dist/providerConnectors.d.ts

@@ -20,6 +20,15 @@ export type ProviderQaPagination = {
     note?: string;
 };
 export type ProviderCoverageStatus = "complete" | "partial";
+/**
+ * Exact provider interval requested by a sync. It is intentionally absent
+ * when the caller leaves the end open: a successful narrow/open-ended read
+ * must never be promoted into an assumed 30-day coverage claim.
+ */
+export type ProviderCoverageInterval = {
+    coverageStart: string;
+    coverageEnd: string;
+};
 export type ProviderFinancialSummary = {
     providerReportedBilledUsd: number | null;
     apiEquivalentEstimatedUsd: number | null;
@@ -65,6 +74,7 @@ export type ProviderConnectorResult = {
     records: UsageRecord[];
     fetchedAt: string;
     coverage: ProviderCoverageStatus;
+    coverageInterval?: ProviderCoverageInterval;
     financials: ProviderFinancialSummary;
     completeness: "verified" | "estimated" | "detected_unverified" | "missing";
     qa: ProviderQaSummary;

package/dist/providerConnectors.js

@@ -314,6 +314,12 @@ export function normalizeCursorSpendResponse(response, options) {
     });
 }
 export async function fetchProviderUsageRecords(input) {
+    // Validate explicit bounds before resolving a credential or making a request.
+    // The interval-aware OpenAI/Anthropic result paths call the same pure helper
+    // to attach normalized bounds only after a successful fetch. Copilot and
+    // Cursor do not currently constrain their reads to these requested bounds,
+    // so they deliberately return no coverage interval.
+    requestedCoverageInterval(input);
     const token = (input.tokenResolver ?? defaultTokenResolver)(input.authReference);
     const fetcher = input.fetcher ?? defaultFetcher;
     const sourceId = input.sourceId ?? `${input.provider}-provider-api`;
@@ -400,7 +406,7 @@ async function fetchOpenAi(input, token, fetcher, sourceId) {
         ...costFetch.pages.flatMap((page) => normalizeOpenAiCostResponse(page, { sourceId, observedFrom: "OpenAI organization costs API" })),
         ...usageFetch.pages.flatMap((page) => normalizeOpenAiUsageResponse(page, { sourceId, observedFrom: "OpenAI organization usage API" }))
     ];
-    return providerResult("openai", sourceId, input.authReference, records, qaSummary("openai", [costFetch, usageFetch]));
+    return providerResult("openai", sourceId, input.authReference, records, qaSummary("openai", [costFetch, usageFetch]), requestedCoverageInterval(input));
 }
 async function fetchAnthropic(input, token, fetcher, sourceId) {
     const costRequest = {
@@ -417,7 +423,7 @@ async function fetchAnthropic(input, token, fetcher, sourceId) {
         ...costFetch.pages.flatMap((page) => normalizeAnthropicCostResponse(page, { sourceId, observedFrom: "Anthropic Admin Cost Report" })),
         ...claudeCodeFetches.flatMap((fetchResult) => fetchResult.pages.flatMap((page) => normalizeAnthropicClaudeCodeUsageResponse(page, { sourceId, observedFrom: "Anthropic Claude Code Usage Report", accountId: input.accountId })))
     ];
-    return providerResult("anthropic", sourceId, input.authReference, records, qaSummary("anthropic", [costFetch, ...claudeCodeFetches]));
+    return providerResult("anthropic", sourceId, input.authReference, records, qaSummary("anthropic", [costFetch, ...claudeCodeFetches]), requestedCoverageInterval(input));
 }
 async function fetchGitHubCopilot(input, token, fetcher, sourceId) {
     const accountId = input.org ?? input.enterprise;
@@ -1257,7 +1263,7 @@ function sumAmounts(records) {
         .filter((amount) => typeof amount === "number");
     return amounts.length > 0 ? amounts.reduce((sum, amount) => sum + amount, 0) : null;
 }
-function providerResult(provider, sourceId, authReference, records, qa) {
+function providerResult(provider, sourceId, authReference, records, qa, coverageInterval) {
     const resolvedQa = qa ?? qaSummary(provider, []);
     const coverage = resolvedQa.coverage
         ?? (resolvedQa.pagination.every((pagination) => pagination.stoppedBecause === "complete") ? "complete" : "partial");
@@ -1276,11 +1282,42 @@ function providerResult(provider, sourceId, authReference, records, qa) {
         records,
         fetchedAt: new Date().toISOString(),
         coverage,
+        ...(coverageInterval ? { coverageInterval } : {}),
         financials,
         completeness,
         qa: resolvedQa
     };
 }
+function requestedCoverageInterval(input) {
+    if (!Number.isFinite(input.startTime) || !Number.isInteger(input.startTime) || input.startTime < 0) {
+        throw new Error("Provider coverage startTime requires a non-negative whole-second timestamp.");
+    }
+    const coverageStart = new Date(input.startTime * 1_000);
+    if (Number.isNaN(coverageStart.getTime())) {
+        throw new Error("Provider coverage interval falls outside the supported timestamp range.");
+    }
+    if (input.endTime === undefined) {
+        if (coverageStart.getTime() > Date.now()) {
+            throw new Error("Provider coverage startTime cannot be in the future.");
+        }
+        return undefined;
+    }
+    if (!Number.isFinite(input.endTime) || !Number.isInteger(input.endTime) ||
+        input.endTime < input.startTime) {
+        throw new Error("Provider coverage interval requires non-negative whole-second bounds with endTime at or after startTime.");
+    }
+    const coverageEnd = new Date(input.endTime * 1_000);
+    if (Number.isNaN(coverageEnd.getTime())) {
+        throw new Error("Provider coverage interval falls outside the supported timestamp range.");
+    }
+    if (coverageEnd.getTime() > Date.now()) {
+        throw new Error("Provider coverage endTime cannot be in the future.");
+    }
+    return {
+        coverageStart: coverageStart.toISOString(),
+        coverageEnd: coverageEnd.toISOString()
+    };
+}
 export function createProviderConnection(input) {
     const source = createProviderConnectorStub(input.provider, "provider_api", input.fetchedAt);
     const total = input.totalUsd === null ? "an unavailable financial headline" : formatProviderUsd(input.totalUsd);
@@ -1328,7 +1365,7 @@ function buildOpenAiCostsUrl(startTime, endTime) {
     url.searchParams.append("group_by", "project_id");
     url.searchParams.append("group_by", "line_item");
     url.searchParams.append("group_by", "api_key_id");
-    if (endTime)
+    if (endTime !== undefined)
         url.searchParams.set("end_time", String(endTime));
     return url.toString();
 }
@@ -1341,14 +1378,14 @@ function buildOpenAiUsageUrl(startTime, endTime) {
     url.searchParams.append("group_by", "user_id");
     url.searchParams.append("group_by", "api_key_id");
     url.searchParams.append("group_by", "model");
-    if (endTime)
+    if (endTime !== undefined)
         url.searchParams.set("end_time", String(endTime));
     return url.toString();
 }
 function buildAnthropicCostUrl(startTime, endTime) {
     const url = new URL("https://api.anthropic.com/v1/organizations/cost_report");
     url.searchParams.set("starting_at", new Date(startTime * 1000).toISOString());
-    if (endTime)
+    if (endTime !== undefined)
         url.searchParams.set("ending_at", new Date(endTime * 1000).toISOString());
     url.searchParams.set("bucket_width", "1d");
     url.searchParams.append("group_by[]", "workspace_id");

package/dist/schema.d.ts

@@ -1,8 +1,8 @@
 import { z } from "zod";
 export declare const costConfidenceValues: readonly ["verified", "estimated", "detected_unverified", "missing"];
 export declare const costConfidenceSchema: z.ZodEnum<{
-    estimated: "estimated";
     verified: "verified";
+    estimated: "estimated";
     detected_unverified: "detected_unverified";
     missing: "missing";
 }>;
@@ -12,8 +12,8 @@ export declare const spendSourceSchema: z.ZodObject<{
     name: z.ZodString;
     provider: z.ZodString;
     confidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -59,8 +59,8 @@ export declare const usageRecordSchema: z.ZodObject<{
         name: z.ZodString;
         provider: z.ZodString;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -71,8 +71,8 @@ export declare const usageRecordSchema: z.ZodObject<{
     outputTokens: z.ZodNumber;
     amountUsd: z.ZodNullable<z.ZodNumber>;
     costConfidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -134,10 +134,10 @@ export declare function downgradeSampleUsageEvidence(records: UsageRecord[]): Us
 export declare function spendComparisonKey(record: UsageRecord): string | undefined;
 export declare const attributionCandidateSchema: z.ZodObject<{
     entityType: z.ZodEnum<{
-        user: "user";
+        client: "client";
         project: "project";
         agent: "agent";
-        client: "client";
+        user: "user";
         workspace: "workspace";
         api_key: "api_key";
     }>;
@@ -150,10 +150,10 @@ export declare const attributionMappingSchema: z.ZodObject<{
     usageRecordId: z.ZodString;
     candidates: z.ZodArray<z.ZodObject<{
         entityType: z.ZodEnum<{
-            user: "user";
+            client: "client";
             project: "project";
             agent: "agent";
-            client: "client";
+            user: "user";
             workspace: "workspace";
             api_key: "api_key";
         }>;
@@ -163,10 +163,10 @@ export declare const attributionMappingSchema: z.ZodObject<{
     }, z.core.$strip>>;
     selected: z.ZodOptional<z.ZodObject<{
         entityType: z.ZodEnum<{
-            user: "user";
+            client: "client";
             project: "project";
             agent: "agent";
-            client: "client";
+            user: "user";
             workspace: "workspace";
             api_key: "api_key";
         }>;
@@ -188,8 +188,8 @@ export declare const spendBreakdownEntrySchema: z.ZodObject<{
     amountUsd: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -206,8 +206,8 @@ export declare const spendAnomalySchema: z.ZodObject<{
     currentAmountUsd: z.ZodNumber;
     multiplier: z.ZodNumber;
     confidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -223,8 +223,8 @@ export declare const workflowWatchEntrySchema: z.ZodObject<{
     shareOfSpend: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -248,8 +248,8 @@ export declare const recommendationSchema: z.ZodObject<{
     }>;
     estimatedImpactUsd: z.ZodNumber;
     confidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -293,8 +293,8 @@ export declare const spendInsightSchema: z.ZodObject<{
     affectedModels: z.ZodArray<z.ZodString>;
     estimatedImpactUsd: z.ZodNumber;
     confidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
@@ -306,14 +306,14 @@ export declare const spendSummarySchema: z.ZodObject<{
     totalUsd: z.ZodNumber;
     recordCount: z.ZodNumber;
     confidence: z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>;
     confidenceBreakdown: z.ZodRecord<z.ZodEnum<{
-        estimated: "estimated";
         verified: "verified";
+        estimated: "estimated";
         detected_unverified: "detected_unverified";
         missing: "missing";
     }>, z.ZodNumber>;
@@ -322,8 +322,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -333,8 +333,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -344,8 +344,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -355,8 +355,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -366,8 +366,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -377,8 +377,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -388,8 +388,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -399,8 +399,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         amountUsd: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -415,8 +415,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         shareOfSpend: z.ZodNumber;
         recordCount: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -437,8 +437,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         currentAmountUsd: z.ZodNumber;
         multiplier: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -456,8 +456,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         }>;
         estimatedImpactUsd: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;
@@ -494,8 +494,8 @@ export declare const spendSummarySchema: z.ZodObject<{
         affectedModels: z.ZodArray<z.ZodString>;
         estimatedImpactUsd: z.ZodNumber;
         confidence: z.ZodEnum<{
-            estimated: "estimated";
             verified: "verified";
+            estimated: "estimated";
             detected_unverified: "detected_unverified";
             missing: "missing";
         }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-finops/core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",