@qumra/app-sdk

Core SDK for building apps on the Qumra e-commerce platform.

The @qumra/app-sdk provides essential utilities for authentication, session management, security verification, and validation when building applications on the Qumra platform. It's designed to work seamlessly with Qumra's API infrastructure and security model.

Installation

npm install @qumra/app-sdk

Optional Dependencies

If you plan to use PrismaSessionStorage, install Prisma:

npm install @prisma/client

Quick Start

Session Management

Store and retrieve user sessions with built-in Prisma support:

import { PrismaSessionStorage } from '@qumra/app-sdk';
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();
const sessionStorage = new PrismaSessionStorage(prisma);

// Store a session
await sessionStorage.setSession('session-id', {
  userId: 'user-123',
  isOnline: true,
  expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
});

// Retrieve a session
const session = await sessionStorage.getSession('session-id');

Security Verification

Verify HMAC signatures from Qumra API requests:

import { verifyRequestHmac } from '@qumra/app-sdk';

const isValid = verifyRequestHmac(
  body,
  hmacHeader,
  process.env.QUMRA_API_SECRET
);

if (!isValid) {
  throw new Error('Invalid request signature');
}

Session Management

SessionStorage Interface

Implement custom session storage by conforming to the SessionStorage interface:

export interface Session {
  userId: string;
  isOnline: boolean;
  expiresAt: Date;
  [key: string]: any; // Additional custom fields
}

export interface SessionStorage {
  getSession(sessionId: string): Promise<Session | null>;
  setSession(sessionId: string, session: Session): Promise<void>;
  deleteSession(sessionId: string): Promise<void>;
}

PrismaSessionStorage

Use the built-in Prisma-based session storage implementation:

import { PrismaSessionStorage, isSessionActive } from '@qumra/app-sdk';
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();
const storage = new PrismaSessionStorage(prisma);

const session = await storage.getSession(sessionId);
if (session && isSessionActive(session)) {
  // Session is valid and not expired
  console.log(`User ${session.userId} is authenticated`);
}

Custom Session Storage

Implement custom storage by extending the SessionStorage interface:

import { SessionStorage, Session } from '@qumra/app-sdk';

class RedisSessionStorage implements SessionStorage {
  constructor(private redis: RedisClient) {}

  async getSession(sessionId: string): Promise<Session | null> {
    const data = await this.redis.get(`session:${sessionId}`);
    return data ? JSON.parse(data) : null;
  }

  async setSession(sessionId: string, session: Session): Promise<void> {
    await this.redis.set(
      `session:${sessionId}`,
      JSON.stringify(session),
      'EX',
      Math.floor((session.expiresAt.getTime() - Date.now()) / 1000)
    );
  }

  async deleteSession(sessionId: string): Promise<void> {
    await this.redis.del(`session:${sessionId}`);
  }
}

Session ID Helpers

Get online and offline session IDs:

import { getOnlineSessionId, getOfflineSessionId } from '@qumra/app-sdk';

const onlineId = getOnlineSessionId(userId);
const offlineId = getOfflineSessionId(userId);

Security Utilities

Request HMAC Verification

Verify that requests from Qumra contain valid HMAC signatures:

import { verifyRequestHmac } from '@qumra/app-sdk';

app.post('/api/webhook', (req, res) => {
  const hmacHeader = req.headers['x-qumra-hmac'];
  const isValid = verifyRequestHmac(
    JSON.stringify(req.body),
    hmacHeader,
    process.env.QUMRA_API_SECRET
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // Process the webhook
  res.json({ success: true });
});

Action HMAC Verification

Verify HMAC signatures for action requests:

import { verifyActionHmac } from '@qumra/app-sdk';

const isValid = verifyActionHmac(
  actionData,
  actionHmac,
  process.env.QUMRA_API_SECRET
);

JWT Verification

Verify JWT tokens from Qumra authentication:

import { verifyJwt } from '@qumra/app-sdk';

try {
  const decoded = verifyJwt(token, process.env.QUMRA_JWT_SECRET);
  console.log('Token is valid:', decoded);
} catch (error) {
  console.error('Invalid token:', error);
}

Validation

Bot Detection

Validate requests to prevent bot abuse:

import { validateNotBot } from '@qumra/app-sdk';

const isHuman = await validateNotBot(req, {
  apiKey: process.env.CAPTCHA_API_KEY,
});

if (!isHuman) {
  return res.status(403).json({ error: 'Bot detected' });
}

Iframe Request Validation

Validate that requests originate from an iframe context:

import { validateIframeRequest } from '@qumra/app-sdk';

const isValidIframe = validateIframeRequest(req, {
  allowedOrigins: ['https://qumra.com'],
});

if (!isValidIframe) {
  return res.status(403).json({ error: 'Invalid iframe origin' });
}

Error Handling

The SDK provides a hierarchy of error types for precise error handling:

import {
  QumraError,
  QumraAuthError,
  QumraFetchError,
  QumraValidationError,
} from '@qumra/app-sdk';

try {
  // SDK operation
  await fetchQuery(query);
} catch (error) {
  if (error instanceof QumraAuthError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof QumraValidationError) {
    console.error('Validation failed:', error.message);
  } else if (error instanceof QumraFetchError) {
    console.error('Network request failed:', error.message);
  } else if (error instanceof QumraError) {
    console.error('SDK error:', error.message);
  }
}

Error Hierarchy

• QumraError - Base error class
  • QumraAuthError - Authentication and authorization failures
  • QumraValidationError - Validation failures
  • QumraFetchError - Network request failures

API Constants

Core API endpoints and configuration:

import {
  AUTH_URL,        // Qumra authentication endpoint
  GRAPHQL_URL,     // Qumra GraphQL endpoint
  DEFAULT_TIMEOUT_MS, // Default request timeout (30000ms)
} from '@qumra/app-sdk';

Use these constants to configure your API clients:

import { createAdminGraphQL, AUTH_URL } from '@qumra/app-sdk';

// Create an authenticated GraphQL client
const client = createAdminGraphQL({
  apiKey: process.env.QUMRA_ADMIN_API_KEY,
  endpoint: GRAPHQL_URL,
});

Qumra Ecosystem

The @qumra/app-sdk is part of a comprehensive toolkit for building on Qumra:

| Package | Purpose | |---------|---------| | @qumra/app-sdk | Core SDK with session, security, and validation utilities | | @qumra/app-react-router | React Router 7 integration for Qumra apps | | @qumra/app-session-storage-prisma | Prisma session storage adapter | | @qumra/app-session-storage-mongodb | MongoDB session storage adapter | | @qumra/jisr | App Bridge for iframe ↔ Admin communication | | @qumra/manara | Design system and React component library | | @qumra/riwaq | UI Extensions SDK for React |

Requirements

• Node.js: >= 18.0.0
• @prisma/client: >= 5.0.0 (optional, only required for PrismaSessionStorage)

License

ISC

Documentation: https://docs.qumra.cloud

Support: https://docs.qumra.cloud/support