ci: pin docs validation to exact published SDK version

.github/workflows/sdk-version-check.yml

@@ -0,0 +1,47 @@
+name: SDK Version Check
+
+on:
+  pull_request:
+    paths:
+      - 'package.json'
+
+jobs:
+  check-sdk-version:
+    name: Verify SDK version exists on npm
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Extract SDK version from package.json
+        id: extract-version
+        run: |
+          VERSION=$(node -p "require('./package.json').dependencies['@wraith-protocol/sdk']")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Detected SDK version: $VERSION"
+
+      - name: Check if version exists on npm
+        id: check
+        run: |
+          VERSION="${{ steps.extract-version.outputs.version }}"
+          echo "Checking if @wraith-protocol/sdk@$VERSION exists on npm..."
+
+          if npm view @wraith-protocol/sdk@$VERSION version > /dev/null 2>&1; then
+            echo "✅ Version $VERSION exists on npm"
+            echo "version=$VERSION" >> $GITHUB_OUTPUT
+          else
+            echo "❌ Version $VERSION does not exist on npm"
+            echo "Please ensure the SDK version is published before updating docs"
+            echo "Run: npm view @wraith-protocol/sdk versions"
+            exit 1
+          fi
+
+      - name: Output verified version
+        run: |
+          echo "Verified SDK version: ${{ steps.check.outputs.version }}"
+          echo "This version will be used for all docs validation checks"

.github/workflows/snippets.yml

@@ -8,9 +8,31 @@ on:
       - main
 
 jobs:
+  extract-sdk-version:
+    name: Extract SDK version
+    runs-on: ubuntu-latest
+    outputs:
+      sdk-version: ${{ steps.version.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Extract SDK version from package.json
+        id: version
+        run: |
+          VERSION=$(node -p "require('./package.json').dependencies['@wraith-protocol/sdk']")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Detected SDK version: $VERSION"
+
   check-snippets:
     name: Compile docs snippets
     runs-on: ubuntu-latest
+    needs: extract-sdk-version
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -26,8 +48,21 @@ jobs:
           node-version: 22
           cache: pnpm
 
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+      - name: Download published SDK artifact
+        run: |
+          echo "Downloading @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}"
+          cd /tmp
+          npm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}
+
+      - name: Install dependencies with pinned SDK
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm remove @wraith-protocol/sdk
+          pnpm add /tmp/wraith-protocol-sdk-${{ needs.extract-sdk-version.outputs.sdk-version }}.tgz
+
+      - name: Record tested SDK version
+        run: |
+          echo "Testing against SDK version: ${{ needs.extract-sdk-version.outputs.sdk-version }}"
 
       - name: Check snippets
         run: pnpm run check:snippets
@@ -42,6 +77,7 @@ jobs:
     name: Stellar snippet testnet validation
     runs-on: ubuntu-latest
     continue-on-error: true
+    needs: extract-sdk-version
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -57,15 +93,29 @@ jobs:
           node-version: 22
           cache: pnpm
 
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+      - name: Download published SDK artifact
+        run: |
+          echo "Downloading @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}"
+          cd /tmp
+          npm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}
+
+      - name: Install dependencies with pinned SDK
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm remove @wraith-protocol/sdk
+          pnpm add /tmp/wraith-protocol-sdk-${{ needs.extract-sdk-version.outputs.sdk-version }}.tgz
+
+      - name: Record tested SDK version
+        run: |
+          echo "Testing against SDK version: ${{ needs.extract-sdk-version.outputs.sdk-version }}"
 
       - name: Validate Stellar testnet snippets
         run: pnpm run check:stellar-testnet
 
   playground-smoke:
     name: Playground smoke test
     runs-on: ubuntu-latest
+    needs: extract-sdk-version
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -81,8 +131,21 @@ jobs:
           node-version: 22
           cache: pnpm
 
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+      - name: Download published SDK artifact
+        run: |
+          echo "Downloading @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}"
+          cd /tmp
+          npm pack @wraith-protocol/sdk@${{ needs.extract-sdk-version.outputs.sdk-version }}
+
+      - name: Install dependencies with pinned SDK
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm remove @wraith-protocol/sdk
+          pnpm add /tmp/wraith-protocol-sdk-${{ needs.extract-sdk-version.outputs.sdk-version }}.tgz
+
+      - name: Record tested SDK version
+        run: |
+          echo "Testing against SDK version: ${{ needs.extract-sdk-version.outputs.sdk-version }}"
 
       - name: Verify playground fixtures are in sync
         run: pnpm run check:playground-fixtures

docs/SDK_VERSION_UPDATE.md

@@ -0,0 +1,37 @@
+# Updating SDK Version in Docs
+
+When updating the `@wraith-protocol/sdk` version in the docs repository, follow these steps:
+
+## Prerequisites
+
+1. Ensure the new SDK version is published to npm
+2. Verify the version exists: `npm view @wraith-protocol/sdk versions`
+
+## Update Process
+
+1. Update the version in `package.json`:
+   ```json
+   "dependencies": {
+     "@wraith-protocol/sdk": "X.Y.Z"
+   }
+   ```
+
+2. Commit the change (the SDK version check workflow will verify the version exists)
+
+3. Update the lockfile:
+   ```bash
+   pnpm install
+   ```
+
+4. Commit the updated lockfile
+
+## CI Behavior
+
+- The `sdk-version-check.yml` workflow runs on any PR that modifies `package.json`
+- It verifies the specified SDK version exists on npm before allowing the PR to proceed
+- The `snippets.yml` workflow extracts the version from `package.json` and:
+  - Downloads the exact published SDK artifact as a `.tgz` file using `npm pack`
+  - Installs the packed artifact instead of the registry version
+  - Records the tested version in CI output
+
+This ensures docs validation always runs against the exact published SDK version, not local or floating versions.

package.json

@@ -19,7 +19,7 @@
   "dependencies": {
     "@solana/web3.js": "^1.95.0",
     "@stellar/stellar-sdk": "^13.1.0",
-    "@wraith-protocol/sdk": "^1.4.5"
+    "@wraith-protocol/sdk": "1.4.5"
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",