@rippling/rippling-sdk 0.2.0-alpha.62 → 0.2.0-alpha.63

package/src/resources/app-users.ts

@@ -0,0 +1,270 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as BusinessPartnersAPI from './business-partners';
+import * as WorkersAPI from './workers';
+import { APIPromise } from '../core/api-promise';
+import { PageCursorURL, PagePromise } from '../core/pagination';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Mappings between Rippling workers and their user accounts in third-party apps
+ */
+export class AppUsers extends APIResource {
+  /**
+   * A list of app users.
+   *
+   * - Requires: `API Tier 1`
+   * - Filterable fields: `worker_id`, `spoke_user_identifier`, `app_handle`,
+   *   `created_at`, `updated_at`
+   * - Expandable fields: `worker`
+   * - Sortable fields: `id`, `created_at`, `updated_at`
+   */
+  list(
+    query: AppUserListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<AppUserListResponsesPageCursorURL, AppUserListResponse> {
+    return this._client.getAPIList('/app-users/', PageCursorURL<AppUserListResponse>, { query, ...options });
+  }
+
+  /**
+   * Retrieve a specific app user
+   */
+  retrieve(
+    id: string,
+    query: AppUserRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<AppUserRetrieveResponse> {
+    return this._client.get(path`/app-users/${id}/`, { query, ...options });
+  }
+}
+
+export type AppUserListResponsesPageCursorURL = PageCursorURL<AppUserListResponse>;
+
+/**
+ * Maps a Rippling worker (if any) to their user account in a third-party
+ *     app (e.g. Slack, Jira, GitHub). Sourced from SpokeUser records.
+ *
+ *     Includes orphan accounts — third-party app accounts with no matching
+ *     Rippling worker (`worker_id=None`, `match_state=NOT_MATCHED`). These are
+ *     the primary signal for IT-admin triage. Uses `BaseResourceDTO` rather
+ *     than `BaseEmployeeResourceDTO` so the platform's role-based auto-filter
+ *     does not silently drop orphans for non-admin tokens. Company scoping is
+ *     enforced explicitly in `AppUsersAPIViewSet.get_queryset`; the `app-users.read`
+ *     scope is the access gate.
+ *
+ *     Resource name aligns with how the product surfaces these in the UI
+ *     ("Slack account", "GitHub account") and matches the equivalent concept
+ *     in Okta's IAM API (AppUser).
+ *
+ *     Designed for point lookups: list endpoint requires at least one filter
+ *     on `worker_id` or `spoke_user_identifier` to prevent bulk enumeration of the
+ *     org's identity graph across connected apps.
+ *
+ *     `spoke_user_identifier` reads `SpokeUser.spokeId` — the user identifier
+ *     stored for the third-party account. Depending on the integration, this may
+ *     be an email, username, account handle, or app-specific user id.
+ */
+export interface AppUserListResponse {
+  /**
+   * Identifier field
+   */
+  id: string;
+
+  /**
+   * Record creation date
+   */
+  created_at: string;
+
+  /**
+   * Record update date
+   */
+  updated_at: string;
+
+  /**
+   * Human-readable display name for the third-party app (e.g. 'Slack', 'GitHub').
+   * Sourced from the customer-configured SpokeOwner.app_display_name; falls back to
+   * a title-cased app handle when the customer hasn't set one.
+   */
+  app_display_name?: string;
+
+  /**
+   * Machine-readable identifier for the third-party app (e.g. 'slack', 'jira',
+   * 'asana'). Stable across the App Shop catalog.
+   */
+  app_handle?: string;
+
+  /**
+   * The user's email address in the third-party app, if known. Null when the app
+   * does not expose an email or Rippling did not capture one.
+   */
+  external_email?: string;
+
+  /**
+   * The user's display name in the third-party app, if known. Null when the app does
+   * not surface a separate username.
+   */
+  external_username?: string;
+
+  /**
+   * Whether this third-party account has been matched to a Rippling worker.
+   */
+  match_state?: 'MATCHED' | 'NOT_MATCHED' | 'IGNORED';
+
+  /**
+   * Provisioning lifecycle state of this account in the third-party app.
+   */
+  push_state?:
+    | 'INIT'
+    | 'EMPLOYEE_CONFIRMATION_PENDING'
+    | 'EMPLOYEE_CONFIRMATION_ACCEPTED'
+    | 'EMPLOYEE_CONFIRMATION_REJECTED'
+    | 'INVITE_PENDING'
+    | 'INVITE_CONFIRMED'
+    | 'INVITE_FAILED'
+    | 'CREATE_PENDING'
+    | 'CREATE_CONFIRMED'
+    | 'CREATE_FAILED'
+    | 'DELETE_PENDING'
+    | 'DELETE_CONFIRMED'
+    | 'DELETE_FAILED'
+    | 'SUSPEND_PENDING'
+    | 'SUSPEND_CONFIRMED'
+    | 'SUSPEND_FAILED';
+
+  /**
+   * Identifier for the user's account in the third-party app workspace. Depending on
+   * the integration, this may be an email, username, account handle, or app-specific
+   * user id.
+   */
+  spoke_user_identifier?: string;
+
+  /**
+   * The Rippling worker associated with this external app account. Expanding this
+   * field requires both `app-users.read` and `workers.read` scopes.
+   *
+   * Expandable field
+   */
+  worker?: WorkersAPI.Worker;
+
+  /**
+   * ID of the Rippling worker associated with this external app account.
+   */
+  worker_id?: string;
+}
+
+/**
+ * Meta information for the response.
+ */
+export interface AppUserRetrieveResponse extends BusinessPartnersAPI.Meta {
+  /**
+   * Identifier field
+   */
+  id: string;
+
+  /**
+   * Record creation date
+   */
+  created_at: string;
+
+  /**
+   * Record update date
+   */
+  updated_at: string;
+
+  /**
+   * Human-readable display name for the third-party app (e.g. 'Slack', 'GitHub').
+   * Sourced from the customer-configured SpokeOwner.app_display_name; falls back to
+   * a title-cased app handle when the customer hasn't set one.
+   */
+  app_display_name?: string;
+
+  /**
+   * Machine-readable identifier for the third-party app (e.g. 'slack', 'jira',
+   * 'asana'). Stable across the App Shop catalog.
+   */
+  app_handle?: string;
+
+  /**
+   * The user's email address in the third-party app, if known. Null when the app
+   * does not expose an email or Rippling did not capture one.
+   */
+  external_email?: string;
+
+  /**
+   * The user's display name in the third-party app, if known. Null when the app does
+   * not surface a separate username.
+   */
+  external_username?: string;
+
+  /**
+   * Whether this third-party account has been matched to a Rippling worker.
+   */
+  match_state?: 'MATCHED' | 'NOT_MATCHED' | 'IGNORED';
+
+  /**
+   * Provisioning lifecycle state of this account in the third-party app.
+   */
+  push_state?:
+    | 'INIT'
+    | 'EMPLOYEE_CONFIRMATION_PENDING'
+    | 'EMPLOYEE_CONFIRMATION_ACCEPTED'
+    | 'EMPLOYEE_CONFIRMATION_REJECTED'
+    | 'INVITE_PENDING'
+    | 'INVITE_CONFIRMED'
+    | 'INVITE_FAILED'
+    | 'CREATE_PENDING'
+    | 'CREATE_CONFIRMED'
+    | 'CREATE_FAILED'
+    | 'DELETE_PENDING'
+    | 'DELETE_CONFIRMED'
+    | 'DELETE_FAILED'
+    | 'SUSPEND_PENDING'
+    | 'SUSPEND_CONFIRMED'
+    | 'SUSPEND_FAILED';
+
+  /**
+   * Identifier for the user's account in the third-party app workspace. Depending on
+   * the integration, this may be an email, username, account handle, or app-specific
+   * user id.
+   */
+  spoke_user_identifier?: string;
+
+  /**
+   * The Rippling worker associated with this external app account. Expanding this
+   * field requires both `app-users.read` and `workers.read` scopes.
+   *
+   * Expandable field
+   */
+  worker?: WorkersAPI.Worker;
+
+  /**
+   * ID of the Rippling worker associated with this external app account.
+   */
+  worker_id?: string;
+}
+
+export interface AppUserListParams {
+  cursor?: string;
+
+  expand?: string;
+
+  filter?: string;
+
+  order_by?: string;
+}
+
+export interface AppUserRetrieveParams {
+  expand?: string;
+}
+
+export declare namespace AppUsers {
+  export {
+    type AppUserListResponse as AppUserListResponse,
+    type AppUserRetrieveResponse as AppUserRetrieveResponse,
+    type AppUserListResponsesPageCursorURL as AppUserListResponsesPageCursorURL,
+    type AppUserListParams as AppUserListParams,
+    type AppUserRetrieveParams as AppUserRetrieveParams,
+  };
+}