@pouchy_ai/admin-sdk 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.13.0 — 2026-08-02
+
+- **`getUsageHistory({ months? })`** over `GET /v1/admin/usage/history` —
+  month-over-month `{ months: MonthUsageHistoryEntry[], scope }`, oldest
+  first, quiet months zero-filled. The route shipped with the 1.4.x history
+  work; this closes the package's own "new mirror ⇒ new method" convention
+  gap (a headless operator could read this month but not the history).
+  `scope: 'account'` is the pooled series the plan cap compares;
+  `'project'` is the fallback when the account can't be resolved.
+  `MonthUsageHistoryEntry` is exported.
+
 ## 0.12.0 — 2026-08-01
 
 - **Typed capability declarations.** `publishCapability` now takes a

package/README.md

@@ -200,7 +200,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` · `getBilling` · `getTracesSummary` · `getRecentTraces` · `getLogs` · `getProject` · `updateProject` |
+| Reporting | `getUsage` · `getUsageHistory` · `getBilling` · `getTracesSummary` · `getRecentTraces` · `getLogs` · `getProject` · `updateProject` |
 | Escape hatch | `request(method, path, body?)` — any endpoint not yet typed |
 
 Channel types are checked at compile time: `createChannel` takes a

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.12.0";
+export declare const ADMIN_SDK_VERSION = "0.13.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
@@ -220,6 +220,16 @@ export interface MonthUsage {
     tokensOut: number;
     [k: string]: unknown;
 }
+/** One month of the usage-history series. Unlike `MonthUsage` (the current
+ *  month's full meter incl. day buckets and the cap), history rows are the
+ *  compact per-month rollup the server keeps for every past month. */
+export interface MonthUsageHistoryEntry {
+    month: string;
+    mau: number;
+    mauTest: number;
+    sessions: number;
+    [k: string]: unknown;
+}
 export interface AuditRow {
     at: string;
     type: string;
@@ -670,8 +680,10 @@ export interface AdminClient {
     /** Create a schedule. `externalUserId` and `prompt` are required alongside
      *  `agentId`; the schedule fires by `intervalMinutes` (recurring, >=5) or
      *  `runAt` (one-shot **epoch milliseconds** — an ISO string is silently
-     *  ignored by the server) — there is NO cron field. Returns the stored
-     *  record, whose id lives on `.id`. */
+     *  ignored by the server; must be in the future — a past `runAt` is a 400,
+     *  with a 60s clock-skew grace) — there is NO cron field. A storage outage
+     *  answers 503, not a validation 400. Returns the stored record, whose id
+     *  lives on `.id`. */
     createSchedule(input: {
         agentId: string;
         externalUserId: string;
@@ -918,6 +930,18 @@ export interface AdminClient {
     getUsage(): Promise<{
         usage: MonthUsage;
     }>;
+    /** Month-over-month usage series, oldest first; quiet months zero-fill
+     *  rather than drop. `scope: 'account'` means the pooled account series —
+     *  the figure the plan cap actually compares (a multi-project account's
+     *  pooled number differs from any one project's slice); `'project'` is the
+     *  fallback when the account can't be resolved. */
+    getUsageHistory(params?: {
+        /** Window size in months, clamped server-side to 1..24 (default 12). */
+        months?: number;
+    }): Promise<{
+        months: MonthUsageHistoryEntry[];
+        scope: 'account' | 'project';
+    }>;
     getBilling(): Promise<{
         billing: {
             plan: string;

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.12.0';
+export const ADMIN_SDK_VERSION = '0.13.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;
@@ -302,6 +302,7 @@ export function createAdminClient(opts) {
         testWebhook: (id) => request('POST', `/webhooks/${encodeURIComponent(id)}/test`),
         redeliverWebhook: (id) => request('POST', `/webhooks/deliveries/${encodeURIComponent(id)}/redeliver`),
         getUsage: () => request('GET', '/usage'),
+        getUsageHistory: (params = {}) => request('GET', `/usage/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.12.0",
+  "version": "0.13.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",