Merge branch 'main' into DVR-342-example-app-content-parser

Author: darrenmelvison1

.github/CODEOWNERS

@@ -17,7 +17,7 @@ package.json @immutable/passport
 /packages/passport @immutable/passport
 /packages/x-provider @immutable/passport
 /packages/checkout @immutable/passport
-/packages/checkout/widgets-lib @immutable/passport
+/packages/checkout/widgets-lib @immutable/gamefi
 /packages/blockchain-data @immutable/activation
 /packages/minting-backend @shineli1984
 /packages/webhook @shineli1984

.github/scripts/check-docs-deployed.sh

@@ -8,10 +8,10 @@ then
   echo "VERSION is not set"
   exit 1
 fi
-
+MAJOR_VERSION=$(echo $VERSION | sed -E 's/^(prelease-)?([0-9]+)\..*/\2/')
 # this command will send a GET request to the docs site, the -s option silences the output,
 # the -o option redirects the output to /dev/null, and the -w option formats the output to only return the HTTP status code
-HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://docs.immutable.com/sdk-references/ts-immutable-sdk/$VERSION/)
+HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://docs.immutable.com/sdk-references/ts-immutable-sdk/v$MAJOR_VERSION/)
 
 if [ "$HTTP_STATUS" -ne 200 ]; then
   echo "SDK reference docs for v$VERSION are not deployed. Check Netlify for the build status. https://app.netlify.com/sites/imx-docs-prod/deploys"

.github/scripts/check-docs-version.sh

@@ -15,14 +15,11 @@ then
   exit 1
 fi
 
-# check a docs folder with the same version exists in $CLONE_DIR
-if [ -d "$CLONE_DIR/api-docs/sdk-references/ts-immutable-sdk/$VERSION" ]; then
-  echo "There is already a docs folder for v$VERSION. Please create a separate PR to update the SDK reference docs for v$VERSION."
-  exit 1
-fi
+# Extract major version only
+MAJOR_VERSION=$(echo $VERSION | cut -d. -f1)
 
-# check the version contains `alpha` string
-if echo "$VERSION" | grep -q "alpha"; then
-  echo "Skipping docs generation for alpha version"
-  exit 1
-fi
+echo "Checking if docs folder for v$VERSION / v$MAJOR_VERSION exists"
+
+# Remove any check for existing folders - we want to overwrite
+
+echo "Will generate docs for v$VERSION in the v$MAJOR_VERSION folder"

.github/scripts/push-docs.sh

@@ -15,12 +15,13 @@ then
   exit 1
 fi
 
-# Do not remove the trailing period!!!
-# https://dev.to/ackshaey/macos-vs-linux-the-cp-command-will-trip-you-up-2p00
+# Extract major version only - handle both regular and prelease tags
+MAJOR_VERSION=$(echo $VERSION | sed -E 's/^(prelease-)?([0-9]+)\..*/\2/')
+# Use v{MAJOR} format for the folder
 INPUT_SOURCE_FOLDER="./docs/."
 INPUT_DESTINATION_REPO="immutable/docs"
 INPUT_DESTINATION_HEAD_BRANCH="ts-immutable-sdk-docs-$VERSION"
-INPUT_DESTINATION_FOLDER="$CLONE_DIR/api-docs/sdk-references/ts-immutable-sdk/$VERSION"
+INPUT_DESTINATION_FOLDER="$CLONE_DIR/api-docs/sdk-references/ts-immutable-sdk/v$MAJOR_VERSION"
 
 if [ -z "$INPUT_PULL_REQUEST_REVIEWERS" ]
 then
@@ -30,6 +31,12 @@ else
 fi
 
 echo "Copying contents to git repo"
+# Clear existing vX folder if it exists
+if [ -d "$INPUT_DESTINATION_FOLDER" ]; then
+  echo "Cleaning existing v$MAJOR_VERSION folder..."
+  rm -rf "$INPUT_DESTINATION_FOLDER"/*
+fi
+
 mkdir -p $INPUT_DESTINATION_FOLDER
 
 if [ -d "$INPUT_DESTINATION_FOLDER" ]; then

.github/scripts/update-docs-link.sh

@@ -15,25 +15,27 @@ then
   exit 1
 fi
 
+# Extract major version for folder paths
+MAJOR_VERSION=$(echo $VERSION | cut -d. -f1)
+
 (
   cd $CLONE_DIR;
   FILE=src/components/UnifiedSDKLink/index.tsx
   if [ "$(uname)" == "Darwin" ]; then
       # On Mac OS, sed requires an empty string as an argument to -i to avoid creating a backup file
-      sed -i '' -E "s/SDK_VERSION = '.*'/SDK_VERSION = '$VERSION'/g;" $FILE
+      sed -i '' -E "s/SDK_VERSION = '.*'/SDK_VERSION = 'v$MAJOR_VERSION'/g;" $FILE
   else
-      sed -i -E "s/SDK_VERSION = '.*'/SDK_VERSION = '$VERSION'/g;" $FILE
+      sed -i -E "s/SDK_VERSION = '.*'/SDK_VERSION = 'v$MAJOR_VERSION'/g;" $FILE
   fi
 
   FILE2=sidebars/sidebars-docs.js
   if [ "$(uname)" == "Darwin" ]; then
       # On Mac OS, sed requires an empty string as an argument to -i to avoid creating a backup file
-      sed -i '' -E "s/SDK_VERSION = '.*'/SDK_VERSION = '$VERSION'/g;" $FILE2
+      sed -i '' -E "s/SDK_VERSION = '.*'/SDK_VERSION = 'v$MAJOR_VERSION'/g;" $FILE2
   else
-      sed -i -E "s/SDK_VERSION = '.*'/SDK_VERSION = '$VERSION'/g;" $FILE2
+      sed -i -E "s/SDK_VERSION = '.*'/SDK_VERSION = 'v$MAJOR_VERSION'/g;" $FILE2
   fi
 
-
   major=$(echo $VERSION | awk '{ 
     split($0, a, ".");
     print a[1];

.github/workflows/build-game-bridge.yaml

@@ -64,41 +64,32 @@ jobs:
       - name: Set TS SDK hash
         run: echo "TS_SDK_HASH=$(git rev-parse HEAD)" >> $GITHUB_ENV
 
-      - name: Build Game Bridge
-        run: pnpm nx run @imtbl/game-bridge:build --skip-nx-cache
-
-      - name: Update Version Strings
-        run: cd packages/game-bridge && ./scripts/updateSdkVersion.sh
-
-      - name: Check Unity Version String Updated
-        if: ${{ github.event.inputs.game_engine == 'Unity' || github.event.inputs.game_engine == 'Both' }}
+      - name: Update 'version' in 'sdk/package.json' from '0.0.0' to '${{ env.TS_SDK_TAG }}'
         run: |
-          UNITY_ARTIFACT_PATH="./packages/game-bridge/dist/unity/index.html"
-          if [ ! -f "$UNITY_ARTIFACT_PATH" ]; then
-            echo "Error: Unity artifact file not found at $UNITY_ARTIFACT_PATH"
-            exit 1
-          fi
-          UNITY_VERSION_STRING_COUNT=$(grep -c -o "ts-immutable-sdk-${{ env.TS_SDK_TAG }}" "$UNITY_ARTIFACT_PATH" || true)
-          if [ "$UNITY_VERSION_STRING_COUNT" -eq 0 ]; then
-            echo "Error: Updated version string not found in $UNITY_ARTIFACT_PATH"
-            exit 1
+          if [[ "$OSTYPE" == "darwin"* ]]; then
+            sed -i '' "s/\"version\": \"0.0.0\"/\"version\": \"${{ env.TS_SDK_TAG }}\"/g" sdk/package.json
+          else
+            sed -i "s/\"version\": \"0.0.0\"/\"version\": \"${{ env.TS_SDK_TAG }}\"/g" sdk/package.json
           fi
-          echo "Unity version string updated successfully"
 
-      - name: Check Unreal Version String Updated
-        if: ${{ github.event.inputs.game_engine == 'Unreal' || github.event.inputs.game_engine == 'Both' }}
+      - name: Update 'sdkVersionTag' in 'packages/game-bridge/src/index.ts' from '__SDK_VERSION__' to '${{ env.TS_SDK_TAG }}'
         run: |
-          UNREAL_ARTIFACT_PATH="./packages/game-bridge/dist/unreal/index.js"
-          if [ ! -f "$UNREAL_ARTIFACT_PATH" ]; then
-            echo "Error: Unreal artifact file not found at $UNREAL_ARTIFACT_PATH"
-            exit 1
+          if [[ "$OSTYPE" == "darwin"* ]]; then
+            sed -i '' "s/__SDK_VERSION__/${{ env.TS_SDK_TAG }}/g" packages/game-bridge/src/index.ts
+          else
+            sed -i "s/__SDK_VERSION__/${{ env.TS_SDK_TAG }}/g" packages/game-bridge/src/index.ts
           fi
-          UNREAL_VERSION_STRING_COUNT=$(grep -c -o "ts-immutable-sdk-${{ env.TS_SDK_TAG }}" "$UNREAL_ARTIFACT_PATH" || true)
-          if [ "$UNREAL_VERSION_STRING_COUNT" -eq 0 ]; then
-            echo "Error: Updated version string not found in $UNREAL_ARTIFACT_PATH"
-            exit 1
+
+      - name: Update 'sdkVersionSha' in 'packages/game-bridge/src/index.ts' from '__SDK_VERSION_SHA__' to '${{ env.TS_SDK_HASH }}'
+        run: |
+          if [[ "$OSTYPE" == "darwin"* ]]; then
+            sed -i '' "s/__SDK_VERSION_SHA__/${{ env.TS_SDK_HASH }}/g" packages/game-bridge/src/index.ts
+          else
+            sed -i "s/__SDK_VERSION_SHA__/${{ env.TS_SDK_HASH }}/g" packages/game-bridge/src/index.ts
           fi
-          echo "Unreal version string updated successfully"
+
+      - name: Build Game Bridge
+        run: pnpm nx run @imtbl/game-bridge:build --skip-nx-cache
 
       - name: Cache build artifacts
         uses: actions/cache@0c907a75c2c80ebcb7f088228285e798b750cf8f

.github/workflows/pr.yaml

@@ -80,13 +80,6 @@ jobs:
       - name: Setup playwright
         uses: ./.github/actions/setup-playwright
 
-      # Temporary disabled until we can release v2, since the tests are failing due to breaking changes
-      # - name: Prepare Checkout SDK bundle for @examples/commerce-widget-nextjs
-      #   run: pnpm --filter @imtbl/checkout-sdk prepare:examplesdk
-
-      # - name: Prepare widgets bundle for @examples/commerce-widget-nextjs
-      #   run: pnpm --filter @imtbl/checkout-widgets prepare:examplewidgets
-
       - name: Test examples
         run: pnpm test:examples
 
@@ -137,25 +130,9 @@ jobs:
 
       - name: Prepare tests
         run: pnpm prepare:tests
-
-      # Temporary disabled until we can release v2, since the tests are failing due to breaking changes
-      # - name: Install SDK at current version for @tests/checkout-widgets-nextjs
-      #   run: pnpm --filter @tests/checkout-widgets-nextjs add @imtbl/sdk@$(npm view @imtbl/sdk version)
-
-      # - name: Build @tests/checkout-widgets-nextjs
-      #   run: pnpm --filter @tests/checkout-widgets-nextjs build
-
-      # - name: Prepare Checkout SDK bundle for @tests/checkout-widgets-nextjs
-      #   run: pnpm --filter @imtbl/checkout-sdk prepare:testsdk
-
-      # - name: Prepare widgets bundle for @tests/checkout-widgets-nextjs
-      #   run: pnpm --filter @imtbl/checkout-widgets prepare:testwidgets
 
       - name: Update modules
         run: pnpm install --frozen-lockfile=false
 
-      - name: Setup playwright
-        uses: ./.github/actions/setup-playwright
-
       - name: Run functional tests
         run: pnpm --filter "@tests/*" --parallel func-test:ci

.github/workflows/publish.yaml

@@ -105,12 +105,6 @@ jobs:
 
       - name: Build SDK & Checkout Widgets
         run: pnpm build
-
-      - name: Generate version.json
-        if: (env.DRY_RUN) == 'false'
-        run: |
-          echo '{ "version": "$(jq -r '.version' ./sdk/package.json)" }' > ./sdk/version.json
-          cp ./sdk/version.json ./sdk/dist/
 
       - name: Pack SDK & Checkout Widgets packages and dependencies
         run: pnpm pack-npm-packages
@@ -128,8 +122,8 @@ jobs:
       - name: Tag Git Pre-Release
         if: ${{ startsWith(env.RELEASE_TYPE, 'pre') }}
         run: |
-          git tag -a $(jq -r '.version' ./sdk/package.json) -m "$(jq -r '.version' ./sdk/package.json)"
-          git push origin $(jq -r '.version' ./sdk/package.json)
+          git tag -a "prelease-$(jq -r '.version' ./sdk/package.json)" -m "$(jq -r '.version' ./sdk/package.json)"
+          git push origin "prelease-$(jq -r '.version' ./sdk/package.json)"
 
       - name: Release to NPM
         id: npm_release
@@ -177,7 +171,7 @@ jobs:
           echo "Waiting for NPM registry to reflect version: $VERSION"
 
           for i in {1..20}; do
-            LATEST_VERSION=$(if [[ "${{ startsWith(env.RELEASE_TYPE, 'pre') }}" == "true" ]]; then npm view @imtbl/sdk@alpha version; else npm view @imtbl/sdk@latest version; fi)
+            LATEST_VERSION=$(if [[ "${{ startsWith(env.RELEASE_TYPE, 'pre') }}" == "true" ]]; then npm view @imtbl/sdk@alpha version; else npm view @imtbl/checkout-widgets@latest version; fi)
             if [[ "$LATEST_VERSION" == "$VERSION" ]]; then
               echo "NPM registry updated to version: $LATEST_VERSION"
               exit 0
@@ -189,9 +183,9 @@ jobs:
           echo "NPM registry failed to update after 5 minutes."
           exit 1
 
-      - name: Purge CDN Cache for version.json
+      - name: Purge CDN Cache for Checkout Widgets
         id: purge_cdn
         if: ${{ !startsWith(env.RELEASE_TYPE, 'pre') }}  && env.DRY_RUN == 'false'
         run: |
-          curl -X GET https://purge.jsdelivr.net/npm/@imtbl/sdk@latest/dist/version.json
-          echo "CDN cache purged for https://cdn.jsdelivr.net/npm/@imtbl/sdk@latest/dist/version.json"
+          curl -X GET https://purge.jsdelivr.net/npm/@imtbl/checkout-widgets@latest
+          echo "CDN cache purged for https://cdn.jsdelivr.net/npm/@imtbl/checkout-widgets@latest"

.github/workflows/title-validation.yaml

@@ -7,9 +7,6 @@ on:
     types:
       - opened
       - edited
-  merge_group:
-    branches:
-      - main
 
 permissions:
   pull-requests: read
@@ -20,7 +17,6 @@ env:
 jobs:
   title-validation:
     name: Validate PR title
-    if: ${{ github.event.action == 'opened' || github.event.changes.title.from }}
     runs-on: ubuntu-latest
     steps:
       - uses: amannn/action-semantic-pull-request@40166f00814508ec3201fc8595b393d451c8cd80

CONTRIBUTING.md

@@ -12,6 +12,9 @@
 - [Creating Pull Requests](#creating-pull-requests)
   - [Title](#title)
   - [Description](#description)
+- [Publishing](#publishing)
+  - [v2](#v2)
+  - [v1 (legacy)](#v1-legacy)
 
 ## Setting Up Your Environment
 
@@ -148,4 +151,69 @@ When creating PR descriptions, start it with a section on one-line Customer Impa
 * `Deprecated` for soon-to-be removed features.
 * `Removed` for now removed features.
 * `Fixed` for any bug fixes.
-* `Security` in case of vulnerabilities.
+* `Security` in case of vulnerabilities.
+
+## Publishing
+
+### v2
+
+To publish a new version of the v2 SDK:
+
+1. **Ensure your changes are merged into the `main` branch**
+   - All v2 SDK changes must be merged into the main branch
+
+2. **Run the publish GitHub Action**
+   - Go to Actions tab in the repository
+   - Select the "Publish to NPM" workflow
+   - Click "Run workflow"
+   - Select the `main` branch
+   - Choose the appropriate release type:
+     - `prerelease`: Increments the prerelease version (e.g., 2.0.0-alpha.1 → 2.0.0-alpha.2)
+     - `prepatch`: Increments the patch version and adds prerelease suffix (e.g., 2.0.0 → 2.0.1-alpha.0)
+     - `preminor`: Increments the minor version and adds prerelease suffix (e.g., 2.0.0 → 2.1.0-alpha.0)
+     - `premajor`: Increments the major version and adds prerelease suffix (e.g., 2.0.0 → 3.0.0-alpha.0)
+     - `patch`: Increments the patch version (e.g., 2.0.0 → 2.0.1)
+     - `minor`: Increments the minor version (e.g., 2.0.0 → 2.1.0)
+     - `major`: Increments the major version (e.g., 2.0.0 → 3.0.0)
+       - Note: Major version releases can only be performed by administrators or authorized SDK team members
+   - Optionally check "Dry run" to simulate the publishing process without actually publishing
+   - Click "Run workflow"
+
+3. **Monitor the workflow execution**
+   - The workflow will build the SDK, generate version files, create a GitHub release (for non-prerelease versions), and publish to npm
+   - If successful, Slack notifications will be sent to the SDK team
+   - The CDN cache will be purged for non-prerelease versions to ensure the latest version is available
+
+Note: Prerelease versions are published with the `alpha` tag on npm, while regular releases are published with the `latest` tag.
+
+### v1 (legacy)
+
+The v1 SDK is maintained in the `legacy-v1` branch and uses a different publishing process.
+
+To publish a new version of the v1 SDK:
+
+1. **Ensure your changes are merged into the `legacy-v1` branch**
+   - All v1 SDK changes must be merged into the legacy-v1 branch
+
+2. **Run the publish GitHub Action**
+   - Go to Actions tab in the repository
+   - Select the "Publish to NPM" workflow
+   - Click "Run workflow"
+   - Select the `legacy-v1` branch
+   - Choose the appropriate release type:
+     - `alpha`: Publishes a prerelease version with the "alpha-legacy" tag
+     - `release`: Publishes a stable release with the "legacy" tag
+   - Choose the appropriate upgrade type:
+     - `none`: Only increments the revision for alpha releases, no change for stable releases
+     - `patch`: Increments the patch version (e.g., 1.0.0 → 1.0.1)
+     - `minor`: Increments the minor version (e.g., 1.0.0 → 1.1.0)
+   - Optionally check "Dry run" to simulate the publishing process without actually publishing
+   - Click "Run workflow"
+
+3. **Monitor the workflow execution**
+   - The workflow will validate the version (ensuring it starts with "1."), run tests, build the SDK, and publish to npm
+   - For stable releases, it will also create a GitHub release and purge the CDN cache
+   - If successful, Slack notifications will be sent to the SDK team
+
+Note: The v1 SDK publish workflow will only accept version numbers that start with "1." to ensure it publishes legacy versions. 
+