@mapletip/data 0.1.0

package/client/core.js

@@ -0,0 +1,359 @@
+import validateManifest from '../generated/product-manifest.validator.js';
+import { assertCompatibleContractVersion, assertManifestCompatibility, minimumPackContractVersion, } from './contract-compatibility.mjs';
+export class StaticClientError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = new.target.name;
+        this.code = code;
+    }
+}
+export class SecureContextRequiredError extends StaticClientError {
+    constructor() {
+        super('SECURE_CONTEXT_REQUIRED', 'Public data verification requires a secure context with WebCrypto SHA-256 (HTTPS or localhost)');
+    }
+}
+export class IntegrityError extends StaticClientError {
+    constructor(message) {
+        super('INTEGRITY_ERROR', message);
+    }
+}
+export class RequestError extends StaticClientError {
+    constructor(message, options) {
+        super('REQUEST_ERROR', message, options);
+    }
+}
+export class InvalidPathError extends StaticClientError {
+    constructor(message) {
+        super('INVALID_PATH', message);
+    }
+}
+export class InvalidJsonError extends StaticClientError {
+    constructor(path, options) {
+        super('INVALID_JSON', `Invalid JSON in ${path}`, options);
+    }
+}
+export class SchemaValidationError extends StaticClientError {
+    constructor(path, details) {
+        super('SCHEMA_VALIDATION_ERROR', `Invalid public data at ${path}: ${details}`);
+    }
+}
+export class ContractVersionError extends StaticClientError {
+    constructor(message, options) {
+        super('CONTRACT_VERSION_ERROR', message, options);
+    }
+}
+export class UnsupportedCapabilityError extends StaticClientError {
+    constructor(message) {
+        super('UNSUPPORTED_CAPABILITY', message);
+    }
+}
+export class UnsupportedProductError extends StaticClientError {
+    constructor(productId) {
+        super('UNSUPPORTED_PRODUCT', `Unsupported public-data product: ${productId}`);
+    }
+}
+export class UnknownBuildError extends StaticClientError {
+    constructor(buildId) {
+        super('UNKNOWN_BUILD', `Build is not present in the pinned release: ${buildId}`);
+    }
+}
+export class ScopeError extends StaticClientError {
+    constructor(message) {
+        super('SCOPE_ERROR', message);
+    }
+}
+export class MissingRecordError extends StaticClientError {
+    constructor(key, domain = 'Monster') {
+        super('MISSING_RECORD', `${domain} record not found: ${key}`);
+    }
+}
+export class MissingPageError extends StaticClientError {
+    constructor(key, kind) {
+        super('MISSING_PAGE', `No ${kind} page pack addresses ${key}`);
+    }
+}
+export function normalizedBaseUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new InvalidPathError(`Product base URL must use HTTP or HTTPS: ${url.protocol}`);
+    }
+    if (!url.pathname.endsWith('/'))
+        url.pathname += '/';
+    url.search = '';
+    url.hash = '';
+    return url;
+}
+function resolveDescriptorUrl(baseUrl, path) {
+    if (!path || path.startsWith('/') || path.includes('\\')
+        || path.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        throw new InvalidPathError(`Expected a normalized relative POSIX path, got: ${path}`);
+    }
+    const url = new URL(path, baseUrl);
+    if (url.origin !== baseUrl.origin || !url.pathname.startsWith(baseUrl.pathname)) {
+        throw new InvalidPathError(`Descriptor path escapes product base URL: ${path}`);
+    }
+    return url;
+}
+function validateDescriptor(descriptor) {
+    if (!/^[0-9a-f]{64}$/.test(descriptor.sha256)) {
+        throw new IntegrityError(`Descriptor has an invalid SHA-256 digest: ${descriptor.path}`);
+    }
+    if (!Number.isSafeInteger(descriptor.byteLength) || descriptor.byteLength < 0) {
+        throw new IntegrityError(`Descriptor has an invalid byte length: ${descriptor.path}`);
+    }
+}
+async function sha256(bytes) {
+    if (globalThis.isSecureContext === false || !globalThis.crypto?.subtle) {
+        throw new SecureContextRequiredError();
+    }
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+export async function verifyBlob(bytes, descriptor) {
+    validateDescriptor(descriptor);
+    const actualSha256 = await sha256(bytes);
+    if (actualSha256 !== descriptor.sha256) {
+        throw new IntegrityError(`SHA-256 mismatch for ${descriptor.path}`);
+    }
+    if (bytes.byteLength !== descriptor.byteLength) {
+        throw new IntegrityError(`Byte length mismatch for ${descriptor.path}: expected ${descriptor.byteLength}, got ${bytes.byteLength}`);
+    }
+}
+export function resolveMediaUrl(baseUrl, descriptor) {
+    const base = baseUrl instanceof URL ? baseUrl : normalizedBaseUrl(baseUrl);
+    return resolveDescriptorUrl(base, descriptor.path).toString();
+}
+function parseJson(bytes, path) {
+    try {
+        return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError || error instanceof TypeError) {
+            throw new InvalidJsonError(path, { cause: error });
+        }
+        throw error;
+    }
+}
+async function parseVerifiedJson(bytes, descriptor) {
+    const actualSha256 = await sha256(bytes);
+    if (actualSha256 !== descriptor.sha256) {
+        throw new IntegrityError(`SHA-256 mismatch for ${descriptor.path}`);
+    }
+    if (bytes.byteLength !== descriptor.byteLength) {
+        throw new IntegrityError(`Byte length mismatch for ${descriptor.path}: expected ${descriptor.byteLength}, got ${bytes.byteLength}`);
+    }
+    return parseJson(bytes, descriptor.path);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function assertCompatibleManifest(manifest) {
+    try {
+        return assertManifestCompatibility(manifest);
+    }
+    catch (error) {
+        const message = errorMessage(error);
+        if (message.toLowerCase().includes('capability')) {
+            throw new UnsupportedCapabilityError(message);
+        }
+        throw new ContractVersionError(message, { cause: error });
+    }
+}
+export function createJsonFetcher(options) {
+    return async function fetchJson(descriptor, kind, operation) {
+        validateDescriptor(descriptor);
+        const url = resolveDescriptorUrl(options.baseUrl, descriptor.path);
+        options.onRequest?.({ kind, path: descriptor.path, url: url.href, source: 'network' });
+        let response;
+        try {
+            const fetcher = options.fetcher;
+            response = await fetcher(url, {
+                redirect: 'error',
+                signal: operation?.signal ?? options.signal,
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError')
+                throw error;
+            throw new RequestError(`Request failed for ${descriptor.path}`, { cause: error });
+        }
+        if (!response.ok) {
+            throw new RequestError(`HTTP ${response.status} fetching ${descriptor.path}`);
+        }
+        let bytes;
+        try {
+            bytes = new Uint8Array(await response.arrayBuffer());
+        }
+        catch (error) {
+            throw new RequestError(`Unable to read response bytes for ${descriptor.path}`, { cause: error });
+        }
+        return parseVerifiedJson(bytes, descriptor);
+    };
+}
+export async function parsePreloadedJson(value, descriptor, kind, baseUrl, onRequest) {
+    validateDescriptor(descriptor);
+    const url = resolveDescriptorUrl(baseUrl, descriptor.path);
+    onRequest?.({ kind, path: descriptor.path, url: url.href, source: 'preloaded' });
+    const bytes = typeof value === 'string' ? new TextEncoder().encode(value) : value;
+    return parseVerifiedJson(bytes, descriptor);
+}
+export function assertEnvelopeVersion(version, minimumVersion, path) {
+    try {
+        assertCompatibleContractVersion(version, minimumVersion);
+    }
+    catch (error) {
+        throw new ContractVersionError(`${path}: ${errorMessage(error)}`, { cause: error });
+    }
+}
+export function assertSameScope(actual, expected, path) {
+    if (actual.family_id !== expected.family_id || actual.build_id !== expected.build_id) {
+        throw new ScopeError(`${path} scope ${actual.family_id}/${actual.build_id} does not match expected `
+            + `${expected.family_id}/${expected.build_id}`);
+    }
+}
+export function rangeDescriptor(descriptors, key, kind) {
+    const matches = descriptors.filter((descriptor) => key >= descriptor.firstKey && key <= descriptor.lastKey);
+    if (matches.length !== 1)
+        throw new MissingPageError(key, kind);
+    return matches[0];
+}
+export function recordRangeDescriptor(descriptors, key, kind, domain = 'Monster') {
+    const matches = descriptors.filter((descriptor) => key >= descriptor.firstKey && key <= descriptor.lastKey);
+    if (matches.length === 0)
+        throw new MissingRecordError(key, domain);
+    if (matches.length > 1)
+        throw new MissingPageError(key, kind);
+    return matches[0];
+}
+export function memoized(cache, key, load) {
+    const existing = cache.get(key);
+    if (existing)
+        return existing;
+    const pending = load();
+    cache.set(key, pending);
+    void pending.catch(() => {
+        if (cache.get(key) === pending)
+            cache.delete(key);
+    });
+    return pending;
+}
+/**
+ * Wrap a static `import()` of one generated validator in a memoized loader.
+ * The import specifier stays literal so bundlers keep the validator in its own
+ * on-demand chunk; a rejected load is evicted so the next call retries.
+ */
+export function lazyValidator(load) {
+    let promise;
+    return () => {
+        if (!promise) {
+            promise = load().then((module) => module.default);
+            void promise.catch(() => { promise = undefined; });
+        }
+        return promise;
+    };
+}
+/** Static (validator-less) domain products served by the same release envelope. */
+const STATIC_DOMAIN_NAMES = new Set([
+    'maps',
+    'npcs',
+    'reactors',
+    'skills',
+    'jobs',
+    'recipes',
+    'cash-shop',
+    'avatars',
+]);
+export function isStaticDomain(domain) {
+    return STATIC_DOMAIN_NAMES.has(domain);
+}
+/** Product capability implied by a content-addressed product ID. */
+export function productCapability(productId) {
+    const match = /^(monsters|items|equipment|quests|media|maps|npcs|reactors|skills|jobs|recipes|cash-shop|avatars)-[0-9a-f]{64}$/u.exec(productId);
+    if (!match)
+        return undefined;
+    switch (match[1]) {
+        case 'monsters': return 'monster-core-v1';
+        case 'items': return 'items-v1';
+        case 'equipment': return 'equipment-v1';
+        case 'quests': return 'quests-v1';
+        case 'media': return 'media-v1';
+        case 'maps': return 'maps-v1';
+        case 'npcs': return 'npcs-v1';
+        case 'reactors': return 'reactors-v1';
+        case 'skills': return 'skills-v1';
+        case 'jobs': return 'jobs-v1';
+        case 'recipes': return 'recipes-v1';
+        case 'cash-shop': return 'cash-shop-v1';
+        case 'avatars': return 'avatars-v1';
+        default: return undefined;
+    }
+}
+/**
+ * Fetch, verify and validate one product manifest, then hand back the verified
+ * context that domain clients build on. This is the single manifest trust gate.
+ */
+export async function openProductContext(options) {
+    validateDescriptor(options.manifest);
+    const baseUrl = normalizedBaseUrl(options.baseUrl);
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const fetchJson = createJsonFetcher({
+        baseUrl,
+        fetcher,
+        onRequest: options.onRequest,
+        signal: options.signal,
+    });
+    const rawManifest = await fetchJson(options.manifest, 'manifest');
+    if (!validateManifest(rawManifest)) {
+        throw new SchemaValidationError(options.manifest.path, JSON.stringify(validateManifest.errors ?? []));
+    }
+    const manifest = rawManifest;
+    assertCompatibleManifest(manifest);
+    const minimumVersion = minimumPackContractVersion(manifest);
+    const contract2 = manifest.contractVersion === '2.0';
+    if (contract2) {
+        if (!manifest.identity || manifest.identity.identityFormat !== 'mapletip-product-id-v2') {
+            throw new ContractVersionError('contract-2.0 product requires product-id-v2 identity metadata');
+        }
+    }
+    assertSameScope(manifest.scope, options.expectedScope, options.manifest.path);
+    async function fetchEnvelope(descriptor, kind, validator, operation) {
+        const raw = await fetchJson(descriptor, kind, operation);
+        if (!validator(raw)) {
+            throw new SchemaValidationError(descriptor.path, JSON.stringify(validator.errors ?? []));
+        }
+        assertEnvelopeVersion(raw.contractVersion, minimumVersion, descriptor.path);
+        assertSameScope(raw.scope, manifest.scope, descriptor.path);
+        return raw;
+    }
+    async function fetchBlob(descriptor, operation) {
+        validateDescriptor(descriptor);
+        const url = resolveDescriptorUrl(baseUrl, descriptor.path);
+        options.onRequest?.({ kind: 'blob', path: descriptor.path, url: url.href, source: 'network' });
+        let response;
+        try {
+            response = await fetcher(url, {
+                redirect: 'error',
+                signal: operation?.signal ?? options.signal,
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError')
+                throw error;
+            throw new RequestError(`Request failed for ${descriptor.path}`, { cause: error });
+        }
+        if (!response.ok) {
+            throw new RequestError(`HTTP ${response.status} fetching ${descriptor.path}`);
+        }
+        let bytes;
+        try {
+            bytes = new Uint8Array(await response.arrayBuffer());
+        }
+        catch (error) {
+            throw new RequestError(`Unable to read response bytes for ${descriptor.path}`, { cause: error });
+        }
+        await verifyBlob(bytes, descriptor);
+        return bytes;
+    }
+    return { manifest, minimumVersion, contract2, fetchJson, fetchEnvelope, fetchBlob };
+}

package/client/equipment.d.ts

@@ -0,0 +1,22 @@
+import type { EquipmentCatalog } from '../generated/equipment-catalog-2.d.ts';
+import type { EquipmentDetailRecord } from '../generated/equipment-detail-2.d.ts';
+import type { EquipmentRelationshipPage } from '../generated/equipment-relationship-pack-2.d.ts';
+import type { EquipmentEvidencePage } from '../generated/equipment-evidence-pack-2.d.ts';
+import { type GetRelationshipOptions, type OpenProductOptions, type OperationOptions, type StaticProductManifest, type VerifiedProductContext } from './core.js';
+export type { GetRelationshipOptions };
+export type StaticEquipmentCatalog = EquipmentCatalog;
+export type StaticEquipmentDetail = EquipmentDetailRecord;
+export interface StaticEquipmentProductClient {
+    readonly manifest: StaticProductManifest;
+    loadCatalog(options?: OperationOptions): Promise<StaticEquipmentCatalog>;
+    getDetail(key: string, options?: OperationOptions): Promise<StaticEquipmentDetail>;
+    getRelationshipPage(pageKey: string, options?: GetRelationshipOptions): Promise<EquipmentRelationshipPage>;
+    getEvidencePage(pageKey: string, options?: OperationOptions): Promise<EquipmentEvidencePage>;
+}
+/** Build an Equipment client over an already verified product manifest. */
+export declare function equipmentProductClient(context: VerifiedProductContext): StaticEquipmentProductClient;
+/** Open one pinned Equipment product. */
+export declare function openEquipmentProduct(options: OpenProductOptions): Promise<StaticEquipmentProductClient>;
+export declare function isEquipmentProductClient(client: {
+    readonly manifest: StaticProductManifest;
+}): client is StaticEquipmentProductClient;

package/client/equipment.js

@@ -0,0 +1,63 @@
+import validateEquipmentCatalog from '../generated/equipment-catalog-2.validator.js';
+import validateEquipmentDetail from '../generated/equipment-detail-2.validator.js';
+import validateEquipmentDetailPack from '../generated/equipment-pack-2.validator.js';
+import validateEquipmentRelationshipPack from '../generated/equipment-relationship-pack-2.validator.js';
+import validateEquipmentEvidencePack from '../generated/equipment-evidence-pack-2.validator.js';
+import { MissingPageError, MissingRecordError, SchemaValidationError, ScopeError, UnsupportedProductError, memoized, openProductContext, rangeDescriptor, recordRangeDescriptor, } from './core.js';
+/** Build an Equipment client over an already verified product manifest. */
+export function equipmentProductClient(context) {
+    const { manifest, fetchEnvelope } = context;
+    if (manifest.productId !== 'equipment')
+        throw new UnsupportedProductError(manifest.productId);
+    let catalogPromise;
+    const detailPackCache = new Map();
+    const relationshipPackCache = new Map();
+    const evidencePackCache = new Map();
+    async function loadCatalog(operation) {
+        if (!catalogPromise) {
+            catalogPromise = fetchEnvelope(manifest.catalog, 'catalog', validateEquipmentCatalog, operation);
+            void catalogPromise.catch(() => { catalogPromise = undefined; });
+        }
+        return catalogPromise;
+    }
+    async function getDetail(key, operation) {
+        const descriptor = recordRangeDescriptor(manifest.detailPacks, key, 'detail', 'Equipment');
+        const pack = await memoized(detailPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'detail', validateEquipmentDetailPack, operation)));
+        if (!Object.hasOwn(pack.records, key))
+            throw new MissingRecordError(key, 'Equipment');
+        const detail = pack.records[key];
+        if (!detail)
+            throw new MissingRecordError(key, 'Equipment');
+        if (!validateEquipmentDetail(detail)) {
+            throw new SchemaValidationError(descriptor.path, JSON.stringify(validateEquipmentDetail.errors ?? []));
+        }
+        return detail;
+    }
+    async function getRelationshipPage(pageKey, operation) {
+        const descriptor = rangeDescriptor(manifest.relationshipPacks, pageKey, 'relationship');
+        const pack = await memoized(relationshipPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'relationship', validateEquipmentRelationshipPack, operation)));
+        const page = pack.records[pageKey];
+        if (!page)
+            throw new MissingPageError(pageKey, 'relationship');
+        if (operation?.expectedOwnerKey !== undefined && page.owner !== operation.expectedOwnerKey) {
+            throw new ScopeError(`Relationship page ${pageKey} owner ${page.owner} does not match expected ${operation.expectedOwnerKey}`);
+        }
+        return page;
+    }
+    async function getEvidencePage(pageKey, operation) {
+        const descriptor = rangeDescriptor(manifest.evidencePacks ?? [], pageKey, 'evidence');
+        const pack = await memoized(evidencePackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'evidence', validateEquipmentEvidencePack, operation)));
+        const page = pack.records[pageKey];
+        if (!page)
+            throw new MissingPageError(pageKey, 'evidence');
+        return page;
+    }
+    return { manifest, loadCatalog, getDetail, getRelationshipPage, getEvidencePage };
+}
+/** Open one pinned Equipment product. */
+export async function openEquipmentProduct(options) {
+    return equipmentProductClient(await openProductContext(options));
+}
+export function isEquipmentProductClient(client) {
+    return client.manifest.productId === 'equipment';
+}

package/client/items.d.ts

@@ -0,0 +1,22 @@
+import type { ItemCatalog } from '../generated/item-catalog-2.d.ts';
+import type { ItemDetailRecord } from '../generated/item-detail-2.d.ts';
+import type { ItemRelationshipPage } from '../generated/item-relationship-pack-2.d.ts';
+import type { ItemEvidencePage } from '../generated/item-evidence-pack-2.d.ts';
+import { type GetRelationshipOptions, type OpenProductOptions, type OperationOptions, type StaticProductManifest, type VerifiedProductContext } from './core.js';
+export type StaticItemCatalog = ItemCatalog;
+export type StaticItemDetail = ItemDetailRecord;
+export type { GetRelationshipOptions };
+export interface StaticItemProductClient {
+    readonly manifest: StaticProductManifest;
+    loadCatalog(options?: OperationOptions): Promise<StaticItemCatalog>;
+    getDetail(key: string, options?: OperationOptions): Promise<StaticItemDetail>;
+    getRelationshipPage(pageKey: string, options?: GetRelationshipOptions): Promise<ItemRelationshipPage>;
+    getEvidencePage(pageKey: string, options?: OperationOptions): Promise<ItemEvidencePage>;
+}
+/** Build an Item client over an already verified product manifest. */
+export declare function itemProductClient(context: VerifiedProductContext): StaticItemProductClient;
+/** Open one pinned Item product. */
+export declare function openItemProduct(options: OpenProductOptions): Promise<StaticItemProductClient>;
+export declare function isItemProductClient(client: {
+    readonly manifest: StaticProductManifest;
+}): client is StaticItemProductClient;

package/client/items.js

@@ -0,0 +1,63 @@
+import validateItemCatalog from '../generated/item-catalog-2.validator.js';
+import validateItemDetail from '../generated/item-detail-2.validator.js';
+import validateItemDetailPack from '../generated/item-pack-2.validator.js';
+import validateItemRelationshipPack from '../generated/item-relationship-pack-2.validator.js';
+import validateItemEvidencePack from '../generated/item-evidence-pack-2.validator.js';
+import { MissingPageError, MissingRecordError, SchemaValidationError, ScopeError, UnsupportedProductError, memoized, openProductContext, rangeDescriptor, recordRangeDescriptor, } from './core.js';
+/** Build an Item client over an already verified product manifest. */
+export function itemProductClient(context) {
+    const { manifest, fetchEnvelope } = context;
+    if (manifest.productId !== 'items')
+        throw new UnsupportedProductError(manifest.productId);
+    let catalogPromise;
+    const detailPackCache = new Map();
+    const relationshipPackCache = new Map();
+    const evidencePackCache = new Map();
+    async function loadCatalog(operation) {
+        if (!catalogPromise) {
+            catalogPromise = fetchEnvelope(manifest.catalog, 'catalog', validateItemCatalog, operation);
+            void catalogPromise.catch(() => { catalogPromise = undefined; });
+        }
+        return catalogPromise;
+    }
+    async function getDetail(key, operation) {
+        const descriptor = recordRangeDescriptor(manifest.detailPacks, key, 'detail', 'Item');
+        const pack = await memoized(detailPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'detail', validateItemDetailPack, operation)));
+        if (!Object.hasOwn(pack.records, key))
+            throw new MissingRecordError(key, 'Item');
+        const detail = pack.records[key];
+        if (!detail)
+            throw new MissingRecordError(key, 'Item');
+        if (!validateItemDetail(detail)) {
+            throw new SchemaValidationError(descriptor.path, JSON.stringify(validateItemDetail.errors ?? []));
+        }
+        return detail;
+    }
+    async function getRelationshipPage(pageKey, operation) {
+        const descriptor = rangeDescriptor(manifest.relationshipPacks, pageKey, 'relationship');
+        const pack = await memoized(relationshipPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'relationship', validateItemRelationshipPack, operation)));
+        const page = pack.records[pageKey];
+        if (!page)
+            throw new MissingPageError(pageKey, 'relationship');
+        if (operation?.expectedOwnerKey !== undefined && page.owner !== operation.expectedOwnerKey) {
+            throw new ScopeError(`Relationship page ${pageKey} owner ${page.owner} does not match expected ${operation.expectedOwnerKey}`);
+        }
+        return page;
+    }
+    async function getEvidencePage(pageKey, operation) {
+        const descriptor = rangeDescriptor(manifest.evidencePacks ?? [], pageKey, 'evidence');
+        const pack = await memoized(evidencePackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'evidence', validateItemEvidencePack, operation)));
+        const page = pack.records[pageKey];
+        if (!page)
+            throw new MissingPageError(pageKey, 'evidence');
+        return page;
+    }
+    return { manifest, loadCatalog, getDetail, getRelationshipPage, getEvidencePage };
+}
+/** Open one pinned Item product. */
+export async function openItemProduct(options) {
+    return itemProductClient(await openProductContext(options));
+}
+export function isItemProductClient(client) {
+    return client.manifest.productId === 'items';
+}

package/client/media.d.ts

@@ -0,0 +1,19 @@
+import type { MediaCatalog } from '../generated/media-catalog-2.d.ts';
+import type { MediaDetailRecord } from '../generated/media-detail-2.d.ts';
+import { type IntegrityDescriptor, type OpenProductOptions, type OperationOptions, type StaticProductManifest, type VerifiedProductContext } from './core.js';
+export { resolveMediaUrl, verifyBlob } from './core.js';
+export type StaticMediaCatalog = MediaCatalog;
+export type StaticMediaDetail = MediaDetailRecord;
+export interface StaticMediaProductClient {
+    readonly manifest: StaticProductManifest;
+    loadCatalog(options?: OperationOptions): Promise<StaticMediaCatalog>;
+    getDetail(key: string, options?: OperationOptions): Promise<StaticMediaDetail>;
+    fetchBlob(descriptor: IntegrityDescriptor, options?: OperationOptions): Promise<Uint8Array>;
+}
+/** Build a Media client over an already verified product manifest. */
+export declare function mediaProductClient(context: VerifiedProductContext): StaticMediaProductClient;
+/** Open one pinned Media product. */
+export declare function openMediaProduct(options: OpenProductOptions): Promise<StaticMediaProductClient>;
+export declare function isMediaProductClient(client: {
+    readonly manifest: StaticProductManifest;
+}): client is StaticMediaProductClient;

package/client/media.js

@@ -0,0 +1,47 @@
+import validateMediaCatalog from '../generated/media-catalog-2.validator.js';
+import validateMediaDetail from '../generated/media-detail-2.validator.js';
+import validateMediaDetailPack from '../generated/media-pack-2.validator.js';
+import { MissingRecordError, SchemaValidationError, UnsupportedProductError, assertEnvelopeVersion, assertSameScope, memoized, openProductContext, recordRangeDescriptor, } from './core.js';
+export { resolveMediaUrl, verifyBlob } from './core.js';
+/** Build a Media client over an already verified product manifest. */
+export function mediaProductClient(context) {
+    const { manifest, fetchEnvelope, fetchBlob } = context;
+    if (manifest.productId !== 'media')
+        throw new UnsupportedProductError(manifest.productId);
+    let catalogPromise;
+    const detailPackCache = new Map();
+    async function loadCatalog(operation) {
+        if (!catalogPromise) {
+            catalogPromise = fetchEnvelope(manifest.catalog, 'catalog', validateMediaCatalog, operation);
+            void catalogPromise.catch(() => { catalogPromise = undefined; });
+        }
+        const catalog = await catalogPromise;
+        if (catalog.records.length !== catalog.recordCount) {
+            throw new SchemaValidationError(manifest.catalog.path, 'recordCount does not match records length');
+        }
+        return catalog;
+    }
+    async function getDetail(key, operation) {
+        const descriptor = recordRangeDescriptor(manifest.detailPacks, key, 'detail', 'Media');
+        const pack = await memoized(detailPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'detail', validateMediaDetailPack, operation)));
+        if (!Object.hasOwn(pack.records, key))
+            throw new MissingRecordError(key);
+        const detail = pack.records[key];
+        if (!detail)
+            throw new MissingRecordError(key);
+        if (!validateMediaDetail(detail)) {
+            throw new SchemaValidationError(descriptor.path, JSON.stringify(validateMediaDetail.errors ?? []));
+        }
+        assertEnvelopeVersion(detail.contractVersion, context.minimumVersion, key);
+        assertSameScope(detail.scope, manifest.scope, key);
+        return detail;
+    }
+    return { manifest, loadCatalog, getDetail, fetchBlob };
+}
+/** Open one pinned Media product. */
+export async function openMediaProduct(options) {
+    return mediaProductClient(await openProductContext(options));
+}
+export function isMediaProductClient(client) {
+    return client.manifest.productId === 'media';
+}

package/client/monster-client.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Monster product client: verified catalog browse plus on-demand detail,
+ * location/relationship and evidence pages.
+ *
+ * Catalog validators are imported eagerly because a Monster browse cannot complete
+ * without them. Detail, relationship and evidence validators are loaded on the first
+ * operation that needs them, so a browse-only consumer never downloads them.
+ */
+import type { MonsterCatalog } from '../generated/monster-catalog.d.ts';
+import type { MonsterCatalogV2 } from '../generated/monster-catalog-2.d.ts';
+import type { MonsterDetailRecord, PageDescriptor } from '../generated/monster-detail.d.ts';
+import type { MonsterDetailRecordV2 } from '../generated/monster-detail-2.d.ts';
+import type { MonsterEvidencePage } from '../generated/monster-evidence-pack.d.ts';
+import type { MonsterEvidencePageV2 } from '../generated/monster-evidence-pack-2.d.ts';
+import type { MonsterLocationOccurrence } from '../generated/monster-relationship-pack.d.ts';
+import type { MonsterCoreRelationshipPackV2 } from '../generated/monster-core-relationship-pack-2.d.ts';
+import { type OpenProductOptions, type OperationOptions, type StaticProductManifest, type VerifiedProductContext } from './core.js';
+export type StaticMonsterCatalog = MonsterCatalog | MonsterCatalogV2;
+export type StaticMonsterDetail = MonsterDetailRecord | MonsterDetailRecordV2;
+export type StaticMonsterEvidencePage = MonsterEvidencePage | MonsterEvidencePageV2;
+export interface StaticProductClient {
+    readonly manifest: StaticProductManifest;
+    loadCatalog(options?: OperationOptions): Promise<StaticMonsterCatalog>;
+    getDetail(key: string, options?: OperationOptions): Promise<StaticMonsterDetail>;
+    getRelationshipPage(page: PageDescriptor, options?: OperationOptions): Promise<MonsterLocationOccurrence[]>;
+    getEvidencePage(page: PageDescriptor, options?: OperationOptions): Promise<StaticMonsterEvidencePage>;
+    getCoreRelationshipPage(page: PageDescriptor, options?: OperationOptions): Promise<MonsterCoreRelationshipPackV2['records'][string]>;
+}
+/** Build a Monster client over an already verified product manifest. */
+export declare function monsterProductClient(context: VerifiedProductContext): StaticProductClient;
+/** Open one pinned Monster product. */
+export declare function openMonsterProduct(options: OpenProductOptions): Promise<StaticProductClient>;
+export declare function isMonsterProductClient(client: {
+    readonly manifest: StaticProductManifest;
+}): client is StaticProductClient;