@stubvia/client

TypeScript client for the Stubvia REST API: typed HTTP methods, tenant-scoped integrator helpers, webhook verification, and checkout deep links.

Install

npm install @stubvia/client

Quick start

import {
  createIntegratorClient,
  verifyWebhookSignature,
  parseIntegratorWebhook,
  buildSignedCheckoutUrl,
} from "@stubvia/client";

const stubvia = createIntegratorClient({
  baseUrl: process.env.STUBVIA_API_URL!,
  externalSystem: "myapp",
  platformApiKey: process.env.STUBVIA_API_KEY!,
  resolveTenantApiKey: async (tenantId) => loadApiKeyFromDb(tenantId),
});

// One-call tenant onboarding (org, legal, API key, webhook, Mercado Pago)
await stubvia.enableTenant({
  tenantId: "tenant_42",
  organizationName: "My Org",
  ownerEmail: "[email protected]",
  webhook: {
    webhookUrl: "https://myapp.com/api/stubvia/webhook",
    webhookSecret: process.env.STUBVIA_WEBHOOK_SECRET!,
  },
  mercadoPagoSeller: {
    accessToken: mpAccessToken,
    refreshToken: mpRefreshToken,
    sellerUserId: mpUserId,
  },
});

// Sync event (externalSystem + idempotency handled)
const { event } = await stubvia.upsertTenantEvent("tenant_42", {
  externalId: "evt_123",
  title: "Show",
  startsAt: "2026-07-01T20:00:00.000Z",
  tiers: [{ name: "Pista", priceCents: 8000, quantityTotal: 200 }],
  publish: true,
});

const orders = await stubvia.listPaidOrdersForTenantEvent("tenant_42", "evt_123");
const checkIn = await stubvia.checkInTenantTicket("tenant_42", event.id, orders[0].admissionQr!);

// Signed checkout link for a known buyer
const checkoutUrl = buildSignedCheckoutUrl(event.checkoutUrl!, {
  externalSystem: "myapp",
  buyerId: "user_99",
  externalId: "evt_123",
  secret: process.env.STUBVIA_WEBHOOK_SECRET!,
  buyerEmail: "[email protected]",
});

// Webhook route
const rawBody = await request.text();
const verified = verifyWebhookSignature({
  secret: process.env.STUBVIA_WEBHOOK_SECRET,
  body: rawBody,
  signatureHeader: request.headers.get("x-stubvia-signature"),
  timestampHeader: request.headers.get("x-stubvia-timestamp"),
});
if (!verified.ok) return Response.json({ error: "Unauthorized" }, { status: 401 });

const webhook = parseIntegratorWebhook(JSON.parse(rawBody), request.headers.get("x-stubvia-event"));
if (webhook?.type === "order.paid") {
  await saveOrder(webhook.data.order);
}

What the SDK handles for you

• Normalized responses — nullable fields are always null, not undefined
• Tenant scope — externalSystem and idempotency keys on writes
• Webhooks — HMAC verification, parsing order.paid / order.checked_in / refunds
• Checkout links — sign and parse cm / ce / cs query params
• Event helpers — summarizeEventTickets() for price, capacity, checkout URL

Docs

• Integration guide
• OpenAPI reference

Requirements

Node.js 20+