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

package/src/resources/earning-types.ts

@@ -9,14 +9,33 @@ import { RequestOptions } from '../internal/request-options';
  */
 export class EarningTypes extends APIResource {
   /**
-   * A list of earning-types.
+   * Lists Global Payroll earning types for selecting payroll earnings inputs. Use
+   * the returned `earning_code` in `POST /earnings-inputs/`; the worker's payroll
+   * catalog determines whether that code is available. `company_entity_id` and
+   * `country_code` restrict results together. Conflicting filters return HTTP 200
+   * with empty `results`. Without either filter, returns the company's combined
+   * earning catalog.
+   *
+   * A legal entity can have multiple payroll entities, including sub entities. With
+   * `company_entity_id`, their catalogs are combined and equivalent entries with the
+   * same country, code, display name, configuration, and behavior are merged.
+   * Calculation and tax settings, effective dates, and employment restrictions
+   * participate in comparison. Different configurations remain separate, even when
+   * returned codes and names match. Each merged entry uses the lexicographically
+   * smallest existing earning type ID; it can change when its source entry is
+   * removed. Catalog membership does not guarantee availability to every worker.
+   * Without `company_entity_id`, entries are deduplicated by earning type ID.
+   *
+   * Entity-filtered results are ordered by display name, country, code, and ID.
+   * Pagination does not provide a snapshot during catalog changes. To continue, pass
+   * the returned `next_link` token as `cursor` with the same filters.
    *
    * - Requires: `Global Payroll`
    *
    * @example HTTP
    * Representative request and response shapes.
    * ```
-   * GET /earning-types/?limit=50&cursor=cursor HTTP/1.1
+   * GET /earning-types/?company_entity_id=company_entity_id&country_code=country_code&limit=50&cursor=cursor HTTP/1.1
    * Host: rest.ripplingapis.com
    * Accept: application/json
    * Rippling-Api-Version: 2024-08-01
@@ -59,34 +78,57 @@ export class EarningTypes extends APIResource {
 export type EarningTypeListResponsesPageCursorURL = PageCursorURL<EarningTypeListResponse>;
 
 /**
- * V2 DTO representing a company earning type.
- *
- *     Used by:
- *       - GET /earning-types/  (list)
+ * An earning category available in Global Payroll, such as salary, commission, or
+ * bonus.
  */
 export interface EarningTypeListResponse {
   /**
-   * Unique identifier for the earning type.
+   * Identifier of a source earning type. With `company_entity_id`, equivalent
+   * entries use one existing ID, which can change when its source entry is removed.
+   * Use `earning_code` when submitting payroll earnings inputs.
    */
   id?: string;
 
   /**
-   * ISO country code where the earning type applies.
+   * Uppercase ISO 3166-1 alpha-2 country code of the payroll catalog, such as `CA`
+   * or `US`.
    */
   country_code?: string;
 
   /**
-   * Human-readable name of the earning type.
+   * Configured display name of the earning type. Entries with different
+   * configurations can have the same name and `earning_code`.
    */
   display_name?: string;
 
   /**
-   * Code identifying the earning type (e.g. regular_salary, commission).
+   * Code used to select this earning type in `POST /earnings-inputs/`, such as
+   * `regular_salary` or `commission`. Availability is validated against the worker's
+   * payroll catalog.
    */
   earning_code?: string;
 }
 
 export interface EarningTypeListParams {
+  /**
+   * Filters earnings to a company legal entity. Use the `id` returned by
+   * `GET /company-legal-entities/`, not a payroll entity ID. Includes the combined
+   * catalogs of linked, non-archived payroll entities, excluding internal shadow
+   * entities. Omit this parameter to use the company-wide catalog. An unknown ID or
+   * an ID outside the authenticated company returns HTTP 200 with empty `results`.
+   * An empty value or a value that is not a 24-character hexadecimal ID returns HTTP
+   * 400 (`VALIDATION_ERROR`).
+   */
+  company_entity_id?: string;
+
+  /**
+   * Filters earnings by the payroll entity's country. Use an uppercase ISO 3166-1
+   * alpha-2 country code, such as `CA` or `US`; matching is case-sensitive. If
+   * omitted or empty, country does not restrict results. When supplied with
+   * `company_entity_id`, only earnings matching both filters are returned.
+   */
+  country_code?: string;
+
   cursor?: string;
 
   /**

package/src/resources/hires.ts

@@ -51,7 +51,6 @@ export class Hires extends APIResource {
    * Content-Type: application/json
    *
    * {
-   *   "ack": false,
    *   "results": [
    *     {
    *       "client_request_id": "string",
@@ -86,11 +85,6 @@ export class Hires extends APIResource {
 }
 
 export interface HireCreateResponse {
-  /**
-   * True when the envelope was accepted for processing.
-   */
-  ack: boolean;
-
   /**
    * One result per request hire, in request order. HTTP 200 means the envelope was
    * accepted; each item's status is the outcome.

package/src/resources/index.ts

@@ -95,6 +95,13 @@ export {
   type CandidateListParams,
   type CandidateListResponsesPageCursorURL,
 } from './candidates';
+export {
+  CardTransactions,
+  type CardTransactionListResponse,
+  type CardTransactionRetrieveResponse,
+  type CardTransactionListParams,
+  type CardTransactionListResponsesPageCursorURL,
+} from './card-transactions';
 export { Companies, type Company, type CompanyListParams, type CompaniesPageCursorURL } from './companies';
 export {
   CompanyLegalEntities,
@@ -543,6 +550,13 @@ export {
   type PlatformCapabilityListResponse,
   type PlatformCapabilityListResponsesPageCursorURL,
 } from './platform-capabilities';
+export {
+  Reimbursements,
+  type ReimbursementListResponse,
+  type ReimbursementRetrieveResponse,
+  type ReimbursementListParams,
+  type ReimbursementListResponsesPageCursorURL,
+} from './reimbursements';
 export {
   ReportRuns,
   type ReportRunCreateResponse,
@@ -817,4 +831,4 @@ export {
   type WorkflowRetrieveParams,
   type WorkflowUpdateParams,
   type WorkflowListResponsesPageCursorURL,
-} from './workflows';
+} from './workflows/workflows';

package/src/resources/payroll-payment-mode-changes.ts

@@ -12,7 +12,13 @@ export class PayrollPaymentModeChanges extends APIResource {
    * Update payment modes for workers in one or more draft Global Payroll runs. The
    * endpoint returns an item-level result for each requested change. When a request
    * contains the same run and worker more than once, only the first change is
-   * evaluated; later entries are rejected as duplicates.
+   * evaluated; later entries are rejected as duplicates. Repeating the same run,
+   * worker, and payment mode is a safe no-op, so callers can retry it without an
+   * idempotency key. Request validation returns every detected error in an errors
+   * array before any payment mode is written. The errors array is the deliberate
+   * batch-validation contract for this pre-GA endpoint so callers can correct
+   * multiple issues at once; permission-denied responses use the same envelope for
+   * consistency.
    *
    * @example HTTP
    * Representative request and response shapes.
@@ -37,13 +43,19 @@ export class PayrollPaymentModeChanges extends APIResource {
    * Content-Type: application/json
    *
    * {
-   *   "changes": [
+   *   "results": [
    *     {
    *       "run_id": "string",
    *       "worker_id": "string",
-   *       "payment_mode": "DEFAULT"
+   *       "payment_mode": "DEFAULT",
+   *       "status": "UPDATED",
+   *       "error": {
+   *         "code": "DUPLICATE_NO_OP",
+   *         "message": "string"
+   *       }
    *     }
-   *   ]
+   *   ],
+   *   "write_status": "COMPLETED"
    * }
    * ```
    */
@@ -57,30 +69,79 @@ export class PayrollPaymentModeChanges extends APIResource {
 
 export interface PayrollPaymentModeChangeCreateResponse {
   /**
-   * Payment mode changes to process. The maximum batch size is 100.
+   * Item-level results for the requested payment mode changes. Each item is either
+   * updated or rejected so callers can retry failed items independently.
+   */
+  results?: Array<PayrollPaymentModeChangeCreateResponse.Result>;
+
+  /**
+   * Completion status for this synchronous request. This is currently always
+   * COMPLETED; the field is reserved for future status values if processing becomes
+   * asynchronous. It describes the overall request, while each result status
+   * describes an individual item.
    */
-  changes: Array<PayrollPaymentModeChangeCreateResponse.Change>;
+  write_status?: 'COMPLETED';
 }
 
 export namespace PayrollPaymentModeChangeCreateResponse {
-  export interface Change {
+  export interface Result {
     /**
-     * Canonical Global Payroll payment mode code to apply to the worker in the run.
-     * Known labels are DEFAULT (Default), BANK_FILE (Bank file), MANUAL (Manual),
-     * SAME_DAY_ACH (Same-day ACH), and CHECK_PRINTING (Check printing). CHECK_MAILING
-     * is supported when eligible; its customer-facing label is pending confirmation.
+     * Structured error when the item was rejected. This field is omitted for UPDATED
+     * items and is present for REJECTED items.
      */
-    payment_mode: 'DEFAULT' | 'BANK_FILE' | 'MANUAL' | 'SAME_DAY_ACH' | 'CHECK_PRINTING' | 'CHECK_MAILING';
+    error?: Result.Error;
 
     /**
-     * ID of the draft Global Payroll run to update.
+     * Requested Global Payroll payment mode code.
      */
-    run_id: string;
+    payment_mode?: 'DEFAULT' | 'BANK_FILE' | 'MANUAL' | 'SAME_DAY_ACH' | 'CHECK_PRINTING' | 'CHECK_MAILING';
 
     /**
-     * ID of the worker whose payment mode will be updated.
+     * ID of the requested payroll run.
      */
-    worker_id: string;
+    run_id?: string;
+
+    /**
+     * Item result: UPDATED or REJECTED.
+     */
+    status?: 'UPDATED' | 'REJECTED';
+
+    /**
+     * ID of the requested worker.
+     */
+    worker_id?: string;
+  }
+
+  export namespace Result {
+    /**
+     * Structured error when the item was rejected. This field is omitted for UPDATED
+     * items and is present for REJECTED items.
+     */
+    export interface Error {
+      /**
+       * Machine-readable error code for a rejected item. DUPLICATE_NO_OP means the
+       * requested change was already requested and no retry is needed;
+       * DUPLICATE_TARGET_CONFLICT, OUT_OF_SCOPE, RUN_NOT_FOUND, WORKER_NOT_IN_RUN, and
+       * PAYMENT_MODE_NOT_SUPPORTED are terminal request errors that require changing the
+       * request or authorization; RUN_NOT_WRITABLE may be retried when the run becomes
+       * writable; PAYMENT_MODE_UPDATE_FAILED is retryable after the underlying update
+       * failure is resolved.
+       */
+      code?:
+        | 'DUPLICATE_NO_OP'
+        | 'DUPLICATE_TARGET_CONFLICT'
+        | 'OUT_OF_SCOPE'
+        | 'RUN_NOT_FOUND'
+        | 'RUN_NOT_WRITABLE'
+        | 'WORKER_NOT_IN_RUN'
+        | 'PAYMENT_MODE_NOT_SUPPORTED'
+        | 'PAYMENT_MODE_UPDATE_FAILED';
+
+      /**
+       * Human-readable error message.
+       */
+      message?: string;
+    }
   }
 }
 
@@ -96,8 +157,8 @@ export namespace PayrollPaymentModeChangeCreateParams {
     /**
      * Canonical Global Payroll payment mode code to apply to the worker in the run.
      * Known labels are DEFAULT (Default), BANK_FILE (Bank file), MANUAL (Manual),
-     * SAME_DAY_ACH (Same-day ACH), and CHECK_PRINTING (Check printing). CHECK_MAILING
-     * is supported when eligible; its customer-facing label is pending confirmation.
+     * SAME_DAY_ACH (Same-day ACH), CHECK_PRINTING (Check printing), and CHECK_MAILING
+     * (Check mailing).
      */
     payment_mode: 'DEFAULT' | 'BANK_FILE' | 'MANUAL' | 'SAME_DAY_ACH' | 'CHECK_PRINTING' | 'CHECK_MAILING';