Core SDK

npm install @usequota/core

import { QuotaClient } from "@usequota/core";

const quota = new QuotaClient({
  apiKey: process.env.QUOTA_API_KEY!,
});

const quota = new QuotaClient({
  accessToken: session.accessToken,
  refreshToken: session.refreshToken,
  clientId: process.env.QUOTA_CLIENT_ID!,
  clientSecret: process.env.QUOTA_CLIENT_SECRET!,
  onTokenRefresh: async ({ accessToken, refreshToken, expiresIn }) => {
    await db.sessions.update(session.id, {
      accessToken,
      refreshToken,
      expiresAt: new Date(Date.now() + expiresIn * 1000),
    });
  },
});

const me = await quota.getMe();
// {
//   id: "u_abc123",
//   email: "ada@example.com",
//   balance: 1500000,                  // number | null — see note below
//   name: "Ada Lovelace",
//   picture: "https://...",
//   user_metadata: {}
// }

import { formatCredits } from "@usequota/core";

// Simple case: just want a number? Use the convenience field.
const { balance } = await quota.getBalance();
console.log(`Balance: ${formatCredits(balance)}`);

// Need to know which wallet you're looking at? Branch on the discriminator.
const b = await quota.getBalance();
if (b.wallet === "developer") {
  console.log(`Developer: ${formatCredits(b.developer_balance!)}`);
} else if (b.wallet === "oauth_user") {
  console.log(`User ${b.user_id}: ${formatCredits(b.balance)}`);
}

const packages = await quota.getPackages();
// [
//   {
//     id: "starter",
//     credits: 4050000,         // 4,050,000 credits = $4.05 of balance for $5.00 paid
//     price_cents: 500,
//     price_display: "$5.00"
//   },
//   ...
// ]

const { url, sessionId } = await quota.createCheckout({
  packageId: "starter",
  successUrl: "https://example.com/billing/done",
  cancelUrl: "https://example.com/billing",
});

// Redirect (or window.open) the user to url

const response = await quota.chat({
  model: "anthropic/claude-sonnet-4.6",
  messages: [{ role: "user", content: "Hello" }],
});

console.log(response.choices[0].message.content);
// The final response includes a `quota` block with credits used.

import { connectVoiceConversion } from "@usequota/core";

const session = await connectVoiceConversion({
  apiKey: process.env.QUOTA_API_KEY!,
  model: "elevenlabs/voice-conversion-v1",
  voice: "rachel",
  format: "pcm_16le_16k_mono",
  maxDurationSeconds: 600,
});

// Forward your own PCM source (file, microphone, RTC track):
session.send(pcmChunk); // Uint8Array

// Receive transformed audio frames:
session.onAudio((chunk) => audioOut.append(chunk));

// Typed close codes — the SDK maps numeric WebSocket codes to enum
// values so client logic doesn't depend on RFC 6455 numerics.
session.onClose((code, reason) => {
  if (code === "BALANCE_EXHAUSTED") {
    // You declared a 10-minute cap; the session ran out of credits
    // before max_duration. Don't auto-reconnect — top up first.
  } else if (code === "FORMAT_VIOLATION") {
    // Your input bytes/sec exceeded 1.5x the declared PCM rate.
  } else if (code === "HEARTBEAT_LOST") {
    // Network dropped; safe to reconnect.
  }
});

import { verifyWebhookSignature } from "@usequota/core";

export async function POST(request: Request) {
  const rawBody = await request.text();
  const signature = request.headers.get("x-quota-signature");

  // `await` is REQUIRED — without it, an unresolved Promise is truthy
  // and verification is silently bypassed.
  const isValid = await verifyWebhookSignature({
    payload: rawBody,
    signature: signature ?? "",
    secret: process.env.QUOTA_WEBHOOK_SECRET!,
  });

  if (!isValid) {
    return new Response("invalid signature", { status: 401 });
  }

  const event = JSON.parse(rawBody);
  // ...handle event.type
  return new Response("ok");
}

import {
  QuotaError,
  QuotaInsufficientCreditsError,
  QuotaNotConnectedError,
  QuotaTokenExpiredError,
  QuotaRateLimitError,
} from "@usequota/core";

try {
  await quota.chat({ model: "gpt-4o", messages });
} catch (e) {
  if (e instanceof QuotaInsufficientCreditsError) {
    // e.balance, e.required (in credits)
    showTopUpDialog({ short: e.required - e.balance });
  } else if (e instanceof QuotaNotConnectedError) {
    redirectToOAuth();
  } else if (e instanceof QuotaTokenExpiredError) {
    redirectToOAuth();
  } else if (e instanceof QuotaRateLimitError) {
    await new Promise((r) => setTimeout(r, e.retryAfter * 1000));
  } else if (e instanceof QuotaError) {
    console.error(`[${e.code}] ${e.message}`);
  }
}

import type { QuotaTokenStorage } from "@usequota/core";

const dbTokenStorage: QuotaTokenStorage = {
  async getTokens(request) {
    const userId = await getUserIdFromSession(request);
    const row = await db.quotaTokens.findUnique({ where: { userId } });
    if (!row) return null;
    return {
      accessToken: row.accessToken,
      refreshToken: row.refreshToken,
    };
  },

  async setTokens(tokens, request) {
    const userId = await getUserIdFromSession(request);
    await db.quotaTokens.upsert({
      where: { userId },
      update: { accessToken: tokens.accessToken, refreshToken: tokens.refreshToken },
      create: { userId, accessToken: tokens.accessToken, refreshToken: tokens.refreshToken },
    });
  },

  async deleteTokens(request) {
    const userId = await getUserIdFromSession(request);
    await db.quotaTokens.delete({ where: { userId } });
  },
};