@rippling/rippling-sdk 0.2.0-alpha.35 → 0.2.0-alpha.37

package/src/lib/manifest/custom-object-page-layout.ts

@@ -1,4 +1,5 @@
 import { generateId } from './_helpers';
+import { CustomObjectFieldSection } from './custom-object-field-section';
 import type { CustomObject } from './custom-object';
 import type { Field } from './field';
 
@@ -65,10 +66,8 @@ export interface HeaderEdits {
 // tab_edits — TabEditsDTO + section/tab DTOs
 // ---------------------------------------------------------------------------
 
-/** One field entry inside a `fields_section`. */
-export interface SectionField {
-  /** RQL name of the field to display. Required. */
-  fieldRqlName: string;
+/** Options for one field entry inside a `fields_section`. */
+export interface SectionFieldOptions {
   /** Hide this field from view. Optional. */
   hidden?: boolean;
   /** Allow inline editing of this field. Optional. */
@@ -77,13 +76,24 @@ export interface SectionField {
   movementOption?: 'tab' | 'free';
 }
 
+/** A typed field entry inside a `fields_section`. */
+export interface SectionFieldRef extends SectionFieldOptions {
+  /** Field to display. Required. */
+  field: Field;
+}
+
+/** One field entry inside a `fields_section`. */
+export type SectionField = Field | SectionFieldRef;
+
 /** A standard field-grid section inside a tab. */
 export interface FieldsSection {
   type: 'fields_section';
-  /** Stable key for this section. Required. */
-  key: string;
-  /** Display name of the section. Required. */
-  name: string;
+  /** Field section metadata for the fields displayed in this layout section. Required. */
+  section: CustomObjectFieldSection;
+  /** Stable layout key for this section. Optional. Defaults to the field section id. */
+  key?: string;
+  /** Display name of the layout section. Optional. Defaults to the field section name. */
+  name?: string;
   /** Fields to display in this section. Required. */
   fields: SectionField[];
 }
@@ -255,6 +265,194 @@ export interface CustomObjectPageLayoutProps {
   blueprintKey?: string;
 }
 
+interface SerializedSectionField extends SectionFieldOptions {
+  fieldRqlName: string;
+}
+
+interface SerializedFieldsSection {
+  type: 'fields_section';
+  key: string;
+  name: string;
+  fields: SerializedSectionField[];
+}
+
+interface SerializedTabWithSections {
+  type: 'tab_with_sections';
+  key: string;
+  name: string;
+  sections: SerializedFieldsSection[];
+}
+
+type SerializedPageLayoutTab = SerializedTabWithSections | CustomTab;
+
+interface SerializedSystemSectionEdit extends Omit<SystemSectionEdit, 'newFields'> {
+  newFields?: SerializedSectionField[];
+}
+
+interface SerializedSystemTabEdit extends Omit<SystemTabEdit, 'newSections' | 'systemSectionEdits'> {
+  newSections?: SerializedFieldsSection[];
+  systemSectionEdits?: Record<string, SerializedSystemSectionEdit>;
+}
+
+interface SerializedTabEdits extends Omit<TabEdits, 'newTabs' | 'systemTabEdits'> {
+  newTabs?: SerializedPageLayoutTab[];
+  systemTabEdits?: Record<string, SerializedSystemTabEdit>;
+}
+
+function isField(value: unknown): value is Field {
+  const candidate = value as {
+    getApiName?: unknown;
+    getCustomObjectApiName?: unknown;
+    getSectionId?: unknown;
+    _assignSection?: unknown;
+  } | null;
+  return (
+    candidate != null &&
+    typeof candidate.getApiName === 'function' &&
+    typeof candidate.getCustomObjectApiName === 'function' &&
+    typeof candidate.getSectionId === 'function' &&
+    typeof candidate._assignSection === 'function'
+  );
+}
+
+function isFieldRef(value: SectionField): value is SectionFieldRef {
+  const candidate = value as { field?: unknown } | null;
+  return candidate != null && typeof candidate === 'object' && isField(candidate.field);
+}
+
+function assertSameObject(customObject: CustomObject, field: Field, sectionKey: string): void {
+  if (field.getCustomObjectApiName() !== customObject.getApiName()) {
+    throw new Error(
+      `CustomObjectPageLayout fields_section "${sectionKey}" references field "${field.getApiName()}" ` +
+        `from "${field.getCustomObjectApiName()}", but the layout belongs to "${customObject.getApiName()}".`,
+    );
+  }
+}
+
+function assertSectionBelongsTo(customObject: CustomObject, section: CustomObjectFieldSection): void {
+  if (section.getModelApiName() !== customObject.getApiName()) {
+    throw new Error(
+      `CustomObjectPageLayout section "${section.getSectionId()}" belongs to "${section.getModelApiName()}", ` +
+        `but the layout belongs to "${customObject.getApiName()}".`,
+    );
+  }
+}
+
+function toSerializedSectionField(
+  fieldRqlName: string,
+  options: SectionFieldOptions = {},
+): SerializedSectionField {
+  const normalized: SerializedSectionField = { fieldRqlName };
+  if (options.hidden != null) normalized.hidden = options.hidden;
+  if (options.editable != null) normalized.editable = options.editable;
+  if (options.movementOption != null) normalized.movementOption = options.movementOption;
+  return normalized;
+}
+
+function normalizeSectionField(
+  customObject: CustomObject,
+  section: CustomObjectFieldSection | string,
+  sectionKey: string,
+  entry: SectionField,
+): SerializedSectionField {
+  if (isField(entry)) {
+    assertSameObject(customObject, entry, sectionKey);
+    entry._assignSection(section);
+    return toSerializedSectionField(entry.getApiName());
+  }
+
+  if (isFieldRef(entry)) {
+    assertSameObject(customObject, entry.field, sectionKey);
+    entry.field._assignSection(section);
+    return toSerializedSectionField(entry.field.getApiName(), entry);
+  }
+
+  throw new Error(
+    `CustomObjectPageLayout fields_section "${sectionKey}" has an invalid field entry; ` +
+      'pass a Field instance or { field }.',
+  );
+}
+
+function normalizeFieldsSection(
+  customObject: CustomObject,
+  input: PageLayoutSection,
+): SerializedFieldsSection {
+  assertSectionBelongsTo(customObject, input.section);
+  const key = input.key ?? input.section.getSectionId();
+  const name = input.name ?? input.section.getName();
+  return {
+    key,
+    name,
+    type: 'fields_section',
+    fields: input.fields.map((field) => normalizeSectionField(customObject, input.section, key, field)),
+  };
+}
+
+function normalizeTab(customObject: CustomObject, tab: PageLayoutTab): SerializedPageLayoutTab {
+  if (tab.type === 'custom_tab') return tab;
+  return {
+    ...tab,
+    sections: tab.sections.map((section) => normalizeFieldsSection(customObject, section)),
+  };
+}
+
+function normalizeSystemSectionEdit(
+  customObject: CustomObject,
+  tabKey: string,
+  sectionKey: string,
+  edit: SystemSectionEdit,
+): SerializedSystemSectionEdit {
+  const { newFields: _newFields, ...rest } = edit;
+  const normalized: SerializedSystemSectionEdit = { ...rest };
+  if (edit.newFields != null) {
+    normalized.newFields = edit.newFields.map((field) =>
+      normalizeSectionField(customObject, sectionKey, `${tabKey}.${sectionKey}`, field),
+    );
+  }
+  return normalized;
+}
+
+function normalizeSystemTabEdit(
+  customObject: CustomObject,
+  tabKey: string,
+  edit: SystemTabEdit,
+): SerializedSystemTabEdit {
+  const { newSections: _newSections, systemSectionEdits: _systemSectionEdits, ...rest } = edit;
+  const normalized: SerializedSystemTabEdit = { ...rest };
+  if (edit.newSections != null) {
+    normalized.newSections = edit.newSections.map((section) => normalizeFieldsSection(customObject, section));
+  }
+  if (edit.systemSectionEdits != null) {
+    const systemSectionEdits: Record<string, SerializedSystemSectionEdit> = {};
+    for (const [sectionKey, sectionEdit] of Object.entries(edit.systemSectionEdits)) {
+      systemSectionEdits[sectionKey] = normalizeSystemSectionEdit(
+        customObject,
+        tabKey,
+        sectionKey,
+        sectionEdit,
+      );
+    }
+    normalized.systemSectionEdits = systemSectionEdits;
+  }
+  return normalized;
+}
+
+function normalizeTabEdits(customObject: CustomObject, tabEdits: TabEdits): SerializedTabEdits {
+  const { newTabs: _newTabs, systemTabEdits: _systemTabEdits, ...rest } = tabEdits;
+  const normalized: SerializedTabEdits = { ...rest };
+  if (tabEdits.newTabs != null) {
+    normalized.newTabs = tabEdits.newTabs.map((tab) => normalizeTab(customObject, tab));
+  }
+  if (tabEdits.systemTabEdits != null) {
+    const systemTabEdits: Record<string, SerializedSystemTabEdit> = {};
+    for (const [tabKey, tabEdit] of Object.entries(tabEdits.systemTabEdits)) {
+      systemTabEdits[tabKey] = normalizeSystemTabEdit(customObject, tabKey, tabEdit);
+    }
+    normalized.systemTabEdits = systemTabEdits;
+  }
+  return normalized;
+}
+
 // ---------------------------------------------------------------------------
 // Class
 // ---------------------------------------------------------------------------
@@ -283,11 +481,11 @@ export interface CustomObjectPageLayoutProps {
  *     newTabs: [{
  *       key: 'member', name: 'Member', type: 'tab_with_sections',
  *       sections: [{
- *         key: 'profile', name: 'Profile', type: 'fields_section',
- *         fields: [
- *           { fieldRqlName: memberFirstName.getApiName() },
- *           { fieldRqlName: memberEmail.getApiName() },
- *         ],
+ *         key: 'profile',
+ *         name: 'Profile',
+ *         type: 'fields_section',
+ *         section: profileSection,
+ *         fields: [memberFirstName, memberEmail],
  *       }],
  *     }],
  *     systemTabEdits: {},
@@ -304,7 +502,7 @@ export class CustomObjectPageLayout {
   private readonly _apiName: string;
   private readonly _customObjectApiName: string;
   private readonly _name: string;
-  private readonly _tabEdits: TabEdits;
+  private readonly _tabEdits: SerializedTabEdits;
   private readonly _headerEdits: HeaderEdits;
   private readonly _visibilityConditions: VisibilityConditions;
   private readonly _blueprintKey: string | undefined;
@@ -321,7 +519,7 @@ export class CustomObjectPageLayout {
     this._apiName = props.apiName;
     this._customObjectApiName = customObject.getApiName();
     this._name = props.name;
-    this._tabEdits = props.tabEdits ?? {};
+    this._tabEdits = normalizeTabEdits(customObject, props.tabEdits ?? {});
     this._headerEdits = props.headerEdits ?? {};
     this._visibilityConditions = props.visibilityConditions ?? {};
     this._blueprintKey = props.blueprintKey;
@@ -396,6 +594,11 @@ export class CustomObjectPageLayout {
   ): CustomObjectPageLayout {
     const coApiName = customObject.getApiName();
     const coName = customObject.getName();
+    const sectionPrefix = coApiName.replace(/__c$/, '').replace(/[^a-zA-Z0-9]+/g, '_');
+    const generalSection = new CustomObjectFieldSection(customObject, {
+      sectionId: `sec_${sectionPrefix}_general`,
+      name: 'General',
+    });
     return new CustomObjectPageLayout(customObject, {
       apiName: 'default',
       name: `${coName} Layout`,
@@ -410,9 +613,8 @@ export class CustomObjectPageLayout {
                 key: 'general',
                 name: 'General',
                 type: 'fields_section',
-                fields: (props.fields ?? []).map((f: Field) => ({
-                  fieldRqlName: f.getApiName(),
-                })),
+                section: generalSection,
+                fields: props.fields ?? [],
               },
             ],
           },

package/src/lib/manifest/field.ts

@@ -130,7 +130,7 @@ export class Field {
   private readonly _rqlFormula: string | null;
   private readonly _formulaAttrMetas: Record<string, any> | null;
   private readonly _derivedFieldFormula: string | null;
-  private readonly _section: string | null;
+  private _section: string | null;
   private readonly _summarySpec: SummarySpec | null;
   private readonly _derivedAggregatedFieldStatic: Record<string, any> | null;
 
@@ -202,6 +202,14 @@ export class Field {
   isSummary(): boolean {
     return this._summarySpec != null;
   }
+  /** Returns the field section id assigned to this field, if any. */
+  getSectionId(): string | null {
+    return this._section;
+  }
+  /** @internal Assigns this field to a field section during page-layout normalization. */
+  _assignSection(section: CustomObjectFieldSection | string): void {
+    this._section = typeof section === 'string' ? section : section.getSectionId();
+  }
 
   // ── Serialization ──────────────────────────────────────────────────────
 

package/src/lib/manifest/index.ts

@@ -35,6 +35,8 @@ export {
   type PageLayoutSection,
   type PageLayoutTab,
   type SectionField,
+  type SectionFieldOptions,
+  type SectionFieldRef,
   type SectionFieldsLayout,
   type SystemHeaderFieldEdit,
   type SystemSectionEdit,

package/src/resources/company-legal-entities.ts

@@ -0,0 +1,237 @@
+// 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 Shared from './shared';
+import { APIPromise } from '../core/api-promise';
+import { PageCursorURL, PagePromise } from '../core/pagination';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Legal entities registered by the company
+ */
+export class CompanyLegalEntities extends APIResource {
+  /**
+   * A list of company legal entities.
+   *
+   * - Requires: `API Tier 2`
+   * - Filterable fields: `country_code`
+   * - Sortable fields: `id`, `created_at`, `updated_at`
+   */
+  list(
+    query: CompanyLegalEntityListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CompanyLegalEntityListResponsesPageCursorURL, CompanyLegalEntityListResponse> {
+    return this._client.getAPIList(
+      '/company-legal-entities/',
+      PageCursorURL<CompanyLegalEntityListResponse>,
+      { query, ...options },
+    );
+  }
+
+  /**
+   * Retrieve a specific company legal entity
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<CompanyLegalEntityRetrieveResponse> {
+    return this._client.get(path`/company-legal-entities/${id}/`, options);
+  }
+}
+
+export type CompanyLegalEntityListResponsesPageCursorURL = PageCursorURL<CompanyLegalEntityListResponse>;
+
+export interface CompanyLegalEntityListResponse {
+  /**
+   * Identifier field
+   */
+  id: string;
+
+  /**
+   * Record creation date
+   */
+  created_at: string;
+
+  /**
+   * Record update date
+   */
+  updated_at: string;
+
+  /**
+   * The company associated with this entity relationship.
+   */
+  company_id?: string;
+
+  /**
+   * The ISO country code for the entity.
+   */
+  country_code?: string;
+
+  /**
+   * The entity's level in a hierarchy. _ `PARENT`: The legal entity is considered
+   * the ultimate holding entity. _ `SUBSIDIARY`: The legal entity is considered a
+   * subsidiary, fully or partially held by another. \* `BRANCH`: The legal entity is
+   * considered a branch, associated with a parent legal entity.
+   */
+  entity_level?: 'PARENT' | 'SUBSIDIARY' | 'BRANCH';
+
+  /**
+   * True if this entity relationship has been archived.
+   */
+  is_archived?: boolean;
+
+  /**
+   * True if this entity is managed as a Contractor of Record.
+   */
+  is_cor?: boolean;
+
+  /**
+   * True if this entity is managed as an Employer of Record.
+   */
+  is_eor?: boolean;
+
+  /**
+   * True if this entity is managed as a Professional Employment Organization.
+   */
+  is_peo?: boolean;
+
+  /**
+   * The legal name of the entity.
+   */
+  legal_name?: string;
+
+  /**
+   * The mailing address of the entity.
+   */
+  mailing_address?: Shared.Address;
+
+  /**
+   * The entity management type. _ `EOR`: The entity is managed as an Employer of
+   * Record. _ `COR`: The entity is managed as a Contractor of Record. _ `PEO`: The
+   * entity is managed as a Professional Employment Organization. _ `null`: The
+   * entity is a direct hire with no managed employment type.
+   */
+  management_type?: 'PEO' | 'EOR' | 'COR';
+
+  /**
+   * The physical address of the entity, if it differs from the mailing address.
+   */
+  physical_address?: Shared.Address;
+
+  /**
+   * The registration date of the entity.
+   */
+  registration_date?: string;
+
+  /**
+   * The tax identifier for this entity.
+   */
+  tax_identifier?: string;
+}
+
+/**
+ * Meta information for the response.
+ */
+export interface CompanyLegalEntityRetrieveResponse extends BusinessPartnersAPI.Meta {
+  /**
+   * Identifier field
+   */
+  id: string;
+
+  /**
+   * Record creation date
+   */
+  created_at: string;
+
+  /**
+   * Record update date
+   */
+  updated_at: string;
+
+  /**
+   * The company associated with this entity relationship.
+   */
+  company_id?: string;
+
+  /**
+   * The ISO country code for the entity.
+   */
+  country_code?: string;
+
+  /**
+   * The entity's level in a hierarchy. _ `PARENT`: The legal entity is considered
+   * the ultimate holding entity. _ `SUBSIDIARY`: The legal entity is considered a
+   * subsidiary, fully or partially held by another. \* `BRANCH`: The legal entity is
+   * considered a branch, associated with a parent legal entity.
+   */
+  entity_level?: 'PARENT' | 'SUBSIDIARY' | 'BRANCH';
+
+  /**
+   * True if this entity relationship has been archived.
+   */
+  is_archived?: boolean;
+
+  /**
+   * True if this entity is managed as a Contractor of Record.
+   */
+  is_cor?: boolean;
+
+  /**
+   * True if this entity is managed as an Employer of Record.
+   */
+  is_eor?: boolean;
+
+  /**
+   * True if this entity is managed as a Professional Employment Organization.
+   */
+  is_peo?: boolean;
+
+  /**
+   * The legal name of the entity.
+   */
+  legal_name?: string;
+
+  /**
+   * The mailing address of the entity.
+   */
+  mailing_address?: Shared.Address;
+
+  /**
+   * The entity management type. _ `EOR`: The entity is managed as an Employer of
+   * Record. _ `COR`: The entity is managed as a Contractor of Record. _ `PEO`: The
+   * entity is managed as a Professional Employment Organization. _ `null`: The
+   * entity is a direct hire with no managed employment type.
+   */
+  management_type?: 'PEO' | 'EOR' | 'COR';
+
+  /**
+   * The physical address of the entity, if it differs from the mailing address.
+   */
+  physical_address?: Shared.Address;
+
+  /**
+   * The registration date of the entity.
+   */
+  registration_date?: string;
+
+  /**
+   * The tax identifier for this entity.
+   */
+  tax_identifier?: string;
+}
+
+export interface CompanyLegalEntityListParams {
+  cursor?: string;
+
+  filter?: string;
+
+  order_by?: string;
+}
+
+export declare namespace CompanyLegalEntities {
+  export {
+    type CompanyLegalEntityListResponse as CompanyLegalEntityListResponse,
+    type CompanyLegalEntityRetrieveResponse as CompanyLegalEntityRetrieveResponse,
+    type CompanyLegalEntityListResponsesPageCursorURL as CompanyLegalEntityListResponsesPageCursorURL,
+    type CompanyLegalEntityListParams as CompanyLegalEntityListParams,
+  };
+}

package/src/resources/company-legal-entity-workers.ts

@@ -0,0 +1,115 @@
+// 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 { APIPromise } from '../core/api-promise';
+import { PageCursorURL, PagePromise } from '../core/pagination';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Workers who work or have worked at the company
+ */
+export class CompanyLegalEntityWorkers extends APIResource {
+  /**
+   * A list of company-legal-entity-workers.
+   *
+   * - Requires: `API Tier 2`
+   * - Filterable fields: `status`, `company_entity_id`
+   * - Sortable fields: `id`, `created_at`, `updated_at`
+   */
+  list(
+    query: CompanyLegalEntityWorkerListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CompanyLegalEntityWorkerListResponsesPageCursorURL, CompanyLegalEntityWorkerListResponse> {
+    return this._client.getAPIList(
+      '/company-legal-entity-workers/',
+      PageCursorURL<CompanyLegalEntityWorkerListResponse>,
+      { query, ...options },
+    );
+  }
+
+  /**
+   * Retrieve a specific company-legal-entity-worker
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<CompanyLegalEntityWorkerRetrieveResponse> {
+    return this._client.get(path`/company-legal-entity-workers/${id}/`, options);
+  }
+}
+
+export type CompanyLegalEntityWorkerListResponsesPageCursorURL =
+  PageCursorURL<CompanyLegalEntityWorkerListResponse>;
+
+export interface CompanyLegalEntityWorkerListResponse {
+  /**
+   * Identifier field
+   */
+  id: string;
+
+  /**
+   * Record creation date
+   */
+  created_at: string;
+
+  /**
+   * Record update date
+   */
+  updated_at: string;
+
+  /**
+   * The worker's associated company legal entity (CER ID).
+   */
+  company_entity_id?: string;
+
+  /**
+   * The worker's status within the organization.
+   */
+  status?: 'INIT' | 'HIRED' | 'ACCEPTED' | 'ACTIVE' | 'TERMINATED';
+}
+
+/**
+ * Meta information for the response.
+ */
+export interface CompanyLegalEntityWorkerRetrieveResponse extends BusinessPartnersAPI.Meta {
+  /**
+   * Identifier field
+   */
+  id: string;
+
+  /**
+   * Record creation date
+   */
+  created_at: string;
+
+  /**
+   * Record update date
+   */
+  updated_at: string;
+
+  /**
+   * The worker's associated company legal entity (CER ID).
+   */
+  company_entity_id?: string;
+
+  /**
+   * The worker's status within the organization.
+   */
+  status?: 'INIT' | 'HIRED' | 'ACCEPTED' | 'ACTIVE' | 'TERMINATED';
+}
+
+export interface CompanyLegalEntityWorkerListParams {
+  cursor?: string;
+
+  filter?: string;
+
+  order_by?: string;
+}
+
+export declare namespace CompanyLegalEntityWorkers {
+  export {
+    type CompanyLegalEntityWorkerListResponse as CompanyLegalEntityWorkerListResponse,
+    type CompanyLegalEntityWorkerRetrieveResponse as CompanyLegalEntityWorkerRetrieveResponse,
+    type CompanyLegalEntityWorkerListResponsesPageCursorURL as CompanyLegalEntityWorkerListResponsesPageCursorURL,
+    type CompanyLegalEntityWorkerListParams as CompanyLegalEntityWorkerListParams,
+  };
+}

package/src/resources/earning-types.ts

@@ -11,7 +11,7 @@ export class EarningTypes extends APIResource {
   /**
    * A list of earning-types.
    *
-   * - Requires: `Payroll API`
+   * - Requires: `Global Payroll`
    */
   list(
     options?: RequestOptions,
@@ -34,12 +34,6 @@ export interface EarningTypeListResponse {
    */
   id?: string;
 
-  /**
-   * Company entity relationship identifier (CER ID) linking the earning type to the
-   * HRIS legal entity.
-   */
-  company_entity_id?: string;
-
   /**
    * ISO country code where the earning type applies.
    */