@stigg/typescript 0.1.0-beta.2 → 0.1.0-beta.21

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

@@ -0,0 +1,354 @@
+// 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 { buildHeaders } from '../../../../../internal/headers';
+import { RequestOptions } from '../../../../../internal/request-options';
+import { path } from '../../../../../internal/utils/path';
+
+export class Entitlements extends APIResource {
+  /**
+   * Experimental — request and response shapes may change without notice. Same
+   * semantics as `Check entitlement`, plus an optional `dimensions` query param that
+   * resolves to per-entity governance limits surfaced as `chains` on the response.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.events.beta.customers.entitlements.check(
+   *     'x',
+   *   );
+   * ```
+   */
+  check(
+    id: string,
+    params: EntitlementCheckParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<EntitlementCheckResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...query } = params ?? {};
+    return this._client.get(path`/api/v1-beta/customers/${id}/entitlements/check`, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+/**
+ * Response object
+ */
+export interface EntitlementCheckResponse {
+  /**
+   * Feature entitlement with optional governance chains attached.
+   */
+  data: EntitlementCheckResponse.Feature | EntitlementCheckResponse.Credit;
+}
+
+export namespace EntitlementCheckResponse {
+  /**
+   * Feature entitlement with optional governance chains attached.
+   */
+  export interface Feature {
+    accessDeniedReason:
+      | 'FeatureNotFound'
+      | 'CustomerNotFound'
+      | 'CustomerIsArchived'
+      | 'CustomerResourceNotFound'
+      | 'NoActiveSubscription'
+      | 'NoFeatureEntitlementInSubscription'
+      | 'RequestedUsageExceedingLimit'
+      | 'RequestedValuesMismatch'
+      | 'BudgetExceeded'
+      | 'Unknown'
+      | 'FeatureTypeMismatch'
+      | 'Revoked'
+      | 'InsufficientCredits'
+      | 'EntitlementNotFound'
+      | null;
+
+    isGranted: boolean;
+
+    type: 'FEATURE';
+
+    /**
+     * Per-entity rollups, one chain per resolved dimension. Omitted when dimensions
+     * was not provided.
+     */
+    chains?: Array<Array<Feature.Chain>>;
+
+    currentUsage?: number;
+
+    /**
+     * Timestamp of the last update to the entitlement grant or configuration.
+     */
+    entitlementUpdatedAt?: string;
+
+    feature?: Feature.Feature;
+
+    hasUnlimitedUsage?: boolean;
+
+    resetPeriod?: 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' | null;
+
+    usageLimit?: number | null;
+
+    /**
+     * The anchor for calculating the usage period for metered entitlements with a
+     * reset period configured
+     */
+    usagePeriodAnchor?: string;
+
+    /**
+     * The end date of the usage period for metered entitlements with a reset period
+     * configured
+     */
+    usagePeriodEnd?: string;
+
+    /**
+     * The start date of the usage period for metered entitlements with a reset period
+     * configured
+     */
+    usagePeriodStart?: string;
+
+    /**
+     * The next time the entitlement should be recalculated
+     */
+    validUntil?: string;
+  }
+
+  export namespace Feature {
+    /**
+     * Per-entity governance node — limit and current usage for a single resolved
+     * entity.
+     */
+    export interface Chain {
+      /**
+       * Amount consumed by this entity in the current cadence period.
+       */
+      currentUsage: number;
+
+      /**
+       * External id of the entity within the customer.
+       */
+      entityId: string;
+
+      /**
+       * Whether this node alone permits the requested usage.
+       */
+      isGranted: boolean;
+
+      /**
+       * Hard usage limit for this node; null when no assignment is configured.
+       */
+      usageLimit: number | null;
+    }
+
+    export interface Feature {
+      /**
+       * The unique reference ID of the entitlement.
+       */
+      id: string;
+
+      /**
+       * The human-readable name of the entitlement, shown in UI elements.
+       */
+      displayName: string;
+
+      /**
+       * The current status of the feature.
+       */
+      featureStatus: 'NEW' | 'SUSPENDED' | 'ACTIVE';
+
+      /**
+       * The type of feature associated with the entitlement.
+       */
+      featureType: 'BOOLEAN' | 'NUMBER' | 'ENUM';
+    }
+  }
+
+  /**
+   * Credit entitlement with optional governance chains attached.
+   */
+  export interface Credit {
+    accessDeniedReason:
+      | 'FeatureNotFound'
+      | 'CustomerNotFound'
+      | 'CustomerIsArchived'
+      | 'CustomerResourceNotFound'
+      | 'NoActiveSubscription'
+      | 'NoFeatureEntitlementInSubscription'
+      | 'RequestedUsageExceedingLimit'
+      | 'RequestedValuesMismatch'
+      | 'BudgetExceeded'
+      | 'Unknown'
+      | 'FeatureTypeMismatch'
+      | 'Revoked'
+      | 'InsufficientCredits'
+      | 'EntitlementNotFound'
+      | null;
+
+    /**
+     * The currency associated with a credit entitlement.
+     */
+    currency: Credit.Currency;
+
+    currentUsage: number;
+
+    isGranted: boolean;
+
+    type: 'CREDIT';
+
+    usageLimit: number;
+
+    /**
+     * Timestamp of the last update to the credit usage.
+     */
+    usageUpdatedAt: string;
+
+    /**
+     * Per-entity rollups, one chain per resolved dimension. Omitted when dimensions
+     * was not provided.
+     */
+    chains?: Array<Array<Credit.Chain>>;
+
+    /**
+     * Timestamp of the last update to the entitlement grant or configuration.
+     */
+    entitlementUpdatedAt?: string;
+
+    /**
+     * The end date of the current billing period for recurring credit grants.
+     */
+    usagePeriodEnd?: string;
+
+    /**
+     * The next time the entitlement should be recalculated
+     */
+    validUntil?: string;
+  }
+
+  export namespace Credit {
+    /**
+     * The currency associated with a credit entitlement.
+     */
+    export interface Currency {
+      /**
+       * The unique identifier of the custom currency.
+       */
+      currencyId: string;
+
+      /**
+       * The display name of the currency.
+       */
+      displayName: string;
+
+      /**
+       * A description of the currency.
+       */
+      description?: string | null;
+
+      /**
+       * Additional metadata associated with the currency.
+       */
+      metadata?: { [key: string]: string } | null;
+
+      /**
+       * The plural form of the currency unit.
+       */
+      unitPlural?: string | null;
+
+      /**
+       * The singular form of the currency unit.
+       */
+      unitSingular?: string | null;
+    }
+
+    /**
+     * Per-entity governance node — limit and current usage for a single resolved
+     * entity.
+     */
+    export interface Chain {
+      /**
+       * Amount consumed by this entity in the current cadence period.
+       */
+      currentUsage: number;
+
+      /**
+       * External id of the entity within the customer.
+       */
+      entityId: string;
+
+      /**
+       * Whether this node alone permits the requested usage.
+       */
+      isGranted: boolean;
+
+      /**
+       * Hard usage limit for this node; null when no assignment is configured.
+       */
+      usageLimit: number | null;
+    }
+  }
+}
+
+export interface EntitlementCheckParams {
+  /**
+   * Query param: Currency ID (refId) to check for credit entitlements. Mutually
+   * exclusive with `featureId`.
+   */
+  currencyId?: string;
+
+  /**
+   * Query param: Optional attribution map (e.g. `dimensions[userId]=u1`). When
+   * provided, the response includes a `chains` array with per-entity governance
+   * limits.
+   */
+  dimensions?: { [key: string]: string };
+
+  /**
+   * Query param: Feature ID (refId) to check. Mutually exclusive with `currencyId`.
+   */
+  featureId?: string;
+
+  /**
+   * Query param: Requested usage amount to evaluate against the entitlement limit
+   * (numeric features only)
+   */
+  requestedUsage?: number;
+
+  /**
+   * Query param: Requested values to evaluate against allowed values (enum features
+   * only)
+   */
+  requestedValues?: Array<string>;
+
+  /**
+   * Query param: Resource ID to scope the entitlement check to a specific resource
+   */
+  resourceId?: 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 declare namespace Entitlements {
+  export {
+    type EntitlementCheckResponse as EntitlementCheckResponse,
+    type EntitlementCheckParams as EntitlementCheckParams,
+  };
+}

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

@@ -0,0 +1,26 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Assignments,
+  type AssignmentListResponse,
+  type AssignmentUpsertResponse,
+  type AssignmentListParams,
+  type AssignmentUpsertParams,
+  type AssignmentListResponsesMyCursorIDPage,
+} from './assignments';
+export { Customers } from './customers';
+export {
+  Entities,
+  type EntityRetrieveResponse,
+  type EntityListResponse,
+  type EntityArchiveResponse,
+  type EntityUnarchiveResponse,
+  type EntityUpsertResponse,
+  type EntityRetrieveParams,
+  type EntityListParams,
+  type EntityArchiveParams,
+  type EntityUnarchiveParams,
+  type EntityUpsertParams,
+  type EntityListResponsesMyCursorIDPage,
+} from './entities';
+export { Entitlements, type EntitlementCheckResponse, type EntitlementCheckParams } from './entitlements';

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

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './customers/index';

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

@@ -0,0 +1,226 @@
+// 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';
+
+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).
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const entityTypeListResponse of client.v1.events.beta.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-beta/entity-types', MyCursorIDPage<EntityTypeListResponse>, {
+      query,
+      ...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.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.v1.events.beta.entityTypes.upsert({
+   *     types: [
+   *       {
+   *         id: 'org',
+   *         displayName: 'Organization',
+   *         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-beta/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;
+
+  /**
+   * 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;
+
+  /**
+   * The display name for the entity type
+   */
+  displayName: string;
+
+  /**
+   * Timestamp of when the record was last updated
+   */
+  updatedAt: string;
+}
+
+/**
+ * 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;
+
+    /**
+     * 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;
+
+    /**
+     * The display name for the entity type
+     */
+    displayName: string;
+
+    /**
+     * Timestamp of when the record was last updated
+     */
+    updatedAt: string;
+  }
+}
+
+export interface EntityTypeListParams extends MyCursorIDPageParams {
+  /**
+   * 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 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;
+  }
+}
+
+export declare namespace EntityTypes {
+  export {
+    type EntityTypeListResponse as EntityTypeListResponse,
+    type EntityTypeUpsertResponse as EntityTypeUpsertResponse,
+    type EntityTypeListResponsesMyCursorIDPage as EntityTypeListResponsesMyCursorIDPage,
+    type EntityTypeListParams as EntityTypeListParams,
+    type EntityTypeUpsertParams as EntityTypeUpsertParams,
+  };
+}

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

@@ -0,0 +1,12 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Beta } from './beta';
+export { Customers } from './customers/index';
+export {
+  EntityTypes,
+  type EntityTypeListResponse,
+  type EntityTypeUpsertResponse,
+  type EntityTypeListParams,
+  type EntityTypeUpsertParams,
+  type EntityTypeListResponsesMyCursorIDPage,
+} from './entity-types';

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

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './beta/index';