Package Exports
- @nozle-js/node
Readme
@nozle-js/node
Server-side Node.js SDK for usage tracking, entitlement checks, margin intelligence, and billing management.
Install
npm install @nozle-js/nodeWorks with both JavaScript and TypeScript. Requires Node.js 18+.
Quick Start
import { Nozle } from "@nozle-js/node";
const nozle = new Nozle({ apiKey: "sk_live_..." });
// Track usage event
await nozle.track("cust_123", "tokens_used", { tokens: 150, model: "gpt-4o" });
// Entitlement check
const { allowed, reason, used, limit } = await nozle.can("cust_123", "code_completion");Configuration
const nozle = new Nozle({
apiKey: "sk_live_...", // Required
baseUrl: "https://api.nozle.ai", // Default: http://localhost:8080
eventsUrl: "https://lago.nozle.ai", // Default: http://localhost:3000
timeout: 15_000, // Default: 10000ms
});Usage Tracking
// Basic tracking (auto-resolves subscription)
await nozle.track("cust_123", "api_call", { tokens: 100 });
// With explicit subscription
await nozle.track("cust_123", "api_call", { tokens: 100 }, {
subscriptionId: "sub_abc",
});
// With custom transaction ID and timestamp
await nozle.track("cust_123", "api_call", { tokens: 100 }, {
transactionId: "tx_custom_123",
timestamp: "2025-01-15T10:30:00Z",
});Subscription auto-resolution: if no subscriptionId is provided, the SDK looks up the customer's active subscription and caches it for subsequent calls.
Entitlement Checks
const result = await nozle.can("cust_123", "code_completion");
if (result.allowed) {
// Feature is available
console.log(`${result.remaining} uses remaining`);
} else {
// Blocked: result.reason is "usage_limit_exceeded" or "below_margin_floor"
console.log(`Blocked: ${result.reason}`);
}Response includes cost intelligence:
result.cost_per_use_cents // Your cost per unit
result.revenue_per_use_cents // What you charge per unit
result.margin_per_use_cents // Revenue minus cost
result.min_margin_percent // Configured margin floor (if set)Margin Intelligence
Requires a secret key (sk_ prefix).
// Overall margin summary
const summary = await nozle.margin.summary();
// Breakdown by dimension
const byCustomer = await nozle.margin.byCustomer();
const byMetric = await nozle.margin.byMetric();
const byPlan = await nozle.margin.byPlan();
const byModel = await nozle.margin.byModel();
// Trend over time
const trend = await nozle.margin.trend({ granularity: "day" });
const weeklyTrend = await nozle.margin.trend({ granularity: "week" });
// With time range
const q1 = await nozle.margin.summary({
from: "2025-01-01T00:00:00Z",
to: "2025-03-31T23:59:59Z",
});Plans & Checkout
// List available plans
const plans = await nozle.plans();
// Create checkout session (returns Stripe client_secret)
const { client_secret, session_id } = await nozle.checkout("cust_123", "pro");
// Create subscription after payment
const { subscription_id, status } = await nozle.subscribe("cust_123", "pro");TypeScript
All methods and responses are fully typed. Exported types:
import type {
NozleConfig,
TrackOptions,
CanResult,
Plan,
CheckoutResult,
SubscribeResult,
MarginQueryParams,
TrendParams,
} from "@nozle-js/node";License
Proprietary