@caelo-cms/shared 0.12.9 → 0.12.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/dist/ai-cost.d.ts +146 -0
  2. package/dist/ai-cost.d.ts.map +1 -0
  3. package/dist/ai-cost.js +182 -0
  4. package/dist/ai-cost.js.map +1 -0
  5. package/dist/ai-tools.d.ts +1 -1
  6. package/dist/build-page.d.ts +2 -2
  7. package/dist/cap-failures.d.ts.map +1 -1
  8. package/dist/cap-failures.js +7 -5
  9. package/dist/cap-failures.js.map +1 -1
  10. package/dist/change-journal.d.ts.map +1 -1
  11. package/dist/change-journal.js +16 -0
  12. package/dist/change-journal.js.map +1 -1
  13. package/dist/content.d.ts +3 -3
  14. package/dist/embedding-models.d.ts +95 -0
  15. package/dist/embedding-models.d.ts.map +1 -0
  16. package/dist/embedding-models.js +60 -0
  17. package/dist/embedding-models.js.map +1 -0
  18. package/dist/index.d.ts +5 -0
  19. package/dist/index.d.ts.map +1 -1
  20. package/dist/index.js +5 -0
  21. package/dist/index.js.map +1 -1
  22. package/dist/module-id-tag.d.ts +13 -0
  23. package/dist/module-id-tag.d.ts.map +1 -1
  24. package/dist/module-id-tag.js +24 -2
  25. package/dist/module-id-tag.js.map +1 -1
  26. package/dist/preview-compose.d.ts +17 -1
  27. package/dist/preview-compose.d.ts.map +1 -1
  28. package/dist/preview-compose.js +10 -3
  29. package/dist/preview-compose.js.map +1 -1
  30. package/dist/search-feed.d.ts +123 -0
  31. package/dist/search-feed.d.ts.map +1 -0
  32. package/dist/search-feed.js +152 -0
  33. package/dist/search-feed.js.map +1 -0
  34. package/dist/seo.d.ts +19 -0
  35. package/dist/seo.d.ts.map +1 -1
  36. package/dist/seo.js +12 -1
  37. package/dist/seo.js.map +1 -1
  38. package/dist/site-security-headers.d.ts +2 -2
  39. package/dist/stage-status.d.ts +10 -5
  40. package/dist/stage-status.d.ts.map +1 -1
  41. package/dist/stage-status.js +27 -1
  42. package/dist/stage-status.js.map +1 -1
  43. package/dist/static-files.d.ts.map +1 -1
  44. package/dist/static-files.js +1 -0
  45. package/dist/static-files.js.map +1 -1
  46. package/dist/version.d.ts +2 -2
  47. package/dist/version.d.ts.map +1 -1
  48. package/dist/version.js +1 -1
  49. package/dist/version.js.map +1 -1
  50. package/dist/visitor-ai-origin.d.ts +41 -0
  51. package/dist/visitor-ai-origin.d.ts.map +1 -0
  52. package/dist/visitor-ai-origin.js +65 -0
  53. package/dist/visitor-ai-origin.js.map +1 -0
  54. package/package.json +8 -1
  55. package/src/ai-cost.test.ts +81 -0
  56. package/src/ai-cost.ts +288 -0
  57. package/src/cap-failures.ts +7 -5
  58. package/src/change-journal.ts +31 -0
  59. package/src/embedding-models.test.ts +37 -0
  60. package/src/embedding-models.ts +147 -0
  61. package/src/index.ts +9 -0
  62. package/src/module-id-tag.test.ts +27 -1
  63. package/src/module-id-tag.ts +29 -2
  64. package/src/preview-compose.test.ts +21 -0
  65. package/src/preview-compose.ts +33 -4
  66. package/src/search-feed.test.ts +115 -0
  67. package/src/search-feed.ts +180 -0
  68. package/src/seo.test.ts +13 -0
  69. package/src/seo.ts +26 -1
  70. package/src/stage-status.ts +29 -1
  71. package/src/static-files.ts +1 -0
  72. package/src/version.ts +1 -1
  73. package/src/visitor-ai-origin.ts +86 -0
@@ -0,0 +1,180 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ /**
4
+ * The site's feed of its latest changes and the two pings that announce a
5
+ * Publish live to search engines (docs/dev/search-engine-feed.md).
6
+ *
7
+ * - `/feed.xml` — Atom 1.0: the {@link FEED_ENTRY_LIMIT} pages whose live
8
+ * content changed last, each with the date it changed. Search engines
9
+ * read a sitemap for the whole site and a feed for what is new; Google
10
+ * accepts both and recommends both.
11
+ * - WebSub — the feed names {@link WEBSUB_HUB_URL} as its hub; after a
12
+ * Publish live the admin tells the hub the feed changed, the hub fetches
13
+ * it and pushes it to its subscribers.
14
+ * - IndexNow — the admin submits the URLs a Publish live changed; every
15
+ * participating engine (Bing, Yandex, Seznam, Naver, Yep, …) shares one
16
+ * submission. Google does not take part. The site proves the host with a
17
+ * key file every build serves at `/<key>.txt`.
18
+ *
19
+ * A page's "change" is a change of what the page itself shows: its title,
20
+ * its description and the text, links and images of its body. A header or
21
+ * footer edit shown on every page is not a change of every page.
22
+ */
23
+
24
+ import { z } from "zod";
25
+ import { trimSlashes } from "./url.js";
26
+
27
+ /** The feed's path at the site root. */
28
+ export const FEED_FILE = "feed.xml";
29
+
30
+ /** The served `Content-Type` of the feed. */
31
+ export const FEED_CONTENT_TYPE = "application/atom+xml; charset=utf-8";
32
+
33
+ /** Entries the feed carries: the pages changed last. The sitemap lists the rest. */
34
+ export const FEED_ENTRY_LIMIT = 100;
35
+
36
+ /** Google's public WebSub hub (pubsubhubbub.appspot.com, WebSub / PubSubHubbub 0.4). */
37
+ export const WEBSUB_HUB_URL = "https://pubsubhubbub.appspot.com/";
38
+
39
+ /** The shared IndexNow endpoint: one submission reaches every participating engine. */
40
+ export const INDEXNOW_ENDPOINT = "https://api.indexnow.org/indexnow";
41
+
42
+ /** URLs IndexNow takes in one submission. */
43
+ export const INDEXNOW_MAX_URLS = 10_000;
44
+
45
+ /** The IndexNow key file a build serves for `key`, relative to the site root. */
46
+ export function indexNowKeyFile(key: string): string {
47
+ return `${key}.txt`;
48
+ }
49
+
50
+ /** The absolute URL of the site's feed. */
51
+ export function siteFeedUrl(siteBaseUrl: string): string {
52
+ return `${trimSlashes(siteBaseUrl)}/${FEED_FILE}`;
53
+ }
54
+
55
+ /**
56
+ * The feed's title and author: the site as it is addressed, its host
57
+ * (`www.example.com`). Always known — a build needs the base URL — so the
58
+ * feed never waits for authoring data a site may not have (CLAUDE.md §2).
59
+ */
60
+ export function siteFeedTitle(siteBaseUrl: string): string {
61
+ return new URL(siteBaseUrl).host;
62
+ }
63
+
64
+ /** The feed every page of a site links, or null when the feed is off. */
65
+ export function siteFeedLink(
66
+ feedEnabled: boolean,
67
+ siteBaseUrl: string,
68
+ ): { readonly url: string; readonly title: string } | null {
69
+ return feedEnabled ? { url: siteFeedUrl(siteBaseUrl), title: siteFeedTitle(siteBaseUrl) } : null;
70
+ }
71
+
72
+ /**
73
+ * How a page's live state changed (`live_page_versions.kind`):
74
+ * - `baseline` — what was live already when the feed shipped; recorded
75
+ * once, never announced (IndexNow asks not to submit old changes).
76
+ * - `added` — the page went live (first publication, published again,
77
+ * indexable again).
78
+ * - `changed` — what it shows changed.
79
+ * - `moved` — it is live at another URL (and maybe changed too).
80
+ * - `removed` — no longer live (unpublished, deleted, noindex).
81
+ * - `restored` — a rollback put an earlier state back (log only).
82
+ * - `redated` — the same content is served with another date: a rollback
83
+ * or a Publish live put back files that show it (log only, never
84
+ * announced: nothing changed live).
85
+ */
86
+ export const PAGE_VERSION_KINDS = [
87
+ "baseline",
88
+ "added",
89
+ "changed",
90
+ "moved",
91
+ "removed",
92
+ "restored",
93
+ "redated",
94
+ ] as const;
95
+ export type PageVersionKind = (typeof PAGE_VERSION_KINDS)[number];
96
+
97
+ /** The kinds a build reports; `restored` is written by a rollback only. */
98
+ export const BUILD_CHANGE_KINDS = ["baseline", "added", "changed", "moved", "removed"] as const;
99
+ export type BuildChangeKind = (typeof BUILD_CHANGE_KINDS)[number];
100
+
101
+ /** Kinds announced to search engines: a change of what is live, not the baseline or a new date. */
102
+ export function isAnnouncedKind(kind: PageVersionKind): boolean {
103
+ return kind !== "baseline" && kind !== "redated";
104
+ }
105
+
106
+ /** One page whose live state a build changes (or records as the baseline). */
107
+ export const pageChangeSchema = z
108
+ .object({
109
+ pageId: z.string().uuid(),
110
+ kind: z.enum(BUILD_CHANGE_KINDS),
111
+ /** Where the page is live after the build; null when it is removed. */
112
+ url: z.string().max(2048).nullable(),
113
+ /** sha256 hex of what the page shows; null when it is removed. */
114
+ fingerprint: z
115
+ .string()
116
+ .regex(/^[0-9a-f]{64}$/)
117
+ .nullable(),
118
+ /**
119
+ * sha256 hex of what the plugins baked into the page show (approved
120
+ * comments, say); null when none bakes into it, or the page is removed.
121
+ */
122
+ pluginFingerprint: z
123
+ .string()
124
+ .regex(/^[0-9a-f]{64}$/)
125
+ .nullable(),
126
+ /** The title and meta description it is published with; null when removed. */
127
+ title: z.string().max(1000).nullable(),
128
+ summary: z.string().max(2000).nullable(),
129
+ /** Where it was live before; null when it was not. */
130
+ prevUrl: z.string().max(2048).nullable(),
131
+ /** The date the feed and the sitemap show for it (ISO). */
132
+ changedAt: z.string().datetime({ offset: true }),
133
+ })
134
+ .strict()
135
+ .refine((c) => (c.url === null) === (c.fingerprint === null), "url and fingerprint go together")
136
+ .refine((c) => (c.kind === "removed") === (c.url === null), "only a removed page has no url")
137
+ .refine(
138
+ (c) => c.url !== null || c.pluginFingerprint === null,
139
+ "a removed page has no plugin fingerprint",
140
+ )
141
+ .refine(
142
+ (c) => (c.url === null) === (c.title === null) && (c.url === null) === (c.summary === null),
143
+ "a live page has a title and a summary, a removed one neither",
144
+ );
145
+ export type PageChange = z.infer<typeof pageChangeSchema>;
146
+
147
+ /**
148
+ * What a build reports about its feed and its pages
149
+ * (`GenerateResult.searchFeed`), recorded with the run.
150
+ */
151
+ export const buildSearchFeedSchema = z
152
+ .object({
153
+ /** The `live_page_versions` head the pages were compared against; null: the log was empty. */
154
+ base: z.number().int().nonnegative().nullable(),
155
+ /** The pages whose live state the build changes, plus the baseline. */
156
+ changes: z.array(pageChangeSchema).max(500_000),
157
+ /** The feed the build serves (absolute URL); null when the feed is off. */
158
+ feedUrl: z.string().max(2048).nullable(),
159
+ /** The IndexNow key file the build serves; null when IndexNow is off. */
160
+ indexNowKey: z
161
+ .string()
162
+ .regex(/^[A-Za-z0-9-]{8,128}$/)
163
+ .nullable(),
164
+ })
165
+ .strict();
166
+ export type BuildSearchFeed = z.infer<typeof buildSearchFeedSchema>;
167
+
168
+ /**
169
+ * Can search engines reach `host`? False for names that only resolve inside
170
+ * a network or on one machine (localhost, `.local`, `.internal`, the
171
+ * reserved test names) and for IP literals: a ping for such a site would
172
+ * only make the engine fetch an address it cannot reach.
173
+ */
174
+ export function isPublicSiteHost(host: string): boolean {
175
+ const h = host.toLowerCase().replace(/\.$/, "");
176
+ if (h.length === 0 || !h.includes(".")) return false;
177
+ if (h.startsWith("[") || /^\d{1,3}(?:\.\d{1,3}){3}$/.test(h)) return false;
178
+ const reserved = ["localhost", "local", "internal", "test", "example", "invalid", "home.arpa"];
179
+ return !reserved.some((r) => h === r || h.endsWith(`.${r}`));
180
+ }
package/src/seo.test.ts CHANGED
@@ -125,8 +125,21 @@ describe("renderSeoHead", () => {
125
125
  noindex: false,
126
126
  ogImageUrl: null,
127
127
  organization: {},
128
+ feed: null,
128
129
  };
129
130
 
131
+ it("links the site's feed when it has one, and nothing when it has none", () => {
132
+ expect(
133
+ renderSeoHead({
134
+ ...base,
135
+ feed: { url: "https://example.com/feed.xml", title: "example.com" },
136
+ }),
137
+ ).toContain(
138
+ '<link rel="alternate" type="application/atom+xml" title="example.com" href="https://example.com/feed.xml" />',
139
+ );
140
+ expect(renderSeoHead(base)).not.toContain("application/atom+xml");
141
+ });
142
+
130
143
  it("#551: omits canonical, og:url and the JSON-LD url when the base URL is unset", () => {
131
144
  const head = renderSeoHead({ ...base, canonical: null });
132
145
  expect(head).not.toContain('rel="canonical"');
package/src/seo.ts CHANGED
@@ -83,6 +83,10 @@ export const siteDefaultsSetSeoInputSchema = z
83
83
  .max(2048)
84
84
  .url("siteBaseUrl must be an absolute URL (https://example.com)"),
85
85
  sitemapEnabled: z.boolean(),
86
+ /** Atom feed of the latest changes + the WebSub ping (docs/dev/search-engine-feed.md). */
87
+ feedEnabled: z.boolean(),
88
+ /** IndexNow submissions of the URLs a Publish live changed. */
89
+ indexNowEnabled: z.boolean(),
86
90
  organizationJson: organizationJsonSchema.default({}),
87
91
  })
88
92
  .strict();
@@ -98,6 +102,8 @@ export const siteSeoProposalInputSchema = z
98
102
  .object({
99
103
  siteBaseUrl: z.string().min(1).max(2048).optional(),
100
104
  sitemapEnabled: z.boolean().optional(),
105
+ feedEnabled: z.boolean().optional(),
106
+ indexNowEnabled: z.boolean().optional(),
101
107
  organizationJson: organizationJsonSchema.optional(),
102
108
  })
103
109
  .strict()
@@ -105,8 +111,10 @@ export const siteSeoProposalInputSchema = z
105
111
  (v) =>
106
112
  v.siteBaseUrl !== undefined ||
107
113
  v.sitemapEnabled !== undefined ||
114
+ v.feedEnabled !== undefined ||
115
+ v.indexNowEnabled !== undefined ||
108
116
  v.organizationJson !== undefined,
109
- "pass at least one of `siteBaseUrl`, `sitemapEnabled`, `organizationJson`",
117
+ "pass at least one of `siteBaseUrl`, `sitemapEnabled`, `feedEnabled`, `indexNowEnabled`, `organizationJson`",
110
118
  );
111
119
  export type SiteSeoProposalInput = z.infer<typeof siteSeoProposalInputSchema>;
112
120
 
@@ -219,6 +227,12 @@ export interface PageSeoRow {
219
227
  export interface SiteSeoSettings {
220
228
  siteBaseUrl: string;
221
229
  sitemapEnabled: boolean;
230
+ /** `site_defaults.feed_enabled` — write `/feed.xml` and link it (docs/dev/search-engine-feed.md). */
231
+ feedEnabled: boolean;
232
+ /** `site_defaults.indexnow_enabled` — serve the IndexNow key file and submit changed URLs. */
233
+ indexNowEnabled: boolean;
234
+ /** `site_defaults.indexnow_key` — public by design, served at `/<key>.txt`. */
235
+ indexNowKey: string;
222
236
  /** `site_defaults.site_language` — the `<html lang>` of every page no
223
237
  * plugin assigns its own locale to (see document-language.ts). Always
224
238
  * set here: the static generator refuses to build while it is NULL. */
@@ -290,6 +304,12 @@ export interface SeoMetaInput {
290
304
  noindex: boolean;
291
305
  ogImageUrl: string | null;
292
306
  organization: SiteSeoSettings["organization"];
307
+ /**
308
+ * The site's Atom feed (`<link rel="alternate" type="application/atom+xml">`),
309
+ * or null when the site has none ({@link siteFeedUrl}). Every page links it,
310
+ * so feed readers and crawlers find it from any page.
311
+ */
312
+ feed: { readonly url: string; readonly title: string } | null;
293
313
  /**
294
314
  * #1142 — the breadcrumb trail the page SHOWS (home → current), as
295
315
  * built by {@link breadcrumbJsonLdItems}; null or empty = the page shows
@@ -351,6 +371,11 @@ export function renderSeoHead(input: SeoMetaInput): string {
351
371
  if (input.noindex) {
352
372
  lines.push(`<meta name="robots" content="noindex" />`);
353
373
  }
374
+ if (input.feed) {
375
+ lines.push(
376
+ `<link rel="alternate" type="application/atom+xml" title="${enc(input.feed.title)}" href="${enc(input.feed.url)}" />`,
377
+ );
378
+ }
354
379
  // Open Graph
355
380
  lines.push(`<meta property="og:title" content="${enc(input.title)}" />`);
356
381
  if (input.metaDescription) {
@@ -61,6 +61,21 @@ export const stageStatusRunSchema = z.object({
61
61
  eta: stageEtaSchema.nullable(),
62
62
  /** Why there is no estimate for a queued or running run; null otherwise. */
63
63
  etaUnavailable: z.string().nullable(),
64
+ /**
65
+ * #1648 — the search indexes (plugin collections) this Stage built, once
66
+ * its build succeeded: Publish live waits for every one to be ready.
67
+ * Absent for a run that has none (no plugin keeps a collection) or no row yet.
68
+ */
69
+ searchIndexes: z
70
+ .array(
71
+ z.object({
72
+ plugin: z.string(),
73
+ collection: z.string(),
74
+ state: z.enum(["pending", "ready", "failed"]),
75
+ error: z.string().nullable(),
76
+ }),
77
+ )
78
+ .optional(),
64
79
  });
65
80
  export type StageStatusRun = z.infer<typeof stageStatusRunSchema>;
66
81
 
@@ -93,6 +108,19 @@ export function describeStageEta(run: Pick<StageStatusRun, "eta" | "etaUnavailab
93
108
  * about 1 min 40 s left (from this run's pace)" or "Failed in generator
94
109
  * after 1 min 34 s: <reason>".
95
110
  */
111
+ /** The search indexes' part of a succeeded Stage's line ("" without any). */
112
+ function describeSearchIndexes(run: StageStatusRun): string {
113
+ const indexes = run.searchIndexes ?? [];
114
+ if (indexes.length === 0) return "";
115
+ const failed = indexes.filter((i) => i.state === "failed");
116
+ const pending = indexes.filter((i) => i.state === "pending");
117
+ if (failed.length > 0)
118
+ return `; search index FAILED (${failed.map((i) => `${i.plugin}/${i.collection}: ${i.error ?? "no reason recorded"}`).join("; ")}) — Publish live is refused until a Stage builds it`;
119
+ if (pending.length > 0)
120
+ return `; search index still building (${pending.map((i) => `${i.plugin}/${i.collection}`).join(", ")}) — Publish live waits for it`;
121
+ return "; search index ready";
122
+ }
123
+
96
124
  export function describeStageRun(run: StageStatusRun): string {
97
125
  const n = (v: number) => v.toLocaleString("en-US");
98
126
  switch (run.phase) {
@@ -105,7 +133,7 @@ export function describeStageRun(run: StageStatusRun): string {
105
133
  case "publishing":
106
134
  return `All ${n(run.pagesTotal ?? 0)} pages built, publishing to staging — ${describeStageEta(run)}`;
107
135
  case "succeeded":
108
- return `Succeeded in ${formatStageDuration(run.elapsedMs)}${run.pagesTotal === null ? "" : ` (${n(run.pagesTotal)} pages)`}`;
136
+ return `Succeeded in ${formatStageDuration(run.elapsedMs)}${run.pagesTotal === null ? "" : ` (${n(run.pagesTotal)} pages)`}${describeSearchIndexes(run)}`;
109
137
  case "failed":
110
138
  return `Failed${run.failedPhase ? ` in ${run.failedPhase}` : ""} after ${formatStageDuration(run.elapsedMs)}: ${run.error ?? "no reason recorded"}`;
111
139
  }
@@ -100,6 +100,7 @@ const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._~-]*$/;
100
100
  const RESERVED_ROOT_FILES: ReadonlySet<string> = new Set([
101
101
  "robots.txt",
102
102
  "sitemap.xml",
103
+ "feed.xml",
103
104
  "routing-manifest.json",
104
105
  "cdn_manifest.json",
105
106
  "render-deps.json",
package/src/version.ts CHANGED
@@ -22,7 +22,7 @@
22
22
  * follow standard SemVer.
23
23
  */
24
24
 
25
- export const CAELO_VERSION = "0.12.9";
25
+ export const CAELO_VERSION = "0.12.11";
26
26
 
27
27
  /**
28
28
  * Deprecated alias for back-compat — early P17 work spelled this
@@ -0,0 +1,86 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ /**
4
+ * Where a visitor's browser streams an AI conversation from (#1654).
5
+ *
6
+ * On `gcp` (load balancer) and self-hosted (Caddy) the site's own origin
7
+ * streams: `/api/*` reaches the gateway unbuffered. On `gcp-firebase` the
8
+ * Firebase Hosting rewrite of `/api/**` buffers a response until it ends,
9
+ * so the widget streams from the gateway's own run.app origin instead
10
+ * (with CORS for the site's origins), the one Cloud Run gives every
11
+ * service: `https://<service>-<project number>.<region>.run.app`.
12
+ *
13
+ * Nothing about it is configured: the service name and region are the
14
+ * env the install already sets (`CAELO_GATEWAY_SERVICE`,
15
+ * `CAELO_GATEWAY_REGION` on the admin; Cloud Run's own `K_SERVICE` on a
16
+ * gateway), the project number and region come from the metadata server
17
+ * of the Cloud Run instance. `CAELO_VISITOR_AI_STREAM_ORIGIN` overrides
18
+ * everything (tests, an install behind its own streaming proxy); an empty
19
+ * value means the site's own origin.
20
+ */
21
+
22
+ /** The override; empty: the site's own origin. */
23
+ export const VISITOR_AI_STREAM_ORIGIN_ENV = "CAELO_VISITOR_AI_STREAM_ORIGIN";
24
+
25
+ /** The deterministic URL Cloud Run gives a service. */
26
+ export function cloudRunServiceOrigin(
27
+ service: string,
28
+ projectNumber: string,
29
+ region: string,
30
+ ): string {
31
+ if (
32
+ !/^[a-z][a-z0-9-]{0,62}$/.test(service) ||
33
+ !/^\d{1,20}$/.test(projectNumber) ||
34
+ !/^[a-z]+-[a-z]+\d+$/.test(region)
35
+ )
36
+ throw new Error(`not a Cloud Run service address: ${service} / ${projectNumber} / ${region}`);
37
+ return `https://${service}-${projectNumber}.${region}.run.app`;
38
+ }
39
+
40
+ /** The project number and region of this Cloud Run instance, from the metadata server. */
41
+ export async function cloudRunInstanceLocation(
42
+ fetchFn: typeof fetch = fetch,
43
+ ): Promise<{ readonly projectNumber: string; readonly region: string }> {
44
+ const res = await fetchFn("http://metadata.google.internal/computeMetadata/v1/instance/region", {
45
+ headers: { "Metadata-Flavor": "Google" },
46
+ signal: AbortSignal.timeout(3000),
47
+ });
48
+ if (!res.ok) throw new Error(`metadata server: instance/region returned HTTP ${res.status}`);
49
+ // projects/<number>/regions/<region>
50
+ const m = /^projects\/(\d+)\/regions\/([a-z]+-[a-z]+\d+)$/.exec((await res.text()).trim());
51
+ if (!m) throw new Error("metadata server: instance/region has an unknown shape");
52
+ return { projectNumber: m[1] as string, region: m[2] as string };
53
+ }
54
+
55
+ /**
56
+ * The origin to stream from, or null for the site's own. `service` and
57
+ * `region` name the gateway (the admin's env); without `region` the
58
+ * instance's own (a gateway asking about itself). The staging gateway
59
+ * always streams on its own origin: it serves the staged site itself, with
60
+ * no Firebase rewrite in front to buffer, and its gate admits only requests
61
+ * carrying the operator's staging cookie, which a run.app request would not.
62
+ */
63
+ export async function visitorAiStreamOrigin(
64
+ env: Readonly<Record<string, string | undefined>>,
65
+ gateway: {
66
+ readonly service: string | undefined;
67
+ readonly region?: string | undefined;
68
+ readonly environment?: "live" | "staging";
69
+ },
70
+ fetchFn: typeof fetch = fetch,
71
+ ): Promise<string | null> {
72
+ const override = env[VISITOR_AI_STREAM_ORIGIN_ENV];
73
+ if (override !== undefined) return override.trim() === "" ? null : new URL(override).origin;
74
+ if (gateway.environment === "staging") return null;
75
+ if (env.CAELO_PROVIDER !== "gcp-firebase") return null;
76
+ if (!gateway.service)
77
+ throw new Error(
78
+ "gcp-firebase: the gateway's Cloud Run service is not named (CAELO_GATEWAY_SERVICE on the admin, K_SERVICE on the gateway); run `cms-provision upgrade`",
79
+ );
80
+ const where = await cloudRunInstanceLocation(fetchFn);
81
+ return cloudRunServiceOrigin(
82
+ gateway.service,
83
+ where.projectNumber,
84
+ gateway.region ?? where.region,
85
+ );
86
+ }