انتقل إلى المحتوى الرئيسي

Qumra SDK

The @qumra/app-sdk is the official SDK for building Qumra apps. It handles authentication, API requests, webhook verification, and session management.

Installation​

npm install @qumra/app-sdk

Initialization​

Create a server-side module to initialize the SDK. This file should be placed at app/qumra.server.ts:

app/qumra.server.ts
import { prisma } from "prisma/lib/prisma";
import QumraClient from "@qumra/app-sdk";

const Qumra = new QumraClient({
  apiKey: process.env.QUMRA_API_KEY as string,
  secretKey: process.env.QUMRA_API_SECRET as string,
  sessionStorage: prisma,
});

export default Qumra;
export const authenticate = Qumra.authenticate;
Server-only

This file must only be imported on the server side. The .server.ts suffix ensures React Router excludes it from the client bundle.

QumraClient​

The QumraClient class is the main entry point for the SDK. It accepts a configuration object with the following options:

const client = new QumraClient({
  apiKey: string,           // Your app's API key (client_id)
  secretKey: string,        // Your app's secret key (client_secret)
  sessionStorage: SessionStorage, // Prisma client instance
});

Properties​

PropertyTypeDescription
apiKeystringYour app's API key, also known as the client_id.
secretKeystringYour app's secret key, also known as client_secret.
sessionStorageSessionStorageA Prisma client instance used to persist sessions.
authenticateobjectObject containing authentication methods.

What the SDK Handles​

The SDK takes care of the most common tasks when building a Qumra app:

  • OAuth 2.0 authentication flows -- handles redirects, token exchange, and session creation automatically.
  • GraphQL client creation with access tokens -- provides a pre-authenticated admin.graphql() method.
  • Webhook HMAC signature verification -- validates incoming webhook requests to ensure they originate from Qumra.
  • Session persistence and management -- stores and retrieves sessions using your Prisma database.
  • Request validation (bot detection, iframe verification) -- protects your app from unauthorized access.
  • Error handling with typed exceptions -- provides structured error types for common failure scenarios.

Next Steps​