Session Management

Qumra apps use Prisma to persist OAuth sessions. The SDK requires a Session model in your database.

Database Schema

Add the following Session model to your Prisma schema:

prisma/schema.prisma

generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider = "sqlite"
}

model Session {
  id            String   @id @unique @default(cuid())
  store         String   @unique
  isOnline      Boolean  @default(false)
  accessToken   String
  userId        String?
  firstName     String?
  lastName      String?
  email         String?
  emailVerified Boolean? @default(false)
  refreshToken  String?
  createdAt     DateTime @default(now())
  lastSeenAt    DateTime @default(now())
}

Session Fields

Field	Type	Required	Description
id	String	Auto	Auto-generated unique identifier (CUID).
store	String	Yes	Unique store domain. One session per store.
isOnline	Boolean	No	Whether this is an online (interactive) session.
accessToken	String	Yes	The OAuth access token for API requests.
userId	String?	No	The ID of the authenticated user.
firstName	String?	No	First name of the authenticated user.
lastName	String?	No	Last name of the authenticated user.
email	String?	No	Email address of the authenticated user.
emailVerified	Boolean?	No	Whether the user's email has been verified.
refreshToken	String?	No	OAuth refresh token for obtaining new access tokens.
createdAt	DateTime	Auto	Timestamp when the session was created.
lastSeenAt	DateTime	Auto	Timestamp of the last authenticated request.

Prisma Setup

1. Prisma Configuration

Create a prisma.config.ts file in your project root:

prisma.config.ts

import path from "node:path";
import type { PrismaConfig } from "prisma";

export default {
  earlyAccess: true,
  schema: path.join("prisma", "schema.prisma"),
} satisfies PrismaConfig;

2. Prisma Client

Create the Prisma client module with the BetterSqlite3 adapter:

prisma/lib/prisma.ts

import { PrismaClient } from "../../generated/prisma";
import { PrismaBetterSqlite3 } from "@prisma/adapter-better-sqlite3";

const adapter = new PrismaBetterSqlite3({
  url: process.env.DATABASE_URL ?? "file:./dev.db",
});

export const prisma = new PrismaClient({ adapter });

3. Running Migrations

Generate the Prisma client and run migrations:

# Generate the Prisma client
npx prisma generate

# Create and apply migrations
npx prisma migrate dev --name init

# (Optional) Open Prisma Studio to inspect data
npx prisma studio

Session Storage Interface

The SDK expects a sessionStorage object that conforms to the following interface:

interface SessionStorage {
  session: {
    upsert(params: {
      where: { store: string };
      update: Partial<Session>;
      create: Session;
    }): Promise<Session>;

    findUnique(params: {
      where: { store: string };
    }): Promise<Session | null>;
  };
}

Prisma Compatibility

The standard Prisma client with the Session model automatically satisfies this interface. No additional adapters or wrappers are needed.

Database Provider for Production

Use SQLite for development and switch to PostgreSQL for production by changing the provider and DATABASE_URL:

prisma/schema.prisma (production)

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

.env

DATABASE_URL="postgresql://user:password@localhost:5432/myapp?schema=public"