@rippling/rippling-sdk 0.2.0-alpha.100

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

@@ -0,0 +1,255 @@
+import { ExistingManifestContext, type ExistingManifestSource } from './existing-manifest-context';
+
+/**
+ * Any object that can be included in a manifest.
+ *
+ * Implement `toDict()` to return the component's wire-format dict.
+ * All built-in SDK classes implement this interface automatically.
+ */
+export interface ManifestComponent {
+  toDict(): Record<string, any>;
+}
+
+/**
+ * Wire-level component types supported by the manifest builder.
+ */
+export type ManifestComponentType =
+  | 'ACP_AGENT'
+  | 'AGENT'
+  | 'CUSTOM_APP'
+  | 'CUSTOM_CATEGORY'
+  | 'CUSTOM_FIELD_SECTION'
+  | 'CUSTOM_FIELD_V2'
+  | 'CUSTOM_OBJECT'
+  | 'CUSTOM_OBJECT_ACTION'
+  | 'CUSTOM_OBJECT_FIELD'
+  | 'CUSTOM_OBJECT_FIELD_SECTION'
+  | 'CUSTOM_OBJECT_LIST_VIEW'
+  | 'CUSTOM_OBJECT_PAGE_LAYOUT'
+  | 'CUSTOM_OBJECT_RECORD_TRIGGERED_FLOW'
+  | 'CUSTOM_OBJECT_VALIDATION_RULE'
+  | 'CUSTOM_SKILL'
+  | 'FUNCTION'
+  | 'SDUI_PAGE'
+  | 'WORKFLOW_DEFINITION';
+
+/**
+ * Static side of a manifest component class.
+ */
+export interface ManifestComponentClass<TIdentifierInput = unknown> {
+  readonly componentType: ManifestComponentType;
+  toDeletionIdentifier(identifier: TIdentifierInput): ManifestComponentDeletion;
+  new (...args: any[]): ManifestComponent;
+}
+
+/**
+ * A manifest component reference that should be deleted during install.
+ */
+export interface ManifestComponentDeletion extends Record<string, any> {
+  /** Wire-level component type, e.g. `'CUSTOM_OBJECT'` or `'CUSTOM_OBJECT_FIELD'`. */
+  type: ManifestComponentType;
+}
+
+/**
+ * A scope — anything that can accept child component registrations.
+ *
+ * Implemented by {@link ManifestBuilder} (the root) and by nestable parents
+ * like `CustomObject` that forward registrations up to the builder.
+ * Pass a scope as the first argument when constructing any manifest component.
+ */
+export interface ManifestScope {
+  /** @internal Register a child component; builder-bound scopes forward up. */
+  _register(component: ManifestComponent): void;
+}
+
+/**
+ * Initialization properties for {@link ManifestBuilder}.
+ */
+export interface ManifestBuilderProps {
+  /**
+   * Unique project key for this manifest (e.g. `'gym_membership_management'`).
+   *
+   * Required.
+   */
+  key: string;
+  /**
+   * Display name for this manifest.
+   *
+   * Optional. Defaults to `key` when not provided.
+   */
+  name?: string;
+  /**
+   * Human-readable description of what this manifest contains.
+   *
+   * Required.
+   */
+  description: string;
+}
+
+/**
+ * Plain object returned by {@link ManifestBuilder.buildManifest}.
+ */
+export interface BuiltManifest {
+  metadata: Record<string, any>;
+  components: Record<string, any>[];
+  components_to_delete?: ManifestComponentDeletion[];
+}
+
+/**
+ * Root container for a manifest — collects all components and serializes them to JSON.
+ *
+ * You would normally create one `ManifestBuilder` at the top of your manifest file,
+ * then pass it as the scope to all top-level components (categories, custom objects,
+ * functions, apps, SDUI pages). Each component auto-registers on construction; there
+ * is no separate add or register call.
+ *
+ * After defining all components, call `preview()` to emit the manifest as a
+ * pretty-printed JSON string, or `buildManifest()` to get the plain object.
+ *
+ * @example
+ * ```ts
+ * const manifest = new ManifestBuilder({
+ *   key: 'gym_membership_management',
+ *   name: 'Gym Membership Management',
+ *   description: 'Members, trainers, schedules, and check-in',
+ * });
+ *
+ * const category = new Category(manifest, { apiName: 'gym__c', name: 'Gym', description: 'Gym domain' });
+ * const memberObj = new CustomObject(manifest, { apiName: 'gym_member__c', name: 'Member', category });
+ * // ... define fields, rules, list views, etc. ...
+ *
+ * console.log(manifest.preview());
+ * ```
+ */
+export class ManifestBuilder implements ManifestScope {
+  readonly key: string;
+  readonly name: string;
+  readonly description: string;
+  private readonly _components: ManifestComponent[] = [];
+  private readonly _componentsToDelete: ManifestComponentDeletion[] = [];
+
+  /**
+   * @param props - Initialization properties.
+   * @throws {Error} If `props.key` is empty or missing.
+   */
+  constructor(props: ManifestBuilderProps) {
+    if (!props.key) {
+      throw new Error('key is required');
+    }
+    this.key = props.key;
+    this.name = props.name || props.key;
+    this.description = props.description;
+  }
+
+  /**
+   * Parses an existing manifest JSON blob, installs it as the active load context,
+   * hydrates every known component, and returns a normal `ManifestBuilder`.
+   */
+  static loadFromExistingJson(source: ExistingManifestSource): ManifestBuilder {
+    return ExistingManifestContext.fromJson(source).loadManifestBuilder();
+  }
+
+  /**
+   * Parses an existing manifest JSON blob and installs it as the active lazy-load context.
+   *
+   * After calling this, individual components can be loaded with
+   * `CustomObjectPageLayout.loadFromExisting(...)`, `Field.loadFromExisting(...)`, etc.
+   */
+  static useExistingJson(source: ExistingManifestSource): ExistingManifestContext {
+    return ExistingManifestContext.fromJson(source);
+  }
+
+  /**
+   * @internal Scope hook invoked by child constructors. Components enter the
+   * manifest here — there is no other path.
+   */
+  _register(component: ManifestComponent): void {
+    if (typeof component.toDict !== 'function') {
+      throw new TypeError('Component must have a toDict() method');
+    }
+    this._components.push(component);
+  }
+
+  /**
+   * Marks a component to be deleted when this manifest is installed.
+   *
+   * @param componentClass - Component class, e.g. `CustomObject`.
+   * @param identifier - Component identifier/key, such as an api_name or the component's identifier object.
+   * @returns This builder for chaining.
+   */
+  markComponentForDeletion<TIdentifierInput>(
+    componentClass: ManifestComponentClass<TIdentifierInput>,
+    identifier: TIdentifierInput,
+  ): this {
+    if (identifier == null || identifier === '') {
+      throw new Error('identifier is required');
+    }
+    if (!componentClass.componentType) {
+      throw new Error('type is required');
+    }
+    if (typeof componentClass.toDeletionIdentifier !== 'function') {
+      throw new TypeError('Component class must have a toDeletionIdentifier() method');
+    }
+
+    const deletion = componentClass.toDeletionIdentifier(identifier);
+    if (!deletion.type) {
+      throw new Error('type is required');
+    }
+    if (Object.keys(deletion).length <= 1) {
+      throw new Error('identifier is required');
+    }
+
+    this._componentsToDelete.push({ ...deletion });
+    return this;
+  }
+
+  /**
+   * Returns the manifest as a plain object with `metadata`, a flat `components` array,
+   * and a `components_to_delete` array when deletions are registered.
+   *
+   * @returns `{ metadata: { key, name, description }, components, components_to_delete? }`
+   */
+  buildManifest(): BuiltManifest {
+    const metadata: Record<string, any> = {
+      key: this.key,
+      name: this.name,
+      description: this.description,
+    };
+    const components = this._components.map((c) => c.toDict());
+    const manifest: BuiltManifest = { metadata, components };
+    if (this._componentsToDelete.length > 0) {
+      manifest.components_to_delete = this.componentsToDeleteList();
+    }
+    return manifest;
+  }
+
+  /**
+   * Returns the flat list of all registered component dicts.
+   *
+   * @returns An array of wire-format component objects, in registration order.
+   */
+  componentsList(): Record<string, any>[] {
+    return this._components.map((c) => c.toDict());
+  }
+
+  /**
+   * Returns the flat list of component deletion references.
+   *
+   * @returns An array of component identifier objects, in registration order.
+   */
+  componentsToDeleteList(): ManifestComponentDeletion[] {
+    return this._componentsToDelete.map((component) => ({ ...component }));
+  }
+
+  /**
+   * Returns the full manifest as a pretty-printed JSON string.
+   *
+   * Typically used as the final line of a manifest file to emit the output:
+   * `console.log(manifest.preview())`.
+   *
+   * @returns Indented JSON string of the complete manifest.
+   */
+  preview(): string {
+    return JSON.stringify(this.buildManifest(), null, 2);
+  }
+}

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

@@ -0,0 +1,186 @@
+import { getExistingManifestContext, type ExistingManifestContextOptions } from './existing-manifest-context';
+import type { ManifestComponentDeletion, ManifestScope } from './manifest-builder';
+import { optionalStringComponentField, requireStringComponentField } from './_existing-component-fields';
+
+/**
+ * Initialization properties for {@link ManifestFunction}.
+ */
+export interface ManifestFunctionProps {
+  /**
+   * Unique identifier for this function (e.g. `'gym_today_schedule_fn'`).
+   *
+   * Required.
+   */
+  apiName: string;
+  /**
+   * Display name shown in the Rippling UI.
+   *
+   * Required.
+   */
+  name: string;
+  /**
+   * TypeScript handler source code. Must export an `onRipplingEvent` function.
+   *
+   * Optional. @default `''`
+   */
+  code?: string;
+  /**
+   * Human-readable description of what this function does.
+   *
+   * Required.
+   */
+  description: string;
+  /**
+   * NPM package dependencies as a `{ packageName: versionRange }` map
+   * (e.g. `{ '@rippling/rippling-sdk': '^0.2.0' }`).
+   *
+   * Optional. @default null
+   */
+  dependencies?: Record<string, string>;
+  /**
+   * Raw deployment options object.
+   *
+   * Optional. @default null
+   */
+  deploymentOptions?: Record<string, any>;
+  /**
+   * Outbound domain allowlist. Requests to domains not in this list will be blocked.
+   *
+   * Optional. @default null
+   */
+  allowedDomains?: string[];
+  /**
+   * Whether this function runs asynchronously (fire-and-forget).
+   *
+   * Optional. @default `false`
+   */
+  isAsync?: boolean;
+}
+
+/**
+ * Defines a serverless function and registers it with the manifest.
+ *
+ * A `ManifestFunction` packages TypeScript handler code that runs on Rippling's
+ * serverless infrastructure. The handler must export `onRipplingEvent`.
+ *
+ * Functions have two primary uses:
+ * 1. **Rendering SDUI for Custom Apps** — the function returns an SDUI spec
+ *    payload that renders as a page tab. Wrap the function in an {@link SduiPage}
+ *    and reference it from an {@link App}.
+ * 2. **Workflow / event handlers** — functions invoked from rules, automations,
+ *    or callbacks that do not render UI.
+ *
+ * This class is named `ManifestFunction` to avoid collision with the JavaScript
+ * built-in `Function`. It is also re-exported as `Function` from the barrel for
+ * convenience.
+ *
+ * @example
+ * ```ts
+ * const todayScheduleFn = new ManifestFunction(manifest, {
+ *   apiName: 'gym_today_schedule_fn',
+ *   name: 'Today\'s schedule (SDUI)',
+ *   description: 'Searchable grid of class sessions',
+ *   code: handlerSource,
+ *   dependencies: {
+ *     '@rippling/rippling-sdk': '^0.2.0-alpha.33',
+ *   },
+ *   isAsync: false,
+ * });
+ * ```
+ *
+ * @see {@link SduiPage} — wraps a `ManifestFunction` as a navigable UI surface.
+ */
+export class ManifestFunction {
+  static readonly componentType = 'FUNCTION' as const;
+
+  static toDeletionIdentifier(apiName: string): ManifestComponentDeletion {
+    return {
+      type: ManifestFunction.componentType,
+      api_name: apiName,
+    };
+  }
+
+  private readonly _apiName: string;
+  private readonly _name: string;
+  private _code: string;
+  private readonly _description: string;
+  private readonly _dependencies: Record<string, string> | undefined;
+  private readonly _deploymentOptions: Record<string, any> | undefined;
+  private readonly _allowedDomains: string[] | undefined;
+  private readonly _isAsync: boolean;
+
+  /**
+   * @param scope - The manifest to register this function with.
+   * @param props - Initialization properties.
+   */
+  constructor(scope: ManifestScope, props: ManifestFunctionProps) {
+    this._apiName = props.apiName;
+    this._name = props.name;
+    this._code = props.code ?? '';
+    this._description = props.description;
+    this._dependencies = props.dependencies;
+    this._deploymentOptions = props.deploymentOptions;
+    this._allowedDomains = props.allowedDomains;
+    this._isAsync = props.isAsync ?? false;
+    scope._register(this);
+  }
+
+  /**
+   * Loads this function from the active existing-manifest JSON context.
+   */
+  static loadFromExisting(apiName: string, options: ExistingManifestContextOptions = {}): ManifestFunction {
+    return getExistingManifestContext(options).loadFunction(apiName);
+  }
+
+  /** @internal Hydrates a function from existing manifest wire JSON. */
+  static _fromExistingComponent(scope: ManifestScope, component: Record<string, any>): ManifestFunction {
+    const props: ManifestFunctionProps = {
+      apiName: requireStringComponentField(component, 'api_name', ManifestFunction.componentType),
+      name: requireStringComponentField(component, 'name', ManifestFunction.componentType),
+      description: optionalStringComponentField(component, 'description'),
+    };
+    if (component['code_draft'] !== undefined) props.code = component['code_draft'];
+    if (component['dependencies'] !== undefined) props.dependencies = component['dependencies'];
+    if (component['deployment_options'] !== undefined) {
+      props.deploymentOptions = component['deployment_options'];
+    }
+    if (component['allowed_domains'] !== undefined) props.allowedDomains = component['allowed_domains'];
+    if (component['is_async'] !== undefined) props.isAsync = component['is_async'];
+    return new ManifestFunction(scope, props);
+  }
+
+  /**
+   * Returns the api_name of this function (e.g. `'gym_today_schedule_fn'`).
+   */
+  getApiName(): string {
+    return this._apiName;
+  }
+
+  /**
+   * Replaces the TypeScript handler source code for this function.
+   */
+  setCode(code: string): this {
+    this._code = code;
+    return this;
+  }
+
+  /**
+   * Serializes this function to the wire format consumed by the manifest install endpoint.
+   *
+   * @returns A plain object with `type: 'FUNCTION'`. Empty or unset optional fields are omitted.
+   */
+  toDict(): Record<string, any> {
+    const component: Record<string, any> = {
+      type: ManifestFunction.componentType,
+      name: this._name,
+      api_name: this._apiName,
+      description: this._description,
+    };
+    if (this._code) component['code_draft'] = this._code;
+    if (this._dependencies != null) component['dependencies'] = this._dependencies;
+    if (this._deploymentOptions != null) component['deployment_options'] = this._deploymentOptions;
+    if (this._allowedDomains != null) component['allowed_domains'] = this._allowedDomains;
+    if (this._isAsync) component['is_async'] = true;
+    return component;
+  }
+}

package/src/lib/manifest/node.ts

@@ -0,0 +1,4 @@
+/** Node.js-only helpers for Metadata SDK manifests. */
+
+export * from './index';
+export { discoverACPAgentSourceFiles } from './acp-agent-source-files';