@lobehub/edge-contract 0.2.0 → 0.3.0

package/README.md

@@ -5,6 +5,7 @@ The gateway, landing, lobehub-cloud and lobe-chat import it instead of carrying
 
 | Subpath | What it owns |
 | --- | --- |
+| `./cache-tags` | Business cache tags, raw-identifier builders, URL-segment decoding and canonical detail-tag recognition. |
 | `./landing-locales` | The URL path prefixes landing serves, and the default (`en`, at the bare path). |
 | `./seo-topics` | The discover topics landing server-renders for `?q=`. |
 | `./request-locale` | The app locale list and how a request picks one (`hl`, then the `LOBE_LOCALE` cookie, then Accept-Language). |
@@ -17,4 +18,31 @@ change every consumer will see, so update the case on purpose, in the same commi
 
 Design: `lobehub-gateway/docs/ryugi/specs/2026-11-06-logic-dedupe-design.md`.
 
+## Cache tag identities
+
+Import from `@lobehub/edge-contract/cache-tags`. `marketplaceItemTag(kind, identifier)`
+and `blogPostTag(slug)` take **raw** identifiers and encode them once. Invalid values
+(empty, over 255 UTF-16 code units, ASCII controls or unpaired surrogates) return
+`undefined`.
+
+For a URL path segment, call `decodeCacheTagPathSegment` first. It decodes once and
+returns the validated raw identifier, or `undefined` for malformed input:
+
+```ts
+marketplaceItemTag('skill', 'owner/repo');
+// landing:marketplace:skill:item:owner%2Frepo
+marketplaceItemTag('skill', 'owner%2Frepo');
+// landing:marketplace:skill:item:owner%252Frepo
+
+const identifier = decodeCacheTagPathSegment('owner%2Frepo');
+const tag = identifier === undefined ? undefined : marketplaceItemTag('skill', identifier);
+// landing:marketplace:skill:item:owner%2Frepo
+```
+
+`isCanonicalBlogPostTag` and `isCanonicalMarketplaceItemTag` recognize complete,
+canonically encoded detail tags. They do not grant purge permission: entrypoint,
+deployment, token and environment policy stay with the consumer. URL-to-tag matching,
+origin hosts, Cloudflare calls and the gateway's `torii:*` cache identities also stay
+in the gateway.
+
 Releases: bump `version`, push a `v<version>` tag; CI publishes to npm.

package/dist/cache-tags.d.ts

@@ -0,0 +1,19 @@
+/** Business cache identities shared by response tagging and purge callers. */
+export declare const LANDING_ALL_TAG = "landing:all";
+export declare const BLOG_SECTION_TAG = "landing:blog";
+export declare const BLOG_LIST_TAG = "landing:blog:list";
+export declare const PRICING_TAG = "landing:pricing";
+export declare const MARKETPLACE_KINDS: readonly ["mcp", "skill"];
+export type MarketplaceKind = (typeof MARKETPLACE_KINDS)[number];
+/** Decode a URL path segment once. Builders always take the resulting raw value. */
+export declare const decodeCacheTagPathSegment: (segment: string) => string | undefined;
+export declare const deploymentTag: (deployment: string) => string;
+export declare const marketplaceListTag: (kind: MarketplaceKind) => string;
+/** The identifier is raw: a literal `%2F` is distinct from a slash. */
+export declare const marketplaceItemTag: (kind: MarketplaceKind, identifier: string) => string | undefined;
+/** The slug is raw, including any literal percent characters. */
+export declare const blogPostTag: (slug: string) => string | undefined;
+/** Format recognition only; entrypoint and purge permissions belong to the caller. */
+export declare const isCanonicalBlogPostTag: (tag: string) => boolean;
+/** Recognize only canonical detail tags for a supported marketplace kind. */
+export declare const isCanonicalMarketplaceItemTag: (tag: string) => boolean;

package/dist/cache-tags.js

@@ -0,0 +1,56 @@
+/** Business cache identities shared by response tagging and purge callers. */
+export const LANDING_ALL_TAG = 'landing:all';
+export const BLOG_SECTION_TAG = 'landing:blog';
+export const BLOG_LIST_TAG = 'landing:blog:list';
+export const PRICING_TAG = 'landing:pricing';
+export const MARKETPLACE_KINDS = ['mcp', 'skill'];
+const BLOG_POST_PREFIX = 'landing:blog:post:';
+const encodeIdentifier = (identifier) => {
+    if (!identifier || identifier.length > 255 || /[\u0000-\u001F\u007F]/.test(identifier)) {
+        return;
+    }
+    try {
+        return encodeURIComponent(identifier);
+    }
+    catch {
+        // Lone UTF-16 surrogates cannot name a URI resource.
+        return;
+    }
+};
+/** Decode a URL path segment once. Builders always take the resulting raw value. */
+export const decodeCacheTagPathSegment = (segment) => {
+    try {
+        const raw = decodeURIComponent(segment);
+        return encodeIdentifier(raw) === undefined ? undefined : raw;
+    }
+    catch {
+        return;
+    }
+};
+export const deploymentTag = (deployment) => `landing:deployment:${deployment}`;
+export const marketplaceListTag = (kind) => `landing:marketplace:${kind}:list`;
+/** The identifier is raw: a literal `%2F` is distinct from a slash. */
+export const marketplaceItemTag = (kind, identifier) => {
+    const encoded = encodeIdentifier(identifier);
+    return encoded === undefined ? undefined : `landing:marketplace:${kind}:item:${encoded}`;
+};
+/** The slug is raw, including any literal percent characters. */
+export const blogPostTag = (slug) => {
+    const encoded = encodeIdentifier(slug);
+    return encoded === undefined ? undefined : `${BLOG_POST_PREFIX}${encoded}`;
+};
+/** Format recognition only; entrypoint and purge permissions belong to the caller. */
+export const isCanonicalBlogPostTag = (tag) => {
+    if (!tag.startsWith(BLOG_POST_PREFIX))
+        return false;
+    const slug = decodeCacheTagPathSegment(tag.slice(BLOG_POST_PREFIX.length));
+    return slug !== undefined && blogPostTag(slug) === tag;
+};
+/** Recognize only canonical detail tags for a supported marketplace kind. */
+export const isCanonicalMarketplaceItemTag = (tag) => {
+    const match = /^landing:marketplace:(mcp|skill):item:(.+)$/.exec(tag);
+    if (!match)
+        return false;
+    const identifier = decodeCacheTagPathSegment(match[2]);
+    return identifier !== undefined && marketplaceItemTag(match[1], identifier) === tag;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lobehub/edge-contract",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "One implementation of the edge logic shared by the LobeHub gateway, landing, cloud and lobe-chat, plus golden fixtures every copy is tested against.",
   "license": "MIT",
   "repository": {
@@ -10,6 +10,10 @@
   "type": "module",
   "sideEffects": false,
   "exports": {
+    "./cache-tags": {
+      "types": "./dist/cache-tags.d.ts",
+      "default": "./dist/cache-tags.js"
+    },
     "./landing-locales": {
       "types": "./dist/landing-locales.d.ts",
       "default": "./dist/landing-locales.js"