@tyndall/dynamic-manifest 0.0.1

package/README.md

@@ -0,0 +1,27 @@
+# @tyndall/dynamic-manifest
+
+## Overview
+Dynamic manifest resolver package for remote page resolution, caching, and policy-aware retrieval.
+
+## Responsibilities
+- Resolve dynamic page definitions from HTTP providers
+- Cache responses with etag and ttl semantics
+- Expose resolver interfaces shared by runtime, dev, and client paths
+
+## Public API Highlights
+- createHttpResolver
+- createDynamicManifestResolver
+
+## Development
+- Build: bun run --filter @tyndall/dynamic-manifest build
+- Test (from workspace root): bun test
+
+## Documentation
+- Package specification: [spec.md](./spec.md)
+- Package architecture: [architecture.md](./architecture.md)
+- Package changes: [CHANGELOG.md](./CHANGELOG.md)
+
+## Maintenance Rules
+- Keep this document aligned with implemented package behavior.
+- Update spec.md and architecture.md whenever package contracts or design boundaries change.
+- Record user-visible package changes in CHANGELOG.md.

package/dist/cache.d.ts

@@ -0,0 +1,19 @@
+import type { DynamicPageEnvelope } from "@tyndall/core";
+export interface DynamicManifestCacheOptions {
+    ttlMs?: number;
+    maxEntries?: number;
+    now?: () => number;
+}
+export interface DynamicManifestCacheEntry {
+    envelope: DynamicPageEnvelope;
+    etag?: string;
+    expiresAt: number;
+}
+export interface DynamicManifestCache {
+    get: (key: string) => DynamicManifestCacheEntry | null;
+    set: (key: string, envelope: DynamicPageEnvelope, etag?: string) => void;
+    delete: (key: string) => void;
+    clear: () => void;
+}
+export declare const createDynamicManifestCache: (options?: DynamicManifestCacheOptions) => DynamicManifestCache;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,MAAM,WAAW,2BAA2B;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,yBAAyB,GAAG,IAAI,CAAC;IACvD,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzE,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,eAAO,MAAM,0BAA0B,GACrC,UAAS,2BAAgC,KACxC,oBA6CF,CAAC"}

package/dist/cache.js

@@ -0,0 +1,44 @@
+export const createDynamicManifestCache = (options = {}) => {
+    const ttlMs = options.ttlMs ?? 5 * 60000;
+    const maxEntries = options.maxEntries ?? 100;
+    const now = options.now ?? (() => Date.now());
+    const entries = new Map();
+    const touch = (key, entry) => {
+        entries.delete(key);
+        entries.set(key, entry);
+    };
+    return {
+        get: (key) => {
+            const entry = entries.get(key);
+            if (!entry) {
+                return null;
+            }
+            if (entry.expiresAt <= now()) {
+                entries.delete(key);
+                return null;
+            }
+            touch(key, entry);
+            return entry;
+        },
+        set: (key, envelope, etag) => {
+            const entry = {
+                envelope,
+                etag,
+                expiresAt: now() + ttlMs,
+            };
+            entries.set(key, entry);
+            if (entries.size > maxEntries) {
+                const oldestKey = entries.keys().next().value;
+                if (oldestKey) {
+                    entries.delete(oldestKey);
+                }
+            }
+        },
+        delete: (key) => {
+            entries.delete(key);
+        },
+        clear: () => {
+            entries.clear();
+        },
+    };
+};

package/dist/http-resolver.d.ts

@@ -0,0 +1,18 @@
+import type { DynamicPageComponentRegistry, DynamicPageEnvelope, DynamicPageResolveInput } from "@tyndall/core";
+import type { DynamicManifestCache } from "./cache.js";
+export interface DynamicManifestHandler {
+    resolveByPath: (input: DynamicPageResolveInput) => Promise<DynamicPageEnvelope | null>;
+    resolveById: (pageId: string) => Promise<DynamicPageEnvelope | null>;
+    listComponents?: (filters?: Record<string, string>) => Promise<DynamicPageComponentRegistry | null>;
+}
+export type DynamicManifestResolver = (path: string) => Promise<DynamicPageEnvelope | null>;
+export interface DynamicManifestResolverOptions {
+    baseUrl?: string;
+    cache?: DynamicManifestCache;
+    fetcher?: typeof fetch;
+    ttlMs?: number;
+    maxEntries?: number;
+}
+export declare const createHttpResolver: (options?: DynamicManifestResolverOptions) => DynamicManifestHandler;
+export declare const createDynamicManifestResolver: (options?: DynamicManifestResolverOptions) => DynamicManifestResolver;
+//# sourceMappingURL=http-resolver.d.ts.map

package/dist/http-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-resolver.d.ts","sourceRoot":"","sources":["../src/http-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,4BAA4B,EAC5B,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGvD,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;IACvF,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;IACrE,cAAc,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC,CAAC;CACrG;AAED,MAAM,MAAM,uBAAuB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;AAE5F,MAAM,WAAW,8BAA8B;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA0CD,eAAO,MAAM,kBAAkB,GAC7B,UAAS,8BAAmC,KAC3C,sBA8CF,CAAC;AAEF,eAAO,MAAM,6BAA6B,GACxC,UAAS,8BAAmC,KAC3C,uBAGF,CAAC"}

package/dist/http-resolver.js

@@ -0,0 +1,82 @@
+import { paramsKey } from "@tyndall/shared";
+import { createDynamicManifestCache } from "./cache.js";
+const resolveBaseUrl = (baseUrl) => {
+    if (baseUrl) {
+        return baseUrl;
+    }
+    if (typeof globalThis !== "undefined" && "location" in globalThis) {
+        const location = globalThis.location;
+        if (location?.origin) {
+            return location.origin;
+        }
+    }
+    return "http://localhost";
+};
+const fetchEnvelope = async (key, url, cache, fetcher) => {
+    const cached = cache.get(key);
+    const headers = {};
+    if (cached?.etag) {
+        headers["If-None-Match"] = cached.etag;
+    }
+    const response = await fetcher(url.toString(), { method: "GET", headers });
+    if (response.status === 304 && cached) {
+        cache.set(key, cached.envelope, cached.etag);
+        return cached.envelope;
+    }
+    if (!response.ok) {
+        return null;
+    }
+    const envelope = (await response.json());
+    const etag = response.headers.get("ETag") ?? response.headers.get("etag") ?? undefined;
+    cache.set(key, envelope, etag);
+    return envelope;
+};
+export const createHttpResolver = (options = {}) => {
+    const cache = options.cache ??
+        createDynamicManifestCache({
+            ttlMs: options.ttlMs,
+            maxEntries: options.maxEntries,
+        });
+    const fetcher = options.fetcher ?? fetch;
+    const baseUrl = resolveBaseUrl(options.baseUrl);
+    return {
+        resolveByPath: async (input) => {
+            const key = `path:${paramsKey(input)}`;
+            const url = new URL("/api/pages/resolve", baseUrl);
+            url.searchParams.set("path", input.path);
+            if (input.locale) {
+                url.searchParams.set("locale", input.locale);
+            }
+            if (input.variant) {
+                url.searchParams.set("variant", input.variant);
+            }
+            if (input.device) {
+                url.searchParams.set("device", input.device);
+            }
+            if (input.ctxHash) {
+                url.searchParams.set("ctxHash", input.ctxHash);
+            }
+            return fetchEnvelope(key, url, cache, fetcher);
+        },
+        resolveById: async (pageId) => {
+            const key = `id:${pageId}`;
+            const url = new URL(`/api/pages/${encodeURIComponent(pageId)}`, baseUrl);
+            return fetchEnvelope(key, url, cache, fetcher);
+        },
+        listComponents: async (filters = {}) => {
+            const url = new URL("/api/components/registry", baseUrl);
+            for (const [key, value] of Object.entries(filters)) {
+                url.searchParams.set(key, value);
+            }
+            const response = await fetcher(url.toString(), { method: "GET" });
+            if (!response.ok) {
+                return null;
+            }
+            return (await response.json());
+        },
+    };
+};
+export const createDynamicManifestResolver = (options = {}) => {
+    const handler = createHttpResolver(options);
+    return async (path) => handler.resolveByPath({ path });
+};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { HyperPlugin } from "@tyndall/core";
+export { createDynamicManifestCache } from "./cache.js";
+export type { DynamicManifestCache, DynamicManifestCacheEntry, DynamicManifestCacheOptions, } from "./cache.js";
+export { createHttpResolver, createDynamicManifestResolver } from "./http-resolver.js";
+export type { DynamicManifestHandler, DynamicManifestResolver, DynamicManifestResolverOptions, } from "./http-resolver.js";
+export { DEFAULT_PROGRAM_SANDBOX_POLICY, buildProgramSandboxContext, dynamicManifestSchema, resolveProgramSandboxPolicy, validateDynamicManifest, validateDynamicManifest as validateManifest, validateProgramIntegrity, } from "@tyndall/core";
+export type { DynamicPageCache, DynamicPageDefinition, DynamicPageEnvelope, DynamicPageMode, DynamicPagePolicy, MetaDefinition, ProgramDefinition, } from "@tyndall/core";
+export declare const registerDynamicManifestModule: () => HyperPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AACxD,YAAY,EACV,oBAAoB,EACpB,yBAAyB,EACzB,2BAA2B,GAC5B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,oBAAoB,CAAC;AACvF,YAAY,EACV,sBAAsB,EACtB,uBAAuB,EACvB,8BAA8B,GAC/B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,qBAAqB,EACrB,2BAA2B,EAC3B,uBAAuB,EACvB,uBAAuB,IAAI,gBAAgB,EAC3C,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,eAAO,MAAM,6BAA6B,QAAO,WAiB/C,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+export { createDynamicManifestCache } from "./cache.js";
+export { createHttpResolver, createDynamicManifestResolver } from "./http-resolver.js";
+export { DEFAULT_PROGRAM_SANDBOX_POLICY, buildProgramSandboxContext, dynamicManifestSchema, resolveProgramSandboxPolicy, validateDynamicManifest, validateDynamicManifest as validateManifest, validateProgramIntegrity, } from "@tyndall/core";
+export const registerDynamicManifestModule = () => ({
+    name: "@tyndall/dynamic-manifest",
+    configResolved: (config) => {
+        if (config.modules.dynamicManifest.enabled) {
+            return;
+        }
+        return {
+            ...config,
+            modules: {
+                ...config.modules,
+                dynamicManifest: {
+                    ...config.modules.dynamicManifest,
+                    enabled: true,
+                },
+            },
+        };
+    },
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@tyndall/dynamic-manifest",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@tyndall/core": "workspace:*",
+    "@tyndall/shared": "workspace:*"
+  }
+}