@mapletip/data 0.5.0 → 0.6.0

package/README.md

@@ -82,11 +82,31 @@ digest. `getMonsterBrowse` still requests only the release manifest named by the
 build index, the product manifest and the Monster catalog.
 
 Releases built before revision `2.1` carry contract-`2.0` catalogs without `sprite`; this
-SDK reads both, and `hasMonsterSprites` narrows a catalog to revisions `2.1` or `2.2`. `@mapletip/data`
+SDK reads both, and `hasMonsterSprites` narrows a catalog to revisions `2.1` through `2.4`. `@mapletip/data`
 `0.2.0` and older reject a `2.1` catalog with a typed `SCHEMA_VALIDATION_ERROR` instead of
 returning rows without sprites, so upgrade to `0.3.0` before adopting a pin that carries
 it.
 
+### Monster HP and MP recovery
+
+Catalog revision `2.4` adds independent `hpRecovery` and `mpRecovery` facts to each row.
+`known` preserves the source integer, including zero; `unknown`, `absent` with its
+coverage key, and `unsupported` remain distinct. One field's value or state says nothing
+about the other. No recovery interval or per-second unit is established, so describe
+these as HP and MP recovery values rather than rates.
+
+```ts
+import { getMonsterBrowse } from '@mapletip/data/monsters';
+
+const catalog = await getMonsterBrowse({ baseUrl: releaseRootUrl, pin: releasePin, buildId: 'gms-v83' });
+if (catalog.format === 'mapletip.monster-catalog-2' && catalog.contractVersion === '2.4') {
+  const recoveries = catalog.records.map((row) => ({
+    hpRecovery: row.hpRecovery.state === 'known' ? row.hpRecovery.value : row.hpRecovery.state,
+    mpRecovery: row.mpRecovery.state === 'known' ? row.mpRecovery.value : row.mpRecovery.state,
+  }));
+}
+```
+
 ### Monster drops and locations
 
 Monster catalog `2.2` keeps these summaries on every Monster row. The catalog-level
@@ -133,6 +153,30 @@ const monstersWithItem = Object.entries(dropBrowse.records)
   .map(([monsterKey]) => monsterKey);
 ```
 
+Drop browse revision `1.1` adds each resolved distinct item's same-build Media icon fact to
+the `items[]` table. Use `itemIconUrl` only for a `known` icon; for other states, keep the
+item name visible without substituting another image. The icon is already in the drop
+browse artifact, so this read does not need an Item, Equipment or Media request:
+
+```ts
+import { getMonsterDropBrowse } from '@mapletip/data/monsters';
+import { itemIconUrl } from '@mapletip/data/items';
+
+const dropBrowse = await getMonsterDropBrowse({
+  baseUrl: releaseRootUrl,
+  pin: releasePin,
+  buildId: 'cw-launch',
+});
+if (dropBrowse.contractVersion === '1.1') {
+  const items = dropBrowse.items.map((item) => ({
+    name: item.itemName.state === 'known' ? item.itemName.value : 'Unknown item',
+    iconUrl: item.icon.state === 'known'
+      ? itemIconUrl(releaseRootUrl, item.icon.value)
+      : undefined,
+  }));
+}
+```
+
 Location summaries count client map placements, not live spawn rates. `known` carries
 distinct map and placement counts; `absent` carries neither count and uses the
 catalog-level coverage key; `unresolved` carries counts for the resolved portion when

package/client/items.js

@@ -189,5 +189,39 @@ export async function getItemRelatedEntities(options) {
 }
 /** Resolve one Item icon blob URL from its content-addressed media digest. */
 export function itemIconUrl(baseUrl, contentId) {
-    return resolveMediaContentUrl(baseUrl, contentId, 'Item icon');
+    return resolveMediaContentUrl(baseUrl, compactSha256ToHex(contentId) ?? contentId, 'Item icon');
+}
+/** Expand the drop-browse base64url digest while keeping the resolver's hex contract. */
+function compactSha256ToHex(value) {
+    if (value.length !== 43)
+        return undefined;
+    const bytes = [];
+    let accumulator = 0;
+    let bitCount = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        const sextet = code >= 65 && code <= 90
+            ? code - 65
+            : code >= 97 && code <= 122
+                ? code - 97 + 26
+                : code >= 48 && code <= 57
+                    ? code - 48 + 52
+                    : code === 45
+                        ? 62
+                        : code === 95
+                            ? 63
+                            : -1;
+        if (sextet < 0)
+            return undefined;
+        accumulator = (accumulator << 6) | sextet;
+        bitCount += 6;
+        if (bitCount >= 8) {
+            bitCount -= 8;
+            bytes.push((accumulator >> bitCount) & 0xff);
+            accumulator &= (1 << bitCount) - 1;
+        }
+    }
+    if (bytes.length !== 32 || bitCount !== 2 || accumulator !== 0)
+        return undefined;
+    return bytes.map((byte) => byte.toString(16).padStart(2, '0')).join('');
 }

package/client/monster-client.d.ts

@@ -11,7 +11,10 @@ import type { MonsterCatalogV2 } from '../generated/monster-catalog-2.d.ts';
 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 { MonsterCatalogV2_4 } from '../generated/monster-catalog-2-4.d.ts';
 import type { MonsterDropBrowseV1 } from '../generated/monster-drop-browse.d.ts';
+import type { MonsterDropBrowseItemV1_1, MonsterDropBrowseV1_1 } from '../generated/monster-drop-browse-1-1.d.ts';
+import type { CatalogFact as CatalogFact2 } from '../generated/contract-2-catalog-fact.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 { MonsterDetailRecord, PageDescriptor } from '../generated/monster-detail.d.ts';
@@ -22,17 +25,24 @@ import type { MonsterLocationOccurrence } from '../generated/monster-relationshi
 import type { MonsterCoreRelationshipPackV2 } from '../generated/monster-core-relationship-pack-2.d.ts';
 import { type OpenProductOptions, type OperationOptions, type StaticProductManifest, type VerifiedProductContext } from './core.js';
 /**
- * A verified Monster catalog. Contracts 2.1 and 2.2 carry the Media content ID fact
- * for a monster's representative image; 2.0 and 1.x records have none.
+ * A verified Monster catalog. Contracts 2.1 through 2.4 carry the Media content ID
+ * fact for a monster's representative image; 2.0 and 1.x records have none.
  */
-export type StaticMonsterCatalog = MonsterCatalog | MonsterCatalogV2 | MonsterCatalogV2_1 | MonsterCatalogV2_2 | MonsterCatalogV2_3;
+export type StaticMonsterCatalog = MonsterCatalog | MonsterCatalogV2 | MonsterCatalogV2_1 | MonsterCatalogV2_2 | MonsterCatalogV2_3 | MonsterCatalogV2_4;
+type StaticMonsterDropBrowseItemV1_1 = Omit<MonsterDropBrowseItemV1_1, 'icon'> & {
+    readonly icon: CatalogFact2<string>;
+};
+export type StaticMonsterDropBrowseV1_1 = Omit<MonsterDropBrowseV1_1, 'items' | 'itemIcons'> & {
+    readonly items: StaticMonsterDropBrowseItemV1_1[];
+};
+export type StaticMonsterDropBrowse = MonsterDropBrowseV1 | StaticMonsterDropBrowseV1_1;
 export type StaticMonsterLocationBrowse = MonsterLocationBrowseV1 | MonsterLocationBrowseV1_1;
 export type StaticMonsterDetail = MonsterDetailRecord | MonsterDetailRecordV2;
 export type StaticMonsterEvidencePage = MonsterEvidencePage | MonsterEvidencePageV2;
 export interface StaticProductClient {
     readonly manifest: StaticProductManifest;
     loadCatalog(options?: OperationOptions): Promise<StaticMonsterCatalog>;
-    loadDropBrowse(options?: OperationOptions): Promise<MonsterDropBrowseV1>;
+    loadDropBrowse(options?: OperationOptions): Promise<StaticMonsterDropBrowse>;
     loadLocationBrowse(options?: OperationOptions): Promise<StaticMonsterLocationBrowse>;
     getDetail(key: string, options?: OperationOptions): Promise<StaticMonsterDetail>;
     getRelationshipPage(page: PageDescriptor, options?: OperationOptions): Promise<MonsterLocationOccurrence[]>;
@@ -46,3 +56,4 @@ export declare function openMonsterProduct(options: OpenProductOptions): Promise
 export declare function isMonsterProductClient(client: {
     readonly manifest: StaticProductManifest;
 }): client is StaticProductClient;
+export {};

package/client/monster-client.js

@@ -3,7 +3,9 @@ import validateCatalogV2 from '../generated/monster-catalog-2.validator.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 validateCatalogV2_4 from '../generated/monster-catalog-2-4.validator.js';
 import validateDropBrowse from '../generated/monster-drop-browse.validator.js';
+import validateDropBrowseV1_1 from '../generated/monster-drop-browse-1-1.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';
@@ -13,13 +15,15 @@ import { MissingPageError, MissingRecordError, SchemaValidationError, Unsupporte
  */
 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 validator = version === '2.4'
+        ? validateCatalogV2_4
+        : 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;
@@ -40,6 +44,49 @@ const validateLocationBrowseRevision = Object.assign((data) => {
     validateLocationBrowseRevision.errors = validator.errors;
     return valid;
 }, { errors: undefined });
+const validateDropBrowseRevision = Object.assign((data) => {
+    const version = data?.contractVersion;
+    const validator = version === '1.1' ? validateDropBrowseV1_1 : validateDropBrowse;
+    const valid = validator(data);
+    validateDropBrowseRevision.errors = validator.errors;
+    return valid;
+}, { errors: undefined });
+function compactSha256ToHex(value) {
+    if (value.length !== 43) {
+        throw new SchemaValidationError('dropBrowse.itemIcons', 'compact Media ID must be 43-character base64url');
+    }
+    const bytes = [];
+    let accumulator = 0;
+    let bitCount = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        const sextet = code >= 65 && code <= 90
+            ? code - 65
+            : code >= 97 && code <= 122
+                ? code - 97 + 26
+                : code >= 48 && code <= 57
+                    ? code - 48 + 52
+                    : code === 45
+                        ? 62
+                        : code === 95
+                            ? 63
+                            : -1;
+        if (sextet < 0) {
+            throw new SchemaValidationError('dropBrowse.itemIcons', 'compact Media ID is not base64url');
+        }
+        accumulator = (accumulator << 6) | sextet;
+        bitCount += 6;
+        if (bitCount >= 8) {
+            bitCount -= 8;
+            bytes.push((accumulator >> bitCount) & 0xff);
+            accumulator &= (1 << bitCount) - 1;
+        }
+    }
+    if (bytes.length !== 32 || bitCount !== 2 || accumulator !== 0) {
+        throw new SchemaValidationError('dropBrowse.itemIcons', 'compact Media ID is not a canonical SHA-256 digest');
+    }
+    return bytes.map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
 /** Build a Monster client over an already verified product manifest. */
 export function monsterProductClient(context) {
     const { manifest, contract2, fetchJson, fetchEnvelope } = context;
@@ -81,7 +128,31 @@ export function monsterProductClient(context) {
         return raw;
     }
     async function loadDropBrowse(operation) {
-        return loadBrowseArtifact(manifest.dropBrowse, 'monster-drop-browse-v1', validateDropBrowse, 'drop browse artifact', operation);
+        const browse = await loadBrowseArtifact(manifest.dropBrowse, 'monster-drop-browse-v1', validateDropBrowseRevision, 'drop browse artifact', operation);
+        if (browse.contractVersion !== '1.1')
+            return browse;
+        if (browse.items.length !== browse.itemIcons.length) {
+            throw new SchemaValidationError(manifest.dropBrowse?.path ?? 'dropBrowse', 'itemIcons length does not match items');
+        }
+        const items = browse.items.map((item, index) => {
+            const icon = browse.itemIcons[index];
+            if (icon === undefined) {
+                throw new SchemaValidationError(manifest.dropBrowse?.path ?? 'dropBrowse', 'item icon fact is missing');
+            }
+            return {
+                ...item,
+                icon: typeof icon === 'string'
+                    ? { state: 'known', value: compactSha256ToHex(icon) }
+                    : icon,
+            };
+        });
+        return {
+            format: browse.format,
+            contractVersion: browse.contractVersion,
+            scope: browse.scope,
+            items,
+            records: browse.records,
+        };
     }
     async function loadLocationBrowse(operation) {
         return loadBrowseArtifact(manifest.locationBrowse, 'monster-location-browse-v1', validateLocationBrowseRevision, 'location browse artifact', operation);

package/client/monsters.d.ts

@@ -1,15 +1,17 @@
 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 { MonsterCatalogV2_4 } from '../generated/monster-catalog-2-4.d.ts';
 import type { MonsterDropBrowseV1 } from '../generated/monster-drop-browse.d.ts';
+import type { MonsterDropBrowseV1_1 } from '../generated/monster-drop-browse-1-1.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 { StaticMonsterCatalog, StaticMonsterDropBrowse, StaticMonsterLocationBrowse } from './monster-client.js';
 import { type OpenReleaseOptions } from './release.js';
-export type { MonsterCatalogV2_3 };
+export type { MonsterCatalogV2_3, MonsterCatalogV2_4 };
 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 { StaticMonsterDropBrowse, StaticMonsterDropBrowseV1_1, StaticMonsterCatalog, StaticMonsterDetail, StaticMonsterEvidencePage, StaticProductClient, } from './monster-client.js';
+export type { MonsterDropBrowseV1, MonsterDropBrowseV1_1, 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. */
@@ -29,7 +31,7 @@ export type GetMonsterLocationBrowseOptions = GetMonsterBrowseOptions;
  */
 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>;
+export declare function getMonsterDropBrowse(options: GetMonsterDropBrowseOptions): Promise<StaticMonsterDropBrowse>;
 /** Read one build's manifest-pinned Monster location browse artifact without caching or fallback. */
 export declare function getMonsterLocationBrowse(options: GetMonsterLocationBrowseOptions): Promise<StaticMonsterLocationBrowse>;
 /**
@@ -40,14 +42,17 @@ export declare function getMonsterLocationBrowse(options: GetMonsterLocationBrow
  */
 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
+ * Narrow a verified catalog to a revision whose rows carry `sprite`. Catalogs 2.1, 2.2,
+ * 2.3, and 2.4 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;
+export declare function hasMonsterSprites(catalog: StaticMonsterCatalog): catalog is MonsterCatalogV2_1 | MonsterCatalogV2_2 | MonsterCatalogV2_3 | MonsterCatalogV2_4;
 /** 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;
+export declare function hasMonsterBrowseSummaries(catalog: StaticMonsterCatalog): catalog is MonsterCatalogV2_2 | MonsterCatalogV2_3 | MonsterCatalogV2_4;
+/**
+ * Narrow a verified catalog to revisions with geography-key fields. Revision 2.4 permits
+ * the row field to be omitted when the same-build Map product has no genuine geography.
+ */
+export declare function hasMonsterGeography(catalog: StaticMonsterCatalog): catalog is MonsterCatalogV2_3 | MonsterCatalogV2_4;
 /** 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

@@ -42,22 +42,28 @@ 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
+ * Narrow a verified catalog to a revision whose rows carry `sprite`. Catalogs 2.1, 2.2,
+ * 2.3, and 2.4 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');
+        && (catalog.contractVersion === '2.1' || catalog.contractVersion === '2.2'
+            || catalog.contractVersion === '2.3' || catalog.contractVersion === '2.4');
 }
 /** 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');
+        && (catalog.contractVersion === '2.2' || catalog.contractVersion === '2.3'
+            || catalog.contractVersion === '2.4');
 }
-/** Narrow a verified catalog to revision 2.3, whose rows carry geography key unions. */
+/**
+ * Narrow a verified catalog to revisions with geography-key fields. Revision 2.4 permits
+ * the row field to be omitted when the same-build Map product has no genuine geography.
+ */
 export function hasMonsterGeography(catalog) {
-    return catalog.format === 'mapletip.monster-catalog-2' && catalog.contractVersion === '2.3';
+    return catalog.format === 'mapletip.monster-catalog-2'
+        && (catalog.contractVersion === '2.3' || catalog.contractVersion === '2.4');
 }
 /** Narrow a location browse artifact to revision 1.1, whose entries carry Map geography facts. */
 export function hasMonsterLocationGeography(browse) {

package/client/static-client.d.ts

@@ -29,7 +29,7 @@ export type { StaticDomainCatalog, StaticDomainCatalogRecord, StaticDomainDetail
 export { openRelease, resolveTargetAvailability } from './release.js';
 export type { OpenReleaseOptions, ReleaseProductDescriptor, StaticReleaseBuild, StaticReleaseClient, TargetAvailability, } from './release.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 type { GetMonsterBrowseOptions, GetMonsterDropBrowseOptions, GetMonsterLocationBrowseOptions, MonsterDropBrowseV1, MonsterDropBrowseV1_1, MonsterLocationBrowseV1, MonsterLocationBrowseV1_1, StaticMonsterDropBrowse, MonsterCatalogV2_3, MonsterCatalogV2_4, } 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;