TypeScript SDK

npm install @alguna/sdk
# or
pnpm add @alguna/sdk

import { Alguna } from "@alguna/sdk";

const alguna = new Alguna({
  apiKey: process.env.ALGUNA_API_KEY,
  apiVersion: "2026-04-01", // required — pin the version you integrate against
});

// 1. Create a customer
const customer = await alguna.customers.create({
  name: "Acme Corp",
  currency: "USD",
  contacts: [{ email: "billing@acme.com", is_primary: true }],
});

// 2. Create a product and start a subscription
const product = await alguna.products.create({
  name: "Platform Fee",
  fee_type: "fixed",
  billing_frequency: "recurring",
  payment_terms: "advance",
});

const subscription = await alguna.subscriptions.create({
  customer_id: customer.id,
  currency: "USD",
  items: [
    {
      product_id: product.id,
      price: {
        type: "fixed",
        fee_type: "fixed",
        billing_direction: "advance",
        billing_frequency: "recurring",
        billing_interval: "monthly",
        fixed_pricing_model: { price_per_unit: "99.00", units: 1 },
      },
    },
  ],
  contract: { period_type: "fixed", duration_months: 12, start_date: "2026-07-01" },
  auto_activate: true,
});

// 3. Issue a one-off invoice
const invoice = await alguna.invoices.create({
  customer_id: customer.id,
  currency: "USD",
  line_items: [{ description: "Onboarding", unit_price: "500.00", quantity: "1" }],
});

// 4. Open a customer portal session so the customer can pay and manage billing
const session = await alguna.portal.createSession({ customer_id: customer.id });
console.log(session.url); // redirect the customer here; the session expires after 1 hour

import type { CreateCustomerRequest, InvoiceResponse } from "@alguna/sdk";

const { data, pagination } = await alguna.customers.list({
  limit: 50,
  offset: 0,
  sort: "name:asc",
});
// data: CustomerResponse[]
// pagination: { per_page, total_pages }

import { NotFoundError, RateLimitError, ValidationError } from "@alguna/sdk";

try {
  await alguna.customers.get("nope");
} catch (error) {
  if (error instanceof NotFoundError) {
    // error.message, error.statusCode, error.requestId
  } else if (error instanceof RateLimitError) {
    // error.retryAfter — seconds to wait before retrying
  } else if (error instanceof ValidationError) {
    // error.fields — per-field validation messages
  }
}

await alguna.subscriptions.create(
  { customer_id: customer.id, plan_id: "plan_abc123", auto_activate: true },
  { idempotencyKey: "order_1234" },
);

const alguna = new Alguna({
  apiKey: "key_id.key_secret",           // required
  apiVersion: "2026-04-01",              // required — pins the Alguna-Version header
  baseUrl: "https://api.alguna.io/beta", // optional — the default
  timeout: 30_000,                       // optional — request timeout in ms
});