review fixes: examples, integration.yml, integration test typecheck (#201)

Deep-review pass over the QF-10 workstream (#196, #197, #199) caught
multiple issues. All P0+P1 findings are addressed here in one PR.

Workflow correctness:
- npm pack: clean tarball dir before each run + use --json output to get
  the exact filename instead of ls glob (avoids picking a stale .tgz).
- Logs ordering: capture docker logs BEFORE compose down (compose down
  destroys the containers, so the previous step ran AFTER teardown and
  always returned empty).
- Persist logs to disk + upload as actions/upload-artifact so failure
  triage doesn't require re-running.
- npm install --prefer-offline --no-audit --no-fund — bound the example
  smoke against npm registry flakes.
- timeout 30 → 60 for the basic example (fresh-runner cold-start budget).
- docker compose up -d --wait --wait-timeout 120 — let compose's own
  healthcheck do the polling.
- concurrency.group on workflow — back-to-back pushes won't spawn
  parallel docker stacks.
- Cron moved from Monday 06:00 UTC to Tuesday 06:00 UTC so failures land
  during EU/IN working hours.

Type-safety gates:
- New tsconfig.tests.json that extends tsconfig.json (so strict + types
  + esModuleInterop are inherited rather than re-specified inline). The
  PR-time integration-test typecheck step now uses this config — the
  earlier inline `tsc --noEmit ...` flags were missing --strict, so
  null/undefined/implicit-any drift could slip through.
- tsconfig.examples.json: defensive `outDir: ./.tsbuildinfo-examples` so
  if anyone removes `noEmit` later, output goes somewhere obvious
  instead of polluting `dist/`.

Examples (user-facing):
- Standardized all examples on `import { AxonFlow } from '@axonflow/sdk'`
  (proxy-mode and wcp-retry-idempotency previously used `'../../src'`
  which only worked when running inside the repo tree).
- examples/basic: removed the "Sandbox Mode" demonstration. The sandbox
  client hard-codes `https://staging-eu.getaxonflow.com` (decommissioned
  2026-04-09); the example would always fail at that step in any real
  user environment AND in the live-integration smoke. The
  AxonFlow.sandbox helper itself is unchanged in the SDK.
- examples/connectors: `tenant_id` now sourced from
  AXONFLOW_TENANT_ID || AXONFLOW_CLIENT_ID. Real installations have
  tenant_id and client_id as distinct values; the previous version
  reused clientId, masking that semantics.
- examples/README.md: corrected the env-var table (was claiming
  AXONFLOW_API_KEY / AXONFLOW_TENANT, but the examples actually read
  AXONFLOW_CLIENT_ID / AXONFLOW_CLIENT_SECRET); switched runner
  instructions from ts-node to tsx; added entries for the proxy-mode
  and wcp-retry-idempotency examples that were previously undocumented.

Tests:
- tests/integration.test.ts: replaced two `fail('...')` calls with
  `throw new Error('...')`. The bare `fail` global was removed in
  jest 27+; the bundled jest 29 throws ReferenceError at runtime
  rather than the descriptive message. PR-time tsc didn't catch it
  because it's a runtime global.
- test/integration.test.ts (the older copy) removed: it pointed at
  decommissioned staging-eu, used deprecated protect(), and had a
  copy-pasted "VPC private endpoint" test that was identical to the
  public one. tests/integration.test.ts is the canonical version.
- package.json `test:integration` script updated to drop the deleted
  file.

CHANGELOG: Fixed-section entries for the example changes (user-facing).
CI / workflow / typecheck plumbing intentionally not in CHANGELOG per
feedback_changelog_no_internal_entries.md.

Author: saurabhjain1592

.github/workflows/integration.yml

@@ -8,11 +8,17 @@ on:
   workflow_dispatch: {}
   # Weekly drift catch
   schedule:
-    - cron: '0 6 * * 1'  # Monday 06:00 UTC
+    - cron: '0 6 * * 2'  # Tuesday 06:00 UTC — failures land in EU/IN working hours
 
 permissions:
   contents: read
 
+# Avoid spawning parallel docker-compose stacks for back-to-back pushes;
+# also cancels stale PR runs when a new commit lands.
+concurrency:
+  group: integration-${{ github.ref }}
+  cancel-in-progress: true
+
 env:
   DO_NOT_TRACK: '1'
 
@@ -37,8 +43,9 @@ jobs:
       - name: Run contract tests
         run: npm run test:contract
 
-  # Example type-check on every PR and push. Catches API drift at PR time
-  # without needing a live stack. Mirrors Python SDK demo-scripts job.
+  # Example + integration-test type-check on every PR and push. Catches API
+  # drift at PR time without needing a live stack. Mirrors Python SDK
+  # demo-scripts job.
   example-typecheck:
     name: Example Type-Check
     runs-on: ubuntu-latest
@@ -62,14 +69,11 @@ jobs:
       # Integration test files live behind jest's testPathIgnorePatterns
       # (only run on push-to-main), so jest never type-checks them at PR
       # time. Drift in those files (e.g. method renames on AxonFlow) only
-      # surfaced after merge. Catch it on every PR.
+      # surfaced after merge. Catch it on every PR. The dedicated tsconfig
+      # inherits strict + esModuleInterop + types from tsconfig.json so
+      # the gate matches what ts-jest applies at runtime.
       - name: Type-check integration test files
-        run: |
-          npx tsc --noEmit \
-            --target es2020 --module commonjs --moduleResolution node \
-            --esModuleInterop --skipLibCheck \
-            --types node,jest \
-            tests/integration.test.ts test/integration.test.ts
+        run: npx tsc -p tsconfig.tests.json
 
   # Integration tests run against a live community stack via docker compose.
   # Runs on main merges, scheduled, and manual dispatch. Skipped on PRs to keep
@@ -103,8 +107,10 @@ jobs:
       - name: Start community stack
         run: |
           cd ../axonflow
-          docker compose up -d
+          docker compose up -d --wait --wait-timeout 120
 
+          # Belt-and-suspenders: also poll /health, since not every compose
+          # service has a healthcheck wired.
           echo "Waiting for agent to be healthy..."
           timeout 120 bash -c 'until curl -sf http://localhost:8080/health; do sleep 2; done'
           echo "Agent is healthy"
@@ -131,27 +137,47 @@ jobs:
           AXONFLOW_CLIENT_SECRET: demo-secret
         run: |
           set -e
+          # Clean tarball dir so a stale .tgz from a re-run can't shadow the
+          # fresh one. `npm pack --json` gives us the exact filename — don't
+          # rely on alphabetical glob.
+          rm -rf /tmp/sdk-tarball /tmp/example-runner
           mkdir -p /tmp/sdk-tarball /tmp/example-runner
-          npm pack --pack-destination /tmp/sdk-tarball
+          PACK_JSON=$(npm pack --pack-destination /tmp/sdk-tarball --json)
+          TARBALL_NAME=$(printf '%s' "$PACK_JSON" | node -e 'process.stdin.on("data",d=>{const o=JSON.parse(d);console.log(o[0].filename||o[0].name)})')
+          TARBALL="/tmp/sdk-tarball/$TARBALL_NAME"
+          test -f "$TARBALL" || { echo "Tarball not found at $TARBALL"; ls -la /tmp/sdk-tarball; exit 1; }
           cp examples/basic/index.ts /tmp/example-runner/
           cd /tmp/example-runner
-          TARBALL=$(ls /tmp/sdk-tarball/*.tgz | head -1)
           npm init -y >/dev/null
-          npm install "$TARBALL" tsx@4 typescript@5 @types/node@20
-          timeout 30 npx tsx index.ts
+          npm install --prefer-offline --no-audit --no-fund \
+            "$TARBALL" tsx@4 typescript@5 @types/node@20
+          timeout 60 npx tsx index.ts
 
-      - name: Stop community stack
-        if: always()
+      # Logs MUST be captured before `Stop community stack` runs — `compose
+      # down` destroys the containers and `compose logs` then returns
+      # nothing. `if: failure()` here, `if: always()` on teardown.
+      - name: Show docker logs on failure
+        if: failure()
         run: |
           if [ -d "../axonflow" ]; then
             cd ../axonflow
-            docker compose down --volumes --remove-orphans || true
+            docker compose logs --tail=200 || true
           fi
 
-      - name: Show docker logs on failure
+      - name: Upload docker logs on failure
         if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docker-compose-logs
+          path: ../axonflow/docker-compose-logs.txt
+          if-no-files-found: ignore
+
+      - name: Stop community stack
+        if: always()
         run: |
           if [ -d "../axonflow" ]; then
             cd ../axonflow
-            docker compose logs --tail=200 || true
+            # Persist logs to disk so the upload step can grab them even after teardown.
+            docker compose logs --tail=500 > docker-compose-logs.txt 2>/dev/null || true
+            docker compose down --volumes --remove-orphans || true
           fi

CHANGELOG.md

@@ -11,6 +11,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **`client.listProviders(options?)`** — list configured LLM providers and their per-provider health snapshot. Calls `GET /api/v1/llm-providers`. New `LLMProvider`, `LLMProviderHealth`, and `ListProvidersOptions` types in `@axonflow/sdk`. Supports `type` and `enabled` filters. Closes the parity gap with the Java SDK's `listLLMProviders()` and the Python SDK's `list_providers()`.
 
+### Fixed
+
+- **`examples/connectors/`** — `installConnector()` call now uses the correct snake-case `connector_id` field (was `connectorId`) and supplies the required `tenant_id` (now sourced from `AXONFLOW_TENANT_ID`, falling back to `AXONFLOW_CLIENT_ID`).
+- **`examples/planning/`** — `PlanStep` field reference fixed: `step.dependsOn` (was `step.dependencies`).
+- **`examples/proxy-mode/`** — replaced `client.executeQuery(...)` with `client.proxyLLMCall(...)` (the method was renamed in v6.0.0); removed the import of the `@internal` `ExecuteQueryOptions` type.
+- **`examples/basic/`, `examples/proxy-mode/`, `examples/README.md`** — replaced the decommissioned `https://staging-eu.getaxonflow.com` default endpoint with `http://localhost:8080` (the local docker-compose default). The staging-eu environment was torn down 2026-04-09.
+- **`examples/basic/`** — removed the "Sandbox Mode" demonstration that constructed `AxonFlow.sandbox(...)`. The sandbox client hard-codes the decommissioned staging-eu endpoint internally and the example would always fail at that step. The sandbox helper itself is unchanged in the SDK.
+- **`examples/README.md`** — corrected stale env-var docs: examples expect `AXONFLOW_CLIENT_ID` / `AXONFLOW_CLIENT_SECRET`, not `AXONFLOW_API_KEY` / `AXONFLOW_TENANT`. Updated runner instructions to use `tsx` (the examples no longer rely on `ts-node`).
+- **All examples** — standardized on `import { AxonFlow } from '@axonflow/sdk'` (was mixed; some examples imported from `'../../src'` which only worked when copy-pasted inside the repo tree).
+
 ## [6.1.0] - 2026-04-25 — Plugin Batch 1 explainability fields on MCP responses
 
 Minor release. Surfaces fields the AxonFlow agent has emitted since v7.1.0 (Plugin Batch 1) but the SDK didn't declare. Pure field-additions on existing methods — no new SDK methods, no breaking changes. Documented in OpenAPI via platform v7.4.3.

examples/README.md

@@ -11,13 +11,11 @@ npm install @axonflow/sdk
 Set environment variables:
 
 ```bash
-export AXONFLOW_API_KEY="AXON-PLUS-yourorg-20351025-signature"  # Your license key
-export AXONFLOW_TENANT="your-tenant-id"
+export AXONFLOW_CLIENT_ID="your-client-id"
+export AXONFLOW_CLIENT_SECRET="your-client-secret"
 export AXONFLOW_AGENT_URL="http://localhost:8080"  # Optional (default for local docker-compose)
 ```
 
-**Note**: `AXONFLOW_API_KEY` should be your AxonFlow license key in the format `AXON-{TIER}-{ORG}-{EXPIRY}-{SIGNATURE}`
-
 ## Examples
 
 ### 1. Basic Usage (`examples/basic/`)
@@ -26,23 +24,22 @@ Simple SDK initialization and protected AI calls.
 
 ```bash
 cd examples/basic
-npx ts-node index.ts
+npx tsx index.ts
 ```
 
 Demonstrates:
 - Client initialization
 - Protecting AI calls with governance
 - Handling blocked requests
 - PII detection
-- Sandbox mode
 
 ### 2. MCP Connectors (`examples/connectors/`)
 
 Working with the MCP connector marketplace.
 
 ```bash
 cd examples/connectors
-npx ts-node index.ts
+npx tsx index.ts
 ```
 
 Demonstrates:
@@ -56,7 +53,7 @@ Complex workflow orchestration with MAP.
 
 ```bash
 cd examples/planning
-npx ts-node index.ts
+npx tsx index.ts
 ```
 
 Demonstrates:
@@ -65,33 +62,46 @@ Demonstrates:
 - Checking plan status
 - Handling plan results
 
-## Running Examples
+### 4. Proxy Mode (`examples/proxy-mode/`)
 
-Each example can be run directly with ts-node:
+Routing requests through AxonFlow with `proxyLLMCall`.
 
 ```bash
-# Install ts-node if not already installed
-npm install -g ts-node typescript
+cd examples/proxy-mode
+npx tsx index.ts
+```
 
-# Run any example
-cd examples/basic
-ts-node index.ts
+### 5. WCP retry_context + idempotency_key (`examples/wcp-retry-idempotency/`)
+
+End-to-end exercise of the v7.3.0 WCP retry primitives. Requires an
+enterprise stack at `AXONFLOW_BASE_URL`.
+
+```bash
+cd examples/wcp-retry-idempotency
+npx tsx index.ts
 ```
 
-Or compile and run:
+## Running Examples
+
+Each example uses `tsx` to run TypeScript directly without a separate compile step:
 
 ```bash
-tsc index.ts
-node index.js
+# tsx is a zero-config TS runner; either install globally or use npx
+npm install -g tsx
+
+# Run any example
+cd examples/basic
+tsx index.ts
 ```
 
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `AXONFLOW_API_KEY` | Yes | Your AxonFlow license key (format: AXON-{TIER}-{ORG}-{EXPIRY}-{SIG}) |
-| `AXONFLOW_TENANT` | Yes | Your tenant identifier |
-| `AXONFLOW_AGENT_URL` | No | Custom endpoint (default: `http://localhost:8080` for local docker-compose) |
+| `AXONFLOW_CLIENT_ID` | Yes | Your client/tenant identifier |
+| `AXONFLOW_CLIENT_SECRET` | Yes | Your client secret |
+| `AXONFLOW_AGENT_URL` | No | Agent endpoint (default: `http://localhost:8080`) |
+| `AXONFLOW_TENANT_ID` | No | Tenant ID for connector ops; falls back to `AXONFLOW_CLIENT_ID` |
 | `AMADEUS_API_KEY` | No | For connector examples |
 | `AMADEUS_API_SECRET` | No | For connector examples |
 

examples/basic/index.ts

@@ -72,27 +72,6 @@ async function main() {
     console.log('✓ Request blocked (PII detected):', err.message);
   }
 
-  // Test with sandbox client
-  console.log('\n' + '='.repeat(60));
-  console.log('Example 3: Sandbox Mode');
-  console.log('='.repeat(60));
-
-  const sandboxClient = AxonFlow.sandbox('demo-key');
-
-  try {
-    const result = await sandboxClient.protect(async () => {
-      return {
-        response: 'This is a sandbox test response',
-        model: 'gpt-4-turbo',
-      };
-    });
-
-    console.log('✓ Sandbox query succeeded:', result);
-  } catch (error) {
-    const err = error as Error;
-    console.log('⚠ Sandbox query result:', err.message);
-  }
-
   console.log('\n✅ All examples completed');
 }
 

examples/connectors/index.ts

@@ -12,6 +12,9 @@ import { AxonFlow } from '@axonflow/sdk';
 async function main() {
   const clientId = process.env.AXONFLOW_CLIENT_ID || 'demo-client';
   const clientSecret = process.env.AXONFLOW_CLIENT_SECRET || 'demo-secret';
+  // Tenant id is independent of the auth principal in real installations,
+  // even when a single demo collapses them to the same value.
+  const tenantId = process.env.AXONFLOW_TENANT_ID || clientId;
 
   const client = new AxonFlow({ clientId, clientSecret, debug: true });
 
@@ -46,7 +49,7 @@ async function main() {
       await client.installConnector({
         connector_id: 'amadeus-travel',
         name: 'amadeus-prod',
-        tenant_id: clientId,
+        tenant_id: tenantId,
         options: { environment: 'production' },
         credentials: { api_key: amadeusKey, api_secret: amadeusSecret },
       });

examples/proxy-mode/index.ts

@@ -5,10 +5,10 @@
  * Proxy Mode routes all requests through AxonFlow, which handles policy checking
  * and optionally routes to LLM providers.
  *
- * Run: npx ts-node examples/proxy-mode/index.ts
+ * Run: npx tsx examples/proxy-mode/index.ts
  */
 
-import { AxonFlow, PolicyViolationError } from '../../src';
+import { AxonFlow, PolicyViolationError } from '@axonflow/sdk';
 
 async function main() {
   // Initialize client

examples/wcp-retry-idempotency/index.ts

@@ -7,14 +7,14 @@
  * Run:
  *   source /tmp/axonflow-e2e-env.sh
  *   export AXONFLOW_BASE_URL=http://localhost:8080
- *   npx ts-node index.ts
+ *   npx tsx index.ts
  */
 
 import {
   AxonFlow,
   IdempotencyKeyMismatchError,
   type StepGateRequest,
-} from '../../src';
+} from '@axonflow/sdk';
 
 function mustEnv(k: string): string {
   const v = process.env[k];

package.json

@@ -27,7 +27,7 @@
     "test": "jest",
     "test:coverage": "jest --coverage",
     "test:contract": "jest tests/contract.test.ts",
-    "test:integration": "jest tests/integration.test.ts test/integration.test.ts --testTimeout=30000 --testPathIgnorePatterns='/node_modules/'",
+    "test:integration": "jest tests/integration.test.ts --testTimeout=30000 --testPathIgnorePatterns='/node_modules/'",
     "test:e2e": "jest tests/e2e-staging.test.ts --testTimeout=60000 --runInBand --testPathIgnorePatterns='/node_modules/'",
     "test:all": "jest --testPathIgnorePatterns='/node_modules/' --testTimeout=60000",
     "lint": "eslint 'src/**/*.ts' 'test/**/*.ts' 'tests/**/*.ts'",