@mapletip/data 0.2.0 → 0.5.0

package/client/monster-client.js

@@ -1,6 +1,29 @@
 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';
+import validateCatalogV2_1 from '../generated/monster-catalog-2-1.validator.js';
+import validateCatalogV2_2 from '../generated/monster-catalog-2-2.validator.js';
+import validateCatalogV2_3 from '../generated/monster-catalog-2-3.validator.js';
+import validateDropBrowse from '../generated/monster-drop-browse.validator.js';
+import validateLocationBrowse from '../generated/monster-location-browse.validator.js';
+import validateLocationBrowseV1_1 from '../generated/monster-location-browse-1-1.validator.js';
+import { MissingPageError, MissingRecordError, SchemaValidationError, UnsupportedCapabilityError, UnsupportedProductError, assertEnvelopeVersion, assertSameScope, lazyValidator, memoized, openProductContext, rangeDescriptor, recordRangeDescriptor, } from './core.js';
+/**
+ * Contract-2 catalog validator that picks the revision's strict schema from the document's
+ * own `contractVersion`. Unsupported revisions fail the 2.0 schema with a typed error.
+ */
+const validateCatalogRevision = Object.assign((data) => {
+    const version = data?.contractVersion;
+    const validator = version === '2.3'
+        ? validateCatalogV2_3
+        : version === '2.2'
+            ? validateCatalogV2_2
+            : version === '2.1'
+                ? validateCatalogV2_1
+                : validateCatalogV2;
+    const valid = validator(data);
+    validateCatalogRevision.errors = validator.errors;
+    return valid;
+}, { errors: undefined });
 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'));
@@ -10,9 +33,16 @@ const loadLocationsV2 = lazyValidator(() => import('../generated/monster-locatio
 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'));
+const validateLocationBrowseRevision = Object.assign((data) => {
+    const version = data?.contractVersion;
+    const validator = version === '1.1' ? validateLocationBrowseV1_1 : validateLocationBrowse;
+    const valid = validator(data);
+    validateLocationBrowseRevision.errors = validator.errors;
+    return valid;
+}, { errors: undefined });
 /** Build a Monster client over an already verified product manifest. */
 export function monsterProductClient(context) {
-    const { manifest, contract2, fetchEnvelope } = context;
+    const { manifest, contract2, fetchJson, fetchEnvelope } = context;
     if (manifest.productId !== 'monsters')
         throw new UnsupportedProductError(manifest.productId);
     let catalogPromise;
@@ -26,7 +56,7 @@ export function monsterProductClient(context) {
     async function loadCatalog(operation) {
         if (!catalogPromise) {
             catalogPromise = contract2
-                ? fetchEnvelope(manifest.catalog, 'catalog', validateCatalogV2, operation)
+                ? fetchEnvelope(manifest.catalog, 'catalog', validateCatalogRevision, operation)
                 : fetchEnvelope(manifest.catalog, 'catalog', validateCatalog, operation);
             void catalogPromise.catch(() => { catalogPromise = undefined; });
         }
@@ -36,6 +66,26 @@ export function monsterProductClient(context) {
         }
         return catalog;
     }
+    async function loadBrowseArtifact(descriptor, capability, validator, label, operation) {
+        if (!(manifest.requiredClientCapabilities ?? []).includes(capability)) {
+            throw new UnsupportedCapabilityError('Monster product manifest does not require ' + capability);
+        }
+        if (!descriptor) {
+            throw new UnsupportedCapabilityError('Monster product manifest does not provide ' + label);
+        }
+        const raw = await fetchJson(descriptor, 'browse', operation);
+        if (!validator(raw)) {
+            throw new SchemaValidationError(descriptor.path, JSON.stringify(validator.errors ?? []));
+        }
+        assertSameScope(raw.scope, manifest.scope, descriptor.path);
+        return raw;
+    }
+    async function loadDropBrowse(operation) {
+        return loadBrowseArtifact(manifest.dropBrowse, 'monster-drop-browse-v1', validateDropBrowse, 'drop browse artifact', operation);
+    }
+    async function loadLocationBrowse(operation) {
+        return loadBrowseArtifact(manifest.locationBrowse, 'monster-location-browse-v1', validateLocationBrowseRevision, 'location browse artifact', operation);
+    }
     async function getDetail(key, operation) {
         const descriptor = recordRangeDescriptor(manifest.detailPacks, key, 'detail', 'Monster');
         if (contract2) {
@@ -140,6 +190,8 @@ export function monsterProductClient(context) {
     return {
         manifest,
         loadCatalog,
+        loadDropBrowse,
+        loadLocationBrowse,
         getDetail,
         getRelationshipPage,
         getEvidencePage,

package/client/monsters.d.ts

@@ -1,19 +1,25 @@
-/**
- * `@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 { MonsterCatalogV2_1 } from '../generated/monster-catalog-2-1.d.ts';
+import type { MonsterCatalogV2_2 } from '../generated/monster-catalog-2-2.d.ts';
+import type { MonsterCatalogV2_3 } from '../generated/monster-catalog-2-3.d.ts';
+import type { MonsterDropBrowseV1 } from '../generated/monster-drop-browse.d.ts';
+import type { MonsterLocationBrowseV1 } from '../generated/monster-location-browse.d.ts';
+import type { MonsterLocationBrowseV1_1 } from '../generated/monster-location-browse-1-1.d.ts';
+import type { StaticMonsterCatalog, StaticMonsterLocationBrowse } from './monster-client.js';
 import { type OpenReleaseOptions } from './release.js';
+export type { MonsterCatalogV2_3 };
 export { isMonsterProductClient, openMonsterProduct } from './monster-client.js';
 export type { StaticMonsterCatalog, StaticMonsterDetail, StaticMonsterEvidencePage, StaticProductClient, } from './monster-client.js';
+export type { MonsterDropBrowseV1, MonsterLocationBrowseV1, MonsterLocationBrowseV1_1 };
+export type { MonsterCatalogV2_1, MonsterCatalogV2_2 };
 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;
 };
+/** Options for one verified Monster drop browse artifact read. */
+export type GetMonsterDropBrowseOptions = GetMonsterBrowseOptions;
+/** Options for one verified Monster location browse artifact read. */
+export type GetMonsterLocationBrowseOptions = GetMonsterBrowseOptions;
 /**
  * Read one build's verified Monster catalog in a single call.
  *
@@ -22,3 +28,26 @@ export type GetMonsterBrowseOptions = OpenReleaseOptions & {
  * lower-level release client when several domain reads share one release.
  */
 export declare function getMonsterBrowse(options: GetMonsterBrowseOptions): Promise<StaticMonsterCatalog>;
+/** Read one build's manifest-pinned Monster drop browse artifact without caching or fallback. */
+export declare function getMonsterDropBrowse(options: GetMonsterDropBrowseOptions): Promise<MonsterDropBrowseV1>;
+/** Read one build's manifest-pinned Monster location browse artifact without caching or fallback. */
+export declare function getMonsterLocationBrowse(options: GetMonsterLocationBrowseOptions): Promise<StaticMonsterLocationBrowse>;
+/**
+ * Resolve one Monster sprite blob URL from a catalog row's known `sprite` content ID.
+ *
+ * The blob lives under the same release root as the catalog, so no Media product is
+ * opened. Throws `SchemaValidationError` for anything but a lowercase SHA-256 digest.
+ */
+export declare function monsterSpriteUrl(baseUrl: URL | string, contentId: string): string;
+/**
+ * Narrow a verified catalog to a revision whose rows carry `sprite`. Catalogs 2.1 and
+ * 2.2 include it; earlier pins do not. The loose 1.x type keeps a plain field check from
+ * narrowing.
+ */
+export declare function hasMonsterSprites(catalog: StaticMonsterCatalog): catalog is MonsterCatalogV2_1 | MonsterCatalogV2_2 | MonsterCatalogV2_3;
+/** Narrow a verified catalog to revisions with drop and location summaries. */
+export declare function hasMonsterBrowseSummaries(catalog: StaticMonsterCatalog): catalog is MonsterCatalogV2_2 | MonsterCatalogV2_3;
+/** Narrow a verified catalog to revision 2.3, whose rows carry geography key unions. */
+export declare function hasMonsterGeography(catalog: StaticMonsterCatalog): catalog is MonsterCatalogV2_3;
+/** Narrow a location browse artifact to revision 1.1, whose entries carry Map geography facts. */
+export declare function hasMonsterLocationGeography(browse: StaticMonsterLocationBrowse): browse is MonsterLocationBrowseV1_1;

package/client/monsters.js

@@ -1,3 +1,11 @@
+/**
+ * `@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 { resolveMediaContentUrl } from './core.js';
 import { openRelease } from './release.js';
 export { isMonsterProductClient, openMonsterProduct } from './monster-client.js';
 /**
@@ -12,3 +20,46 @@ export async function getMonsterBrowse(options) {
     const monster = await release.openBuild(options.buildId);
     return monster.loadCatalog({ signal: options.signal });
 }
+/** Read one build's manifest-pinned Monster drop browse artifact without caching or fallback. */
+export async function getMonsterDropBrowse(options) {
+    const release = await openRelease(options);
+    const monster = await release.openBuild(options.buildId);
+    return monster.loadDropBrowse({ signal: options.signal });
+}
+/** Read one build's manifest-pinned Monster location browse artifact without caching or fallback. */
+export async function getMonsterLocationBrowse(options) {
+    const release = await openRelease(options);
+    const monster = await release.openBuild(options.buildId);
+    return monster.loadLocationBrowse({ signal: options.signal });
+}
+/**
+ * Resolve one Monster sprite blob URL from a catalog row's known `sprite` content ID.
+ *
+ * The blob lives under the same release root as the catalog, so no Media product is
+ * opened. Throws `SchemaValidationError` for anything but a lowercase SHA-256 digest.
+ */
+export function monsterSpriteUrl(baseUrl, contentId) {
+    return resolveMediaContentUrl(baseUrl, contentId, 'Monster sprite');
+}
+/**
+ * Narrow a verified catalog to a revision whose rows carry `sprite`. Catalogs 2.1 and
+ * 2.2 include it; earlier pins do not. The loose 1.x type keeps a plain field check from
+ * narrowing.
+ */
+export function hasMonsterSprites(catalog) {
+    return catalog.format === 'mapletip.monster-catalog-2'
+        && (catalog.contractVersion === '2.1' || catalog.contractVersion === '2.2' || catalog.contractVersion === '2.3');
+}
+/** Narrow a verified catalog to revisions with drop and location summaries. */
+export function hasMonsterBrowseSummaries(catalog) {
+    return catalog.format === 'mapletip.monster-catalog-2'
+        && (catalog.contractVersion === '2.2' || catalog.contractVersion === '2.3');
+}
+/** Narrow a verified catalog to revision 2.3, whose rows carry geography key unions. */
+export function hasMonsterGeography(catalog) {
+    return catalog.format === 'mapletip.monster-catalog-2' && catalog.contractVersion === '2.3';
+}
+/** Narrow a location browse artifact to revision 1.1, whose entries carry Map geography facts. */
+export function hasMonsterLocationGeography(browse) {
+    return browse.format === 'mapletip.monster-location-browse' && browse.contractVersion === '1.1';
+}

package/client/static-client.d.ts

@@ -16,9 +16,9 @@ import { type StaticDomainProductClient } from './static-domains.js';
 export { ContractVersionError, IntegrityError, InvalidJsonError, InvalidPathError, MissingPageError, MissingRecordError, RequestError, SchemaValidationError, ScopeError, SecureContextRequiredError, StaticClientError, UnknownBuildError, UnsupportedCapabilityError, UnsupportedProductError, resolveMediaUrl, verifyBlob, } from './core.js';
 export type { GetRelationshipOptions, IntegrityDescriptor, OpenProductOptions, OperationOptions, ProductIdentity, ProductManifestDescriptor, ProductScope, RequestKind, RequestLogEntry, RequestLogHook, StaticProductManifest, } from './core.js';
 export { isMonsterProductClient, openMonsterProduct } from './monster-client.js';
-export type { StaticMonsterCatalog, StaticMonsterDetail, StaticMonsterEvidencePage, StaticProductClient, } from './monster-client.js';
-export { getItemBrowse, isItemProductClient, itemIconUrl, openItemProduct } from './items.js';
-export type { GetItemBrowseOptions, ItemBrowseCoverage, ItemBrowsePack, ItemBrowseRecord, ItemBrowseRow, StaticItemBrowse, StaticItemCatalog, StaticItemDetail, StaticItemProductClient, } from './items.js';
+export type { StaticMonsterCatalog, StaticMonsterDetail, StaticMonsterEvidencePage, StaticMonsterLocationBrowse, StaticProductClient, } from './monster-client.js';
+export { getItemBrowse, getItemRelatedEntities, hasItemPlayerFacts, isItemProductClient, itemIconUrl, openItemProduct, } from './items.js';
+export type { GetItemBrowseOptions, GetItemRelatedEntitiesOptions, ItemBrowseBuff, ItemBrowseBuffEffect, ItemBrowseBuffStat, ItemBrowseBuffUnit, ItemBrowseCoverage, ItemBrowseCoverageState, ItemBrowsePlayerFactCoverage, ItemBrowsePack, ItemBrowseJobFamily, ItemBrowseLevelRange, ItemBrowseRecovery, ItemBrowseRequirement, ItemBrowseRelationshipKind, ItemBrowseRecord, ItemBrowseRow, ItemRelatedEntityBrowsePack, ItemRelatedEntityTarget, StaticItemBrowse, StaticItemBrowseV2_0, StaticItemBrowseV2_1, StaticItemCatalog, StaticItemDetail, StaticItemProductClient, } from './items.js';
 export { isEquipmentProductClient, openEquipmentProduct } from './equipment.js';
 export type { StaticEquipmentCatalog, StaticEquipmentDetail, StaticEquipmentProductClient, } from './equipment.js';
 export { isMediaProductClient, openMediaProduct } from './media.js';
@@ -28,8 +28,10 @@ export type { QuestAuxiliaryPack, QuestAuxiliaryPage, QuestBrowsePack, QuestBrow
 export type { StaticDomainCatalog, StaticDomainCatalogRecord, StaticDomainDetailRecord, StaticDomainFactState, StaticDomainProductClient, StaticDomainSourceIdentity, } from './static-domains.js';
 export { openRelease, resolveTargetAvailability } from './release.js';
 export type { OpenReleaseOptions, ReleaseProductDescriptor, StaticReleaseBuild, StaticReleaseClient, TargetAvailability, } from './release.js';
-export { getMonsterBrowse } from './monsters.js';
-export type { GetMonsterBrowseOptions } from './monsters.js';
+export { getMonsterBrowse, getMonsterDropBrowse, getMonsterLocationBrowse, hasMonsterGeography, hasMonsterLocationGeography, hasMonsterBrowseSummaries, hasMonsterSprites, monsterSpriteUrl, } from './monsters.js';
+export type { GetMonsterBrowseOptions, GetMonsterDropBrowseOptions, GetMonsterLocationBrowseOptions, MonsterDropBrowseV1, MonsterLocationBrowseV1, MonsterLocationBrowseV1_1, MonsterCatalogV2_3, } from './monsters.js';
+export { getMapGeography, isMapGeographyModel, isMapProductClient, openMapProduct } from './maps.js';
+export type { GetMapGeographyOptions, MapGeographyModel, StaticMapProductClient } from './maps.js';
 export type AnyProductClient = StaticProductClient | StaticMediaProductClient | StaticQuestProductClient | StaticItemProductClient | StaticEquipmentProductClient | StaticDomainProductClient;
 /**
  * Open one pinned product of any supported domain.

package/client/static-client.js

@@ -15,12 +15,13 @@ import { questProductClient } from './quests.js';
 import { staticDomainProductClient } from './static-domains.js';
 export { ContractVersionError, IntegrityError, InvalidJsonError, InvalidPathError, MissingPageError, MissingRecordError, RequestError, SchemaValidationError, ScopeError, SecureContextRequiredError, StaticClientError, UnknownBuildError, UnsupportedCapabilityError, UnsupportedProductError, resolveMediaUrl, verifyBlob, } from './core.js';
 export { isMonsterProductClient, openMonsterProduct } from './monster-client.js';
-export { getItemBrowse, isItemProductClient, itemIconUrl, openItemProduct } from './items.js';
+export { getItemBrowse, getItemRelatedEntities, hasItemPlayerFacts, isItemProductClient, itemIconUrl, openItemProduct, } from './items.js';
 export { isEquipmentProductClient, openEquipmentProduct } from './equipment.js';
 export { isMediaProductClient, openMediaProduct } from './media.js';
 export { isQuestProductClient, openQuestProduct } from './quests.js';
 export { openRelease, resolveTargetAvailability } from './release.js';
-export { getMonsterBrowse } from './monsters.js';
+export { getMonsterBrowse, getMonsterDropBrowse, getMonsterLocationBrowse, hasMonsterGeography, hasMonsterLocationGeography, hasMonsterBrowseSummaries, hasMonsterSprites, monsterSpriteUrl, } from './monsters.js';
+export { getMapGeography, isMapGeographyModel, isMapProductClient, openMapProduct } from './maps.js';
 /**
  * Open one pinned product of any supported domain.
  *

package/client/static-domains.d.ts

@@ -4,6 +4,9 @@
  * envelopes are checked against the same contract/scope rules as every other pack.
  */
 import { type OpenProductOptions, type OperationOptions, type ProductScope, type StaticProductManifest, type VerifiedProductContext } from './core.js';
+import type { MapGeographyFact } from '../generated/map-catalog-2-1.d.ts';
+import type { MapGeographyModel } from '../generated/map-geography.d.ts';
+export type { MapGeographyFact, MapGeographyModel };
 export type StaticDomainFactState = {
     readonly state: 'known';
     readonly value: string;
@@ -24,10 +27,11 @@ export interface StaticDomainCatalogRecord {
     readonly sourceIdentity: StaticDomainSourceIdentity;
     readonly name: StaticDomainFactState;
     readonly facts: Readonly<Record<string, unknown>>;
+    readonly geography?: MapGeographyFact;
 }
 export interface StaticDomainCatalog {
     readonly format: 'mapletip.domain-catalog/1';
-    readonly contractVersion: string;
+    readonly contractVersion: '2.0' | '2.1';
     readonly scope: ProductScope;
     readonly domain: string;
     readonly coverage: 'partial';
@@ -40,8 +44,11 @@ export interface StaticDomainDetailRecord extends StaticDomainCatalogRecord {
 export interface StaticDomainProductClient {
     readonly manifest: StaticProductManifest;
     loadCatalog(options?: OperationOptions): Promise<StaticDomainCatalog>;
+    loadGeography(options?: OperationOptions): Promise<MapGeographyModel>;
     getDetail(key: string, options?: OperationOptions): Promise<StaticDomainDetailRecord>;
 }
+/** Type guard for the build-scoped, labeled Map geography read model. */
+export declare function isMapGeographyModel(value: unknown): value is MapGeographyModel;
 /** Build a static domain client over an already verified product manifest. */
 export declare function staticDomainProductClient(context: VerifiedProductContext): StaticDomainProductClient;
 /** Open one pinned static domain product. */

package/client/static-domains.js

@@ -3,7 +3,13 @@
  * cash-shop, avatars). These products carry no generated Ajv validators; their
  * envelopes are checked against the same contract/scope rules as every other pack.
  */
-import { MissingRecordError, SchemaValidationError, UnsupportedProductError, assertEnvelopeVersion, assertSameScope, isStaticDomain, memoized, openProductContext, recordRangeDescriptor, } from './core.js';
+import { MissingRecordError, SchemaValidationError, UnsupportedCapabilityError, UnsupportedProductError, assertEnvelopeVersion, assertSameScope, isStaticDomain, memoized, openProductContext, recordRangeDescriptor, } from './core.js';
+import validateMapCatalogV2_1 from '../generated/map-catalog-2-1.validator.js';
+import validateMapGeography from '../generated/map-geography.validator.js';
+/** Type guard for the build-scoped, labeled Map geography read model. */
+export function isMapGeographyModel(value) {
+    return validateMapGeography(value);
+}
 function asObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value)
         ? value
@@ -14,7 +20,8 @@ function assertDomainCatalog(value, path, manifest) {
     const records = object?.records;
     const scope = asObject(object?.scope);
     if (!object || object.format !== 'mapletip.domain-catalog/1'
-        || object.contractVersion !== '2.0'
+        || (object.contractVersion !== '2.0'
+            && !(manifest.productId === 'maps' && object.contractVersion === '2.1'))
         || object.domain !== manifest.productId
         || object.coverage !== 'partial'
         || !scope || scope.family_id !== manifest.scope.family_id || scope.build_id !== manifest.scope.build_id
@@ -23,6 +30,9 @@ function assertDomainCatalog(value, path, manifest) {
         || object.recordCount !== records.length) {
         throw new SchemaValidationError(path, 'invalid MapleKit normalized domain catalog envelope');
     }
+    if (object.contractVersion === '2.1' && !validateMapCatalogV2_1(value)) {
+        throw new SchemaValidationError(path, JSON.stringify(validateMapCatalogV2_1.errors ?? []));
+    }
     let previous = '';
     for (const recordValue of records) {
         const record = asObject(recordValue);
@@ -105,7 +115,21 @@ export function staticDomainProductClient(context) {
             throw new MissingRecordError(key, manifest.productId);
         return detail;
     }
-    return { manifest, loadCatalog, getDetail };
+    async function loadGeography(operation) {
+        const capability = 'map-geography-v1';
+        if (manifest.productId !== 'maps'
+            || !(manifest.requiredClientCapabilities ?? []).includes(capability)
+            || !manifest.geography) {
+            throw new UnsupportedCapabilityError('Maps product manifest does not provide map-geography-v1');
+        }
+        const raw = await fetchJson(manifest.geography, 'browse', operation);
+        if (!isMapGeographyModel(raw)) {
+            throw new SchemaValidationError(manifest.geography.path, JSON.stringify(validateMapGeography.errors ?? []));
+        }
+        assertSameScope(raw.scope, manifest.scope, manifest.geography.path);
+        return raw;
+    }
+    return { manifest, loadCatalog, loadGeography, getDetail };
 }
 /** Open one pinned static domain product. */
 export async function openStaticDomainProduct(options) {

package/generated/item-browse-pack-2.d.ts

@@ -4,6 +4,28 @@
  * Coverage state for one browse relationship or the Scroll tier facet.
  */
 export type ItemBrowseCoverageState = "complete" | "partial" | "unsupported";
+/**
+ * Closed player-stat vocabulary for consumable buffs.
+ */
+export type ItemBrowseBuffStat =
+  | "weaponAttack"
+  | "magicAttack"
+  | "weaponDefense"
+  | "magicDefense"
+  | "accuracy"
+  | "avoidability"
+  | "speed"
+  | "jump"
+  | "criticalRate"
+  | "criticalDamage"
+  | "maxHp"
+  | "maxMp"
+  | "itemDropRate"
+  | "mesoDropRate";
+/**
+ * Whether a buff effect is an absolute stat delta or a percentage.
+ */
+export type ItemBrowseBuffUnit = "flat" | "percent";
 /**
  * Positive source-backed Item behavior.
  */
@@ -34,6 +56,10 @@ export type CoverageKey = string;
  * Canonical non-equipment Item class.
  */
 export type ItemBrowseClass = "consume" | "etc" | "setup" | "cash" | "pet";
+/**
+ * Job family named by a source-backed Item requirement.
+ */
+export type ItemBrowseJobFamily = "beginner" | "warrior" | "magician" | "bowman" | "thief" | "pirate";
 /**
  * Named or typed Scroll mechanic.
  */
@@ -102,7 +128,7 @@ export type ItemBrowseType =
  * Bounded pack of compact browse rows keyed by Item public key.
  */
 export interface ItemBrowsePack {
-  contractVersion: "2.0";
+  contractVersion: "2.0" | "2.1";
   coverage: ItemBrowseCoverage;
   format: "item-browse-pack/1";
   records: {
@@ -114,9 +140,27 @@ export interface ItemBrowsePack {
  * Build-level coverage for the browse product.
  */
 export interface ItemBrowseCoverage {
+  /**
+   * Per-build availability of the sparse player-facing browse facts.
+   * Missing in Item Browse 2.0 documents; present in 2.1 documents.
+   */
+  playerFacts?: ItemBrowsePlayerFactCoverage | null;
   relationships: ItemBrowseRelationshipCoverage;
   scrollTier: ItemBrowseCoverageState;
 }
+/**
+ * Per-field source availability for player-facing browse facts in one build.
+ */
+export interface ItemBrowsePlayerFactCoverage {
+  buff: ItemBrowseCoverageState;
+  flatRecovery: ItemBrowseCoverageState;
+  levelRange: ItemBrowseCoverageState;
+  maxStack: ItemBrowseCoverageState;
+  percentRecovery: ItemBrowseCoverageState;
+  requirementJobs: ItemBrowseCoverageState;
+  requirementLevel: ItemBrowseCoverageState;
+  sellPrice: ItemBrowseCoverageState;
+}
 /**
  * Per-relationship coverage for one build.
  */
@@ -133,21 +177,52 @@ export interface ItemBrowseRelationshipCoverage {
  * One compact Item Browse row.
  */
 export interface ItemBrowseRecord {
+  buff?: ItemBrowseBuff | null;
   family?: string | null;
   functions?: ItemBrowseFunction[];
   icon: CatalogFact;
   itemClass: ItemBrowseClass;
+  levelRange?: ItemBrowseLevelRange | null;
+  maxStack?: number | null;
   name: CatalogFact;
   petFood?: ItemBrowsePetFood | null;
   projectileAttack?: number | null;
   questFlag?: boolean;
   recovery?: ItemBrowseRecovery | null;
   relationships?: ItemBrowseRelationshipCounts;
+  requirement?: ItemBrowseRequirement | null;
   scroll?: ItemBrowseScroll | null;
   seatingRecovery?: ItemBrowseSeatingRecovery | null;
+  /**
+   * Sparse facts. Omission means unknown unless coverage says unsupported.
+   */
+  sellPrice?: number | null;
   sourceId: string;
   types?: ItemBrowseType[];
 }
+/**
+ * Recognized consumable buffs and their optional source duration.
+ */
+export interface ItemBrowseBuff {
+  durationSeconds?: number | null;
+  effects: ItemBrowseBuffEffect[];
+}
+/**
+ * One recognized source-backed consumable buff effect.
+ */
+export interface ItemBrowseBuffEffect {
+  stat: ItemBrowseBuffStat;
+  unit: ItemBrowseBuffUnit;
+  value: number;
+}
+/**
+ * Separate level-band and requirement-level adjustment facts.
+ */
+export interface ItemBrowseLevelRange {
+  monsterLevelMax?: number | null;
+  monsterLevelMin?: number | null;
+  requirementLevelDelta?: number | null;
+}
 /**
  * Pet-food effect values and the Pet items they target.
  */
@@ -179,6 +254,13 @@ export interface ItemBrowseRelationshipCounts {
   "quest-reward"?: number | null;
   "used-in-recipe"?: number | null;
 }
+/**
+ * Requirement facts. The optional fields are sparse; absence means the source value is unknown.
+ */
+export interface ItemBrowseRequirement {
+  jobs?: ItemBrowseJobFamily[];
+  level?: number | null;
+}
 /**
  * Scroll facts derived from a typed upgrade row and its source title.
  */