@superjolt/sdk

Official SDK for Superjolt — agent-first cloud compute.

One typed surface for the deployed apps your agent builds on Superjolt: verify webhooks, fetch session context, generate billing & portal URLs, send email, call the LLM gateway. Credentials come from the environment Superjolt injects into your VM (SUPERJOLT_ENV_TOKEN, SUPERJOLT_WEBHOOK_SECRET) — no config code in your app.

npm install @superjolt/sdk

Quick start

Verify an incoming webhook

import { superjolt } from '@superjolt/sdk';

export async function POST(req: Request) {
  const event = await superjolt.verifyWebhook(req);
  // event.type, event.data — typed envelope, signature already checked
  if (event.type === 'subscription.created') {
    // ...
  }
  return new Response('ok');
}

Read the signed-in user inside a route

import { session } from '@superjolt/sdk';

export async function GET(req: Request) {
  const ctx = await session.get(req);
  // ctx.user.email, ctx.plan, ctx.role, ctx.features, ctx.seats
  if (!ctx) return new Response('signed out', { status: 401 });
  return Response.json({ user: ctx.user });
}

Generate a Stripe Checkout URL

import { billing } from '@superjolt/sdk';

const url = await billing.checkoutUrl({
  plan: 'pro',
  customerEmail: '[email protected]',
});

Full reference

See superjolt.com/docs/contract for the complete envelope shape, event vocabulary, retry curve, and every namespace.

Testing

Two layers guard the SDK:

• Unit (npm test in this package) — node:test specs under test/ that drive each namespace against a mocked fetch (injected via each call's options), pinning request shape (path, method, bearer, body) and response parsing / error paths.
• Live-API contract — apps/api/test/sdk-*.e2e-spec.ts in the monorepo import the real client from source and exercise it against a live API spawned by the e2e runner (events feed, session-context, LLM gateway, email reads, magic-link, billing lookup). Run with: E2E_ONLY=sdk-events,sdk-session,sdk-llm,sdk-email,sdk-auth,sdk-billing DROPLET_COUNT=1 npm run test:e2e.

License

MIT