TypeScript SDK

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

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

// Reads the API key from ALGUNA_API_KEY when you do not pass apiKey.
const alguna = new Alguna({
  apiVersion: "2026-04-01", // recommended — 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 page = await alguna.customers.list({ limit: 50, offset: 0, sort: "name:asc" });
page.data; // CustomerResponse[]
page.response.pagination; // { per_page, total_pages }

for await (const customer of await alguna.customers.list({ limit: 100 })) {
  console.log(customer.id);
}

const pdf = await alguna.invoices.generatePdf(invoice.id);
await writeFile("invoice.pdf", Buffer.from(await pdf.arrayBuffer()));

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 ValidationError) {
    // error.message — the API's explanation of what is wrong
  } else if (error instanceof RateLimitError) {
    // only the credit check/track endpoints send 429
  }
}

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",           // optional — defaults to ALGUNA_API_KEY
  apiVersion: "2026-04-01",              // optional — defaults to the version this package was built for
  baseUrl: "https://api.alguna.io", // optional — the default
  timeout: 60_000,                       // optional — timeout of each attempt in ms
  maxRetries: 2,                         // optional — see Idempotency and retries
});