@stigg/typescript 0.1.0-beta.64 → 0.1.0-beta.66

package/src/resources/v1/entity-types.ts

@@ -0,0 +1,402 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+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 EntityTypes extends APIResource {
+  /**
+   * Returns a cursor-paginated list of entity types defined in the environment.
+   * Entity types are vendor-defined categories of resource that can be governed
+   * (e.g. Org, Team, User). Archived entity types are excluded unless
+   * includeArchived=true.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const entityTypeListResponse of client.v1.entityTypes.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    params: EntityTypeListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<EntityTypeListResponsesMyCursorIDPage, EntityTypeListResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...query } = params ?? {};
+    return this._client.getAPIList('/api/v1/entity-types', MyCursorIDPage<EntityTypeListResponse>, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Archives entity types in bulk by id. An entity type with active entities cannot
+   * be archived: archive its entities first, or the whole request fails with 400.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.entityTypes.archive({
+   *   ids: ['team'],
+   * });
+   * ```
+   */
+  archive(params: EntityTypeArchiveParams, options?: RequestOptions): APIPromise<EntityTypeArchiveResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
+    return this._client.post('/api/v1/entity-types/archive', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Returns whether any active entity of this entity type exists, across every
+   * customer. An entity type can be archived only when this is false. An unknown
+   * entity type returns false.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.entityTypes.checkActiveEntities('id');
+   * ```
+   */
+  checkActiveEntities(
+    id: string,
+    params: EntityTypeCheckActiveEntitiesParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<EntityTypeCheckActiveEntitiesResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID } = params ?? {};
+    return this._client.get(path`/api/v1/entity-types/${id}/has-active-entities`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Batched create-or-update of entity types. Existing types matched by id are
+   * updated; new ids are created. Idempotent — re-submitting the same payload
+   * converges to the same state. An upsert of an archived entity type restores it.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.entityTypes.upsert({
+   *   types: [
+   *     {
+   *       id: 'org',
+   *       displayName: 'Organization',
+   *       description:
+   *         'A customer organization — the top of the hierarchy, holding the account-wide budget.',
+   *       attributionKeys: ['organizationId'],
+   *     },
+   *     {
+   *       id: 'team',
+   *       displayName: 'Team',
+   *       attributionKeys: ['teamId'],
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  upsert(params: EntityTypeUpsertParams, options?: RequestOptions): APIPromise<EntityTypeUpsertResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
+    return this._client.put('/api/v1/entity-types', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export type EntityTypeListResponsesMyCursorIDPage = MyCursorIDPage<EntityTypeListResponse>;
+
+/**
+ * A vendor-defined category of resource that can be governed (e.g. Org, Team,
+ * User). Vendors define entity types once per environment; their customers create
+ * instances (entities) of these types and the governance engine tracks usage and
+ * enforces limits per instance.
+ */
+export interface EntityTypeListResponse {
+  /**
+   * The unique identifier for the entity
+   */
+  id: string;
+
+  /**
+   * Timestamp of when the record was deleted
+   */
+  archivedAt: string | null;
+
+  /**
+   * Dimension keys used to attribute usage events to instances of this type (e.g.
+   * ["orgId"]). Empty array means no attribution.
+   */
+  attributionKeys: Array<string>;
+
+  /**
+   * Timestamp of when the record was created
+   */
+  createdAt: string;
+
+  /**
+   * What this entity type represents and what it is for governing, or null when none
+   * is set
+   */
+  description: string | null;
+
+  /**
+   * The display name for the entity type
+   */
+  displayName: string;
+
+  /**
+   * Timestamp of when the record was last updated
+   */
+  updatedAt: string;
+}
+
+/**
+ * Wrapped response echoing the entity type ids that were acted on by an archive
+ * call
+ */
+export interface EntityTypeArchiveResponse {
+  /**
+   * List of entity type identifiers that were acted on
+   */
+  data: EntityTypeArchiveResponse.Data;
+}
+
+export namespace EntityTypeArchiveResponse {
+  /**
+   * List of entity type identifiers that were acted on
+   */
+  export interface Data {
+    /**
+     * Entity type identifiers to act on
+     */
+    ids: Array<string>;
+  }
+}
+
+/**
+ * Wrapped response with whether an entity type has active entities
+ */
+export interface EntityTypeCheckActiveEntitiesResponse {
+  /**
+   * Whether an entity type has active entities
+   */
+  data: EntityTypeCheckActiveEntitiesResponse.Data;
+}
+
+export namespace EntityTypeCheckActiveEntitiesResponse {
+  /**
+   * Whether an entity type has active entities
+   */
+  export interface Data {
+    /**
+     * Whether at least one active (non-archived) entity of the entity type exists,
+     * across every customer
+     */
+    hasActiveEntities: boolean;
+  }
+}
+
+/**
+ * Entity types after upsert.
+ */
+export interface EntityTypeUpsertResponse {
+  data: Array<EntityTypeUpsertResponse.Data>;
+}
+
+export namespace EntityTypeUpsertResponse {
+  /**
+   * A vendor-defined category of resource that can be governed (e.g. Org, Team,
+   * User). Vendors define entity types once per environment; their customers create
+   * instances (entities) of these types and the governance engine tracks usage and
+   * enforces limits per instance.
+   */
+  export interface Data {
+    /**
+     * The unique identifier for the entity
+     */
+    id: string;
+
+    /**
+     * Timestamp of when the record was deleted
+     */
+    archivedAt: string | null;
+
+    /**
+     * Dimension keys used to attribute usage events to instances of this type (e.g.
+     * ["orgId"]). Empty array means no attribution.
+     */
+    attributionKeys: Array<string>;
+
+    /**
+     * Timestamp of when the record was created
+     */
+    createdAt: string;
+
+    /**
+     * What this entity type represents and what it is for governing, or null when none
+     * is set
+     */
+    description: string | null;
+
+    /**
+     * The display name for the entity type
+     */
+    displayName: string;
+
+    /**
+     * Timestamp of when the record was last updated
+     */
+    updatedAt: string;
+  }
+}
+
+export interface EntityTypeListParams extends MyCursorIDPageParams {
+  /**
+   * Query param: Whether to include archived entity types. One of: true, false
+   */
+  includeArchived?: 'true' | 'false';
+
+  /**
+   * 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 interface EntityTypeArchiveParams {
+  /**
+   * Body param: Entity type identifiers to act on
+   */
+  ids: Array<string>;
+
+  /**
+   * 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 interface EntityTypeCheckActiveEntitiesParams {
+  /**
+   * 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;
+
+  /**
+   * 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 interface EntityTypeUpsertParams {
+  /**
+   * Body param: Entity types to upsert (1–100 per request)
+   */
+  types: Array<EntityTypeUpsertParams.Type>;
+
+  /**
+   * 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 namespace EntityTypeUpsertParams {
+  /**
+   * A single entity type definition.
+   */
+  export interface Type {
+    /**
+     * The unique identifier for the entity
+     */
+    id: string;
+
+    /**
+     * Dimension keys used to attribute usage events to instances of this type (e.g.
+     * ["orgId"]). Empty array means no attribution.
+     */
+    attributionKeys: Array<string>;
+
+    /**
+     * The display name for the entity type
+     */
+    displayName: string;
+
+    /**
+     * What this entity type represents and what it is for governing. Omit to preserve
+     * the stored value, or send an empty string or null to clear it.
+     */
+    description?: string | null;
+  }
+}
+
+export declare namespace EntityTypes {
+  export {
+    type EntityTypeListResponse as EntityTypeListResponse,
+    type EntityTypeArchiveResponse as EntityTypeArchiveResponse,
+    type EntityTypeCheckActiveEntitiesResponse as EntityTypeCheckActiveEntitiesResponse,
+    type EntityTypeUpsertResponse as EntityTypeUpsertResponse,
+    type EntityTypeListResponsesMyCursorIDPage as EntityTypeListResponsesMyCursorIDPage,
+    type EntityTypeListParams as EntityTypeListParams,
+    type EntityTypeArchiveParams as EntityTypeArchiveParams,
+    type EntityTypeCheckActiveEntitiesParams as EntityTypeCheckActiveEntitiesParams,
+    type EntityTypeUpsertParams as EntityTypeUpsertParams,
+  };
+}

package/src/resources/v1/events/beta/customers.ts

@@ -13,6 +13,14 @@ export class Customers extends APIResource {
    * 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
+   * const response =
+   *   await client.v1.events.beta.customers.retrieveGovernance(
+   *     'id',
+   *   );
+   * ```
    */
   retrieveGovernance(
     id: string,

package/src/resources/v1/events/data-export/data-export.ts

@@ -21,6 +21,12 @@ export class DataExport extends APIResource {
   /**
    * List the catalog of data-export models the customer can opt into when connecting
    * a destination.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.events.dataExport.listModels();
+   * ```
    */
   listModels(
     params: DataExportListModelsParams | null | undefined = {},
@@ -42,6 +48,12 @@ export class DataExport extends APIResource {
   /**
    * Trigger a sync for one destination or all destinations under the provider
    * entity.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.events.dataExport.triggerSync();
+   * ```
    */
   triggerSync(
     params: DataExportTriggerSyncParams,

package/src/resources/v1/events/data-export/destinations.ts

@@ -11,6 +11,15 @@ export class Destinations extends APIResource {
    * Register a destination on the environment's DATA_EXPORT integration.
    * Lazy-creates the integration row + provider recipient on first call. Idempotent
    * on destinationId.
+   *
+   * @example
+   * ```ts
+   * const destination =
+   *   await client.v1.events.dataExport.destinations.create({
+   *     destinationId: 'x',
+   *     destinationType: 'x',
+   *   });
+   * ```
    */
   create(params: DestinationCreateParams, options?: RequestOptions): APIPromise<DestinationCreateResponse> {
     const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
@@ -31,6 +40,14 @@ export class Destinations extends APIResource {
    * Disconnect a destination: stops the provider sync (deletes the provider
    * destination) and removes it from the DATA_EXPORT integration. Non-destructive —
    * the warehouse table is left intact. Idempotent.
+   *
+   * @example
+   * ```ts
+   * const destination =
+   *   await client.v1.events.dataExport.destinations.delete(
+   *     'x',
+   *   );
+   * ```
    */
   delete(
     destinationID: string,
@@ -54,6 +71,15 @@ export class Destinations extends APIResource {
    * Update a destination's entity selection. Pushes the new enabled_models to the
    * provider first, then persists the selection. Applies on the next scheduled
    * transfer.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.events.dataExport.destinations.updateSelection(
+   *     'x',
+   *     { enabledModels: ['x'], integrationId: 'x' },
+   *   );
+   * ```
    */
   updateSelection(
     destinationID: string,

package/src/resources/v1/events/events.ts

@@ -26,6 +26,14 @@ export class Events extends APIResource {
    * Estimates the credit cost of a usage event without ingesting it. Returns the
    * estimated cost per credit currency, the current balance, and the balance after
    * the estimated consumption.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.events.estimate({
+   *   customerId: 'customerId',
+   *   eventName: 'x',
+   * });
+   * ```
    */
   estimate(params: EventEstimateParams, options?: RequestOptions): APIPromise<EventEstimateResponse> {
     const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
@@ -45,6 +53,19 @@ export class Events extends APIResource {
   /**
    * Reports raw usage events for event-based metering. Events are validated and
    * stored synchronously, then aggregated into usage totals asynchronously.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.events.report({
+   *   events: [
+   *     {
+   *       customerId: 'customerId',
+   *       eventName: 'x',
+   *       idempotencyKey: 'x',
+   *     },
+   *   ],
+   * });
+   * ```
    */
   report(params: EventReportParams, options?: RequestOptions): APIPromise<EventReportResponse> {
     const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;

package/src/resources/v1/features.ts

@@ -13,6 +13,13 @@ import { path } from '../../internal/utils/path';
 export class Features extends APIResource {
   /**
    * Archives a feature, preventing it from being used in new entitlements.
+   *
+   * @example
+   * ```ts
+   * const feature = await client.v1.features.archiveFeature(
+   *   'x',
+   * );
+   * ```
    */
   archiveFeature(
     id: string,
@@ -34,6 +41,15 @@ export class Features extends APIResource {
 
   /**
    * Creates a new feature with the specified type, metering, and configuration.
+   *
+   * @example
+   * ```ts
+   * const feature = await client.v1.features.createFeature({
+   *   id: 'id',
+   *   displayName: 'displayName',
+   *   featureType: 'BOOLEAN',
+   * });
+   * ```
    */
   createFeature(params: FeatureCreateFeatureParams, options?: RequestOptions): APIPromise<Feature> {
     const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
@@ -52,6 +68,14 @@ export class Features extends APIResource {
 
   /**
    * Retrieves a paginated list of features in the environment.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const featureListFeaturesResponse of client.v1.features.listFeatures()) {
+   *   // ...
+   * }
+   * ```
    */
   listFeatures(
     params: FeatureListFeaturesParams | null | undefined = {},
@@ -73,6 +97,13 @@ export class Features extends APIResource {
 
   /**
    * Retrieves a feature by its unique identifier.
+   *
+   * @example
+   * ```ts
+   * const feature = await client.v1.features.retrieveFeature(
+   *   'x',
+   * );
+   * ```
    */
   retrieveFeature(
     id: string,
@@ -94,6 +125,13 @@ export class Features extends APIResource {
 
   /**
    * Restores an archived feature, allowing it to be used in entitlements again.
+   *
+   * @example
+   * ```ts
+   * const feature = await client.v1.features.unarchiveFeature(
+   *   'x',
+   * );
+   * ```
    */
   unarchiveFeature(
     id: string,
@@ -116,6 +154,11 @@ export class Features extends APIResource {
   /**
    * Updates an existing feature's properties such as display name, description, and
    * configuration.
+   *
+   * @example
+   * ```ts
+   * const feature = await client.v1.features.updateFeature('x');
+   * ```
    */
   updateFeature(
     id: string,

package/src/resources/v1/index.ts

@@ -81,6 +81,18 @@ export {
   type CustomerListInvoicesResponsesMyCursorIDPage,
   type CustomerListResourcesResponsesMyCursorIDPage,
 } from './customers/index';
+export {
+  EntityTypes,
+  type EntityTypeListResponse,
+  type EntityTypeArchiveResponse,
+  type EntityTypeCheckActiveEntitiesResponse,
+  type EntityTypeUpsertResponse,
+  type EntityTypeListParams,
+  type EntityTypeArchiveParams,
+  type EntityTypeCheckActiveEntitiesParams,
+  type EntityTypeUpsertParams,
+  type EntityTypeListResponsesMyCursorIDPage,
+} from './entity-types';
 export {
   Events,
   type EventEstimateResponse,

package/src/resources/v1/plans/entitlements.ts

@@ -9,6 +9,14 @@ import { path } from '../../../internal/utils/path';
 export class Entitlements extends APIResource {
   /**
    * Creates one or more entitlements (feature or credit) on a draft plan.
+   *
+   * @example
+   * ```ts
+   * const entitlement =
+   *   await client.v1.plans.entitlements.create('planId', {
+   *     entitlements: [{ id: 'id', type: 'FEATURE' }],
+   *   });
+   * ```
    */
   create(
     planID: string,
@@ -31,6 +39,15 @@ export class Entitlements extends APIResource {
 
   /**
    * Updates an existing entitlement on a draft plan.
+   *
+   * @example
+   * ```ts
+   * const planEntitlement =
+   *   await client.v1.plans.entitlements.update('id', {
+   *     planId: 'planId',
+   *     type: 'FEATURE',
+   *   });
+   * ```
    */
   update(id: string, params: EntitlementUpdateParams, options?: RequestOptions): APIPromise<PlanEntitlement> {
     const { planId, 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
@@ -49,6 +66,12 @@ export class Entitlements extends APIResource {
 
   /**
    * Retrieves a list of entitlements for a plan.
+   *
+   * @example
+   * ```ts
+   * const entitlements =
+   *   await client.v1.plans.entitlements.list('planId');
+   * ```
    */
   list(
     planID: string,
@@ -70,6 +93,14 @@ export class Entitlements extends APIResource {
 
   /**
    * Deletes an entitlement from a draft plan.
+   *
+   * @example
+   * ```ts
+   * const planEntitlement =
+   *   await client.v1.plans.entitlements.delete('id', {
+   *     planId: 'planId',
+   *   });
+   * ```
    */
   delete(id: string, params: EntitlementDeleteParams, options?: RequestOptions): APIPromise<PlanEntitlement> {
     const { planId, 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID } = params;