@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/usage.d.ts

@@ -0,0 +1,277 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.usage` (Usage): 9 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"get_billing_product_billing_products__product_id__get">;
+ *
+ * Reference with examples: usage.md
+ */
+/* eslint-disable */
+
+/** `g8.api.usage.<member>` -> the operationId it calls. */
+export interface UsageMembers {
+  getBillingProduct: "get_billing_product_billing_products__product_id__get";
+  getCompanyBilling: "get_company_billing_companies__company_id__billing_get";
+  getCreditHolds: "get_credit_holds_usage_holds_get";
+  getDomainPricing: "get_domain_pricing_usage_pricing_domains__tld__get";
+  getLlmPricing: "get_llm_pricing_usage_pricing_llm_get";
+  getSubscriptionStatus: "get_subscription_status_usage_subscription_get";
+  getUsage: "get_usage_usage_get";
+  listBillingProducts: "list_billing_products_billing_products_get";
+  listUsageTransactions: "list_usage_transactions_usage_transactions_get";
+}
+
+/** Input and output of every `g8.api.usage` operation, keyed by operationId. */
+export interface UsageOperations {
+  /**
+   * GET /billing/products/{product_id}
+   * Get Billing Product
+   * tier: read · scope: analytics:read
+   */
+  get_billing_product_billing_products__product_id__get: {
+    input: {
+    path: {
+      /** Product id from `GET /billing/products`. */
+      product_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/billing
+   * Get Company Billing
+   * tier: read · scope: analytics:read
+   */
+  get_company_billing_companies__company_id__billing_get: {
+    input: {
+    path: {
+      company_id: number;
+    };
+    query?: {
+      /** Invoices to return, newest first. 50 is a hard ceiling in the app, applied whatever is sent - declared honestly here so an over-large value is a 422 rather than a silently smaller answer. */
+      invoice_limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * GET /usage/holds
+   * Get Credit Holds
+   * tier: read · scope: analytics:read
+   */
+  get_credit_holds_usage_holds_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * GET /usage/pricing/domains/{tld}
+   * Get Domain Pricing
+   * tier: read · scope: analytics:read
+   */
+  get_domain_pricing_usage_pricing_domains__tld__get: {
+    input: {
+    path: {
+      /** Top-level domain, with or without the leading dot - `com` and `.com` both resolve. */
+      tld: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * GET /usage/pricing/llm
+   * Get Llm Pricing
+   * tier: read · scope: analytics:read
+   */
+  get_llm_pricing_usage_pricing_llm_get: {
+    input: {
+    query: {
+      /** Pricing tier, e.g. `g8_t1`. The same value that appears in the `llm_tier` column of `GET /usage/transactions`, which is where to find the tier a given operation actually bills at. */
+      llm_tier: string;
+      /** Prompt tokens. */
+      input_tokens?: number;
+      /** Completion tokens. */
+      output_tokens?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * GET /usage/subscription
+   * Get Subscription Status
+   * tier: read · scope: analytics:read
+   */
+  get_subscription_status_usage_subscription_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportPayload_;
+  };
+  /**
+   * GET /usage
+   * Get Usage
+   * tier: read · scope: usage:read
+   */
+  get_usage_usage_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_UsageBalanceResponse_;
+  };
+  /**
+   * GET /billing/products
+   * List Billing Products
+   * tier: read · scope: analytics:read
+   */
+  list_billing_products_billing_products_get: {
+    input: {
+    query?: {
+      /** Only products currently on sale. */
+      active_only?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ReportListPayload_;
+  };
+  /**
+   * GET /usage/transactions
+   * List Usage Transactions
+   * tier: read · scope: usage:read
+   */
+  list_usage_transactions_usage_transactions_get: {
+    input: {
+    query?: {
+      /** Page number (ignored when `cursor` is supplied) */
+      page?: number;
+      /** Items per page */
+      limit?: number;
+      /** Opaque pagination cursor from a prior response's `next_cursor`. When supplied it takes precedence over `page`. */
+      cursor?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_UsageTransactionResponse__;
+  };
+}
+
+// 9 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_ReportListPayload_ {
+  data: ReportListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ReportPayload_ {
+  data: ReportPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_UsageBalanceResponse_ {
+  data: UsageBalanceResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_UsageTransactionResponse__ {
+  data: Array<UsageTransactionResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}
+
+/**
+ * An OPEN envelope for a report that answers with a bare LIST.
+ *
+ * A bare list is reachable as `items`; a named list (`{"counts": {...}}`)
+ * keeps its own key AND gains `items`, so a caller can read either shape
+ * without branching.
+ */
+export interface ReportListPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * An OPEN envelope around one report's answer.
+ *
+ * The app wraps every one of these reports in `{success, data, meta}`, where
+ * `meta` carries the cache state, the window and - on the agency reports -
+ * `failed_org_ids`, the orgs that contributed NOTHING to the totals above.
+ * That field is the difference between "this client sent no email" and "we
+ * could not query this client", so it is forwarded rather than flattened
+ * away.
+ *
+ * Open on purpose: `data` is `dict | list` in the app and its contents grow
+ * with the product. A closed model would turn every new metric into a
+ * silently dropped one.
+ */
+export type ReportPayload = Record<string, unknown>;
+
+/** An org's current credit balance + lifetime totals. */
+export interface UsageBalanceResponse {
+  /** Spendable credits (credits - held) */
+  available_credits: number;
+  /** Total credit balance */
+  credits: number;
+  /** Org / customer id the credits belong to */
+  customer_id: string;
+  /** Credits currently on hold */
+  held_credits: number;
+  /** Lifetime credits earned */
+  total_earned: number;
+  /** Lifetime credits used */
+  total_used: number;
+}
+
+/** A single credit-ledger transaction. */
+export interface UsageTransactionResponse {
+  /** Credit delta (negative = spend) */
+  amount?: number;
+  created_at?: string | null;
+  description?: string | null;
+  /** Transaction id */
+  id?: string | null;
+  /** g8_t1 / g8_t2 / g8_t3 when an LLM charge */
+  llm_tier?: string | null;
+  quantity?: number | null;
+  /** Service the charge was for (e.g. 'ai_enrichment') */
+  service?: string | null;
+  /** Transaction type (e.g. 'usage', 'purchase') */
+  type?: string | null;
+}

package/docs/api/usage.md

@@ -0,0 +1,389 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.usage`: Usage
+
+9 operations (9 read).
+
+No hand-written client covers this area. Call it through `g8.api.usage.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [usage.d.ts](usage.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`getBillingProduct`](#op-getbillingproduct) | `GET /api/v1/billing/products/{product_id}` | read | `analytics:read` | Get Billing Product |
+| [`getCompanyBilling`](#op-getcompanybilling) | `GET /api/v1/companies/{company_id}/billing` | read | `analytics:read` | Get Company Billing |
+| [`getCreditHolds`](#op-getcreditholds) | `GET /api/v1/usage/holds` | read | `analytics:read` | Get Credit Holds |
+| [`getDomainPricing`](#op-getdomainpricing) | `GET /api/v1/usage/pricing/domains/{tld}` | read | `analytics:read` | Get Domain Pricing |
+| [`getLlmPricing`](#op-getllmpricing) | `GET /api/v1/usage/pricing/llm` | read | `analytics:read` | Get Llm Pricing |
+| [`getSubscriptionStatus`](#op-getsubscriptionstatus) | `GET /api/v1/usage/subscription` | read | `analytics:read` | Get Subscription Status |
+| [`getUsage`](#op-getusage) | `GET /api/v1/usage` | read | `usage:read` | Get Usage |
+| [`listBillingProducts`](#op-listbillingproducts) | `GET /api/v1/billing/products` | read | `analytics:read` | List Billing Products |
+| [`listUsageTransactions`](#op-listusagetransactions) | `GET /api/v1/usage/transactions` | read | `usage:read` | List Usage Transactions |
+
+---
+
+<a id="op-getbillingproduct"></a>
+
+### `g8.api.usage.getBillingProduct(input)`
+
+**Get Billing Product**
+
+- HTTP: `GET /api/v1/billing/products/{product_id}`
+- operationId: `get_billing_product_billing_products__product_id__get` (also callable as `g8.api.call("get_billing_product_billing_products__product_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+One plan or credit pack from the catalogue.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.product_id` | `string` | yes | Product id from `GET /billing/products`. |
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.usage.getBillingProduct({ path: { product_id: "id" } });
+```
+
+---
+
+<a id="op-getcompanybilling"></a>
+
+### `g8.api.usage.getCompanyBilling(input)`
+
+**Get Company Billing**
+
+- HTTP: `GET /api/v1/companies/{company_id}/billing`
+- operationId: `get_company_billing_companies__company_id__billing_get` (also callable as `g8.api.call("get_company_billing_companies__company_id__billing_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+What ONE of your customers is paying you: subscription, invoices,
+upcoming charge.
+
+Read from the `stripe_*` tables that the per-org Stripe sync populates
+from the customer's OWN connected account, so this is revenue the caller
+receives - not what the caller owes graph8, which is `GET /usage`.
+
+`payment_method` is null by design rather than by omission: card data is
+not synced, and the hosted portal is the only place it exists.
+
+A company in another org is a 404, not a 403 - the app's own choice, so
+that the API cannot be used to test whether a company id exists somewhere
+else.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes |  |
+| `query.invoice_limit` | `integer` | no | Invoices to return, newest first. 50 is a hard ceiling in the app, applied whatever is sent - declared honestly here so an over-large value is a 422 rather than a silently smaller answer. default `20` |
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.usage.getCompanyBilling({ path: { company_id: 123 } });
+```
+
+---
+
+<a id="op-getcreditholds"></a>
+
+### `g8.api.usage.getCreditHolds(input?)`
+
+**Get Credit Holds**
+
+- HTTP: `GET /api/v1/usage/holds`
+- operationId: `get_credit_holds_usage_holds_get` (also callable as `g8.api.call("get_credit_holds_usage_holds_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Credits currently RESERVED against work in flight.
+
+This is the difference `GET /usage` reports but cannot explain: a hold
+subtracts from `available_credits` without appearing in the transaction
+ledger, because nothing has been spent yet. An operation that reserves
+credits up front and settles later shows up here in between.
+
+A balance that looks lower than the ledger says is almost always this.
+
+The org is the authenticated key's own. There is no customer parameter on
+this route.
+
+**Input**: none.
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.usage.getCreditHolds();
+```
+
+---
+
+<a id="op-getdomainpricing"></a>
+
+### `g8.api.usage.getDomainPricing(input)`
+
+**Get Domain Pricing**
+
+- HTTP: `GET /api/v1/usage/pricing/domains/{tld}`
+- operationId: `get_domain_pricing_usage_pricing_domains__tld__get` (also callable as `g8.api.call("get_domain_pricing_usage_pricing_domains__tld__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+What registering a domain on this TLD costs in credits.
+
+The price `POST /channels/domains/purchase` will charge. A TLD with no
+pricing row is a 404 rather than a zero - a missing price is not a free
+domain.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.tld` | `string` | yes | Top-level domain, with or without the leading dot - `com` and `.com` both resolve. |
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.usage.getDomainPricing({ path: { tld: "example" } });
+```
+
+---
+
+<a id="op-getllmpricing"></a>
+
+### `g8.api.usage.getLlmPricing(input)`
+
+**Get Llm Pricing**
+
+- HTTP: `GET /api/v1/usage/pricing/llm`
+- operationId: `get_llm_pricing_usage_pricing_llm_get` (also callable as `g8.api.call("get_llm_pricing_usage_pricing_llm_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+What an LLM operation of this size would cost. Charges nothing.
+
+READ `capped` before reading `credits`. Several tiers have a per-operation
+ceiling, and for typical prompt sizes the ceiling is what is actually paid
+- so `credits` stops moving when the prompt grows, and
+`uncapped_credits` is what the token arithmetic alone would have produced.
+A caller that shows `credits` without `capped` gets asked why shortening
+the prompt changed nothing.
+
+`found` is false for a tier that does not exist or is not currently
+active; `credits` is then 0, which is not a price.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.llm_tier` | `string` | yes | Pricing tier, e.g. `g8_t1`. The same value that appears in the `llm_tier` column of `GET /usage/transactions`, which is where to find the tier a given operation actually bills at. |
+| `query.input_tokens` | `integer` | no | Prompt tokens. default `0` |
+| `query.output_tokens` | `integer` | no | Completion tokens. default `0` |
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.usage.getLlmPricing({ query: { llm_tier: "example" } });
+```
+
+---
+
+<a id="op-getsubscriptionstatus"></a>
+
+### `g8.api.usage.getSubscriptionStatus(input?)`
+
+**Get Subscription Status**
+
+- HTTP: `GET /api/v1/usage/subscription`
+- operationId: `get_subscription_status_usage_subscription_get` (also callable as `g8.api.call("get_subscription_status_usage_subscription_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Whether this organisation's subscription is active.
+
+Worth checking before anything that spends: a charge against an inactive
+subscription is refused even when the balance is healthy, so "insufficient
+credits" is not the only way spending fails.
+
+`raise_on_unavailable` is set, which is the whole point of answering this
+as its own route rather than as a boolean somewhere else: without it an
+unreachable billing service and an authoritatively-inactive subscription
+both answer `false`, and those two mean opposite things. Unreachable
+becomes a 503 here; `false` means false.
+
+**Input**: none.
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.usage.getSubscriptionStatus();
+```
+
+---
+
+<a id="op-getusage"></a>
+
+### `g8.api.usage.getUsage(input?)`
+
+**Get Usage**
+
+- HTTP: `GET /api/v1/usage`
+- operationId: `get_usage_usage_get` (also callable as `g8.api.call("get_usage_usage_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `usage:read`
+
+Current credit balance for the authenticated org — total, held, available, and lifetime totals.
+
+**Input**: none.
+
+**Returns** `ApiResponse_UsageBalanceResponse_`: the envelope `{ data: UsageBalanceResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`UsageBalanceResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `available_credits` | `number` | yes | Spendable credits (credits - held) |
+| `credits` | `number` | yes | Total credit balance |
+| `customer_id` | `string` | yes | Org / customer id the credits belong to |
+| `held_credits` | `number` | yes | Credits currently on hold |
+| `total_earned` | `number` | yes | Lifetime credits earned |
+| `total_used` | `number` | yes | Lifetime credits used |
+
+**Example**
+
+```ts
+const result = await g8.api.usage.getUsage();
+```
+
+---
+
+<a id="op-listbillingproducts"></a>
+
+### `g8.api.usage.listBillingProducts(input?)`
+
+**List Billing Products**
+
+- HTTP: `GET /api/v1/billing/products`
+- operationId: `list_billing_products_billing_products_get` (also callable as `g8.api.call("list_billing_products_billing_products_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+The plans and credit packs graph8 sells, with their prices.
+
+The same catalogue the Billing page renders. It is not per-organisation -
+every caller sees the same list - which is why this is one of the very few
+credit-server reads that can be published without a customer parameter.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.active_only` | `boolean` | no | Only products currently on sale. default `true` |
+
+**Returns** `ApiResponse_ReportListPayload_`: the envelope `{ data: ReportListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ReportListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.usage.listBillingProducts();
+```
+
+---
+
+<a id="op-listusagetransactions"></a>
+
+### `g8.api.usage.listUsageTransactions(input?)`
+
+**List Usage Transactions**
+
+- HTTP: `GET /api/v1/usage/transactions`
+- operationId: `list_usage_transactions_usage_transactions_get` (also callable as `g8.api.call("list_usage_transactions_usage_transactions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `usage:read`
+
+Paginated credit-transaction ledger for the authenticated org (most recent first).
+
+Supports both page-number pagination (`page`/`limit`) and opaque cursor
+pagination (`cursor`). When `cursor` is supplied it wins; the response always
+returns `next_cursor` for forward iteration.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.page` | `integer` | no | Page number (ignored when `cursor` is supplied) default `1` |
+| `query.limit` | `integer` | no | Items per page default `50` |
+| `query.cursor` | `string \| null` | no | Opaque pagination cursor from a prior response's `next_cursor`. When supplied it takes precedence over `page`. |
+
+**Returns** `ApiResponse_list_UsageTransactionResponse__`: the envelope `{ data: Array<UsageTransactionResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`UsageTransactionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `amount` | `number` | no | Credit delta (negative = spend) default `0` |
+| `created_at` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `id` | `string \| null` | no | Transaction id |
+| `llm_tier` | `string \| null` | no | g8_t1 / g8_t2 / g8_t3 when an LLM charge |
+| `quantity` | `integer \| null` | no |  |
+| `service` | `string \| null` | no | Service the charge was for (e.g. 'ai_enrichment') |
+| `type` | `string \| null` | no | Transaction type (e.g. 'usage', 'purchase') |
+
+**Example**
+
+```ts
+const result = await g8.api.usage.listUsageTransactions();
+```