@nodaro/sdk 2.47.0 → 2.51.0

package/dist/entries/client.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkNP6KDFIJ_cjs = require('../chunk-NP6KDFIJ.cjs');
+var chunkHPSENMVN_cjs = require('../chunk-HPSENMVN.cjs');
 require('../chunk-JTOEHQQJ.cjs');
 require('../chunk-W5VHATSR.cjs');
 require('../chunk-R63TTR35.cjs');
@@ -12,8 +12,8 @@ require('../chunk-WMT7HEBZ.cjs');
 require('../chunk-MBFUMWI5.cjs');
 require('../chunk-NKH2UFSD.cjs');
 require('../chunk-UIBYZNDR.cjs');
-require('../chunk-XKDVEQVD.cjs');
-require('../chunk-DIF7A5OH.cjs');
+require('../chunk-LTZKNAXM.cjs');
+require('../chunk-E5MJK3W5.cjs');
 require('../chunk-KMNSPC72.cjs');
 require('../chunk-NBVARNVA.cjs');
 require('../chunk-7YHIFCJ4.cjs');
@@ -26,7 +26,7 @@ require('../chunk-SYVNY3AH.cjs');
 require('../chunk-22P4X3N5.cjs');
 require('../chunk-7QOCWJKD.cjs');
 require('../chunk-ZCWKX4V6.cjs');
-require('../chunk-34PU2DAT.cjs');
+require('../chunk-Q45PC4YD.cjs');
 require('../chunk-TK2CEVSK.cjs');
 require('../chunk-GVIFLUYZ.cjs');
 require('../chunk-CR5E2SF3.cjs');
@@ -34,7 +34,7 @@ require('../chunk-J5LGGCAS.cjs');
 require('../chunk-SF2CMKWA.cjs');
 require('../chunk-SBV5MWEL.cjs');
 require('../chunk-WUKIJJG2.cjs');
-require('../chunk-7LTVS75S.cjs');
+require('../chunk-P6AM42UB.cjs');
 require('../chunk-2DZWWIJ4.cjs');
 require('../chunk-SS3B6PHT.cjs');
 require('../chunk-MQ74AKA2.cjs');
@@ -43,15 +43,15 @@ require('../chunk-43FVH6LJ.cjs');
 require('../chunk-YFS2LMG4.cjs');
 require('../chunk-OSMKIRKI.cjs');
 require('../chunk-FRQJNGJS.cjs');
-var chunkMYTMNPCP_cjs = require('../chunk-MYTMNPCP.cjs');
+var chunkOMX7JBGY_cjs = require('../chunk-OMX7JBGY.cjs');
 require('../chunk-FM2KM5TY.cjs');
 require('../chunk-HGCVWOGK.cjs');
-require('../chunk-FIMBPKIH.cjs');
+require('../chunk-4BAHF762.cjs');
 require('../chunk-A3S55XGF.cjs');
 require('../chunk-JOXZ4ZIF.cjs');
 require('../chunk-GA4LZZKQ.cjs');
-require('../chunk-NGKODS3J.cjs');
-require('../chunk-GDDV5U32.cjs');
+require('../chunk-6FZN3QQO.cjs');
+require('../chunk-TY2S25W5.cjs');
 require('../chunk-BPWUWUZ3.cjs');
 require('../chunk-HAKYPZLB.cjs');
 
@@ -59,23 +59,23 @@ require('../chunk-HAKYPZLB.cjs');
 
 Object.defineProperty(exports, "NodaroClient", {
   enumerable: true,
-  get: function () { return chunkNP6KDFIJ_cjs.NodaroClient; }
+  get: function () { return chunkHPSENMVN_cjs.NodaroClient; }
 });
 Object.defineProperty(exports, "createClient", {
   enumerable: true,
-  get: function () { return chunkNP6KDFIJ_cjs.createClient; }
+  get: function () { return chunkHPSENMVN_cjs.createClient; }
 });
 Object.defineProperty(exports, "CallbackAuth", {
   enumerable: true,
-  get: function () { return chunkMYTMNPCP_cjs.CallbackAuth; }
+  get: function () { return chunkOMX7JBGY_cjs.CallbackAuth; }
 });
 Object.defineProperty(exports, "StaticTokenAuth", {
   enumerable: true,
-  get: function () { return chunkMYTMNPCP_cjs.StaticTokenAuth; }
+  get: function () { return chunkOMX7JBGY_cjs.StaticTokenAuth; }
 });
 Object.defineProperty(exports, "supabaseAuth", {
   enumerable: true,
-  get: function () { return chunkMYTMNPCP_cjs.supabaseAuth; }
+  get: function () { return chunkOMX7JBGY_cjs.supabaseAuth; }
 });
 //# sourceMappingURL=client.cjs.map
 //# sourceMappingURL=client.cjs.map

package/dist/entries/client.js

@@ -1,4 +1,4 @@
-export { NodaroClient, createClient } from '../chunk-I7AHLDXV.js';
+export { NodaroClient, createClient } from '../chunk-EC6MC46Y.js';
 import '../chunk-WY4QRJZW.js';
 import '../chunk-ERLXU47J.js';
 import '../chunk-T7N7DFQJ.js';
@@ -10,8 +10,8 @@ import '../chunk-WS4ZQ4AA.js';
 import '../chunk-WVFAQBS7.js';
 import '../chunk-AUKHMT53.js';
 import '../chunk-M7VSFZMV.js';
-import '../chunk-KBHDUHKM.js';
-import '../chunk-XILR6TFO.js';
+import '../chunk-2SQ7V6EX.js';
+import '../chunk-YXVMQEJX.js';
 import '../chunk-HPXE3NZW.js';
 import '../chunk-WEQWU2IC.js';
 import '../chunk-KFZOJBI5.js';
@@ -24,7 +24,7 @@ import '../chunk-NCCBS6GU.js';
 import '../chunk-BQAW4RX2.js';
 import '../chunk-Y6V6CBY5.js';
 import '../chunk-YVU2M7MI.js';
-import '../chunk-JTAW54UM.js';
+import '../chunk-AEUPH7EE.js';
 import '../chunk-GW76IRQD.js';
 import '../chunk-Z7LGWNI7.js';
 import '../chunk-7LSFG2AF.js';
@@ -32,7 +32,7 @@ import '../chunk-ALSLZG3U.js';
 import '../chunk-RBX3QTKB.js';
 import '../chunk-Z3ZKFI2M.js';
 import '../chunk-JDEZHITT.js';
-import '../chunk-PQHZUWSL.js';
+import '../chunk-THLTFB6I.js';
 import '../chunk-P6E4QDJN.js';
 import '../chunk-E37CVHWW.js';
 import '../chunk-TVENC6PH.js';
@@ -41,15 +41,15 @@ import '../chunk-SFB4YLCS.js';
 import '../chunk-BU5A6K4C.js';
 import '../chunk-D2ILCSOQ.js';
 import '../chunk-7CUWAVWB.js';
-export { CallbackAuth, StaticTokenAuth, supabaseAuth } from '../chunk-FCYN4N3M.js';
+export { CallbackAuth, StaticTokenAuth, supabaseAuth } from '../chunk-XISHBW5I.js';
 import '../chunk-L6T44A3G.js';
 import '../chunk-CK3AMMSC.js';
-import '../chunk-5MOJSYHI.js';
+import '../chunk-7QK2NXJA.js';
 import '../chunk-65E3JBFZ.js';
 import '../chunk-7LODCIQK.js';
 import '../chunk-3QFTP5P5.js';
-import '../chunk-J4WFSKY6.js';
-import '../chunk-OWG3XAHQ.js';
+import '../chunk-WYYDWJFF.js';
+import '../chunk-OCRUDBPG.js';
 import '../chunk-KG4R454Z.js';
 import '../chunk-EJSGJDZY.js';
 //# sourceMappingURL=client.js.map

package/dist/entries/core.cjs

@@ -1,26 +1,26 @@
 'use strict';
 
 require('../chunk-X7XP5WBP.cjs');
-var chunkMYTMNPCP_cjs = require('../chunk-MYTMNPCP.cjs');
+var chunkOMX7JBGY_cjs = require('../chunk-OMX7JBGY.cjs');
 require('../chunk-FM2KM5TY.cjs');
 
 
 
 Object.defineProperty(exports, "CallbackAuth", {
   enumerable: true,
-  get: function () { return chunkMYTMNPCP_cjs.CallbackAuth; }
+  get: function () { return chunkOMX7JBGY_cjs.CallbackAuth; }
 });
 Object.defineProperty(exports, "NodaroClientCore", {
   enumerable: true,
-  get: function () { return chunkMYTMNPCP_cjs.NodaroClientCore; }
+  get: function () { return chunkOMX7JBGY_cjs.NodaroClientCore; }
 });
 Object.defineProperty(exports, "StaticTokenAuth", {
   enumerable: true,
-  get: function () { return chunkMYTMNPCP_cjs.StaticTokenAuth; }
+  get: function () { return chunkOMX7JBGY_cjs.StaticTokenAuth; }
 });
 Object.defineProperty(exports, "supabaseAuth", {
   enumerable: true,
-  get: function () { return chunkMYTMNPCP_cjs.supabaseAuth; }
+  get: function () { return chunkOMX7JBGY_cjs.supabaseAuth; }
 });
 //# sourceMappingURL=core.cjs.map
 //# sourceMappingURL=core.cjs.map

package/dist/entries/core.js

@@ -1,5 +1,5 @@
 import '../chunk-AUDHV3OE.js';
-export { CallbackAuth, NodaroClientCore, StaticTokenAuth, supabaseAuth } from '../chunk-FCYN4N3M.js';
+export { CallbackAuth, NodaroClientCore, StaticTokenAuth, supabaseAuth } from '../chunk-XISHBW5I.js';
 import '../chunk-L6T44A3G.js';
 //# sourceMappingURL=core.js.map
 //# sourceMappingURL=core.js.map

package/dist/entries/credits.cjs

@@ -1,13 +1,13 @@
 'use strict';
 
 require('../chunk-ALUUBPDG.cjs');
-var chunkFIMBPKIH_cjs = require('../chunk-FIMBPKIH.cjs');
+var chunk4BAHF762_cjs = require('../chunk-4BAHF762.cjs');
 
 
 
 Object.defineProperty(exports, "CreditsResource", {
   enumerable: true,
-  get: function () { return chunkFIMBPKIH_cjs.CreditsResource; }
+  get: function () { return chunk4BAHF762_cjs.CreditsResource; }
 });
 //# sourceMappingURL=credits.cjs.map
 //# sourceMappingURL=credits.cjs.map

package/dist/entries/credits.d.cts

@@ -202,6 +202,157 @@ interface CreditTransactionsOptions {
     /** The `nextCursor` of the previous page. */
     cursor?: string;
 }
+/** How `credits.usageSummary()` groups the series over time. */
+type UsageSummaryBucket = "day" | "week" | "month";
+interface UsageSummaryOptions {
+    /** An ISO-8601 timestamp, or a date alone (`"2026-10-01"`: that whole UTC day), inclusive; default the last 30 days up to now. A period of at most a year. */
+    from?: string;
+    to?: string;
+    /** Default `"day"`. Buckets are UTC. */
+    bucket?: UsageSummaryBucket;
+}
+interface UsageSummaryTotals {
+    /** Credits spent on runs in the period: each run's charge (a running hold counts; a refunded run does not). */
+    used: number;
+    /** Credits bought: packs, loads, subscription grants. */
+    purchased: number;
+    /** Credits granted free, net: sign-up and admin adjustments, a grant taken back subtracted. */
+    granted: number;
+    /** Credits given back for a refunded run or by Stripe (a hold released when a run settled below it is not a refund). */
+    refunded: number;
+    /** Runs that were charged or are still running. */
+    runs: number;
+    /** `used / runs`, one decimal; 0 with no runs. */
+    avgPerRun: number;
+}
+interface UsageByModel {
+    model: string;
+    provider: string | null;
+    credits: number;
+    runs: number;
+    /** Of `totals.used`, 0–1. */
+    share: number;
+}
+interface UsageByCategory {
+    /** `"image"`, `"video"`, `"audio"` or `"other"`. */
+    category: string;
+    credits: number;
+    runs: number;
+}
+interface UsageOverTime {
+    /** The bucket's first day in UTC (`"2026-10-26"`; a week by its Monday; a month as `"2026-10"`). The first bucket of a period may be a partial week or month. */
+    bucket: string;
+    used: number;
+    purchased: number;
+    runs: number;
+}
+/** The spend of one session or one workflow. */
+interface UsageByGroup {
+    id: string;
+    /** The session's title or the workflow's name; `null` when it has none or is gone. */
+    name: string | null;
+    /** The tool the session belongs to; `null` on a workflow. */
+    tool: string | null;
+    credits: number;
+    runs: number;
+    /** The models used, by spend. */
+    models: string[];
+    /** ISO-8601: the latest run. */
+    lastAt: string;
+}
+/** The answer of `credits.usageSummary()`. */
+interface UsageSummary {
+    period: {
+        from: string;
+        to: string;
+        bucket: UsageSummaryBucket;
+    };
+    totals: UsageSummaryTotals;
+    /** The model with the most spend; `null` with no runs. */
+    mostUsed: UsageByModel | null;
+    /** By spend. */
+    byModel: UsageByModel[];
+    byCategory: UsageByCategory[];
+    /** Every bucket of the period, empty ones included, oldest first. */
+    overTime: UsageOverTime[];
+    bySession: UsageByGroup[];
+    byWorkflow: UsageByGroup[];
+    /** A read hit the server's row cap: the figures under-report; narrow the period. */
+    truncated: boolean;
+    /** A side read failed on the server (the jobs, or a session's or workflow's name): a grouping is missing or unnamed; the totals are whole. */
+    partial: boolean;
+}
+/** What a movement of the balance was; `app` is credits earned from, or paid for, a published app. */
+type CreditHistoryKind = "usage" | "purchase" | "grant" | "refund" | "app" | "adjustment" | "expiry";
+/** The job behind a usage row of {@link CreditHistoryEntry}. */
+interface CreditHistoryJob {
+    id: string;
+    /** The node type that ran (`generate-image`, `image-to-video`, …); `null` when the job is gone. */
+    type: string | null;
+    status: string | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    /** From start to completion; `null` until it completes. */
+    durationMs: number | null;
+    workflowId: string | null;
+    sessionId: string | null;
+}
+/** One movement of the balance (`credits.history()`). */
+interface CreditHistoryEntry {
+    id: string;
+    /** ISO-8601. Also the paging cursor. */
+    at: string;
+    kind: CreditHistoryKind;
+    /** The ledger's own word: `usage`, `one_time_purchase`, `subscription_renewal`, `signup_grant`, `refund`, `admin_adjustment`, `expiry`, … */
+    source: string;
+    /** The movement, signed: a run's hold negative, a purchase positive. */
+    amount: number;
+    /** The balance right after this movement. */
+    balanceAfter: number;
+    /** Which pool moved; `"mixed"` when both did. */
+    pool: "subscription" | "topup" | "mixed";
+    description: string | null;
+    /** The model that ran, on a row with a job; `null` otherwise. */
+    model: string | null;
+    provider: string | null;
+    /**
+     * The job's charge, on its reserve row only (the hold taken when the run
+     * was accepted): the settled charge, the hold while the run is open, `0`
+     * once refunded. `null` on every other row — a refund, a metered overrun
+     * line, a purchase — so summing it over a list counts each job once. Read
+     * this for spend, not `amount`.
+     */
+    charge: number | null;
+    /** The run's credit status (`"reserved"`, `"committed"` or `"refunded"`), beside `charge`; `null` elsewhere. */
+    status: string | null;
+    /** On a row with a job; `type` and the rest `null` when the job is gone or not the person's. */
+    job: CreditHistoryJob | null;
+    /** Stripe's hosted receipt, on a purchase that has one. */
+    receiptUrl: string | null;
+}
+/** A page of {@link CreditHistoryEntry}, newest first. */
+interface CreditHistoryPage {
+    data: CreditHistoryEntry[];
+    /** Pass as `cursor` for the next page; `null` when there are no more rows. */
+    nextCursor: string | null;
+}
+/** What narrows the history. */
+interface CreditHistoryFilters {
+    kind?: CreditHistoryKind;
+    /** A model identifier: only runs of that model. */
+    model?: string;
+    /** ISO-8601 bounds on `at`, inclusive. */
+    from?: string;
+    to?: string;
+    /** Words looked for in the description, case-insensitively. */
+    q?: string;
+}
+interface CreditHistoryOptions extends CreditHistoryFilters {
+    /** Rows per page, 1–100 (server default 50). */
+    limit?: number;
+    /** The `nextCursor` of the previous page, as given (opaque; another string is refused with 400). */
+    cursor?: string;
+}
 declare class CreditsResource {
     private client;
     constructor(client: NodaroClientCore);
@@ -219,6 +370,33 @@ declare class CreditsResource {
      * Cloud-only route: a self-hosted instance answers 404.
      */
     transactions(options?: CreditTransactionsOptions): Promise<CreditTransactionsPage>;
+    /**
+     * `GET /v1/credits/usage-summary` → the period's credit usage summed the
+     * way a billing screen draws it: totals, the spend by model and by
+     * category, a series over time (`bucket`: day, week or month, no holes),
+     * and the spend by session and by workflow. The last 30 days unless
+     * `from` / `to` say otherwise; a period of at most a year (400 beyond).
+     * Cloud-only route: a self-hosted instance answers 404.
+     */
+    usageSummary(options?: UsageSummaryOptions): Promise<UsageSummary>;
+    /**
+     * `GET /v1/credits/history` → one page of every movement of the balance,
+     * newest first — runs, purchases, grants, refunds, adjustments, expiries —
+     * each with the balance after it; a job's reserve row carries its model,
+     * its `charge` (the settled charge, the hold while the run is open, `0`
+     * once refunded — read that for spend, not `amount`) and its job. Filter by
+     * `kind`, `model`, `from` / `to` and `q`; pass the page's `nextCursor` (an
+     * opaque string) as `cursor` for the next page (`null` at the end).
+     * Cloud-only route: a self-hosted instance answers 404.
+     */
+    history(options?: CreditHistoryOptions): Promise<CreditHistoryPage>;
+    /**
+     * `GET /v1/credits/history?format=csv` → the whole filtered history as a
+     * CSV file (the same fields as {@link history}, one line per movement,
+     * newest first), at most 5,000 rows — the last line says when it was cut.
+     * Hand the text to the person as `credit-history.csv`.
+     */
+    exportHistory(filters?: CreditHistoryFilters): Promise<string>;
     /**
      * `POST /v1/credits/model-costs` → per-identifier credit cost, for editor
      * cost previews. Capped at the first {@link MODEL_COSTS_LIMIT} identifiers
@@ -269,4 +447,4 @@ declare class CreditsResource {
     markWelcomeOfferSeen(): Promise<WelcomeOfferSeenResult>;
 }
 
-export { type CreditTransaction, type CreditTransactionsOptions, type CreditTransactionsPage, CreditsResource, type FreeGrantState, type ModelCostError, type ModelCostResult, type ModelCostsResult, type SignupGrantClaimResult, type SignupKeys, type UserBalance, type WelcomeOfferClaimInput, type WelcomeOfferClaimResult, type WelcomeOfferSeenResult, type WelcomeOfferState };
+export { type CreditHistoryEntry, type CreditHistoryFilters, type CreditHistoryJob, type CreditHistoryKind, type CreditHistoryOptions, type CreditHistoryPage, type CreditTransaction, type CreditTransactionsOptions, type CreditTransactionsPage, CreditsResource, type FreeGrantState, type ModelCostError, type ModelCostResult, type ModelCostsResult, type SignupGrantClaimResult, type SignupKeys, type UsageByCategory, type UsageByGroup, type UsageByModel, type UsageOverTime, type UsageSummary, type UsageSummaryBucket, type UsageSummaryOptions, type UsageSummaryTotals, type UserBalance, type WelcomeOfferClaimInput, type WelcomeOfferClaimResult, type WelcomeOfferSeenResult, type WelcomeOfferState };

package/dist/entries/credits.d.ts

@@ -202,6 +202,157 @@ interface CreditTransactionsOptions {
     /** The `nextCursor` of the previous page. */
     cursor?: string;
 }
+/** How `credits.usageSummary()` groups the series over time. */
+type UsageSummaryBucket = "day" | "week" | "month";
+interface UsageSummaryOptions {
+    /** An ISO-8601 timestamp, or a date alone (`"2026-10-01"`: that whole UTC day), inclusive; default the last 30 days up to now. A period of at most a year. */
+    from?: string;
+    to?: string;
+    /** Default `"day"`. Buckets are UTC. */
+    bucket?: UsageSummaryBucket;
+}
+interface UsageSummaryTotals {
+    /** Credits spent on runs in the period: each run's charge (a running hold counts; a refunded run does not). */
+    used: number;
+    /** Credits bought: packs, loads, subscription grants. */
+    purchased: number;
+    /** Credits granted free, net: sign-up and admin adjustments, a grant taken back subtracted. */
+    granted: number;
+    /** Credits given back for a refunded run or by Stripe (a hold released when a run settled below it is not a refund). */
+    refunded: number;
+    /** Runs that were charged or are still running. */
+    runs: number;
+    /** `used / runs`, one decimal; 0 with no runs. */
+    avgPerRun: number;
+}
+interface UsageByModel {
+    model: string;
+    provider: string | null;
+    credits: number;
+    runs: number;
+    /** Of `totals.used`, 0–1. */
+    share: number;
+}
+interface UsageByCategory {
+    /** `"image"`, `"video"`, `"audio"` or `"other"`. */
+    category: string;
+    credits: number;
+    runs: number;
+}
+interface UsageOverTime {
+    /** The bucket's first day in UTC (`"2026-10-26"`; a week by its Monday; a month as `"2026-10"`). The first bucket of a period may be a partial week or month. */
+    bucket: string;
+    used: number;
+    purchased: number;
+    runs: number;
+}
+/** The spend of one session or one workflow. */
+interface UsageByGroup {
+    id: string;
+    /** The session's title or the workflow's name; `null` when it has none or is gone. */
+    name: string | null;
+    /** The tool the session belongs to; `null` on a workflow. */
+    tool: string | null;
+    credits: number;
+    runs: number;
+    /** The models used, by spend. */
+    models: string[];
+    /** ISO-8601: the latest run. */
+    lastAt: string;
+}
+/** The answer of `credits.usageSummary()`. */
+interface UsageSummary {
+    period: {
+        from: string;
+        to: string;
+        bucket: UsageSummaryBucket;
+    };
+    totals: UsageSummaryTotals;
+    /** The model with the most spend; `null` with no runs. */
+    mostUsed: UsageByModel | null;
+    /** By spend. */
+    byModel: UsageByModel[];
+    byCategory: UsageByCategory[];
+    /** Every bucket of the period, empty ones included, oldest first. */
+    overTime: UsageOverTime[];
+    bySession: UsageByGroup[];
+    byWorkflow: UsageByGroup[];
+    /** A read hit the server's row cap: the figures under-report; narrow the period. */
+    truncated: boolean;
+    /** A side read failed on the server (the jobs, or a session's or workflow's name): a grouping is missing or unnamed; the totals are whole. */
+    partial: boolean;
+}
+/** What a movement of the balance was; `app` is credits earned from, or paid for, a published app. */
+type CreditHistoryKind = "usage" | "purchase" | "grant" | "refund" | "app" | "adjustment" | "expiry";
+/** The job behind a usage row of {@link CreditHistoryEntry}. */
+interface CreditHistoryJob {
+    id: string;
+    /** The node type that ran (`generate-image`, `image-to-video`, …); `null` when the job is gone. */
+    type: string | null;
+    status: string | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    /** From start to completion; `null` until it completes. */
+    durationMs: number | null;
+    workflowId: string | null;
+    sessionId: string | null;
+}
+/** One movement of the balance (`credits.history()`). */
+interface CreditHistoryEntry {
+    id: string;
+    /** ISO-8601. Also the paging cursor. */
+    at: string;
+    kind: CreditHistoryKind;
+    /** The ledger's own word: `usage`, `one_time_purchase`, `subscription_renewal`, `signup_grant`, `refund`, `admin_adjustment`, `expiry`, … */
+    source: string;
+    /** The movement, signed: a run's hold negative, a purchase positive. */
+    amount: number;
+    /** The balance right after this movement. */
+    balanceAfter: number;
+    /** Which pool moved; `"mixed"` when both did. */
+    pool: "subscription" | "topup" | "mixed";
+    description: string | null;
+    /** The model that ran, on a row with a job; `null` otherwise. */
+    model: string | null;
+    provider: string | null;
+    /**
+     * The job's charge, on its reserve row only (the hold taken when the run
+     * was accepted): the settled charge, the hold while the run is open, `0`
+     * once refunded. `null` on every other row — a refund, a metered overrun
+     * line, a purchase — so summing it over a list counts each job once. Read
+     * this for spend, not `amount`.
+     */
+    charge: number | null;
+    /** The run's credit status (`"reserved"`, `"committed"` or `"refunded"`), beside `charge`; `null` elsewhere. */
+    status: string | null;
+    /** On a row with a job; `type` and the rest `null` when the job is gone or not the person's. */
+    job: CreditHistoryJob | null;
+    /** Stripe's hosted receipt, on a purchase that has one. */
+    receiptUrl: string | null;
+}
+/** A page of {@link CreditHistoryEntry}, newest first. */
+interface CreditHistoryPage {
+    data: CreditHistoryEntry[];
+    /** Pass as `cursor` for the next page; `null` when there are no more rows. */
+    nextCursor: string | null;
+}
+/** What narrows the history. */
+interface CreditHistoryFilters {
+    kind?: CreditHistoryKind;
+    /** A model identifier: only runs of that model. */
+    model?: string;
+    /** ISO-8601 bounds on `at`, inclusive. */
+    from?: string;
+    to?: string;
+    /** Words looked for in the description, case-insensitively. */
+    q?: string;
+}
+interface CreditHistoryOptions extends CreditHistoryFilters {
+    /** Rows per page, 1–100 (server default 50). */
+    limit?: number;
+    /** The `nextCursor` of the previous page, as given (opaque; another string is refused with 400). */
+    cursor?: string;
+}
 declare class CreditsResource {
     private client;
     constructor(client: NodaroClientCore);
@@ -219,6 +370,33 @@ declare class CreditsResource {
      * Cloud-only route: a self-hosted instance answers 404.
      */
     transactions(options?: CreditTransactionsOptions): Promise<CreditTransactionsPage>;
+    /**
+     * `GET /v1/credits/usage-summary` → the period's credit usage summed the
+     * way a billing screen draws it: totals, the spend by model and by
+     * category, a series over time (`bucket`: day, week or month, no holes),
+     * and the spend by session and by workflow. The last 30 days unless
+     * `from` / `to` say otherwise; a period of at most a year (400 beyond).
+     * Cloud-only route: a self-hosted instance answers 404.
+     */
+    usageSummary(options?: UsageSummaryOptions): Promise<UsageSummary>;
+    /**
+     * `GET /v1/credits/history` → one page of every movement of the balance,
+     * newest first — runs, purchases, grants, refunds, adjustments, expiries —
+     * each with the balance after it; a job's reserve row carries its model,
+     * its `charge` (the settled charge, the hold while the run is open, `0`
+     * once refunded — read that for spend, not `amount`) and its job. Filter by
+     * `kind`, `model`, `from` / `to` and `q`; pass the page's `nextCursor` (an
+     * opaque string) as `cursor` for the next page (`null` at the end).
+     * Cloud-only route: a self-hosted instance answers 404.
+     */
+    history(options?: CreditHistoryOptions): Promise<CreditHistoryPage>;
+    /**
+     * `GET /v1/credits/history?format=csv` → the whole filtered history as a
+     * CSV file (the same fields as {@link history}, one line per movement,
+     * newest first), at most 5,000 rows — the last line says when it was cut.
+     * Hand the text to the person as `credit-history.csv`.
+     */
+    exportHistory(filters?: CreditHistoryFilters): Promise<string>;
     /**
      * `POST /v1/credits/model-costs` → per-identifier credit cost, for editor
      * cost previews. Capped at the first {@link MODEL_COSTS_LIMIT} identifiers
@@ -269,4 +447,4 @@ declare class CreditsResource {
     markWelcomeOfferSeen(): Promise<WelcomeOfferSeenResult>;
 }
 
-export { type CreditTransaction, type CreditTransactionsOptions, type CreditTransactionsPage, CreditsResource, type FreeGrantState, type ModelCostError, type ModelCostResult, type ModelCostsResult, type SignupGrantClaimResult, type SignupKeys, type UserBalance, type WelcomeOfferClaimInput, type WelcomeOfferClaimResult, type WelcomeOfferSeenResult, type WelcomeOfferState };
+export { type CreditHistoryEntry, type CreditHistoryFilters, type CreditHistoryJob, type CreditHistoryKind, type CreditHistoryOptions, type CreditHistoryPage, type CreditTransaction, type CreditTransactionsOptions, type CreditTransactionsPage, CreditsResource, type FreeGrantState, type ModelCostError, type ModelCostResult, type ModelCostsResult, type SignupGrantClaimResult, type SignupKeys, type UsageByCategory, type UsageByGroup, type UsageByModel, type UsageOverTime, type UsageSummary, type UsageSummaryBucket, type UsageSummaryOptions, type UsageSummaryTotals, type UserBalance, type WelcomeOfferClaimInput, type WelcomeOfferClaimResult, type WelcomeOfferSeenResult, type WelcomeOfferState };

package/dist/entries/credits.js

@@ -1,4 +1,4 @@
 import '../chunk-V4GPQ6Y2.js';
-export { CreditsResource } from '../chunk-5MOJSYHI.js';
+export { CreditsResource } from '../chunk-7QK2NXJA.js';
 //# sourceMappingURL=credits.js.map
 //# sourceMappingURL=credits.js.map

package/dist/entries/jobs.cjs

@@ -1,13 +1,13 @@
 'use strict';
 
 require('../chunk-EHRWTYGR.cjs');
-var chunk7LTVS75S_cjs = require('../chunk-7LTVS75S.cjs');
+var chunkP6AM42UB_cjs = require('../chunk-P6AM42UB.cjs');
 
 
 
 Object.defineProperty(exports, "JobsResource", {
   enumerable: true,
-  get: function () { return chunk7LTVS75S_cjs.JobsResource; }
+  get: function () { return chunkP6AM42UB_cjs.JobsResource; }
 });
 //# sourceMappingURL=jobs.cjs.map
 //# sourceMappingURL=jobs.cjs.map

package/dist/entries/jobs.d.cts

@@ -133,17 +133,28 @@ interface Job {
      *  `usage_logs.status`. `null` when there is no usage log to report. Never
      *  changes the meaning of `credits` (the reserved amount) below. */
     credit_status?: CreditStatus | null;
-    /** The credits HELD when the job was accepted. Never changes — a job can
-     *  settle below it; read {@link Job.credits_charged} for what it cost. */
+    /** The credits the job itself HELD when it was accepted. Never changes — a
+     *  job can settle below it; read {@link Job.credits_charged} for what it cost. */
     credits: number | null;
     /**
-     * What the job actually cost once its hold settled. Can be lower than
-     * `credits` (the unused part goes back to the balance), `0` when the hold was
-     * refunded, `null` while the job is still running or when it reserved
-     * nothing of its own. Sum this — not `credits` — to total spend. Returned by
-     * `get()` and `list()`.
+     * What the job actually cost once its hold settled, INCLUDING the steps it
+     * ran: a job that runs other jobs for you (a Nodaro Motion run's reference
+     * preparation, mask and video) is charged for each, and they are not listed
+     * on their own. A step adds its charge once it settles. Can be lower than
+     * {@link Job.credits_held} (the unused part goes back to the balance). `0`
+     * when the run's own hold was refunded, plus any settled steps (a refunded
+     * Nodaro Motion run whose reference and mask steps committed reads
+     * `credit_status: "refunded"` with `credits_charged: 165`). `null` while the
+     * job's own hold is still open (even when some steps have settled), when
+     * nothing in the run was reserved, or when its steps could not be read for a
+     * moment (unknown — never a lower figure). Sum this — not `credits` — to
+     * total spend. Returned by `get()` and `list()`.
      */
     credits_charged?: number | null;
+    /** The run's hold: the job's own `credits` plus its steps' holds (equals `credits` for a job with no steps). */
+    credits_held?: number | null;
+    /** What went back from `credits_held` once every hold in the run settled; `null` until then. */
+    credits_released?: number | null;
     job_type: string | null;
     created_at: string;
     started_at: string | null;