@pouchy_ai/admin-sdk 0.14.0 → 0.15.1

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.15.1 — 2026-08-03
+
+- **Docs fix: `MonthUsage.mauLimit` prescribed a call that does not compile.**
+  0.15.0 documented the account-scope workaround as
+  `getUsageHistory({ scope: 'account' })`. `scope` is a **response**
+  discriminant the server decides — `GET /usage/history` reads only `months` —
+  so the literal fails excess-property checking against the method's own
+  declared `{ months?: number }`, and casting past it just appends a query
+  parameter nothing reads. The advice is now the call that works: invoke
+  `getUsageHistory()` and read the returned `scope`, which is `'account'`
+  whenever the server can resolve one and `'project'` when it cannot. Note the
+  consequence the old wording hid — there is no way to *force* account scope, so
+  a `'project'` series on a multi-project account carries the same
+  understatement as `mau` itself.
+
+  No type or runtime change; every 0.15.0 signature is unchanged.
+
+  A drift gate now checks every documented `method({ key … })` example in the
+  source and the README against the keys that method actually declares, so the
+  next piece of prose that outruns the surface fails a merge.
+
+## 0.15.0 — 2026-08-03
+
+- **`MonthUsage` now types the whole meter, including credits and voice.** The
+  interface declared six fields (`month`, `mau`, `mauLimit`, `sessions`,
+  `tokensIn`, `tokensOut`) while `GET /usage` returns sixteen. The rest fell
+  through the `[k: string]: unknown` index signature, so they were reachable but
+  typed `unknown` — `usage.credits > limit` did not compile, and reading the
+  product's metered units from the typed client required a cast. Newly declared:
+  - `credits`, `creditsByDay`, `creditLimit` — the per-turn credit meter;
+  - `creditsVoice`, `voiceMs`, `voiceCalls` — the realtime-voice slice of
+    `credits` and the measured minutes behind it. Voice is the most expensive
+    metered unit, so this is the split worth alerting on;
+  - `mauTest`, `sessionsByDay`, `mauByDay`, `tokensByDay` — the test-key MAU
+    count and the per-day chart buckets.
+
+  Additive and backwards-compatible: the index signature is retained, and every
+  new field is optional so the package stays honest against a deployment that
+  predates one. No runtime change — this release is types and docs only.
+
+  A drift gate now pins the interface against the server's usage reader, so the
+  next field added server-side cannot silently skip the package again.
+
 ## 0.14.0 — 2026-08-02
 
 - **Channel provider registration is now typed.** The server registers

package/README.md

@@ -37,9 +37,12 @@ await admin.updateAgent(agent.agentId, { status: 'published' });
 const { key } = await admin.createKey({ label: 'prod-backend', env: 'live' });
 console.log(key); // the plaintext token — shown ONCE
 
-// Read this month's usage
+// Read this month's usage — MAU, tokens, and the credit meter (all typed)
 const { usage } = await admin.getUsage();
 console.log(usage.mau, '/', usage.mauLimit, 'MAU');
+console.log(usage.credits, '/', usage.creditLimit, 'credits');
+// Voice is the priciest metered unit — watch its slice, not just the total
+console.log(usage.creditsVoice, 'of those credits were', usage.voiceCalls, 'voice calls');
 
 // Equip an agent with ANY skill — including a docs-only skill.md that has no
 // `tools:` block — entirely via the API:

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.14.0";
+export declare const ADMIN_SDK_VERSION = "0.15.1";
 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
@@ -211,13 +211,59 @@ export interface Instance {
     lastActiveAt: string;
     suspended?: boolean;
 }
+/** The current month's meter, as `GET /usage` returns it.
+ *
+ *  Every field the server sends is declared. The index signature stays for
+ *  forward compatibility with a newer server, but it is a fallback, not the
+ *  contract: reaching a field THROUGH it yields `unknown`, so
+ *  `usage.credits > limit` does not compile and an integrator has to cast — the
+ *  same untyped-surface friction the channel-provisioning gap caused. The
+ *  credit/voice fields below are the ones that bit: they are the product's
+ *  metered units, and they shipped server-side (and in the OpenAPI) while this
+ *  interface still described only MAU and tokens.
+ *
+ *  All but `month` are optional so the package stays honest against an OLDER
+ *  deployment that predates a field — a self-hosted server on a prior release
+ *  really can omit the voice trio, and typing them as required would be the
+ *  package asserting something it cannot know. */
 export interface MonthUsage {
     month: string;
     mau: number;
+    /** Sessions minted by TEST keys — metered but never gated. */
+    mauTest?: number;
+    /** The plan's monthly MAU cap. ACCOUNT-scoped (pooled across the owner's
+     *  projects) while `mau` above is this project's slice, so `mau / mauLimit`
+     *  understates consumption on a multi-project account.
+     *
+     *  For the number the mint gate actually enforces, call `getUsageHistory()`
+     *  and READ its `scope`: the server pools across the account whenever it can
+     *  resolve one and answers `scope: 'account'`, falling back to this project's
+     *  own slice (`'project'`) when it cannot. `scope` is a response
+     *  discriminant, not a request option — there is no parameter that forces
+     *  account scope, so a series that comes back `'project'` on a multi-project
+     *  account means the account could not be resolved, and comparing it against
+     *  `mauLimit` has the same understatement as `mau` does. */
     mauLimit: number;
     sessions: number;
     tokensIn: number;
     tokensOut: number;
+    /** Per-UTC-day buckets, `{ 'YYYY-MM-DD': n }` — for charts. */
+    sessionsByDay?: Record<string, number>;
+    mauByDay?: Record<string, number>;
+    tokensByDay?: Record<string, number>;
+    creditsByDay?: Record<string, number>;
+    /** Credits consumed this month: one per completed standard turn, the Pro
+     *  multiplier per Pro turn, and the per-minute rate for realtime voice. */
+    credits?: number;
+    /** The VOICE slice of `credits`, and the measured minutes it came from.
+     *  Project-scoped: the pooled account counter carries no per-source
+     *  breakdown. Voice is by far the most expensive metered unit, so this is
+     *  the split to watch before a bill surprises anyone. */
+    creditsVoice?: number;
+    voiceMs?: number;
+    voiceCalls?: number;
+    /** The plan's monthly credit allowance (account-level, like `mauLimit`). */
+    creditLimit?: number;
     [k: string]: unknown;
 }
 /** One month of the usage-history series. Unlike `MonthUsage` (the current

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.14.0';
+export const ADMIN_SDK_VERSION = '0.15.1';
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/admin-sdk",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "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",