@agent-native/core 0.92.12 → 0.93.0

package/dist/integrations/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/integrations/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { H3Event } from \"h3\";\n\nimport type { EnvKeyConfig } from \"../server/create-server.js\";\n\n/**\n * Normalized incoming message from any messaging platform.\n */\nexport interface IncomingMessage {\n  /** Platform identifier (e.g., \"slack\", \"telegram\", \"whatsapp\") */\n  platform: string;\n  /** Platform-specific thread/conversation identifier */\n  externalThreadId: string;\n  /** Message text content */\n  text: string;\n  /** Display name of the sender */\n  senderName?: string;\n  /** Verified sender email, when the platform can provide one */\n  senderEmail?: string;\n  /** Platform-specific sender ID */\n  senderId?: string;\n  /**\n   * Whether the platform cryptographically authenticated that the message\n   * genuinely came from the claimed sender (e.g. inbound email that passed\n   * DKIM, or an aligned SPF pass, for the From domain). Defaults to\n   * undefined/false for platforms that don't provide sender authentication.\n   *\n   * Owner-resolution paths that grant a real user's identity/credentials\n   * MUST treat a missing/false value as \"unverified\" and fail closed —\n   * never derive a privileged acting identity from an unverified sender.\n   */\n  senderVerified?: boolean;\n  /** Raw platform-specific context needed for routing responses */\n  platformContext: Record<string, unknown>;\n  /** Message timestamp (epoch ms) */\n  timestamp: number;\n}\n\n/**\n * Outgoing message to send back to a messaging platform.\n */\nexport interface OutgoingMessage {\n  /** Text content of the response */\n  text: string;\n  /** Platform-specific payload (e.g., Slack blocks, Telegram parse_mode) */\n  platformContext: Record<string, unknown>;\n}\n\n/**\n * Proactive outbound message target for a platform.\n * Used when the agent needs to send to a saved destination instead of replying\n * to the current inbound thread.\n */\nexport interface OutboundTarget {\n  /** Canonical platform-specific destination id (channel, chat, thread, etc.) */\n  destination: string;\n  /** Optional thread reference when the destination supports threading */\n  threadRef?: string | null;\n  /** Optional fallback display label */\n  label?: string;\n}\n\n/**\n * Connection status for a platform integration.\n */\nexport interface IntegrationStatus {\n  platform: string;\n  /** Human-readable label (e.g., \"Slack\", \"Telegram\") */\n  label: string;\n  /** Whether the integration is explicitly enabled */\n  enabled: boolean;\n  /** Whether all required credentials are configured */\n  configured: boolean;\n  /** Platform-specific details (workspace name, bot username, etc.) */\n  details?: Record<string, unknown>;\n  /** Error message if something is wrong */\n  error?: string;\n  /** The webhook URL that should be configured in the platform */\n  webhookUrl?: string;\n  /** The full list of env keys (required + optional) the adapter recognizes,\n   *  including UI hints. Surfaced on the integrations status endpoint so the\n   *  frontend can render fields without hard-coding them per platform. */\n  requiredEnvKeys?: import(\"../server/create-server.js\").EnvKeyConfig[];\n}\n\n/**\n * Platform adapter interface — implement this for each messaging platform.\n *\n * Each adapter handles the platform-specific concerns:\n * - Webhook verification (HMAC signatures, challenge responses)\n * - Message parsing (platform events → normalized IncomingMessage)\n * - Response formatting (agent text → platform-specific format)\n * - Response delivery (POST back to platform API)\n */\nexport interface PlatformAdapter {\n  /** Unique platform identifier */\n  readonly platform: string;\n  /** Human-readable label */\n  readonly label: string;\n\n  /** Env keys this adapter needs (tokens, secrets, etc.) */\n  getRequiredEnvKeys(): EnvKeyConfig[];\n\n  /**\n   * Handle platform-specific verification challenges.\n   * For example, Slack sends a `url_verification` event when setting up.\n   * Return `{ handled: true, response }` to short-circuit the webhook handler.\n   */\n  handleVerification(event: H3Event): Promise<{\n    handled: boolean;\n    response?: unknown;\n  }>;\n\n  /**\n   * Validate the webhook request signature.\n   * Returns true if the request is authentic.\n   */\n  verifyWebhook(event: H3Event): Promise<boolean>;\n\n  /**\n   * Parse the webhook payload into a normalized IncomingMessage.\n   * Return null to silently ignore the event (bot messages, edits, etc.).\n   */\n  parseIncomingMessage(event: H3Event): Promise<IncomingMessage | null>;\n\n  /**\n   * Send the agent's response back to the messaging platform.\n   *\n   * If `opts.placeholderRef` is provided (returned earlier by\n   * `postProcessingPlaceholder`), adapters that support in-place edits should\n   * update that placeholder message rather than posting a new one. Adapters\n   * without an \"update message\" API can ignore the ref and post fresh.\n   */\n  sendResponse(\n    message: OutgoingMessage,\n    context: IncomingMessage,\n    opts?: { placeholderRef?: string },\n  ): Promise<void>;\n\n  /**\n   * Optionally post a \"working on it…\" placeholder message immediately when a\n   * webhook arrives, before the agent loop runs. Adapters that support\n   * in-place message edits (Slack via `chat.update`, etc.) return an opaque\n   * `placeholderRef` that the webhook flow threads through to `sendResponse`\n   * so the same message is updated with the final answer once ready.\n   *\n   * Adapters without edit support should leave this undefined; the webhook\n   * handler will skip the placeholder step entirely.\n   */\n  postProcessingPlaceholder?(\n    incoming: IncomingMessage,\n  ): Promise<{ placeholderRef: string } | null>;\n\n  /**\n   * Send a proactive outbound message to a platform destination. Adapters that\n   * only support direct replies can omit this.\n   */\n  sendMessageToTarget?(\n    message: OutgoingMessage,\n    target: OutboundTarget,\n  ): Promise<void>;\n\n  /**\n   * Format plain agent response text into a platform-appropriate message.\n   * Handles markdown conversion, message splitting for length limits, etc.\n   *\n   * `opts.threadDeepLinkUrl`, when present, is a URL back to the originating\n   * thread in the dispatch UI. Adapters that support rich blocks should\n   * render this as a button (Slack); adapters that don't may inline it as a\n   * link or simply omit it.\n   */\n  formatAgentResponse(\n    text: string,\n    opts?: { threadDeepLinkUrl?: string },\n  ): OutgoingMessage;\n\n  /** Return current connection/configuration status for the settings UI. */\n  getStatus(baseUrl?: string): Promise<IntegrationStatus>;\n}\n\n/**\n * Options for the integrations plugin.\n */\nexport interface IntegrationsPluginOptions {\n  /** App identifier used by call-agent to prevent self-calls (e.g. \"dispatch\"). */\n  appId?: string;\n  /** Platform adapters to enable. Default: all built-in adapters with configured env keys. */\n  adapters?: PlatformAdapter[];\n  /** System prompt for the agent (same as agent-chat). Inherited from agent-chat plugin if not set. */\n  systemPrompt?: string;\n  /** Actions registry (same as agent-chat). */\n  actions?: Record<string, import(\"../agent/production-agent.js\").ActionEntry>;\n  /** Model to use. Defaults to the resolved engine's default model. */\n  model?: string;\n  /** Anthropic API key. Falls back to ANTHROPIC_API_KEY env var. */\n  apiKey?: string;\n  /** Agent engine to use. Defaults to the same engine resolver as web chat. */\n  engine?:\n    | import(\"../agent/engine/types.js\").AgentEngine\n    | string\n    | {\n        name: string;\n        config: Record<string, unknown>;\n      };\n  /**\n   * Resolve which owner should receive personal resource context and own the\n   * created chat thread for an incoming platform message.\n   */\n  resolveOwner?: (incoming: IncomingMessage) => string | Promise<string>;\n  /**\n   * Optional preprocessor for inbound platform messages. Can intercept special\n   * commands (such as `/link`) before the agent loop runs.\n   */\n  beforeProcess?: (\n    incoming: IncomingMessage,\n    adapter: PlatformAdapter,\n  ) => Promise<\n    | {\n        handled: true;\n        responseText?: string;\n      }\n    | { handled: false }\n  >;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/integrations/types.ts"],"names":[],"mappings":"AAoMA,MAAM,OAAO,kCAAmC,SAAQ,KAAK;IAIhD,QAAQ;IACR,UAAU;IAJZ,IAAI,GAAG,iCAAiC,CAAC;IAElD,YACW,QAAgB,EAChB,UAA6C;QAEtD,KAAK,CAAC,YAAY,QAAQ,qBAAqB,UAAU,EAAE,CAAC,CAAC;wBAHpD,QAAQ;0BACR,UAAU;QAGnB,IAAI,CAAC,IAAI,GAAG,oCAAoC,CAAC;IACnD,CAAC;CACF;AA+HD,MAAM,UAAU,wBAAwB,CACtC,OAAwB,EACxB,UAA6C;IAE7C,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,UAAU,CAAC,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,IAAI,kCAAkC,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC7E,CAAC;AACH,CAAC","sourcesContent":["import type { H3Event } from \"h3\";\n\nimport type { AgentChatEvent } from \"../agent/types.js\";\nimport type { EnvKeyConfig } from \"../server/create-server.js\";\n\nexport type IntegrationConversationType =\n  | \"channel\"\n  | \"private_channel\"\n  | \"dm\"\n  | \"group_dm\"\n  | \"unknown\";\n\nexport type IntegrationTriggerKind = \"mention\" | \"dm\" | \"thread_reply\";\n\nexport interface IntegrationActorTrust {\n  memberType: \"owner\" | \"admin\" | \"member\" | \"guest\" | \"external\" | \"unknown\";\n  verified: boolean;\n}\n\nexport interface IntegrationContextMessage {\n  senderId?: string;\n  senderName?: string;\n  text: string;\n  timestamp: number;\n  sourceUrl?: string;\n  reactions?: Array<{ name: string; count: number }>;\n  files?: IntegrationFileReference[];\n}\n\nexport interface IntegrationFileReference {\n  id: string;\n  name?: string;\n  mimetype?: string;\n  size?: number;\n  permalink?: string;\n  downloadUrl?: string;\n}\n\n/**\n * Normalized incoming message from any messaging platform.\n */\nexport interface IncomingMessage {\n  /** Platform identifier (e.g., \"slack\", \"telegram\", \"whatsapp\") */\n  platform: string;\n  /** Platform-specific thread/conversation identifier */\n  externalThreadId: string;\n  /** Message text content */\n  text: string;\n  /** Display name of the sender */\n  senderName?: string;\n  /** Verified sender email, when the platform can provide one */\n  senderEmail?: string;\n  /** Platform-specific sender ID */\n  senderId?: string;\n  /** How this message intentionally invoked an agent. */\n  triggerKind?: IntegrationTriggerKind;\n  /** Normalized provider conversation type for policy evaluation. */\n  conversationType?: IntegrationConversationType;\n  /** Provider tenant/workspace identifier. */\n  tenantId?: string;\n  /** Authorized integration scope resolved before execution. */\n  integrationScopeId?: string;\n  /** Normalized actor trust; unknown/unverified callers fail closed. */\n  actorTrust?: IntegrationActorTrust;\n  /** Bounded provider-native conversation context hydrated at run time. */\n  contextMessages?: IntegrationContextMessage[];\n  /** Provider file references only. Raw file bodies never belong here. */\n  files?: IntegrationFileReference[];\n  /** Server-verified approval grants carried by an interaction continuation. */\n  approvedToolCalls?: string[];\n  /**\n   * Whether the platform cryptographically authenticated that the message\n   * genuinely came from the claimed sender (e.g. inbound email that passed\n   * DKIM, or an aligned SPF pass, for the From domain). Defaults to\n   * undefined/false for platforms that don't provide sender authentication.\n   *\n   * Owner-resolution paths that grant a real user's identity/credentials\n   * MUST treat a missing/false value as \"unverified\" and fail closed —\n   * never derive a privileged acting identity from an unverified sender.\n   */\n  senderVerified?: boolean;\n  /** Raw platform-specific context needed for routing responses */\n  platformContext: Record<string, unknown>;\n  /**\n   * Short-lived delivery context needed only while the queued task is active.\n   * Secrets such as Discord interaction tokens belong here, never in\n   * `platformContext`, thread mappings, logs, or agent-visible context.\n   */\n  responseContext?: Record<string, unknown>;\n  /** Provider-native thread/topic reference, when one exists. */\n  threadRef?: string;\n  /**\n   * Canonical provider URL for the originating message thread, when the\n   * provider can resolve one. This is safe agent-visible provenance (not a\n   * credential) and should be preserved across A2A delegation so created\n   * artifacts can link back to their request source.\n   */\n  sourceUrl?: string;\n  /**\n   * Trusted app-side routing guidance added after provider parsing. Adapters\n   * should not copy this from user-controlled webhook payload fields.\n   */\n  routingHint?: {\n    targetAgent?: string;\n    instruction: string;\n  };\n  /** Provider-native message/activity reference for contextual replies. */\n  replyRef?: string;\n  /** Message timestamp (epoch ms) */\n  timestamp: number;\n}\n\n/**\n * Outgoing message to send back to a messaging platform.\n */\nexport interface OutgoingMessage {\n  /** Text content of the response */\n  text: string;\n  /** Platform-specific payload (e.g., Slack blocks, Telegram parse_mode) */\n  platformContext: Record<string, unknown>;\n}\n\n/**\n * Proactive outbound message target for a platform.\n * Used when the agent needs to send to a saved destination instead of replying\n * to the current inbound thread.\n */\nexport interface OutboundTarget {\n  /** Canonical platform-specific destination id (channel, chat, thread, etc.) */\n  destination: string;\n  /** Optional thread reference when the destination supports threading */\n  threadRef?: string | null;\n  /** Optional fallback display label */\n  label?: string;\n  /** Provider tenant/workspace used to select an installation credential. */\n  tenantId?: string;\n  /** Managed installation id when the caller already resolved it. */\n  installationId?: string;\n}\n\n/**\n * Connection status for a platform integration.\n */\nexport interface IntegrationStatus {\n  platform: string;\n  /** Human-readable label (e.g., \"Slack\", \"Telegram\") */\n  label: string;\n  /** Whether the integration is explicitly enabled */\n  enabled: boolean;\n  /** Whether all required credentials are configured */\n  configured: boolean;\n  /** Platform-specific details (workspace name, bot username, etc.) */\n  details?: Record<string, unknown>;\n  /** Error message if something is wrong */\n  error?: string;\n  /** The webhook URL that should be configured in the platform */\n  webhookUrl?: string;\n  /** The full list of env keys (required + optional) the adapter recognizes,\n   *  including UI hints. Surfaced on the integrations status endpoint so the\n   *  frontend can render fields without hard-coding them per platform. */\n  requiredEnvKeys?: import(\"../server/create-server.js\").EnvKeyConfig[];\n}\n\nexport interface PlatformAdapterCapabilities {\n  /** The adapter can deliver a response to the current inbound event. */\n  replyText: boolean;\n  /** The adapter can send without an active inbound event. */\n  proactiveMessages: boolean;\n  /** The adapter preserves a provider-native thread or topic reference. */\n  nativeThreads: boolean;\n  /** The adapter can quote/reply to a specific inbound message. */\n  contextualReplies: boolean;\n  /** The provider requires an immediate deferred webhook acknowledgement. */\n  deferredWebhookResponse: boolean;\n  /** The adapter only receives explicit interactions, not ordinary messages. */\n  interactionOnly?: boolean;\n  /** The adapter can hydrate bounded native thread/file/reaction context. */\n  nativeContextHydration?: boolean;\n  /** The adapter can surface live agent progress in the provider UI. */\n  liveRunProgress?: boolean;\n}\n\nexport interface PlatformRunProgress {\n  /** Receive normalized agent events. Implementations should throttle writes. */\n  onEvent(event: AgentChatEvent): Promise<void> | void;\n  /** Finalize the provider-native progress surface with the answer. */\n  complete(message: OutgoingMessage): Promise<void>;\n  /** Mark the provider-native surface failed and leave a retryable explanation. */\n  fail?(message: string): Promise<void>;\n}\n\nexport interface ImmediateWebhookResponse {\n  status: number;\n  body: unknown;\n}\n\nexport class UnsupportedPlatformCapabilityError extends Error {\n  readonly code = \"UNSUPPORTED_PLATFORM_CAPABILITY\";\n\n  constructor(\n    readonly platform: string,\n    readonly capability: keyof PlatformAdapterCapabilities,\n  ) {\n    super(`Platform ${platform} does not support ${capability}`);\n    this.name = \"UnsupportedPlatformCapabilityError\";\n  }\n}\n\n/**\n * Platform adapter interface — implement this for each messaging platform.\n *\n * Each adapter handles the platform-specific concerns:\n * - Webhook verification (HMAC signatures, challenge responses)\n * - Message parsing (platform events → normalized IncomingMessage)\n * - Response formatting (agent text → platform-specific format)\n * - Response delivery (POST back to platform API)\n */\nexport interface PlatformAdapter {\n  /** Unique platform identifier */\n  readonly platform: string;\n  /** Human-readable label */\n  readonly label: string;\n  /** Explicit runtime behavior. Missing fields are treated as unsupported. */\n  readonly capabilities?: Partial<PlatformAdapterCapabilities>;\n\n  /** Env keys this adapter needs (tokens, secrets, etc.) */\n  getRequiredEnvKeys(): EnvKeyConfig[];\n\n  /**\n   * Handle platform-specific verification challenges.\n   * For example, Slack sends a `url_verification` event when setting up.\n   * Return `{ handled: true, response }` to short-circuit the webhook handler.\n   */\n  handleVerification(event: H3Event): Promise<{\n    handled: boolean;\n    response?: unknown;\n  }>;\n\n  /**\n   * Validate the webhook request signature.\n   * Returns true if the request is authentic.\n   */\n  verifyWebhook(event: H3Event): Promise<boolean>;\n\n  /**\n   * Parse the webhook payload into a normalized IncomingMessage.\n   * Return null to silently ignore the event (bot messages, edits, etc.).\n   */\n  parseIncomingMessage(event: H3Event): Promise<IncomingMessage | null>;\n\n  /**\n   * Hydrate bounded provider-native context after durable enqueue, outside the\n   * provider acknowledgement budget. Implementations must return references,\n   * metadata, and text only — never persist file bodies or credentials.\n   */\n  hydrateIncomingMessage?(incoming: IncomingMessage): Promise<IncomingMessage>;\n\n  /**\n   * Provider-specific response returned only after a message is verified and\n   * durably enqueued. Discord uses this to return a type-5 deferred response\n   * within its three-second interaction deadline.\n   */\n  getImmediateWebhookResponse?(\n    incoming: IncomingMessage,\n  ): ImmediateWebhookResponse | null;\n\n  /**\n   * Return pre-canonical thread ids used by older adapter versions. The\n   * integration handler checks these only when the canonical mapping is\n   * missing, then aliases a match to the canonical id without forking history.\n   */\n  getLegacyExternalThreadIds?(incoming: IncomingMessage): string[];\n\n  /**\n   * Send the agent's response back to the messaging platform.\n   *\n   * If `opts.placeholderRef` is provided (returned earlier by\n   * `postProcessingPlaceholder`), adapters that support in-place edits should\n   * update that placeholder message rather than posting a new one. Adapters\n   * without an \"update message\" API can ignore the ref and post fresh.\n   */\n  sendResponse(\n    message: OutgoingMessage,\n    context: IncomingMessage,\n    opts?: { placeholderRef?: string },\n  ): Promise<void>;\n\n  /**\n   * Optionally post a \"working on it…\" placeholder message immediately when a\n   * webhook arrives, before the agent loop runs. Adapters that support\n   * in-place message edits (Slack via `chat.update`, etc.) return an opaque\n   * `placeholderRef` that the webhook flow threads through to `sendResponse`\n   * so the same message is updated with the final answer once ready.\n   *\n   * Adapters without edit support should leave this undefined; the webhook\n   * handler will skip the placeholder step entirely.\n   */\n  postProcessingPlaceholder?(\n    incoming: IncomingMessage,\n  ): Promise<{ placeholderRef: string } | null>;\n\n  /** Start a provider-native progress/streaming surface for an agent run. */\n  startRunProgress?(\n    incoming: IncomingMessage,\n  ): Promise<PlatformRunProgress | null>;\n\n  /**\n   * Send a proactive outbound message to a platform destination. Adapters that\n   * only support direct replies can omit this.\n   */\n  sendMessageToTarget?(\n    message: OutgoingMessage,\n    target: OutboundTarget,\n  ): Promise<void>;\n\n  /**\n   * Format plain agent response text into a platform-appropriate message.\n   * Handles markdown conversion, message splitting for length limits, etc.\n   *\n   * `opts.threadDeepLinkUrl`, when present, is a URL back to the originating\n   * thread in the dispatch UI. Adapters that support rich blocks should\n   * render this as a button (Slack); adapters that don't may inline it as a\n   * link or simply omit it.\n   */\n  formatAgentResponse(\n    text: string,\n    opts?: { threadDeepLinkUrl?: string },\n  ): OutgoingMessage;\n\n  /** Return current connection/configuration status for the settings UI. */\n  getStatus(baseUrl?: string): Promise<IntegrationStatus>;\n}\n\nexport function assertPlatformCapability(\n  adapter: PlatformAdapter,\n  capability: keyof PlatformAdapterCapabilities,\n): void {\n  if (adapter.capabilities?.[capability] !== true) {\n    throw new UnsupportedPlatformCapabilityError(adapter.platform, capability);\n  }\n}\n\n/**\n * Options for the integrations plugin.\n */\nexport interface IntegrationsPluginOptions {\n  /** App identifier used by call-agent to prevent self-calls (e.g. \"dispatch\"). */\n  appId?: string;\n  /** Platform adapters to enable. Default: all built-in adapters with configured env keys. */\n  adapters?: PlatformAdapter[];\n  /** System prompt for the agent (same as agent-chat). Inherited from agent-chat plugin if not set. */\n  systemPrompt?: string;\n  /** Actions registry (same as agent-chat). */\n  actions?: Record<string, import(\"../agent/production-agent.js\").ActionEntry>;\n  /** Model to use. Defaults to the resolved engine's default model. */\n  model?: string;\n  /** Anthropic API key. Falls back to ANTHROPIC_API_KEY env var. */\n  apiKey?: string;\n  /** Agent engine to use. Defaults to the same engine resolver as web chat. */\n  engine?:\n    | import(\"../agent/engine/types.js\").AgentEngine\n    | string\n    | {\n        name: string;\n        config: Record<string, unknown>;\n      };\n  /**\n   * Resolve which owner should receive personal resource context and own the\n   * created chat thread for an incoming platform message.\n   */\n  resolveOwner?: (incoming: IncomingMessage) => string | Promise<string>;\n  /**\n   * Resolve the durable execution principal for an inbound provider message.\n   * Shared channels should use a service principal; DMs may use a verified\n   * linked user. When present this supersedes `resolveOwner`.\n   */\n  resolveExecutionContext?: (\n    incoming: IncomingMessage,\n  ) => IntegrationExecutionContext | Promise<IntegrationExecutionContext>;\n  /**\n   * Optional preprocessor for inbound platform messages. Can intercept special\n   * commands (such as `/link`) before the agent loop runs.\n   */\n  beforeProcess?: (\n    incoming: IncomingMessage,\n    adapter: PlatformAdapter,\n  ) => Promise<\n    | {\n        handled: true;\n        responseText?: string;\n      }\n    | { handled: false }\n  >;\n}\n\nexport interface IntegrationExecutionContext {\n  ownerEmail: string;\n  orgId: string | null;\n  principalType: \"user\" | \"service\";\n  installationId?: string;\n  scopeId?: string;\n}\n"]}

package/dist/integrations/usage-budget-store.d.ts

@@ -0,0 +1,84 @@
+import { type IntegrationScopeAccess, type IntegrationScopeKey } from "./scope-store.js";
+/** All budget values are integer millionths of one billing currency unit. */
+export declare const INTEGRATION_BUDGET_COST_UNIT: "currency_micros";
+export type IntegrationBudgetPeriod = "day" | "month";
+export type IntegrationBudgetSubject = {
+    type: "org";
+    orgId: string;
+} | {
+    type: "user";
+    userEmail: string;
+} | {
+    type: "scope";
+    scope: IntegrationScopeKey;
+};
+export interface IntegrationUsageBudget {
+    id: string;
+    subjectType: IntegrationBudgetSubject["type"];
+    subjectId: string;
+    period: IntegrationBudgetPeriod;
+    /** Integer millionths of one billing currency unit. */
+    limitMicros: number;
+    /** Threshold in basis points: 8,000 means 80%. */
+    thresholdBps: number;
+    ownerEmail: string;
+    orgId: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface IntegrationBudgetSnapshot {
+    budget: IntegrationUsageBudget;
+    windowStart: number;
+    windowEnd: number;
+    usedMicros: number;
+    reservedMicros: number;
+    remainingMicros: number;
+    costUnit: typeof INTEGRATION_BUDGET_COST_UNIT;
+}
+export type IntegrationReservationStatus = "pending" | "reserved" | "denied" | "settled" | "released";
+export interface IntegrationBudgetReservationResult {
+    allowed: boolean;
+    reservationId: string;
+    status: IntegrationReservationStatus;
+    estimatedCostMicros: number;
+    settledCostMicros: number | null;
+    thresholdEventEmitted: boolean;
+    snapshot: IntegrationBudgetSnapshot;
+}
+export interface IntegrationBudgetThresholdEvent {
+    id: string;
+    budgetId: string;
+    windowStart: number;
+    thresholdBps: number;
+    observedMicros: number;
+    createdAt: number;
+}
+export declare function saveIntegrationUsageBudget(input: {
+    subject: IntegrationBudgetSubject;
+    period: IntegrationBudgetPeriod;
+    limitMicros: number;
+    thresholdBps?: number;
+}, accessInput: IntegrationScopeAccess): Promise<IntegrationUsageBudget>;
+export declare function getIntegrationUsageBudget(budgetIdInput: string, accessInput: IntegrationScopeAccess): Promise<IntegrationUsageBudget | null>;
+/** List budgets visible in the caller's personal/active-org partition. */
+export declare function listIntegrationUsageBudgets(accessInput: IntegrationScopeAccess): Promise<IntegrationUsageBudget[]>;
+export declare function getIntegrationBudgetSnapshot(budgetIdInput: string, accessInput: IntegrationScopeAccess, timestamp?: number): Promise<IntegrationBudgetSnapshot | null>;
+export declare function reserveIntegrationUsageBudget(input: {
+    budgetId: string;
+    reservationId: string;
+    estimatedCostMicros: number;
+    timestamp?: number;
+}, accessInput: IntegrationScopeAccess): Promise<IntegrationBudgetReservationResult>;
+export declare function settleIntegrationUsageBudget(input: {
+    budgetId: string;
+    reservationId: string;
+    actualCostMicros: number;
+}, accessInput: IntegrationScopeAccess): Promise<IntegrationBudgetReservationResult>;
+export declare function releaseIntegrationUsageBudget(input: {
+    budgetId: string;
+    reservationId: string;
+}, accessInput: IntegrationScopeAccess): Promise<IntegrationBudgetReservationResult>;
+export declare function listIntegrationBudgetThresholdEvents(budgetIdInput: string, accessInput: IntegrationScopeAccess): Promise<IntegrationBudgetThresholdEvent[]>;
+/** Test-only reset for suites that swap the injected database. */
+export declare function _resetIntegrationUsageBudgetStoreForTests(): void;
+//# sourceMappingURL=usage-budget-store.d.ts.map

package/dist/integrations/usage-budget-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-budget-store.d.ts","sourceRoot":"","sources":["../../src/integrations/usage-budget-store.ts"],"names":[],"mappings":"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"}