@numerum-tech/yeriasdk 1.0.0

package/dist/core/key-store.js

@@ -0,0 +1,138 @@
+"use strict";
+// YeriaKeyStore — provider-side helper for resolving the JWT `kid` header
+// of inbound Yeria-issued user tokens.
+//
+// The store fetches keys from `GET /api/v1/public/registry/public-keys/{kid}`
+// on demand, caches the result in memory, and only ever returns a PEM
+// when the key is still trusted (state ∈ {active, rotating}). Expired /
+// unknown keys are negatively cached so a flood of bad tokens does not
+// hammer Yeria.
+//
+// Providers wire it into their own auth middleware:
+//
+//   import { JsonApp, YeriaKeyStore } from '@numerum-tech/yeriasdk';
+//
+//   const keys = new YeriaKeyStore({ baseUrl: process.env.YERIA_BASE_URL });
+//
+//   const claims = await JsonApp.verifyUserTokenWithResolver(
+//       bearer,
+//       (kid) => keys.getByKid(kid),
+//       MY_SERVICE_ID
+//   );
+//
+// The SDK never reaches out to Yeria on its own — every network call
+// flows through a fetch implementation the caller can swap (tests,
+// non-Node runtimes).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YeriaKeyStore = void 0;
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+class YeriaKeyStore {
+    constructor(opts) {
+        this.cache = new Map();
+        if (!opts || !opts.baseUrl) {
+            throw new Error('YeriaKeyStore: baseUrl is required');
+        }
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        const f = opts.fetch ?? globalThis.fetch;
+        if (typeof f !== 'function') {
+            throw new Error('YeriaKeyStore: no fetch available — pass opts.fetch on Node < 18 or non-browser runtimes');
+        }
+        this.fetchImpl = f.bind(globalThis);
+    }
+    /**
+     * Resolve a kid to a PEM. Returns null when the key is expired or
+     * unknown — the caller should reject the inbound token in that case.
+     */
+    async getByKid(kid) {
+        const lookup = await this.lookup(kid);
+        return lookup.publicKey;
+    }
+    /**
+     * Resolve a kid to its full trust state. Same network/cache behaviour
+     * as `getByKid` — exposed for callers that want to log / branch on
+     * the state.
+     */
+    async getState(kid) {
+        const lookup = await this.lookup(kid);
+        return lookup.state;
+    }
+    /** Drop a single cache entry. Use after a verify failure to force a
+     *  refetch on the retry — covers the case where Yeria rotated a key
+     *  out from under our cache. */
+    invalidate(kid) {
+        this.cache.delete(kid);
+    }
+    /** Drop the entire cache. */
+    invalidateAll() {
+        this.cache.clear();
+    }
+    async lookup(kid) {
+        if (typeof kid !== 'string' || kid.length === 0) {
+            return { state: 'unknown', publicKey: null, expiresAt: null };
+        }
+        const now = Date.now();
+        const cached = this.cache.get(kid);
+        if (cached && cached.expiresAt > now) {
+            return cached.lookup;
+        }
+        const lookup = await this.fetchFromYeria(kid);
+        this.cache.set(kid, { lookup, expiresAt: now + this.ttlMs });
+        return lookup;
+    }
+    async fetchFromYeria(kid) {
+        const url = `${this.baseUrl}/api/v1/public/registry/public-keys/${encodeURIComponent(kid)}`;
+        let res;
+        try {
+            res = await this.fetchImpl(url, { method: 'GET' });
+        }
+        catch (e) {
+            // Network failure — surface as `unknown` so the caller rejects
+            // the inbound token without caching the result for long.
+            // We still cache briefly (the TTL) to avoid hot-looping.
+            return { state: 'unknown', publicKey: null, expiresAt: null };
+        }
+        // Yeria returns 404 for unknown kid + 200 with state otherwise.
+        // The body shape is the same on success and on the 404 case
+        // (`{state, key_id, [public_key, ...]}`) wrapped in
+        // `{success, message, result}` by the platform's jsonSuccess /
+        // jsonFail helpers.
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch (_e) {
+            return { state: 'unknown', publicKey: null, expiresAt: null };
+        }
+        const result = extractResult(body);
+        if (!result) {
+            return { state: 'unknown', publicKey: null, expiresAt: null };
+        }
+        const state = result['state'] || 'unknown';
+        if (state === 'active' || state === 'rotating') {
+            return {
+                state,
+                publicKey: typeof result['public_key'] === 'string' ? result['public_key'] : null,
+                expiresAt: typeof result['expires_at'] === 'string' ? result['expires_at'] : null,
+            };
+        }
+        return { state, publicKey: null, expiresAt: null };
+    }
+}
+exports.YeriaKeyStore = YeriaKeyStore;
+/** Extract `result` from a `{success, message, result}` envelope, or fall
+ *  back to the top-level object when the platform returned a state-only
+ *  body without the wrapper. */
+function extractResult(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const b = body;
+    if (b['result'] && typeof b['result'] === 'object') {
+        return b['result'];
+    }
+    // Some jsonFail paths return the result fields at the top level.
+    if (typeof b['state'] === 'string')
+        return b;
+    return null;
+}
+//# sourceMappingURL=key-store.js.map

package/dist/core/key-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-store.js","sourceRoot":"","sources":["../../src/core/key-store.ts"],"names":[],"mappings":";AAAA,0EAA0E;AAC1E,uCAAuC;AACvC,EAAE;AACF,8EAA8E;AAC9E,sEAAsE;AACtE,wEAAwE;AACxE,uEAAuE;AACvE,gBAAgB;AAChB,EAAE;AACF,oDAAoD;AACpD,EAAE;AACF,qEAAqE;AACrE,EAAE;AACF,6EAA6E;AAC7E,EAAE;AACF,8DAA8D;AAC9D,gBAAgB;AAChB,qCAAqC;AACrC,sBAAsB;AACtB,OAAO;AACP,EAAE;AACF,qEAAqE;AACrE,mEAAmE;AACnE,sBAAsB;;;AAkCtB,MAAM,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEtC,MAAa,aAAa;IAMtB,YAAY,IAA0B;QAFrB,UAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;QAGnD,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,cAAc,CAAC;QAC1C,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;QACzC,IAAI,OAAO,CAAC,KAAK,UAAU,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACX,0FAA0F,CAC7F,CAAC;QACN,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ,CAAC,GAAW;QACtB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACtC,OAAO,MAAM,CAAC,SAAS,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,GAAW;QACtB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACtC,OAAO,MAAM,CAAC,KAAK,CAAC;IACxB,CAAC;IAED;;oCAEgC;IAChC,UAAU,CAAC,GAAW;QAClB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,6BAA6B;IAC7B,aAAa;QACT,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAEO,KAAK,CAAC,MAAM,CAAC,GAAW;QAC5B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9C,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAClE,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC;YACnC,OAAO,MAAM,CAAC,MAAM,CAAC;QACzB,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QAC9C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QAC7D,OAAO,MAAM,CAAC;IAClB,CAAC;IAEO,KAAK,CAAC,cAAc,CAAC,GAAW;QACpC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,uCAAuC,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5F,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACD,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QACvD,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,+DAA+D;YAC/D,yDAAyD;YACzD,yDAAyD;YACzD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAClE,CAAC;QAED,gEAAgE;QAChE,4DAA4D;QAC5D,oDAAoD;QACpD,+DAA+D;QAC/D,oBAAoB;QACpB,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACD,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC5B,CAAC;QAAC,OAAO,EAAE,EAAE,CAAC;YACV,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAClE,CAAC;QAED,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,MAAM,EAAE,CAAC;YACV,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAClE,CAAC;QAED,MAAM,KAAK,GAAI,MAAM,CAAC,OAAO,CAAc,IAAI,SAAS,CAAC;QACzD,IAAI,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;YAC7C,OAAO;gBACH,KAAK;gBACL,SAAS,EAAE,OAAO,MAAM,CAAC,YAAY,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAW,CAAC,CAAC,CAAC,IAAI;gBAC3F,SAAS,EAAE,OAAO,MAAM,CAAC,YAAY,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAW,CAAC,CAAC,CAAC,IAAI;aAC9F,CAAC;QACN,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACvD,CAAC;CACJ;AA1GD,sCA0GC;AAED;;gCAEgC;AAChC,SAAS,aAAa,CAAC,IAAa;IAChC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACnD,MAAM,CAAC,GAAG,IAA+B,CAAC;IAC1C,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,QAAQ,EAAE,CAAC;QACjD,OAAO,CAAC,CAAC,QAAQ,CAA4B,CAAC;IAClD,CAAC;IACD,iEAAiE;IACjE,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IAC7C,OAAO,IAAI,CAAC;AAChB,CAAC"}

package/dist/core/map-view.d.ts

@@ -0,0 +1,45 @@
+import { BaseView } from './base-view';
+import { GeoPoint, MapBasemap, MapContent, MapControls, MapLayer, MapMarker, MapPickConfig, MapShape, MapShapeStyle, MapViewport } from '../types';
+/**
+ * MapView (v2) — see specs/map-view.md
+ *
+ * Wire format: a single data path, `content.layers[]`. Even one-marker views
+ * are described as `[{ type: 'markers', markers: [...] }]`.
+ *
+ * SDK ergonomics: `addMarker / addPolygon / addCircle / ...` are convenience
+ * methods that target either an implicit default layer (`_default_markers` or
+ * `_default_shapes`, auto-created on first call) or a named layer (passed as
+ * the optional final `layerId` argument). Named layers must be declared up
+ * front via `addLayer({...})`.
+ */
+export declare class MapView extends BaseView {
+    static readonly DEFAULT_MARKERS_LAYER_ID = "_default_markers";
+    static readonly DEFAULT_SHAPES_LAYER_ID = "_default_shapes";
+    constructor(viewId: string, title: string, processId?: string);
+    setIntro(intro: string): this;
+    setBasemap(name: MapBasemap): this;
+    setViewport(viewport: MapViewport): this;
+    setControls(controls: MapControls): this;
+    setEmptyMessage(text: string): this;
+    setPickMode(config: MapPickConfig): this;
+    addLayer(layer: MapLayer): this;
+    setLayers(layers: MapLayer[]): this;
+    clearLayers(): this;
+    getLayer(id: string): MapLayer | undefined;
+    addMarker(marker: MapMarker, layerId?: string): this;
+    addMarkers(markers: MapMarker[], layerId?: string): this;
+    clearMarkers(layerId?: string): this;
+    addShape(shape: MapShape, layerId?: string): this;
+    addPolygon(id: string, points: GeoPoint[], config?: MapShapeStyle, layerId?: string): this;
+    addCircle(id: string, center: GeoPoint, radius: number, config?: MapShapeStyle, layerId?: string): this;
+    addPolyline(id: string, points: GeoPoint[], config?: MapShapeStyle, layerId?: string): this;
+    addRectangle(id: string, sw: GeoPoint, ne: GeoPoint, config?: MapShapeStyle, layerId?: string): this;
+    clearShapes(layerId?: string): this;
+    getContent(): MapContent;
+    private resolveOrCreateMarkersLayer;
+    private resolveOrCreateShapesLayer;
+    private validateGeoPoint;
+    private validateShape;
+    private validateViewport;
+}
+//# sourceMappingURL=map-view.d.ts.map

package/dist/core/map-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-view.d.ts","sourceRoot":"","sources":["../../src/core/map-view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EACH,QAAQ,EACR,UAAU,EACV,UAAU,EACV,WAAW,EACX,QAAQ,EACR,SAAS,EACT,aAAa,EACb,QAAQ,EACR,aAAa,EACb,WAAW,EAGd,MAAM,UAAU,CAAC;AAWlB;;;;;;;;;;;GAWG;AACH,qBAAa,OAAQ,SAAQ,QAAQ;IACjC,gBAAuB,wBAAwB,sBAAsB;IACrE,gBAAuB,uBAAuB,qBAAsB;gBAExD,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;IAoB7D,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI7B,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAKlC,WAAW,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI;IAMxC,WAAW,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI;IAKxC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKnC,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAmBxC,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAiB/B,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI;IASnC,WAAW,IAAI,IAAI;IAKnB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAM1C,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAmBpD,UAAU,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAQxD,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAapC,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAcjD,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,MAAM,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAI1F,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAIvG,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,MAAM,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAI3F,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAIpG,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAWnC,UAAU,IAAI,UAAU;IAMxB,OAAO,CAAC,2BAA2B;IA2BnC,OAAO,CAAC,0BAA0B;IA2BlC,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,aAAa;IA2CrB,OAAO,CAAC,gBAAgB;CA4B3B"}

package/dist/core/map-view.js

@@ -0,0 +1,318 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MapView = void 0;
+const base_view_1 = require("./base-view");
+const errors_1 = require("../errors");
+/**
+ * MapView (v2) — see specs/map-view.md
+ *
+ * Wire format: a single data path, `content.layers[]`. Even one-marker views
+ * are described as `[{ type: 'markers', markers: [...] }]`.
+ *
+ * SDK ergonomics: `addMarker / addPolygon / addCircle / ...` are convenience
+ * methods that target either an implicit default layer (`_default_markers` or
+ * `_default_shapes`, auto-created on first call) or a named layer (passed as
+ * the optional final `layerId` argument). Named layers must be declared up
+ * front via `addLayer({...})`.
+ */
+class MapView extends base_view_1.BaseView {
+    constructor(viewId, title, processId) {
+        super({
+            id: viewId,
+            type: 'Map',
+            processId,
+            metadata: {
+                version: '2.0.0',
+                createdAt: new Date()
+            }
+        });
+        this.content = {
+            title,
+            layers: [],
+            controls: { zoom: true, compass: true, userLocation: false }
+        };
+    }
+    // ─── view-level setters ─────────────────────────────────────────────
+    setIntro(intro) {
+        return this.setIntroText('intro', intro);
+    }
+    setBasemap(name) {
+        this.content.basemap = name;
+        return this;
+    }
+    setViewport(viewport) {
+        this.validateViewport(viewport);
+        this.content.viewport = { ...viewport };
+        return this;
+    }
+    setControls(controls) {
+        this.content.controls = { ...controls };
+        return this;
+    }
+    setEmptyMessage(text) {
+        this.content.emptyMessage = text;
+        return this;
+    }
+    setPickMode(config) {
+        if (!config || typeof config.submitUrl !== 'string' || !config.submitUrl.trim()) {
+            throw new errors_1.MissingRequiredParameterError('pick.submitUrl');
+        }
+        if (config.initialLocation) {
+            this.validateGeoPoint(config.initialLocation, 'pick.initialLocation');
+        }
+        if (config.bounds) {
+            this.validateGeoPoint(config.bounds.sw, 'pick.bounds.sw');
+            this.validateGeoPoint(config.bounds.ne, 'pick.bounds.ne');
+        }
+        const content = this.content;
+        content.mode = 'pick';
+        content.pick = { ...config };
+        return this;
+    }
+    // ─── layer management ───────────────────────────────────────────────
+    addLayer(layer) {
+        if (!layer || typeof layer !== 'object') {
+            throw new errors_1.MissingRequiredParameterError('layer');
+        }
+        if (typeof layer.id !== 'string' || !layer.id.trim()) {
+            throw new errors_1.MissingRequiredParameterError('layer.id');
+        }
+        const content = this.content;
+        if (content.layers.some(l => l.id === layer.id)) {
+            throw new errors_1.DuplicateLayerIdError(layer.id);
+        }
+        // Shallow copy so callers can't mutate the layer payload after the fact.
+        const copy = { ...layer };
+        content.layers.push(copy);
+        return this;
+    }
+    setLayers(layers) {
+        if (!Array.isArray(layers)) {
+            throw new errors_1.InvalidParameterError('layers', layers, 'must be an array');
+        }
+        this.content.layers = [];
+        for (const l of layers)
+            this.addLayer(l);
+        return this;
+    }
+    clearLayers() {
+        this.content.layers = [];
+        return this;
+    }
+    getLayer(id) {
+        return this.content.layers.find(l => l.id === id);
+    }
+    // ─── markers (default layer or named target) ────────────────────────
+    addMarker(marker, layerId) {
+        if (!marker || typeof marker !== 'object') {
+            throw new errors_1.MissingRequiredParameterError('marker');
+        }
+        if (typeof marker.id !== 'string' || !marker.id.trim()) {
+            throw new errors_1.MissingRequiredParameterError('marker.id');
+        }
+        this.validateGeoPoint(marker.location, `marker "${marker.id}".location`);
+        const layer = this.resolveOrCreateMarkersLayer(layerId);
+        layer.markers.push({
+            ...marker,
+            id: marker.id.trim(),
+            title: marker.title?.trim(),
+            description: marker.description?.trim()
+        });
+        return this;
+    }
+    addMarkers(markers, layerId) {
+        if (!Array.isArray(markers)) {
+            throw new errors_1.InvalidParameterError('markers', markers, 'must be an array');
+        }
+        for (const m of markers)
+            this.addMarker(m, layerId);
+        return this;
+    }
+    clearMarkers(layerId) {
+        const target = layerId ?? MapView.DEFAULT_MARKERS_LAYER_ID;
+        const layer = this.getLayer(target);
+        if (!layer)
+            return this;
+        if (layer.type !== 'markers') {
+            throw new errors_1.LayerTypeMismatchError(target, 'markers', layer.type);
+        }
+        layer.markers = [];
+        return this;
+    }
+    // ─── shapes (default layer or named target) ─────────────────────────
+    addShape(shape, layerId) {
+        if (!shape || typeof shape !== 'object') {
+            throw new errors_1.MissingRequiredParameterError('shape');
+        }
+        if (typeof shape.id !== 'string' || !shape.id.trim()) {
+            throw new errors_1.MissingRequiredParameterError('shape.id');
+        }
+        this.validateShape(shape);
+        const layer = this.resolveOrCreateShapesLayer(layerId);
+        layer.shapes.push({ ...shape, id: shape.id.trim() });
+        return this;
+    }
+    addPolygon(id, points, config, layerId) {
+        return this.addShape({ id, type: 'Polygon', points, config }, layerId);
+    }
+    addCircle(id, center, radius, config, layerId) {
+        return this.addShape({ id, type: 'Circle', center, radius, config }, layerId);
+    }
+    addPolyline(id, points, config, layerId) {
+        return this.addShape({ id, type: 'Polyline', points, config }, layerId);
+    }
+    addRectangle(id, sw, ne, config, layerId) {
+        return this.addShape({ id, type: 'Rectangle', sw, ne, config }, layerId);
+    }
+    clearShapes(layerId) {
+        const target = layerId ?? MapView.DEFAULT_SHAPES_LAYER_ID;
+        const layer = this.getLayer(target);
+        if (!layer)
+            return this;
+        if (layer.type !== 'shapes') {
+            throw new errors_1.LayerTypeMismatchError(target, 'shapes', layer.type);
+        }
+        layer.shapes = [];
+        return this;
+    }
+    getContent() {
+        return this.content;
+    }
+    // ─── private helpers ────────────────────────────────────────────────
+    resolveOrCreateMarkersLayer(layerId) {
+        const content = this.content;
+        if (layerId) {
+            const layer = content.layers.find(l => l.id === layerId);
+            if (!layer)
+                throw new errors_1.LayerNotFoundError(layerId);
+            if (layer.type !== 'markers') {
+                throw new errors_1.LayerTypeMismatchError(layerId, 'markers', layer.type);
+            }
+            return layer;
+        }
+        let def = content.layers.find(l => l.id === MapView.DEFAULT_MARKERS_LAYER_ID);
+        if (!def) {
+            const created = {
+                id: MapView.DEFAULT_MARKERS_LAYER_ID,
+                type: 'markers',
+                markers: [],
+                toggleable: false
+            };
+            content.layers.push(created);
+            return created;
+        }
+        if (def.type !== 'markers') {
+            throw new errors_1.LayerTypeMismatchError(def.id, 'markers', def.type);
+        }
+        return def;
+    }
+    resolveOrCreateShapesLayer(layerId) {
+        const content = this.content;
+        if (layerId) {
+            const layer = content.layers.find(l => l.id === layerId);
+            if (!layer)
+                throw new errors_1.LayerNotFoundError(layerId);
+            if (layer.type !== 'shapes') {
+                throw new errors_1.LayerTypeMismatchError(layerId, 'shapes', layer.type);
+            }
+            return layer;
+        }
+        let def = content.layers.find(l => l.id === MapView.DEFAULT_SHAPES_LAYER_ID);
+        if (!def) {
+            const created = {
+                id: MapView.DEFAULT_SHAPES_LAYER_ID,
+                type: 'shapes',
+                shapes: [],
+                toggleable: false
+            };
+            content.layers.push(created);
+            return created;
+        }
+        if (def.type !== 'shapes') {
+            throw new errors_1.LayerTypeMismatchError(def.id, 'shapes', def.type);
+        }
+        return def;
+    }
+    validateGeoPoint(p, ctx) {
+        if (!p || typeof p !== 'object') {
+            throw new errors_1.InvalidGeoPointError(p, `${ctx}: location is required`);
+        }
+        if (typeof p.lat !== 'number' || p.lat < -90 || p.lat > 90) {
+            throw new errors_1.InvalidGeoPointError(p, `${ctx}: lat must be a number in [-90, 90]`);
+        }
+        if (typeof p.lon !== 'number' || p.lon < -180 || p.lon > 180) {
+            throw new errors_1.InvalidGeoPointError(p, `${ctx}: lon must be a number in [-180, 180]`);
+        }
+    }
+    validateShape(s) {
+        switch (s.type) {
+            case 'Polygon': {
+                if (!Array.isArray(s.points) || s.points.length < 3) {
+                    throw new errors_1.InvalidParameterError('points', s.points, 'Polygon requires at least 3 points');
+                }
+                s.points.forEach((p, i) => this.validateGeoPoint(p, `Polygon "${s.id}" points[${i}]`));
+                break;
+            }
+            case 'Polyline': {
+                if (!Array.isArray(s.points) || s.points.length < 2) {
+                    throw new errors_1.InvalidParameterError('points', s.points, 'Polyline requires at least 2 points');
+                }
+                s.points.forEach((p, i) => this.validateGeoPoint(p, `Polyline "${s.id}" points[${i}]`));
+                break;
+            }
+            case 'Circle': {
+                this.validateGeoPoint(s.center, `Circle "${s.id}" center`);
+                if (typeof s.radius !== 'number' || s.radius <= 0) {
+                    throw new errors_1.InvalidParameterError('radius', s.radius, 'Circle radius must be > 0 (meters)');
+                }
+                break;
+            }
+            case 'Rectangle': {
+                this.validateGeoPoint(s.sw, `Rectangle "${s.id}" sw`);
+                this.validateGeoPoint(s.ne, `Rectangle "${s.id}" ne`);
+                if (s.sw.lat > s.ne.lat || s.sw.lon > s.ne.lon) {
+                    throw new errors_1.InvalidParameterError('sw,ne', { sw: s.sw, ne: s.ne }, 'Rectangle sw must be south-west of ne (sw.lat <= ne.lat and sw.lon <= ne.lon)');
+                }
+                break;
+            }
+            default: {
+                // exhaustiveness guard — TypeScript will flag if a new shape type is added
+                const _exhaustive = s;
+                throw new errors_1.InvalidParameterError('shape.type', _exhaustive.type, 'unknown shape type');
+            }
+        }
+    }
+    validateViewport(v) {
+        if (v.center)
+            this.validateGeoPoint(v.center, 'viewport.center');
+        if (v.bounds) {
+            this.validateGeoPoint(v.bounds.sw, 'viewport.bounds.sw');
+            this.validateGeoPoint(v.bounds.ne, 'viewport.bounds.ne');
+            if (v.bounds.sw.lat > v.bounds.ne.lat || v.bounds.sw.lon > v.bounds.ne.lon) {
+                throw new errors_1.InvalidViewportError('viewport.bounds.sw must be south-west of bounds.ne');
+            }
+        }
+        if (v.zoom !== undefined && (v.zoom < 0 || v.zoom > 22)) {
+            throw new errors_1.InvalidViewportError('zoom must be in [0, 22]');
+        }
+        if (v.minZoom !== undefined && (v.minZoom < 0 || v.minZoom > 22)) {
+            throw new errors_1.InvalidViewportError('minZoom must be in [0, 22]');
+        }
+        if (v.maxZoom !== undefined && (v.maxZoom < 0 || v.maxZoom > 22)) {
+            throw new errors_1.InvalidViewportError('maxZoom must be in [0, 22]');
+        }
+        if (v.minZoom !== undefined && v.maxZoom !== undefined && v.minZoom > v.maxZoom) {
+            throw new errors_1.InvalidViewportError('minZoom must be <= maxZoom');
+        }
+        if (v.bearing !== undefined && (v.bearing < 0 || v.bearing >= 360)) {
+            throw new errors_1.InvalidViewportError('bearing must be in [0, 360)');
+        }
+        if (v.pitch !== undefined && (v.pitch < 0 || v.pitch > 60)) {
+            throw new errors_1.InvalidViewportError('pitch must be in [0, 60]');
+        }
+    }
+}
+exports.MapView = MapView;
+MapView.DEFAULT_MARKERS_LAYER_ID = '_default_markers';
+MapView.DEFAULT_SHAPES_LAYER_ID = '_default_shapes';
+//# sourceMappingURL=map-view.js.map

package/dist/core/map-view.js.map

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

package/dist/core/media-view.d.ts

@@ -0,0 +1,20 @@
+import { BaseView } from './base-view';
+import { MediaContent, MediaItem, MediaKind } from '../types';
+export declare class MediaView extends BaseView {
+    constructor(viewId: string, title: string, processId?: string);
+    setIntro(intro: string): this;
+    addMediaItem(item: MediaItem): this;
+    createMedia(id: string, kind: MediaKind, src: string, options?: {
+        type?: string;
+        title?: string;
+        description?: string;
+        poster?: string;
+        autoplay?: boolean;
+        loop?: boolean;
+        controls?: boolean;
+    }): MediaItem;
+    clearItems(): this;
+    getContent(): MediaContent;
+    private normalizeSource;
+}
+//# sourceMappingURL=media-view.d.ts.map

package/dist/core/media-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-view.d.ts","sourceRoot":"","sources":["../../src/core/media-view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAe,MAAM,UAAU,CAAC;AAI3E,qBAAa,SAAU,SAAQ,QAAQ;gBACvB,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;IAmB7D,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK7B,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAgBnC,WAAW,CACP,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO,GAC/I,SAAS;IAgBZ,UAAU,IAAI,IAAI;IAMlB,UAAU,IAAI,YAAY;IAI1B,OAAO,CAAC,eAAe;CAW1B"}

package/dist/core/media-view.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediaView = void 0;
+const base_view_1 = require("./base-view");
+// MediaView groups audio and video resources in a consistent playlist for mobile playback.
+class MediaView extends base_view_1.BaseView {
+    constructor(viewId, title, processId) {
+        super({
+            id: viewId,
+            type: 'Media',
+            processId,
+            metadata: {
+                version: '1.0.0',
+                createdAt: new Date()
+            }
+        });
+        this.content = {
+            title,
+            intro: '',
+            items: []
+        };
+    }
+    // Optional lead text for the media playlist section.
+    setIntro(intro) {
+        return this.setIntroText('intro', intro);
+    }
+    // Registers a ready-to-play media entry.
+    addMediaItem(item) {
+        if (!item.id || !item.kind || !item.sources || item.sources.length === 0) {
+            throw new Error('Media item requires an id, type, and at least one source');
+        }
+        this.content.items.push({
+            ...item,
+            id: item.id.trim(),
+            title: item.title?.trim(),
+            description: item.description?.trim(),
+            sources: item.sources.map(source => this.normalizeSource(source))
+        });
+        return this;
+    }
+    createMedia(id, kind, src, options = {}) {
+        const primarySource = this.normalizeSource({ src, type: options.type });
+        return {
+            id: id.trim(),
+            kind,
+            title: options.title?.trim(),
+            description: options.description?.trim(),
+            poster: options.poster?.trim(),
+            autoplay: options.autoplay,
+            loop: options.loop,
+            controls: options.controls ?? true,
+            sources: [primarySource]
+        };
+    }
+    clearItems() {
+        this.content.items = [];
+        return this;
+    }
+    // Helper to inspect the assembled playlist.
+    getContent() {
+        return this.content;
+    }
+    normalizeSource(source) {
+        const trimmedSrc = source.src.trim();
+        if (!trimmedSrc) {
+            throw new Error('Media source src cannot be empty');
+        }
+        return {
+            src: trimmedSrc,
+            type: source.type?.trim()
+        };
+    }
+}
+exports.MediaView = MediaView;
+//# sourceMappingURL=media-view.js.map

package/dist/core/media-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-view.js","sourceRoot":"","sources":["../../src/core/media-view.ts"],"names":[],"mappings":";;;AAAA,2CAAuC;AAGvC,2FAA2F;AAE3F,MAAa,SAAU,SAAQ,oBAAQ;IACnC,YAAY,MAAc,EAAE,KAAa,EAAE,SAAkB;QACzD,KAAK,CAAC;YACF,EAAE,EAAE,MAAM;YACV,IAAI,EAAE,OAAO;YACb,SAAS;YACT,QAAQ,EAAE;gBACN,OAAO,EAAE,OAAO;gBAChB,SAAS,EAAE,IAAI,IAAI,EAAE;aACxB;SACJ,CAAC,CAAC;QAEH,IAAI,CAAC,OAAO,GAAG;YACX,KAAK;YACL,KAAK,EAAE,EAAE;YACT,KAAK,EAAE,EAAE;SACI,CAAC;IACtB,CAAC;IAED,qDAAqD;IACrD,QAAQ,CAAC,KAAa;QAClB,OAAO,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC7C,CAAC;IAED,yCAAyC;IACzC,YAAY,CAAC,IAAe;QACxB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvE,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAChF,CAAC;QAEA,IAAI,CAAC,OAAwB,CAAC,KAAK,CAAC,IAAI,CAAC;YACtC,GAAG,IAAI;YACP,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE;YAClB,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE;YACzB,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE;YACrC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;SACpE,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,WAAW,CACP,EAAU,EACV,IAAe,EACf,GAAW,EACX,UAA4I,EAAE;QAE9I,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAExE,OAAO;YACH,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE;YACb,IAAI;YACJ,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE;YAC5B,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,IAAI,EAAE;YACxC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE;YAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI;YAClC,OAAO,EAAE,CAAC,aAAa,CAAC;SAC3B,CAAC;IACN,CAAC;IAED,UAAU;QACL,IAAI,CAAC,OAAwB,CAAC,KAAK,GAAG,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,4CAA4C;IAC5C,UAAU;QACN,OAAO,IAAI,CAAC,OAAuB,CAAC;IACxC,CAAC;IAEO,eAAe,CAAC,MAAmB;QACvC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,UAAU,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACxD,CAAC;QAED,OAAO;YACH,GAAG,EAAE,UAAU;YACf,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE;SAC5B,CAAC;IACN,CAAC;CACJ;AAnFD,8BAmFC"}