@api-client/core 0.15.1 → 0.16.0

package/src/modeling/definitions/SKU.ts

@@ -0,0 +1,254 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Supported SKU validation modes.
+ */
+export type SKUValidationMode = 'strict' | 'lenient' | 'custom'
+
+/**
+ * Supported SKU case transformation modes.
+ */
+export type SKUCaseMode = 'uppercase' | 'lowercase' | 'preserve'
+
+/**
+ * Configuration options for the SKU semantic.
+ * Controls SKU validation, formatting, uniqueness enforcement, and pattern matching.
+ */
+export interface SKUConfig {
+  /**
+   * The validation mode for SKU format.
+   *
+   * - 'strict': Enforces alphanumeric characters with optional hyphens/underscores
+   * - 'lenient': Allows more special characters but still validates basic format
+   * - 'custom': Uses custom regex pattern defined in `customPattern`
+   */
+  validationMode?: SKUValidationMode
+
+  /**
+   * Custom regex pattern for SKU validation when using 'custom' validation mode.
+   * Only used when validationMode is 'custom'.
+   */
+  customPattern?: string
+
+  /**
+   * Case transformation to apply to SKUs.
+   * - 'uppercase': Convert to uppercase (recommended for consistency)
+   * - 'lowercase': Convert to lowercase
+   * - 'preserve': Keep original case
+   */
+  caseMode?: SKUCaseMode
+
+  /**
+   * Prefix to automatically add to SKUs if not present.
+   * Useful for organizing SKUs by category (e.g., 'PROD-', 'SKU-').
+   */
+  prefix?: string
+
+  /**
+   * Whether to enforce global uniqueness across all entities.
+   * When true, creates unique database constraints.
+   * Default: true
+   */
+  enforceUniqueness?: boolean
+
+  /**
+   * Whether to auto-generate SKUs when not provided.
+   * When true, generates SKUs based on other fields or random values.
+   * Default: false
+   */
+  autoGenerate?: boolean
+
+  /**
+   * Field name to use as source for auto-generation.
+   * Only used when autoGenerate is true.
+   * If not specified, uses random generation.
+   */
+  autoGenerateSource?: string
+
+  /**
+   * Whether to validate that SKU doesn't conflict with reserved words or patterns.
+   * Default: true
+   */
+  validateReservedWords?: boolean
+
+  /**
+   * List of reserved SKU values that cannot be used.
+   * Common examples: 'ADMIN', 'TEST', 'NULL', 'DEFAULT'
+   */
+  reservedValues?: string[]
+
+  /**
+   * Custom metadata for the SKU field.
+   */
+  metadata?: Record<string, unknown>
+
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for SKU semantic.
+ */
+export interface AppliedSKUSemantic extends AppliedDataSemantic {
+  id: SemanticType.SKU
+  config?: SKUConfig
+}
+
+/**
+ * Type guard to check if a semantic is a SKU semantic.
+ */
+export const isSKUSemantic = (semantic: AppliedDataSemantic): semantic is AppliedSKUSemantic => {
+  return semantic.id === SemanticType.SKU
+}
+
+/**
+ * Helper function to create a SKU semantic with configuration.
+ */
+export const createSKUSemantic = (config: SKUConfig = {}): AppliedSKUSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_SKU_CONFIG,
+    ...config,
+  }
+
+  // Merge metadata separately
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.SKU,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for SKU semantic.
+ * Optimized for common product catalog use cases.
+ */
+export const DEFAULT_SKU_CONFIG: SKUConfig = {
+  validationMode: 'strict',
+  caseMode: 'uppercase',
+  enforceUniqueness: true,
+  autoGenerate: false,
+  validateReservedWords: true,
+  reservedValues: ['ADMIN', 'TEST', 'NULL', 'DEFAULT', 'UNDEFINED', 'SAMPLE', 'DEMO'],
+}
+
+/**
+ * Predefined configurations for common use cases.
+ */
+export const SKU_PRESETS = {
+  /**
+   * Standard product SKU with strict validation and uppercase formatting.
+   */
+  PRODUCT_STANDARD: createSKUSemantic({
+    validationMode: 'strict',
+    caseMode: 'uppercase',
+    prefix: 'PROD-',
+    enforceUniqueness: true,
+  }),
+
+  /**
+   * Simple SKU configuration for basic catalogs.
+   */
+  SIMPLE: createSKUSemantic({
+    validationMode: 'lenient',
+    caseMode: 'preserve',
+    enforceUniqueness: true,
+  }),
+
+  /**
+   * Auto-generating SKU from product name.
+   */
+  AUTO_GENERATE: createSKUSemantic({
+    validationMode: 'strict',
+    caseMode: 'uppercase',
+    autoGenerate: true,
+    autoGenerateSource: 'name',
+    enforceUniqueness: true,
+  }),
+
+  /**
+   * Flexible SKU for variable product types.
+   */
+  FLEXIBLE: createSKUSemantic({
+    validationMode: 'lenient',
+    caseMode: 'preserve',
+    enforceUniqueness: true,
+    validateReservedWords: false,
+  }),
+} as const
+
+/**
+ * Helper function to validate a SKU configuration.
+ */
+export const validateSKUConfig = (config: SKUConfig): string[] => {
+  const errors: string[] = []
+
+  if (config.validationMode === 'custom' && !config.customPattern) {
+    errors.push('customPattern is required when validationMode is custom')
+  }
+
+  if (config.customPattern) {
+    try {
+      new RegExp(config.customPattern)
+    } catch {
+      errors.push('customPattern must be a valid regular expression')
+    }
+  }
+
+  if (config.prefix && config.prefix.length === 0) {
+    errors.push('prefix cannot be empty string')
+  }
+
+  if (config.autoGenerateSource && !config.autoGenerate) {
+    errors.push('autoGenerate must be true when autoGenerateSource is specified')
+  }
+
+  return errors
+}
+
+/**
+ * Helper function to validate SKU value against configuration.
+ */
+export const validateSKUValue = (value: string, config: SKUConfig = DEFAULT_SKU_CONFIG): string[] => {
+  const errors: string[] = []
+  const mergedConfig = { ...DEFAULT_SKU_CONFIG, ...config }
+
+  if (!value || typeof value !== 'string') {
+    errors.push('SKU value must be a non-empty string')
+    return errors
+  }
+
+  if (mergedConfig.validateReservedWords && mergedConfig.reservedValues) {
+    const normalizedValue = value.toUpperCase()
+    if (mergedConfig.reservedValues.some((reserved) => reserved.toUpperCase() === normalizedValue)) {
+      errors.push(`SKU cannot use reserved value: ${value}`)
+    }
+  }
+
+  // Validation pattern checks
+  if (mergedConfig.validationMode === 'strict') {
+    if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+      errors.push('SKU can only contain alphanumeric characters, hyphens, and underscores')
+    }
+  } else if (mergedConfig.validationMode === 'lenient') {
+    if (!/^[A-Za-z0-9_.-]+$/.test(value)) {
+      errors.push('SKU contains invalid characters')
+    }
+  } else if (mergedConfig.validationMode === 'custom' && mergedConfig.customPattern) {
+    try {
+      const regex = new RegExp(mergedConfig.customPattern)
+      if (!regex.test(value)) {
+        errors.push('SKU does not match the required pattern')
+      }
+    } catch {
+      errors.push('Invalid custom pattern configuration')
+    }
+  }
+
+  return errors
+}

package/src/modeling/definitions/Status.ts

@@ -0,0 +1,227 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the Status semantic.
+ * These options control state management and workflow behavior.
+ */
+export interface StatusConfig {
+  /**
+   * Allowed states for this status field.
+   * Only required when the field doesn't have enum values defined in the schema.
+   * If enum values are defined in DomainProperty > Schema, those values will be used instead.
+   */
+  allowedStates?: string[]
+
+  /**
+   * Default state when creating new records.
+   * Must be one of the allowedStates (if specified) or enum values from the schema.
+   */
+  defaultState: string
+
+  /**
+   * State transitions configuration.
+   * Maps from current state to array of allowed next states.
+   */
+  transitions?: Record<string, string[]>
+
+  /**
+   * State-specific behaviors and permissions.
+   */
+  stateBehaviors?: Record<
+    string,
+    {
+      /**
+       * Whether records in this state are publicly visible.
+       * Defaults to true if not specified.
+       */
+      isPublic?: boolean
+
+      /**
+       * Whether records in this state can be edited.
+       * Defaults to true if not specified.
+       */
+      isEditable?: boolean
+
+      /**
+       * Whether records in this state can be deleted.
+       * Defaults to false if not specified.
+       */
+      isDeletable?: boolean
+
+      /**
+       * Whether this state requires approval before transition.
+       * Defaults to false if not specified.
+       */
+      requiresApproval?: boolean
+
+      /**
+       * Custom display name for this state.
+       */
+      displayName?: string
+
+      /**
+       * Custom description for this state.
+       */
+      description?: string
+
+      /**
+       * Color or visual indicator for this state.
+       */
+      color?: string
+
+      /**
+       * Icon for this state.
+       */
+      icon?: string
+    }
+  >
+
+  /**
+   * Workflow configuration for status management.
+   */
+  workflow?: {
+    /**
+     * Whether status changes require approval.
+     * Defaults to false if not specified.
+     */
+    requiresApproval?: boolean
+
+    /**
+     * Roles that can approve status changes.
+     * Required if requiresApproval is true.
+     */
+    approvalRoles?: string[]
+
+    /**
+     * Whether to send notifications on status changes.
+     * Defaults to false if not specified.
+     */
+    sendNotifications?: boolean
+
+    /**
+     * Notification channels to use.
+     */
+    notificationChannels?: ('email' | 'sms' | 'push' | 'webhook')[]
+
+    /**
+     * Whether to log status change history.
+     * Defaults to true if not specified.
+     */
+    logHistory?: boolean
+
+    /**
+     * Whether to allow bulk status changes.
+     * Defaults to false if not specified.
+     */
+    allowBulkChanges?: boolean
+  }
+
+  /**
+   * Auto-transitions based on conditions.
+   */
+  autoTransitions?: {
+    /**
+     * Current state that triggers the auto-transition.
+     */
+    from: string
+
+    /**
+     * Target state to transition to.
+     */
+    to: string
+
+    /**
+     * Condition that triggers the transition.
+     * Examples: "after 24 hours", "when approved", "when payment received"
+     */
+    condition: string
+
+    /**
+     * Whether this auto-transition requires approval.
+     * Defaults to false if not specified.
+     */
+    requiresApproval?: boolean
+  }[]
+
+  /**
+   * Custom metadata for the status field.
+   */
+  metadata?: Record<string, unknown>
+
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Status semantic.
+ */
+export interface AppliedStatusSemantic extends AppliedDataSemantic {
+  id: SemanticType.Status
+  config?: StatusConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Status semantic.
+ */
+export const isStatusSemantic = (semantic: AppliedDataSemantic): semantic is AppliedStatusSemantic => {
+  return semantic.id === SemanticType.Status
+}
+
+/**
+ * Helper function to create a Status semantic with configuration.
+ */
+export const createStatusSemantic = (config: Partial<StatusConfig> = {}): AppliedStatusSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_STATUS_CONFIG,
+    ...config,
+    // Deep merge nested objects
+    stateBehaviors: config.stateBehaviors
+      ? { ...DEFAULT_STATUS_CONFIG.stateBehaviors, ...config.stateBehaviors }
+      : DEFAULT_STATUS_CONFIG.stateBehaviors,
+    workflow: config.workflow
+      ? { ...DEFAULT_STATUS_CONFIG.workflow, ...config.workflow }
+      : DEFAULT_STATUS_CONFIG.workflow,
+  }
+
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Status,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Status semantic.
+ */
+export const DEFAULT_STATUS_CONFIG: StatusConfig = {
+  defaultState: 'draft',
+  stateBehaviors: {
+    draft: {
+      isPublic: false,
+      isEditable: true,
+      isDeletable: true,
+    },
+    published: {
+      isPublic: true,
+      isEditable: true,
+      isDeletable: false,
+    },
+    archived: {
+      isPublic: false,
+      isEditable: false,
+      isDeletable: false,
+    },
+  },
+  workflow: {
+    requiresApproval: false,
+    sendNotifications: false,
+    logHistory: true,
+    allowBulkChanges: false,
+  },
+}

package/src/modeling/definitions/Summary.ts

@@ -0,0 +1,73 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration for the Summary semantic.
+ * Summary is a simple semantic without configuration options.
+ */
+export interface SummaryConfig {
+  /**
+   * Custom metadata for the summary field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Default configuration for the Summary semantic.
+ */
+export const DEFAULT_SUMMARY_CONFIG: SummaryConfig = {}
+
+/**
+ * Creates a Summary semantic application.
+ * @param config - Optional configuration (not used for simple semantic)
+ * @returns AppliedDataSemantic for Summary
+ */
+export const createSummarySemantic = (config?: SummaryConfig): AppliedDataSemantic => ({
+  id: SemanticType.Summary,
+  config: config ? { ...DEFAULT_SUMMARY_CONFIG, ...config } : { ...DEFAULT_SUMMARY_CONFIG },
+})
+
+/**
+ * Type guard to check if a semantic is a Summary semantic.
+ * @param semantic - The semantic to check
+ * @returns True if the semantic is a Summary semantic
+ */
+export const isSummarySemantic = (
+  semantic: AppliedDataSemantic
+): semantic is AppliedDataSemantic & { id: SemanticType.Summary } => semantic.id === SemanticType.Summary
+
+/**
+ * Extracts the configuration from a Summary semantic application.
+ * @param semantic - The semantic application
+ * @returns The Summary configuration or undefined if not a Summary semantic
+ */
+export const getSummaryConfig = (semantic: AppliedDataSemantic): SummaryConfig | undefined => {
+  if (!isSummarySemantic(semantic)) {
+    return undefined
+  }
+  return semantic.config as SummaryConfig | undefined
+}
+
+/**
+ * Validates Summary semantic configuration.
+ * @returns True if the configuration is valid
+ */
+export const validateSummaryConfig = (): boolean => {
+  // No validation needed for simple semantic
+  return true
+}
+
+/**
+ * Merges Summary configurations, with the second config taking precedence.
+ * @param base - The base configuration
+ * @param override - The configuration to merge on top
+ * @returns Merged configuration
+ */
+export const mergeSummaryConfig = (base: SummaryConfig, override: SummaryConfig): SummaryConfig => {
+  // No merging needed for simple semantic
+  return { ...base, ...override }
+}

package/src/modeling/definitions/Tags.ts

@@ -0,0 +1,75 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the Tags semantic.
+ * Controls allowed tags, validation, and formatting for associations.
+ */
+export interface TagsConfig {
+  /**
+   * List of allowed tags.
+   */
+  allowedTags?: string[]
+  /**
+   * Whether to allow custom tags not in the allowedTags list.
+   */
+  allowCustomTags?: boolean
+  /**
+   * Whether tags are case sensitive.
+   */
+  caseSensitive?: boolean
+  /**
+   * Whether to allow Unicode characters in tags.
+   */
+  allowUnicode?: boolean
+  /**
+   * Custom metadata for the tags association.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Tags semantic.
+ */
+export interface AppliedTagsSemantic extends AppliedDataSemantic {
+  id: SemanticType.Tags
+  config?: TagsConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Tags semantic.
+ */
+export const isTagsSemantic = (semantic: AppliedDataSemantic): semantic is AppliedTagsSemantic => {
+  return semantic.id === SemanticType.Tags
+}
+
+/**
+ * Helper function to create a Tags semantic with configuration.
+ */
+export const createTagsSemantic = (config: TagsConfig = {}): AppliedTagsSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_TAGS_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Tags,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Tags semantic.
+ */
+export const DEFAULT_TAGS_CONFIG: TagsConfig = {
+  allowCustomTags: true,
+  caseSensitive: false,
+  allowUnicode: false,
+}