/**
 * Monthly Verify Scheduler — SDK consumer of PR-C (verify-monthly endpoint).
 *
 * Responsibilities:
 *   1. On first AGENT_TOOL_OBSERVED event of each calendar month per agent,
 *      call POST https://license.my-cc.io/api/v1/license/verify-monthly with
 *      the agent's service JWT (Bearer).
 *   2. Cache the response { valid, licensedPacks, paidThrough,
 *      gracePeriodUntil?, cacheUntil } until `cacheUntil` (start of next
 *      calendar month UTC).
 *   3. Expose getLicensedPacks() so LicensePackLoader can pre-check packs
 *      before hitting the PR-D endpoint.
 *   4. Expose licenseStatus() for diagnostic logging.
 *   5. On verify failure: use last cached state. Never throw, never block.
 *
 * Implements MonthlyVerifyCache interface consumed by LicensePackLoader.
 *
 * Architectural invariants honoured:
 *   Invariant 2  (advisory, never authoritative): failure falls back to cache.
 *   Invariant 10 (push-receive-only): SDK calls out to our endpoint.
 *                We never push into customer infrastructure.
 *
 * Integration gap closed: PR-C endpoint exists + tested but had no SDK caller.
 * This module is that caller.
 *
 * @connexum/ai-governance  Task #32 — SDK consumer PR-C
 */
import type { MonthlyVerifyCache } from './license-pack-loader.js';
/**
 * Response body from POST /api/v1/license/verify-monthly (PR-C).
 */
export interface VerifyMonthlyResponse {
    valid: boolean;
    licensedPacks: string[];
    paidThrough: string;
    gracePeriodUntil?: string;
    /** ISO 8601 — SDK caches until this timestamp (start of next month UTC). */
    cacheUntil: string;
}
/**
 * Diagnostic status object surfaced via licenseStatus().
 */
export interface LicenseStatusSnapshot {
    /** True if last verified response was valid. */
    valid: boolean | null;
    licensedPacks: string[] | null;
    paidThrough: string | null;
    gracePeriodUntil: string | null;
    /** ISO 8601 — when the cache expires. Null if cache is cold. */
    cacheUntil: string | null;
    /** ISO 8601 — when the cache was last populated. Null if cache is cold. */
    lastVerifiedAt: string | null;
}
/**
 * Dependency injection for the verify-monthly HTTP call.
 * Allows tests to stub the call without touching module-level singletons.
 */
export interface VerifyMonthlyDeps {
    /**
     * POST to the verify-monthly endpoint.
     * Must never throw — return a structured error result instead.
     *
     * @returns { status, body } or { status: 0, body: null } on network failure.
     */
    postVerifyMonthly: (licenseServerUrl: string, agentJwt: string) => Promise<{
        status: number;
        body: unknown;
    }>;
}
/**
 * Production postVerifyMonthly — calls the real endpoint.
 * 10-second timeout. Never throws (returns synthetic 503 on error).
 */
export declare function defaultPostVerifyMonthly(licenseServerUrl: string, agentJwt: string): Promise<{
    status: number;
    body: unknown;
}>;
export interface MonthlyVerifySchedulerOptions {
    /** URL of the license server (e.g. https://license.my-cc.io). */
    licenseServerUrl: string;
    /**
     * The agent's service JWT (gov-server-issued, ORG_OPERATOR role).
     * Used as the Bearer token for verify-monthly calls.
     * The endpoint reads orgId from the JWT's `org` claim.
     */
    agentJwt: string;
    /** Injected dependencies. Defaults to production implementation. */
    deps?: Partial<VerifyMonthlyDeps>;
}
/**
 * Calendar-month key in UTC.
 * Format: "YYYY-MM"
 *
 * Exported for test use — allows tests to verify month-key logic.
 */
export declare function calendarMonthKey(date?: Date): string;
/**
 * MonthlyVerifyScheduler — wraps PR-C verify-monthly with calendar-month
 * deduplication and an in-process response cache.
 *
 * Usage:
 *
 * ```ts
 * const scheduler = new MonthlyVerifyScheduler({
 *   licenseServerUrl: 'https://license.my-cc.io',
 *   agentJwt: serviceToken,
 * });
 *
 * // Wire into the SelfRegistrationHook sink:
 * hook.sink = (event) => {
 *   if (event.kind === 'AGENT_TOOL_OBSERVED') {
 *     void scheduler.onToolObserved(event.agentId);
 *   }
 * };
 *
 * // LicensePackLoader reads from the scheduler:
 * const loader = new LicensePackLoader({ ..., monthlyVerifyCache: scheduler });
 * ```
 */
export declare class MonthlyVerifyScheduler implements MonthlyVerifyCache {
    private readonly licenseServerUrl;
    private readonly agentJwt;
    private readonly deps;
    /** Map of agentId → month key of last verify call ("YYYY-MM"). */
    private readonly lastVerifiedMonth;
    /** Cached verify response (shared across all agents in this process). */
    private cachedResponse;
    /** ISO 8601 timestamp of last successful verify. */
    private lastVerifiedAt;
    /** In-flight promise guard — prevents duplicate concurrent calls. */
    private _inFlightVerify;
    constructor(options: MonthlyVerifySchedulerOptions);
    /**
     * Return cached licensedPacks array, or null when the cache is cold.
     * Called synchronously by LicensePackLoader before any network attempt.
     */
    getLicensedPacks(): string[] | null;
    /**
     * Diagnostic snapshot of the current license status.
     * Never throws.
     */
    licenseStatus(): LicenseStatusSnapshot;
    /**
     * Call on first AGENT_TOOL_OBSERVED event of each calendar month.
     * Triggers verify-monthly if this agent has not yet verified this month.
     *
     * Safe to call from every AGENT_TOOL_OBSERVED event — internally
     * deduplicates by calendar month per agent and prevents concurrent calls.
     *
     * Never throws (Invariant 2: fails-soft).
     *
     * @param agentId - The agentId from the SelfRegistrationEvent.
     */
    onToolObserved(agentId: string): Promise<void>;
    private _runVerify;
    /** Reset all state. Call between tests. */
    __resetForTest(): void;
    /**
     * Inject a cached response directly (for test setup without calling onToolObserved).
     * This simulates a state where verify-monthly has already run.
     */
    __setCacheForTest(response: VerifyMonthlyResponse, verifiedAt?: string): void;
}
//# sourceMappingURL=monthly-verify-scheduler.d.ts.map