@uptimizr/sdk-core 1.0.1 → 1.1.0

package/AGENTS.md

@@ -58,6 +58,10 @@ Engine adapters are just collectors that translate engine events into `@uptimizr
 - Respect privacy: never set or persist a client identifier; honor `disabled` / Do-Not-Track.
 - Use `beforeSend` for filtering/redaction; use a custom `transport` for delivery changes.
 - New instrumentation = a new collector, not a core modification.
+- `registerRegions(sceneId, regions, { endpoint, apiKey })` declares a scene's named regions
+  (the scene registry, not capture). It **replaces** the scene's set and is an authenticated
+  write needing an **`annotate`**-capable key (a `query`-only key gets `403`) — never emit the
+  API key into a public bundle; call it from build/deploy/admin code.
 
 ## Key options
 

package/README.md

@@ -78,6 +78,39 @@ invalid payload can never succeed and would block later flushes) — and `false`
 failures (network error, 5xx, 408, 429), which the client re-queues. Provide your own via the `transport` option to integrate a
 different delivery mechanism.
 
+## Registering scene regions
+
+`registerRegions(sceneId, regions, options)` declares the named places inside a scene — the
+authoring counterpart to a connector's `scanSceneProxy`. A region is a labelled world-space box
+(`{ id, label, bounds: [minX,minY,minZ,maxX,maxY,maxZ], description? }`); once registered, any
+spatial query can be drilled into it by name with `?region=<id>`, and summaries can answer "the
+checkout counter" instead of a voxel centre.
+
+```ts
+import { registerRegions } from "@uptimizr/sdk-core";
+
+await registerRegions(
+  "lobby",
+  [
+    { id: "entrance", label: "Entrance", bounds: [-5, 0, -5, 5, 3, 0] },
+    { id: "counter", label: "Checkout counter", bounds: [-1, 0, 1, 1, 2, 3] },
+  ],
+  { endpoint: "https://collect.example.com", apiKey: process.env.UPTIMIZR_API_KEY! },
+);
+```
+
+The call **replaces** the scene's whole set (leaving a region out removes it; `[]` clears them)
+and validates locally before sending, so a bad box fails with a precise message.
+
+> **Security.** Unlike event capture — which is deliberately keyless — this is an authenticated
+> write that sends a project API key as `x-api-key`, exactly like the scene-proxy upload. The
+> key must hold the **`annotate`** capability — mint one with
+> `uptimizr new-key <projectId> --capabilities annotate` (or `query,annotate` if the same key
+> reads the regions back); a `query`-only key is refused with `403`. Never
+> bake that key into a public production bundle: call `registerRegions` from a build/deploy
+> script, a server-side route, an internal admin tool, or a developer-only path. It is a one-off
+> authoring step, not a per-page-load call.
+
 ## Offloading work to a Web Worker
 
 Capture (reading your 3D scene) always runs on the main thread, but the **processing** that

package/dist/index.d.ts

@@ -9,6 +9,8 @@ export { EventQueue } from "./queue.js";
 export { createBeaconTransport } from "./transport.js";
 export { createMainProcessor, createWorkerProcessor, collectTransferables } from "./processor.js";
 export { randomId } from "./idgen.js";
+export { registerRegions } from "./regions.js";
+export type { RegisterRegionsOptions } from "./regions.js";
 export { SDK_VERSION } from "./version.js";
 export { resolveCadence } from "./sampling.js";
 export { classifyCameraGesture, DEFAULT_GESTURE_THRESHOLDS } from "./gesture.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAClG,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EACL,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EACL,gBAAgB,EAChB,4BAA4B,EAC5B,aAAa,EACb,sBAAsB,EACtB,SAAS,EACT,SAAS,EACT,SAAS,EACT,aAAa,EACb,mBAAmB,EACnB,OAAO,GACR,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,yBAAyB,EACzB,sBAAsB,EACtB,uBAAuB,EACvB,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,UAAU,EACV,UAAU,GACX,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,EACxB,YAAY,EACZ,wBAAwB,EACxB,6BAA6B,EAC7B,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,UAAU,EACV,cAAc,EACd,SAAS,EACT,iBAAiB,EACjB,sBAAsB,EACtB,SAAS,EACT,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACnG,OAAO,EAAE,cAAc,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AACnF,YAAY,EAAE,eAAe,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AAE1F,YAAY,EACV,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAClG,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EACL,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EACL,gBAAgB,EAChB,4BAA4B,EAC5B,aAAa,EACb,sBAAsB,EACtB,SAAS,EACT,SAAS,EACT,SAAS,EACT,aAAa,EACb,mBAAmB,EACnB,OAAO,GACR,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,EACR,eAAe,EACf,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,yBAAyB,EACzB,sBAAsB,EACtB,uBAAuB,EACvB,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,UAAU,EACV,UAAU,GACX,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,EACxB,YAAY,EACZ,wBAAwB,EACxB,6BAA6B,EAC7B,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,UAAU,EACV,cAAc,EACd,SAAS,EACT,iBAAiB,EACjB,sBAAsB,EACtB,SAAS,EACT,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACnG,OAAO,EAAE,cAAc,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AACnF,YAAY,EAAE,eAAe,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AAE1F,YAAY,EACV,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -9,6 +9,7 @@ export { EventQueue } from "./queue.js";
 export { createBeaconTransport } from "./transport.js";
 export { createMainProcessor, createWorkerProcessor, collectTransferables } from "./processor.js";
 export { randomId } from "./idgen.js";
+export { registerRegions } from "./regions.js";
 export { SDK_VERSION } from "./version.js";
 export { resolveCadence } from "./sampling.js";
 export { classifyCameraGesture, DEFAULT_GESTURE_THRESHOLDS } from "./gesture.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAClG,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EACL,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EACL,gBAAgB,EAChB,4BAA4B,EAC5B,aAAa,EACb,sBAAsB,EACtB,SAAS,EACT,SAAS,EACT,SAAS,EACT,aAAa,EACb,mBAAmB,EACnB,OAAO,GACR,MAAM,wBAAwB,CAAC;AAmBhC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAgClC,OAAO,EAAE,cAAc,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAClG,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EACL,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EACL,gBAAgB,EAChB,4BAA4B,EAC5B,aAAa,EACb,sBAAsB,EACtB,SAAS,EACT,SAAS,EACT,SAAS,EACT,aAAa,EACb,mBAAmB,EACnB,OAAO,GACR,MAAM,wBAAwB,CAAC;AAmBhC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAgClC,OAAO,EAAE,cAAc,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/regions.d.ts

@@ -0,0 +1,71 @@
+import type { SceneRegion } from "@uptimizr/schema";
+/**
+ * Scene-region registration (ADR 0051 §2 / sketch §B.2) — the authoring
+ * counterpart to a connector's `scanSceneProxy`.
+ *
+ * A scene proxy tells Uptimizr what a scene *looks* like; regions tell it what
+ * the places in that scene are *called*. Declaring
+ * `[{ id: "entrance", label: "Entrance", bounds: [...] }]` lets every spatial
+ * query be drilled by name (`?region=entrance`) and lets summaries and agents
+ * answer in words instead of coordinates.
+ *
+ * ## Security — this is an authenticated write, unlike event capture
+ *
+ * Event capture is deliberately keyless: `navigator.sendBeacon` cannot attach
+ * secret headers, so the public `projectId` is the only credential (ADR 0003).
+ * The scene registry is the opposite — like the existing
+ * `PUT /scenes/:id/representation` proxy upload, it authenticates with a project
+ * **API key** sent as `x-api-key`. That key must therefore NOT be baked into a
+ * public production bundle. Call `registerRegions` from a build/deploy script,
+ * an internal admin tool, a server-side route, or a developer-only path in your
+ * app (the Uptimizr playground registers from its dev UI for exactly this
+ * reason). It is a one-off authoring step, not something to run per page load.
+ *
+ * The key needs the **`annotate`** capability — the dedicated metadata-write
+ * capability (ADR 0051 §5/§7), not `query`. Mint one with
+ * `uptimizr new-key <projectId> --capabilities annotate`, or
+ * `--capabilities query,annotate` if the same key also reads the regions back.
+ */
+/** Transport/auth settings for a scene-registry write. */
+export interface RegisterRegionsOptions {
+    /**
+     * Collector base URL — the same `endpoint` the capture client is configured
+     * with, with or without a trailing slash (e.g. `"http://localhost:4318"`).
+     */
+    endpoint: string;
+    /**
+     * Project API key, sent as `x-api-key`. It must hold the `annotate`
+     * capability. See the security note above: never ship this in a public
+     * bundle.
+     */
+    apiKey: string;
+    /** `fetch` implementation to use. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Abort signal, so a caller can cancel or time out the request. */
+    signal?: AbortSignal;
+}
+/**
+ * Declare `sceneId`'s regions, **replacing** whatever the registry holds for
+ * that scene — the call states what the scene's regions are, so removing one is
+ * leaving it out and `[]` clears them. Idempotent: registering the same set
+ * twice is a no-op in effect.
+ *
+ * Validates against `sceneRegionsSchema` before sending, so a bad box or a
+ * duplicate id fails locally with a precise message instead of a bare `400`.
+ * Rejects when the collector refuses the write (the error message carries the
+ * status and the response body, truncated).
+ *
+ * @example
+ * ```ts
+ * await registerRegions(
+ *   "lobby",
+ *   [
+ *     { id: "entrance", label: "Entrance", bounds: [-5, 0, -5, 5, 3, 0] },
+ *     { id: "counter", label: "Checkout counter", bounds: [-1, 0, 1, 1, 2, 3] },
+ *   ],
+ *   { endpoint: "http://localhost:4318", apiKey: process.env.UPTIMIZR_API_KEY! },
+ * );
+ * ```
+ */
+export declare function registerRegions(sceneId: string, regions: readonly SceneRegion[], options: RegisterRegionsOptions): Promise<void>;
+//# sourceMappingURL=regions.d.ts.map

package/dist/regions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regions.d.ts","sourceRoot":"","sources":["../src/regions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,0DAA0D;AAC1D,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA2Bf"}

package/dist/regions.js

@@ -0,0 +1,52 @@
+import { sceneRegionsSchema } from "@uptimizr/schema";
+/**
+ * Declare `sceneId`'s regions, **replacing** whatever the registry holds for
+ * that scene — the call states what the scene's regions are, so removing one is
+ * leaving it out and `[]` clears them. Idempotent: registering the same set
+ * twice is a no-op in effect.
+ *
+ * Validates against `sceneRegionsSchema` before sending, so a bad box or a
+ * duplicate id fails locally with a precise message instead of a bare `400`.
+ * Rejects when the collector refuses the write (the error message carries the
+ * status and the response body, truncated).
+ *
+ * @example
+ * ```ts
+ * await registerRegions(
+ *   "lobby",
+ *   [
+ *     { id: "entrance", label: "Entrance", bounds: [-5, 0, -5, 5, 3, 0] },
+ *     { id: "counter", label: "Checkout counter", bounds: [-1, 0, 1, 1, 2, 3] },
+ *   ],
+ *   { endpoint: "http://localhost:4318", apiKey: process.env.UPTIMIZR_API_KEY! },
+ * );
+ * ```
+ */
+export async function registerRegions(sceneId, regions, options) {
+    const parsed = sceneRegionsSchema.parse(regions);
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== "function") {
+        throw new Error("registerRegions needs a fetch implementation (pass options.fetchImpl).");
+    }
+    // Trim trailing slashes with a loop rather than a `/\/+$/` regex: the greedy
+    // quantifier backtracks from every position, so an endpoint of many slashes
+    // costs quadratic time (CodeQL `js/polynomial-redos`). This is linear.
+    let base = options.endpoint;
+    while (base.endsWith("/"))
+        base = base.slice(0, -1);
+    const url = `${base}/api/v1/scenes/${encodeURIComponent(sceneId)}/regions`;
+    const response = await doFetch(url, {
+        method: "PUT",
+        headers: { "content-type": "application/json", "x-api-key": options.apiKey },
+        body: JSON.stringify({ regions: parsed }),
+        signal: options.signal,
+    });
+    if (!response.ok) {
+        // Surface the collector's own validation message; cap it so a stray HTML
+        // error page cannot flood the console.
+        const body = await response.text().catch(() => "");
+        throw new Error(`Uptimizr region registration failed for scene "${sceneId}" ` +
+            `(${response.status})${body ? `: ${body.slice(0, 300)}` : ""}`);
+    }
+}
+//# sourceMappingURL=regions.js.map

package/dist/regions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"regions.js","sourceRoot":"","sources":["../src/regions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAkDtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAe,EACf,OAA+B,EAC/B,OAA+B;IAE/B,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,CAAC;IACtD,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;IAC5F,CAAC;IACD,6EAA6E;IAC7E,4EAA4E;IAC5E,uEAAuE;IACvE,IAAI,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC5B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACpD,MAAM,GAAG,GAAG,GAAG,IAAI,kBAAkB,kBAAkB,CAAC,OAAO,CAAC,UAAU,CAAC;IAC3E,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE;QAClC,MAAM,EAAE,KAAK;QACb,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,WAAW,EAAE,OAAO,CAAC,MAAM,EAAE;QAC5E,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QACzC,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,yEAAyE;QACzE,uCAAuC;QACvC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QACnD,MAAM,IAAI,KAAK,CACb,kDAAkD,OAAO,IAAI;YAC3D,IAAI,QAAQ,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CACjE,CAAC;IACJ,CAAC;AACH,CAAC"}

package/llms.txt

@@ -14,3 +14,6 @@
 
 - `UptimizrClient` — create, `start()`, `track(name, props)`, `use(collector)`, `stop()`.
 - `Collector` / `Transport` types — the extension points.
+- `registerRegions(sceneId, regions, { endpoint, apiKey })` — declare a scene's named regions
+  in the scene registry (an authenticated write needing an `annotate`-capable key; keep the
+  API key out of public bundles).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uptimizr/sdk-core",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Framework-agnostic Uptimizr capture runtime — session, batching, cookieless transport, and a pluggable collector system.",
   "keywords": [
     "uptimizr",
@@ -46,7 +46,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@uptimizr/schema": "1.0.1"
+    "@uptimizr/schema": "1.1.0"
   },
   "devDependencies": {
     "vitest": "^4.1.11"