Fix Postman bumps and document the Trailers PHP SDK

.github/workflows/api-docs.yml

@@ -0,0 +1,35 @@
+name: API documentation contract
+
+on:
+  pull_request:
+    paths:
+      - 'vendor/postman'
+      - 'scripts/**'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - '.github/workflows/api-docs.yml'
+      - '.github/workflows/bump-postman.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - name: Verify complete PHP catalog before postinstall
+        run: node scripts/sync-php-sdk-examples.mjs
+      - run: pnpm install --frozen-lockfile
+      - run: node --test scripts/sdk-emitters.test.mjs scripts/sync-php-sdk-examples.test.mjs
+      - run: pnpm generate:api-docs

.github/workflows/bump-postman.yml

@@ -12,6 +12,13 @@ on:
   repository_dispatch:
     types: [postman-updated]
   workflow_dispatch:
+  schedule:
+    # Retry after an SDK contract update is merged, even without a Postman push.
+    - cron: '17 5 * * *'
+
+concurrency:
+  group: bump-postman
+  cancel-in-progress: false
 
 permissions:
   contents: write
@@ -45,48 +52,52 @@ jobs:
           echo "old_short=${old_sha:0:7}" >> "$GITHUB_OUTPUT"
           echo "new_short=${new_sha:0:7}" >> "$GITHUB_OUTPUT"
 
-          if [ "$old_sha" = "$new_sha" ]; then
-            echo "no_change=true" >> "$GITHUB_OUTPUT"
-            echo "✅ Submodule is already at latest main ($old_sha) — nothing to do."
-          else
-            echo "no_change=false" >> "$GITHUB_OUTPUT"
-            echo "🆕 Bumping submodule: $old_sha → $new_sha"
-          fi
-
-      - name: Stop early if nothing changed
-        if: steps.bump.outputs.no_change == 'true'
-        run: exit 0
+          echo "Postman: $old_sha → $new_sha; checking the PHP catalog as well."
 
       - name: Setup pnpm
-        if: steps.bump.outputs.no_change != 'true'
         uses: pnpm/action-setup@v3
         with:
           version: 10
 
       - name: Setup Node.js
-        if: steps.bump.outputs.no_change != 'true'
         uses: actions/setup-node@v4
         with:
           node-version: 20
           cache: pnpm
 
+      - name: Checkout the reviewed PHP SDK catalog
+        uses: actions/checkout@v4
+        with:
+          repository: fleetbase/fleetbase-php
+          ref: main
+          path: .php-sdk-source
+          persist-credentials: false
+          sparse-checkout: contracts
+
+      - name: Synchronize PHP examples before postinstall generates docs
+        id: sdk
+        run: |
+          echo "sha=$(git -C .php-sdk-source rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+          node scripts/sync-php-sdk-examples.mjs --source .php-sdk-source/contracts/php-sdk-examples.json
+
       - name: Install dependencies
-        if: steps.bump.outputs.no_change != 'true'
         run: pnpm install --frozen-lockfile
 
       - name: Regenerate API docs
-        if: steps.bump.outputs.no_change != 'true'
-        run: pnpm generate:api-docs
+        run: |
+          node --test scripts/sdk-emitters.test.mjs scripts/sync-php-sdk-examples.test.mjs
+          pnpm generate:api-docs
 
       - name: Create Pull Request
-        if: steps.bump.outputs.no_change != 'true'
         uses: peter-evans/create-pull-request@v6
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           commit-message: "chore: bump postman submodule (${{ steps.bump.outputs.old_short }} → ${{ steps.bump.outputs.new_short }})"
           title: "chore: bump postman submodule"
           body: |
-            Automated bump of the `vendor/postman` submodule.
+            Automated bump of the `vendor/postman` submodule and matching PHP SDK examples.
+
+            PHP SDK catalog source: `fleetbase/fleetbase-php@${{ steps.sdk.outputs.sha }}`.
 
             **Diff:** [`${{ steps.bump.outputs.old_short }}...${{ steps.bump.outputs.new_short }}`](https://github.com/fleetbase/postman/compare/${{ steps.bump.outputs.old_sha }}...${{ steps.bump.outputs.new_sha }})
 
@@ -99,6 +110,9 @@ jobs:
           branch: chore/bump-postman
           delete-branch: true
           base: main
+          add-paths: |
+            vendor/postman
+            scripts/php-sdk-examples.generated.json
           labels: |
             automated
             api-docs

.gitignore

@@ -2,6 +2,7 @@
 
 # dependencies
 /node_modules
+/.php-sdk-source/
 /.pnp
 .pnp.*
 .yarn/*
@@ -57,4 +58,3 @@ yarn-error.log*
 *.tsbuildinfo
 next-env.d.ts
 
-

package.json

@@ -9,8 +9,8 @@
     "prebuild": "node scripts/generate-api-docs.mjs",
     "start": "next start",
     "lint": "next lint",
-    "test": "node --experimental-strip-types --test \"src/**/*.test.ts\" && node --test scripts/sdk-emitters.test.mjs",
-    "test:sdk-emitters": "node --test scripts/sdk-emitters.test.mjs",
+    "test": "node --experimental-strip-types --test \"src/**/*.test.ts\" && node --test scripts/sdk-emitters.test.mjs scripts/sync-php-sdk-examples.test.mjs",
+    "test:sdk-emitters": "node --test scripts/sdk-emitters.test.mjs scripts/sync-php-sdk-examples.test.mjs",
     "postinstall": "fumadocs-mdx && node scripts/generate-api-docs.mjs",
     "content-agent:prepare": "node scripts/content-agent/prepare.mjs",
     "content-agent:generate-artifacts": "node scripts/content-agent/generate-artifacts.mjs",