Stoa SDK

Usage-based billing SDK for AI applications. Wrap your AI provider calls to automatically meter usage and bill your users.

Installation

npm install @onstoa/sdk

Quick Start

import { Stoa, StoaChargeRequiredError } from "@onstoa/sdk";

// Reads STOA_API_KEY from environment
const stoa = new Stoa();

// Use your app's own user ID for billing calls
const client = stoa.openai("user_123");

try {
  const response = await client.chat.completions.create({
    model: "gpt-4",
    messages: [{ role: "user", content: "Hello!" }],
  });
} catch (error) {
  if (error instanceof StoaChargeRequiredError) {
    const payment = await stoa.createPayment({
      userId: "user_123",
      email: "ada@example.com",
      returnUrl: "https://app.example.com/billing/stoa-return",
    });
    redirectUserTo(payment.hostedUrl);
  } else {
    throw error;
  }
}

Typical flow:

call stoa.createPayment(...) when you want to start a hosted payment flow
keep using your own app userId in SDK billing calls
if a metered call raises StoaChargeRequiredError, call stoa.createPayment(...)

If you already have users who predate your Stoa integration, you can also add a one-time lazy fallback before their first billable AI request. The operation is idempotent.

Onboard Users

Stoa can stay invisible to the customer while still owning the canonical user and membership records.

Explicitly bootstrap a member

registerMember(...) is still available if you want to bootstrap a user eagerly during signup.

import { Stoa } from "@onstoa/sdk";

const stoa = new Stoa({
  apiKey: process.env.STOA_API_KEY,
  baseUrl: process.env.STOA_BASE_URL,
});

const result = await stoa.registerMember({
  registrationSecret: process.env.STOA_REGISTRATION_SECRET!,
  userId: user.id,
  email: user.email,
  name: user.name,
  avatarUrl: user.avatarUrl,
});

// Optional: store the membership ID for debugging or richer account UX.
await persistMembershipBinding({
  userId: user.id,
  membershipId: result.membershipId,
});

Stoa registers the user for billing in your app. Your app can continue billing that user with its own userId.

Start a hosted payment flow

If you want an explicit pay or add-funds action in your product:

const payment = await stoa.createPayment({
  userId: user.id,
  email: user.email,
  returnUrl: "https://app.example.com/billing/stoa-return",
});

Send the user to payment.hostedUrl. The response also carries the payment ID.

Recover from `StoaChargeRequiredError`

If a metered call fails because the user is not yet chargeable in Stoa, start a hosted payment flow explicitly with createPayment(...):

import { StoaChargeRequiredError } from "@onstoa/sdk";

const client = stoa.openai(user.id);

try {
  const response = await client.chat.completions.create({
    model: "gpt-4",
    messages: [{ role: "user", content: "Hello!" }],
  });
} catch (error) {
  if (error instanceof StoaChargeRequiredError) {
    const payment = await stoa.createPayment({
      userId: user.id,
      email: user.email,
      returnUrl: "https://app.example.com/billing/stoa-return",
    });

    redirectUserTo(payment.hostedUrl);
  } else {
    throw error;
  }
}

Supported Providers

OpenAI

const client = stoa.openai("user_123");

const response = await client.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Explain quantum computing" }],
});

const embeddings = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: "Hello world",
});

Anthropic

const client = stoa.anthropic("user_123");

const response = await client.messages.create({
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Write a haiku about TypeScript" }],
});

Environment Variables

Variable	Required	Default	Description
`STOA_API_KEY`	Yes	-	Your Stoa application API key
`STOA_BASE_URL`	No	`https://www.onstoa.com/api`	Stoa API base URL (for self-hosted or testing)
`STOA_REGISTRATION_SECRET`	No	-	Registration signing secret for onboarding users from your app

Example `.env`

# Required
STOA_API_KEY=stoa_app_xxx
STOA_REGISTRATION_SECRET=stoa_reg_xxx

# Optional - override API endpoint
STOA_BASE_URL=https://www.onstoa.com/api

Documentation

See docs.onstoa.com for full documentation.

@onstoa/sdk

Package Exports

Readme