JavaScript & TypeScript SDK

Install the official client to talk to the Playbasis API from Node.js, browsers, or serverless functions. The SDK wraps authentication, retries, and response typing so you can focus on the user journey.

Installation

pnpm add @playbasis/client

Or with npm:

npm install @playbasis/client

Creating the client

import { PlaybasisClient } from '@playbasis/client';

type Env = 'staging' | 'production';

const env: Env = process.env.NEXT_PUBLIC_PLAYBASIS_ENVIRONMENT === 'staging' ? 'staging' : 'production';

const client = new PlaybasisClient({
  baseUrl: env === 'staging' ? 'https://api.example.com/v1' : 'https://api.example.com/v1',
  apiKey: process.env.PLAYBASIS_API_KEY ?? '',
});

React Query hooks

import { createPlaybasisHooks } from '@playbasis/client/react';

const hooks = createPlaybasisHooks({ client });
const { useLeaderboard, useQuests, usePlayerBadges } = hooks;

export function LeaderboardPanel() {
  const leaderboard = useLeaderboard('points:points', { limit: 10 }).data;
  return (
    <ul>
      {(leaderboard?.entries ?? []).map((entry) => (
        <li key={entry.playerId}>{entry.displayName ?? entry.playerId}: {entry.score}</li>
      ))}
    </ul>
  );
}

Auth and retries

const client = new PlaybasisClient({
  baseUrl,
  apiKey,
  retry: {
    attempts: 3,
    initialDelayMs: 200,
  },
  onRequest: (request) => {
    console.info('Calling Playbasis', request.path);
  },
});

Webhook verification helper

Verify incoming webhook signatures with the bundled helper instead of hand-rolling HMAC logic.

import { verifyWebhookSignature } from '@playbasis/sdk-js/webhooks';

const isValid = verifyWebhookSignature({
  payload: rawBodyBuffer,
  secret: process.env.PLAYBASIS_WEBHOOK_SECRET ?? '',
  signatureHeader: request.headers['x-playbasis-signature'],
});

Need an end-to-end walkthrough? Check the Node webhook guide.

Sandbox helpers