@rippling/rippling-sdk 0.2.0-alpha.85 → 0.2.0-alpha.86

package/src/core/platform/custom-objects/schema-manager.ts

@@ -0,0 +1,351 @@
+import type { RipplingSDK } from '../../../client';
+import type {
+  CustomObjectCategoryDefinition,
+  CustomObjectCategoryMutationOptions,
+  ProvisionedCustomObjectCategory,
+  ReconciledCustomObjectCategory,
+} from './category';
+import {
+  buildObjectCategoryCreateParams,
+  buildObjectCategoryUpdateParams,
+  deleteCustomObjectCategoryDefinition,
+  provisionCustomObjectCategoryDefinition,
+  provisionCustomObjectCategoryDefinitions,
+  reconcileCustomObjectCategoryDefinition,
+  reconcileCustomObjectCategoryDefinitions,
+} from './category';
+import type { AnyCustomObjectDefinition, FieldNames, LogicalCategoryName } from './types';
+import type {
+  ProvisionCustomObjectOptions,
+  ProvisionCustomObjectsOptions,
+  ProvisionableFieldParams,
+  ProvisionedCustomObject,
+} from './provisioning';
+import {
+  buildCustomObjectCreateParams,
+  buildCustomObjectNameFieldDetails,
+  buildCustomObjectUpdateParams,
+  buildProvisionableFieldParams,
+  provisionCustomObjectDefinition,
+  provisionCustomObjectDefinitions,
+} from './provisioning';
+import type {
+  ReconcileCustomObjectDefinitionOptions,
+  ReconcileCustomObjectDefinitionsOptions,
+  ReconciledCustomObject,
+} from './lifecycle';
+import {
+  deleteCustomObjectDefinition,
+  reconcileCustomObjectDefinition,
+  reconcileCustomObjectDefinitions,
+} from './lifecycle';
+
+/**
+ * Typed manager bound to one category definition and one SDK client.
+ *
+ * @typeParam TName - Logical category name carried by the bound definition.
+ */
+export class TypedCustomObjectCategoryManager<TName extends LogicalCategoryName = LogicalCategoryName> {
+  private readonly client: RipplingSDK;
+  private readonly definition: CustomObjectCategoryDefinition<TName>;
+
+  /**
+   * Creates a typed category manager bound to one SDK client and one category definition.
+   *
+   * @param client - SDK client used for category lifecycle operations.
+   * @param definition - Typed category definition to bind to the manager.
+   */
+  constructor(client: RipplingSDK, definition: CustomObjectCategoryDefinition<TName>) {
+    this.client = client;
+    this.definition = definition;
+  }
+
+  /**
+   * Returns the bound typed category definition.
+   *
+   * @returns Bound typed category definition.
+   */
+  getDefinition(): CustomObjectCategoryDefinition<TName> {
+    return this.definition;
+  }
+
+  /**
+   * Builds the low-level create payload for the bound category definition.
+   *
+   * @returns REST category-create payload for the bound definition.
+   */
+  buildCreateParams() {
+    return buildObjectCategoryCreateParams(this.definition);
+  }
+
+  /**
+   * Builds the low-level update payload for the bound category definition.
+   *
+   * @returns REST category-update payload for the bound definition.
+   */
+  buildUpdateParams() {
+    return buildObjectCategoryUpdateParams(this.definition);
+  }
+
+  /**
+   * Provisions the bound category definition through the REST SDK.
+   *
+   * @param options - Provisioning behavior flags for display-metadata updates.
+   * @returns Provisioning result for the bound category definition.
+   */
+  provision(
+    options: CustomObjectCategoryMutationOptions = {},
+  ): Promise<ProvisionedCustomObjectCategory<TName>> {
+    return provisionCustomObjectCategoryDefinition(this.client, this.definition, options);
+  }
+
+  /**
+   * Reconciles the bound category definition against the backend.
+   *
+   * @param options - Reconciliation behavior flags for display-metadata updates.
+   * @returns Reconciliation result for the bound category definition.
+   */
+  reconcile(
+    options: CustomObjectCategoryMutationOptions = {},
+  ): Promise<ReconciledCustomObjectCategory<TName>> {
+    return reconcileCustomObjectCategoryDefinition(this.client, this.definition, options);
+  }
+
+  /** Deletes the category that matches the bound typed definition. */
+  delete(): Promise<boolean> {
+    return deleteCustomObjectCategoryDefinition(this.client, this.definition);
+  }
+}
+
+/**
+ * Typed manager bound to one custom-object definition and one SDK client.
+ *
+ * @typeParam TDefinition - Object definition bound to the manager.
+ */
+export class TypedCustomObjectSchemaManager<
+  TDefinition extends AnyCustomObjectDefinition = AnyCustomObjectDefinition,
+> {
+  private readonly client: RipplingSDK;
+  private readonly definition: TDefinition;
+
+  /**
+   * Creates a typed schema manager bound to one SDK client and one object definition.
+   *
+   * @param client - SDK client used for object lifecycle operations.
+   * @param definition - Typed object definition to bind to the manager.
+   */
+  constructor(client: RipplingSDK, definition: TDefinition) {
+    this.client = client;
+    this.definition = definition;
+  }
+
+  /**
+   * Returns the bound typed object definition.
+   *
+   * @returns Bound typed object definition.
+   */
+  getDefinition(): TDefinition {
+    return this.definition;
+  }
+
+  /**
+   * Returns a typed category manager when the bound definition embeds a category definition.
+   *
+   * @returns Typed category manager for the embedded category definition, when present.
+   */
+  category():
+    | TypedCustomObjectCategoryManager<NonNullable<TDefinition['categoryDefinition']>['name']>
+    | undefined {
+    const categoryDefinition = this.definition.categoryDefinition;
+    return categoryDefinition == null ? undefined : (
+        new TypedCustomObjectCategoryManager(this.client, categoryDefinition)
+      );
+  }
+
+  /**
+   * Builds the low-level create payload for the bound object definition using a resolved category id.
+   *
+   * @param categoryIdentifier - Resolved custom-category id or native category id required by the live API.
+   * @returns REST object-create payload for the bound definition.
+   */
+  buildCreateParams(categoryIdentifier: string) {
+    return buildCustomObjectCreateParams(this.definition, categoryIdentifier);
+  }
+
+  /**
+   * Builds the low-level update payload for the bound object definition using a resolved category id.
+   *
+   * @param categoryIdentifier - Resolved custom-category id or native category id required by the live API.
+   * @returns REST object-update payload for the bound definition.
+   */
+  buildUpdateParams(categoryIdentifier: string) {
+    return buildCustomObjectUpdateParams(this.definition, categoryIdentifier);
+  }
+
+  /**
+   * Builds the low-level platform-managed name-field metadata payload for the bound definition.
+   *
+   * @returns Name-field metadata payload for the bound definition, when needed.
+   */
+  buildNameFieldDetails() {
+    return buildCustomObjectNameFieldDetails(this.definition);
+  }
+
+  /**
+   * Builds typed field create/update payloads for one logical field on the bound definition.
+   *
+   * @param fieldName - Logical field name to compile.
+   * @returns Frozen create/update payload pair for the requested field.
+   * @typeParam TFieldName - Logical field name being compiled.
+   */
+  buildFieldParams<TFieldName extends FieldNames<TDefinition>>(
+    fieldName: TFieldName,
+  ): ProvisionableFieldParams {
+    return buildProvisionableFieldParams(this.definition, fieldName);
+  }
+
+  /**
+   * Provisions the bound object definition through the REST SDK.
+   *
+   * @param options - Provisioning behavior flags for categories, display metadata, and name fields.
+   * @returns Provisioning result for the bound object definition.
+   */
+  provision(options: ProvisionCustomObjectOptions = {}): Promise<ProvisionedCustomObject<TDefinition>> {
+    return provisionCustomObjectDefinition(this.client, this.definition, options);
+  }
+
+  /**
+   * Reconciles the bound object definition against the backend.
+   *
+   * @param options - Reconciliation behavior flags for categories, name fields, and deletions.
+   * @returns Reconciliation result for the bound object definition.
+   */
+  reconcile(
+    options: ReconcileCustomObjectDefinitionOptions = {},
+  ): Promise<ReconciledCustomObject<TDefinition>> {
+    return reconcileCustomObjectDefinition(this.client, this.definition, options);
+  }
+
+  /** Deletes the bound object definition by its compiled api name. */
+  delete(): Promise<void> {
+    return deleteCustomObjectDefinition(this.client, this.definition);
+  }
+}
+
+/**
+ * Root schema manager that binds typed category/object definitions to one SDK client.
+ *
+ * Use this when you want a lifecycle-oriented API for categories, object metadata,
+ * field metadata, and typed reconciliation without manually threading the same
+ * `RipplingSDK` client through every helper call.
+ */
+export class CustomObjectSchemaManager {
+  private readonly client: RipplingSDK;
+
+  /**
+   * Creates a new schema manager bound to one SDK client.
+   *
+   * @param client - SDK client used for all subsequent category and object lifecycle operations.
+   */
+  constructor(client: RipplingSDK) {
+    this.client = client;
+  }
+
+  /**
+   * Returns a typed category manager bound to one category definition.
+   *
+   * @param definition - Typed category definition to bind.
+   * @returns Definition-bound category manager.
+   * @typeParam TName - Logical category name carried by the bound definition.
+   */
+  forCategory<TName extends LogicalCategoryName>(
+    definition: CustomObjectCategoryDefinition<TName>,
+  ): TypedCustomObjectCategoryManager<TName> {
+    return new TypedCustomObjectCategoryManager(this.client, definition);
+  }
+
+  /**
+   * Returns a typed schema manager bound to one object definition.
+   *
+   * @param definition - Typed object definition to bind.
+   * @returns Definition-bound schema manager.
+   * @typeParam TDefinition - Object definition bound to the manager.
+   */
+  forObject<TDefinition extends AnyCustomObjectDefinition>(
+    definition: TDefinition,
+  ): TypedCustomObjectSchemaManager<TDefinition> {
+    return new TypedCustomObjectSchemaManager(this.client, definition);
+  }
+
+  /**
+   * Short ergonomic alias for {@link forObject}.
+   *
+   * @param definition - Typed object definition to bind.
+   * @returns Definition-bound schema manager.
+   * @typeParam TDefinition - Object definition bound to the manager.
+   */
+  for<TDefinition extends AnyCustomObjectDefinition>(
+    definition: TDefinition,
+  ): TypedCustomObjectSchemaManager<TDefinition> {
+    return this.forObject(definition);
+  }
+
+  /**
+   * Provisions multiple typed category definitions through the REST SDK.
+   *
+   * @param definitions - Typed category definitions to provision.
+   * @param options - Provisioning behavior flags shared across the batch.
+   * @returns Provisioning results in input order.
+   */
+  provisionCategories(
+    definitions: readonly CustomObjectCategoryDefinition[],
+    options: CustomObjectCategoryMutationOptions = {},
+  ): Promise<readonly ProvisionedCustomObjectCategory[]> {
+    return provisionCustomObjectCategoryDefinitions(this.client, definitions, options);
+  }
+
+  /**
+   * Reconciles multiple typed category definitions against the backend.
+   *
+   * @param definitions - Typed category definitions to reconcile.
+   * @param options - Reconciliation behavior flags shared across the batch.
+   * @returns Reconciliation results in input order.
+   */
+  reconcileCategories(
+    definitions: readonly CustomObjectCategoryDefinition[],
+    options: CustomObjectCategoryMutationOptions = {},
+  ): Promise<readonly ReconciledCustomObjectCategory[]> {
+    return reconcileCustomObjectCategoryDefinitions(this.client, definitions, options);
+  }
+
+  /**
+   * Provisions multiple typed object definitions through the REST SDK.
+   *
+   * @param definitions - Typed object definitions to provision.
+   * @param options - Batch provisioning behavior flags.
+   * @returns Provisioning results in input order.
+   */
+  provisionDefinitions(
+    definitions: readonly AnyCustomObjectDefinition[],
+    options: ProvisionCustomObjectsOptions = {},
+  ): Promise<ReadonlyArray<ProvisionedCustomObject>> {
+    return provisionCustomObjectDefinitions(this.client, definitions, options);
+  }
+
+  /**
+   * Reconciles multiple typed object definitions against the backend.
+   *
+   * @param definitions - Typed object definitions to reconcile.
+   * @param options - Batch reconciliation behavior flags.
+   * @returns Reconciliation results in input order.
+   */
+  reconcileDefinitions(
+    definitions: readonly AnyCustomObjectDefinition[],
+    options: ReconcileCustomObjectDefinitionsOptions = {},
+  ): Promise<readonly ReconciledCustomObject[]> {
+    return reconcileCustomObjectDefinitions(this.client, definitions, options);
+  }
+}
+
+/** Short alias for teams that prefer concise schema-manager names. */
+export class COSchemaManager extends CustomObjectSchemaManager {}