@trackingkoala/sdk

Official Node.js SDK for TrackingKoala.

Installation

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

Usage

import {
  TrackingKoala,
  TrackingKoalaApiError,
  TrackingKoalaNetworkError,
  TrackingKoalaValidationError
} from "@trackingkoala/sdk";

const koala = new TrackingKoala("YOUR_API_KEY", {
  timeoutMs: 10000
});

try {
  await koala.track({
    cost: 150,
    // amount: 150, // alias for cost
    charge: 299,
    currency: "USD",
    environment: "production",
    provider: "openai",
    action: "signup",
    userId: "usr_123",
    traces: ["trace_abc"],
    tags: ["signup", "conversion"],
    metadata: {
      plan: "pro",
      source: "google_ads"
    }
  });
} catch (error) {
  if (error instanceof TrackingKoalaValidationError) {
    console.error("Validation failed", error.issues);
  } else if (error instanceof TrackingKoalaApiError) {
    console.error("API failed", error.status, error.responseBody);
  } else if (error instanceof TrackingKoalaNetworkError) {
    console.error("Network failed", error.message);
  } else {
    throw error;
  }
}

Template Execution

const result = await koala.rateTemplate({
  templateId: "tmpl_openai_pricing",
  mode: "preview", // or "track"
  inputs: {
    model: "gpt-4.1",
    input_tokens: 1200,
    output_tokens: 450
  },
  event: {
    source: "template",
    provider: "openai",
    action: "summarize"
  }
});

console.log(result.cost, result.charge, result.breakdown);

Client Validation

• cost (or amount) must be a finite number greater than 0.
• charge, when provided, must be a finite number greater than 0.
• If both cost and amount are provided, they must be equal.
• userId is the canonical identity field. customerId is still accepted as a backward-compatible alias.
• If both userId and customerId are provided, they must be equal.
• tags and traces default to [] when omitted.

IntelliSense and Method Docs

The SDK ships with TypeScript declarations and JSDoc comments on constructor options, methods, and errors so editors show inline usage details.

Publishing to Private Registry

To publish this package to a private registry (e.g. GitHub Packages or a self-hosted Verdaccio instance):

1. Configure .npmrc: Create a .npmrc file in the project root or user home directory with the registry URL and authentication token.

   //npm.pkg.github.com/:_authToken=YOUR_TOKEN
   @trackingkoala:registry=https://npm.pkg.github.com

2. Update package.json: Ensure the publishConfig points to your registry.

   "publishConfig": {
     "registry": "https://npm.pkg.github.com"
   }

3. Publish: Run npm publish or pnpm publish.

Development

• pnpm build: Build the package
• pnpm dev: Watch mode