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

package/examples/manifest/procurement-approval-hub/schema.ts

@@ -1,256 +0,0 @@
-/**
- * Typed custom-object schema definitions for the procurement approval hub example.
- */
-
-import {
-  date,
-  defineCustomObject,
-  email,
-  formula,
-  longText,
-  lookup,
-  number,
-  parentChild,
-  radio,
-  section,
-  text,
-} from '@rippling/rippling-sdk/core/platform/custom-objects';
-
-/** Logical category shared by the procurement approval hub example. */
-export const PROCUREMENT_CATEGORY = 'procurement';
-
-/** Vendor profile schema used for contract and request relationships. */
-export const vendorDefinition = defineCustomObject({
-  name: 'pa_vendor',
-  displayName: 'Vendor',
-  pluralLabel: 'Vendors',
-  category: PROCUREMENT_CATEGORY,
-  description: 'Vendor profile, risk tier, and compliance owner',
-  sections: {
-    vendor: section('Vendor', { sectionId: 'sec_pa_vendor' }),
-  },
-  fields: {
-    legal_name: text({
-      displayName: 'Legal name',
-      description: 'Registered legal vendor name',
-      required: true,
-      maxLength: 200,
-      section: 'vendor',
-    }),
-    vendor_category: radio({
-      displayName: 'Vendor category',
-      description: 'Primary spend category',
-      options: ['Software', 'Facilities', 'Professional services', 'Marketing', 'Hardware', 'Other'],
-      required: true,
-      section: 'vendor',
-    }),
-    risk_tier: radio({
-      displayName: 'Risk tier',
-      description: 'Risk tier from diligence review',
-      options: ['Low', 'Medium', 'High', 'Critical'],
-      required: true,
-      section: 'vendor',
-    }),
-    contact_email: email({
-      displayName: 'Contact email',
-      description: 'Primary vendor contact email',
-      section: 'vendor',
-    }),
-  },
-});
-
-/** Contract schema tied to a parent vendor. */
-export const contractDefinition = defineCustomObject({
-  name: 'pa_contract',
-  displayName: 'Contract',
-  pluralLabel: 'Contracts',
-  category: PROCUREMENT_CATEGORY,
-  description: 'Vendor contract with dates, status, and spend ceiling',
-  sections: {
-    contract: section('Contract', { sectionId: 'sec_pa_contract' }),
-  },
-  fields: {
-    vendor_ref: parentChild(vendorDefinition, {
-      displayName: 'Vendor',
-      description: 'Vendor this contract belongs to',
-      relatedDataLabel: 'Contracts',
-      parentChildType: 'PRIMARY',
-      enableParentOwnerInheritance: false,
-      section: 'contract',
-    }),
-    status: radio({
-      displayName: 'Status',
-      description: 'Contract lifecycle status',
-      options: ['Draft', 'In review', 'Active', 'Expired', 'Terminated'],
-      required: true,
-      section: 'contract',
-    }),
-    start_date: date({
-      displayName: 'Start date',
-      description: 'Contract effective date',
-      section: 'contract',
-    }),
-    end_date: date({
-      displayName: 'End date',
-      description: 'Contract expiration date',
-      section: 'contract',
-    }),
-    spend_ceiling_cents: number({
-      displayName: 'Spend ceiling (cents)',
-      description: 'Approved maximum spend in cents',
-      decimalPlaces: 0,
-      section: 'contract',
-    }),
-    key_terms: longText({
-      displayName: 'Key terms',
-      description: 'Renewal, data processing, and termination notes',
-      maxLength: 6000,
-      section: 'contract',
-    }),
-  },
-});
-
-/** Purchase-request schema tied to a vendor and optional contract. */
-export const requestDefinition = defineCustomObject({
-  name: 'pa_purchase_request',
-  displayName: 'Purchase request',
-  pluralLabel: 'Purchase requests',
-  category: PROCUREMENT_CATEGORY,
-  description: 'Purchase request with business justification and approval state',
-  sections: {
-    request: section('Purchase request', { sectionId: 'sec_pa_request' }),
-  },
-  fields: {
-    vendor_ref: lookup(vendorDefinition, {
-      displayName: 'Vendor',
-      description: 'Preferred or selected vendor',
-      relatedDataLabel: 'Purchase requests',
-      required: true,
-      section: 'request',
-    }),
-    contract_ref: lookup(contractDefinition, {
-      displayName: 'Contract',
-      description: 'Contract used for this request, if any',
-      relatedDataLabel: 'Purchase requests',
-      section: 'request',
-    }),
-    amount_cents: number({
-      displayName: 'Amount (cents)',
-      description: 'Requested spend amount in cents',
-      decimalPlaces: 0,
-      required: true,
-      section: 'request',
-    }),
-    status: radio({
-      displayName: 'Status',
-      description: 'Approval status',
-      options: ['Draft', 'Submitted', 'In approval', 'Approved', 'Rejected', 'Ordered'],
-      required: true,
-      section: 'request',
-    }),
-    need_by: date({
-      displayName: 'Need by',
-      description: 'Requested delivery or purchase date',
-      section: 'request',
-    }),
-    business_justification: longText({
-      displayName: 'Business justification',
-      description: 'Why the purchase is needed',
-      maxLength: 6000,
-      section: 'request',
-    }),
-    approval_label: formula.text({
-      displayName: 'Approval label',
-      description: 'Status and amount for approval queues',
-      formula: "CONCATENATE(status__c, ' - ', amount_cents__c)",
-      maxLength: 240,
-      section: 'request',
-    }),
-  },
-});
-
-/** Approval-step schema tied to a parent purchase request. */
-export const approvalDefinition = defineCustomObject({
-  name: 'pa_approval_step',
-  displayName: 'Approval step',
-  pluralLabel: 'Approval steps',
-  category: PROCUREMENT_CATEGORY,
-  description: 'Approval routing line tied to a purchase request',
-  sections: {
-    approval: section('Approval step', { sectionId: 'sec_pa_approval' }),
-  },
-  fields: {
-    purchase_request_ref: parentChild(requestDefinition, {
-      displayName: 'Purchase request',
-      description: 'Purchase request this approval belongs to',
-      relatedDataLabel: 'Approval steps',
-      parentChildType: 'PRIMARY',
-      enableParentOwnerInheritance: true,
-      section: 'approval',
-    }),
-    sequence: number({
-      displayName: 'Sequence',
-      description: 'Approval sequence number',
-      decimalPlaces: 0,
-      required: true,
-      section: 'approval',
-    }),
-    approval_role: radio({
-      displayName: 'Approval role',
-      description: 'Approval lane',
-      options: ['Budget owner', 'Finance', 'Security', 'Legal', 'Procurement'],
-      required: true,
-      section: 'approval',
-    }),
-    status: radio({
-      displayName: 'Status',
-      description: 'Approval step status',
-      options: ['Pending', 'Approved', 'Rejected', 'Skipped'],
-      required: true,
-      section: 'approval',
-    }),
-  },
-});
-
-/** Invoice schema tied to a parent contract. */
-export const invoiceDefinition = defineCustomObject({
-  name: 'pa_invoice',
-  displayName: 'Invoice',
-  pluralLabel: 'Invoices',
-  category: PROCUREMENT_CATEGORY,
-  description: 'Invoice received against a vendor contract',
-  sections: {
-    invoice: section('Invoice', { sectionId: 'sec_pa_invoice' }),
-  },
-  fields: {
-    contract_ref: parentChild(contractDefinition, {
-      displayName: 'Contract',
-      description: 'Contract this invoice is billed against',
-      relatedDataLabel: 'Invoices',
-      parentChildType: 'PRIMARY',
-      enableParentOwnerInheritance: false,
-      section: 'invoice',
-    }),
-    invoice_number: text({
-      displayName: 'Invoice number',
-      description: 'Vendor invoice number',
-      maxLength: 120,
-      required: true,
-      section: 'invoice',
-    }),
-    amount_cents: number({
-      displayName: 'Amount (cents)',
-      description: 'Invoice amount in cents',
-      decimalPlaces: 0,
-      required: true,
-      section: 'invoice',
-    }),
-    status: radio({
-      displayName: 'Status',
-      description: 'Invoice processing status',
-      options: ['Received', 'Matched', 'Approved', 'Paid', 'Exception'],
-      required: true,
-      section: 'invoice',
-    }),
-  },
-});

package/examples/manifest/simple-todo-app/schema.ts

@@ -1,60 +0,0 @@
-/**
- * Typed custom-object schema for the simple todo example.
- */
-
-import {
-  date,
-  defineCustomObject,
-  longText,
-  radio,
-  section,
-  select,
-} from '@rippling/rippling-sdk/core/platform/custom-objects';
-
-/** Logical category shared by the simple todo custom-object example. */
-export const SIMPLE_TODO_CATEGORY = 'simple_todo';
-
-/** Typed schema used by the simple todo manifest and action functions. */
-export const todoDefinition = defineCustomObject({
-  name: 'simple_todo',
-  displayName: 'Todo',
-  pluralLabel: 'Todos',
-  category: SIMPLE_TODO_CATEGORY,
-  description: 'A single task with status, priority, due date, and notes.',
-  icon: { emoji: '✅' },
-  sections: {
-    details: section('Details', { sectionId: 'sec_todo_details' }),
-  },
-  fields: {
-    status: radio({
-      displayName: 'Status',
-      description: 'Status field',
-      options: ['To Do', 'In Progress', 'Done'],
-      required: true,
-      section: 'details',
-    }),
-    priority: radio({
-      displayName: 'Priority',
-      description: 'Priority field',
-      options: ['Low', 'Medium', 'High'],
-      section: 'details',
-    }),
-    labels: select({
-      displayName: 'Labels',
-      description: 'One or more labels for organizing the task',
-      options: ['Personal', 'Work', 'Urgent', 'Follow-up'],
-      section: 'details',
-    }),
-    due_date: date({
-      displayName: 'Due date',
-      description: 'Due date field',
-      section: 'details',
-    }),
-    notes: longText({
-      displayName: 'Notes',
-      description: 'Notes field',
-      maxLength: 4000,
-      section: 'details',
-    }),
-  },
-});

package/examples/manifest/todo-app-without-object-list-view/schema.ts

@@ -1,28 +0,0 @@
-/**
- * Typed custom-object schema for the custom SDUI todo example.
- */
-
-import { boolean, defineCustomObject, section } from '@rippling/rippling-sdk/core/platform/custom-objects';
-
-/** Logical category shared by the custom SDUI todo example. */
-export const CUSTOM_TODO_CATEGORY = 'custom_todo_app';
-
-/** Typed schema used by the custom SDUI todo manifest and function code. */
-export const todoDefinition = defineCustomObject({
-  name: 'todo',
-  displayName: 'Todo',
-  pluralLabel: 'Todos',
-  category: CUSTOM_TODO_CATEGORY,
-  description: 'A todo item rendered by a custom SDUI page.',
-  icon: { emoji: '✅' },
-  sections: {
-    details: section('Details', { sectionId: 'sec_custom_todo_details' }),
-  },
-  fields: {
-    completed: boolean({
-      displayName: 'Completed',
-      description: 'Whether the todo item is complete',
-      section: 'details',
-    }),
-  },
-});

package/src/core/platform/README.md

@@ -1,20 +0,0 @@
-# `core/platform`
-
-This directory holds public, higher-level platform abstractions that sit above the generated REST resources and above low-level manifest classes.
-
-Use this layer for SDK capabilities that are:
-
-- public and stable enough to be imported by SDK consumers
-- opinionated or cross-cutting rather than raw transport wrappers
-- centered on platform concepts such as custom objects, typed schemas, lifecycle helpers, record managers, or query helpers
-
-In practice, the layering is:
-
-- `src/resources/*` — generated REST resources and DTOs
-- `src/lib/manifest/*` — low-level manifest authoring classes
-- `src/core/platform/*` — higher-level typed/platform abstractions built on top of those surfaces
-
-Current structure:
-
-- `custom-objects/` — typed custom-object domain model, validation, provisioning, lifecycle, records, and RQL helpers
-- `manifest/` — typed adapters that materialize platform-domain definitions into low-level manifest authoring surfaces

package/src/core/platform/custom-objects/category.ts

@@ -1,294 +0,0 @@
-import type { RipplingSDK } from '../../../client';
-import type {
-  ObjectCategory,
-  ObjectCategoryCreateParams,
-  ObjectCategoryUpdateParams,
-} from '../../../resources/object-categories';
-import type { CategoryApiName, LogicalCategoryName } from './types';
-import { toCustomCategoryApiName } from './definition';
-import { validateLogicalCategoryName } from './validation';
-
-/**
- * Author input accepted by {@link defineCustomObjectCategory}.
- *
- * @typeParam TName - Logical category name supplied by the caller.
- */
-interface CustomObjectCategoryDefinitionInput<TName extends string> {
-  /** Logical unsuffixed snake_case category name. */
-  readonly name: LogicalCategoryName<TName>;
-  /** Human-readable display name applied after creation. */
-  readonly displayName: string;
-  /** Optional category description. */
-  readonly description?: string;
-}
-
-/** Immutable typed category definition used by provisioning and lifecycle helpers. */
-export interface CustomObjectCategoryDefinition<TName extends LogicalCategoryName = LogicalCategoryName> {
-  /** Logical unsuffixed snake_case category name. */
-  readonly name: TName;
-  /** Compiled wire-level category api name. */
-  readonly apiName: CategoryApiName<TName>;
-  /** Human-readable display name. */
-  readonly displayName: string;
-  /** Optional category description. */
-  readonly description?: string;
-}
-
-/** Result returned by category provisioning helpers. */
-export interface ProvisionedCustomObjectCategory<TName extends LogicalCategoryName = LogicalCategoryName> {
-  /** Source typed category definition. */
-  readonly definition: CustomObjectCategoryDefinition<TName>;
-  /** Response returned by `client.objectCategories.create(...)`. */
-  readonly createdCategory: ObjectCategory;
-  /** Response returned by `client.objectCategories.update(...)`. */
-  readonly updatedCategory: ObjectCategory;
-}
-
-/** Lifecycle action emitted by category reconciliation helpers. */
-export type CustomObjectCategoryLifecycleAction = 'created' | 'updated' | 'unchanged';
-
-/** Result returned by category reconciliation helpers. */
-export interface ReconciledCustomObjectCategory<TName extends LogicalCategoryName = LogicalCategoryName> {
-  /** Source typed category definition. */
-  readonly definition: CustomObjectCategoryDefinition<TName>;
-  /** Whether the remote category was created, updated, or already matched. */
-  readonly action: CustomObjectCategoryLifecycleAction;
-  /** Remote category after reconciliation. */
-  readonly category: ObjectCategory;
-}
-
-/** Options for category provisioning and reconciliation helpers. */
-export interface CustomObjectCategoryMutationOptions {
-  /** Whether to apply the follow-up display-metadata update. Defaults to `true`. */
-  readonly updateDisplayMetadata?: boolean;
-}
-
-/**
- * Creates an immutable typed custom-object category definition.
- *
- * @param definition - Logical category metadata to normalize and freeze.
- * @returns Immutable typed category definition with compiled API name.
- * @typeParam TName - Logical category name supplied by the caller.
- */
-export function defineCustomObjectCategory<TName extends string>(
-  definition: CustomObjectCategoryDefinitionInput<TName>,
-): Readonly<CustomObjectCategoryDefinition<LogicalCategoryName<TName>>> {
-  validateLogicalCategoryName(definition.name);
-  return Object.freeze({
-    name: definition.name,
-    apiName: toCustomCategoryApiName(definition.name),
-    displayName: definition.displayName,
-    ...(definition.description != null ? { description: definition.description } : {}),
-  }) as Readonly<CustomObjectCategoryDefinition<LogicalCategoryName<TName>>>;
-}
-
-/**
- * Builds the low-level create payload for an object category.
- *
- * @param definition - Typed category definition to compile.
- * @returns REST create payload using the logical category name.
- * @typeParam TName - Logical category name carried by the definition.
- */
-export function buildObjectCategoryCreateParams<TName extends LogicalCategoryName>(
-  definition: CustomObjectCategoryDefinition<TName>,
-): ObjectCategoryCreateParams {
-  return {
-    name: definition.name,
-    ...(definition.description != null ? { description: definition.description } : {}),
-  };
-}
-
-/**
- * Builds the low-level update payload for an object category.
- *
- * @param definition - Typed category definition to compile.
- * @returns REST update payload using human-facing display metadata.
- * @typeParam TName - Logical category name carried by the definition.
- */
-export function buildObjectCategoryUpdateParams<TName extends LogicalCategoryName>(
-  definition: CustomObjectCategoryDefinition<TName>,
-): ObjectCategoryUpdateParams {
-  return {
-    name: definition.displayName,
-    ...(definition.description != null ? { description: definition.description } : {}),
-  };
-}
-
-/**
- * Returns whether one public category DTO matches the typed category definition by currently visible names.
- *
- * @param category - Public category DTO returned by the REST API.
- * @param definition - Typed category definition being matched.
- * @returns Whether the visible name matches either the logical or display name.
- * @typeParam TName - Logical category name carried by the definition.
- */
-function isMatchingCategoryName<TName extends LogicalCategoryName>(
-  category: ObjectCategory,
-  definition: CustomObjectCategoryDefinition<TName>,
-): boolean {
-  return category.name === definition.name || category.name === definition.displayName;
-}
-
-/**
- * Lists all public category DTOs that ambiguously or exactly match one typed definition.
- *
- * @param client - SDK client used to enumerate categories.
- * @param definition - Typed category definition being matched.
- * @returns Frozen list of public categories whose visible names match.
- * @typeParam TName - Logical category name carried by the definition.
- */
-async function listMatchingCategories<TName extends LogicalCategoryName>(
-  client: RipplingSDK,
-  definition: CustomObjectCategoryDefinition<TName>,
-): Promise<readonly ObjectCategory[]> {
-  const matches: ObjectCategory[] = [];
-  for await (const category of client.objectCategories.list()) {
-    if (isMatchingCategoryName(category, definition)) {
-      matches.push(category);
-    }
-  }
-  return Object.freeze(matches);
-}
-
-/**
- * Returns the single public category matching one typed definition or throws when the match is ambiguous.
- *
- * @param client - SDK client used to enumerate categories.
- * @param definition - Typed category definition being matched.
- * @returns Matching public category, if any.
- * @throws Error when multiple public categories match the visible names.
- * @typeParam TName - Logical category name carried by the definition.
- */
-async function getSingleMatchingCategory<TName extends LogicalCategoryName>(
-  client: RipplingSDK,
-  definition: CustomObjectCategoryDefinition<TName>,
-): Promise<ObjectCategory | undefined> {
-  const matches = await listMatchingCategories(client, definition);
-  if (matches.length <= 1) return matches[0];
-
-  throw new Error(
-    `Ambiguous category match for "${definition.name}" / "${definition.displayName}". ` +
-      `Matched ids: ${matches.map((category) => category.id).join(', ')}.`,
-  );
-}
-
-/**
- * Creates one typed custom-object category through the REST SDK.
- *
- * @param client - SDK client used to call the category APIs.
- * @param definition - Typed category definition to provision.
- * @param options - Provisioning behavior flags for display-metadata updates.
- * @returns Frozen summary of the created and updated backend category DTOs.
- * @typeParam TName - Logical category name carried by the definition.
- */
-export async function provisionCustomObjectCategoryDefinition<TName extends LogicalCategoryName>(
-  client: RipplingSDK,
-  definition: CustomObjectCategoryDefinition<TName>,
-  options: CustomObjectCategoryMutationOptions = {},
-): Promise<ProvisionedCustomObjectCategory<TName>> {
-  const createdCategory = await client.objectCategories.create(buildObjectCategoryCreateParams(definition));
-  const updatedCategory =
-    options.updateDisplayMetadata ?? true ?
-      await client.objectCategories.update(createdCategory.id, buildObjectCategoryUpdateParams(definition))
-    : createdCategory;
-
-  return Object.freeze({ definition, createdCategory, updatedCategory });
-}
-
-/**
- * Creates multiple typed custom-object categories through the REST SDK.
- *
- * @param client - SDK client used to call the category APIs.
- * @param definitions - Typed category definitions to provision.
- * @param options - Provisioning behavior flags shared across the batch.
- * @returns Frozen batch of provisioning results in input order.
- */
-export async function provisionCustomObjectCategoryDefinitions(
-  client: RipplingSDK,
-  definitions: readonly CustomObjectCategoryDefinition[],
-  options: CustomObjectCategoryMutationOptions = {},
-): Promise<readonly ProvisionedCustomObjectCategory[]> {
-  const results: ProvisionedCustomObjectCategory[] = [];
-  for (const definition of definitions) {
-    results.push(await provisionCustomObjectCategoryDefinition(client, definition, options));
-  }
-  return Object.freeze(results);
-}
-
-/**
- * Reconciles one typed category definition against the backend by name.
- *
- * @param client - SDK client used to call the category APIs.
- * @param definition - Typed category definition to reconcile.
- * @param options - Reconciliation behavior flags for display-metadata updates.
- * @returns Frozen reconciliation result describing the final backend category state.
- * @typeParam TName - Logical category name carried by the definition.
- */
-export async function reconcileCustomObjectCategoryDefinition<TName extends LogicalCategoryName>(
-  client: RipplingSDK,
-  definition: CustomObjectCategoryDefinition<TName>,
-  options: CustomObjectCategoryMutationOptions = {},
-): Promise<ReconciledCustomObjectCategory<TName>> {
-  const existing = await getSingleMatchingCategory(client, definition);
-  if (existing == null) {
-    const provisioned = await provisionCustomObjectCategoryDefinition(client, definition, options);
-    return Object.freeze({
-      definition,
-      action: 'created' as const,
-      category: provisioned.updatedCategory,
-    });
-  }
-
-  const shouldUpdate =
-    (options.updateDisplayMetadata ?? true) &&
-    (existing.name !== definition.displayName ||
-      (existing.description ?? '') !== (definition.description ?? ''));
-
-  if (!shouldUpdate) {
-    return Object.freeze({ definition, action: 'unchanged', category: existing });
-  }
-
-  const updated = await client.objectCategories.update(
-    existing.id,
-    buildObjectCategoryUpdateParams(definition),
-  );
-  return Object.freeze({ definition, action: 'updated', category: updated });
-}
-
-/**
- * Reconciles multiple typed category definitions against the backend by name.
- *
- * @param client - SDK client used to call the category APIs.
- * @param definitions - Typed category definitions to reconcile.
- * @param options - Reconciliation behavior flags shared across the batch.
- * @returns Frozen batch of reconciliation results in input order.
- */
-export async function reconcileCustomObjectCategoryDefinitions(
-  client: RipplingSDK,
-  definitions: readonly CustomObjectCategoryDefinition[],
-  options: CustomObjectCategoryMutationOptions = {},
-): Promise<readonly ReconciledCustomObjectCategory[]> {
-  const results: ReconciledCustomObjectCategory[] = [];
-  for (const definition of definitions) {
-    results.push(await reconcileCustomObjectCategoryDefinition(client, definition, options));
-  }
-  return Object.freeze(results);
-}
-
-/**
- * Deletes a category that matches the typed definition's logical or display name.
- *
- * @param client - SDK client used to call the category APIs.
- * @param definition - Typed category definition used to find the category to delete.
- * @returns Whether a matching category existed and was deleted.
- * @typeParam TName - Logical category name carried by the definition.
- */
-export async function deleteCustomObjectCategoryDefinition<TName extends LogicalCategoryName>(
-  client: RipplingSDK,
-  definition: CustomObjectCategoryDefinition<TName>,
-): Promise<boolean> {
-  const existing = await getSingleMatchingCategory(client, definition);
-  if (existing == null) return false;
-  await client.objectCategories.delete(existing.id);
-  return true;
-}