@api-client/core 0.15.1 → 0.16.1

package/src/modeling/definitions/Password.ts

@@ -0,0 +1,156 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Supported encryption algorithms for password hashing.
+ */
+export enum PasswordEncryptionAlgorithm {
+  /**
+   * bcrypt - Industry standard, secure, and widely supported
+   */
+  Bcrypt = 'bcrypt',
+  /**
+   * Argon2 - Winner of the Password Hashing Competition, very secure
+   */
+  Argon2 = 'argon2',
+  /**
+   * scrypt - Memory-hard function, good for high-security applications
+   */
+  Scrypt = 'scrypt',
+}
+
+/**
+ * Configuration options for the Password semantic.
+ * These options control password validation and encryption behavior.
+ */
+export interface PasswordConfig {
+  /**
+   * Whether to require special characters.
+   * Defaults to false if not specified.
+   */
+  requireSpecialChars?: boolean
+
+  /**
+   * Whether to require numbers.
+   * Defaults to false if not specified.
+   */
+  requireNumbers?: boolean
+
+  /**
+   * Whether to require uppercase letters.
+   * Defaults to false if not specified.
+   */
+  requireUppercase?: boolean
+
+  /**
+   * Whether to require lowercase letters.
+   * Defaults to false if not specified.
+   */
+  requireLowercase?: boolean
+
+  /**
+   * Encryption algorithm to use for password hashing.
+   * Defaults to 'bcrypt' if not specified.
+   */
+  encryptionAlgorithm?: PasswordEncryptionAlgorithm
+
+  /**
+   * Number of salt rounds for bcrypt.
+   * Defaults to 12 if not specified.
+   */
+  saltRounds?: number
+
+  /**
+   * Maximum age of password in days before requiring change.
+   * Defaults to null (no expiration) if not specified.
+   */
+  maxAge?: number
+
+  /**
+   * Whether to prevent reuse of recent passwords.
+   * Defaults to false if not specified.
+   */
+  preventReuse?: boolean
+
+  /**
+   * Number of recent passwords to prevent reuse.
+   * Defaults to 5 if preventReuse is true.
+   */
+  preventReuseCount?: number
+
+  /**
+   * Custom password validation regex pattern.
+   * If specified, overrides other validation rules.
+   */
+  customPattern?: string
+
+  /**
+   * Custom error message for validation failures.
+   */
+  customErrorMessage?: string
+
+  /**
+   * Whether to allow common passwords.
+   * Defaults to false if not specified.
+   */
+  allowCommonPasswords?: boolean
+
+  /**
+   * Custom metadata for the password field.
+   */
+  metadata?: Record<string, unknown>
+
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Password semantic.
+ */
+export interface AppliedPasswordSemantic extends AppliedDataSemantic {
+  id: SemanticType.Password
+  config?: PasswordConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Password semantic.
+ */
+export const isPasswordSemantic = (semantic: AppliedDataSemantic): semantic is AppliedPasswordSemantic => {
+  return semantic.id === SemanticType.Password
+}
+
+/**
+ * Helper function to create a Password semantic with configuration.
+ */
+export const createPasswordSemantic = (config: PasswordConfig = {}): AppliedPasswordSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_PASSWORD_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Password,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Password semantic.
+ */
+export const DEFAULT_PASSWORD_CONFIG: PasswordConfig = {
+  requireSpecialChars: true,
+  requireNumbers: true,
+  requireUppercase: true,
+  requireLowercase: true,
+  encryptionAlgorithm: PasswordEncryptionAlgorithm.Bcrypt,
+  saltRounds: 12,
+  maxAge: undefined,
+  preventReuse: false,
+  preventReuseCount: 5,
+  allowCommonPasswords: false,
+}

package/src/modeling/definitions/Phone.ts

@@ -0,0 +1,116 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the Phone semantic.
+ * Controls validation, formatting, and verification of phone numbers.
+ */
+export interface PhoneConfig {
+  /**
+   * List of allowed country codes (ISO 3166-1 alpha-2 format).
+   * If not specified, all countries are allowed.
+   * Examples: ['US', 'CA', 'GB', 'DE']
+   */
+  allowedCountries?: string[]
+
+  /**
+   * Whether the phone number must include a country code.
+   * Defaults to true for E.164 format.
+   */
+  requireCountryCode?: boolean
+
+  /**
+   * Format for phone number validation and display.
+   * - 'E.164': International format with + prefix (e.g., +1234567890)
+   * - 'national': Country-specific format without country code
+   * - 'international': International format with country code
+   * - 'custom': Use customFormat pattern
+   */
+  format?: 'E.164' | 'national' | 'international' | 'custom'
+
+  /**
+   * Custom format pattern for phone number validation.
+   * Only used when format is set to 'custom'.
+   * Examples: '###-###-####', '(###) ###-####'
+   */
+  customFormat?: string
+
+  /**
+   * Whether to allow phone extensions (e.g., +1234567890 ext 123).
+   * Defaults to false.
+   */
+  allowExtension?: boolean
+
+  /**
+   * Whether phone number verification is required.
+   * Defaults to false.
+   */
+  requireVerification?: boolean
+
+  /**
+   * Method to use for phone verification.
+   * - 'sms': Send verification code via SMS
+   * - 'call': Make verification call
+   * - 'none': No verification required
+   */
+  verificationMethod?: 'sms' | 'call' | 'none'
+
+  /**
+   * Custom metadata for the phone field.
+   */
+  metadata?: Record<string, unknown>
+
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Phone semantic.
+ */
+export interface AppliedPhoneSemantic extends AppliedDataSemantic {
+  id: SemanticType.Phone
+  config?: PhoneConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Phone semantic.
+ * @param semantic - The semantic to check
+ * @returns True if the semantic is a Phone semantic
+ */
+export const isPhoneSemantic = (semantic: AppliedDataSemantic): semantic is AppliedPhoneSemantic => {
+  return semantic.id === SemanticType.Phone
+}
+
+/**
+ * Helper function to create a Phone semantic with configuration.
+ * @param config - Configuration options for the phone semantic
+ * @returns AppliedPhoneSemantic with the specified configuration
+ */
+export const createPhoneSemantic = (config: PhoneConfig = {}): AppliedPhoneSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_PHONE_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Phone,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Phone semantic.
+ * Uses E.164 format with country code required and SMS verification.
+ */
+export const DEFAULT_PHONE_CONFIG: PhoneConfig = {
+  requireCountryCode: true,
+  format: 'E.164',
+  allowExtension: false,
+  requireVerification: false,
+  verificationMethod: 'sms',
+}

package/src/modeling/definitions/Price.examples.md

@@ -0,0 +1,158 @@
+# Price Semantic Examples
+
+This document provides examples of how to use the Price semantic with different configurations.
+
+## Basic Usage
+
+```typescript
+import { createPriceSemantic, PRICE_PRESETS } from './Price.js'
+
+// Simple USD decimal storage
+const basicPrice = createPriceSemantic({
+  storageFormat: 'decimal',
+  defaultCurrency: 'USD',
+  decimalPlaces: 2,
+  allowNegative: false,
+})
+
+// Using a preset
+const usdDecimal = PRICE_PRESETS.USD_DECIMAL
+```
+
+## Configuration Examples
+
+### 1. Simple E-commerce Store (USD only)
+
+```typescript
+const ecommercePrice = createPriceSemantic({
+  storageFormat: 'decimal',
+  defaultCurrency: 'USD',
+  decimalPlaces: 2,
+  allowNegative: false,
+})
+```
+
+### 2. International E-commerce (Multi-currency)
+
+```typescript
+const internationalPrice = createPriceSemantic({
+  storageFormat: 'complex_object',
+  allowedCurrencies: ['USD', 'EUR', 'GBP', 'JPY', 'CAD', 'AUD'],
+  decimalPlaces: 2,
+  allowNegative: false,
+})
+```
+
+### 3. Financial System (High precision, allows negatives)
+
+```typescript
+const financialPrice = createPriceSemantic({
+  storageFormat: 'integer_cents',
+  defaultCurrency: 'USD',
+  decimalPlaces: 4,
+  allowNegative: true,
+})
+```
+
+### 4. Cryptocurrency Trading
+
+```typescript
+const cryptoPrice = createPriceSemantic({
+  storageFormat: 'decimal',
+  defaultCurrency: 'BTC',
+  decimalPlaces: 8,
+  allowNegative: false,
+})
+```
+
+## Storage Format Details
+
+### Decimal Format
+
+- **Best for**: Simple single-currency applications
+- **PostgreSQL Type**: DECIMAL(precision, scale)
+- **Example Value**: 19.99
+- **Pros**: Human-readable, direct calculations
+- **Cons**: Currency must be stored separately if needed
+
+### Integer Cents Format
+
+- **Best for**: Financial calculations requiring precision
+- **PostgreSQL Type**: BIGINT
+- **Example Value**: 1999 (represents $19.99)
+- **Pros**: No floating-point errors, efficient storage
+- **Cons**: Requires conversion for display
+
+### Complex Object Format
+
+- **Best for**: Multi-currency applications
+- **PostgreSQL Type**: JSONB
+- **Example Value**: {"amount": 1999, "currency": "USD"}
+- **Pros**: Stores amount and currency together, flexible
+- **Cons**: More complex queries, larger storage
+
+## Database Schema Generation Examples
+
+The runtime will generate appropriate PostgreSQL schemas based on the semantic configuration:
+
+### For Decimal Format
+
+Based on `storageFormat: 'decimal'` configuration, the runtime should generate:
+
+```sql
+CREATE TABLE products (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(255),
+  price DECIMAL(19, 2) NOT NULL,
+  currency CHAR(3) DEFAULT 'USD'
+);
+
+CREATE INDEX idx_products_price ON products(price);
+```
+
+### For Integer Cents Format
+
+Based on `storageFormat: 'integer_cents'` configuration, the runtime should generate:
+
+```sql
+CREATE TABLE products (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(255),
+  price_cents BIGINT NOT NULL,
+  currency CHAR(3) DEFAULT 'USD'
+);
+
+CREATE INDEX idx_products_price_cents ON products(price_cents);
+```
+
+### For Complex Object Format
+
+Based on `storageFormat: 'complex_object'` configuration, the runtime should generate:
+
+```sql
+CREATE TABLE products (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(255),
+  price JSONB NOT NULL
+);
+
+CREATE INDEX idx_products_price_amount ON products USING GIN ((price->>'amount'));
+CREATE INDEX idx_products_price_currency ON products USING GIN ((price->>'currency'));
+```
+
+## Validation Examples
+
+The Price semantic includes built-in validation:
+
+```typescript
+import { validatePriceConfig } from './Price.js'
+
+const config = {
+  storageFormat: 'decimal' as const,
+  // Missing defaultCurrency - this will cause an error
+  decimalPlaces: 2,
+}
+
+const errors = validatePriceConfig(config)
+console.log(errors) // ['defaultCurrency is required when storageFormat is not complex_object']
+```

package/src/modeling/definitions/Price.ts

@@ -0,0 +1,180 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Supported storage formats for monetary values.
+ */
+export type PriceStorageFormat = 'decimal' | 'integer_cents' | 'complex_object'
+
+/**
+ * Configuration options for the Price semantic.
+ * Controls monetary value storage, validation, currency handling, and precision.
+ */
+export interface PriceConfig {
+  /**
+   * How the monetary value is stored in the database.
+   *
+   * - 'decimal': Store as DECIMAL/NUMERIC type (e.g., 19.99)
+   * - 'integer_cents': Store as INTEGER in smallest currency unit (e.g., 1999 for $19.99)
+   * - 'complex_object': Store as JSON/JSONB with amount and currency (e.g., {"amount": 1999, "currency": "USD"})
+   */
+  storageFormat?: PriceStorageFormat
+
+  /**
+   * Default currency code (ISO 4217) when not specified.
+   * Required when using 'decimal' or 'integer_cents' format.
+   */
+  defaultCurrency?: string
+
+  /**
+   * List of allowed currency codes (ISO 4217).
+   * If not specified, all valid ISO 4217 currencies are allowed.
+   */
+  allowedCurrencies?: string[]
+
+  /**
+   * Number of decimal places for precision.
+   * Default: 2 (for most currencies like USD, EUR)
+   * Some currencies may need 0 (JPY, KRW) or 3 (BHD, KWD)
+   */
+  decimalPlaces?: number
+
+  /**
+   * Whether negative values are allowed (for refunds, discounts, etc.).
+   */
+  allowNegative?: boolean
+
+  /**
+   * Whether to automatically validate currency codes against ISO 4217.
+   */
+  validateCurrencyCode?: boolean
+
+  /**
+   * Custom metadata for the price field.
+   */
+  metadata?: Record<string, unknown>
+
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Price semantic.
+ */
+export interface AppliedPriceSemantic extends AppliedDataSemantic {
+  id: SemanticType.Price
+  config?: PriceConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Price semantic.
+ */
+export const isPriceSemantic = (semantic: AppliedDataSemantic): semantic is AppliedPriceSemantic => {
+  return semantic.id === SemanticType.Price
+}
+
+/**
+ * Helper function to create a Price semantic with configuration.
+ */
+export const createPriceSemantic = (config: PriceConfig = {}): AppliedPriceSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_PRICE_CONFIG,
+    ...config,
+  }
+
+  // Merge metadata separately
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Price,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Price semantic.
+ * Optimized for common e-commerce use cases with USD currency.
+ */
+export const DEFAULT_PRICE_CONFIG: PriceConfig = {
+  storageFormat: 'decimal',
+  defaultCurrency: 'USD',
+  decimalPlaces: 2,
+  allowNegative: false,
+  validateCurrencyCode: true,
+}
+
+/**
+ * Predefined configurations for common use cases.
+ */
+export const PRICE_PRESETS = {
+  /**
+   * Simple USD decimal storage - good for most e-commerce sites.
+   */
+  USD_DECIMAL: createPriceSemantic({
+    storageFormat: 'decimal',
+    defaultCurrency: 'USD',
+    decimalPlaces: 2,
+    allowNegative: false,
+  }),
+
+  /**
+   * Integer cents storage - avoids floating point issues, good for financial calculations.
+   */
+  USD_CENTS: createPriceSemantic({
+    storageFormat: 'integer_cents',
+    defaultCurrency: 'USD',
+    decimalPlaces: 2,
+    allowNegative: false,
+  }),
+
+  /**
+   * Multi-currency support with complex object storage.
+   */
+  MULTI_CURRENCY: createPriceSemantic({
+    storageFormat: 'complex_object',
+    allowedCurrencies: ['USD', 'EUR', 'GBP', 'JPY', 'CAD'],
+    decimalPlaces: 2,
+    allowNegative: false,
+  }),
+
+  /**
+   * Configuration that allows negative values for refunds, discounts, etc.
+   */
+  WITH_NEGATIVES: createPriceSemantic({
+    storageFormat: 'decimal',
+    defaultCurrency: 'USD',
+    decimalPlaces: 2,
+    allowNegative: true,
+  }),
+
+  /**
+   * High-precision configuration for cryptocurrency or precious metals.
+   */
+  HIGH_PRECISION: createPriceSemantic({
+    storageFormat: 'decimal',
+    defaultCurrency: 'BTC',
+    decimalPlaces: 8,
+    allowNegative: false,
+  }),
+} as const
+
+/**
+ * Helper function to validate a price configuration.
+ */
+export const validatePriceConfig = (config: PriceConfig): string[] => {
+  const errors: string[] = []
+
+  if (config.storageFormat !== 'complex_object' && !config.defaultCurrency) {
+    errors.push('defaultCurrency is required when storageFormat is not complex_object')
+  }
+
+  if (config.decimalPlaces !== undefined && config.decimalPlaces < 0) {
+    errors.push('decimalPlaces must be non-negative')
+  }
+
+  return errors
+}

package/src/modeling/definitions/PublicUniqueName.ts

@@ -0,0 +1,98 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the PublicUniqueName (slug) semantic.
+ * Controls how slugs are generated and validated.
+ */
+export interface PublicUniqueNameConfig {
+  /**
+   * The source field to generate the slug from (e.g., 'title').
+   * Default to the field that is annotated with the Title semantic.
+   */
+  sourceField?: string
+  /**
+   * Separator character to use in the slug (default: '-').
+   */
+  separator?: string
+  /**
+   * Maximum length of the slug (default: 64).
+   */
+  maxLength?: number
+  /**
+   * Whether the slug is case sensitive (default: false).
+   */
+  caseSensitive?: boolean
+  /**
+   * Whether to allow Unicode characters in the slug (default: false).
+   */
+  allowUnicode?: boolean
+  /**
+   * Name of a custom generator function to use for slug creation.
+   */
+  customGenerator?: string
+  /**
+   * Whether to allow duplicate slugs (default: false).
+   */
+  allowDuplicates?: boolean
+  /**
+   * Fallback field to use if the source field is empty or invalid.
+   */
+  fallbackField?: string
+  /**
+   * Custom metadata for the slug field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for PublicUniqueName semantic.
+ */
+export interface AppliedPublicUniqueNameSemantic extends AppliedDataSemantic {
+  id: SemanticType.PublicUniqueName
+  config?: PublicUniqueNameConfig
+}
+
+/**
+ * Type guard to check if a semantic is a PublicUniqueName semantic.
+ */
+export const isPublicUniqueNameSemantic = (
+  semantic: AppliedDataSemantic
+): semantic is AppliedPublicUniqueNameSemantic => {
+  return semantic.id === SemanticType.PublicUniqueName
+}
+
+/**
+ * Helper function to create a PublicUniqueName semantic with configuration.
+ */
+export const createPublicUniqueNameSemantic = (
+  config: PublicUniqueNameConfig = {}
+): AppliedPublicUniqueNameSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_PUBLIC_UNIQUE_NAME_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.PublicUniqueName,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for PublicUniqueName semantic.
+ */
+export const DEFAULT_PUBLIC_UNIQUE_NAME_CONFIG: PublicUniqueNameConfig = {
+  separator: '-',
+  maxLength: 64,
+  caseSensitive: false,
+  allowUnicode: false,
+  allowDuplicates: false,
+}