run402 2.10.0 → 2.11.0

package/sdk/dist/namespaces/cache.js

@@ -0,0 +1,104 @@
+/**
+ * `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 { LocalError } from "../errors.js";
+export class Cache {
+    client;
+    constructor(client) {
+        this.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`.
+     */
+    async invalidate(url) {
+        const u = url instanceof URL ? url : new URL(url);
+        return this.client.request("/cache/v1/invalidate", {
+            method: "POST",
+            body: {
+                kind: "exact",
+                host: u.host.toLowerCase(),
+                path: u.pathname + (u.search || ""),
+            },
+            context: "invalidating cache (exact URL)",
+        });
+    }
+    /**
+     * Invalidate all cache rows under a path prefix on the given host.
+     */
+    async invalidatePrefix(opts) {
+        if (!opts.prefix.startsWith("/")) {
+            throw new LocalError("cache.invalidatePrefix: prefix must start with '/'", "invalidating cache (prefix)");
+        }
+        return this.client.request("/cache/v1/invalidate", {
+            method: "POST",
+            body: {
+                kind: "prefix",
+                host: opts.host.toLowerCase(),
+                prefix: opts.prefix,
+            },
+            context: "invalidating cache (prefix)",
+        });
+    }
+    /**
+     * 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.
+     */
+    async invalidateAll(opts) {
+        return this.client.request("/cache/v1/invalidate", {
+            method: "POST",
+            body: {
+                kind: "all",
+                host: opts.host.toLowerCase(),
+            },
+            context: "invalidating cache (all)",
+        });
+    }
+    /**
+     * Bulk-invalidate many absolute URLs in a single round-trip. Groups
+     * by host and issues one transaction per host.
+     */
+    async invalidateMany(urls) {
+        const normalized = urls.map((u) => (u instanceof URL ? u.toString() : u));
+        return this.client.request("/cache/v1/invalidate", {
+            method: "POST",
+            body: { kind: "many", urls: normalized },
+            context: "invalidating cache (many)",
+        });
+    }
+    /**
+     * 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.
+     */
+    async inspect(url, options = {}) {
+        const u = url instanceof URL ? url : new URL(url);
+        const params = new URLSearchParams();
+        params.set("host", u.host.toLowerCase());
+        params.set("path", u.pathname + (u.search || ""));
+        if (options.locale)
+            params.set("locale", options.locale);
+        if (options.releaseId)
+            params.set("release_id", options.releaseId);
+        const result = await this.client.request(`/cache/v1/inspect?${params.toString()}`, { context: "inspecting cache" });
+        return { ...result, url: url.toString() };
+    }
+}
+//# sourceMappingURL=cache.js.map

package/sdk/dist/namespaces/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/namespaces/cache.ts"],"names":[],"mappings":"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"}