@rippling/rippling-sdk 0.2.0-alpha.85 → 0.2.0-alpha.87

package/src/client.ts

@@ -432,6 +432,22 @@ import {
   ShiftassignmentUpdateResponse,
   Shiftassignments,
 } from './resources/shiftassignments';
+import {
+  SiteCreateParams,
+  SiteCreateResponse,
+  SiteFileOperationsParams,
+  SiteFileOperationsResponse,
+  SiteFilesParams,
+  SiteFilesResponse,
+  SiteListResponse,
+  SiteListResponsesPageCursorURL,
+  SiteRetrieveResponse,
+  SiteUpdateParams,
+  SiteUpdateResponse,
+  SiteUploadBatchesParams,
+  SiteUploadBatchesResponse,
+  Sites,
+} from './resources/sites';
 import {
   SoftwareDeploymentCreateParams,
   SoftwareDeploymentCreateResponse,
@@ -564,6 +580,17 @@ import {
   WorkflowActionExecutionCreateResponse,
   WorkflowActionExecutions,
 } from './resources/workflow-action-executions';
+import {
+  AgentCreateParams,
+  AgentCreateResponse,
+  AgentListParams,
+  AgentListResponse,
+  AgentListResponsesPageCursorURL,
+  AgentRetrieveResponse,
+  AgentUpdateParams,
+  AgentUpdateResponse,
+  Agents,
+} from './resources/agents/agents';
 import {
   CustomObject,
   CustomObjectCreateParams,
@@ -581,6 +608,17 @@ import {
   Functions,
   FunctionsPageCursorURL,
 } from './resources/functions/functions';
+import {
+  PackageCreateParams,
+  PackageCreateResponse,
+  PackageListParams,
+  PackageListResponse,
+  PackageListResponsesPageCursorURL,
+  PackageRetrieveResponse,
+  PackageUpdateParams,
+  PackageUpdateResponse,
+  Packages,
+} from './resources/packages/packages';
 import {
   PayrollRunListParams,
   PayrollRunListResponse,
@@ -1461,6 +1499,10 @@ export class RipplingSDK {
    * Job related information for the company
    */
   jobPayRateExceptions: API.JobPayRateExceptions = new API.JobPayRateExceptions(this);
+  /**
+   * Agents defined by the company
+   */
+  agents: API.Agents = new API.Agents(this);
   /**
    * Mappings between Rippling workers and their user accounts in third-party apps
    */
@@ -1564,6 +1606,10 @@ export class RipplingSDK {
    * Geographic compensation adjustment factors that modify base compensation based on location-specific market conditions and cost of living
    */
   locationFactors: API.LocationFactors = new API.LocationFactors(this);
+  /**
+   * Author, publish, and install Unity Packages V2 packages
+   */
+  packages: API.Packages = new API.Packages(this);
   /**
    * Payroll runs for the company
    */
@@ -1592,6 +1638,7 @@ export class RipplingSDK {
    * Shift assignments assigned to workers
    */
   shiftassignments: API.Shiftassignments = new API.Shiftassignments(this);
+  sites: API.Sites = new API.Sites(this);
   /**
    * Software deployed to company devices
    */
@@ -1660,6 +1707,7 @@ RipplingSDK.BusinessPartnerGroups = BusinessPartnerGroups;
 RipplingSDK.Functions = Functions;
 RipplingSDK.JobAssignments = JobAssignments;
 RipplingSDK.JobPayRateExceptions = JobPayRateExceptions;
+RipplingSDK.Agents = Agents;
 RipplingSDK.AppUsers = AppUsers;
 RipplingSDK.BreakPolicies = BreakPolicies;
 RipplingSDK.BreakTypes = BreakTypes;
@@ -1688,6 +1736,7 @@ RipplingSDK.JobRequisitionsWrite = JobRequisitionsWrite;
 RipplingSDK.LeaveAccruals = LeaveAccruals;
 RipplingSDK.LeaveProgramEvaluations = LeaveProgramEvaluations;
 RipplingSDK.LocationFactors = LocationFactors;
+RipplingSDK.Packages = Packages;
 RipplingSDK.PayrollRuns = PayrollRuns;
 RipplingSDK.PlatformCapabilities = PlatformCapabilities;
 RipplingSDK.Reports = Reports;
@@ -1695,6 +1744,7 @@ RipplingSDK.ReportRuns = ReportRuns;
 RipplingSDK.Schedules = Schedules;
 RipplingSDK.ScheduledJobAssignments = ScheduledJobAssignments;
 RipplingSDK.Shiftassignments = Shiftassignments;
+RipplingSDK.Sites = Sites;
 RipplingSDK.SoftwareDeployments = SoftwareDeployments;
 RipplingSDK.Titles = Titles;
 RipplingSDK.Unassignedshifts = Unassignedshifts;
@@ -2011,6 +2061,18 @@ export declare namespace RipplingSDK {
     type JobPayRateExceptionListChangeLogParams as JobPayRateExceptionListChangeLogParams,
   };
 
+  export {
+    Agents as Agents,
+    type AgentListResponse as AgentListResponse,
+    type AgentCreateResponse as AgentCreateResponse,
+    type AgentRetrieveResponse as AgentRetrieveResponse,
+    type AgentUpdateResponse as AgentUpdateResponse,
+    type AgentListResponsesPageCursorURL as AgentListResponsesPageCursorURL,
+    type AgentListParams as AgentListParams,
+    type AgentCreateParams as AgentCreateParams,
+    type AgentUpdateParams as AgentUpdateParams,
+  };
+
   export {
     AppUsers as AppUsers,
     type AppUserListResponse as AppUserListResponse,
@@ -2239,6 +2301,18 @@ export declare namespace RipplingSDK {
     type LocationFactorListParams as LocationFactorListParams,
   };
 
+  export {
+    Packages as Packages,
+    type PackageListResponse as PackageListResponse,
+    type PackageCreateResponse as PackageCreateResponse,
+    type PackageRetrieveResponse as PackageRetrieveResponse,
+    type PackageUpdateResponse as PackageUpdateResponse,
+    type PackageListResponsesPageCursorURL as PackageListResponsesPageCursorURL,
+    type PackageListParams as PackageListParams,
+    type PackageCreateParams as PackageCreateParams,
+    type PackageUpdateParams as PackageUpdateParams,
+  };
+
   export {
     PayrollRuns as PayrollRuns,
     type PayrollRunListResponse as PayrollRunListResponse,
@@ -2296,6 +2370,23 @@ export declare namespace RipplingSDK {
     type ShiftassignmentUpdateParams as ShiftassignmentUpdateParams,
   };
 
+  export {
+    Sites as Sites,
+    type SiteListResponse as SiteListResponse,
+    type SiteCreateResponse as SiteCreateResponse,
+    type SiteRetrieveResponse as SiteRetrieveResponse,
+    type SiteUpdateResponse as SiteUpdateResponse,
+    type SiteUploadBatchesResponse as SiteUploadBatchesResponse,
+    type SiteFilesResponse as SiteFilesResponse,
+    type SiteFileOperationsResponse as SiteFileOperationsResponse,
+    type SiteListResponsesPageCursorURL as SiteListResponsesPageCursorURL,
+    type SiteCreateParams as SiteCreateParams,
+    type SiteUpdateParams as SiteUpdateParams,
+    type SiteUploadBatchesParams as SiteUploadBatchesParams,
+    type SiteFilesParams as SiteFilesParams,
+    type SiteFileOperationsParams as SiteFileOperationsParams,
+  };
+
   export {
     SoftwareDeployments as SoftwareDeployments,
     type SoftwareDeploymentListResponse as SoftwareDeploymentListResponse,

package/src/core/platform/custom-objects/category.ts

@@ -0,0 +1,294 @@
+import type { RipplingSDK } from '../../../client';
+import type {
+  ObjectCategory,
+  ObjectCategoryCreateParams,
+  ObjectCategoryUpdateParams,
+} from '../../../resources/object-categories';
+import type { CategoryApiName, LogicalCategoryName } from './types';
+import { toCustomCategoryApiName } from './definition';
+import { validateLogicalCategoryName } from './validation';
+
+/**
+ * Author input accepted by {@link defineCustomObjectCategory}.
+ *
+ * @typeParam TName - Logical category name supplied by the caller.
+ */
+interface CustomObjectCategoryDefinitionInput<TName extends string> {
+  /** Logical unsuffixed snake_case category name. */
+  readonly name: LogicalCategoryName<TName>;
+  /** Human-readable display name applied after creation. */
+  readonly displayName: string;
+  /** Optional category description. */
+  readonly description?: string;
+}
+
+/** Immutable typed category definition used by provisioning and lifecycle helpers. */
+export interface CustomObjectCategoryDefinition<TName extends LogicalCategoryName = LogicalCategoryName> {
+  /** Logical unsuffixed snake_case category name. */
+  readonly name: TName;
+  /** Compiled wire-level category api name. */
+  readonly apiName: CategoryApiName<TName>;
+  /** Human-readable display name. */
+  readonly displayName: string;
+  /** Optional category description. */
+  readonly description?: string;
+}
+
+/** Result returned by category provisioning helpers. */
+export interface ProvisionedCustomObjectCategory<TName extends LogicalCategoryName = LogicalCategoryName> {
+  /** Source typed category definition. */
+  readonly definition: CustomObjectCategoryDefinition<TName>;
+  /** Response returned by `client.objectCategories.create(...)`. */
+  readonly createdCategory: ObjectCategory;
+  /** Response returned by `client.objectCategories.update(...)`. */
+  readonly updatedCategory: ObjectCategory;
+}
+
+/** Lifecycle action emitted by category reconciliation helpers. */
+export type CustomObjectCategoryLifecycleAction = 'created' | 'updated' | 'unchanged';
+
+/** Result returned by category reconciliation helpers. */
+export interface ReconciledCustomObjectCategory<TName extends LogicalCategoryName = LogicalCategoryName> {
+  /** Source typed category definition. */
+  readonly definition: CustomObjectCategoryDefinition<TName>;
+  /** Whether the remote category was created, updated, or already matched. */
+  readonly action: CustomObjectCategoryLifecycleAction;
+  /** Remote category after reconciliation. */
+  readonly category: ObjectCategory;
+}
+
+/** Options for category provisioning and reconciliation helpers. */
+export interface CustomObjectCategoryMutationOptions {
+  /** Whether to apply the follow-up display-metadata update. Defaults to `true`. */
+  readonly updateDisplayMetadata?: boolean;
+}
+
+/**
+ * Creates an immutable typed custom-object category definition.
+ *
+ * @param definition - Logical category metadata to normalize and freeze.
+ * @returns Immutable typed category definition with compiled API name.
+ * @typeParam TName - Logical category name supplied by the caller.
+ */
+export function defineCustomObjectCategory<TName extends string>(
+  definition: CustomObjectCategoryDefinitionInput<TName>,
+): Readonly<CustomObjectCategoryDefinition<LogicalCategoryName<TName>>> {
+  validateLogicalCategoryName(definition.name);
+  return Object.freeze({
+    name: definition.name,
+    apiName: toCustomCategoryApiName(definition.name),
+    displayName: definition.displayName,
+    ...(definition.description != null ? { description: definition.description } : {}),
+  }) as Readonly<CustomObjectCategoryDefinition<LogicalCategoryName<TName>>>;
+}
+
+/**
+ * Builds the low-level create payload for an object category.
+ *
+ * @param definition - Typed category definition to compile.
+ * @returns REST create payload using the logical category name.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+export function buildObjectCategoryCreateParams<TName extends LogicalCategoryName>(
+  definition: CustomObjectCategoryDefinition<TName>,
+): ObjectCategoryCreateParams {
+  return {
+    name: definition.name,
+    ...(definition.description != null ? { description: definition.description } : {}),
+  };
+}
+
+/**
+ * Builds the low-level update payload for an object category.
+ *
+ * @param definition - Typed category definition to compile.
+ * @returns REST update payload using human-facing display metadata.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+export function buildObjectCategoryUpdateParams<TName extends LogicalCategoryName>(
+  definition: CustomObjectCategoryDefinition<TName>,
+): ObjectCategoryUpdateParams {
+  return {
+    name: definition.displayName,
+    ...(definition.description != null ? { description: definition.description } : {}),
+  };
+}
+
+/**
+ * Returns whether one public category DTO matches the typed category definition by currently visible names.
+ *
+ * @param category - Public category DTO returned by the REST API.
+ * @param definition - Typed category definition being matched.
+ * @returns Whether the visible name matches either the logical or display name.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+function isMatchingCategoryName<TName extends LogicalCategoryName>(
+  category: ObjectCategory,
+  definition: CustomObjectCategoryDefinition<TName>,
+): boolean {
+  return category.name === definition.name || category.name === definition.displayName;
+}
+
+/**
+ * Lists all public category DTOs that ambiguously or exactly match one typed definition.
+ *
+ * @param client - SDK client used to enumerate categories.
+ * @param definition - Typed category definition being matched.
+ * @returns Frozen list of public categories whose visible names match.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+async function listMatchingCategories<TName extends LogicalCategoryName>(
+  client: RipplingSDK,
+  definition: CustomObjectCategoryDefinition<TName>,
+): Promise<readonly ObjectCategory[]> {
+  const matches: ObjectCategory[] = [];
+  for await (const category of client.objectCategories.list()) {
+    if (isMatchingCategoryName(category, definition)) {
+      matches.push(category);
+    }
+  }
+  return Object.freeze(matches);
+}
+
+/**
+ * Returns the single public category matching one typed definition or throws when the match is ambiguous.
+ *
+ * @param client - SDK client used to enumerate categories.
+ * @param definition - Typed category definition being matched.
+ * @returns Matching public category, if any.
+ * @throws Error when multiple public categories match the visible names.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+async function getSingleMatchingCategory<TName extends LogicalCategoryName>(
+  client: RipplingSDK,
+  definition: CustomObjectCategoryDefinition<TName>,
+): Promise<ObjectCategory | undefined> {
+  const matches = await listMatchingCategories(client, definition);
+  if (matches.length <= 1) return matches[0];
+
+  throw new Error(
+    `Ambiguous category match for "${definition.name}" / "${definition.displayName}". ` +
+      `Matched ids: ${matches.map((category) => category.id).join(', ')}.`,
+  );
+}
+
+/**
+ * Creates one typed custom-object category through the REST SDK.
+ *
+ * @param client - SDK client used to call the category APIs.
+ * @param definition - Typed category definition to provision.
+ * @param options - Provisioning behavior flags for display-metadata updates.
+ * @returns Frozen summary of the created and updated backend category DTOs.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+export async function provisionCustomObjectCategoryDefinition<TName extends LogicalCategoryName>(
+  client: RipplingSDK,
+  definition: CustomObjectCategoryDefinition<TName>,
+  options: CustomObjectCategoryMutationOptions = {},
+): Promise<ProvisionedCustomObjectCategory<TName>> {
+  const createdCategory = await client.objectCategories.create(buildObjectCategoryCreateParams(definition));
+  const updatedCategory =
+    options.updateDisplayMetadata ?? true ?
+      await client.objectCategories.update(createdCategory.id, buildObjectCategoryUpdateParams(definition))
+    : createdCategory;
+
+  return Object.freeze({ definition, createdCategory, updatedCategory });
+}
+
+/**
+ * Creates multiple typed custom-object categories through the REST SDK.
+ *
+ * @param client - SDK client used to call the category APIs.
+ * @param definitions - Typed category definitions to provision.
+ * @param options - Provisioning behavior flags shared across the batch.
+ * @returns Frozen batch of provisioning results in input order.
+ */
+export async function provisionCustomObjectCategoryDefinitions(
+  client: RipplingSDK,
+  definitions: readonly CustomObjectCategoryDefinition[],
+  options: CustomObjectCategoryMutationOptions = {},
+): Promise<readonly ProvisionedCustomObjectCategory[]> {
+  const results: ProvisionedCustomObjectCategory[] = [];
+  for (const definition of definitions) {
+    results.push(await provisionCustomObjectCategoryDefinition(client, definition, options));
+  }
+  return Object.freeze(results);
+}
+
+/**
+ * Reconciles one typed category definition against the backend by name.
+ *
+ * @param client - SDK client used to call the category APIs.
+ * @param definition - Typed category definition to reconcile.
+ * @param options - Reconciliation behavior flags for display-metadata updates.
+ * @returns Frozen reconciliation result describing the final backend category state.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+export async function reconcileCustomObjectCategoryDefinition<TName extends LogicalCategoryName>(
+  client: RipplingSDK,
+  definition: CustomObjectCategoryDefinition<TName>,
+  options: CustomObjectCategoryMutationOptions = {},
+): Promise<ReconciledCustomObjectCategory<TName>> {
+  const existing = await getSingleMatchingCategory(client, definition);
+  if (existing == null) {
+    const provisioned = await provisionCustomObjectCategoryDefinition(client, definition, options);
+    return Object.freeze({
+      definition,
+      action: 'created' as const,
+      category: provisioned.updatedCategory,
+    });
+  }
+
+  const shouldUpdate =
+    (options.updateDisplayMetadata ?? true) &&
+    (existing.name !== definition.displayName ||
+      (existing.description ?? '') !== (definition.description ?? ''));
+
+  if (!shouldUpdate) {
+    return Object.freeze({ definition, action: 'unchanged', category: existing });
+  }
+
+  const updated = await client.objectCategories.update(
+    existing.id,
+    buildObjectCategoryUpdateParams(definition),
+  );
+  return Object.freeze({ definition, action: 'updated', category: updated });
+}
+
+/**
+ * Reconciles multiple typed category definitions against the backend by name.
+ *
+ * @param client - SDK client used to call the category APIs.
+ * @param definitions - Typed category definitions to reconcile.
+ * @param options - Reconciliation behavior flags shared across the batch.
+ * @returns Frozen batch of reconciliation results in input order.
+ */
+export async function reconcileCustomObjectCategoryDefinitions(
+  client: RipplingSDK,
+  definitions: readonly CustomObjectCategoryDefinition[],
+  options: CustomObjectCategoryMutationOptions = {},
+): Promise<readonly ReconciledCustomObjectCategory[]> {
+  const results: ReconciledCustomObjectCategory[] = [];
+  for (const definition of definitions) {
+    results.push(await reconcileCustomObjectCategoryDefinition(client, definition, options));
+  }
+  return Object.freeze(results);
+}
+
+/**
+ * Deletes a category that matches the typed definition's logical or display name.
+ *
+ * @param client - SDK client used to call the category APIs.
+ * @param definition - Typed category definition used to find the category to delete.
+ * @returns Whether a matching category existed and was deleted.
+ * @typeParam TName - Logical category name carried by the definition.
+ */
+export async function deleteCustomObjectCategoryDefinition<TName extends LogicalCategoryName>(
+  client: RipplingSDK,
+  definition: CustomObjectCategoryDefinition<TName>,
+): Promise<boolean> {
+  const existing = await getSingleMatchingCategory(client, definition);
+  if (existing == null) return false;
+  await client.objectCategories.delete(existing.id);
+  return true;
+}