@agent-finops/core 0.6.0 → 0.6.1

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/package.json

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