Repo Statistics

WarmHub exposes several repository statistics surfaces because dashboards, billing, settings pages, and shape summaries need different levels of detail.

Method names below are the TypeScript spellings. The Python SDK has the same methods in snake_case — client.repo.list_for_caller(...), client.repo.get_stats(...), and so on — with signatures in the Python SDK reference.

Cross-Org Repo Listing

client.repo.listForCaller(opts?) returns repositories across all organizations the caller has access to, with optional limit and sort ('recent' | 'name') parameters.

Use this when you need an account-wide view rather than calling listPage separately for each organization. Note that listForCaller requires an interactive session — it does not accept PAT or component-token auth.

Dashboard List Metadata

client.repo.listPage(...) returns repository list items with dashboard-oriented metadata:

• total is the exact number of active stored identities.

• byKind partitions those identities into shape, thing, and assertion. assertion counts every active assertion — every item whose Shape closure includes Assertion, however it was written — the same set count returns for kind: 'assertion'. thing counts the remaining non-Shape items, so no item is counted twice.

• lastWriteAt is an activity timestamp, not a strict write-history cursor.

• hasErrors is true when the repo has at least one active subscription whose latest terminal run is a failure. A subsequent successful run clears the flag. Inactive subscriptions are excluded.

• failingSubscriptionName is present when hasErrors is true and the caller holds repo:configure. It names the failing subscription whose failure is the most recent among all currently failing subscriptions.

  Note

  Subscriptions that have since succeeded are excluded from this check. Callers without repo:configure will not receive this field. You can use the name to deep-link directly to that subscription in your UI.

Use this for repository tiles and organization dashboards.

Exact Single-Repo Stats

client.repo.getStats(...) returns an exact active-item count for one repository.

The total field counts active stored identities. The byKind breakdown partitions them the same way as listPage: assertion counts every active assertion (Shape closure includes Assertion), and thing counts the remaining non-Shape items. The per-shape map is keyed by each item’s declared Shape and counts both ordinary things and assertions under it; an assertion whose declared Shape composes Assertion counts under that Shape, not under Assertion.

Use this for billing, quotas, or repository detail pages that need the per-shape map.

Batch Stats

client.repo.getStatsBatch(...) returns exact totals for up to 100 repositories in one request.

Use it when callers need exact counts for a caller-provided set of repositories. The batch result does not include the per-shape map; call getStats(...) for any repository where you need that detail.

Configure Stats

client.repo.getConfigureStats(...) returns settings-page counts such as the number of subscriptions attached to a repository.

Use it before delete or visibility-change flows when the UI needs to explain what repository configuration will be affected.

Shape Instance Counts

client.repo.getShapeInstanceCounts(...) returns thing and assertion counts grouped by shape.

The server computes these totals directly, so callers do not need to page through repository contents to build a shape summary UI.