@gdrl/kronos-lib 0.1.3 → 0.1.6

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { K as KronosClientConfig, I as IngestResponse, a as IngestStatusResponse, C as CreateMCPServerResponse, L as ListMCPServersResponse, G as GetMCPServerResponse, b as ConnectMCPServerResponse, R as RotateMCPServerTokenResponse, M as MemoryStatsResponse, c as CostSummaryResponse, S as ScratchsheetResponse, d as ListScopesResponse, e as GetScopeResponse, f as ScopeSpec, g as CreateScopeResponse, U as UpdateScopeResponse, h as ListTriggersResponse, i as CreateTriggerRequest, j as CreateTriggerResponse, T as TriggerRecord, k as UpdateTriggerRequest, l as UpdateTriggerResponse, D as DeleteTriggerResponse, m as CreateFrontendTokenResponse, n as SkillManageParams, o as SkillManageResponse, p as ContextGraphSummaryResponse, q as ContextGraphReadResponse } from './types-CPHJocLg.mjs';
-export { y as ConnectMCPServerRequest, Z as ContextGraphProcedureSummary, H as CreateFrontendTokenRequest, u as CreateMCPServerRequest, E as CreateScopeRequest, s as IngestMemoryDisposition, t as IngestRequest, r as IngestStatus, x as MCPServerDetails, v as MCPServerStatus, w as MCPServerToolCapabilities, O as OnTriggered, z as RotateMCPServerTokenRequest, B as ScopeDetail, A as ScopeSummary, P as SkillFileContentMode, Q as SkillFileInput, V as SkillFileRecord, J as SkillFileType, X as SkillMetadataRecord, N as SkillReadMode, Y as SkillSummaryRecord, W as SkillTreeNode, F as TriggerType } from './types-CPHJocLg.mjs';
+import { K as KronosClientConfig, I as IngestResponse, a as IngestStatusResponse, C as CreateMCPServerResponse, L as ListMCPServersResponse, G as GetMCPServerResponse, b as ConnectMCPServerResponse, R as RotateMCPServerTokenResponse, M as MemoryStatsResponse, c as CostSummaryResponse, d as CostBreakdownResponse, e as GetBillingUsageWebhookResponse, f as ConfigureBillingUsageWebhookResponse, D as DeleteBillingUsageWebhookResponse, S as ScratchsheetResponse, g as ListScopesResponse, h as GetScopeResponse, i as ScopeSpec, j as CreateScopeResponse, U as UpdateScopeResponse, k as ListTriggersResponse, l as CreateTriggerRequest, m as CreateTriggerResponse, T as TriggerRecord, n as UpdateTriggerRequest, o as UpdateTriggerResponse, p as DeleteTriggerResponse, q as CreateFrontendTokenResponse, r as SkillManageParams, s as SkillManageResponse, t as ContextGraphSummaryResponse, u as ContextGraphReadResponse, B as BillingUsageWebhookEvent } from './types-CTMNKYHj.mjs';
+export { N as BillingUsageWebhookEventData, O as ConfigureBillingUsageWebhookRequest, F as ConnectMCPServerRequest, a5 as ContextGraphProcedureSummary, J as CostBreakdownPoint, Y as CreateFrontendTokenRequest, y as CreateMCPServerRequest, V as CreateScopeRequest, w as IngestMemoryDisposition, x as IngestRequest, v as IngestStatus, E as MCPServerDetails, z as MCPServerStatus, A as MCPServerToolCapabilities, X as OnTriggered, H as RotateMCPServerTokenRequest, Q as ScopeDetail, P as ScopeSummary, $ as SkillFileContentMode, a0 as SkillFileInput, a1 as SkillFileRecord, Z as SkillFileType, a3 as SkillMetadataRecord, _ as SkillReadMode, a4 as SkillSummaryRecord, a2 as SkillTreeNode, W as TriggerType } from './types-CTMNKYHj.mjs';
 
 declare class KronosClient {
     private readonly workerUrl;
@@ -102,6 +102,45 @@ declare class KronosClient {
     getCostSummary(params?: {
         tenant_user_id?: string;
     }): Promise<CostSummaryResponse>;
+    /**
+     * Get daily AI stage cost totals for the app, or for a single user if specified.
+     */
+    getCostBreakdown(params?: {
+        tenant_user_id?: string;
+        days?: number;
+    }): Promise<CostBreakdownResponse>;
+    /**
+     * Get the app-level billing usage webhook configuration.
+     */
+    getBillingUsageWebhook(): Promise<GetBillingUsageWebhookResponse>;
+    /**
+     * Configure the app-level billing usage webhook.
+     */
+    configureBillingUsageWebhook(params: {
+        webhook_url: string;
+        webhook_secret: string;
+        event_types?: Array<'billing.usage.updated'>;
+        status?: 'active' | 'disabled';
+    }): Promise<ConfigureBillingUsageWebhookResponse>;
+    /**
+     * Delete the app-level billing usage webhook configuration.
+     */
+    deleteBillingUsageWebhook(): Promise<DeleteBillingUsageWebhookResponse>;
+    /**
+     * Verify an incoming billing usage webhook against the stored app webhook secret.
+     */
+    verifyBillingUsageWebhook(params: {
+        payload: string;
+        signature: string;
+        timestamp: string;
+    }): Promise<boolean>;
+    /**
+     * Verify an incoming Kronos webhook request and optionally validate its payload shape.
+     */
+    verifyWebhook<T = unknown>(request: Request, options?: {
+        expectedEventType?: string;
+        validate?: (payload: unknown) => payload is T;
+    }): Promise<T>;
     /**
      * Read the current scratchsheet document for a user.
      */
@@ -276,6 +315,29 @@ declare function generateIdempotencyKey(): string;
  * Webhook verification utilities for Kronos triggers
  * Provides secure constant-time comparison for webhook secrets
  */
+declare const KRONOS_WEBHOOK_SIGNATURE_HEADER = "x-kronos-signature";
+declare const KRONOS_WEBHOOK_TIMESTAMP_HEADER = "x-kronos-timestamp";
+declare const KRONOS_WEBHOOK_EVENT_ID_HEADER = "x-kronos-event-id";
+declare const KRONOS_WEBHOOK_EVENT_TYPE_HEADER = "x-kronos-event-type";
+declare const BILLING_USAGE_UPDATED_EVENT = "billing.usage.updated";
+declare class KronosWebhookError extends Error {
+    status: number;
+    constructor(message: string, status?: number);
+}
+declare function buildKronosWebhookSignatureInput(timestamp: string, payload: string): string;
+declare function signKronosWebhookPayload(params: {
+    payload: string;
+    secret: string;
+    timestamp: string;
+}): Promise<string>;
+declare function verifyKronosWebhookSignature(params: {
+    payload: string;
+    secret: string;
+    timestamp: string | null | undefined;
+    signature: string | null | undefined;
+    toleranceSeconds?: number;
+    now?: number;
+}): Promise<boolean>;
 /**
  * Verify a webhook secret using constant-time comparison to prevent timing attacks.
  *
@@ -298,6 +360,7 @@ declare function generateIdempotencyKey(): string;
  * ```
  */
 declare function verifyWebhookSecret(receivedSecret: string | null | undefined, storedSecret: string | null | undefined): boolean;
+declare function isBillingUsageWebhookEvent(value: unknown): value is BillingUsageWebhookEvent;
 
 /**
  * Base error for Kronos API failures
@@ -339,4 +402,4 @@ declare class KronosServerError extends KronosError {
     constructor(message: string, status?: number, body?: unknown);
 }
 
-export { ConnectMCPServerResponse, ContextGraphReadResponse, ContextGraphSummaryResponse, CostSummaryResponse, CreateFrontendTokenResponse, CreateMCPServerResponse, CreateScopeResponse, CreateTriggerRequest, CreateTriggerResponse, DeleteTriggerResponse, GetMCPServerResponse, GetScopeResponse, IngestResponse, IngestStatusResponse, KronosBadRequestError, KronosClient, KronosClientConfig, KronosError, KronosForbiddenError, KronosNotFoundError, KronosServerError, KronosUnauthorizedError, ListMCPServersResponse, ListScopesResponse, ListTriggersResponse, MemoryStatsResponse, RotateMCPServerTokenResponse, ScopeSpec, ScratchsheetResponse, SkillManageParams, SkillManageResponse, TriggerRecord, UpdateTriggerRequest, UpdateTriggerResponse, generateIdempotencyKey, verifyWebhookSecret };
+export { BILLING_USAGE_UPDATED_EVENT, BillingUsageWebhookEvent, ConfigureBillingUsageWebhookResponse, ConnectMCPServerResponse, ContextGraphReadResponse, ContextGraphSummaryResponse, CostBreakdownResponse, CostSummaryResponse, CreateFrontendTokenResponse, CreateMCPServerResponse, CreateScopeResponse, CreateTriggerRequest, CreateTriggerResponse, DeleteBillingUsageWebhookResponse, DeleteTriggerResponse, GetBillingUsageWebhookResponse, GetMCPServerResponse, GetScopeResponse, IngestResponse, IngestStatusResponse, KRONOS_WEBHOOK_EVENT_ID_HEADER, KRONOS_WEBHOOK_EVENT_TYPE_HEADER, KRONOS_WEBHOOK_SIGNATURE_HEADER, KRONOS_WEBHOOK_TIMESTAMP_HEADER, KronosBadRequestError, KronosClient, KronosClientConfig, KronosError, KronosForbiddenError, KronosNotFoundError, KronosServerError, KronosUnauthorizedError, KronosWebhookError, ListMCPServersResponse, ListScopesResponse, ListTriggersResponse, MemoryStatsResponse, RotateMCPServerTokenResponse, ScopeSpec, ScratchsheetResponse, SkillManageParams, SkillManageResponse, TriggerRecord, UpdateTriggerRequest, UpdateTriggerResponse, buildKronosWebhookSignatureInput, generateIdempotencyKey, isBillingUsageWebhookEvent, signKronosWebhookPayload, verifyKronosWebhookSignature, verifyWebhookSecret };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { K as KronosClientConfig, I as IngestResponse, a as IngestStatusResponse, C as CreateMCPServerResponse, L as ListMCPServersResponse, G as GetMCPServerResponse, b as ConnectMCPServerResponse, R as RotateMCPServerTokenResponse, M as MemoryStatsResponse, c as CostSummaryResponse, S as ScratchsheetResponse, d as ListScopesResponse, e as GetScopeResponse, f as ScopeSpec, g as CreateScopeResponse, U as UpdateScopeResponse, h as ListTriggersResponse, i as CreateTriggerRequest, j as CreateTriggerResponse, T as TriggerRecord, k as UpdateTriggerRequest, l as UpdateTriggerResponse, D as DeleteTriggerResponse, m as CreateFrontendTokenResponse, n as SkillManageParams, o as SkillManageResponse, p as ContextGraphSummaryResponse, q as ContextGraphReadResponse } from './types-CPHJocLg.js';
-export { y as ConnectMCPServerRequest, Z as ContextGraphProcedureSummary, H as CreateFrontendTokenRequest, u as CreateMCPServerRequest, E as CreateScopeRequest, s as IngestMemoryDisposition, t as IngestRequest, r as IngestStatus, x as MCPServerDetails, v as MCPServerStatus, w as MCPServerToolCapabilities, O as OnTriggered, z as RotateMCPServerTokenRequest, B as ScopeDetail, A as ScopeSummary, P as SkillFileContentMode, Q as SkillFileInput, V as SkillFileRecord, J as SkillFileType, X as SkillMetadataRecord, N as SkillReadMode, Y as SkillSummaryRecord, W as SkillTreeNode, F as TriggerType } from './types-CPHJocLg.js';
+import { K as KronosClientConfig, I as IngestResponse, a as IngestStatusResponse, C as CreateMCPServerResponse, L as ListMCPServersResponse, G as GetMCPServerResponse, b as ConnectMCPServerResponse, R as RotateMCPServerTokenResponse, M as MemoryStatsResponse, c as CostSummaryResponse, d as CostBreakdownResponse, e as GetBillingUsageWebhookResponse, f as ConfigureBillingUsageWebhookResponse, D as DeleteBillingUsageWebhookResponse, S as ScratchsheetResponse, g as ListScopesResponse, h as GetScopeResponse, i as ScopeSpec, j as CreateScopeResponse, U as UpdateScopeResponse, k as ListTriggersResponse, l as CreateTriggerRequest, m as CreateTriggerResponse, T as TriggerRecord, n as UpdateTriggerRequest, o as UpdateTriggerResponse, p as DeleteTriggerResponse, q as CreateFrontendTokenResponse, r as SkillManageParams, s as SkillManageResponse, t as ContextGraphSummaryResponse, u as ContextGraphReadResponse, B as BillingUsageWebhookEvent } from './types-CTMNKYHj.js';
+export { N as BillingUsageWebhookEventData, O as ConfigureBillingUsageWebhookRequest, F as ConnectMCPServerRequest, a5 as ContextGraphProcedureSummary, J as CostBreakdownPoint, Y as CreateFrontendTokenRequest, y as CreateMCPServerRequest, V as CreateScopeRequest, w as IngestMemoryDisposition, x as IngestRequest, v as IngestStatus, E as MCPServerDetails, z as MCPServerStatus, A as MCPServerToolCapabilities, X as OnTriggered, H as RotateMCPServerTokenRequest, Q as ScopeDetail, P as ScopeSummary, $ as SkillFileContentMode, a0 as SkillFileInput, a1 as SkillFileRecord, Z as SkillFileType, a3 as SkillMetadataRecord, _ as SkillReadMode, a4 as SkillSummaryRecord, a2 as SkillTreeNode, W as TriggerType } from './types-CTMNKYHj.js';
 
 declare class KronosClient {
     private readonly workerUrl;
@@ -102,6 +102,45 @@ declare class KronosClient {
     getCostSummary(params?: {
         tenant_user_id?: string;
     }): Promise<CostSummaryResponse>;
+    /**
+     * Get daily AI stage cost totals for the app, or for a single user if specified.
+     */
+    getCostBreakdown(params?: {
+        tenant_user_id?: string;
+        days?: number;
+    }): Promise<CostBreakdownResponse>;
+    /**
+     * Get the app-level billing usage webhook configuration.
+     */
+    getBillingUsageWebhook(): Promise<GetBillingUsageWebhookResponse>;
+    /**
+     * Configure the app-level billing usage webhook.
+     */
+    configureBillingUsageWebhook(params: {
+        webhook_url: string;
+        webhook_secret: string;
+        event_types?: Array<'billing.usage.updated'>;
+        status?: 'active' | 'disabled';
+    }): Promise<ConfigureBillingUsageWebhookResponse>;
+    /**
+     * Delete the app-level billing usage webhook configuration.
+     */
+    deleteBillingUsageWebhook(): Promise<DeleteBillingUsageWebhookResponse>;
+    /**
+     * Verify an incoming billing usage webhook against the stored app webhook secret.
+     */
+    verifyBillingUsageWebhook(params: {
+        payload: string;
+        signature: string;
+        timestamp: string;
+    }): Promise<boolean>;
+    /**
+     * Verify an incoming Kronos webhook request and optionally validate its payload shape.
+     */
+    verifyWebhook<T = unknown>(request: Request, options?: {
+        expectedEventType?: string;
+        validate?: (payload: unknown) => payload is T;
+    }): Promise<T>;
     /**
      * Read the current scratchsheet document for a user.
      */
@@ -276,6 +315,29 @@ declare function generateIdempotencyKey(): string;
  * Webhook verification utilities for Kronos triggers
  * Provides secure constant-time comparison for webhook secrets
  */
+declare const KRONOS_WEBHOOK_SIGNATURE_HEADER = "x-kronos-signature";
+declare const KRONOS_WEBHOOK_TIMESTAMP_HEADER = "x-kronos-timestamp";
+declare const KRONOS_WEBHOOK_EVENT_ID_HEADER = "x-kronos-event-id";
+declare const KRONOS_WEBHOOK_EVENT_TYPE_HEADER = "x-kronos-event-type";
+declare const BILLING_USAGE_UPDATED_EVENT = "billing.usage.updated";
+declare class KronosWebhookError extends Error {
+    status: number;
+    constructor(message: string, status?: number);
+}
+declare function buildKronosWebhookSignatureInput(timestamp: string, payload: string): string;
+declare function signKronosWebhookPayload(params: {
+    payload: string;
+    secret: string;
+    timestamp: string;
+}): Promise<string>;
+declare function verifyKronosWebhookSignature(params: {
+    payload: string;
+    secret: string;
+    timestamp: string | null | undefined;
+    signature: string | null | undefined;
+    toleranceSeconds?: number;
+    now?: number;
+}): Promise<boolean>;
 /**
  * Verify a webhook secret using constant-time comparison to prevent timing attacks.
  *
@@ -298,6 +360,7 @@ declare function generateIdempotencyKey(): string;
  * ```
  */
 declare function verifyWebhookSecret(receivedSecret: string | null | undefined, storedSecret: string | null | undefined): boolean;
+declare function isBillingUsageWebhookEvent(value: unknown): value is BillingUsageWebhookEvent;
 
 /**
  * Base error for Kronos API failures
@@ -339,4 +402,4 @@ declare class KronosServerError extends KronosError {
     constructor(message: string, status?: number, body?: unknown);
 }
 
-export { ConnectMCPServerResponse, ContextGraphReadResponse, ContextGraphSummaryResponse, CostSummaryResponse, CreateFrontendTokenResponse, CreateMCPServerResponse, CreateScopeResponse, CreateTriggerRequest, CreateTriggerResponse, DeleteTriggerResponse, GetMCPServerResponse, GetScopeResponse, IngestResponse, IngestStatusResponse, KronosBadRequestError, KronosClient, KronosClientConfig, KronosError, KronosForbiddenError, KronosNotFoundError, KronosServerError, KronosUnauthorizedError, ListMCPServersResponse, ListScopesResponse, ListTriggersResponse, MemoryStatsResponse, RotateMCPServerTokenResponse, ScopeSpec, ScratchsheetResponse, SkillManageParams, SkillManageResponse, TriggerRecord, UpdateTriggerRequest, UpdateTriggerResponse, generateIdempotencyKey, verifyWebhookSecret };
+export { BILLING_USAGE_UPDATED_EVENT, BillingUsageWebhookEvent, ConfigureBillingUsageWebhookResponse, ConnectMCPServerResponse, ContextGraphReadResponse, ContextGraphSummaryResponse, CostBreakdownResponse, CostSummaryResponse, CreateFrontendTokenResponse, CreateMCPServerResponse, CreateScopeResponse, CreateTriggerRequest, CreateTriggerResponse, DeleteBillingUsageWebhookResponse, DeleteTriggerResponse, GetBillingUsageWebhookResponse, GetMCPServerResponse, GetScopeResponse, IngestResponse, IngestStatusResponse, KRONOS_WEBHOOK_EVENT_ID_HEADER, KRONOS_WEBHOOK_EVENT_TYPE_HEADER, KRONOS_WEBHOOK_SIGNATURE_HEADER, KRONOS_WEBHOOK_TIMESTAMP_HEADER, KronosBadRequestError, KronosClient, KronosClientConfig, KronosError, KronosForbiddenError, KronosNotFoundError, KronosServerError, KronosUnauthorizedError, KronosWebhookError, ListMCPServersResponse, ListScopesResponse, ListTriggersResponse, MemoryStatsResponse, RotateMCPServerTokenResponse, ScopeSpec, ScratchsheetResponse, SkillManageParams, SkillManageResponse, TriggerRecord, UpdateTriggerRequest, UpdateTriggerResponse, buildKronosWebhookSignatureInput, generateIdempotencyKey, isBillingUsageWebhookEvent, signKronosWebhookPayload, verifyKronosWebhookSignature, verifyWebhookSecret };

package/dist/index.js

@@ -20,6 +20,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BILLING_USAGE_UPDATED_EVENT: () => BILLING_USAGE_UPDATED_EVENT,
+  KRONOS_WEBHOOK_EVENT_ID_HEADER: () => KRONOS_WEBHOOK_EVENT_ID_HEADER,
+  KRONOS_WEBHOOK_EVENT_TYPE_HEADER: () => KRONOS_WEBHOOK_EVENT_TYPE_HEADER,
+  KRONOS_WEBHOOK_SIGNATURE_HEADER: () => KRONOS_WEBHOOK_SIGNATURE_HEADER,
+  KRONOS_WEBHOOK_TIMESTAMP_HEADER: () => KRONOS_WEBHOOK_TIMESTAMP_HEADER,
   KronosBadRequestError: () => KronosBadRequestError,
   KronosClient: () => KronosClient,
   KronosError: () => KronosError,
@@ -27,7 +32,12 @@ __export(index_exports, {
   KronosNotFoundError: () => KronosNotFoundError,
   KronosServerError: () => KronosServerError,
   KronosUnauthorizedError: () => KronosUnauthorizedError,
+  KronosWebhookError: () => KronosWebhookError,
+  buildKronosWebhookSignatureInput: () => buildKronosWebhookSignatureInput,
   generateIdempotencyKey: () => generateIdempotencyKey,
+  isBillingUsageWebhookEvent: () => isBillingUsageWebhookEvent,
+  signKronosWebhookPayload: () => signKronosWebhookPayload,
+  verifyKronosWebhookSignature: () => verifyKronosWebhookSignature,
   verifyWebhookSecret: () => verifyWebhookSecret
 });
 module.exports = __toCommonJS(index_exports);
@@ -87,6 +97,84 @@ function generateIdempotencyKey() {
   return `idem_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
 }
 
+// src/webhook-verification.ts
+var KRONOS_WEBHOOK_SIGNATURE_HEADER = "x-kronos-signature";
+var KRONOS_WEBHOOK_TIMESTAMP_HEADER = "x-kronos-timestamp";
+var KRONOS_WEBHOOK_EVENT_ID_HEADER = "x-kronos-event-id";
+var KRONOS_WEBHOOK_EVENT_TYPE_HEADER = "x-kronos-event-type";
+var BILLING_USAGE_UPDATED_EVENT = "billing.usage.updated";
+var KronosWebhookError = class extends Error {
+  constructor(message, status = 400) {
+    super(message);
+    this.name = "KronosWebhookError";
+    this.status = status;
+  }
+};
+function hexFromBytes(bytes) {
+  return Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function buildKronosWebhookSignatureInput(timestamp, payload) {
+  return `${timestamp}.${payload}`;
+}
+async function signKronosWebhookPayload(params) {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(params.secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(
+      buildKronosWebhookSignatureInput(params.timestamp, params.payload)
+    )
+  );
+  return hexFromBytes(new Uint8Array(signature));
+}
+async function verifyKronosWebhookSignature(params) {
+  if (!params.timestamp || !params.signature || !params.secret) {
+    return false;
+  }
+  const toleranceSeconds = params.toleranceSeconds ?? 300;
+  const now = params.now ?? Math.floor(Date.now() / 1e3);
+  const timestampSeconds = Number(params.timestamp);
+  if (!Number.isFinite(timestampSeconds)) {
+    return false;
+  }
+  if (Math.abs(now - timestampSeconds) > toleranceSeconds) {
+    return false;
+  }
+  const expected = await signKronosWebhookPayload({
+    payload: params.payload,
+    secret: params.secret,
+    timestamp: params.timestamp
+  });
+  return verifyWebhookSecret(params.signature, expected);
+}
+function verifyWebhookSecret(receivedSecret, storedSecret) {
+  if (!receivedSecret || !storedSecret) {
+    return false;
+  }
+  if (receivedSecret.length !== storedSecret.length) {
+    return false;
+  }
+  let result = 0;
+  for (let i = 0; i < receivedSecret.length; i++) {
+    result |= receivedSecret.charCodeAt(i) ^ storedSecret.charCodeAt(i);
+  }
+  return result === 0;
+}
+function isBillingUsageWebhookEvent(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const event = value;
+  const data = event.data;
+  return event.type === BILLING_USAGE_UPDATED_EVENT && typeof event.id === "string" && typeof event.created_at === "string" && !!data && typeof data.app_id === "string" && typeof data.tenant_user_id === "string" && typeof data.total_cost_usd === "number" && typeof data.latest_run_cost_usd === "number" && typeof data.updated_at === "string";
+}
+
 // src/client.ts
 var DEFAULT_WORKER_URL = "https://api.kronos.ai";
 var DEFAULT_MASTRA_URL = "https://mastra.kronos.ai";
@@ -364,6 +452,127 @@ var KronosClient = class {
       { method: "GET" }
     );
   }
+  /**
+   * Get daily AI stage cost totals for the app, or for a single user if specified.
+   */
+  async getCostBreakdown(params = {}) {
+    const query = new URLSearchParams({
+      app_id: this.appId
+    });
+    if (params.tenant_user_id) {
+      query.set("tenant_user_id", params.tenant_user_id);
+    }
+    if (typeof params.days === "number" && Number.isFinite(params.days)) {
+      query.set("days", String(Math.trunc(params.days)));
+    }
+    return this.workerFetch(
+      `/v1/costs/breakdown?${query.toString()}`,
+      { method: "GET" }
+    );
+  }
+  /**
+   * Get the app-level billing usage webhook configuration.
+   */
+  async getBillingUsageWebhook() {
+    const query = new URLSearchParams({
+      app_id: this.appId
+    });
+    return this.workerFetch(
+      `/v1/webhooks/billing-usage?${query.toString()}`,
+      { method: "GET" }
+    );
+  }
+  /**
+   * Configure the app-level billing usage webhook.
+   */
+  async configureBillingUsageWebhook(params) {
+    return this.workerFetch(
+      "/v1/webhooks/billing-usage",
+      {
+        method: "PUT",
+        json: {
+          app_id: this.appId,
+          webhook_url: params.webhook_url,
+          webhook_secret: params.webhook_secret,
+          event_types: params.event_types,
+          status: params.status
+        }
+      }
+    );
+  }
+  /**
+   * Delete the app-level billing usage webhook configuration.
+   */
+  async deleteBillingUsageWebhook() {
+    const query = new URLSearchParams({
+      app_id: this.appId
+    });
+    return this.workerFetch(
+      `/v1/webhooks/billing-usage?${query.toString()}`,
+      { method: "DELETE" }
+    );
+  }
+  /**
+   * Verify an incoming billing usage webhook against the stored app webhook secret.
+   */
+  async verifyBillingUsageWebhook(params) {
+    const response = await this.workerFetch(
+      "/v1/webhooks/billing-usage/verify",
+      {
+        method: "POST",
+        json: {
+          app_id: this.appId,
+          payload: params.payload,
+          received_signature: params.signature,
+          received_timestamp: params.timestamp
+        }
+      }
+    );
+    return response.valid;
+  }
+  /**
+   * Verify an incoming Kronos webhook request and optionally validate its payload shape.
+   */
+  async verifyWebhook(request, options = {}) {
+    const payload = await request.text();
+    const signature = request.headers.get(KRONOS_WEBHOOK_SIGNATURE_HEADER);
+    const timestamp = request.headers.get(KRONOS_WEBHOOK_TIMESTAMP_HEADER);
+    if (!signature || !timestamp) {
+      throw new KronosWebhookError("Missing webhook signature headers", 401);
+    }
+    const response = await this.workerFetch(
+      "/v1/webhooks/verify",
+      {
+        method: "POST",
+        json: {
+          app_id: this.appId,
+          payload,
+          received_signature: signature,
+          received_timestamp: timestamp
+        }
+      }
+    );
+    if (!response.valid) {
+      throw new KronosWebhookError("Invalid webhook signature", 401);
+    }
+    const eventType = request.headers.get(KRONOS_WEBHOOK_EVENT_TYPE_HEADER);
+    if (options.expectedEventType && eventType !== options.expectedEventType) {
+      throw new KronosWebhookError(
+        `Unsupported webhook event type: ${eventType ?? "missing"}`,
+        400
+      );
+    }
+    let parsedPayload;
+    try {
+      parsedPayload = JSON.parse(payload);
+    } catch {
+      throw new KronosWebhookError("Invalid webhook payload", 400);
+    }
+    if (options.validate && !options.validate(parsedPayload)) {
+      throw new KronosWebhookError("Invalid webhook payload", 400);
+    }
+    return parsedPayload;
+  }
   /**
    * Read the current scratchsheet document for a user.
    */
@@ -741,23 +950,13 @@ var KronosClient = class {
     };
   }
 };
-
-// src/webhook-verification.ts
-function verifyWebhookSecret(receivedSecret, storedSecret) {
-  if (!receivedSecret || !storedSecret) {
-    return false;
-  }
-  if (receivedSecret.length !== storedSecret.length) {
-    return false;
-  }
-  let result = 0;
-  for (let i = 0; i < receivedSecret.length; i++) {
-    result |= receivedSecret.charCodeAt(i) ^ storedSecret.charCodeAt(i);
-  }
-  return result === 0;
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BILLING_USAGE_UPDATED_EVENT,
+  KRONOS_WEBHOOK_EVENT_ID_HEADER,
+  KRONOS_WEBHOOK_EVENT_TYPE_HEADER,
+  KRONOS_WEBHOOK_SIGNATURE_HEADER,
+  KRONOS_WEBHOOK_TIMESTAMP_HEADER,
   KronosBadRequestError,
   KronosClient,
   KronosError,
@@ -765,7 +964,12 @@ function verifyWebhookSecret(receivedSecret, storedSecret) {
   KronosNotFoundError,
   KronosServerError,
   KronosUnauthorizedError,
+  KronosWebhookError,
+  buildKronosWebhookSignatureInput,
   generateIdempotencyKey,
+  isBillingUsageWebhookEvent,
+  signKronosWebhookPayload,
+  verifyKronosWebhookSignature,
   verifyWebhookSecret
 });
 //# sourceMappingURL=index.js.map