run402-mcp/sdk/dist/namespaces/cache.d.ts

MCP server for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.

/**
 * `cache` namespace — SSR origin cache inspection and invalidation.
 *
 * Capability `ssr-isr-cache` (Run402 v1.52). Used by AI coding agents
 * and CLI tooling to invalidate cached SSR responses after admin
 * content edits, OR to inspect what's currently cached.
 *
 * All operations are project-scoped: the SDK reads the active project
 * from the credentials provider, and the gateway enforces host
 * ownership (cross-project hosts throw
 * `R402_CACHE_INVALIDATION_HOST_FORBIDDEN`).
 *
 * @see https://docs.run402.com/cache/concepts
 */
import type { Client } from "../kernel.js";
export interface CacheInvalidateResult {
    /** Number of cache rows DELETEd by this call. */
    deleted: number;
    /** Post-increment generation for the affected (project, host). Used
     *  by the generation guard to prevent in-flight MISS renders from
     *  overwriting after invalidation. */
    generation: string;
    /** The host the invalidation targeted. Empty string for bulk calls
     *  that span multiple hosts. */
    host: string;
    /** Path targeted (single-URL form only). */
    path?: string;
    /** Per-host results for bulk invalidation. */
    results?: Array<{
        host: string;
        deleted: number;
        generation: string;
    }>;
}
export interface CacheInspectOptions {
    /** Inspect a non-default-locale row. */
    locale?: string;
    /** Inspect a non-active-release row. */
    releaseId?: string;
}
export interface CacheInspectResult {
    /** `HIT` when a fresh row exists; `MISS` when no fresh row.
     *  NEVER `BYPASS` — inspect doesn't issue a request. */
    status: "HIT" | "MISS";
    url?: string;
    host?: string;
    path?: string;
    search?: string;
    method?: string;
    locale?: string;
    release_id?: string;
    cached_at?: string;
    expires_at?: string;
    written_under_generation?: string;
    content_sha256?: string;
    headers?: Record<string, string | string[]>;
}
export interface CacheInvalidatePrefixOptions {
    host: string;
    prefix: string;
}
export interface CacheInvalidateAllOptions {
    host: string;
}
export declare class Cache {
    private readonly client;
    constructor(client: Client);
    /**
     * Invalidate a single cached SSR response.
     *
     * @param url - Absolute URL (e.g., `https://eagles.kychon.com/the-guys`).
     *              The host MUST be owned by the SDK's active project;
     *              cross-project calls throw `R402_CACHE_INVALIDATION_HOST_FORBIDDEN`.
     */
    invalidate(url: string | URL): Promise<CacheInvalidateResult>;
    /**
     * Invalidate all cache rows under a path prefix on the given host.
     */
    invalidatePrefix(opts: CacheInvalidatePrefixOptions): Promise<CacheInvalidateResult>;
    /**
     * Invalidate ALL cache rows for the given host. Use for catastrophic
     * content changes (nav restructure, layout-wide update, etc.) where
     * targeted invalidation would be impractical.
     */
    invalidateAll(opts: CacheInvalidateAllOptions): Promise<CacheInvalidateResult>;
    /**
     * Bulk-invalidate many absolute URLs in a single round-trip. Groups
     * by host and issues one transaction per host.
     */
    invalidateMany(urls: Array<string | URL>): Promise<CacheInvalidateResult>;
    /**
     * Inspect the cache row state for a URL. Returns `{ status: 'HIT' | 'MISS', ... }`.
     * Does NOT issue a request to the URL.
     *
     * @param url - Absolute URL.
     * @param options - Optional `--locale` / `--release-id` overrides.
     */
    inspect(url: string | URL, options?: CacheInspectOptions): Promise<CacheInspectResult>;
}
//# sourceMappingURL=cache.d.ts.map