@gamesheet-inc/cache-invalidation-contract 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# Cache invalidation contract
+
+`@gamesheet-inc/cache-invalidation-contract` is this contract's only copy. The edge-router and the
+widget app import it through the app-stats-widget-next workspace; cache-invalidation-service and
+project-forge pin a published version. The data-write-gateway's Go struct
+(`src/Shared/Invalidation/message.go`) mirrors §3 by hand, so a message change lists it among the
+consumers to update. Design: `docs/superpowers/specs/2026-09-28-cache-invalidation-contract-package-design.md`
+in app-stats-widget-next, which builds on the cache-invalidation design spec §7.
+
+## 1. Cache tags (edge-router ↔ service)
+
+Every response the edge Worker caches carries `cf.cacheTags`, derived from the public URL only
+(the Worker's own 60 s build-id lookup is the single untagged entry; see the edge-router
+constraints doc):
+
+- `<env>-season-<id>`
+- `<env>-league-<id>`
+- `<env>-game-<id>`
+- `<env>-team-<id>`
+- `<env>-player-<id>`
+- `<env>-widget-config-<id>`
+- constant `<env>-stats-widget` on every cached response
+
+`<env>` is one of `dev | qa | prod` — the Worker's `TAG_ENV` var and the service's `TAG_ENV`
+var, which must match per env (the apex and `next.` prod Workers both use `prod`). Ids are decimal
+integers exactly as they appear in URLs. Tags are emitted lower-case; Cloudflare matches them
+case-insensitively. A Worker with no valid `TAG_ENV` emits no tags at all — never an unprefixed one.
+
+Why the prefix: Cloudflare cache tags are zone-wide, dev/qa/prod share `gamesheetstats.com`, and the
+three databases have overlapping numeric id spaces. Without it a dev purge of `season-19483` would
+evict prod's season 19483.
+
+`<env>-stats-widget` is a break-glass lever (purge one env's whole widget edge cache) with its own
+runbook in the service repo. It is never exposed in a UI.
+
+## 2. Generation keys (widget ↔ service; the widget's Upstash instance, per env)
+
+- `gen:season:<id>`
+- `gen:league:<id>`
+- `gen:game:<id>`
+- `gen:player:<id>`
+- `gen:widget-config:<id>`
+
+Integer counters. A missing key reads as `0`. The service is the only writer (`INCR` + `EXPIRE`
+30 days on every bump); the widget only reads. There is no `gen:team:*` — every team-scoped widget
+key also carries its season, so the season counter covers it.
+
+## 3. `cache-invalidate` topic payload v1 (publishers ↔ service)
+
+```json
+{
+	"v": 1,
+	"source": "data-write-gateway.ScheduleGame.update",
+	"reason": "optional free text",
+	"seasons": [19483],
+	"games": [123],
+	"teams": [456, 789],
+	"leagues": [],
+	"players": [],
+	"widgetConfigs": []
+}
+```
+
+Message attributes: `schema: cache-invalidate.v1`, `source`. All arrays optional. Publishers send
+integer ids; the schema also accepts numeric strings of up to 19 digits and parses them. Every
+id must parse to a positive integer of at most 9007199254740991 (`Number.MAX_SAFE_INTEGER`);
+anything else is refused.
+Publishers never send tags or keys.
+
+## Exports
+
+- Tags: `TAG_ENVS`, `TagEnv`, `parseTagEnv`, `SCOPE_TAG_KINDS`, `ScopeTagKind`, `STATS_WIDGET_TAG`,
+  `tagFor`, `breakGlassTag`.
+- URL rules: `ScopeRef`, `resolveScopes`, `resolveCacheTags`.
+- Generation keys: `GEN_KINDS`, `GenKind`, `GEN_KEY_PREFIX`, `genKeyFor`, `GEN_TTL_SECONDS`.
+- Message v1: `CACHE_INVALIDATE_TOPIC`, `CACHE_INVALIDATE_SCHEMA`, `MESSAGE_FIELDS`, `MessageField`,
+  `ScopeIdSchema`, `CacheInvalidateV1Schema`, `CacheInvalidateV1`. zod is a required peer.
+
+## Changelog
+
+A change to any exported value or rule is a new version. Each entry names the consumers that must
+move: the edge-router and the widget app (same PR, through the workspace), cache-invalidation-service
+and project-forge (a pin bump), and the data-write-gateway's Go struct (by hand, for a message
+change).
+
+- **0.1.0** — First release. Moves the edge-router's `cache-tags.ts`, the widget's generation-key
+  names and the service's `contract.ts`, `idSchema` and `cacheInvalidateV1Schema` here, with no
+  change to any tag, key or accepted message.

package/dist/gen-keys.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The generation counters the service bumps and the widget reads (contract
+ * §2), keyed `gen:<kind>:<id>`; a missing key reads as 0. There is no team
+ * counter: every team-scoped widget key also carries its season.
+ */
+export declare const GEN_KINDS: readonly ["season", "league", "game", "player", "widget-config"];
+export type GenKind = (typeof GEN_KINDS)[number];
+export declare const GEN_KEY_PREFIX = "gen";
+/** The service refreshes this expiry on every bump. */
+export declare const GEN_TTL_SECONDS: number;
+export declare function genKeyFor(kind: GenKind, id: number | string): string;

package/dist/gen-keys.js

@@ -0,0 +1,18 @@
+/**
+ * The generation counters the service bumps and the widget reads (contract
+ * §2), keyed `gen:<kind>:<id>`; a missing key reads as 0. There is no team
+ * counter: every team-scoped widget key also carries its season.
+ */
+export const GEN_KINDS = [
+    "season",
+    "league",
+    "game",
+    "player",
+    "widget-config",
+];
+export const GEN_KEY_PREFIX = "gen";
+/** The service refreshes this expiry on every bump. */
+export const GEN_TTL_SECONDS = 30 * 24 * 60 * 60;
+export function genKeyFor(kind, id) {
+    return `${GEN_KEY_PREFIX}:${kind}:${id}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./tags.ts";
+export * from "./url-rules.ts";
+export * from "./gen-keys.ts";
+export * from "./message.ts";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./tags.js";
+export * from "./url-rules.js";
+export * from "./gen-keys.js";
+export * from "./message.js";

package/dist/message.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { ScopeTagKind } from "./tags.ts";
+export declare const CACHE_INVALIDATE_TOPIC = "cache-invalidate";
+export declare const CACHE_INVALIDATE_SCHEMA = "cache-invalidate.v1";
+/** Each scope kind's id-list field in the message (contract §3). */
+export declare const MESSAGE_FIELDS: {
+    readonly season: "seasons";
+    readonly league: "leagues";
+    readonly game: "games";
+    readonly team: "teams";
+    readonly player: "players";
+    readonly "widget-config": "widgetConfigs";
+};
+export type MessageField = (typeof MESSAGE_FIELDS)[ScopeTagKind];
+/** An id: a positive safe integer, or a numeric string of up to 19 digits that parses to one. */
+export declare const ScopeIdSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodNumber>;
+/** The `cache-invalidate` message v1 (contract §3). Every id list defaults to empty. */
+export declare const CacheInvalidateV1Schema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    source: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+    seasons: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodNumber>>>;
+    games: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodNumber>>>;
+    teams: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodNumber>>>;
+    leagues: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodNumber>>>;
+    players: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodNumber>>>;
+    widgetConfigs: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodNumber>>>;
+}, z.core.$strip>;
+export type CacheInvalidateV1 = z.infer<typeof CacheInvalidateV1Schema>;

package/dist/message.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+export const CACHE_INVALIDATE_TOPIC = "cache-invalidate";
+export const CACHE_INVALIDATE_SCHEMA = "cache-invalidate.v1";
+/** Each scope kind's id-list field in the message (contract §3). */
+export const MESSAGE_FIELDS = {
+    season: "seasons",
+    league: "leagues",
+    game: "games",
+    team: "teams",
+    player: "players",
+    "widget-config": "widgetConfigs",
+};
+/** An id: a positive safe integer, or a numeric string of up to 19 digits that parses to one. */
+export const ScopeIdSchema = z
+    .union([
+    z.number().int().positive(),
+    z
+        .string()
+        .regex(/^\d{1,19}$/)
+        .transform((value) => Number.parseInt(value, 10)),
+])
+    .pipe(z.number().int().positive());
+/** The `cache-invalidate` message v1 (contract §3). Every id list defaults to empty. */
+export const CacheInvalidateV1Schema = z.object({
+    v: z.literal(1),
+    source: z.string().min(1),
+    reason: z.string().optional(),
+    seasons: z.array(ScopeIdSchema).default([]),
+    games: z.array(ScopeIdSchema).default([]),
+    teams: z.array(ScopeIdSchema).default([]),
+    leagues: z.array(ScopeIdSchema).default([]),
+    players: z.array(ScopeIdSchema).default([]),
+    widgetConfigs: z.array(ScopeIdSchema).default([]),
+});

package/dist/tags.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Cache-tag vocabulary for purge-by-tag invalidation (contract §1). Every tag
+ * is prefixed with its env, because Cloudflare tags are zone-wide and dev, qa
+ * and prod share one zone with overlapping numeric id spaces.
+ */
+export declare const TAG_ENVS: readonly ["dev", "qa", "prod"];
+export type TagEnv = (typeof TAG_ENVS)[number];
+export declare const STATS_WIDGET_TAG = "stats-widget";
+export declare const SCOPE_TAG_KINDS: readonly ["season", "league", "game", "team", "player", "widget-config"];
+export type ScopeTagKind = (typeof SCOPE_TAG_KINDS)[number];
+export declare function parseTagEnv(raw: string | undefined): TagEnv | null;
+/** `<env>-<kind>-<id>`, the id as given. */
+export declare function tagFor(env: TagEnv, kind: ScopeTagKind, id: number | string): string;
+/** The whole-widget tag: a break-glass lever with its own runbook, never exposed in a UI. */
+export declare function breakGlassTag(env: TagEnv): string;

package/dist/tags.js

@@ -0,0 +1,26 @@
+/**
+ * Cache-tag vocabulary for purge-by-tag invalidation (contract §1). Every tag
+ * is prefixed with its env, because Cloudflare tags are zone-wide and dev, qa
+ * and prod share one zone with overlapping numeric id spaces.
+ */
+export const TAG_ENVS = ["dev", "qa", "prod"];
+export const STATS_WIDGET_TAG = "stats-widget";
+export const SCOPE_TAG_KINDS = [
+    "season",
+    "league",
+    "game",
+    "team",
+    "player",
+    "widget-config",
+];
+export function parseTagEnv(raw) {
+    return raw === "dev" || raw === "qa" || raw === "prod" ? raw : null;
+}
+/** `<env>-<kind>-<id>`, the id as given. */
+export function tagFor(env, kind, id) {
+    return `${env}-${kind}-${id}`;
+}
+/** The whole-widget tag: a break-glass lever with its own runbook, never exposed in a UI. */
+export function breakGlassTag(env) {
+    return `${env}-${STATS_WIDGET_TAG}`;
+}

package/dist/url-rules.d.ts

@@ -0,0 +1,15 @@
+import { type ScopeTagKind, type TagEnv } from "./tags.ts";
+/** A scope a public widget URL is cached under: its tag kind, and its id exactly as the URL spells it. */
+export type ScopeRef = {
+    kind: ScopeTagKind;
+    id: string;
+};
+/**
+ * The edge-router's rules (contract §1): every scope a public URL is cached
+ * under, from its path and query only, never from origin headers. The result
+ * is deduplicated and in the order the scopes' tags sort, so
+ * `resolveCacheTags` keeps the router's exact output.
+ */
+export declare function resolveScopes(url: URL): ScopeRef[];
+/** The break-glass tag first, then each scope's tag in sorted order, ids exactly as the URL spells them. */
+export declare function resolveCacheTags(url: URL, env: TagEnv): string[];

package/dist/url-rules.js

@@ -0,0 +1,107 @@
+import { breakGlassTag, tagFor, } from "./tags.js";
+const NUMERIC_ID = /^\d{1,19}$/;
+const PAGE_PREFIX_KINDS = new Map([
+    ["seasons", "season"],
+    ["leagues", "league"],
+]);
+const PAGE_SUBSEGMENT_KINDS = new Map([
+    ["teams", "team"],
+    ["games", "game"],
+    ["players", "player"],
+    ["goalies", "player"],
+]);
+const API_SEASON_AT_2 = new Set([
+    "standings",
+    "season-info",
+    "season-frozen",
+    "season-divisions",
+    "unified-games",
+    "brackets",
+]);
+const API_PLAYER_GROUPS = new Set(["players", "goalies"]);
+const API_PLAYER_SUBROUTES = new Set([
+    "career",
+    "career-raw",
+    "gamelog",
+    "overview",
+]);
+function scopeRef(kind, id) {
+    return id !== undefined && NUMERIC_ID.test(id) ? { kind, id } : null;
+}
+function pageScopes(segments, search) {
+    const rootKind = PAGE_PREFIX_KINDS.get(segments[0] ?? "");
+    if (!rootKind)
+        return [];
+    const refs = [
+        scopeRef(rootKind, segments[1]),
+        scopeRef("widget-config", search.get("configuration") ?? undefined),
+    ];
+    const subKind = PAGE_SUBSEGMENT_KINDS.get(segments[2] ?? "");
+    if (subKind)
+        refs.push(scopeRef(subKind, segments[3]));
+    return refs;
+}
+function apiScopes(segments, search) {
+    const [, group, a, b] = segments;
+    if (group === undefined)
+        return [];
+    if (API_SEASON_AT_2.has(group))
+        return [scopeRef("season", a)];
+    if (group === "teams")
+        return [scopeRef("season", a), scopeRef("team", b)];
+    if (group === "widget-config") {
+        return a === "season-default"
+            ? [scopeRef("season", b)]
+            : [scopeRef("widget-config", a)];
+    }
+    if (group === "leagues")
+        return [scopeRef("league", a)];
+    if (group === "games") {
+        if (a === "game")
+            return [scopeRef("game", b)];
+        if (a === "season")
+            return [scopeRef("season", b)];
+        return [];
+    }
+    if (API_PLAYER_GROUPS.has(group)) {
+        if (a === "standings")
+            return [scopeRef("season", b)];
+        if (a !== undefined && API_PLAYER_SUBROUTES.has(a)) {
+            return [
+                scopeRef("player", b),
+                scopeRef("season", search.get("seasonId") ?? undefined),
+            ];
+        }
+        return [];
+    }
+    return [];
+}
+function scopeKey(ref) {
+    return `${ref.kind}-${ref.id}`;
+}
+/**
+ * The edge-router's rules (contract §1): every scope a public URL is cached
+ * under, from its path and query only, never from origin headers. The result
+ * is deduplicated and in the order the scopes' tags sort, so
+ * `resolveCacheTags` keeps the router's exact output.
+ */
+export function resolveScopes(url) {
+    const segments = url.pathname.split("/").filter(Boolean);
+    const found = segments[0] === "api"
+        ? apiScopes(segments, url.searchParams)
+        : pageScopes(segments, url.searchParams);
+    const unique = new Map();
+    for (const ref of found)
+        if (ref)
+            unique.set(scopeKey(ref), ref);
+    return [...unique.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([, ref]) => ref);
+}
+/** The break-glass tag first, then each scope's tag in sorted order, ids exactly as the URL spells them. */
+export function resolveCacheTags(url, env) {
+    return [
+        breakGlassTag(env),
+        ...resolveScopes(url).map((ref) => tagFor(env, ref.kind, ref.id)),
+    ];
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@gamesheet-inc/cache-invalidation-contract",
+  "version": "0.1.0",
+  "description": "The stats widget's cache-invalidation contract: cache tags and URL rules, generation keys, and the cache-invalidate message v1.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GameSheet-Inc/app-stats-widget-next.git",
+    "directory": "packages/cache-invalidation-contract"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.2",
+    "oxfmt": "^0.36.0",
+    "oxlint": "^1.79.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "zod": "^4.3.6"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "type-check": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "oxlint",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check"
+  }
+}