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

package/src/resources/v1/customers/entities/entities.ts

@@ -0,0 +1,470 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../../core/resource';
+import * as EntitlementsAPI from './entitlements';
+import {
+  EntitlementListParams,
+  EntitlementListResponse,
+  EntitlementListResponsesMyCursorIDPage,
+  EntitlementUpsertParams,
+  EntitlementUpsertResponse,
+  Entitlements,
+} from './entitlements';
+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 Entities extends APIResource {
+  entitlements: EntitlementsAPI.Entitlements = new EntitlementsAPI.Entitlements(this._client);
+
+  /**
+   * Retrieves a single entity for the given customer by its identifier.
+   *
+   * @example
+   * ```ts
+   * const entity = await client.v1.customers.entities.retrieve(
+   *   'x',
+   *   { id: 'id' },
+   * );
+   * ```
+   */
+  retrieve(
+    entityID: string,
+    params: EntityRetrieveParams,
+    options?: RequestOptions,
+  ): APIPromise<EntityRetrieveResponse> {
+    const { id, 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID } = params;
+    return this._client.get(path`/api/v1/customers/${id}/entities/${entityID}`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Retrieves a paginated list of entities for the given customer.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const entityListResponse of client.v1.customers.entities.list(
+   *   'id',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    id: string,
+    params: EntityListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<EntityListResponsesMyCursorIDPage, EntityListResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...query } = params ?? {};
+    return this._client.getAPIList(
+      path`/api/v1/customers/${id}/entities`,
+      MyCursorIDPage<EntityListResponse>,
+      {
+        query,
+        ...options,
+        headers: buildHeaders([
+          {
+            ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+            ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+          },
+          options?.headers,
+        ]),
+      },
+    );
+  }
+
+  /**
+   * Archives entities in bulk for the given customer by id. Upsert an archived
+   * entity to restore it.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.customers.entities.archive(
+   *   'id',
+   *   { ids: ['user-7f3a0c1d', 'user-c4d1b2e9'] },
+   * );
+   * ```
+   */
+  archive(
+    id: string,
+    params: EntityArchiveParams,
+    options?: RequestOptions,
+  ): APIPromise<EntityArchiveResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
+    return this._client.post(path`/api/v1/customers/${id}/entities/archive`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Creates or updates entities in bulk for the given customer. Existing entities
+   * matched by id are updated; new ids are created. An upsert of an archived entity
+   * restores it. An entity on an archived entity type fails with 400.
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.customers.entities.upsert(
+   *   'id',
+   *   {
+   *     entities: [
+   *       {
+   *         id: 'user-7f3a0c1d',
+   *         displayName: 'Jane Doe',
+   *         entityTypeId: 'user',
+   *         metadata: { email: 'jane@acme.com', role: 'admin' },
+   *       },
+   *       {
+   *         id: 'user-c4d1b2e9',
+   *         displayName: 'John Roe',
+   *         entityTypeId: 'user',
+   *         metadata: { email: 'john@acme.com' },
+   *       },
+   *     ],
+   *   },
+   * );
+   * ```
+   */
+  upsert(id: string, params: EntityUpsertParams, options?: RequestOptions): APIPromise<EntityUpsertResponse> {
+    const { 'X-ACCOUNT-ID': xAccountID, 'X-ENVIRONMENT-ID': xEnvironmentID, ...body } = params;
+    return this._client.put(path`/api/v1/customers/${id}/entities`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAccountID != null ? { 'X-ACCOUNT-ID': xAccountID } : undefined),
+          ...(xEnvironmentID != null ? { 'X-ENVIRONMENT-ID': xEnvironmentID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export type EntityListResponsesMyCursorIDPage = MyCursorIDPage<EntityListResponse>;
+
+/**
+ * Response object
+ */
+export interface EntityRetrieveResponse {
+  /**
+   * A stored entity instance tracked by the governance service for a given customer
+   */
+  data: EntityRetrieveResponse.Data;
+}
+
+export namespace EntityRetrieveResponse {
+  /**
+   * A stored entity instance tracked by the governance service for a given customer
+   */
+  export interface Data {
+    /**
+     * The unique identifier for the entity
+     */
+    id: string;
+
+    /**
+     * Timestamp of when the record was deleted
+     */
+    archivedAt: string | null;
+
+    /**
+     * Timestamp of when the record was created
+     */
+    createdAt: string;
+
+    /**
+     * Human-readable name for the entity, or null when none is set — in which case
+     * clients display the entity ID
+     */
+    displayName: string | null;
+
+    /**
+     * The entity type identifier this entity instantiates
+     */
+    entityTypeId: string;
+
+    /**
+     * Free-form key/value metadata attached to the entity
+     */
+    metadata: { [key: string]: string };
+
+    /**
+     * Timestamp of when the record was last updated
+     */
+    updatedAt: string;
+  }
+}
+
+/**
+ * A stored entity instance tracked by the governance service for a given customer
+ */
+export interface EntityListResponse {
+  /**
+   * The unique identifier for the entity
+   */
+  id: string;
+
+  /**
+   * Timestamp of when the record was deleted
+   */
+  archivedAt: string | null;
+
+  /**
+   * Timestamp of when the record was created
+   */
+  createdAt: string;
+
+  /**
+   * Human-readable name for the entity, or null when none is set — in which case
+   * clients display the entity ID
+   */
+  displayName: string | null;
+
+  /**
+   * The entity type identifier this entity instantiates
+   */
+  entityTypeId: string;
+
+  /**
+   * Free-form key/value metadata attached to the entity
+   */
+  metadata: { [key: string]: string };
+
+  /**
+   * Timestamp of when the record was last updated
+   */
+  updatedAt: string;
+}
+
+/**
+ * Wrapped response echoing the ids that were acted on by an archive/unarchive call
+ */
+export interface EntityArchiveResponse {
+  /**
+   * List of entity identifiers that were acted on
+   */
+  data: EntityArchiveResponse.Data;
+}
+
+export namespace EntityArchiveResponse {
+  /**
+   * List of entity identifiers that were acted on
+   */
+  export interface Data {
+    /**
+     * Entity identifiers to act on
+     */
+    ids: Array<string>;
+  }
+}
+
+/**
+ * List of entities created or updated by an upsert request
+ */
+export interface EntityUpsertResponse {
+  data: Array<EntityUpsertResponse.Data>;
+}
+
+export namespace EntityUpsertResponse {
+  /**
+   * A stored entity instance tracked by the governance service for a given customer
+   */
+  export interface Data {
+    /**
+     * The unique identifier for the entity
+     */
+    id: string;
+
+    /**
+     * Timestamp of when the record was deleted
+     */
+    archivedAt: string | null;
+
+    /**
+     * Timestamp of when the record was created
+     */
+    createdAt: string;
+
+    /**
+     * Human-readable name for the entity, or null when none is set — in which case
+     * clients display the entity ID
+     */
+    displayName: string | null;
+
+    /**
+     * The entity type identifier this entity instantiates
+     */
+    entityTypeId: string;
+
+    /**
+     * Free-form key/value metadata attached to the entity
+     */
+    metadata: { [key: string]: string };
+
+    /**
+     * Timestamp of when the record was last updated
+     */
+    updatedAt: string;
+  }
+}
+
+export interface EntityRetrieveParams {
+  /**
+   * Path param: The customer identifier (owner) the entity belongs to
+   */
+  id: 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 EntityListParams extends MyCursorIDPageParams {
+  /**
+   * Query param: Filter results to entities of a specific entity type, by the type's
+   * ID
+   */
+  entityTypeId?: string;
+
+  /**
+   * Query param: Whether to include archived entities. 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 EntityArchiveParams {
+  /**
+   * Body param: Entity 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 EntityUpsertParams {
+  /**
+   * Body param: List of entities to create or update (1-100 entries)
+   */
+  entities: Array<EntityUpsertParams.Entity>;
+
+  /**
+   * 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 EntityUpsertParams {
+  /**
+   * A single entity to create or update.
+   */
+  export interface Entity {
+    /**
+     * The unique identifier for the entity
+     */
+    id: string;
+
+    /**
+     * Human-readable name for the entity. Omit to preserve the stored value, or send
+     * an empty string or null to clear it.
+     */
+    displayName?: string | null;
+
+    /**
+     * The entity type ID this entity instantiates. Required when creating a new
+     * entity; on a re-upsert may be omitted to preserve the existing type. Governance
+     * returns 400 if missing on create.
+     */
+    entityTypeId?: string;
+
+    /**
+     * Free-form key/value metadata. Patch semantics: empty-string value removes a key,
+     * omitted keys are preserved.
+     */
+    metadata?: { [key: string]: string };
+  }
+}
+
+Entities.Entitlements = Entitlements;
+
+export declare namespace Entities {
+  export {
+    type EntityRetrieveResponse as EntityRetrieveResponse,
+    type EntityListResponse as EntityListResponse,
+    type EntityArchiveResponse as EntityArchiveResponse,
+    type EntityUpsertResponse as EntityUpsertResponse,
+    type EntityListResponsesMyCursorIDPage as EntityListResponsesMyCursorIDPage,
+    type EntityRetrieveParams as EntityRetrieveParams,
+    type EntityListParams as EntityListParams,
+    type EntityArchiveParams as EntityArchiveParams,
+    type EntityUpsertParams as EntityUpsertParams,
+  };
+
+  export {
+    Entitlements as Entitlements,
+    type EntitlementListResponse as EntitlementListResponse,
+    type EntitlementUpsertResponse as EntitlementUpsertResponse,
+    type EntitlementListResponsesMyCursorIDPage as EntitlementListResponsesMyCursorIDPage,
+    type EntitlementListParams as EntitlementListParams,
+    type EntitlementUpsertParams as EntitlementUpsertParams,
+  };
+}