drizzle-otel/packages/otel-autumn/README.md

@kubiks/otel-autumn

OpenTelemetry instrumentation for the Autumn billing SDK. Capture spans for every billing operation including feature checks, usage tracking, checkout flows, product attachments, and cancellations with detailed metadata.

Visualize your billing operations with detailed span information including operation type, customer IDs, feature IDs, and billing metadata.

Installation

npm install @kubiks/otel-autumn
# or
pnpm add @kubiks/otel-autumn

Peer Dependencies: @opentelemetry/api >= 1.9.0, autumn-js >= 0.1.0

Quick Start

import { Autumn } from "autumn-js";
import { instrumentAutumn } from "@kubiks/otel-autumn";

const autumn = instrumentAutumn(
  new Autumn({
    secretKey: process.env.AUTUMN_SECRET_KEY!,
  }),
);

// All operations are now automatically traced
const checkResult = await autumn.check({
  customer_id: "user_123",
  feature_id: "messages",
});

await autumn.track({
  customer_id: "user_123",
  feature_id: "messages",
  value: 1,
});

instrumentAutumn wraps your Autumn client instance — no configuration changes needed. Every SDK call creates a client span with detailed billing attributes.

What Gets Traced

This instrumentation wraps the core Autumn billing methods:

• check - Feature access and product status checks
• track - Usage event tracking
• checkout - Checkout session creation
• attach - Product attachment to customers
• cancel - Product cancellation

Each operation creates a dedicated span with operation-specific attributes.

Span Attributes

Common Attributes (All Operations)

Attribute	Description	Example
billing.system	Constant value autumn	autumn
billing.operation	Operation type	check, track
autumn.resource	Resource being accessed	features, products
autumn.target	Full operation target	features.check
autumn.customer_id	Customer ID	user_123
autumn.entity_id	Entity ID (if applicable)	org_456

Check Operation

Attribute	Description	Example
autumn.feature_id	Feature being checked	messages
autumn.product_id	Product being checked	pro
autumn.allowed	Whether access is allowed	true
autumn.balance	Current balance/remaining uses	42
autumn.usage	Current usage	8
autumn.included_usage	Included usage in plan	50
autumn.unlimited	Whether usage is unlimited	false
autumn.required_balance	Required balance for operation	1

Track Operation

Attribute	Description	Example
autumn.feature_id	Feature being tracked	messages
autumn.event_name	Custom event name	message_sent
autumn.value	Usage value tracked	1
autumn.event_id	Generated event ID	evt_123
autumn.idempotency_key	Idempotency key for dedup	msg_456

Checkout Operation

Attribute	Description	Example
autumn.product_id	Product being purchased	pro
autumn.product_ids	Multiple products (comma-separated)	pro, addon_analytics
autumn.checkout_url	Stripe checkout URL	https://checkout.stripe.com/...
autumn.has_prorations	Whether prorations apply	true
autumn.total_amount	Total checkout amount	2000 (cents)
autumn.currency	Currency code	usd
autumn.force_checkout	Whether to force Stripe checkout	false
autumn.invoice	Whether to create invoice	true

Attach Operation

Attribute	Description	Example
autumn.product_id	Product being attached	pro
autumn.success	Whether attachment succeeded	true
autumn.checkout_url	Checkout URL if payment needed	https://checkout.stripe.com/...

Cancel Operation

Attribute	Description	Example
autumn.product_id	Product being cancelled	pro
autumn.success	Whether cancellation succeeded	true

Configuration

You can optionally configure the instrumentation:

import { instrumentAutumn } from "@kubiks/otel-autumn";

const autumn = instrumentAutumn(client, {
  // Capture customer data in spans (default: false)
  captureCustomerData: true,

  // Capture product options/configuration (default: false)
  captureOptions: true,
});

Usage Examples

Feature Access Control

const autumn = instrumentAutumn(
  new Autumn({ secretKey: process.env.AUTUMN_SECRET_KEY! }),
);

// Check if user can access a feature
const result = await autumn.check({
  customer_id: "user_123",
  feature_id: "messages",
  required_balance: 1,
});

if (result.data?.allowed) {
  // User has access
  console.log(`Remaining: ${result.data.balance}`);
}

Usage Tracking

// Track feature usage
await autumn.track({
  customer_id: "user_123",
  feature_id: "messages",
  value: 1,
  idempotency_key: `msg_${messageId}`, // Prevent double-counting
});

Checkout Flow

// Create a checkout session for a product
const result = await autumn.checkout({
  customer_id: "user_123",
  product_id: "pro",
  force_checkout: false, // Use billing portal if payment method exists
});

if (result.data?.url) {
  // Redirect to Stripe checkout
  console.log(`Checkout URL: ${result.data.url}`);
}

Product Management

// Attach a free product
const attachResult = await autumn.attach({
  customer_id: "user_123",
  product_id: "free",
});

// Cancel a subscription
const cancelResult = await autumn.cancel({
  customer_id: "user_123",
  product_id: "pro",
});

License

MIT