@rippling/rippling-sdk 0.2.0-alpha.79 → 0.2.0-alpha.80

package/src/lib/manifest/agent.ts

@@ -0,0 +1,141 @@
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
+import type { ManifestScope } from './manifest-builder';
+import type { CustomSkill } from './custom-skill';
+import { requireArrayComponentField, requireStringComponentField } from './_existing-component-fields';
+
+export type AgentIdentityMode = 'runner' | 'user';
+
+export interface AgentSourceFile {
+  path: string;
+  content: string;
+  kind: string;
+}
+
+/**
+ * Initialization properties for {@link Agent}.
+ */
+export interface AgentProps {
+  /** Stable system name for this agent. */
+  apiName: string;
+  /** Display name shown in Rippling. */
+  name: string;
+  /** Human-readable description of the agent. */
+  description?: string;
+  /** Identity used when the agent runs. Defaults to `runner`. */
+  identityMode?: AgentIdentityMode;
+  /** Role used when `identityMode` is `user`. */
+  identityRoleId?: string;
+  /** Source files for the agent's latest revision. */
+  files: AgentSourceFile[];
+  /** Path of the source file that starts the agent. */
+  entrypoint: string;
+  /** Existing Custom Skills included in the agent's latest revision. */
+  skills?: CustomSkill[];
+}
+
+/**
+ * Defines an agent and its latest source revision in a single manifest component.
+ *
+ * Reinstalling a component with the same `apiName` updates the agent metadata and
+ * creates a new source revision when its source or skills change.
+ */
+export class Agent {
+  static readonly componentType = 'AGENT' as const;
+
+  private readonly _apiName: string;
+  private _name: string;
+  private _description: string | undefined;
+  private _identityMode: AgentIdentityMode | undefined;
+  private _identityRoleId: string | undefined;
+  private _files: AgentSourceFile[];
+  private _entrypoint: string;
+  private _skills: CustomSkill[] | undefined;
+
+  constructor(scope: ManifestScope, props: AgentProps) {
+    this._apiName = props.apiName;
+    this._name = props.name;
+    this._description = props.description;
+    this._identityMode = props.identityMode;
+    this._identityRoleId = props.identityRoleId;
+    this._files = props.files;
+    this._entrypoint = props.entrypoint;
+    this._skills = props.skills == null ? undefined : [...props.skills];
+    scope._register(this);
+  }
+
+  /** Loads this agent from the active existing-manifest JSON context. */
+  static loadFromExisting(apiName: string, options: ExistingManifestContextOptions = {}): Agent {
+    return getExistingManifestContext(options).loadAgent(apiName);
+  }
+
+  /** @internal Hydrates an agent from existing manifest wire JSON. */
+  static _fromExistingComponent(
+    scope: ManifestScope,
+    component: Record<string, any>,
+    resolveSkill: (sourceSkillId: string) => CustomSkill,
+  ): Agent {
+    const props: AgentProps = {
+      apiName: requireStringComponentField(component, 'api_name', Agent.componentType),
+      name: requireStringComponentField(component, 'name', Agent.componentType),
+      files: component['files'] ?? [],
+      entrypoint: requireStringComponentField(component, 'entrypoint', Agent.componentType),
+    };
+    if (component['description'] !== undefined) props.description = component['description'];
+    if (component['identity_mode'] !== undefined) props.identityMode = component['identity_mode'];
+    if (component['identity_role_id'] !== undefined) props.identityRoleId = component['identity_role_id'];
+    if (component['skill_ids'] !== undefined) {
+      props.skills = requireArrayComponentField<string>(component, 'skill_ids', Agent.componentType).map(
+        resolveSkill,
+      );
+    }
+    return new Agent(scope, props);
+  }
+
+  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: AgentIdentityMode, identityRoleId?: string): this {
+    this._identityMode = identityMode;
+    this._identityRoleId = identityRoleId;
+    return this;
+  }
+
+  setSource(files: AgentSourceFile[], entrypoint: string): this {
+    this._files = files;
+    this._entrypoint = entrypoint;
+    return this;
+  }
+
+  setSkills(skills: CustomSkill[]): this {
+    this._skills = [...skills];
+    return this;
+  }
+
+  toDict(): Record<string, any> {
+    const component: Record<string, any> = {
+      type: Agent.componentType,
+      api_name: this._apiName,
+      name: this._name,
+      files: this._files,
+      entrypoint: this._entrypoint,
+    };
+    if (this._description !== undefined) component['description'] = this._description;
+    if (this._identityMode !== undefined) component['identity_mode'] = this._identityMode;
+    if (this._identityRoleId !== undefined) component['identity_role_id'] = this._identityRoleId;
+    if (this._skills !== undefined) {
+      component['skill_ids'] = this._skills.map((skill) => skill.getSourceSkillId());
+    }
+    return component;
+  }
+}

package/src/lib/manifest/custom-skill.ts

@@ -0,0 +1,205 @@
+import { generateId } from './_helpers';
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
+import type { ManifestComponentDeletion, ManifestScope } from './manifest-builder';
+import { requireStringComponentField } from './_existing-component-fields';
+
+export type CustomSkillStatus = 'active' | 'inactive';
+export type CustomSkillSourceType = 'user' | 'company';
+
+/**
+ * Initialization properties for {@link CustomSkill}.
+ */
+export interface CustomSkillProps {
+  /**
+   * Source-side identifier for this Custom Skill.
+   *
+   * For a new skill, omit this field and the SDK generates a temporary handle
+   * that Composer maps to the skill's generated database UUID during deploy.
+   *
+   * For an existing skill, use the `source_skill_id` loaded from component
+   * search/extraction.
+   *
+   * Optional. Auto-generated when omitted. @default generateId('skill')
+   */
+  sourceSkillId?: string;
+  /**
+   * Display name shown in Rippling AI.
+   *
+   * Required.
+   */
+  name: string;
+  /**
+   * Description used to explain when the skill applies.
+   *
+   * Required. Use `null` to clear this field when updating an existing skill.
+   */
+  description: string | null;
+  /**
+   * Markdown instruction content for the skill.
+   *
+   * Required.
+   */
+  content: string;
+  /**
+   * Optional folder path for organizing skills. Use `null` to clear this field
+   * when updating an existing skill.
+   */
+  path?: string | null;
+  /**
+   * Whether the skill is active or inactive.
+   *
+   * Required.
+   */
+  status: CustomSkillStatus;
+  /**
+   * Skill visibility. `user` creates a personal skill; `company` creates a
+   * company skill.
+   *
+   * Optional create-time visibility. Do not set when updating an existing
+   * skill; use `CustomSkill.loadFromExisting(...)` so the extracted value can
+   * round-trip unchanged.
+   */
+  sourceType?: CustomSkillSourceType;
+}
+
+/**
+ * Defines a Rippling AI Custom Skill and registers it with the manifest.
+ */
+export class CustomSkill {
+  static readonly componentType = 'CUSTOM_SKILL' as const;
+
+  static toDeletionIdentifier(sourceSkillId: string): ManifestComponentDeletion {
+    return {
+      type: CustomSkill.componentType,
+      source_skill_id: sourceSkillId,
+    };
+  }
+
+  private readonly _sourceSkillId: string;
+  private _name: string;
+  private _description: string | null | undefined;
+  private _content: string;
+  private _path: string | null | undefined;
+  private _status: CustomSkillStatus;
+  private _sourceType: CustomSkillSourceType | undefined;
+
+  /**
+   * @param scope - The manifest to register this skill with.
+   * @param props - Initialization properties.
+   */
+  constructor(scope: ManifestScope, props: CustomSkillProps) {
+    if (props.sourceSkillId != null && props.sourceType != null) {
+      throw new Error(
+        'CustomSkill sourceType is create-time only. Omit sourceType when constructing an existing skill; ' +
+          'use CustomSkill.loadFromExisting(...) to update extracted skills.',
+      );
+    }
+    this._sourceSkillId = props.sourceSkillId ?? generateId('skill');
+    this._name = props.name;
+    this._description = props.description;
+    this._content = props.content;
+    this._path = props.path;
+    this._status = props.status;
+    this._sourceType = props.sourceType;
+    scope._register(this);
+  }
+
+  /**
+   * Loads this skill from the active existing-manifest JSON context.
+   */
+  static loadFromExisting(sourceSkillId: string, options: ExistingManifestContextOptions = {}): CustomSkill {
+    return getExistingManifestContext(options).loadCustomSkill(sourceSkillId);
+  }
+
+  /** @internal Hydrates a custom skill from existing manifest wire JSON. */
+  static _fromExistingComponent(scope: ManifestScope, component: Record<string, any>): CustomSkill {
+    const props: CustomSkillProps = {
+      sourceSkillId: requireStringComponentField(component, 'source_skill_id', CustomSkill.componentType),
+      name: requireStringComponentField(component, 'name', CustomSkill.componentType),
+      description:
+        component['description'] == null ?
+          null
+        : requireStringComponentField(component, 'description', CustomSkill.componentType),
+      content: requireStringComponentField(component, 'content', CustomSkill.componentType),
+      status: requireStringComponentField(
+        component,
+        'status',
+        CustomSkill.componentType,
+      ) as CustomSkillStatus,
+    };
+    if (typeof component['path'] === 'string') props.path = component['path'];
+    if (typeof component['source_type'] === 'string') {
+      props.sourceType = component['source_type'] as CustomSkillSourceType;
+    }
+    const { sourceType, ...loadProps } = props;
+    const skill = new CustomSkill(scope, loadProps);
+    skill._sourceType = sourceType;
+    return skill;
+  }
+
+  /**
+   * Returns this skill's source-side manifest identifier. New skills use a
+   * generated temporary handle; extracted skills use their database UUID.
+   */
+  getSourceSkillId(): string {
+    return this._sourceSkillId;
+  }
+
+  /**
+   * Replaces the display name for this skill.
+   */
+  setName(name: string): this {
+    this._name = name;
+    return this;
+  }
+
+  /**
+   * Replaces the description for this skill. Pass `null` to clear it.
+   */
+  setDescription(description: string | null): this {
+    this._description = description;
+    return this;
+  }
+
+  /**
+   * Replaces the plaintext markdown instruction content for this skill.
+   */
+  setContent(content: string): this {
+    this._content = content;
+    return this;
+  }
+
+  /**
+   * Replaces the optional folder path for this skill. Pass `null` to clear it,
+   * or `undefined` to omit it from the serialized manifest.
+   */
+  setPath(path: string | null | undefined): this {
+    this._path = path;
+    return this;
+  }
+
+  /**
+   * Replaces whether this skill is active or inactive.
+   */
+  setStatus(status: CustomSkillStatus): this {
+    this._status = status;
+    return this;
+  }
+
+  /**
+   * Serializes this skill to the wire format consumed by the manifest install endpoint.
+   */
+  toDict(): Record<string, any> {
+    const component: Record<string, any> = {
+      type: CustomSkill.componentType,
+      source_skill_id: this._sourceSkillId,
+      name: this._name,
+      content: this._content,
+      status: this._status,
+    };
+    if (this._description !== undefined) component['description'] = this._description;
+    if (this._path !== undefined) component['path'] = this._path;
+    if (this._sourceType != null) component['source_type'] = this._sourceType;
+    return component;
+  }
+}

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

@@ -1,4 +1,5 @@
 import { App } from './app';
+import { Agent } from './agent';
 import { Category } from './category';
 import { CustomField } from './custom-field';
 import { CustomFieldSection } from './custom-field-section';
@@ -6,6 +7,7 @@ import { CustomObject } from './custom-object';
 import { CustomObjectAction } from './custom-object-action';
 import { CustomObjectFieldSection } from './custom-object-field-section';
 import { CustomObjectPageLayout } from './custom-object-page-layout';
+import { CustomSkill } from './custom-skill';
 import { Field } from './field';
 import { ListViewDef } from './list-view';
 import { ManifestBuilder, type ManifestComponent } from './manifest-builder';
@@ -85,6 +87,7 @@ function componentLabel(component: Record<string, any>): string {
     component['rule_id'] ??
     component['flow_id'] ??
     component['sdui_page_id'] ??
+    component['source_skill_id'] ??
     component['field_api_name'] ??
     component['section_id'] ??
     'unknown';
@@ -305,6 +308,15 @@ export class ExistingManifestContext {
     return this.loadFunctionComponent(component);
   }
 
+  loadCustomSkill(sourceSkillId: string): CustomSkill {
+    const component = this.findUnique(
+      'CUSTOM_SKILL',
+      (candidate) => candidate['source_skill_id'] === sourceSkillId,
+      `CUSTOM_SKILL ${sourceSkillId}`,
+    );
+    return this.loadCustomSkillComponent(component);
+  }
+
   loadSduiPage(sduiPageId: string): SduiPage {
     const component = this.findUnique(
       'SDUI_PAGE',
@@ -323,8 +335,19 @@ export class ExistingManifestContext {
     return this.loadAppComponent(component);
   }
 
+  loadAgent(apiName: string): Agent {
+    const component = this.findUnique(
+      'AGENT',
+      (candidate) => candidate['api_name'] === apiName,
+      `AGENT ${apiName}`,
+    );
+    return this.loadAgentComponent(component);
+  }
+
   private loadComponent(component: Record<string, any>): unknown {
     switch (component['type']) {
+      case 'AGENT':
+        return this.loadAgentComponent(component);
       case 'CUSTOM_CATEGORY':
         return this.loadCategoryComponent(component);
       case 'CUSTOM_OBJECT':
@@ -347,6 +370,8 @@ export class ExistingManifestContext {
         return this.loadValidationComponent(component);
       case 'CUSTOM_OBJECT_RECORD_TRIGGERED_FLOW':
         return this.loadRuleComponent(component);
+      case 'CUSTOM_SKILL':
+        return this.loadCustomSkillComponent(component);
       case 'FUNCTION':
         return this.loadFunctionComponent(component);
       case 'SDUI_PAGE':
@@ -538,6 +563,18 @@ export class ExistingManifestContext {
     );
   }
 
+  private loadCustomSkillComponent(component: Record<string, any>): CustomSkill {
+    const sourceSkillId = requireStringComponentField(
+      component,
+      'source_skill_id',
+      CustomSkill.componentType,
+    );
+    const cacheKey = this.cacheKey('CUSTOM_SKILL', sourceSkillId);
+    return this.getOrLoad(cacheKey, () =>
+      CustomSkill._fromExistingComponent(this.getManifestBuilder(), component),
+    );
+  }
+
   private loadSduiPageComponent(component: Record<string, any>): SduiPage {
     const sduiPageId = requireStringComponentField(component, 'sdui_page_id', SduiPage.componentType);
     const cacheKey = this.cacheKey('SDUI_PAGE', sduiPageId);
@@ -557,6 +594,16 @@ export class ExistingManifestContext {
     });
   }
 
+  private loadAgentComponent(component: Record<string, any>): Agent {
+    const apiName = requireStringComponentField(component, 'api_name', Agent.componentType);
+    const cacheKey = this.cacheKey('AGENT', apiName);
+    return this.getOrLoad(cacheKey, () =>
+      Agent._fromExistingComponent(this.getManifestBuilder(), component, (sourceSkillId) =>
+        this.loadRequiredCustomSkillForAgent(sourceSkillId, apiName),
+      ),
+    );
+  }
+
   private loadRawComponent(component: Record<string, any>): ExistingRawComponent {
     const index = this.componentIndexes.get(component) ?? -1;
     const cacheKey = this.cacheKey('RAW', `${index}:${componentLabel(component)}`);
@@ -648,6 +695,20 @@ export class ExistingManifestContext {
     return this.loadFunctionComponent(functionComponent);
   }
 
+  private loadRequiredCustomSkillForAgent(sourceSkillId: string, agentApiName: string): CustomSkill {
+    const skillComponent = this.ofType('CUSTOM_SKILL').find(
+      (candidate) => candidate['source_skill_id'] === sourceSkillId,
+    );
+    if (skillComponent == null) {
+      throw new Error(
+        `AGENT ${agentApiName} references CUSTOM_SKILL ${sourceSkillId}, ` +
+          'but that custom skill component is not present. Pass the full existing component extraction ' +
+          'to ManifestBuilder.loadFromExistingJson(...).',
+      );
+    }
+    return this.loadCustomSkillComponent(skillComponent);
+  }
+
   private loadSyntheticFieldReference(customObjectApiName: string, fieldApiName: string): Field {
     const cacheKey = this.cacheKey('CUSTOM_OBJECT_FIELD_REF', `${customObjectApiName}.${fieldApiName}`);
     return this.getOrLoad(cacheKey, () => Field._syntheticReference(customObjectApiName, fieldApiName));

package/src/lib/manifest/index.ts

@@ -1,5 +1,7 @@
 /** Manifest builder public API (hand-written, not Stainless-generated). */
 
+export { Agent, type AgentIdentityMode, type AgentProps, type AgentSourceFile } from './agent';
+
 export {
   generateId,
   type EdgeType,
@@ -58,6 +60,13 @@ export {
   type IconConfig,
 } from './custom-object';
 
+export {
+  CustomSkill,
+  type CustomSkillProps,
+  type CustomSkillSourceType,
+  type CustomSkillStatus,
+} from './custom-skill';
+
 export {
   CustomObjectFieldSection,
   type CustomObjectFieldSectionLoadFromExistingOptions,

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 =
+  | 'AGENT'
   | 'CUSTOM_APP'
   | 'CUSTOM_CATEGORY'
   | 'CUSTOM_FIELD_SECTION'
@@ -26,6 +27,7 @@ export type ManifestComponentType =
   | 'CUSTOM_OBJECT_PAGE_LAYOUT'
   | 'CUSTOM_OBJECT_RECORD_TRIGGERED_FLOW'
   | 'CUSTOM_OBJECT_VALIDATION_RULE'
+  | 'CUSTOM_SKILL'
   | 'FUNCTION'
   | 'SDUI_PAGE'
   | 'WORKFLOW_DEFINITION';

package/src/resources/index.ts

@@ -462,7 +462,9 @@ export {
   type Team,
   type TeamRetrieveResponse,
   type TeamListParams,
+  type TeamCreateParams,
   type TeamRetrieveParams,
+  type TeamUpdateParams,
   type TeamsPageCursorURL,
 } from './teams';
 export {

package/src/resources/leave-program-evaluations.ts

@@ -26,9 +26,9 @@ export interface LeaveProgramEvaluationCreateResponse {
   leave_plan: unknown;
 
   /**
-   * Distinct evidence gaps reported by evaluated eligibility rules.
+   * Structured evidence gaps reported by evaluated eligibility rules.
    */
-  missing_evidence: Array<string>;
+  missing_evidence: Array<LeaveProgramEvaluationCreateResponse.MissingEvidence>;
 
   /**
    * Per-program rule outputs in evaluation order.
@@ -36,6 +36,30 @@ export interface LeaveProgramEvaluationCreateResponse {
   program_results: Array<unknown>;
 }
 
+export namespace LeaveProgramEvaluationCreateResponse {
+  export interface MissingEvidence {
+    /**
+     * Expected answer type for this evidence key.
+     */
+    answer_type: string;
+
+    /**
+     * Stable evidence key that can be supplied in supplemental_evidence.
+     */
+    key: string;
+
+    /**
+     * Human-readable label for the missing evidence.
+     */
+    label: string;
+
+    /**
+     * Leave program codes that reported this missing evidence.
+     */
+    program_codes: Array<string>;
+  }
+}
+
 export interface LeaveProgramEvaluationCreateParams {
   /**
    * Requested leave start date.
@@ -63,6 +87,12 @@ export interface LeaveProgramEvaluationCreateParams {
    */
   child_entered_family_date?: string;
 
+  /**
+   * Demo/test-company only evidence overrides for exercising eligibility scenarios
+   * when the role's real data would not qualify.
+   */
+  evidence_override?: unknown;
+
   /**
    * Optional parental leave relationship type for parental leave programs.
    */
@@ -78,6 +108,12 @@ export interface LeaveProgramEvaluationCreateParams {
    * program runs in dependency order.
    */
   program_codes?: Array<string>;
+
+  /**
+   * Answers for evidence keys returned in missing_evidence. These answers only fill
+   * facts that the evaluation reported as missing.
+   */
+  supplemental_evidence?: unknown;
 }
 
 export declare namespace LeaveProgramEvaluations {

package/src/resources/teams.ts

@@ -4,6 +4,7 @@ import { APIResource } from '../core/resource';
 import * as BusinessPartnersAPI from './business-partners';
 import { APIPromise } from '../core/api-promise';
 import { PageCursorURL, PagePromise } from '../core/pagination';
+import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
@@ -25,6 +26,13 @@ export class Teams extends APIResource {
     return this._client.getAPIList('/teams/', PageCursorURL<Team>, { query, ...options });
   }
 
+  /**
+   * Create a new team
+   */
+  create(body: TeamCreateParams, options?: RequestOptions): APIPromise<Team> {
+    return this._client.post('/teams/', { body, ...options });
+  }
+
   /**
    * Retrieve a specific team
    */
@@ -35,6 +43,27 @@ export class Teams extends APIResource {
   ): APIPromise<TeamRetrieveResponse> {
     return this._client.get(path`/teams/${id}/`, { query, ...options });
   }
+
+  /**
+   * Update a specific team.
+   */
+  update(
+    id: string,
+    body: TeamUpdateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Team> {
+    return this._client.patch(path`/teams/${id}/`, { body, ...options });
+  }
+
+  /**
+   * Delete a team
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/teams/${id}/`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
 }
 
 export type TeamsPageCursorURL = PageCursorURL<Team>;
@@ -86,16 +115,42 @@ export interface TeamListParams {
   order_by?: string;
 }
 
+export interface TeamCreateParams {
+  /**
+   * The name of the team.
+   */
+  name: string;
+
+  /**
+   * The parent team
+   */
+  parent_id?: string;
+}
+
 export interface TeamRetrieveParams {
   expand?: string;
 }
 
+export interface TeamUpdateParams {
+  /**
+   * The name of the team.
+   */
+  name?: string;
+
+  /**
+   * The parent team
+   */
+  parent_id?: string;
+}
+
 export declare namespace Teams {
   export {
     type Team as Team,
     type TeamRetrieveResponse as TeamRetrieveResponse,
     type TeamsPageCursorURL as TeamsPageCursorURL,
     type TeamListParams as TeamListParams,
+    type TeamCreateParams as TeamCreateParams,
     type TeamRetrieveParams as TeamRetrieveParams,
+    type TeamUpdateParams as TeamUpdateParams,
   };
 }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.2.0-alpha.79'; // x-release-please-version
+export const VERSION = '0.2.0-alpha.80'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.0-alpha.79";
+export declare const VERSION = "0.2.0-alpha.80";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.0-alpha.79";
+export declare const VERSION = "0.2.0-alpha.80";
 //# sourceMappingURL=version.d.ts.map