@vinext/cloudflare 1.0.0-beta.8 → 1.0.0

package/dist/tpr.d.ts

@@ -1,71 +1,36 @@
+import { parseWranglerConfig } from "./wrangler-config.js";
 //#region src/tpr.d.ts
-/**
- * TPR: Traffic-aware Pre-Rendering
- *
- * Uses Cloudflare zone analytics to determine which pages actually get
- * traffic, and pre-renders only those during deploy. The pre-rendered
- * HTML is uploaded to KV in the same format ISR uses at runtime — no
- * runtime changes needed.
- *
- * Flow:
- *   1. Parse wrangler config to find custom domain and KV namespace
- *   2. Resolve the Cloudflare zone for the custom domain
- *   3. Query zone analytics (GraphQL) for top pages by request count
- *   4. Walk ranked list until coverage threshold is met
- *   5. Start the built production server locally
- *   6. Fetch each hot route to produce HTML
- *   7. Upload pre-rendered HTML to KV (same KVCacheEntry format ISR reads)
- *
- * TPR is an experimental feature enabled via --experimental-tpr. It
- * gracefully skips when no custom domain, no API token, no traffic data,
- * or no KV namespace is configured.
- */
 export type TPROptions = {
   /** Project root directory. */
   root: string;
   /** Wrangler config path, relative to root unless absolute. */
   config?: string;
-  /** Traffic coverage percentage (0–100). Default: 90. */
-  coverage: number;
-  /** Hard cap on number of pages to pre-render. Default: 1000. */
-  limit: number;
+  /** Wrangler environment whose custom domain should be analyzed. */
+  env?: string;
+  /** Explicit domain used to resolve the analytics zone, overriding Wrangler routes. */
+  hostname?: string;
+  /** Read domains from generated Build Output instead of a Wrangler config. */
+  typedConfig?: boolean;
   /** Analytics lookback window in hours. Default: 24. */
   window: number;
 };
-export type TPRResult = {
-  /** Total unique page paths found in analytics. */
-  totalPaths: number;
-  /** Number of pages successfully pre-rendered and uploaded. */
-  prerenderedCount: number;
-  /** Actual traffic coverage achieved (percentage). */
-  coverageAchieved: number;
-  /** Wall-clock duration of the TPR step in milliseconds. */
-  durationMs: number;
+export type TPRRouteResult = {
+  routes: TrafficEntry[];
+  /** Custom-domain origin from typed Build Output for staged pre-warming. */
+  targetUrl?: string;
   /** If TPR was skipped, the reason. */
   skipped?: string;
 };
-type PrerenderResult = {
-  html: string;
-  status: number;
-  headers: Record<string, string>;
+export type TrafficEntry = {
+  path: string;
+  requests: number;
 };
-type WranglerConfig = {
-  accountId?: string;
-  kvNamespaceId?: string;
-  customDomain?: string;
-  name?: string;
-  legacyEnv?: boolean;
-  env?: Record<string, WranglerEnvironmentConfig>;
+export type SelectedRoutes = {
+  routes: TrafficEntry[];
+  totalRequests: number;
+  coveredRequests: number;
+  coveragePercent: number;
 };
-export type WranglerEnvironmentConfig = {
-  customDomain?: string;
-  name?: string;
-};
-/**
- * Parse wrangler config (JSONC or TOML) to extract the fields TPR needs:
- * account_id, VINEXT_KV_CACHE KV namespace ID, and custom domain.
- */
-export declare function parseWranglerConfig(root: string, configPath?: string): WranglerConfig | null;
 /**
  * Generate zone lookup candidates from shortest (2-part) to longest.
  * Tries the most common case first (e.g., "example.com") and progressively
@@ -76,25 +41,17 @@ export declare function parseWranglerConfig(root: string, configPath?: string):
  * "example.com"         → ["example.com"]
  */
 export declare function domainCandidates(domain: string): string[];
-export declare function resolveVinextProdServerPath(root: string): string;
+/** Filter out non-page requests (static assets, API routes, internal routes). */
+export declare function filterTrafficPaths(entries: TrafficEntry[]): TrafficEntry[];
 /**
- * Build KV bulk API pairs from pre-rendered entries.
- *
- * Key format matches the runtime KVCacheHandler exactly:
- *   createKvKeySpace().entryKey(isrCacheKey("app", pathname, buildId) + ":html")
- *   → "cache:app:<buildId>:<pathname>:html"
+ * Walk the ranked traffic list, accumulating request counts until the
+ * coverage target is met or the hard cap is reached.
  */
-export declare function buildTprKVPairs(entries: Map<string, PrerenderResult>, buildId: string | undefined, defaultRevalidateSeconds: number): Array<{
-  key: string;
-  value: string;
-  expiration_ttl: number;
-}>;
+export declare function selectRoutes(traffic: TrafficEntry[], coverageTarget: number, limit: number): SelectedRoutes;
 /**
- * Run the TPR pipeline: query traffic, select routes, pre-render, upload.
- *
- * Designed to be called between the build step and wrangler deploy in the
- * `vinext-cloudflare deploy` pipeline. Gracefully skips (never errors) when
- * the prerequisites aren't met.
+ * Resolve ranked traffic paths. The standard CDN pre-warming flow owns route
+ * matching, coverage selection, rendering, and cache admission.
  */
-export declare function runTPR(options: TPROptions): Promise<TPRResult>;
-//#endregion
+export declare function resolveTPRRoutes(options: TPROptions): Promise<TPRRouteResult>;
+//#endregion
+export { parseWranglerConfig };