@pouchy_ai/admin-sdk 0.41.0 → 0.43.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.43.0 — 2026-10-08
+
+- **Three period reads** (admin API 1.20.0), the same answers the dashboard
+  reads, so a period's numbers can go straight into an integrator's own BI:
+  - `getUsageRange({ from, to, tz? })` — usage over any period up to 366 days,
+    day by day, with the same-length previous period. `distinct` is an
+    estimate of distinct live users over the period (HyperLogLog, about ±5%;
+    `complete: false` means a lower bound), with daily estimates for periods up
+    to 92 days. `tz` cuts the days in an IANA zone; a day the hourly data does
+    not cover is the UTC day of that date, marked `utcFallback`.
+  - `getUsageBreakdown({ from, to })` — where the tokens went, by stage and by
+    experience; every row is a slice of `totalTokens`, and the remainders
+    (`untaggedTokens`, `nonWorldTokens`) are reported rather than dropped.
+  - `getRunHistory({ from, to })` — runs, errors, latency and tokens per day and
+    per agent from daily rollups, past the 30-day trace retention. Percentiles
+    are bucket upper edges, not exact values; `uncoveredDays` names days whose
+    runs are missing.
+  Additive; no existing method changed.
+
+## 0.42.0 — 2026-10-08
+
+- **`getRecentTraces({ from, to })`: a custom window by UTC day** (admin API
+  1.19.0). The run browser could only look back from now (`sinceHours`); a
+  window that ends in the past (last Tuesday's failures) had no expression.
+  `from` / `to` are inclusive UTC days, given together, within the 30-day trace
+  retention — older is a 400, never an empty list that reads as "no runs".
+  `window.untilMs` (exclusive) is typed and present on such a window.
+  `sinceHours` alone behaves as before. Additive.
+- **`getUsageHistory()` rows carry `credits`** — the credits charged that
+  month (the pooled account figure on `scope: 'account'`), typed as optional
+  because an older server does not send it.
+
 ## 0.41.0 — 2026-10-02
 
 - **Three world session-mint codes join `ADMIN_ERROR_CODES`.** `POST

package/README.md

@@ -474,7 +474,7 @@ Reads (`GET`) are not covered by that bucket. `retryAfter` is available from
 | Durable runs | `listRuns` · `createRun` · `getRun` · `cancelRun` · `resumeRun` · `signalRun` |
 | Data capabilities | `listCapabilities` (heads + MASKED signing status) · `publishCapability` (TYPED `CapabilityDeclaration`; immutable next version, idempotent on content) · `setCapabilityDisabled` (per-capability live revoke) · `listCapabilityVersions` (history; rollback = republish an old declaration) · `testReadCapability` · `testActionCapability({ confirmDuplicates: true, … })` (REAL deliveries incl. intentional duplicates — 428 without consent) · `listActionExecutions` (the durable Action journal, incl. `authorizedBy: 'automation'`) · `listEventReceipts` (receipts + wake trail) |
 | Webhooks | `listWebhooks` · `createWebhook` · `updateWebhook` · `rotateWebhookSecret` · `deleteWebhook` · `testWebhook` · `redeliverWebhook` |
-| Reporting | `getUsage` · `getUsageHistory` · `getBilling` · `getTracesSummary` · `getRecentTraces` · `getLogs` · `getProject` · `updateProject` |
+| Reporting | `getUsage` · `getUsageHistory` · `getUsageRange` · `getUsageBreakdown` · `getRunHistory` · `getBilling` · `getTracesSummary` · `getRecentTraces` · `getLogs` · `getProject` · `updateProject` |
 | Utilities | `extractJson` (structured JSON from prose, schema-shaped) · `synthesizeSpeech` (short TTS clip in a catalog voice, base64 mp3) |
 | Escape hatch | `request(method, path, body?)` — any endpoint not yet typed |
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.41.0";
+export declare const ADMIN_SDK_VERSION = "0.43.0";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1/admin";
 /** Deadline for the routes whose server handler declares `maxDuration: 300` —
  *  the server's own ceiling plus headroom, so a client abort can only ever mean
@@ -373,8 +373,151 @@ export interface MonthUsageHistoryEntry {
     mau: number;
     mauTest: number;
     sessions: number;
+    /** 0.42.0 (admin API 1.19.0): credits charged that month. Absent from an
+     *  older server. */
+    credits?: number;
     [k: string]: unknown;
 }
+/** 0.43.0 (admin API 1.20.0) — the period reads. A period is `from` / `to`,
+ *  inclusive days "YYYY-MM-DD", at most 366 days; a day after today is clamped
+ *  (`clampedTo`). A bad period is a 400; a storage fault a 503 — never zeros. */
+export type UsagePeriodParams = {
+    from: string;
+    to: string;
+};
+export interface UsageDay {
+    date: string;
+    /** Live sessions started that day. */
+    sessions: number;
+    /** Live users whose FIRST activity that month fell on this day — NOT
+     *  distinct users across a period (see `UsageRange.distinct`). */
+    activations: number;
+    /** Tokens in + out, test instances included. */
+    tokens: number;
+    credits: number;
+    /** `tz` only: no complete hour data covers this local day, so these are the
+     *  numbers of the UTC day with the same date. */
+    utcFallback?: boolean;
+}
+export interface UsageRange {
+    from: string;
+    to: string;
+    clampedTo: boolean;
+    /** The zone the days are cut in. */
+    timezone: string;
+    /** The zone has a non-whole-hour offset: day edges are off by up to 45 min. */
+    approximate?: boolean;
+    days: UsageDay[];
+    totals: {
+        sessions: number;
+        activations: number;
+        tokens: number;
+        credits: number;
+    };
+    /** The same-length period immediately before — the comparison base. */
+    previous: {
+        from: string;
+        to: string;
+        totals: {
+            sessions: number;
+            activations: number;
+            tokens: number;
+            credits: number;
+        };
+    };
+    /** Whole UTC (billing) months the period touches; `partial` when it cuts one.
+     *  `mau` is the exact distinct figure for that month. */
+    months: Array<{
+        month: string;
+        mau: number;
+        mauTest: number;
+        sessions: number;
+        tokensIn: number;
+        tokensOut: number;
+        credits: number;
+        partial: boolean;
+    }>;
+    /** ≈ distinct live users over the period (HyperLogLog, UTC days). Absent when
+     *  the sketches could not be read. `complete: false` = a lower bound. */
+    distinct?: {
+        estimate: number;
+        relativeError: number;
+        complete: boolean;
+        /** ≈ daily active users — periods up to 92 days only. */
+        byDay?: Array<{
+            date: string;
+            estimate: number;
+        }>;
+    };
+}
+export interface UsageSliceRow {
+    key: string;
+    tokensIn: number;
+    tokensOut: number;
+    calls: number;
+    /** Share of the period's `totalTokens`, 0..1. */
+    share: number;
+}
+export interface UsageBreakdown {
+    from: string;
+    to: string;
+    timezone: 'UTC';
+    totalTokens: number;
+    /** Tagged ancillary stages. Every row is a SLICE of `totalTokens`. */
+    byTag: UsageSliceRow[];
+    /** Tokens in no tagged stage — the main conversation turns. */
+    untaggedTokens: number;
+    /** By experience (environment id); `name` while the world still exists. */
+    byWorld: Array<UsageSliceRow & {
+        name?: string;
+    }>;
+    nonWorldTokens: number;
+    /** `incomplete` = that month's per-day maps do not cover it, so the
+     *  remainders are upper bounds there. */
+    months: Array<{
+        month: string;
+        tag: 'month' | 'daily' | 'incomplete';
+        world: 'month' | 'daily' | 'incomplete';
+    }>;
+}
+export interface RunHistorySummary {
+    runs: number;
+    errors: number;
+    okRate: number;
+    avgMs: number;
+    /** Upper edge of the latency bucket the percentile falls in; `null` = above
+     *  120 s. Not an exact value (`latencyApprox`). */
+    p50Ms: number | null;
+    p95Ms: number | null;
+    p99Ms: number | null;
+    tokensIn: number;
+    tokensOut: number;
+    tokensCached: number;
+    byTrigger: Record<string, number>;
+}
+export interface RunHistory {
+    from: string;
+    to: string;
+    clampedTo: boolean;
+    timezone: 'UTC';
+    latencyApprox: true;
+    overall: RunHistorySummary;
+    /** `agentId` / `name` present while the agent still exists. */
+    agents: Array<RunHistorySummary & {
+        key: string;
+        agentId?: string;
+        name?: string;
+    }>;
+    days: Array<{
+        date: string;
+        runs: number;
+        errors: number;
+        p95Ms: number | null;
+        tokens: number;
+    }>;
+    /** Days with live sessions but no rollup — their runs are missing above. */
+    uncoveredDays: string[];
+}
 export interface AuditRow {
     at: string;
     type: string;
@@ -1439,6 +1582,17 @@ export interface AdminClient {
         months: MonthUsageHistoryEntry[];
         scope: 'account' | 'project';
     }>;
+    /** 0.43.0: usage over any period up to 366 days, day by day, with the
+     *  previous period and a distinct-user estimate. `tz` (an IANA zone) cuts
+     *  the days in that zone. */
+    getUsageRange(params: UsagePeriodParams & {
+        tz?: string;
+    }): Promise<UsageRange>;
+    /** 0.43.0: where a period's tokens went — by stage and by experience. */
+    getUsageBreakdown(params: UsagePeriodParams): Promise<UsageBreakdown>;
+    /** 0.43.0: run history from daily rollups, past the 30-day trace retention.
+     *  Percentiles are bucket upper edges. */
+    getRunHistory(params: UsagePeriodParams): Promise<RunHistory>;
     getBilling(): Promise<{
         billing: {
             plan: string;
@@ -1461,12 +1615,21 @@ export interface AdminClient {
     getRecentTraces(params?: {
         agentId?: string;
         sinceHours?: number;
+        /** 0.42.0 (admin API 1.19.0): a custom window by UTC day, inclusive,
+         *  both required together. Run traces are kept 30 days, so `from` must
+         *  fall within the last 30 UTC days — older is a 400, not an empty list.
+         *  `sinceHours` is ignored when these are given. */
+        from?: string;
+        to?: string;
         errorsOnly?: boolean;
         limit?: number;
     }): Promise<{
         sinceHours: number;
+        /** `untilMs` (exclusive) is present only on a custom window ending
+         *  before now. */
         window: {
             sinceMs: number;
+            untilMs?: number;
         };
         degraded: false | 'index' | 'error';
         traces: RecentTrace[];

package/dist/index.js

@@ -8,7 +8,7 @@
 //   import { createAdminClient } from '@pouchy_ai/admin-sdk';
 //   const admin = createAdminClient({ adminKey: process.env.POUCHY_ADMIN_KEY! });
 //   const { agents } = await admin.listAgents();
-export const ADMIN_SDK_VERSION = '0.41.0';
+export const ADMIN_SDK_VERSION = '0.43.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1/admin';
 /** Default per-request timeout (ms). A hung upstream otherwise never rejects. */
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -400,6 +400,9 @@ export function createAdminClient(opts) {
         redeliverWebhook: (id) => request('POST', `/webhooks/deliveries/${encodeURIComponent(id)}/redeliver`),
         getUsage: () => request('GET', '/usage'),
         getUsageHistory: (params = {}) => request('GET', `/usage/history${qs(params)}`),
+        getUsageRange: (params) => request('GET', `/usage/range${qs(params)}`),
+        getUsageBreakdown: (params) => request('GET', `/usage/breakdown${qs(params)}`),
+        getRunHistory: (params) => request('GET', `/health/history${qs(params)}`),
         getBilling: () => request('GET', '/billing'),
         getTracesSummary: (params) => request('GET', `/traces/summary${qs(params)}`),
         getRecentTraces: (params = {}) => request('GET', `/traces/recent${qs({ ...params, errorsOnly: params.errorsOnly ? '1' : undefined })}`),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pouchy_ai/admin-sdk",
-	"version": "0.41.0",
+	"version": "0.43.0",
 	"description": "Typed TypeScript client for the Pouchy Admin API \u2014 manage agents, keys, end users, knowledge, skills, channels, schedules, webhooks and credentials headlessly, with a project Admin key.",
 	"type": "module",
 	"license": "SEE LICENSE IN LICENSE",