@littlebearapps/platform-admin-sdk 1.4.2 → 2.0.0

package/templates/shared/tests/unit/workers/batch-persistence.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Unit Tests for Batch Resource Snapshot Persistence
+ *
+ * Tests the batch D1 insert logic in persistResourceUsageSnapshots():
+ * - Rows are batched in groups of 25
+ * - Fallback to individual inserts on batch failure
+ * - SQL uses ON CONFLICT DO UPDATE
+ */
+
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { MockD1Database } from '../../helpers/mock-d1';
+
+// ---------------------------------------------------------------------------
+// Module mocks
+// ---------------------------------------------------------------------------
+
+vi.mock('@littlebearapps/platform-consumer-sdk', async (importOriginal) => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    createLoggerFromEnv: () => ({
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    }),
+  };
+});
+
+import { persistResourceUsageSnapshots } from '../../../workers/lib/usage/scheduled/data-collection';
+
+// ---------------------------------------------------------------------------
+// BatchCapturingD1 — extends MockD1Database to track batch() calls
+// ---------------------------------------------------------------------------
+
+class BatchCapturingD1 extends MockD1Database {
+  batchCalls: unknown[][] = [];
+  batchShouldFail = false;
+  private batchFailCount = 0;
+  private batchFailMax = Infinity;
+
+  failBatchTimes(n: number): void {
+    this.batchShouldFail = true;
+    this.batchFailMax = n;
+    this.batchFailCount = 0;
+  }
+
+  async batch(statements: unknown[]): Promise<unknown[]> {
+    this.batchCalls.push([...statements]);
+    if (this.batchShouldFail && this.batchFailCount < this.batchFailMax) {
+      this.batchFailCount++;
+      throw new Error('Simulated batch failure');
+    }
+    return statements.map(() => ({ success: true, results: [] }));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Fixture factory
+// ---------------------------------------------------------------------------
+
+function makeWorkerEntry(name: string) {
+  return {
+    scriptName: name,
+    requests: 100,
+    errors: 0,
+    cpuTimeMs: 50,
+    duration50thMs: 1,
+    duration99thMs: 5,
+  };
+}
+
+function makeUsageData(workerCount: number) {
+  return {
+    workers: Array.from({ length: workerCount }, (_, i) => makeWorkerEntry(`worker-${i}`)),
+    d1: { reads: 1000, writes: 100 },
+    kv: { reads: 500, writes: 50 },
+    r2: { reads: 10, writes: 2, storage: 1024 },
+  };
+}
+
+// ===========================================================================
+// Tests
+// ===========================================================================
+
+describe('persistResourceUsageSnapshots', () => {
+  it('batches rows in groups of 25', async () => {
+    const db = new BatchCapturingD1();
+    const usageData = makeUsageData(30);
+
+    await persistResourceUsageSnapshots(db as never, usageData as never, 'all');
+
+    // Should have called batch at least once
+    expect(db.batchCalls.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('falls back to individual inserts on batch failure', async () => {
+    const db = new BatchCapturingD1();
+    db.failBatchTimes(1);
+    // Queue individual run results for fallback
+    for (let i = 0; i < 30; i++) {
+      db.queueRunResult({ success: true });
+    }
+
+    const usageData = makeUsageData(5);
+
+    await expect(
+      persistResourceUsageSnapshots(db as never, usageData as never, 'all')
+    ).resolves.not.toThrow();
+  });
+
+  it('handles empty usage data', async () => {
+    const db = new BatchCapturingD1();
+    const usageData = makeUsageData(0);
+
+    await persistResourceUsageSnapshots(db as never, usageData as never, 'all');
+
+    // Should not fail with empty data
+    expect(db.batchCalls.length).toBe(0);
+  });
+
+  it('uses ON CONFLICT in SQL statements', async () => {
+    const db = new BatchCapturingD1();
+    const usageData = makeUsageData(1);
+
+    await persistResourceUsageSnapshots(db as never, usageData as never, 'all');
+
+    const hasConflict = db.statements.some((s: string) =>
+      s.toUpperCase().includes('ON CONFLICT')
+    );
+    expect(hasConflict).toBe(true);
+  });
+});

package/templates/shared/tests/unit/workers/budget-enforcement.test.ts

@@ -0,0 +1,214 @@
+/**
+ * Unit Tests for Budget Enforcement
+ *
+ * Covers:
+ * - Feature-level budget warnings at 70%/90% thresholds
+ * - Circuit breaker trip at 100%
+ * - Monthly budget tracking
+ * - Dedup via KV BUDGET_WARN: prefix
+ */
+
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { createMockKV } from '../../helpers/mock-kv';
+import { MockD1Database } from '../../helpers/mock-d1';
+
+// ---------------------------------------------------------------------------
+// Module mocks — must be before imports that resolve these modules
+// ---------------------------------------------------------------------------
+
+vi.mock('@littlebearapps/platform-consumer-sdk', async (importOriginal) => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    createLoggerFromEnv: () => ({
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    }),
+  };
+});
+
+vi.mock('../../../workers/lib/circuit-breaker-middleware', () => ({
+  CB_STATUS: { CLOSED: 'active', WARNING: 'warning', OPEN: 'paused' },
+}));
+
+vi.mock('../../../workers/lib/platform-settings', () => ({
+  getPlatformSettings: vi.fn().mockResolvedValue({}),
+  getProjectSetting: vi.fn().mockResolvedValue(null),
+  DEFAULT_PLATFORM_SETTINGS: {},
+}));
+
+const mockFetch = vi.fn().mockResolvedValue(new Response('ok', { status: 200 }));
+
+import {
+  checkAndUpdateBudgetStatus,
+  checkMonthlyBudgets,
+} from '../../../workers/lib/usage/queue/budget-enforcement';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createTestEnv(kvData: Record<string, string> = {}, slackUrl?: string) {
+  const db = new MockD1Database();
+  db.queueRunResult({ success: true });
+  db.queueRunResult({ success: true });
+
+  return {
+    env: {
+      PLATFORM_CACHE: createMockKV(kvData),
+      PLATFORM_DB: db,
+      SLACK_WEBHOOK_URL: slackUrl,
+      NOTIFICATIONS_API: undefined,
+      PLATFORM_TELEMETRY: undefined,
+      TELEMETRY_QUEUE: undefined,
+    } as unknown,
+    db,
+  };
+}
+
+// ===========================================================================
+// Section A: Feature-Level Budget Warnings
+// ===========================================================================
+
+describe('checkAndUpdateBudgetStatus', () => {
+  beforeEach(() => {
+    vi.stubGlobal('fetch', mockFetch);
+    mockFetch.mockClear();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('fires 70% warning when metric is between 70-89% of budget', async () => {
+    const { env } = createTestEnv(
+      {
+        'CONFIG:FEATURE:test:api:endpoint:BUDGET': JSON.stringify({
+          d1_rows_written: 100_000,
+        }),
+      },
+      'https://hooks.slack.com/test'
+    );
+
+    await checkAndUpdateBudgetStatus(
+      'test:api:endpoint',
+      { d1RowsWritten: 72_000 } as never,
+      env as never
+    );
+
+    const kv = (env as Record<string, unknown>).PLATFORM_CACHE as ReturnType<typeof createMockKV>;
+    expect(kv.put).toHaveBeenCalledWith(
+      'BUDGET_WARN:test:api:endpoint:d1RowsWritten:70',
+      '1',
+      { expirationTtl: 3600 }
+    );
+  });
+
+  it('fires 90% critical warning when metric >= 90% of budget', async () => {
+    const { env } = createTestEnv(
+      {
+        'CONFIG:FEATURE:test:api:endpoint:BUDGET': JSON.stringify({
+          d1_rows_written: 100_000,
+        }),
+      },
+      'https://hooks.slack.com/test'
+    );
+
+    await checkAndUpdateBudgetStatus(
+      'test:api:endpoint',
+      { d1RowsWritten: 92_000 } as never,
+      env as never
+    );
+
+    const kv = (env as Record<string, unknown>).PLATFORM_CACHE as ReturnType<typeof createMockKV>;
+    expect(kv.put).toHaveBeenCalledWith(
+      'BUDGET_WARN:test:api:endpoint:d1RowsWritten:90',
+      '1',
+      { expirationTtl: 3600 }
+    );
+  });
+
+  it('does not fire warning when metric is below 70%', async () => {
+    const { env } = createTestEnv(
+      {
+        'CONFIG:FEATURE:test:api:endpoint:BUDGET': JSON.stringify({
+          d1_rows_written: 100_000,
+        }),
+      },
+      'https://hooks.slack.com/test'
+    );
+
+    await checkAndUpdateBudgetStatus(
+      'test:api:endpoint',
+      { d1RowsWritten: 50_000 } as never,
+      env as never
+    );
+
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('skips warning when dedup key already exists', async () => {
+    const { env } = createTestEnv(
+      {
+        'CONFIG:FEATURE:test:api:endpoint:BUDGET': JSON.stringify({
+          d1_rows_written: 100_000,
+        }),
+        'BUDGET_WARN:test:api:endpoint:d1RowsWritten:70': '1',
+      },
+      'https://hooks.slack.com/test'
+    );
+
+    await checkAndUpdateBudgetStatus(
+      'test:api:endpoint',
+      { d1RowsWritten: 75_000 } as never,
+      env as never
+    );
+
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when no budget config exists', async () => {
+    const { env } = createTestEnv({}, 'https://hooks.slack.com/test');
+
+    await checkAndUpdateBudgetStatus(
+      'test:api:endpoint',
+      { d1RowsWritten: 99_000 } as never,
+      env as never
+    );
+
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+});
+
+// ===========================================================================
+// Section B: Monthly Budget Tracking
+// ===========================================================================
+
+describe('checkMonthlyBudgets', () => {
+  beforeEach(() => {
+    vi.stubGlobal('fetch', mockFetch);
+    mockFetch.mockClear();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('queries daily_usage_rollups for current month', async () => {
+    const { env, db } = createTestEnv({});
+    db.queueAllResult([]);
+
+    await checkMonthlyBudgets(env as never);
+
+    expect(db.statements.some((s: string) => s.includes('daily_usage_rollups'))).toBe(true);
+  });
+
+  it('handles missing tables gracefully', async () => {
+    const { env } = createTestEnv({});
+
+    // Should not throw even with empty DB
+    await expect(checkMonthlyBudgets(env as never)).resolves.not.toThrow();
+  });
+});

package/templates/shared/vitest.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      include: ['workers/**/*.ts'],
+    },
+  },
+  resolve: {
+    alias: {
+      '@': './src',
+    },
+  },
+});

package/templates/shared/workers/lib/usage/collectors/anthropic.ts

@@ -0,0 +1,114 @@
+/**
+ * Anthropic (Claude) Usage Collector
+ *
+ * Collects API usage from the Anthropic Admin Usage API.
+ * Requires an Admin API key with organization:usage:read scope.
+ *
+ * NOTE: This only tracks API usage (developer/organization consumption).
+ * Claude Max subscriptions (claude.ai consumer product) are NOT tracked here -
+ * there is no API to retrieve Claude Max conversation/usage data.
+ *
+ * This is a FLOW metric (usage that accumulates) - safe to SUM.
+ *
+ * @see https://docs.anthropic.com/en/api/admin-api
+ */
+
+import type { Env, AnthropicUsageData } from '../shared';
+import { fetchWithRetry } from '../shared';
+import { createLoggerFromEnv } from '@littlebearapps/platform-consumer-sdk';
+import type { ExternalCollector } from './index';
+
+/**
+ * Collect Anthropic (Claude) API usage from the Admin Usage API.
+ * Requires an Admin API key with organization:usage:read scope.
+ */
+export async function collectAnthropicUsage(env: Env): Promise<AnthropicUsageData | null> {
+  const log = createLoggerFromEnv(env, 'platform-usage', 'platform:usage:anthropic');
+  if (!env.ANTHROPIC_ADMIN_API_KEY) {
+    log.info('No ANTHROPIC_ADMIN_API_KEY configured, skipping usage collection');
+    return null;
+  }
+
+  try {
+    // Get usage for the last 24 hours
+    const now = new Date();
+    const yesterday = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+    const startTime = yesterday.toISOString().replace(/\.\d{3}Z$/, 'Z');
+    const endTime = now.toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+    const url =
+      `https://api.anthropic.com/v1/organizations/usage?` +
+      `start_time=${startTime}&end_time=${endTime}&group_by=model`;
+
+    const response = await fetchWithRetry(url, {
+      headers: {
+        'anthropic-version': '2023-06-01',
+        'x-api-key': env.ANTHROPIC_ADMIN_API_KEY,
+      },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      log.error(`Usage API returned ${response.status}: ${errorText}`);
+      return null;
+    }
+
+    const data = (await response.json()) as {
+      data?: Array<{
+        model?: string;
+        input_tokens?: number;
+        output_tokens?: number;
+      }>;
+    };
+
+    if (!data.data || !Array.isArray(data.data)) {
+      log.info('No usage data returned');
+      return { inputTokens: 0, outputTokens: 0, totalCost: 0, modelBreakdown: {} };
+    }
+
+    const result: AnthropicUsageData = {
+      inputTokens: 0,
+      outputTokens: 0,
+      totalCost: 0,
+      modelBreakdown: {},
+    };
+
+    // Aggregate usage by model
+    for (const item of data.data) {
+      const inputTokens = item.input_tokens || 0;
+      const outputTokens = item.output_tokens || 0;
+      result.inputTokens += inputTokens;
+      result.outputTokens += outputTokens;
+
+      if (item.model) {
+        if (!result.modelBreakdown[item.model]) {
+          result.modelBreakdown[item.model] = { inputTokens: 0, outputTokens: 0 };
+        }
+        result.modelBreakdown[item.model].inputTokens += inputTokens;
+        result.modelBreakdown[item.model].outputTokens += outputTokens;
+      }
+    }
+
+    // Estimate cost (rough approximation - actual pricing varies by model)
+    // Claude Sonnet: $3/$15 per MTok, Claude Opus: $15/$75 per MTok
+    // Using average estimate of $5/$20 per MTok
+    result.totalCost = (result.inputTokens * 5 + result.outputTokens * 20) / 1_000_000;
+
+    log.info('Collected usage', {
+      inputTokens: result.inputTokens,
+      outputTokens: result.outputTokens,
+      estimatedCost: result.totalCost,
+    });
+    return result;
+  } catch (error) {
+    log.error('Failed to collect usage', error);
+    return null;
+  }
+}
+
+/** Collector registration for use in collectors/index.ts COLLECTORS array */
+export const anthropicCollector: ExternalCollector<AnthropicUsageData | null> = {
+  name: 'anthropic',
+  collect: collectAnthropicUsage,
+  defaultValue: null,
+};

package/templates/shared/workers/lib/usage/collectors/apify.ts

@@ -0,0 +1,96 @@
+/**
+ * Apify Usage Collector
+ *
+ * Collects platform usage from the Apify Monthly Usage API.
+ *
+ * This is a FLOW metric (usage that accumulates) - safe to SUM.
+ *
+ * @see https://docs.apify.com/api/v2/users-me-usage-monthly-get
+ */
+
+import type { Env, ApifyUsageData } from '../shared';
+import { fetchWithRetry } from '../shared';
+import { createLoggerFromEnv } from '@littlebearapps/platform-consumer-sdk';
+import type { ExternalCollector } from './index';
+
+/**
+ * Collect Apify platform usage from the Monthly Usage API.
+ */
+export async function collectApifyUsage(env: Env): Promise<ApifyUsageData | null> {
+  const log = createLoggerFromEnv(env, 'platform-usage', 'platform:usage:apify');
+  if (!env.APIFY_API_KEY) {
+    log.info('No APIFY_API_KEY configured, skipping usage collection');
+    return null;
+  }
+
+  try {
+    const response = await fetchWithRetry('https://api.apify.com/v2/users/me/usage/monthly', {
+      headers: {
+        Authorization: `Bearer ${env.APIFY_API_KEY}`,
+        Accept: 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      if (response.status === 401) {
+        log.info('API key invalid or expired');
+        return null;
+      }
+      log.error(`Usage API returned ${response.status}: ${errorText}`);
+      return null;
+    }
+
+    const data = (await response.json()) as {
+      data?: {
+        monthlyServiceUsage?: Record<
+          string,
+          {
+            quantity?: number;
+            baseAmountUsd?: number;
+          }
+        >;
+        totalUsageCreditsUsdAfterVolumeDiscount?: number;
+      };
+    };
+
+    const result: ApifyUsageData = {
+      totalUsageCreditsUsd: data.data?.totalUsageCreditsUsdAfterVolumeDiscount || 0,
+      actorComputeUnits: 0,
+      dataTransferGb: 0,
+      storageGb: 0,
+    };
+
+    const services = data.data?.monthlyServiceUsage;
+    if (services) {
+      if (services.ACTOR_COMPUTE_UNITS) {
+        result.actorComputeUnits = services.ACTOR_COMPUTE_UNITS.quantity || 0;
+      }
+      if (services.DATA_TRANSFER_EXTERNAL_GBYTES) {
+        result.dataTransferGb = services.DATA_TRANSFER_EXTERNAL_GBYTES.quantity || 0;
+      }
+      if (services.DATASET_STORAGE_GBYTES) {
+        result.storageGb += services.DATASET_STORAGE_GBYTES.quantity || 0;
+      }
+      if (services.KEY_VALUE_STORE_STORAGE_GBYTES) {
+        result.storageGb += services.KEY_VALUE_STORE_STORAGE_GBYTES.quantity || 0;
+      }
+    }
+
+    log.info('Collected usage', {
+      totalUsageCreditsUsd: result.totalUsageCreditsUsd,
+      actorComputeUnits: result.actorComputeUnits,
+    });
+    return result;
+  } catch (error) {
+    log.error('Failed to collect usage', error);
+    return null;
+  }
+}
+
+/** Collector registration for use in collectors/index.ts COLLECTORS array */
+export const apifyCollector: ExternalCollector<ApifyUsageData | null> = {
+  name: 'apify',
+  collect: collectApifyUsage,
+  defaultValue: null,
+};