agental-sdk 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -344,6 +344,14 @@ An account starts on the free plan: nothing a month, and what it runs is paid fr
344
344
 
345
345
  `setAutoReload(dollars)` has the card saved at the last purchase charged for a top-up of that much, with tax, when the month's credits and the top-ups run out, and the credits added at once, before any sandbox is stopped: at most three times a day, and not again for a day after a card that would not pay. `setAutoReload(null)` turns it off, and `billing().autoReload` says how it is set. It needs a card saved first: `billing().canAutoReload` says whether it can be set, and the call answers `409 no_card` until then.
346
346
 
347
+ ```ts
348
+ const page = await agental.invoices({ limit: 10 });
349
+ for await (const invoice of agental.allInvoices()) console.log(invoice.number, invoice.status, invoice.totalMicros);
350
+ const { card } = await agental.card();
351
+ ```
352
+
353
+ `invoices()` gives the account's invoices from the payment provider, newest first, 25 to a page unless `limit` says otherwise: a plan's months, top-ups and auto-reloads, each with its number, state, what it was for, what it came to in millionths, and its page and PDF (`null` for an admin). Pass a page's `next` as `startingAfter` for the page after it, or let `allInvoices()` read them all. `card()` gives the card the account pays with now: brand, last four, expiry and wallet, or `null` where none is saved.
354
+
347
355
  The free plan makes tiny and small sandboxes, the $100 plan medium ones too, and the $500 and $2000 plans every size: `prices.tiers` lists the plans, and each plan's `sizes` says which. A create, fork or template start of a size the plan does not make throws an `ApiError` with the status 402 and the code `size_not_on_plan`, whose message names the plan that makes it. A sandbox made before a change of plan still starts at its own size.
348
356
 
349
357
  ## How many you run, and how fast you start them
package/dist/client.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { Http, type AgentalOptions } from "./http.js";
2
2
  import { Email, Sandbox, type CreateOptions } from "./sandbox.js";
3
3
  import { Templates } from "./template.js";
4
- import type { AccountEmail, AccountExport, ApiKey, ApiKeyUsage, Billing, Headroom, HeadroomNow, HeadroomRange, Catalog, HostRoute, Invite, Me, Member, Organization, Region, AutoReload, Checkout, DataRetention, CreateApiKey, CreatedApiKey, MetricsAtMoment, Policy, Prices, RunningOverTime, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, Snapshot, Team, TeamRole, Telemetry, TelemetryTest, ClaudeConnection, ClaudeSession, RunsOnRepository, RunsOnRepositories, Usage, Webhook, EgressAccount } from "./types.js";
4
+ import type { AccountEmail, AccountExport, ApiKey, ApiKeyUsage, Billing, Headroom, HeadroomNow, HeadroomRange, Catalog, HostRoute, Invite, Me, Member, Organization, Region, AutoReload, BillingCard, BillingInvoice, BillingInvoices, Checkout, DataRetention, CreateApiKey, CreatedApiKey, MetricsAtMoment, Policy, Prices, RunningOverTime, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, Snapshot, Team, TeamRole, Telemetry, TelemetryTest, ClaudeConnection, ClaudeSession, RunsOnRepository, RunsOnRepositories, Usage, Webhook, EgressAccount } from "./types.js";
5
5
  /** What a list of sandboxes is narrowed to. Each field left out narrows nothing; a list of values is any of them. */
6
6
  export interface SandboxFilter {
7
7
  /** Tags every sandbox has. */
@@ -310,6 +310,21 @@ export declare class Agental {
310
310
  * first, by checkout(): billing().canAutoReload says whether it can be set.
311
311
  */
312
312
  setAutoReload(dollars: number | null): Promise<AutoReload>;
313
+ /**
314
+ * The account's invoices, newest first, read from the payment provider: a plan's months, top-ups
315
+ * and auto-reloads, drafts left out. 25 unless limit says otherwise, 100 at most; pass a page's
316
+ * next as startingAfter for the page after it. An admin is given no pageUrl or pdfUrl.
317
+ */
318
+ invoices(options?: {
319
+ limit?: number;
320
+ startingAfter?: string;
321
+ }): Promise<BillingInvoices>;
322
+ /** Every invoice, newest first, read a page at a time as they are asked for. */
323
+ allInvoices(options?: {
324
+ limit?: number;
325
+ }): AsyncGenerator<BillingInvoice, void, void>;
326
+ /** The card the account pays with now, the one an auto-reload charges: its brand, last four, expiry and wallet, or null where none is saved. */
327
+ card(): Promise<BillingCard>;
313
328
  /** The account's mail: the handle every address of its sandboxes carries, what its plan allows, and what it has had of that today. */
314
329
  email(): Promise<AccountEmail>;
315
330
  /**
package/dist/client.js CHANGED
@@ -426,6 +426,31 @@ export class Agental {
426
426
  async setAutoReload(dollars) {
427
427
  return (await this.http.json({ method: "PUT", path: "/v1/billing/auto-reload", body: { dollars } })).body;
428
428
  }
429
+ /**
430
+ * The account's invoices, newest first, read from the payment provider: a plan's months, top-ups
431
+ * and auto-reloads, drafts left out. 25 unless limit says otherwise, 100 at most; pass a page's
432
+ * next as startingAfter for the page after it. An admin is given no pageUrl or pdfUrl.
433
+ */
434
+ async invoices(options = {}) {
435
+ const query = { limit: options.limit === undefined ? undefined : String(options.limit), startingAfter: options.startingAfter };
436
+ return (await this.http.json({ method: "GET", path: "/v1/billing/invoices", query, replay: true })).body;
437
+ }
438
+ /** Every invoice, newest first, read a page at a time as they are asked for. */
439
+ async *allInvoices(options = {}) {
440
+ let startingAfter;
441
+ for (;;) {
442
+ const page = await this.invoices({ ...options, ...(startingAfter === undefined ? {} : { startingAfter }) });
443
+ yield* page.invoices;
444
+ if (page.next === null) {
445
+ return;
446
+ }
447
+ startingAfter = page.next;
448
+ }
449
+ }
450
+ /** The card the account pays with now, the one an auto-reload charges: its brand, last four, expiry and wallet, or null where none is saved. */
451
+ async card() {
452
+ return (await this.http.json({ method: "GET", path: "/v1/billing/card", replay: true })).body;
453
+ }
429
454
  /** The account's mail: the handle every address of its sandboxes carries, what its plan allows, and what it has had of that today. */
430
455
  async email() {
431
456
  return (await this.http.json({ method: "GET", path: "/v1/email", replay: true })).body;
package/dist/index.d.ts CHANGED
@@ -8,5 +8,5 @@ export { Terminal, TERMINAL_CLOSE, TERMINAL_PROTOCOL } from "./terminal.js";
8
8
  export type { TerminalExit, TerminalOptions, WebSocketConstructor, WebSocketLike } from "./terminal.js";
9
9
  export type { TemplateChanges } from "./template.js";
10
10
  export type { BurstOptions, CommandLine, CreateOptions, DesktopButton, ExecEvent, ExecOptions, SandboxChanges, ScreenshotOptions, SendEmailOptions, StartOptions, StopOptions, WaitOptions } from "./sandbox.js";
11
- export type { AccountEmail, ApiKey, ApiKeyAction, ApiKeyPreset, ApiKeyUsage, Billing, BrowserState, BurstFee, BurstQuote, Headroom, HeadroomNow, HeadroomRange, HeadroomStep, Catalog, Region, AutoReload, Checkout, Command, CreateSchedule, CreateApiKey, CreatedApiKey, DesktopLink, DesktopScreenshot, DesktopState, Egress, EgressAccount, EgressInput, EmailMessage, EmailMessageList, EmailMessageSummary, ExecResult, HiddenVariable, HostRoute, Invite, Me, Member, Organization, MetricsAtMoment, MetricsReading, NetworkRule, Operation, PlainVariable, Plan, Policy, Prices, RunningOverTime, SandboxAutoStop, SandboxEmail, SandboxInfo, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, SandboxMetrics, SandboxNetwork, SandboxNetworkDetail, SandboxOwnNetwork, SandboxStatus, SandboxTemplate, SandboxUsage, Schedule, ScheduleRun, SecretVariable, SendEmail, SetAutoStop, Size, Snapshot, SshKey, SshState, UpdateSchedule, Team, TeamRole, Telemetry, DataRetention, AccountExport, TelemetryTest, ClaudeConnection, ClaudeSession, RunsOnRepository, RunsOnRepositories, TemplateApplied, TemplateInfo, TemplateNetwork, TemplateSandbox, TemplateStart, TemplateSsh, Usage, Webhook, WebhookDelivery, } from "./types.js";
11
+ export type { AccountEmail, ApiKey, ApiKeyAction, ApiKeyPreset, ApiKeyUsage, Billing, BrowserState, BurstFee, BurstQuote, Headroom, HeadroomNow, HeadroomRange, HeadroomStep, Catalog, Region, AutoReload, BillingCard, BillingInvoice, BillingInvoices, Checkout, Command, CreateSchedule, CreateApiKey, CreatedApiKey, DesktopLink, DesktopScreenshot, DesktopState, Egress, EgressAccount, EgressInput, EmailMessage, EmailMessageList, EmailMessageSummary, ExecResult, HiddenVariable, HostRoute, Invite, Me, Member, Organization, MetricsAtMoment, MetricsReading, NetworkRule, Operation, PlainVariable, Plan, Policy, Prices, RunningOverTime, SandboxAutoStop, SandboxEmail, SandboxInfo, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, SandboxMetrics, SandboxNetwork, SandboxNetworkDetail, SandboxOwnNetwork, SandboxStatus, SandboxTemplate, SandboxUsage, Schedule, ScheduleRun, SecretVariable, SendEmail, SetAutoStop, Size, Snapshot, SshKey, SshState, UpdateSchedule, Team, TeamRole, Telemetry, DataRetention, AccountExport, TelemetryTest, ClaudeConnection, ClaudeSession, RunsOnRepository, RunsOnRepositories, TemplateApplied, TemplateInfo, TemplateNetwork, TemplateSandbox, TemplateStart, TemplateSsh, Usage, Webhook, WebhookDelivery, } from "./types.js";
12
12
  export { verifyWebhook } from "./webhooks.js";
package/dist/openapi.d.ts CHANGED
@@ -2304,6 +2304,38 @@ export interface paths {
2304
2304
  patch?: never;
2305
2305
  trace?: never;
2306
2306
  };
2307
+ "/v1/billing/invoices": {
2308
+ parameters: {
2309
+ query?: never;
2310
+ header?: never;
2311
+ path?: never;
2312
+ cookie?: never;
2313
+ };
2314
+ get: operations["listBillingInvoices"];
2315
+ put?: never;
2316
+ post?: never;
2317
+ delete?: never;
2318
+ options?: never;
2319
+ head?: never;
2320
+ patch?: never;
2321
+ trace?: never;
2322
+ };
2323
+ "/v1/billing/card": {
2324
+ parameters: {
2325
+ query?: never;
2326
+ header?: never;
2327
+ path?: never;
2328
+ cookie?: never;
2329
+ };
2330
+ get: operations["getBillingCard"];
2331
+ put?: never;
2332
+ post?: never;
2333
+ delete?: never;
2334
+ options?: never;
2335
+ head?: never;
2336
+ patch?: never;
2337
+ trace?: never;
2338
+ };
2307
2339
  "/v1/cli-sign-ins": {
2308
2340
  parameters: {
2309
2341
  query?: never;
@@ -5216,6 +5248,46 @@ export interface components {
5216
5248
  dollars: number;
5217
5249
  } | null;
5218
5250
  };
5251
+ BillingInvoices: {
5252
+ invoices: {
5253
+ id: string;
5254
+ /** @description The number on the invoice. Null until it is finalized. */
5255
+ number: string | null;
5256
+ createdAt: string;
5257
+ /**
5258
+ * @description open: not paid yet. void: cancelled, nothing is owed, as a reload whose card declined. uncollectible: written off.
5259
+ * @enum {string}
5260
+ */
5261
+ status: "open" | "paid" | "void" | "uncollectible";
5262
+ /** @description What it was for, as the invoice says it. */
5263
+ description: string | null;
5264
+ /** @example usd */
5265
+ currency: string;
5266
+ /** @description What it came to, tax included. */
5267
+ totalMicros: number;
5268
+ taxMicros: number;
5269
+ amountPaidMicros: number;
5270
+ /** @description The payment provider's page for it, where an open one is paid. It shows the billing name and address, so it is given to an owner only: null for an admin. */
5271
+ pageUrl: string | null;
5272
+ /** @description Its PDF, an owner's only as pageUrl is. */
5273
+ pdfUrl: string | null;
5274
+ }[];
5275
+ /** @description Pass as startingAfter for the page after this one. Null on the last page. */
5276
+ next: string | null;
5277
+ };
5278
+ BillingCard: {
5279
+ /** @description Null where the account has no card saved. */
5280
+ card: {
5281
+ /** @example visa */
5282
+ brand: string | null;
5283
+ /** @example 4242 */
5284
+ last4: string | null;
5285
+ expMonth: number | null;
5286
+ expYear: number | null;
5287
+ /** @description apple_pay, google_pay or another wallet it is kept in; null for a card typed in. */
5288
+ wallet: string | null;
5289
+ } | null;
5290
+ };
5219
5291
  CliSignIn: {
5220
5292
  /** @example cli_5d0f3c9a7e214b86a0c1d2e3f4a5b6c7 */
5221
5293
  id: string;
@@ -16472,6 +16544,69 @@ export interface operations {
16472
16544
  };
16473
16545
  };
16474
16546
  };
16547
+ listBillingInvoices: {
16548
+ parameters: {
16549
+ query?: {
16550
+ /** @description How many to answer at most, 1 to 100. 25 when left out. */
16551
+ limit?: number;
16552
+ /** @description The next value of the page before, for the page after it. A page may hold fewer than limit, drafts being left out, and still have a next. */
16553
+ startingAfter?: string;
16554
+ };
16555
+ header?: never;
16556
+ path?: never;
16557
+ cookie?: never;
16558
+ };
16559
+ requestBody?: never;
16560
+ responses: {
16561
+ /** @description The account's invoices, newest first, as the payment provider keeps them: a plan's months, top-ups and auto-reloads, drafts left out. Read from it each time; agental keeps none of them. Amounts are millionths of the invoice's currency. */
16562
+ 200: {
16563
+ headers: {
16564
+ [name: string]: unknown;
16565
+ };
16566
+ content: {
16567
+ "application/json": components["schemas"]["BillingInvoices"];
16568
+ };
16569
+ };
16570
+ /** @description billing_not_configured: nothing is sold here. */
16571
+ 409: {
16572
+ headers: {
16573
+ [name: string]: unknown;
16574
+ };
16575
+ content: {
16576
+ "application/json": components["schemas"]["Error"];
16577
+ };
16578
+ };
16579
+ };
16580
+ };
16581
+ getBillingCard: {
16582
+ parameters: {
16583
+ query?: never;
16584
+ header?: never;
16585
+ path?: never;
16586
+ cookie?: never;
16587
+ };
16588
+ requestBody?: never;
16589
+ responses: {
16590
+ /** @description The card the account pays with now: the one a plan's month, a top-up and an auto-reload charge. Its brand, last four and expiry only, read from the payment provider each time. Changed on the payment provider's page, POST /v1/billing/portal. */
16591
+ 200: {
16592
+ headers: {
16593
+ [name: string]: unknown;
16594
+ };
16595
+ content: {
16596
+ "application/json": components["schemas"]["BillingCard"];
16597
+ };
16598
+ };
16599
+ /** @description billing_not_configured: nothing is sold here. */
16600
+ 409: {
16601
+ headers: {
16602
+ [name: string]: unknown;
16603
+ };
16604
+ content: {
16605
+ "application/json": components["schemas"]["Error"];
16606
+ };
16607
+ };
16608
+ };
16609
+ };
16475
16610
  createCliSignIn: {
16476
16611
  parameters: {
16477
16612
  query?: never;
package/dist/types.d.ts CHANGED
@@ -170,6 +170,12 @@ export type Billing = Omit<Schemas["Billing"], "plan" | "discount" | "sandboxesA
170
170
  export type Checkout = Schemas["Checkout"];
171
171
  /** The auto-reload as it is now: the top-up the saved card is charged for when the credits run out, or null while it is off. */
172
172
  export type AutoReload = Schemas["AutoReload"];
173
+ /** A page of the account's invoices, newest first, and the value to pass as startingAfter for the page after it, null on the last. */
174
+ export type BillingInvoices = Schemas["BillingInvoices"];
175
+ /** An invoice: its number, state, what it was for, what it came to in millionths, and the payment provider's page and PDF for it (an owner's only). */
176
+ export type BillingInvoice = Schemas["BillingInvoices"]["invoices"][number];
177
+ /** The card the account pays with now, or null where it has none: brand, last four, expiry and wallet only. */
178
+ export type BillingCard = Schemas["BillingCard"];
173
179
  /** Whether mail is on for a sandbox, and the domain its addresses end in. */
174
180
  export type SandboxEmail = Schemas["SandboxEmail"];
175
181
  /** A message as a list gives it: who it is from and for, what was made of its sender, and where a sent one has got to. */
package/dist/version.d.ts CHANGED
@@ -1,2 +1,2 @@
1
1
  /** This package's version, as package.json says it. A test holds the two to the same. */
2
- export declare const VERSION = "0.6.0";
2
+ export declare const VERSION = "0.7.0";
package/dist/version.js CHANGED
@@ -1,2 +1,2 @@
1
1
  /** This package's version, as package.json says it. A test holds the two to the same. */
2
- export const VERSION = "0.6.0";
2
+ export const VERSION = "0.7.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agental-sdk",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "TypeScript SDK for agental.io: Linux sandboxes for your agents. The agental command is the package agental.",
5
5
  "license": "MIT",
6
6
  "author": "VERTIXER LTD",