feat: new approach to mappings (#282)

Co-authored-by: LautaroPetaccio <[email protected]>

.github/workflows/build-and-publish.yml

@@ -11,7 +11,7 @@ jobs:
     outputs:
       s3_bucket_key: ${{ steps.publish_package.outputs.s3-bucket-key }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: install
         run: npm ci
       - name: build
@@ -52,7 +52,7 @@ jobs:
     name: Deployment Notification
     steps:
       - name: Find Comment
-        uses: peter-evans/find-comment@v2
+        uses: peter-evans/find-comment@v3
         id: fc
         with:
           issue-number: ${{ github.event.pull_request.number }}
@@ -64,7 +64,7 @@ jobs:
         run: echo "body=${{ secrets.SDK_TEAM_S3_BASE_URL }}/${{ needs.check_and_build.outputs.s3_bucket_key }}" >> $GITHUB_OUTPUT
 
       - name: Create or update comment
-        uses: peter-evans/create-or-update-comment@v3
+        uses: peter-evans/create-or-update-comment@v4
         with:
           comment-id: ${{ steps.fc.outputs.comment-id }}
           issue-number: ${{ github.event.pull_request.number }}

.github/workflows/master.yml

@@ -14,11 +14,11 @@ jobs:
   install:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@master
-      - name: Use Node.js 16.x
-        uses: actions/setup-node@v1
+      - uses: actions/checkout@v4
+      - name: Use Node.js 18.x
+        uses: actions/setup-node@v4
         with:
-          node-version: 16.x
+          node-version: 18.x
 
       - name: npm ci
         run:  npm ci

.github/workflows/pr.yml

@@ -10,11 +10,11 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@master
-      - name: Use Node.js 16.x
-        uses: actions/setup-node@v1
+      - uses: actions/checkout@v4
+      - name: Use Node.js 18.x
+        uses: actions/setup-node@v4
         with:
-          node-version: 16.x
+          node-version: 18.x
       - name: npm ci
         run:  npm ci
       - name: npm run build

.nvmrc

@@ -1 +1 @@
-v16.13.0
+v18

package.json

@@ -6,6 +6,7 @@
   "license": "Apache-2.0",
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "build:watch": "tsc -p tsconfig.json --watch",
     "test": "mocha",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",

report/schemas.api.md

@@ -72,6 +72,22 @@ export enum AccountSortBy {
 // @public (undocumented)
 type Actions = typeof SCENE_UPDATE | typeof UPDATE;
 
+// Warning: (ae-missing-release-tag) "AddMappingError" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public (undocumented)
+export class AddMappingError extends Error {
+    // Warning: (ae-incompatible-release-tags) The symbol "__constructor" is marked as @public, but its signature references "Mapping" which is marked as @alpha
+    constructor(message: string, existingMapping: Mapping, conflictingMapping: Mapping);
+    // Warning: (ae-incompatible-release-tags) The symbol "conflictingMapping" is marked as @public, but its signature references "Mapping" which is marked as @alpha
+    //
+    // (undocumented)
+    conflictingMapping: Mapping;
+    // Warning: (ae-incompatible-release-tags) The symbol "existingMapping" is marked as @public, but its signature references "Mapping" which is marked as @alpha
+    //
+    // (undocumented)
+    existingMapping: Mapping;
+}
+
 export { Ajv }
 
 // Warning: (ae-missing-release-tag) "AnalyticsDayData" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -643,6 +659,9 @@ export namespace Contract {
     validate: ValidateFunction<Contract>;
 }
 
+// @alpha
+export type ContractAddress = string;
+
 // Warning: (ae-missing-release-tag) "ContractFilters" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -651,6 +670,18 @@ export type ContractFilters = {
     network?: Network;
 };
 
+// @alpha
+export enum ContractNetwork {
+    // (undocumented)
+    AMOY = "amoy",
+    // (undocumented)
+    MAINNET = "mainnet",
+    // (undocumented)
+    MATIC = "matic",
+    // (undocumented)
+    SEPOLIA = "sepolia"
+}
+
 // Warning: (ae-missing-release-tag) "ContractSortBy" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -659,6 +690,12 @@ export enum ContractSortBy {
     NAME = "name"
 }
 
+// Warning: (ae-incompatible-release-tags) The symbol "createMappingsHelper" is marked as @public, but its signature references "Mappings" which is marked as @alpha
+// Warning: (ae-missing-release-tag) "createMappingsHelper" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public (undocumented)
+export function createMappingsHelper(initial?: Mappings): MappingsHelper;
+
 // Warning: (tsdoc-missing-deprecation-message) The @deprecated block must include a deprecation message, e.g. describing the recommended alternative
 //
 // @public @deprecated
@@ -1381,6 +1418,34 @@ export namespace Mapping {
     validate: ValidateFunction<Mapping>;
 }
 
+// @alpha
+export type Mappings = Partial<Record<ContractNetwork, Record<ContractAddress, Mapping[]>>>;
+
+// @alpha
+export namespace Mappings {
+    const // (undocumented)
+    _isMappingsValid: {
+        keyword: string;
+        validate: (schema: boolean, data: any) => boolean;
+        errors: boolean;
+    };
+    const // (undocumented)
+    innerSchema: JSONSchema<Record<ContractAddress, Mapping[]>>;
+    const // (undocumented)
+    schema: JSONSchema<Mappings>;
+    const // (undocumented)
+    validate: ValidateFunction<Mappings>;
+}
+
+// Warning: (ae-missing-release-tag) "MappingsHelper" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public (undocumented)
+export type MappingsHelper = {
+    getMappings(): Mappings;
+    addMapping(network: ContractNetwork, contractAddress: ContractAddress, mapping: Mapping): void;
+    includesNft(network: ContractNetwork, contractAddress: ContractAddress, tokenId: string): boolean;
+};
+
 // @alpha
 export enum MappingType {
     // (undocumented)
@@ -2925,7 +2990,7 @@ export type SyncDeployment = SnapshotSyncDeployment | PointerChangesSyncDeployme
 export type ThirdPartyProps = {
     merkleProof: MerkleProof;
     content: Record<string, string>;
-    mappings?: Mapping[];
+    mappings?: Mappings;
 };
 
 // Warning: (ae-missing-release-tag) "Trade" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -3322,8 +3387,14 @@ export namespace WorldConfiguration {
 // src/platform/events/blockchain.ts:21:3 - (ae-forgotten-export) The symbol "BidMetadata" needs to be exported by the entry point index.d.ts
 // src/platform/events/blockchain.ts:163:3 - (ae-forgotten-export) The symbol "RentalMetadata" needs to be exported by the entry point index.d.ts
 // src/platform/item/emote/adr74/emote-data-adr74.ts:7:3 - (ae-incompatible-release-tags) The symbol "representations" is marked as @public, but its signature references "EmoteRepresentationADR74" which is marked as @alpha
+// src/platform/item/linked-wearable-mappings.ts:253:3 - (ae-incompatible-release-tags) The symbol "getMappings" is marked as @public, but its signature references "Mappings" which is marked as @alpha
+// src/platform/item/linked-wearable-mappings.ts:254:3 - (ae-incompatible-release-tags) The symbol "addMapping" is marked as @public, but its signature references "ContractNetwork" which is marked as @alpha
+// src/platform/item/linked-wearable-mappings.ts:254:3 - (ae-incompatible-release-tags) The symbol "addMapping" is marked as @public, but its signature references "ContractAddress" which is marked as @alpha
+// src/platform/item/linked-wearable-mappings.ts:254:3 - (ae-incompatible-release-tags) The symbol "addMapping" is marked as @public, but its signature references "Mapping" which is marked as @alpha
+// src/platform/item/linked-wearable-mappings.ts:255:3 - (ae-incompatible-release-tags) The symbol "includesNft" is marked as @public, but its signature references "ContractNetwork" which is marked as @alpha
+// src/platform/item/linked-wearable-mappings.ts:255:3 - (ae-incompatible-release-tags) The symbol "includesNft" is marked as @public, but its signature references "ContractAddress" which is marked as @alpha
 // src/platform/item/third-party-props.ts:7:3 - (ae-incompatible-release-tags) The symbol "merkleProof" is marked as @public, but its signature references "MerkleProof" which is marked as @alpha
-// src/platform/item/third-party-props.ts:9:3 - (ae-incompatible-release-tags) The symbol "mappings" is marked as @public, but its signature references "Mapping" which is marked as @alpha
+// src/platform/item/third-party-props.ts:9:3 - (ae-incompatible-release-tags) The symbol "mappings" is marked as @public, but its signature references "Mappings" which is marked as @alpha
 // src/platform/scene/feature-toggles.ts:11:3 - (ae-forgotten-export) The symbol "EnabledDisabled" needs to be exported by the entry point index.d.ts
 // src/platform/scene/feature-toggles.ts:12:3 - (ae-forgotten-export) The symbol "PortableExperiencesToggles" needs to be exported by the entry point index.d.ts
 // src/platform/scene/spawn-point.ts:6:3 - (ae-forgotten-export) The symbol "SinglePosition" needs to be exported by the entry point index.d.ts

src/platform/item/emote/emote.ts

@@ -1,8 +1,8 @@
-import { isThirdParty, RangeMapping } from '..'
+import { isThirdParty, Mappings, RangeMapping } from '..'
 import { generateLazyValidator, JSONSchema } from '../../../validation'
 import { BaseItem, baseItemProperties, isBaseEmote, requiredBaseItemProps } from '../base-item'
 import { standardProperties, StandardProps } from '../standard-props'
-import { thirdPartyProps, ThirdPartyProps } from '../third-party-props'
+import { schema as thirdPartyPropsSchema, ThirdPartyProps } from '../third-party-props'
 import { EmoteDataADR74 } from './adr74/emote-data-adr74'
 
 export type EmoteADR74 = BaseItem & (StandardProps | ThirdPartyProps) & { emoteDataADR74: EmoteDataADR74 }
@@ -17,7 +17,7 @@ export namespace Emote {
     properties: {
       ...baseItemProperties,
       ...standardProperties,
-      ...thirdPartyProps,
+      ...thirdPartyPropsSchema.properties,
       emoteDataADR74: EmoteDataADR74.schema
     },
     additionalProperties: true,
@@ -80,6 +80,7 @@ export namespace Emote {
   export const validate = generateLazyValidator(schema, [
     _isThirdPartyKeywordDef,
     _isBaseEmoteKeywordDef,
-    RangeMapping._fromLessThanOrEqualTo
+    RangeMapping._fromLessThanOrEqualTo,
+    Mappings._isMappingsValid
   ])
 }

src/platform/item/index.ts

@@ -4,6 +4,6 @@ export { Metrics } from './metrics'
 export { BodyShape } from './body-shape'
 export { StandardProps, isStandard } from './standard-props'
 export { ThirdPartyProps, isThirdParty } from './third-party-props'
-export * from './linked-wearable-props'
+export * from './linked-wearable-mappings'
 export * from './wearable'
 export * from './emote'