@rippling/rippling-sdk 0.2.0-alpha.100

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

@@ -0,0 +1,215 @@
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
+import type { ManifestComponentDeletion, ManifestScope } from './manifest-builder';
+import {
+  requireArrayComponentField,
+  requireBooleanComponentField,
+  requireStringComponentField,
+} from './_existing-component-fields';
+import type { BusinessEventKey } from './business-event';
+
+/** 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 {
+  /** Stable identifier for this trigger within the agent. */
+  key: string;
+  /** Business event to subscribe to. Availability is validated during installation. */
+  eventKey: BusinessEventKey;
+  /** Optional RQL condition evaluated against the event object. @default '' */
+  rqlFormula?: string;
+  /** Prompt sent to the agent when the event matches. */
+  promptTemplate: string;
+  /** Whether this trigger receives events. @default true */
+  enabled?: boolean;
+}
+
+export type ACPAgentEventKey = BusinessEventKey;
+
+/** 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;
+  /** Trigger configuration managed by this manifest. Pass [] for no triggers. */
+  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[];
+  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];
+    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),
+      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,
+        ) as BusinessEventKey,
+        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[]): this {
+    this._eventTriggers = [...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,
+      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 ?? true,
+      })),
+    };
+    return component;
+  }
+}

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/app.ts

@@ -0,0 +1,233 @@
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
+import type { ManifestComponentDeletion, ManifestScope } from './manifest-builder';
+import { SduiPage } from './sdui-page';
+import {
+  optionalArrayComponentField,
+  optionalStringComponentField,
+  requireStringComponentField,
+} from './_existing-component-fields';
+import type { AppVisibilityPlatform } from './_helpers';
+
+/**
+ * A single page entry in an {@link App}.
+ *
+ * Apps host SDUI page tabs. To show custom-object records, create an
+ * {@link SduiPage} that renders an SDUI `ObjectListView` for that object.
+ */
+export type AppPage = SduiPage;
+
+/**
+ * S3 icon reference for an {@link App}.
+ */
+export interface AppIcon {
+  /** S3 bucket holding the icon asset. */
+  s3Bucket: string;
+  /** S3 key (path) within `s3Bucket`. */
+  s3Key: string;
+}
+
+/**
+ * Initialization properties for {@link App}.
+ */
+export interface AppProps {
+  /**
+   * Unique identifier for this app (e.g. `'gym_membership_management_app'`).
+   *
+   * Required.
+   */
+  apiName: string;
+  /**
+   * Display name shown as the app title in the Rippling UI.
+   *
+   * Required.
+   */
+  name: string;
+  /**
+   * Human-readable description of what this app does.
+   *
+   * Required.
+   */
+  description: string;
+  /**
+   * App type discriminator.
+   *
+   * Optional. @default `'custom'`
+   */
+  appType?: string;
+  /**
+   * S3 icon for this app.
+   *
+   * Optional. @default null
+   */
+  icon?: AppIcon;
+  /**
+   * Platforms this app is visible on.
+   *
+   * Optional. @default `['WEB']`
+   */
+  visibilityPlatforms?: AppVisibilityPlatform[];
+  /**
+   * SDUI pages shown as tabs in the app. Tab order matches the array order.
+   *
+   * Required. Must include at least one page.
+   */
+  pages: AppPage[];
+}
+
+function resolvePage(entry: AppPage): Record<string, any> {
+  if (!(entry instanceof SduiPage)) {
+    throw new Error(
+      'App pages must be SduiPage instances. To show a custom object, create an SDUI page that renders ObjectListView.',
+    );
+  }
+  const sduiPageId = entry.getSduiPageId();
+  const visibilityPlatforms = entry.getVisibilityPlatforms();
+  return {
+    api_name: sduiPageId,
+    page_type: 'sdui_page',
+    sdui_page_id: sduiPageId,
+    ...(visibilityPlatforms != null && { visibility_platforms: [...visibilityPlatforms] }),
+  };
+}
+
+function resolvePages(pages: AppPage[] | undefined): Record<string, any>[] {
+  if (pages == null || pages.length === 0) {
+    throw new Error('App pages must include at least one page.');
+  }
+  return pages.map(resolvePage);
+}
+
+function clonePages(value: unknown): Record<string, any>[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error('App pages must include at least one page.');
+  }
+  return cloneJson(value) as Record<string, any>[];
+}
+
+function cloneJson<T>(value: T): T {
+  if (value == null) return value;
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+/**
+ * Defines a Rippling app and registers it with the manifest.
+ *
+ * An app is the top-level navigation container. It groups one or more SDUI pages
+ * as tabs visible to users. You would normally define the app last in your
+ * manifest file, after all objects, functions, and SDUI pages have been declared.
+ *
+ * @example
+ * ```ts
+ * new App(manifest, {
+ *   apiName: 'gym_membership_management_app',
+ *   name: 'Gym Membership Management',
+ *   description: 'Members, trainers, schedules, and check-in',
+ *   appType: 'custom',
+ *   pages: [memberListPage, trainerListPage, todaySchedulePage, checkInDeskPage],
+ * });
+ * ```
+ *
+ * @see {@link SduiPage} — SDUI surface tab source.
+ */
+export class App {
+  static readonly componentType = 'CUSTOM_APP' as const;
+
+  static toDeletionIdentifier(apiName: string): ManifestComponentDeletion {
+    return {
+      type: App.componentType,
+      api_name: apiName,
+    };
+  }
+
+  private readonly _apiName: string;
+  private readonly _name: string;
+  private readonly _description: string;
+  private readonly _appType: string | undefined;
+  private readonly _icon: AppIcon | undefined;
+  private readonly _visibilityPlatforms: AppVisibilityPlatform[] | undefined;
+  /** Wire-format pages, resolved eagerly at construction. */
+  private readonly _pages: Record<string, any>[];
+
+  /**
+   * @param scope - The manifest to register this app with.
+   * @param props - Initialization properties.
+   */
+  constructor(scope: ManifestScope, props: AppProps) {
+    this._apiName = props.apiName;
+    this._name = props.name;
+    this._description = props.description;
+    this._appType = props.appType;
+    this._icon = props.icon;
+    this._visibilityPlatforms = props.visibilityPlatforms ? [...props.visibilityPlatforms] : undefined;
+    this._pages = resolvePages(props.pages);
+    scope._register(this);
+  }
+
+  /**
+   * Loads this app from the active existing-manifest JSON context.
+   */
+  static loadFromExisting(apiName: string, options: ExistingManifestContextOptions = {}): App {
+    return getExistingManifestContext(options).loadApp(apiName);
+  }
+
+  /** @internal Hydrates an app from existing manifest wire JSON. */
+  static _fromExistingComponent(scope: ManifestScope, component: Record<string, any>): App {
+    const app = Object.create(App.prototype) as App;
+    Object.assign(app as Record<string, any>, {
+      _apiName: requireStringComponentField(component, 'api_name', App.componentType),
+      _name: requireStringComponentField(component, 'name', App.componentType),
+      _description: optionalStringComponentField(component, 'description'),
+      _appType: component['app_type'],
+      _visibilityPlatforms: optionalArrayComponentField<AppVisibilityPlatform>(
+        component,
+        'visibility_platforms',
+        App.componentType,
+      ),
+      _pages: clonePages(component['pages']),
+    });
+    scope._register(app);
+    return app;
+  }
+
+  private static appIconFromExistingComponent(value: unknown): AppIcon | undefined {
+    if (value == null || typeof value !== 'object') return undefined;
+    const wire = value as Record<string, any>;
+    if (typeof wire['s3_bucket'] !== 'string' || typeof wire['s3_key'] !== 'string') return undefined;
+    return { s3Bucket: wire['s3_bucket'], s3Key: wire['s3_key'] };
+  }
+
+  /**
+   * Returns the api_name of this app (e.g. `'gym_membership_management_app'`).
+   */
+  getApiName(): string {
+    return this._apiName;
+  }
+
+  /**
+   * Returns the display name of this app.
+   */
+  getName(): string {
+    return this._name;
+  }
+
+  /**
+   * Serializes this app to the wire format consumed by the manifest install endpoint.
+   *
+   * @returns A plain object with `type: 'CUSTOM_APP'`. Optional fields are omitted when unset.
+   */
+  toDict(): Record<string, any> {
+    const component: Record<string, any> = {
+      type: App.componentType,
+      api_name: this._apiName,
+      name: this._name,
+      description: this._description,
+    };
+    if (this._icon != null) {
+      component['icon'] = { s3_bucket: this._icon.s3Bucket, s3_key: this._icon.s3Key };
+    }
+    if (this._appType != null) component['app_type'] = this._appType;
+    if (this._visibilityPlatforms != null) component['visibility_platforms'] = [...this._visibilityPlatforms];
+    component['pages'] = this._pages.map((p) => ({ ...p }));
+    return component;
+  }
+}

package/src/lib/manifest/business-event.ts

@@ -0,0 +1,72 @@
+/**
+ * Static business events that can trigger workflows and ACP agents.
+ *
+ * Availability still depends on the target company and execution role. The
+ * manifest installation API is the authority for those checks.
+ */
+export const BusinessEvent = {
+  EMPLOYEE_HIRING_INITIATED: 'EMPLOYEE_HIRING_INITIATED',
+  EMPLOYEE_HIRING_OFFER_SENT: 'EMPLOYEE_HIRING_OFFER_SENT',
+  EMPLOYEE_HIRING_OFFER_ACCEPTED: 'EMPLOYEE_HIRING_OFFER_ACCEPTED',
+  EMPLOYEE_IS_TRANSITIONED: 'EMPLOYEE_IS_TRANSITIONED',
+  EMPLOYEE_TERMINATION_INITIATED: 'EMPLOYEE_TERMINATION_INITIATED',
+  EMPLOYEE_TERMINATION_FINALIZED: 'EMPLOYEE_TERMINATION_FINALIZED',
+  EMPLOYEE_TERMINATION_APPLIED: 'EMPLOYEE_TERMINATION_APPLIED',
+  EMPLOYEE_PROFILE_CHANGE_APPROVED: 'EMPLOYEE_PROFILE_CHANGE_APPROVED',
+  EMPLOYEE_PROFILE_CHANGE_INITIATED: 'EMPLOYEE_PROFILE_CHANGE_INITIATED',
+  LEAVE_REQUEST_CREATED: 'LEAVE_REQUEST_CREATED',
+  LEAVE_REQUEST_APPROVED: 'LEAVE_REQUEST_APPROVED',
+  LEAVE_REQUEST_REJECTED: 'LEAVE_REQUEST_REJECTED',
+  LEAVE_REQUEST_STARTED: 'LEAVE_REQUEST_STARTED',
+  LEAVE_REQUEST_FINISHED: 'LEAVE_REQUEST_FINISHED',
+  LEAVE_REQUEST_CANCELED: 'LEAVE_REQUEST_CANCELED',
+  DOCUMENT_DELETED: 'DOCUMENT_DELETED',
+  DOCUMENT_EXPIRED: 'DOCUMENT_EXPIRED',
+  DOCUMENT_SENT: 'DOCUMENT_SENT',
+  DOCUMENT_SIGNED: 'DOCUMENT_SIGNED',
+  DOCUMENT_UPLOADED: 'DOCUMENT_UPLOADED',
+  DOCUMENT_VIEWED: 'DOCUMENT_VIEWED',
+  OFFER_STATE_REACHED: 'OFFER_STATE_REACHED',
+  REJECTED: 'REJECTED',
+  MILESTONE_GREATER_THAN_OR_EQUAL_TO_SCREEN_STATE: 'MILESTONE_GREATER_THAN_OR_EQUAL_TO_SCREEN_STATE',
+  STAGE_CHANGED: 'STAGE_CHANGED',
+  APPLICANT_CREATED: 'APPLICANT_CREATED',
+  INTERNAL_CANDIDATE_APPLIED: 'INTERNAL_CANDIDATE_APPLIED',
+  REJECTION_REASON_CHANGED: 'REJECTION_REASON_CHANGED',
+  JOB_REQ_CREATED: 'JOB_REQ_CREATED',
+  APPLICATION_INTERVIEW_IS_CANCELLED: 'APPLICATION_INTERVIEW_IS_CANCELLED',
+  ATS_OFFER_LETTER_SIGNED: 'ATS_OFFER_LETTER_SIGNED',
+  ENROLMENT_COMPLETED: 'ENROLMENT_COMPLETED',
+  ENROLMENT_STARTED: 'ENROLMENT_STARTED',
+  LEARNING_PATH_COMPLETED: 'LEARNING_PATH_COMPLETED',
+  EMPLOYEE_SURVEY_RESPONSE_SUBMITTED: 'EMPLOYEE_SURVEY_RESPONSE_SUBMITTED',
+  APPLICANT_SURVEY_RESPONSE_SUBMITTED: 'APPLICANT_SURVEY_RESPONSE_SUBMITTED',
+  FUNCTION_RUN_COMPLETED: 'FUNCTION_RUN_COMPLETED',
+  CARD_AUTHORIZATION_CREATED: 'CARD_AUTHORIZATION_CREATED',
+  CARD_TRANSACTION_DISPUTED: 'CARD_TRANSACTION_DISPUTED',
+  CARD_TRANSACTION_ANOMALY_DETECTED: 'CARD_TRANSACTION_ANOMALY_DETECTED',
+  CARD_REPAYMENT_REQUEST_CANCELLED: 'CARD_REPAYMENT_REQUEST_CANCELLED',
+  INVOICE_STATEMENT_GENERATED: 'INVOICE_STATEMENT_GENERATED',
+  SPEND_PROGRAM_BALANCE_UPDATED: 'SPEND_PROGRAM_BALANCE_UPDATED',
+  VENDOR_ADDED: 'VENDOR_ADDED',
+  VENDOR_BANK_ACCOUNT_ADDED: 'VENDOR_BANK_ACCOUNT_ADDED',
+  PAYROLL_JOURNAL_ENTRY_POSTED: 'PAYROLL_JOURNAL_ENTRY_POSTED',
+  FLIGHT_BOOKED: 'FLIGHT_BOOKED',
+} as const;
+
+export type StaticBusinessEventKey = (typeof BusinessEvent)[keyof typeof BusinessEvent];
+
+/** Approval events are generated from the approval action type at runtime. */
+export type ApprovalBusinessEventOutcome = 'approved' | 'rejected';
+export type ApprovalBusinessEventKey = `approvals_${string}_request_is_${ApprovalBusinessEventOutcome}`;
+
+/** A public business-event key accepted in a manifest. */
+export type BusinessEventKey = StaticBusinessEventKey | ApprovalBusinessEventKey;
+
+/** Builds the event key for an approval action type such as `leave_request_approval`. */
+export function approvalBusinessEventKey(
+  actionType: string,
+  outcome: ApprovalBusinessEventOutcome,
+): ApprovalBusinessEventKey {
+  return `approvals_${actionType.toLowerCase()}_request_is_${outcome}`;
+}