@rippling/rippling-sdk 0.2.0-alpha.88 → 0.2.0-alpha.90

package/src/lib/manifest/acp-agent.ts

@@ -0,0 +1,207 @@
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
+import type { ManifestComponentDeletion, ManifestScope } from './manifest-builder';
+import {
+  requireArrayComponentField,
+  requireBooleanComponentField,
+  requireStringComponentField,
+} from './_existing-component-fields';
+
+/** Composer supports only runner-identity ACP agents. */
+export type ACPAgentIdentityMode = 'runner';
+
+/** A source file in an ACP agent source revision. */
+export interface ACPAgentSourceFile {
+  path: string;
+  content: string;
+  kind: string;
+}
+
+/** An event that starts an ACP agent session. */
+export interface ACPAgentEventTrigger {
+  key: string;
+  eventKey: string;
+  rqlFormula: string;
+  promptTemplate: string;
+  enabled: boolean;
+}
+
+/** Initialization properties for {@link ACPAgent}. */
+export interface ACPAgentProps {
+  /** Company-scoped API name. */
+  apiName: string;
+  /** Display name shown in Rippling. */
+  name: string;
+  /** Human-readable description. */
+  description: string;
+  /** Identity used when the agent runs. ACP Composer supports only `runner`. */
+  identityMode: ACPAgentIdentityMode;
+  /** Omit to preserve existing UI-owned triggers; pass [] to clear them. */
+  eventTriggers?: ACPAgentEventTrigger[];
+  /** Source files for the agent's latest revision. */
+  files: ACPAgentSourceFile[];
+  /** Path of the source file that starts the agent. */
+  entrypoint: string;
+}
+
+/**
+ * Defines an Agent Control Plane agent for Composer.
+ *
+ * New agents use their `apiName` as the Composer source handle, so a
+ * source-executed manifest does not need to persist a separate identifier.
+ */
+export class ACPAgent {
+  static readonly componentType = 'ACP_AGENT' as const;
+
+  static toDeletionIdentifier(sourceAgentId: string): ManifestComponentDeletion {
+    return {
+      type: ACPAgent.componentType,
+      source_agent_id: sourceAgentId,
+    };
+  }
+
+  private readonly _sourceAgentId: string;
+  private readonly _apiName: string;
+  private _name: string;
+  private _description: string;
+  private _eventTriggers: ACPAgentEventTrigger[] | undefined;
+  private _files: ACPAgentSourceFile[];
+  private _entrypoint: string;
+
+  constructor(scope: ManifestScope, props: ACPAgentProps, sourceAgentId = props.apiName) {
+    if (props.identityMode !== 'runner') {
+      throw new Error('ACP agents support only runner identity.');
+    }
+    if ((props as unknown as Record<string, unknown>)['skills'] !== undefined) {
+      throw new Error('ACP Agent skill references are not supported by this SDK release.');
+    }
+    this._sourceAgentId = sourceAgentId;
+    this._apiName = props.apiName;
+    this._name = props.name;
+    this._description = props.description;
+    this._eventTriggers = props.eventTriggers == null ? undefined : [...props.eventTriggers];
+    this._files = [...props.files];
+    this._entrypoint = props.entrypoint;
+    scope._register(this);
+  }
+
+  /** Loads this ACP agent from the active existing-manifest JSON context. */
+  static loadFromExisting(apiName: string, options: ExistingManifestContextOptions = {}): ACPAgent {
+    return getExistingManifestContext(options).loadACPAgent(apiName);
+  }
+
+  /** @internal Hydrates an ACP agent from existing manifest wire JSON. */
+  static _fromExistingComponent(scope: ManifestScope, component: Record<string, any>): ACPAgent {
+    if (component['skill_ids'] !== undefined) {
+      throw new Error('ACP Agent skill references are not supported by this SDK release.');
+    }
+    const identityMode = requireStringComponentField(
+      component,
+      'identity_mode',
+      ACPAgent.componentType,
+    ) as ACPAgentIdentityMode;
+    if (identityMode !== 'runner') {
+      throw new Error('ACP agents support only runner identity.');
+    }
+    const props: ACPAgentProps = {
+      apiName: requireStringComponentField(component, 'api_name', ACPAgent.componentType),
+      name: requireStringComponentField(component, 'name', ACPAgent.componentType),
+      description: requireStringComponentField(component, 'description', ACPAgent.componentType, {
+        allowEmpty: true,
+      }),
+      identityMode,
+      files: requireArrayComponentField<Record<string, any>>(component, 'files', ACPAgent.componentType).map(
+        (file) => ({
+          path: requireStringComponentField(file, 'path', ACPAgent.componentType),
+          content: requireStringComponentField(file, 'content', ACPAgent.componentType),
+          kind: requireStringComponentField(file, 'kind', ACPAgent.componentType),
+        }),
+      ),
+      entrypoint: requireStringComponentField(component, 'entrypoint', ACPAgent.componentType),
+    };
+    if (component['event_triggers'] !== undefined) {
+      props.eventTriggers = requireArrayComponentField<Record<string, any>>(
+        component,
+        'event_triggers',
+        ACPAgent.componentType,
+      ).map((trigger) => ({
+        key: requireStringComponentField(trigger, 'key', ACPAgent.componentType),
+        eventKey: requireStringComponentField(trigger, 'event_key', ACPAgent.componentType),
+        rqlFormula: requireStringComponentField(trigger, 'rql_formula', ACPAgent.componentType, {
+          allowEmpty: true,
+        }),
+        promptTemplate: requireStringComponentField(trigger, 'prompt_template', ACPAgent.componentType),
+        enabled: requireBooleanComponentField(trigger, 'enabled', ACPAgent.componentType),
+      }));
+    }
+    return new ACPAgent(
+      scope,
+      props,
+      requireStringComponentField(component, 'source_agent_id', ACPAgent.componentType),
+    );
+  }
+
+  getSourceAgentId(): string {
+    return this._sourceAgentId;
+  }
+
+  getApiName(): string {
+    return this._apiName;
+  }
+
+  setName(name: string): this {
+    this._name = name;
+    return this;
+  }
+
+  setDescription(description: string): this {
+    this._description = description;
+    return this;
+  }
+
+  setIdentity(identityMode: ACPAgentIdentityMode): this {
+    if (identityMode !== 'runner') {
+      throw new Error('ACP agents support only runner identity.');
+    }
+    return this;
+  }
+
+  setEventTriggers(eventTriggers: ACPAgentEventTrigger[] | undefined): this {
+    this._eventTriggers = eventTriggers == null ? undefined : [...eventTriggers];
+    return this;
+  }
+
+  setSource(files: ACPAgentSourceFile[], entrypoint: string): this {
+    this._files = [...files];
+    this._entrypoint = entrypoint;
+    return this;
+  }
+
+  toDict(): Record<string, any> {
+    const component: Record<string, any> = {
+      type: ACPAgent.componentType,
+      source_agent_id: this._sourceAgentId,
+      api_name: this._apiName,
+      name: this._name,
+      description: this._description,
+      identity_mode: 'runner',
+      files: this._files.map((file) => ({
+        type: ACPAgent.componentType,
+        path: file.path,
+        content: file.content,
+        kind: file.kind,
+      })),
+      entrypoint: this._entrypoint,
+    };
+    if (this._eventTriggers !== undefined) {
+      component['event_triggers'] = this._eventTriggers.map((trigger) => ({
+        type: ACPAgent.componentType,
+        key: trigger.key,
+        event_key: trigger.eventKey,
+        rql_formula: trigger.rqlFormula,
+        prompt_template: trigger.promptTemplate,
+        enabled: trigger.enabled,
+      }));
+    }
+    return component;
+  }
+}

package/src/lib/manifest/existing-manifest-context.ts

@@ -1,4 +1,5 @@
 import { App } from './app';
+import { ACPAgent } from './acp-agent';
 import { Agent } from './agent';
 import { Category } from './category';
 import { CustomField } from './custom-field';
@@ -81,6 +82,7 @@ function componentLabel(component: Record<string, any>): string {
   const type = component['type'] ?? 'UNKNOWN';
   const id =
     component['api_name'] ??
+    component['source_agent_id'] ??
     component['layout_id'] ??
     component['view_id'] ??
     component['action_id'] ??
@@ -344,10 +346,21 @@ export class ExistingManifestContext {
     return this.loadAgentComponent(component);
   }
 
+  loadACPAgent(apiName: string): ACPAgent {
+    const component = this.findUnique(
+      'ACP_AGENT',
+      (candidate) => candidate['api_name'] === apiName,
+      `ACP_AGENT ${apiName}`,
+    );
+    return this.loadACPAgentComponent(component);
+  }
+
   private loadComponent(component: Record<string, any>): unknown {
     switch (component['type']) {
       case 'AGENT':
         return this.loadAgentComponent(component);
+      case 'ACP_AGENT':
+        return this.loadACPAgentComponent(component);
       case 'CUSTOM_CATEGORY':
         return this.loadCategoryComponent(component);
       case 'CUSTOM_OBJECT':
@@ -604,6 +617,15 @@ export class ExistingManifestContext {
     );
   }
 
+  private loadACPAgentComponent(component: Record<string, any>): ACPAgent {
+    requireStringComponentField(component, 'source_agent_id', ACPAgent.componentType);
+    const apiName = requireStringComponentField(component, 'api_name', ACPAgent.componentType);
+    const cacheKey = this.cacheKey('ACP_AGENT', apiName);
+    return this.getOrLoad(cacheKey, () =>
+      ACPAgent._fromExistingComponent(this.getManifestBuilder(), component),
+    );
+  }
+
   private loadRawComponent(component: Record<string, any>): ExistingRawComponent {
     const index = this.componentIndexes.get(component) ?? -1;
     const cacheKey = this.cacheKey('RAW', `${index}:${componentLabel(component)}`);

package/src/lib/manifest/index.ts

@@ -2,6 +2,14 @@
 
 export { Agent, type AgentIdentityMode, type AgentProps, type AgentSourceFile } from './agent';
 
+export {
+  ACPAgent,
+  type ACPAgentEventTrigger,
+  type ACPAgentIdentityMode,
+  type ACPAgentProps,
+  type ACPAgentSourceFile,
+} from './acp-agent';
+
 export {
   generateId,
   type EdgeType,

package/src/lib/manifest/manifest-builder.ts

@@ -14,6 +14,7 @@ export interface ManifestComponent {
  * Wire-level component types supported by the manifest builder.
  */
 export type ManifestComponentType =
+  | 'ACP_AGENT'
   | 'AGENT'
   | 'CUSTOM_APP'
   | 'CUSTOM_CATEGORY'

package/src/resources/app-users.ts

@@ -252,6 +252,11 @@ export interface AppUserListParams {
 
   filter?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/break-policies.ts

@@ -113,6 +113,11 @@ export interface BreakPolicyRetrieveResponse extends BusinessPartnersAPI.Meta {
 export interface BreakPolicyListParams {
   cursor?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/break-types.ts

@@ -229,6 +229,11 @@ export interface BreakTypeListParams {
 
   filter?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/business-partner-groups.ts

@@ -114,6 +114,11 @@ export interface BusinessPartnerGroupListParams {
 
   expand?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/business-partners.ts

@@ -163,6 +163,11 @@ export interface BusinessPartnerListParams {
 
   filter?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/business-structure-paths.ts

@@ -139,6 +139,11 @@ export interface BusinessStructurePathListParams {
 
   expand?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/candidate-applications.ts

@@ -89,6 +89,11 @@ export interface CandidateApplicationListParams {
 
   expand?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/candidates.ts

@@ -72,6 +72,11 @@ export interface CandidateListResponse {
 export interface CandidateListParams {
   cursor?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/companies.ts

@@ -103,6 +103,11 @@ export interface CompanyListParams {
 
   expand?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

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

@@ -224,6 +224,11 @@ export interface CompanyLegalEntityListParams {
 
   filter?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

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

@@ -102,6 +102,11 @@ export interface CompanyLegalEntityWorkerListParams {
 
   filter?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/compensation-bands-details.ts

@@ -125,6 +125,11 @@ export interface CompensationBandsDetailListParams {
 
   filter?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/compensations.ts

@@ -300,6 +300,11 @@ export interface CompensationListParams {
 
   expand?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/custom-fields.ts

@@ -92,6 +92,11 @@ export interface CustomFieldListResponse {
 export interface CustomFieldListParams {
   cursor?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/custom-objects/custom-objects.ts

@@ -6,6 +6,7 @@ import {
   CustomObjectField,
   CustomObjectFieldsPageCursorURL,
   FieldCreateParams,
+  FieldListParams,
   FieldUpdateParams,
   Fields,
 } from './fields';
@@ -20,6 +21,7 @@ import {
   RecordBulkUpdateResponse,
   RecordCreateParams,
   RecordCreateResponse,
+  RecordListParams,
   RecordQueryParams,
   RecordQueryResponse,
   RecordUpdateParams,
@@ -44,8 +46,11 @@ export class CustomObjects extends APIResource {
    *
    * - Requires: `API Tier 1`
    */
-  list(options?: RequestOptions): PagePromise<CustomObjectsPageCursorURL, CustomObject> {
-    return this._client.getAPIList('/custom-objects/', PageCursorURL<CustomObject>, options);
+  list(
+    query: CustomObjectListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<CustomObjectsPageCursorURL, CustomObject> {
+    return this._client.getAPIList('/custom-objects/', PageCursorURL<CustomObject>, { query, ...options });
   }
 
   /**
@@ -152,6 +157,15 @@ export interface CustomObject {
   owner_id?: string;
 }
 
+export interface CustomObjectListParams {
+  cursor?: string;
+
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+}
+
 /** Request payload accepted by `client.customObjects.create(...)`. */
 export interface CustomObjectCreateParams {
   /**
@@ -210,6 +224,7 @@ export declare namespace CustomObjects {
   export {
     type CustomObject as CustomObject,
     type CustomObjectsPageCursorURL as CustomObjectsPageCursorURL,
+    type CustomObjectListParams as CustomObjectListParams,
     type CustomObjectCreateParams as CustomObjectCreateParams,
     type CustomObjectUpdateParams as CustomObjectUpdateParams,
   };
@@ -218,6 +233,7 @@ export declare namespace CustomObjects {
     Fields as Fields,
     type CustomObjectField as CustomObjectField,
     type CustomObjectFieldsPageCursorURL as CustomObjectFieldsPageCursorURL,
+    type FieldListParams as FieldListParams,
     type FieldCreateParams as FieldCreateParams,
     type FieldUpdateParams as FieldUpdateParams,
   };
@@ -231,6 +247,7 @@ export declare namespace CustomObjects {
     type RecordBulkCreateResponse as RecordBulkCreateResponse,
     type RecordBulkUpdateResponse as RecordBulkUpdateResponse,
     type CustomObjectDataRowsPageCursorURL as CustomObjectDataRowsPageCursorURL,
+    type RecordListParams as RecordListParams,
     type RecordCreateParams as RecordCreateParams,
     type RecordQueryParams as RecordQueryParams,
     type RecordUpdateParams as RecordUpdateParams,

package/src/resources/custom-objects/fields.ts

@@ -18,12 +18,13 @@ export class Fields extends APIResource {
    */
   list(
     customObjectAPIName: string,
+    query: FieldListParams | null | undefined = {},
     options?: RequestOptions,
   ): PagePromise<CustomObjectFieldsPageCursorURL, CustomObjectField> {
     return this._client.getAPIList(
       path`/custom-objects/${customObjectAPIName}/fields/`,
       PageCursorURL<CustomObjectField>,
-      options,
+      { query, ...options },
     );
   }
 
@@ -77,6 +78,15 @@ export class Fields extends APIResource {
 
 export type CustomObjectFieldsPageCursorURL = PageCursorURL<CustomObjectField>;
 
+export interface FieldListParams {
+  cursor?: string;
+
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+}
+
 /** Supported wire-level field-type identifiers for custom-object fields. */
 export type CustomObjectFieldType =
   | 'TEXT'
@@ -442,6 +452,7 @@ export declare namespace Fields {
     type CustomObjectNameFieldDetails as CustomObjectNameFieldDetails,
     type CustomObjectField as CustomObjectField,
     type CustomObjectFieldsPageCursorURL as CustomObjectFieldsPageCursorURL,
+    type FieldListParams as FieldListParams,
     type FieldCreateParams as FieldCreateParams,
     type FieldUpdateParams as FieldUpdateParams,
   };

package/src/resources/custom-objects/index.ts

@@ -3,6 +3,7 @@
 export {
   CustomObjects,
   type CustomObject,
+  type CustomObjectListParams,
   type CustomObjectCreateParams,
   type CustomObjectUpdateParams,
   type CustomObjectsPageCursorURL,
@@ -10,6 +11,7 @@ export {
 export {
   Fields,
   type CustomObjectField,
+  type FieldListParams,
   type FieldCreateParams,
   type FieldUpdateParams,
   type CustomObjectFieldsPageCursorURL,
@@ -22,6 +24,7 @@ export {
   type RecordUpdateResponse,
   type RecordBulkCreateResponse,
   type RecordBulkUpdateResponse,
+  type RecordListParams,
   type RecordCreateParams,
   type RecordQueryParams,
   type RecordUpdateParams,

package/src/resources/custom-objects/records.ts

@@ -18,12 +18,13 @@ export class Records extends APIResource {
    */
   list(
     customObjectAPIName: string,
+    query: RecordListParams | null | undefined = {},
     options?: RequestOptions,
   ): PagePromise<CustomObjectDataRowsPageCursorURL, CustomObjectDataRow> {
     return this._client.getAPIList(
       path`/custom-objects/${customObjectAPIName}/records/`,
       PageCursorURL<CustomObjectDataRow>,
-      options,
+      { query, ...options },
     );
   }
 
@@ -263,6 +264,15 @@ export interface RecordBulkUpdateResponse {
   data?: Array<CustomObjectDataRow>;
 }
 
+export interface RecordListParams {
+  cursor?: string;
+
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+}
+
 export type RecordCreateParams = { [key: string]: unknown };
 
 export interface RecordQueryParams {
@@ -332,6 +342,7 @@ export declare namespace Records {
     type RecordBulkCreateResponse as RecordBulkCreateResponse,
     type RecordBulkUpdateResponse as RecordBulkUpdateResponse,
     type CustomObjectDataRowsPageCursorURL as CustomObjectDataRowsPageCursorURL,
+    type RecordListParams as RecordListParams,
     type RecordCreateParams as RecordCreateParams,
     type RecordQueryParams as RecordQueryParams,
     type RecordUpdateParams as RecordUpdateParams,

package/src/resources/custom-settings.ts

@@ -280,6 +280,11 @@ export interface CustomSettingUpdateResponse {
 export interface CustomSettingListParams {
   cursor?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/departments.ts

@@ -116,6 +116,11 @@ export interface DepartmentListParams {
 
   expand?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/device-orders.ts

@@ -182,6 +182,11 @@ export interface DeviceOrderListParams {
 
   filter?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }
 

package/src/resources/devices.ts

@@ -478,6 +478,11 @@ export interface DeviceListParams {
 
   filter?: string;
 
+  /**
+   * The maximum number of results to return. Defaults to 50. Maximum is 100.
+   */
+  limit?: number;
+
   order_by?: string;
 }