@api-client/core 0.15.0 → 0.16.0

package/src/modeling/definitions/Markdown.ts

@@ -0,0 +1,116 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the Markdown semantic.
+ * Controls rendering, sanitization, and allowed features.
+ */
+export interface MarkdownConfig {
+  /**
+   * List of allowed HTML tags in the rendered output.
+   */
+  allowedTags?: string[]
+  /**
+   * Maximum length of the markdown content.
+   */
+  maxLength?: number
+  /**
+   * Render mode: 'html', 'text', or 'both'.
+   */
+  renderMode?: 'html' | 'text' | 'both'
+  /**
+   * Sanitization level: 'strict', 'moderate', or 'none'.
+   */
+  sanitizeLevel?: 'strict' | 'moderate' | 'none'
+  /**
+   * Whether to allow images in markdown.
+   */
+  allowImages?: boolean
+  /**
+   * Whether to allow links in markdown.
+   */
+  allowLinks?: boolean
+  /**
+   * Whether to allow tables in markdown.
+   */
+  allowTables?: boolean
+  /**
+   * Whether to allow raw HTML in markdown.
+   */
+  allowHtml?: boolean
+  /**
+   * Whether to allow footnotes in markdown.
+   */
+  allowFootnotes?: boolean
+  /**
+   * Whether to allow GitHub-style task lists.
+   */
+  allowTaskLists?: boolean
+  /**
+   * Whether to allow strikethrough formatting.
+   */
+  allowStrikethrough?: boolean
+  /**
+   * Whether to allow math expressions (e.g., LaTeX).
+   */
+  allowMath?: boolean
+  /**
+   * Custom metadata for the markdown field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Markdown semantic.
+ */
+export interface AppliedMarkdownSemantic extends AppliedDataSemantic {
+  id: SemanticType.Markdown
+  config?: MarkdownConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Markdown semantic.
+ */
+export const isMarkdownSemantic = (semantic: AppliedDataSemantic): semantic is AppliedMarkdownSemantic => {
+  return semantic.id === SemanticType.Markdown
+}
+
+/**
+ * Helper function to create a Markdown semantic with configuration.
+ */
+export const createMarkdownSemantic = (config: MarkdownConfig = {}): AppliedMarkdownSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_MARKDOWN_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Markdown,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Markdown semantic.
+ */
+export const DEFAULT_MARKDOWN_CONFIG: MarkdownConfig = {
+  allowedTags: ['b', 'i', 'em', 'strong', 'a', 'ul', 'ol', 'li', 'p', 'br', 'pre', 'code'],
+  maxLength: 10000,
+  renderMode: 'html',
+  sanitizeLevel: 'strict',
+  allowImages: true,
+  allowLinks: true,
+  allowTables: true,
+  allowHtml: false,
+  allowFootnotes: false,
+  allowTaskLists: false,
+  allowStrikethrough: true,
+  allowMath: false,
+}

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']
+```