await owo.track({
  customer: string,    // Your internal user ID
  feature: string,     // Feature key being used
  value?: number,      // Amount to track (default: 1)
  entity?: string,     // Optional entity scope (seat, workspace, org)
  customerData?: {     // Optional: auto-create customer
    email: string,
    name?: string,
    metadata?: Record<string, unknown>,
  },
  metadata?: object,   // Optional event metadata
}): Promise<TrackResult>

interface TrackResult {
  success: boolean;
  allowed: boolean; // Whether the usage was accepted
  code: string; // tracked, tracked_overage, limit_exceeded, etc.
  usage: number | null;
  limit: number | null;
  balance: number | null; // Remaining balance when applicable
  resetsAt: string | null; // Period reset time
  resetInterval: string | null;
  credits:
    | {
        source: "credit_system";
        systemSlug: string;
        costPerUnit: number;
        addonBalance: number;
        plan: {
          used: number;
          limit: number | null;
          balance: number | null;
          resetsAt: string;
        };
      }
    | {
        source: "prepaid";
        addonBalance: null;
        plan: {
          used: number;
          limit: number | null;
          balance: number | null;
          resetsAt: string;
        };
      }
    | null;
  details: {
    message: string;
    planName?: string;
    trial?: boolean;
    trialEndsAt?: string | null;
  };
}

import { Owostack } from "owostack";

const owo = new Owostack({ secretKey: process.env.OWOSTACK_API_KEY });

// Track a single API call
await owo.track({
  customer: "user_123",
  feature: "api_calls",
});

// Track storage usage (e.g., 1.5 MB uploaded)
await owo.track({
  customer: "user_123",
  feature: "storage_mb",
  value: 1.5,
});

// Track multiple items at once
await owo.track({
  customer: "user_123",
  feature: "messages_sent",
  value: 10,
});

await owo.track({
  customer: "user_123",
  feature: "api_calls",
  value: 1,
  metadata: {
    endpoint: "/api/generate",
    responseTime: 234,
    model: "gpt-4",
  },
});

// Common pattern: check quota, then track usage
async function processRequest(userId: string) {
  // 1. Check if customer has remaining quota
  const check = await owo.check({
    customer: userId,
    feature: "api_calls",
  });

  if (!check.allowed) {
    throw new Error(`Quota exceeded. Resets at ${check.resetsAt}`);
  }

  // 2. Process the request
  const result = await expensiveOperation();

  // 3. Track usage after successful completion
  await owo.track({
    customer: userId,
    feature: "api_calls",
  });

  return result;
}

// Track each AI token generated
await owo.track({
  customer: "user_123",
  feature: "ai_tokens",
  value: response.usage.total_tokens,
});

const result = await owo.track({
  customer: "user_123",
  feature: "exports",
});

console.log(`${result.balance} exports remaining this month`);

const result = await owo.track({
  customer: "user_123",
  feature: "gpt-4",
  value: 1,
});

if (result.credits?.source === "credit_system") {
  console.log("Plan credits left:", result.credits.plan.balance);
  console.log("Add-on credits left:", result.credits.addonBalance);
}