@codeletco/sdk

Official TypeScript SDK for the Codelet public API.

Install

npm install @codeletco/sdk

Usage

import { Codelet, CodeletError } from "@codeletco/sdk";

const codelet = new Codelet({
  apiKey: process.env.CODELET_API_KEY!, // cl_live_… or cl_test_…
});

// Ingest (auto idempotency_key when omitted)
await codelet.ingest({
  customer_id: "org_42",
  metric: "api_call",
  quantity: "1",
});

const me = await codelet.account.getMe();
const customers = await codelet.customers.listCustomers();
const packs = await codelet.creditPacks.listCreditPacks({
  metric: "api_request",
  active: "all",
});
await codelet.subscriptions.cancelSubscription("subs_…", {
  mode: "at_period_end",
});

Optional client options: baseUrl, retry, headers, fetchApi.

Examples

Create metrics before plans, credit packs, or ingest. Unknown metric names return 400.

Create a metric

const metric = await codelet.metrics.createMetric({
  name: "api_request",
  display_name: "API Request",
  aggregation: "sum",
});

Create a credit pack

const pack = await codelet.creditPacks.createCreditPack({
  metric: "api_request",
  name: "500 API requests",
  price_amount: "25.00",
  currency: "USD",
  quantity_granted: "500",
});

Create and publish a plan

const plan = await codelet.plans.createPlan({
  name: "Pro",
  description: "Usage-based Pro plan",
  version: {
    currency: "USD",
    billing_period: "monthly",
    billing_mode: "postpaid",
    fixed_fees: [
      {
        fee_type: "period_charge",
        name: "Platform fee",
        amount: "29.00",
      },
    ],
    usage_fees: [
      {
        pricing_model: "unit",
        billing_timing: "in_arrears",
        included_quantity: "1000",
        unit_price: "0.002",
        metric: "api_request",
      },
    ],
  },
});

// Drafts are not checkout-ready until published
await codelet.plans.publishPlan(plan.id);

Create checkout

Credit pack (one-time purchase):

const packCheckout = await codelet.checkout.createCheckout({
  customer_id: "org_42",
  pack_id: "pack_…",
  success_url: "https://yourapp.com/billing/success",
  cancel_url: "https://yourapp.com/billing/cancel",
  idempotency_key: "purchase:order-123",
});
// Redirect the browser to packCheckout.checkout_url

Subscription (plan):

const planCheckout = await codelet.checkout.createCheckout({
  customer_id: "org_42",
  plan_id: "plan_…",
  success_url: "https://yourapp.com/welcome",
});
// Redirect the browser to planCheckout.checkout_url

Pass either customer_id or customer_email, not both. Exactly one of pack_id or plan_id is required.

API reference

All generated methods are available on the Codelet instance (for example codelet.customers.listCustomers). Prefer codelet.ingest(…) over codelet.usage.ingestEvent(…) when recording usage; the helper fills idempotency_key when omitted.

codelet.ingest(body)

Ingest a usage event. Same as usage.ingestEvent, but generates idempotency_key when omitted.

| Method | Description | | --- | --- | | ingest(body) | POST /v1/ingest |

Account (codelet.account)

| Method | Description | | --- | --- | | getMe() | API key context (project + environment) |

Checkout (codelet.checkout)

| Method | Description | | --- | --- | | createCheckout(requestBody) | Create a credit pack or subscription checkout |

Credit packs (codelet.creditPacks)

| Method | Description | | --- | --- | | listCreditPacks({ metric?, active?, pageSize?, cursor? }) | List packs (default: active only) | | createCreditPack(requestBody) | Create a pack | | getCreditPack(packId) | Get a pack by ID | | updateCreditPack(packId, requestBody) | Update name, description, and/or active |

Customers (codelet.customers)

| Method | Description | | --- | --- | | listCustomers({ pageSize?, cursor? }) | List customers | | createCustomer(requestBody) | Create a customer | | getCustomer(customerId) | Get a customer | | updateCustomer(customerId, requestBody) | Update editable fields | | getCustomerBalance(customerId, { metric? }) | Credit balances (all metrics, or one) |

Metrics (codelet.metrics)

| Method | Description | | --- | --- | | listMetrics({ pageSize?, cursor? }) | List metrics | | createMetric(requestBody) | Create a metric | | getMetric(name) | Get a metric by name | | updateMetric(name, requestBody) | Partial update (today: display_name) |

Plans (codelet.plans)

| Method | Description | | --- | --- | | listPlans({ status?, pageSize?, cursor? }) | List plans (default: published) | | createPlan(requestBody) | Create a draft plan | | getPlan(planId, { includePricingDetails? }) | Get a plan | | publishPlan(planId) | Publish the draft version |

Subscriptions (codelet.subscriptions)

| Method | Description | | --- | --- | | listSubscriptions({ customer?, status?, pageSize?, cursor? }) | List subscriptions | | getSubscription(subscriptionId) | Get a subscription | | cancelSubscription(subscriptionId, requestBody) | Cancel (at_period_end or immediate) | | resumeSubscription(subscriptionId) | Clear a scheduled cancellation |

Usage (codelet.usage)

| Method | Description | | --- | --- | | ingestEvent(requestBody) | Ingest a usage event (no auto idempotency key) |

Request and response shapes match the OpenAPI spec. See also codelet.co/SKILL.md for merchant integration guidance.

Errors

import { CodeletError, CodeletRateLimitError } from "@codeletco/sdk";

try {
  await codelet.ingest({ /* … */ });
} catch (error) {
  if (error instanceof CodeletRateLimitError) {
    // 429
  } else if (error instanceof CodeletError) {
    // other API errors (status + body)
  }
}

Generated services throw ApiError from the OpenAPI client. The top-level ingest helper maps those to CodeletError / CodeletRateLimitError.

Development

# from repo root
make sdk-generate
cd sdks/typescript && npm install && npm run build