TypeScript SDK
The official SDK for apps and integrations, with a typed API client, token handling, and webhook and extension verification
@checkcourt/sdk takes care of the repetitive parts of a CheckCourt integration.
Everything it does can also be built with plain HTTP; the rest of the developer
documentation describes the protocol. The SDK saves you the parts that are easy to get
wrong: token rotation, signatures, PKCE.
Client and authentication
Typed access to /api/v1 with an API key, installation token or member token
OAuth for member apps
PKCE, authorize URL, code exchange, refresh and revoke
Webhooks
Verify signatures and get typed events
UI extensions
Verify context tokens, build UI documents, connect iframes
Manifest
Write the manifest with autocompletion and compile-time checks
Errors and retries
Error classes, rate limits and what to do in each case
What's included
| Area | Purpose |
|---|---|
createCheckCourtClient | Typed client for every endpoint under /api/v1, generated from the API reference |
apiKeyAuth, installationAuth, userAuth | The three ways to authenticate, with token caching and safe refresh |
getInstallation, getMe | Your club installation with its settings, or who connected your member app |
createPkcePair, buildAuthorizeUrl, exchangeCode, … | OAuth 2.1 for member apps |
verifyWebhook | Verify the signature, get the event back as a type |
verifyExtensionContext, verifyExtensionRequest, ui | Declarative UI extensions |
@checkcourt/sdk/iframe | iframe extensions in the browser: height, toasts, navigation, theme |
sendNotification | Notify members through CheckCourt |
getObjectMetadata, putObjectMetadata, publishAppEvent, … | Connections between apps |
defineManifest | Fully typed manifest, including permissions and every extension point |
The SDK is written in TypeScript, ships its own type definitions and runs as an ES module
on Node.js 20 or later. It uses WebCrypto, so webhook and extension verification also work
on edge runtimes such as Cloudflare Workers, Vercel Edge or Deno. Its only dependency is
openapi-fetch.
Installation
The SDK is open source at CheckCourt/sdk.
Version 0.x
The API may still change before version 1.0. Read the changelog before you upgrade.
Install the package
npm install @checkcourt/sdkThe package ships its compiled build and type definitions. This documentation describes version 0.12.0; where a feature needs a newer version than you have, the page says so. The changes in each release are listed in the changelog.
Import it
import { createCheckCourtClient, installationAuth, verifyWebhook } from "@checkcourt/sdk";In the browser, for iframe extensions, import only the browser entry point:
import { connectExtensionFrame } from "@checkcourt/sdk/iframe";Entry points
| Import | Runs in | Contents |
|---|---|---|
@checkcourt/sdk | Server | Everything except the iframe part |
@checkcourt/sdk/oauth | Server | OAuth and installation tokens only |
@checkcourt/sdk/webhooks | Server, edge | Webhook verification and event types only |
@checkcourt/sdk/extensions | Server, edge | Context tokens, request verification, UI builder |
@checkcourt/sdk/manifest | Anywhere | defineManifest and constants |
@checkcourt/sdk/iframe | Browser | connectExtensionFrame and messages |
Client secrets, signing secrets and refresh tokens belong on your server only. The browser entry point needs none of them.