@rippling/rippling-sdk 0.2.0-alpha.104 → 0.2.0-alpha.106

package/src/resources/activity-log.ts

@@ -0,0 +1,645 @@
+// 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';
+
+/**
+ * Visible Activity Log events recorded for the company
+ */
+export class ActivityLog extends APIResource {
+  /**
+   * Lists only Activity Log events retained from the last 90 days that are visible
+   * to the caller. Linked child events are omitted. An occurred_at filter before the
+   * retention window returns an empty page, not older history. Full admins and
+   * Activity Log admins see company-wide events; other admins see only events for
+   * app installations they fully administer. A caller with no administered app
+   * installation receives 403. The targets.id filter does not match GROUP or
+   * SPOKE_USER targets.
+   *
+   * - Requires: `Activity Log Platform API`
+   * - Filterable fields: `occurred_at`, `event_type`, `worker_id`, `targets.id`,
+   *   `source_app_handle`
+   * - Expandable fields: `worker`
+   * - Sortable fields: `id`, `created_at`, `updated_at`, `occurred_at`
+   *
+   * @example HTTP
+   * Representative request and response shapes.
+   * ```
+   * GET /activity-log/?filter=filter&expand=expand&order_by=order_by&limit=50&cursor=cursor HTTP/1.1
+   * Host: rest.ripplingapis.com
+   * Accept: application/json
+   * Rippling-Api-Version: 2024-08-01
+   *
+   * HTTP/1.1 200 OK
+   * Content-Type: application/json
+   *
+   * {
+   *   "__meta": {
+   *     "redacted_fields": [
+   *       {
+   *         "name": "date_of_birth",
+   *         "reason": "Insufficient entitlements"
+   *       }
+   *     ]
+   *   },
+   *   "results": [
+   *     {
+   *       "id": "string",
+   *       "created_at": "string",
+   *       "updated_at": "string",
+   *       "occurred_at": "string",
+   *       "event_type": "string",
+   *       "status": "SUCCESS",
+   *       "actor_type": "WORKER",
+   *       "worker_id": "string",
+   *       "worker": {
+   *         "id": "string",
+   *         "created_at": "string",
+   *         "updated_at": "string",
+   *         "user_id": "string",
+   *         "user": {},
+   *         "is_manager": "string",
+   *         "manager_id": "string",
+   *         "manager": {},
+   *         "legal_entity_id": "string",
+   *         "legal_entity": {},
+   *         "country": "AF",
+   *         "start_date": "string",
+   *         "end_date": "string",
+   *         "number": "string",
+   *         "work_email": "string",
+   *         "personal_email": "string",
+   *         "status": "INIT",
+   *         "location": {},
+   *         "employment_type_id": "string",
+   *         "employment_type": {},
+   *         "gender": "MALE",
+   *         "date_of_birth": "string",
+   *         "race": "BLACK",
+   *         "ethnicity": "HISPANIC_OR_LATINO",
+   *         "citizenship": "AF",
+   *         "compensation_id": "string",
+   *         "compensation": {},
+   *         "overtime_exemption": "EXEMPT",
+   *         "department_id": "string",
+   *         "department": {},
+   *         "teams_id": [],
+   *         "teams": [],
+   *         "title": "string",
+   *         "title_effective_date": "string",
+   *         "level_id": "string",
+   *         "level": {},
+   *         "job_function_id": "string",
+   *         "job_function": {},
+   *         "termination_details": {},
+   *         "pay_schedule_id": "string",
+   *         "work_schedule": {},
+   *         "compensation_grade": {},
+   *         "original_start_date": "string",
+   *         "custom_fields": [],
+   *         "country_fields": {},
+   *         "business_partners_id": [],
+   *         "business_partners": []
+   *       },
+   *       "targets": [
+   *         {}
+   *       ],
+   *       "source_app_handle": "string",
+   *       "reason": {
+   *         "code": "string",
+   *         "message": "string"
+   *       },
+   *       "request_context": {
+   *         "ip_address": "string",
+   *         "device": "string",
+   *         "browser": "string",
+   *         "operating_system": "string",
+   *         "city": "string",
+   *         "state": "string",
+   *         "country": "string",
+   *         "latitude": "string",
+   *         "longitude": "string",
+   *         "accuracy_radius": "string"
+   *       }
+   *     }
+   *   ],
+   *   "next_link": "string"
+   * }
+   * ```
+   */
+  list(
+    query: ActivityLogListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<ActivityLogListResponsesPageCursorURL, ActivityLogListResponse> {
+    return this._client.getAPIList('/activity-log/', PageCursorURL<ActivityLogListResponse>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Retrieves one Activity Log event from the same 90-day visibility set as the list
+   * endpoint. Full admins and Activity Log admins can retrieve company-wide events;
+   * other admins can retrieve only events for app installations they fully
+   * administer. An admin with no administered app installation receives 403. An ID
+   * outside that visibility set, including an event for an installation the caller
+   * does not administer, returns 404.
+   *
+   * @example HTTP
+   * Representative request and response shapes.
+   * ```
+   * GET /activity-log/{id}/?expand=expand HTTP/1.1
+   * Host: rest.ripplingapis.com
+   * Accept: application/json
+   * Rippling-Api-Version: 2024-08-01
+   *
+   * HTTP/1.1 200 OK
+   * Content-Type: application/json
+   *
+   * {
+   *   "__meta": {
+   *     "redacted_fields": [
+   *       {}
+   *     ]
+   *   }
+   * }
+   * ```
+   */
+  retrieve(
+    id: string,
+    query: ActivityLogRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ActivityLogRetrieveResponse> {
+    return this._client.get(path`/activity-log/${id}/`, { query, ...options });
+  }
+}
+
+export type ActivityLogListResponsesPageCursorURL = PageCursorURL<ActivityLogListResponse>;
+
+/**
+ * One visible Activity Log event retained from the last 90 days.
+ */
+export interface ActivityLogListResponse {
+  /**
+   * Identifier field
+   */
+  id: string;
+
+  /**
+   * Record creation date
+   */
+  created_at: string;
+
+  /**
+   * Record update date
+   */
+  updated_at: string;
+
+  /**
+   * The kind of actor that initiated the event. WORKER is a Rippling worker;
+   * INTERNAL_BY_WORKER is an internal API request triggered by a worker; SYSTEM is
+   * an automated Rippling system process; EXTERNAL is an external system or
+   * integration; RIPPLING_MDM is Rippling MDM; PARTNER is a Rippling partner, but
+   * the partner identity is not returned; and PROXY is Rippling staff or support
+   * acting through proxy. Null when no actor type was recorded.
+   */
+  actor_type?: 'WORKER' | 'SYSTEM' | 'EXTERNAL' | 'INTERNAL_BY_WORKER' | 'RIPPLING_MDM' | 'PARTNER' | 'PROXY';
+
+  /**
+   * The open UPPER_SNAKE_CASE Activity Log code, such as USER_LOGIN_SUCCESS. New
+   * codes can appear over time.
+   */
+  event_type?: string;
+
+  /**
+   * The activity occurrence time as an ISO 8601 UTC timestamp. Unlike created_at,
+   * which records when the Activity Log record was persisted, occurred_at records
+   * when the underlying activity happened.
+   */
+  occurred_at?: string;
+
+  /**
+   * Why the activity occurred. Null when no reason was recorded.
+   */
+  reason?: ActivityLogListResponse.Reason;
+
+  /**
+   * Request and approximate location details captured for the activity. Null for
+   * non-request events.
+   */
+  request_context?: ActivityLogListResponse.RequestContext;
+
+  /**
+   * The public app handle used by GET /app-users/ for the Rippling app associated
+   * with the activity. Null when the activity is not app-specific.
+   */
+  source_app_handle?: string;
+
+  /**
+   * The outcome of the activity. SUCCESS means the activity completed successfully;
+   * FAILURE means the activity failed. Null when no outcome was recorded.
+   */
+  status?: 'SUCCESS' | 'FAILURE';
+
+  /**
+   * The resources affected by the activity. Empty when no targets were recorded.
+   */
+  targets?: Array<ActivityLogListResponse.Target>;
+
+  /**
+   * The worker who initiated the activity. Request with expand=worker and the
+   * workers.read OAuth scope to return the Worker resource.
+   *
+   * Expandable field
+   */
+  worker?: WorkersAPI.Worker;
+
+  /**
+   * The Platform worker ID from GET /workers/{id}/ when the actor is a worker. Null
+   * when the actor is not a worker.
+   */
+  worker_id?: string;
+}
+
+export namespace ActivityLogListResponse {
+  /**
+   * Why the activity occurred. Null when no reason was recorded.
+   */
+  export interface Reason {
+    /**
+     * The machine-readable reason code recorded for the event. Null when no reason was
+     * recorded.
+     */
+    code?: string;
+
+    /**
+     * The human-readable meaning of the reason code. Null when no reason was recorded.
+     */
+    message?: string;
+  }
+
+  /**
+   * Request and approximate location details captured for the activity. Null for
+   * non-request events.
+   */
+  export interface RequestContext {
+    /**
+     * The accuracy radius of the IP-derived location in kilometers. Null without the
+     * activity-log.sensitive-data.read scope or when geolocation is unresolved.
+     */
+    accuracy_radius?: number;
+
+    /**
+     * The browser family parsed from the request user agent. Returned with the
+     * activity-log.read scope. Null when unavailable.
+     */
+    browser?: string;
+
+    /**
+     * The city resolved from the request IP address. Null without the
+     * activity-log.sensitive-data.read scope or when geolocation is unresolved.
+     */
+    city?: string;
+
+    /**
+     * The country resolved from the request IP address. Null without the
+     * activity-log.sensitive-data.read scope or when geolocation is unresolved.
+     */
+    country?: string;
+
+    /**
+     * The device family parsed from the request user agent. Returned with the
+     * activity-log.read scope. Null when unavailable.
+     */
+    device?: string;
+
+    /**
+     * The IPv4 or IPv6 address associated with the request. Null without the
+     * activity-log.sensitive-data.read scope.
+     */
+    ip_address?: string;
+
+    /**
+     * The approximate latitude in decimal degrees resolved from the request IP
+     * address. Null without the activity-log.sensitive-data.read scope or when
+     * geolocation is unresolved.
+     */
+    latitude?: number;
+
+    /**
+     * The approximate longitude in decimal degrees resolved from the request IP
+     * address. Null without the activity-log.sensitive-data.read scope or when
+     * geolocation is unresolved.
+     */
+    longitude?: number;
+
+    /**
+     * The operating system parsed from the request user agent. Returned with the
+     * activity-log.read scope. Null when unavailable.
+     */
+    operating_system?: string;
+
+    /**
+     * The state or region resolved from the request IP address. Null without the
+     * activity-log.sensitive-data.read scope or when geolocation is unresolved.
+     */
+    state?: string;
+  }
+
+  /**
+   * A resource or internal entity affected by an Activity Log event.
+   */
+  export interface Target {
+    /**
+     * The ID of the resource affected by the event. Null when the event target has no
+     * referenced resource. Filtering by targets.id is not supported for GROUP or
+     * SPOKE_USER targets.
+     */
+    id?: string;
+
+    /**
+     * The kind of target. WORKER uses the worker ID from GET /workers/{id}/; DEVICE
+     * uses the device ID from GET /devices/{id}/; GROUP uses the group ID from GET
+     * /supergroups/{id}/; SPOKE_USER uses the app-user ID from GET /app-users/{id}/.
+     * COMPUTER is deprecated in favor of DEVICE and its ID is not a Platform resource
+     * ID. IDs for SPOKE, RPASS_ITEM, RPASS_FOLDER, SCHEDULED_CHANGE, BDR_POLICY,
+     * AUTH_RULE, COMPANY_AUTH_RULE, USER_ACCOUNT, HARDWARE_SCRIPT,
+     * HARDWARE_CONFIGURATION, SOFTWARE_UPDATE, OS_SOFTWARE_UPDATE, WORK_EMAIL_POLICY,
+     * OFFBOARDING_POLICY, REMOTE_ACCESS_SESSION_OPTIONS, and
+     * REMOTE_ACCESS_SESSION_ERROR_DETAILS are not Platform resource IDs.
+     */
+    type?:
+      | 'WORKER'
+      | 'SPOKE'
+      | 'RPASS_ITEM'
+      | 'SPOKE_USER'
+      | 'GROUP'
+      | 'RPASS_FOLDER'
+      | 'SCHEDULED_CHANGE'
+      | 'COMPUTER'
+      | 'BDR_POLICY'
+      | 'AUTH_RULE'
+      | 'COMPANY_AUTH_RULE'
+      | 'DEVICE'
+      | 'USER_ACCOUNT'
+      | 'HARDWARE_SCRIPT'
+      | 'HARDWARE_CONFIGURATION'
+      | 'SOFTWARE_UPDATE'
+      | 'OS_SOFTWARE_UPDATE'
+      | 'WORK_EMAIL_POLICY'
+      | 'OFFBOARDING_POLICY'
+      | 'REMOTE_ACCESS_SESSION_OPTIONS'
+      | 'REMOTE_ACCESS_SESSION_ERROR_DETAILS';
+  }
+}
+
+/**
+ * Meta information for the response.
+ */
+export interface ActivityLogRetrieveResponse extends BusinessPartnersAPI.Meta {
+  /**
+   * Identifier field
+   */
+  id: string;
+
+  /**
+   * Record creation date
+   */
+  created_at: string;
+
+  /**
+   * Record update date
+   */
+  updated_at: string;
+
+  /**
+   * The kind of actor that initiated the event. WORKER is a Rippling worker;
+   * INTERNAL_BY_WORKER is an internal API request triggered by a worker; SYSTEM is
+   * an automated Rippling system process; EXTERNAL is an external system or
+   * integration; RIPPLING_MDM is Rippling MDM; PARTNER is a Rippling partner, but
+   * the partner identity is not returned; and PROXY is Rippling staff or support
+   * acting through proxy. Null when no actor type was recorded.
+   */
+  actor_type?: 'WORKER' | 'SYSTEM' | 'EXTERNAL' | 'INTERNAL_BY_WORKER' | 'RIPPLING_MDM' | 'PARTNER' | 'PROXY';
+
+  /**
+   * The open UPPER_SNAKE_CASE Activity Log code, such as USER_LOGIN_SUCCESS. New
+   * codes can appear over time.
+   */
+  event_type?: string;
+
+  /**
+   * The activity occurrence time as an ISO 8601 UTC timestamp. Unlike created_at,
+   * which records when the Activity Log record was persisted, occurred_at records
+   * when the underlying activity happened.
+   */
+  occurred_at?: string;
+
+  /**
+   * Why the activity occurred. Null when no reason was recorded.
+   */
+  reason?: ActivityLogRetrieveResponse.Reason;
+
+  /**
+   * Request and approximate location details captured for the activity. Null for
+   * non-request events.
+   */
+  request_context?: ActivityLogRetrieveResponse.RequestContext;
+
+  /**
+   * The public app handle used by GET /app-users/ for the Rippling app associated
+   * with the activity. Null when the activity is not app-specific.
+   */
+  source_app_handle?: string;
+
+  /**
+   * The outcome of the activity. SUCCESS means the activity completed successfully;
+   * FAILURE means the activity failed. Null when no outcome was recorded.
+   */
+  status?: 'SUCCESS' | 'FAILURE';
+
+  /**
+   * The resources affected by the activity. Empty when no targets were recorded.
+   */
+  targets?: Array<ActivityLogRetrieveResponse.Target>;
+
+  /**
+   * The worker who initiated the activity. Request with expand=worker and the
+   * workers.read OAuth scope to return the Worker resource.
+   *
+   * Expandable field
+   */
+  worker?: WorkersAPI.Worker;
+
+  /**
+   * The Platform worker ID from GET /workers/{id}/ when the actor is a worker. Null
+   * when the actor is not a worker.
+   */
+  worker_id?: string;
+}
+
+export namespace ActivityLogRetrieveResponse {
+  /**
+   * Why the activity occurred. Null when no reason was recorded.
+   */
+  export interface Reason {
+    /**
+     * The machine-readable reason code recorded for the event. Null when no reason was
+     * recorded.
+     */
+    code?: string;
+
+    /**
+     * The human-readable meaning of the reason code. Null when no reason was recorded.
+     */
+    message?: string;
+  }
+
+  /**
+   * Request and approximate location details captured for the activity. Null for
+   * non-request events.
+   */
+  export interface RequestContext {
+    /**
+     * The accuracy radius of the IP-derived location in kilometers. Null without the
+     * activity-log.sensitive-data.read scope or when geolocation is unresolved.
+     */
+    accuracy_radius?: number;
+
+    /**
+     * The browser family parsed from the request user agent. Returned with the
+     * activity-log.read scope. Null when unavailable.
+     */
+    browser?: string;
+
+    /**
+     * The city resolved from the request IP address. Null without the
+     * activity-log.sensitive-data.read scope or when geolocation is unresolved.
+     */
+    city?: string;
+
+    /**
+     * The country resolved from the request IP address. Null without the
+     * activity-log.sensitive-data.read scope or when geolocation is unresolved.
+     */
+    country?: string;
+
+    /**
+     * The device family parsed from the request user agent. Returned with the
+     * activity-log.read scope. Null when unavailable.
+     */
+    device?: string;
+
+    /**
+     * The IPv4 or IPv6 address associated with the request. Null without the
+     * activity-log.sensitive-data.read scope.
+     */
+    ip_address?: string;
+
+    /**
+     * The approximate latitude in decimal degrees resolved from the request IP
+     * address. Null without the activity-log.sensitive-data.read scope or when
+     * geolocation is unresolved.
+     */
+    latitude?: number;
+
+    /**
+     * The approximate longitude in decimal degrees resolved from the request IP
+     * address. Null without the activity-log.sensitive-data.read scope or when
+     * geolocation is unresolved.
+     */
+    longitude?: number;
+
+    /**
+     * The operating system parsed from the request user agent. Returned with the
+     * activity-log.read scope. Null when unavailable.
+     */
+    operating_system?: string;
+
+    /**
+     * The state or region resolved from the request IP address. Null without the
+     * activity-log.sensitive-data.read scope or when geolocation is unresolved.
+     */
+    state?: string;
+  }
+
+  /**
+   * A resource or internal entity affected by an Activity Log event.
+   */
+  export interface Target {
+    /**
+     * The ID of the resource affected by the event. Null when the event target has no
+     * referenced resource. Filtering by targets.id is not supported for GROUP or
+     * SPOKE_USER targets.
+     */
+    id?: string;
+
+    /**
+     * The kind of target. WORKER uses the worker ID from GET /workers/{id}/; DEVICE
+     * uses the device ID from GET /devices/{id}/; GROUP uses the group ID from GET
+     * /supergroups/{id}/; SPOKE_USER uses the app-user ID from GET /app-users/{id}/.
+     * COMPUTER is deprecated in favor of DEVICE and its ID is not a Platform resource
+     * ID. IDs for SPOKE, RPASS_ITEM, RPASS_FOLDER, SCHEDULED_CHANGE, BDR_POLICY,
+     * AUTH_RULE, COMPANY_AUTH_RULE, USER_ACCOUNT, HARDWARE_SCRIPT,
+     * HARDWARE_CONFIGURATION, SOFTWARE_UPDATE, OS_SOFTWARE_UPDATE, WORK_EMAIL_POLICY,
+     * OFFBOARDING_POLICY, REMOTE_ACCESS_SESSION_OPTIONS, and
+     * REMOTE_ACCESS_SESSION_ERROR_DETAILS are not Platform resource IDs.
+     */
+    type?:
+      | 'WORKER'
+      | 'SPOKE'
+      | 'RPASS_ITEM'
+      | 'SPOKE_USER'
+      | 'GROUP'
+      | 'RPASS_FOLDER'
+      | 'SCHEDULED_CHANGE'
+      | 'COMPUTER'
+      | 'BDR_POLICY'
+      | 'AUTH_RULE'
+      | 'COMPANY_AUTH_RULE'
+      | 'DEVICE'
+      | 'USER_ACCOUNT'
+      | 'HARDWARE_SCRIPT'
+      | 'HARDWARE_CONFIGURATION'
+      | 'SOFTWARE_UPDATE'
+      | 'OS_SOFTWARE_UPDATE'
+      | 'WORK_EMAIL_POLICY'
+      | 'OFFBOARDING_POLICY'
+      | 'REMOTE_ACCESS_SESSION_OPTIONS'
+      | 'REMOTE_ACCESS_SESSION_ERROR_DETAILS';
+  }
+}
+
+export interface ActivityLogListParams {
+  cursor?: string;
+
+  expand?: string;
+
+  filter?: string;
+
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
+  order_by?: string;
+}
+
+export interface ActivityLogRetrieveParams {
+  expand?: string;
+}
+
+export declare namespace ActivityLog {
+  export {
+    type ActivityLogListResponse as ActivityLogListResponse,
+    type ActivityLogRetrieveResponse as ActivityLogRetrieveResponse,
+    type ActivityLogListResponsesPageCursorURL as ActivityLogListResponsesPageCursorURL,
+    type ActivityLogListParams as ActivityLogListParams,
+    type ActivityLogRetrieveParams as ActivityLogRetrieveParams,
+  };
+}

package/src/resources/compensations.ts

@@ -13,7 +13,7 @@ import { path } from '../internal/utils/path';
  */
 export class Compensations extends APIResource {
   /**
-   * A list of compensations.
+   * Paginates through the compensation the authenticated user has access to.
    *
    * - Requires: `API Tier 1`
    * - Expandable fields: `worker`

package/src/resources/developer-program-application.ts

@@ -10,7 +10,7 @@ import { RequestOptions } from '../internal/request-options';
  */
 export class DeveloperProgramApplication extends APIResource {
   /**
-   * A list of developer program application.
+   * Get the Developer Program application for the authenticated company.
    *
    * - Requires: `Developer Program`
    *

package/src/resources/developer-users.ts

@@ -9,7 +9,8 @@ import { RequestOptions } from '../internal/request-options';
  */
 export class DeveloperUsers extends APIResource {
   /**
-   * A list of App Shop publisher users.
+   * List App Shop Publishers Super Group members for the authenticated company.
+   * Filterable: email, role_state.
    *
    * - Requires: `Developer Program`
    * - Filterable fields: `email`, `role_state`