@stigg/typescript 0.1.0-beta.61 → 0.1.0-beta.63

package/src/resources/v1-beta/customers/governance.ts

@@ -0,0 +1,210 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import { MyCursorIDPage, type MyCursorIDPageParams, PagePromise } from '../../../core/pagination';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+export class Governance extends APIResource {
+  /**
+   * Queries the customer's governance hierarchy tree, returning a cursor-paginated
+   * list of nodes with their usage configuration (limit, cadence, scope) and current
+   * usage, sortable and filterable by usage. Each node carries `parentId` so the
+   * tree can be rebuilt client-side. Usage is read from a periodically-refreshed
+   * read model and never gates access.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const governanceListResponse of client.v1Beta.customers.governance.list(
+   *   'id',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    id: string,
+    params: GovernanceListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<GovernanceListResponsesMyCursorIDPage, GovernanceListResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...query } = params ?? {};
+    return this._client.getAPIList(
+      path`/api/v1-beta/customers/${id}/governance`,
+      MyCursorIDPage<GovernanceListResponse>,
+      {
+        query,
+        ...options,
+        headers: buildHeaders([
+          {
+            ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+            ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+          },
+          options?.headers,
+        ]),
+      },
+    );
+  }
+}
+
+export type GovernanceListResponsesMyCursorIDPage = MyCursorIDPage<GovernanceListResponse>;
+
+/**
+ * A node of the governance hierarchy tree with its usage configuration (limit,
+ * cadence, scope) and current usage. Usage is read from a periodically-refreshed
+ * read model and may lag the live counter by a short interval; it never gates
+ * access.
+ */
+export interface GovernanceListResponse {
+  /**
+   * Usage-reset cadence as an ISO-8601 single-unit duration, e.g. `P1M`, `P30D`,
+   * `PT1M`; `null` when the node has no usage configuration.
+   */
+  cadence: string | null;
+
+  /**
+   * Usage consumed in the current cadence period (may lag the live counter by a
+   * short interval).
+   */
+  currentUsage: number | null;
+
+  /**
+   * Human-readable name of the entity, or null when none is set (display the entity
+   * id instead).
+   */
+  displayName: string | null;
+
+  /**
+   * External id of the entity at this node.
+   */
+  entityId: string;
+
+  /**
+   * External id of the entity type (e.g. `team`, `user`).
+   */
+  entityTypeId: string;
+
+  /**
+   * External id of the parent entity in the tree. `null` means the entity is either
+   * a root or not yet placed in the hierarchy — placement rides on an assignment, so
+   * an entity with no limits set has no parent yet. Both render at the top level;
+   * use it to rebuild the tree.
+   */
+  parentId: string | null;
+
+  /**
+   * The configuration scope (entity ids). Empty is the node-wide configuration; a
+   * non-empty set is a dimension-scoped sub-configuration.
+   */
+  scopeEntityIds: Array<string>;
+
+  /**
+   * Hard usage limit for this node per cadence period.
+   */
+  usageLimit: number | null;
+
+  /**
+   * Exclusive end of the cadence period in progress now — when usage resets. `null`
+   * when the node has no usage configuration, or when a stored cadence cannot be
+   * parsed.
+   */
+  usagePeriodEnd: string | null;
+
+  /**
+   * Start of the cadence period in progress now, derived from the cadence and the
+   * assignment anchor — it stays correct across a rollover. `null` when the node has
+   * no usage configuration, or when a stored cadence cannot be parsed.
+   */
+  usagePeriodStart: string | null;
+
+  /**
+   * `currentUsage / usageLimit` (1 when usageLimit is 0 — always at limit). The
+   * cross-capability-safe sort key.
+   */
+  utilization: number | null;
+
+  /**
+   * The metered currency ID (present when the configured capability is a credit
+   * currency).
+   */
+  currencyId?: string;
+
+  /**
+   * The metered feature ID (present when the configured capability is a feature).
+   */
+  featureId?: string;
+}
+
+export interface GovernanceListParams extends MyCursorIDPageParams {
+  /**
+   * Query param: Currency ids to include, comma-separated (e.g.
+   * `?currencyIds=credits`), up to 100. Omit both featureIds and currencyIds for
+   * tree mode.
+   */
+  currencyIds?: Array<string>;
+
+  /**
+   * Query param: Case-insensitive substring match on the entity id or its display
+   * name (`%`/`_` matched literally).
+   */
+  entityIdSearch?: string;
+
+  /**
+   * Query param: Filter to one or more entity types, comma-separated (e.g.
+   * `?entityTypeIds=team,user`), up to 100.
+   */
+  entityTypeIds?: Array<string>;
+
+  /**
+   * Query param: Feature ids to include, comma-separated (e.g.
+   * `?featureIds=ai-tokens,seats`), up to 100. Omit both featureIds and currencyIds
+   * for tree mode — every node in the hierarchy with no usage configuration
+   * attached.
+   */
+  featureIds?: Array<string>;
+
+  /**
+   * Query param: Only nodes with utilization ≥ this value (e.g. 0.8 for ≥80%, 1 for
+   * at/over limit).
+   */
+  minUtilization?: number;
+
+  /**
+   * Query param: Sort direction: `asc` or `desc` (default `desc`).
+   */
+  order?: 'asc' | 'desc';
+
+  /**
+   * Query param: Filter by configuration scope: `all` (default), `nodeWide` (`[]`
+   * only), or `scoped` (non-empty only).
+   */
+  scope?: 'all' | 'nodeWide' | 'scoped';
+
+  /**
+   * Query param: Sort key: `utilization` (default, cross-capability-safe),
+   * `currentUsage`, `usageLimit`, `scopeSize`, `id`, or `createdAt`.
+   */
+  sortBy?: 'utilization' | 'currentUsage' | 'usageLimit' | 'scopeSize' | 'id' | 'createdAt';
+
+  /**
+   * Header param: Account ID — optional when authenticating with a user JWT (Bearer
+   * token); falls back to the user's first membership. Ignored for API-key auth.
+   */
+  'X-ACCOUNT-ID'?: string;
+
+  /**
+   * Header param: Environment ID — required when authenticating with a user JWT
+   * (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is
+   * intrinsic to the key).
+   */
+  'X-ENVIRONMENT-ID'?: string;
+}
+
+export declare namespace Governance {
+  export {
+    type GovernanceListResponse as GovernanceListResponse,
+    type GovernanceListResponsesMyCursorIDPage as GovernanceListResponsesMyCursorIDPage,
+    type GovernanceListParams as GovernanceListParams,
+  };
+}

package/src/resources/v1-beta/customers/index.ts

@@ -24,3 +24,9 @@ export {
   type EntityListResponsesMyCursorIDPage,
 } from './entities';
 export { Entitlements, type EntitlementCheckResponse, type EntitlementCheckParams } from './entitlements';
+export {
+  Governance,
+  type GovernanceListResponse,
+  type GovernanceListParams,
+  type GovernanceListResponsesMyCursorIDPage,
+} from './governance';

package/src/resources/v2/usage.ts

@@ -299,9 +299,10 @@ export namespace UsageReportParams {
     featureId: string;
 
     /**
-     * The value to report for usage. Must be a whole number — the REST API does not
-     * accept fractional (float) usage values; scale up (e.g. report cents instead of
-     * dollars, or milliseconds instead of seconds) if you need sub-unit precision.
+     * The value to report for usage. Fractional values are accepted and rounded half
+     * away from zero to 5 decimal places. A value with a fractional part must have an
+     * absolute value below 34,359,738,368 (2^35); whole numbers are accepted up to
+     * ±9,007,199,254,740,991.
      */
     value: number;
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.1.0-beta.61'; // x-release-please-version
+export const VERSION = '0.1.0-beta.63'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.0-beta.61";
+export declare const VERSION = "0.1.0-beta.63";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.0-beta.61";
+export declare const VERSION = "0.1.0-beta.63";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.1.0-beta.61'; // x-release-please-version
+exports.VERSION = '0.1.0-beta.63'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.1.0-beta.61'; // x-release-please-version
+export const VERSION = '0.1.0-beta.63'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map