@mapletip/data 0.1.0

package/client/monster-client.js

@@ -0,0 +1,155 @@
+import validateCatalog from '../generated/monster-catalog.validator.js';
+import validateCatalogV2 from '../generated/monster-catalog-2.validator.js';
+import { MissingPageError, MissingRecordError, SchemaValidationError, UnsupportedProductError, assertEnvelopeVersion, assertSameScope, lazyValidator, memoized, openProductContext, rangeDescriptor, recordRangeDescriptor, } from './core.js';
+const loadDetailPack = lazyValidator(() => import('../generated/monster-pack.validator.js'));
+const loadDetail = lazyValidator(() => import('../generated/monster-detail.validator.js'));
+const loadDetailPackV2 = lazyValidator(() => import('../generated/monster-pack-2.validator.js'));
+const loadDetailV2 = lazyValidator(() => import('../generated/monster-detail-2.validator.js'));
+const loadRelationships = lazyValidator(() => import('../generated/monster-relationship-pack.validator.js'));
+const loadLocationsV2 = lazyValidator(() => import('../generated/monster-location-pack-2.validator.js'));
+const loadCoreRelationshipsV2 = lazyValidator(() => import('../generated/monster-core-relationship-pack-2.validator.js'));
+const loadEvidence = lazyValidator(() => import('../generated/monster-evidence-pack.validator.js'));
+const loadEvidenceV2 = lazyValidator(() => import('../generated/monster-evidence-pack-2.validator.js'));
+/** Build a Monster client over an already verified product manifest. */
+export function monsterProductClient(context) {
+    const { manifest, contract2, fetchEnvelope } = context;
+    if (manifest.productId !== 'monsters')
+        throw new UnsupportedProductError(manifest.productId);
+    let catalogPromise;
+    const detailPackCache = new Map();
+    const detailPackV2Cache = new Map();
+    const relationshipPackCache = new Map();
+    const locationPackV2Cache = new Map();
+    const coreRelationshipPackCache = new Map();
+    const evidencePackCache = new Map();
+    const evidencePackV2Cache = new Map();
+    async function loadCatalog(operation) {
+        if (!catalogPromise) {
+            catalogPromise = contract2
+                ? fetchEnvelope(manifest.catalog, 'catalog', validateCatalogV2, operation)
+                : fetchEnvelope(manifest.catalog, 'catalog', validateCatalog, 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', 'Monster');
+        if (contract2) {
+            const [validatePack, validateRecord] = await Promise.all([loadDetailPackV2(), loadDetailV2()]);
+            const pack = await memoized(detailPackV2Cache, descriptor.path, () => (fetchEnvelope(descriptor, 'detail', validatePack, operation)));
+            if (!Object.hasOwn(pack.records, key))
+                throw new MissingRecordError(key);
+            const detail = pack.records[key];
+            if (!detail)
+                throw new MissingRecordError(key);
+            if (!validateRecord(detail)) {
+                throw new SchemaValidationError(descriptor.path, JSON.stringify(validateRecord.errors ?? []));
+            }
+            assertEnvelopeVersion(detail.contractVersion, context.minimumVersion, key);
+            assertSameScope(detail.scope, manifest.scope, key);
+            return detail;
+        }
+        const [validatePack, validateRecord] = await Promise.all([loadDetailPack(), loadDetail()]);
+        const pack = await memoized(detailPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'detail', validatePack, operation)));
+        if (!Object.hasOwn(pack.records, key))
+            throw new MissingRecordError(key);
+        const detail = pack.records[key];
+        if (!detail)
+            throw new MissingRecordError(key);
+        if (!validateRecord(detail)) {
+            throw new SchemaValidationError(descriptor.path, JSON.stringify(validateRecord.errors ?? []));
+        }
+        assertEnvelopeVersion(detail.contractVersion, context.minimumVersion, key);
+        assertSameScope(detail.scope, manifest.scope, key);
+        return detail;
+    }
+    async function getRelationshipPage(page, operation) {
+        if (contract2) {
+            if (page.recordKind !== 'locations')
+                throw new MissingPageError(page.recordKey, 'location');
+            const descriptor = rangeDescriptor(manifest.relationshipPacks, page.recordKey, 'location');
+            const validator = await loadLocationsV2();
+            const pack = await memoized(locationPackV2Cache, descriptor.path, () => (fetchEnvelope(descriptor, 'relationship', validator, operation)));
+            const record = pack.records[page.recordKey];
+            if (!record)
+                throw new MissingRecordError(page.recordKey);
+            if (record.occurrences.length !== page.count)
+                throw new MissingPageError(page.recordKey, 'location');
+            return record.occurrences;
+        }
+        if (page.recordKind !== 'relationships') {
+            throw new MissingPageError(page.recordKey, 'relationship');
+        }
+        const descriptor = rangeDescriptor(manifest.relationshipPacks, page.recordKey, 'relationship');
+        const validator = await loadRelationships();
+        const pack = await memoized(relationshipPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'relationship', validator, operation)));
+        if (!Object.hasOwn(pack.records, page.recordKey)) {
+            throw new MissingRecordError(page.recordKey);
+        }
+        const records = pack.records[page.recordKey];
+        if (!records || records.length !== page.count)
+            throw new MissingPageError(page.recordKey, 'relationship');
+        return records;
+    }
+    async function getEvidencePage(page, operation) {
+        if (contract2) {
+            if (page.recordKind !== 'drop-evidence' && page.recordKind !== 'quests') {
+                throw new MissingPageError(page.recordKey, 'evidence');
+            }
+            const descriptor = rangeDescriptor(manifest.evidencePacks ?? [], page.recordKey, 'evidence');
+            const validator = await loadEvidenceV2();
+            const pack = await memoized(evidencePackV2Cache, descriptor.path, () => (fetchEnvelope(descriptor, 'evidence', validator, operation)));
+            const record = pack.records[page.recordKey];
+            if (!record || (record.dropAssertions?.length ?? 0) + (record.quests?.length ?? 0) + (record.sourceEvidence?.length ?? 0) !== page.count) {
+                throw new MissingPageError(page.recordKey, 'evidence');
+            }
+            return record;
+        }
+        if (page.recordKind !== 'evidence') {
+            throw new MissingPageError(page.recordKey, 'evidence');
+        }
+        const descriptor = rangeDescriptor(manifest.evidencePacks ?? [], page.recordKey, 'evidence');
+        const validator = await loadEvidence();
+        const pack = await memoized(evidencePackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'evidence', validator, operation)));
+        if (!Object.hasOwn(pack.records, page.recordKey)) {
+            throw new MissingRecordError(page.recordKey);
+        }
+        const records = pack.records[page.recordKey];
+        if (!records || records.drops.length + records.quests.length !== page.count) {
+            throw new MissingPageError(page.recordKey, 'evidence');
+        }
+        return records;
+    }
+    async function getCoreRelationshipPage(page, operation) {
+        if (!contract2 || page.recordKind !== 'core-relationships') {
+            throw new MissingPageError(page.recordKey, 'core relationship');
+        }
+        const descriptor = rangeDescriptor(manifest.coreRelationshipPacks ?? [], page.recordKey, 'core relationship');
+        const validator = await loadCoreRelationshipsV2();
+        const pack = await memoized(coreRelationshipPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'core-relationship', validator, operation)));
+        const record = pack.records[page.recordKey];
+        if (!record || record.occurrences.length !== page.count) {
+            throw new MissingPageError(page.recordKey, 'core relationship');
+        }
+        return record;
+    }
+    return {
+        manifest,
+        loadCatalog,
+        getDetail,
+        getRelationshipPage,
+        getEvidencePage,
+        getCoreRelationshipPage,
+    };
+}
+/** Open one pinned Monster product. */
+export async function openMonsterProduct(options) {
+    return monsterProductClient(await openProductContext(options));
+}
+export function isMonsterProductClient(client) {
+    return client.manifest.productId === 'monsters' || client.manifest.productId === undefined;
+}

package/client/monsters.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@mapletip/data/monsters` — Monster browse and Monster product operations.
+ *
+ * This entry pulls the verified release core and the Monster client (with its catalog
+ * validators) and nothing else: Item, Equipment, Media, Quest, static-domain code and
+ * Monster detail/relationship/evidence validators stay out of the initial graph.
+ */
+import type { StaticMonsterCatalog } from './monster-client.js';
+import { type OpenReleaseOptions } from './release.js';
+export { isMonsterProductClient, openMonsterProduct } from './monster-client.js';
+export type { StaticMonsterCatalog, StaticMonsterDetail, StaticMonsterEvidencePage, StaticProductClient, } from './monster-client.js';
+export type { OpenReleaseOptions };
+/** Options for the one-shot Monster catalog read: an opened release plus the build to read. */
+export type GetMonsterBrowseOptions = OpenReleaseOptions & {
+    readonly buildId: string;
+};
+/**
+ * Read one build's verified Monster catalog in a single call.
+ *
+ * Equivalent to `openRelease(options)` → `openBuild(options.buildId)` →
+ * `loadCatalog()`; it adds no caching, fallback or alternate data path. Use the
+ * lower-level release client when several domain reads share one release.
+ */
+export declare function getMonsterBrowse(options: GetMonsterBrowseOptions): Promise<StaticMonsterCatalog>;

package/client/monsters.js

@@ -0,0 +1,14 @@
+import { openRelease } from './release.js';
+export { isMonsterProductClient, openMonsterProduct } from './monster-client.js';
+/**
+ * Read one build's verified Monster catalog in a single call.
+ *
+ * Equivalent to `openRelease(options)` → `openBuild(options.buildId)` →
+ * `loadCatalog()`; it adds no caching, fallback or alternate data path. Use the
+ * lower-level release client when several domain reads share one release.
+ */
+export async function getMonsterBrowse(options) {
+    const release = await openRelease(options);
+    const monster = await release.openBuild(options.buildId);
+    return monster.loadCatalog({ signal: options.signal });
+}

package/client/quests.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Quest product client. Every Quest validator is loaded on the first operation that
+ * needs it, so a Quest browse or detail read never downloads the others and no other
+ * domain downloads Quest validators.
+ */
+import type { QuestCatalog } from '../generated/quest-catalog-2.d.ts';
+import type { QuestBrowsePack, QuestBrowseRecord } from '../generated/quest-browse-pack-2.d.ts';
+import type { QuestDetailPack, QuestDetailRecord } from '../generated/quest-pack-2.d.ts';
+import type { QuestRelationshipPack, QuestRelationshipRecord } from '../generated/quest-relationship-pack-2.d.ts';
+import type { QuestAuxiliaryPack, QuestAuxiliaryPage } from '../generated/quest-auxiliary-pack-2.d.ts';
+import type { QuestEvidencePack, QuestEvidencePage } from '../generated/quest-evidence-pack-2.d.ts';
+import { type GetRelationshipOptions, type OpenProductOptions, type OperationOptions, type StaticProductManifest, type VerifiedProductContext } from './core.js';
+export type { GetRelationshipOptions };
+export type { QuestCatalog, QuestBrowsePack, QuestBrowseRecord, QuestDetailPack, QuestDetailRecord, QuestRelationshipPack, QuestRelationshipRecord, QuestAuxiliaryPack, QuestAuxiliaryPage, QuestEvidencePack, QuestEvidencePage, };
+export interface StaticQuestProductClient {
+    readonly manifest: StaticProductManifest;
+    loadCatalog(options?: OperationOptions): Promise<QuestCatalog>;
+    loadBrowsePacks(options?: OperationOptions): Promise<readonly QuestBrowsePack[]>;
+    getBrowseRecord(key: string, options?: OperationOptions): Promise<QuestBrowseRecord>;
+    getDetail(key: string, options?: OperationOptions): Promise<QuestDetailRecord>;
+    getRelationshipPage(pageKey: string, options?: GetRelationshipOptions): Promise<QuestRelationshipRecord>;
+    getAuxiliaryPage(pageKey: string, options?: OperationOptions): Promise<QuestAuxiliaryPage>;
+    getEvidencePage(pageKey: string, options?: OperationOptions): Promise<QuestEvidencePage>;
+}
+/** Build a Quest client over an already verified product manifest. */
+export declare function questProductClient(context: VerifiedProductContext): StaticQuestProductClient;
+/** Open one pinned Quest product. */
+export declare function openQuestProduct(options: OpenProductOptions): Promise<StaticQuestProductClient>;
+export declare function isQuestProductClient(client: {
+    readonly manifest: StaticProductManifest;
+}): client is StaticQuestProductClient;

package/client/quests.js

@@ -0,0 +1,124 @@
+import { MissingPageError, MissingRecordError, SchemaValidationError, ScopeError, UnsupportedCapabilityError, UnsupportedProductError, lazyValidator, memoized, openProductContext, rangeDescriptor, recordRangeDescriptor, } from './core.js';
+const loadCatalogValidator = lazyValidator(() => import('../generated/quest-catalog-2.validator.js'));
+const loadBrowsePackValidator = lazyValidator(() => import('../generated/quest-browse-pack-2.validator.js'));
+const loadDetailPackValidator = lazyValidator(() => import('../generated/quest-pack-2.validator.js'));
+const loadRelationshipPackValidator = lazyValidator(() => import('../generated/quest-relationship-pack-2.validator.js'));
+const loadAuxiliaryPackValidator = lazyValidator(() => import('../generated/quest-auxiliary-pack-2.validator.js'));
+const loadEvidencePackValidator = lazyValidator(() => import('../generated/quest-evidence-pack-2.validator.js'));
+/** Build a Quest client over an already verified product manifest. */
+export function questProductClient(context) {
+    const { manifest, fetchEnvelope } = context;
+    if (manifest.productId !== 'quests')
+        throw new UnsupportedProductError(manifest.productId);
+    let catalogPromise;
+    const browsePackCache = new Map();
+    const detailPackCache = new Map();
+    const relationshipPackCache = new Map();
+    const auxiliaryPackCache = new Map();
+    const evidencePackCache = new Map();
+    function loadCatalog(operation) {
+        if (!catalogPromise) {
+            catalogPromise = (async () => {
+                const validator = await loadCatalogValidator();
+                const catalog = await fetchEnvelope(manifest.catalog, 'catalog', validator, operation);
+                if (catalog.recordCount?.state === 'known' && catalog.records?.state === 'known') {
+                    if (catalog.recordCount.value !== catalog.records.items.length) {
+                        throw new SchemaValidationError(manifest.catalog.path, 'recordCount does not match records length');
+                    }
+                }
+                return catalog;
+            })();
+            void catalogPromise.catch(() => { catalogPromise = undefined; });
+        }
+        return catalogPromise;
+    }
+    async function loadBrowsePacks(operation) {
+        if (!manifest.browsePacks) {
+            throw new UnsupportedCapabilityError('Quest product manifest does not provide browse packs');
+        }
+        const packs = manifest.browsePacks;
+        const validator = await loadBrowsePackValidator();
+        return Promise.all(packs.map((descriptor) => (memoized(browsePackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'browse', validator, operation))))));
+    }
+    async function getBrowseRecord(key, operation) {
+        if (!manifest.browsePacks) {
+            throw new UnsupportedCapabilityError('Quest product manifest does not provide browse packs');
+        }
+        const descriptor = recordRangeDescriptor(manifest.browsePacks, key, 'browse', 'Quest');
+        const validator = await loadBrowsePackValidator();
+        const pack = await memoized(browsePackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'browse', validator, operation)));
+        if (!Object.hasOwn(pack.records, key))
+            throw new MissingRecordError(key, 'Quest');
+        const record = pack.records[key];
+        if (!record || record.key !== key)
+            throw new MissingRecordError(key, 'Quest');
+        return record;
+    }
+    async function getDetail(key, operation) {
+        const descriptor = recordRangeDescriptor(manifest.detailPacks, key, 'detail', 'Quest');
+        const validator = await loadDetailPackValidator();
+        const pack = await memoized(detailPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'detail', validator, operation)));
+        if (!Object.hasOwn(pack.records, key))
+            throw new MissingRecordError(key, 'Quest');
+        const detail = pack.records[key];
+        if (!detail || detail.key !== key)
+            throw new MissingRecordError(key, 'Quest');
+        return detail;
+    }
+    async function getRelationshipPage(pageKey, operation) {
+        const descriptor = rangeDescriptor(manifest.relationshipPacks, pageKey, 'relationship');
+        const validator = await loadRelationshipPackValidator();
+        const pack = await memoized(relationshipPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'relationship', validator, operation)));
+        if (!Object.hasOwn(pack.records, pageKey))
+            throw new MissingPageError(pageKey, 'relationship');
+        const record = pack.records[pageKey];
+        if (!record || record.recordKey !== pageKey)
+            throw new MissingPageError(pageKey, 'relationship');
+        if (operation?.expectedOwnerKey !== undefined && record.ownerKey !== operation.expectedOwnerKey) {
+            throw new ScopeError(`Relationship page ${pageKey} owner ${record.ownerKey} does not match expected ${operation.expectedOwnerKey}`);
+        }
+        return record;
+    }
+    async function getAuxiliaryPage(pageKey, operation) {
+        if (!manifest.coreRelationshipPacks || manifest.coreRelationshipPacks.length === 0) {
+            throw new UnsupportedCapabilityError('Quest product manifest does not provide auxiliary (coreRelationshipPacks) packs');
+        }
+        const descriptor = rangeDescriptor(manifest.coreRelationshipPacks, pageKey, 'auxiliary');
+        const validator = await loadAuxiliaryPackValidator();
+        const pack = await memoized(auxiliaryPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'auxiliary', validator, operation)));
+        if (!Object.hasOwn(pack.records, pageKey))
+            throw new MissingPageError(pageKey, 'auxiliary');
+        const page = pack.records[pageKey];
+        if (!page || page.recordKey !== pageKey)
+            throw new MissingPageError(pageKey, 'auxiliary');
+        return page;
+    }
+    async function getEvidencePage(pageKey, operation) {
+        const descriptor = rangeDescriptor(manifest.evidencePacks ?? [], pageKey, 'evidence');
+        const validator = await loadEvidencePackValidator();
+        const pack = await memoized(evidencePackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'evidence', validator, operation)));
+        if (!Object.hasOwn(pack.records, pageKey))
+            throw new MissingPageError(pageKey, 'evidence');
+        const page = pack.records[pageKey];
+        if (!page || page.recordKey !== pageKey)
+            throw new MissingPageError(pageKey, 'evidence');
+        return page;
+    }
+    return {
+        manifest,
+        loadCatalog,
+        loadBrowsePacks,
+        getBrowseRecord,
+        getDetail,
+        getRelationshipPage,
+        getAuxiliaryPage,
+        getEvidencePage,
+    };
+}
+/** Open one pinned Quest product. */
+export async function openQuestProduct(options) {
+    return questProductClient(await openProductContext(options));
+}
+export function isQuestProductClient(client) {
+    return client.manifest.productId === 'quests';
+}

package/client/release.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Verified release selection: immutable pin, release manifest and build index
+ * verification plus build-scoped product openers.
+ *
+ * The Monster client is a static dependency because `openBuild` is the release
+ * client's primary build selector and `getMonsterBrowse` must not defer code it
+ * immediately needs. Every other domain opener loads its implementation on demand, so
+ * release metadata verification and Monster selection never pull Item, Equipment,
+ * Media, Quest or static-domain code into a consumer's initial graph.
+ */
+import type { ReleaseBuildIndex } from '../generated/release-build-index.d.ts';
+import type { ReleaseManifest } from '../generated/release-manifest.d.ts';
+import type { ReleasePin } from '../generated/release-pin.d.ts';
+import { type RequestLogHook } from './core.js';
+import { type StaticProductClient } from './monster-client.js';
+import type { StaticItemProductClient } from './items.js';
+import type { StaticEquipmentProductClient } from './equipment.js';
+import type { StaticQuestProductClient } from './quests.js';
+import type { StaticMediaProductClient } from './media.js';
+import type { StaticDomainProductClient } from './static-domains.js';
+export type ReleaseProductDescriptor = ReleaseBuildIndex['builds'][number]['products'][number];
+export interface StaticReleaseBuild {
+    readonly family: string;
+    readonly build: string;
+    readonly productDescriptor?: ReleaseProductDescriptor;
+    readonly monsterProductDescriptor?: ReleaseProductDescriptor;
+    readonly itemProductDescriptor?: ReleaseProductDescriptor;
+    readonly equipmentProductDescriptor?: ReleaseProductDescriptor;
+    readonly questProductDescriptor?: ReleaseProductDescriptor;
+    readonly mediaProductDescriptor?: ReleaseProductDescriptor;
+    readonly domainProductDescriptors: Readonly<Record<string, ReleaseProductDescriptor>>;
+    readonly productCapabilities: readonly string[];
+}
+export interface OpenReleaseOptions {
+    /** Directory URL containing the selected release's content-addressed files. */
+    readonly baseUrl: string | URL;
+    /** Immutable local release pin. Its digest and byte length pin the manifest. */
+    readonly pin: ReleasePin;
+    /** Caller-injected immutable release metadata, verified before parsing. */
+    readonly preloaded?: {
+        readonly releaseManifest: Uint8Array | string;
+        readonly buildIndex: Uint8Array | string;
+    };
+    readonly signal?: AbortSignal;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly onRequest?: RequestLogHook;
+}
+export interface StaticReleaseClient {
+    readonly manifest: ReleaseManifest;
+    readonly builds: readonly StaticReleaseBuild[];
+    openBuild(buildId: string): Promise<StaticProductClient>;
+    openItemBuild(buildId: string): Promise<StaticItemProductClient>;
+    openEquipmentBuild(buildId: string): Promise<StaticEquipmentProductClient>;
+    openQuestBuild(buildId: string): Promise<StaticQuestProductClient>;
+    openMediaBuild(buildId: string): Promise<StaticMediaProductClient>;
+    openDomainBuild(buildId: string, domain: string): Promise<StaticDomainProductClient>;
+}
+export type TargetAvailability = 'available' | 'not-available' | 'unknown';
+/** Resolve a target against the verified product roster in its build envelope. */
+export declare function resolveTargetAvailability(build: Pick<StaticReleaseBuild, 'productCapabilities'>, target: Readonly<{
+    kind: string;
+}>): TargetAvailability;
+export declare function openRelease(options: OpenReleaseOptions): Promise<StaticReleaseClient>;