Skip to main content

Quickstart

Test the SDK immediately with the built-in demo — no provider app needed.

Prerequisites​

  • Node.js >= 16.x
  • npm, yarn, or pnpm

Step 1: Install the SDK​

npm install @mission_sciences/provider-sdk

Step 2: Generate Test Keys​

npm run generate-keys

Step 3: Start the Test Server​

In a terminal, start the local development server:

npm run test-server

This starts a server at http://localhost:3000 that serves:

  • The example app
  • JWKS endpoint (for JWT validation)
  • All SDK files

Step 4: Generate a JWT​

Open a new terminal and generate a 5-minute session JWT:

npm run generate-jwt 5

Copy the token from the output.

Step 5: Open in Browser​

http://localhost:3000/example?gwSession=<PASTE_JWT_HERE>

You should see:

  • Countdown timer
  • Session details
  • Pause/Resume buttons
  • End Session button
  • A floating session-controls widget at bottom-right (auto-mounted by the SDK). Opt out with sessionControls: { autoMount: false } if your app renders its own UI.

What to Try​

Watch the Countdown​

The timer updates every second showing time remaining.

Test Pause/Resume​

Click pause, wait a few seconds, then resume. The timer continues from where it paused.

Trigger the Warning​

Generate a short JWT (1 minute) to see the warning modal:

npm run generate-jwt 1

After approximately 30 seconds remaining, a warning modal appears.

Test Expiration​

Wait for the timer to reach zero. The session automatically ends.

Check the Console​

Open browser DevTools (F12) and check the Console tab. You will see:

  • [MarketplaceSDK] Session initialized successfully
  • [TimerManager] Starting timer with X seconds remaining
  • Timer updates every second

Testing Different Scenarios​

Short Session (1 minute)​

npm run generate-jwt 1

Test the warning modal and expiration flow.

Normal Session (60 minutes)​

npm run generate-jwt 60

Standard session duration for testing.

Long Session (24 hours)​

npm run generate-jwt 1440

Maximum allowed duration.

Inspect the JWT​

Copy your JWT and paste it at jwt.io to see the decoded claims:

{
  "sessionId": "sess_xyz",
  "applicationId": "app_test_123",
  "userId": "user_test_456",
  "orgId": "org_test_789",
  "startTime": 1730000000,
  "durationMinutes": 60,
  "exp": 1730003600,
  "iat": 1730000000,
  "iss": "generalwisdom.com",
  "sub": "user_test_456"
}

Troubleshooting​

"Public key not found"​

npm run generate-keys

"SDK not built"​

npm run build

CORS Errors​

Make sure you are using npm run test-server which handles CORS properly. Do not open the HTML file directly (file://) — it will not work with ES modules.

JWT Expired Immediately​

The test JWT generator uses the current time. Make sure your system clock is correct.

Cannot See Console Logs​

Enable debug mode in the SDK config:

const sdk = new MarketplaceSDK({
  // ...
  debug: true,
});

Next Steps​

Once you have verified the SDK works:

  1. Try the React Example — See examples/react/ for React integration. Copy useMarketplaceSession.ts to your app.
  2. Integrate with Your App — Follow the SDK Integration Guide for full integration instructions. Customize the warning modal styling and add your own event handlers.
  3. Connect to the Platform — Update jwksUri to the production JWKS endpoint and use real JWTs from the platform backend.