boxd 0.2.13.dev715__tar.gz → 0.2.13.dev751__tar.gz

{boxd-0.2.13.dev715/src/boxd.egg-info → boxd-0.2.13.dev751}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boxd
-Version: 0.2.13.dev715
+Version: 0.2.13.dev751
 Summary: Python SDK for the boxd cloud VM platform
 Author: Azin
 License-Expression: MIT
@@ -56,6 +56,10 @@ boxd.machines.wait_until_ready(machine.id)
 result = boxd.machines.exec(machine.id, "uname -a")
 print(result.stdout)
 
+# What it cost (metered every few minutes; still answers after delete):
+usage = boxd.machines.usage(machine.id)
+print(usage.cost_micro / 1e6, usage.currency)
+
 boxd.machines.delete(machine.id)
 boxd.close()
 ```
@@ -753,6 +757,60 @@ cfg = boxd.account.config()
 cfg.default_image, cfg.zone
 ```
 
+## Usage and cost
+
+What each machine used and cost, and what was actually charged. Org owners
+and admins only; an API key issued for the org works too.
+
+```python
+from datetime import datetime, timezone
+
+# One machine over its whole life, or pass since=/until= (datetime or unix
+# seconds). A deleted machine is found by its id or name (org= says where to look).
+u = boxd.machines.usage("my-machine")
+u.seconds.running, u.seconds.standby, u.seconds.hibernated, u.seconds.stopped
+u.cost_micro / 1e6                   # estimated cost, in u.currency ("eur" | "usd")
+u.complete                           # True once all its usage is metered (see below)
+u.period.start, u.period.end
+u.vcpu_hours, u.ram_gib_hours, u.disk_gib_hours   # what the cost is priced on
+u.rates                              # ...at these rates, per unit-hour
+
+# Every machine in an org, most expensive first. Default: the last 28 days.
+r = boxd.orgs.usage(since=datetime(2026, 9, 1, tzinfo=timezone.utc))
+r.total_cost_micro, r.currency
+for m in r.machines:
+    print(m.name, m.status, m.cost_micro / 1e6)
+
+# The credit ledger: what was actually charged, newest first.
+for e in boxd.orgs.ledger(since=datetime(2026, 9, 1, tzinfo=timezone.utc)):
+    print(e.created_at, e.kind, e.amount_micro / 1e6)   # charges are negative
+```
+
+To record what a machine cost after deleting it, wait for `complete`:
+metering lags by up to ~25 minutes, so the figure read right after `delete()`
+is still growing.
+
+```python
+boxd.machines.delete(machine_id)
+# ...a little later, or from a periodic job:
+u = boxd.machines.usage(machine_id)
+if u.complete:
+    save(machine_id, u.cost_micro, u.currency)   # otherwise try again later
+```
+
+`orgs.usage()` carries the same flag on every machine, so one periodic call can
+settle all of them. A machine that still exists is never complete in a window
+that runs to now.
+
+Money is in micro-units (1e-6) of the org's currency. Usage is metered in
+15-minute buckets and priced at the org's current rates, so it is an estimate
+that tracks the ledger closely; the ledger is what was charged (one
+`usage_charge` per 15 minutes for the whole org, plus top-ups and grants).
+Machines deleted since still show up, with status `"deleted"`. A window spans
+at most 366 days. `orgs.ledger_page()` returns one page with its
+`next_page_token` when you want to page by hand. The async client has the
+same methods (`async for e in boxd.orgs.ledger(): ...`).
+
 ## Errors
 
 ```python

{boxd-0.2.13.dev715 → boxd-0.2.13.dev751}/README.md

@@ -24,6 +24,10 @@ boxd.machines.wait_until_ready(machine.id)
 result = boxd.machines.exec(machine.id, "uname -a")
 print(result.stdout)
 
+# What it cost (metered every few minutes; still answers after delete):
+usage = boxd.machines.usage(machine.id)
+print(usage.cost_micro / 1e6, usage.currency)
+
 boxd.machines.delete(machine.id)
 boxd.close()
 ```
@@ -721,6 +725,60 @@ cfg = boxd.account.config()
 cfg.default_image, cfg.zone
 ```
 
+## Usage and cost
+
+What each machine used and cost, and what was actually charged. Org owners
+and admins only; an API key issued for the org works too.
+
+```python
+from datetime import datetime, timezone
+
+# One machine over its whole life, or pass since=/until= (datetime or unix
+# seconds). A deleted machine is found by its id or name (org= says where to look).
+u = boxd.machines.usage("my-machine")
+u.seconds.running, u.seconds.standby, u.seconds.hibernated, u.seconds.stopped
+u.cost_micro / 1e6                   # estimated cost, in u.currency ("eur" | "usd")
+u.complete                           # True once all its usage is metered (see below)
+u.period.start, u.period.end
+u.vcpu_hours, u.ram_gib_hours, u.disk_gib_hours   # what the cost is priced on
+u.rates                              # ...at these rates, per unit-hour
+
+# Every machine in an org, most expensive first. Default: the last 28 days.
+r = boxd.orgs.usage(since=datetime(2026, 9, 1, tzinfo=timezone.utc))
+r.total_cost_micro, r.currency
+for m in r.machines:
+    print(m.name, m.status, m.cost_micro / 1e6)
+
+# The credit ledger: what was actually charged, newest first.
+for e in boxd.orgs.ledger(since=datetime(2026, 9, 1, tzinfo=timezone.utc)):
+    print(e.created_at, e.kind, e.amount_micro / 1e6)   # charges are negative
+```
+
+To record what a machine cost after deleting it, wait for `complete`:
+metering lags by up to ~25 minutes, so the figure read right after `delete()`
+is still growing.
+
+```python
+boxd.machines.delete(machine_id)
+# ...a little later, or from a periodic job:
+u = boxd.machines.usage(machine_id)
+if u.complete:
+    save(machine_id, u.cost_micro, u.currency)   # otherwise try again later
+```
+
+`orgs.usage()` carries the same flag on every machine, so one periodic call can
+settle all of them. A machine that still exists is never complete in a window
+that runs to now.
+
+Money is in micro-units (1e-6) of the org's currency. Usage is metered in
+15-minute buckets and priced at the org's current rates, so it is an estimate
+that tracks the ledger closely; the ledger is what was charged (one
+`usage_charge` per 15 minutes for the whole org, plus top-ups and grants).
+Machines deleted since still show up, with status `"deleted"`. A window spans
+at most 366 days. `orgs.ledger_page()` returns one page with its
+`next_page_token` when you want to page by hand. The async client has the
+same methods (`async for e in boxd.orgs.ledger(): ...`).
+
 ## Errors
 
 ```python

{boxd-0.2.13.dev715 → boxd-0.2.13.dev751}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "boxd"
-version = "0.2.13.dev715"
+version = "0.2.13.dev751"
 description = "Python SDK for the boxd cloud VM platform"
 readme = "README.md"
 license = "MIT"

{boxd-0.2.13.dev715 → boxd-0.2.13.dev751}/src/boxd/__init__.py

@@ -53,6 +53,8 @@ from .models import (
     EnvVar,
     ExecResult,
     ExposedPort,
+    LedgerEntry,
+    LedgerPage,
     Machine,
     MachineAccess,
     MachineIdle,
@@ -61,6 +63,8 @@ from .models import (
     MachineSource,
     MachineSourceKind,
     MachineStatus,
+    MachineUsage,
+    MachineUsageReport,
     Org,
     OrgDomain,
     OrgInvite,
@@ -69,6 +73,7 @@ from .models import (
     OrgMembers,
     OrgRef,
     OrgRole,
+    OrgUsage,
     PauseResult,
     Proxy,
     ProxyEntry,
@@ -77,8 +82,11 @@ from .models import (
     ResumeResult,
     Secret,
     Snapshot,
+    StateSeconds,
     Team,
     TeamMember,
+    UsagePeriod,
+    UsageRates,
     VarScope,
     VolumeMount,
 )
@@ -122,6 +130,8 @@ __all__ = [
     "EnvVar",
     "ExecResult",
     "ExposedPort",
+    "LedgerEntry",
+    "LedgerPage",
     "Machine",
     "MachineAccess",
     "MachineIdle",
@@ -130,6 +140,8 @@ __all__ = [
     "MachineSource",
     "MachineSourceKind",
     "MachineStatus",
+    "MachineUsage",
+    "MachineUsageReport",
     "Org",
     "OrgDomain",
     "OrgInvite",
@@ -138,6 +150,7 @@ __all__ = [
     "OrgMembers",
     "OrgRef",
     "OrgRole",
+    "OrgUsage",
     "PauseResult",
     "Proxy",
     "ProxyEntry",
@@ -146,8 +159,11 @@ __all__ = [
     "ResumeResult",
     "Secret",
     "Snapshot",
+    "StateSeconds",
     "Team",
     "TeamMember",
+    "UsagePeriod",
+    "UsageRates",
     "VarScope",
     "VolumeMount",
     # Errors