@api-client/core 0.17.3 → 0.17.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.17.3",
+  "version": "0.17.5",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/modeling/Semantics.ts

@@ -151,7 +151,7 @@ export enum SemanticType {
    * Can store simple decimal amounts or complex objects with amount and currency.
    * Enforces proper decimal handling to avoid floating-point errors.
    */
-  Price = 'Semantic#Price',
+  Currency = 'Semantic#Currency',
   /**
    * Annotates a field as a URL with validation and allowed protocols.
    */
@@ -293,6 +293,11 @@ interface BaseDataSemantic {
    * The category this semantic belongs to for UI organization.
    */
   category: SemanticCategory
+  /**
+   * Whether the semantic has a configuration or additional options.
+   * This is used to determine if the semantic requires additional setup or configuration.
+   */
+  hasConfig: boolean
 }
 
 /**
@@ -359,6 +364,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     scope: SemanticScope.Entity,
     description: 'System users and accounts',
     category: SemanticCategory.Identity,
+    hasConfig: false,
   },
   [SemanticType.Password]: {
     id: SemanticType.Password,
@@ -367,6 +373,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Secure password field',
     category: SemanticCategory.Identity,
     applicableDataTypes: ['string'],
+    hasConfig: true,
   },
   [SemanticType.UserRole]: {
     id: SemanticType.UserRole,
@@ -375,6 +382,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'User permissions and access level',
     category: SemanticCategory.Identity,
     applicableDataTypes: ['string'],
+    hasConfig: false,
   },
   [SemanticType.ResourceOwnerIdentifier]: {
     id: SemanticType.ResourceOwnerIdentifier,
@@ -382,6 +390,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     scope: SemanticScope.Association,
     description: 'Links record to owner user',
     category: SemanticCategory.Identity,
+    hasConfig: false,
   },
 
   //
@@ -395,6 +404,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'When record was created',
     category: SemanticCategory.Lifecycle,
     applicableDataTypes: ['datetime'],
+    hasConfig: false,
   },
   [SemanticType.UpdatedTimestamp]: {
     id: SemanticType.UpdatedTimestamp,
@@ -403,6 +413,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'When record was last modified',
     category: SemanticCategory.Lifecycle,
     applicableDataTypes: ['datetime'],
+    hasConfig: false,
   },
   [SemanticType.DeletedTimestamp]: {
     id: SemanticType.DeletedTimestamp,
@@ -411,6 +422,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'When record was marked deleted',
     category: SemanticCategory.Lifecycle,
     applicableDataTypes: ['datetime'],
+    hasConfig: false,
   },
   [SemanticType.DeletedFlag]: {
     id: SemanticType.DeletedFlag,
@@ -419,6 +431,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Mark record as deleted',
     category: SemanticCategory.Lifecycle,
     applicableDataTypes: ['boolean'],
+    hasConfig: false,
   },
   [SemanticType.Version]: {
     id: SemanticType.Version,
@@ -427,6 +440,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Auto-incrementing version counter',
     category: SemanticCategory.Lifecycle,
     applicableDataTypes: ['number'],
+    hasConfig: false,
   },
 
   //
@@ -440,6 +454,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Main title or heading',
     category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
+    hasConfig: false,
   },
   [SemanticType.Description]: {
     id: SemanticType.Description,
@@ -448,6 +463,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Detailed description text',
     category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
+    hasConfig: false,
   },
   [SemanticType.Summary]: {
     id: SemanticType.Summary,
@@ -456,6 +472,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Brief summary text',
     category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
+    hasConfig: false,
   },
   [SemanticType.Markdown]: {
     id: SemanticType.Markdown,
@@ -464,6 +481,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Formatted text content',
     category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
+    hasConfig: true,
   },
   [SemanticType.HTML]: {
     id: SemanticType.HTML,
@@ -472,6 +490,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Rich HTML content',
     category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
+    hasConfig: true,
   },
   [SemanticType.ImageURL]: {
     id: SemanticType.ImageURL,
@@ -480,6 +499,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Link to image file',
     category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
+    hasConfig: false,
   },
   [SemanticType.FileURL]: {
     id: SemanticType.FileURL,
@@ -488,6 +508,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Link to file attachment',
     category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
+    hasConfig: false,
   },
 
   //
@@ -501,14 +522,16 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Current state of record',
     category: SemanticCategory.Business,
     applicableDataTypes: ['string'],
+    hasConfig: true,
   },
-  [SemanticType.Price]: {
-    id: SemanticType.Price,
-    displayName: 'Price',
+  [SemanticType.Currency]: {
+    id: SemanticType.Currency,
+    displayName: 'Currency',
     scope: SemanticScope.Property,
     description: 'Monetary value with currency',
     category: SemanticCategory.Business,
     applicableDataTypes: ['number', 'string'],
+    hasConfig: true,
   },
   [SemanticType.SKU]: {
     id: SemanticType.SKU,
@@ -517,6 +540,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Product identification code',
     category: SemanticCategory.Business,
     applicableDataTypes: ['string'],
+    hasConfig: true,
   },
 
   //
@@ -530,6 +554,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Email address',
     category: SemanticCategory.Contact,
     applicableDataTypes: ['string'],
+    hasConfig: true,
   },
   [SemanticType.Phone]: {
     id: SemanticType.Phone,
@@ -538,6 +563,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Phone number',
     category: SemanticCategory.Contact,
     applicableDataTypes: ['string'],
+    hasConfig: true,
   },
   [SemanticType.URL]: {
     id: SemanticType.URL,
@@ -546,6 +572,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Web address or link',
     category: SemanticCategory.Contact,
     applicableDataTypes: ['string'],
+    hasConfig: true,
   },
 
   //
@@ -559,6 +586,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'URL-friendly unique identifier',
     category: SemanticCategory.Organization,
     applicableDataTypes: ['string'],
+    hasConfig: true,
   },
   [SemanticType.Tags]: {
     id: SemanticType.Tags,
@@ -566,6 +594,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     scope: SemanticScope.Association,
     description: 'Enable tagging functionality',
     category: SemanticCategory.Organization,
+    hasConfig: true,
   },
   [SemanticType.Categories]: {
     id: SemanticType.Categories,
@@ -573,6 +602,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     scope: SemanticScope.Association,
     description: 'Enable categorization functionality',
     category: SemanticCategory.Organization,
+    hasConfig: true,
   },
 
   //
@@ -586,6 +616,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Location coordinates',
     category: SemanticCategory.Location,
     applicableDataTypes: ['string'],
+    hasConfig: true,
   },
 
   //
@@ -599,6 +630,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Auto-calculated field value',
     category: SemanticCategory.Computed,
     applicableDataTypes: ['string'],
+    hasConfig: true,
   },
   [SemanticType.Derived]: {
     id: SemanticType.Derived,
@@ -607,6 +639,7 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Value derived from other fields',
     category: SemanticCategory.Computed,
     applicableDataTypes: ['string'],
+    hasConfig: true,
   },
 }
 

package/src/modeling/definitions/{Price.examples.md → Currency.examples.md}

@@ -1,14 +1,14 @@
-# Price Semantic Examples
+# Currency Semantic Examples
 
-This document provides examples of how to use the Price semantic with different configurations.
+This document provides examples of how to use the Currency semantic with different configurations.
 
 ## Basic Usage
 
 ```typescript
-import { createPriceSemantic, PRICE_PRESETS } from './Price.js'
+import { createCurrencySemantic, CURRENCY_PRESETS } from './Currency.js'
 
 // Simple USD decimal storage
-const basicPrice = createPriceSemantic({
+const basicCurrency = createCurrencySemantic({
   storageFormat: 'decimal',
   defaultCurrency: 'USD',
   decimalPlaces: 2,
@@ -16,7 +16,7 @@ const basicPrice = createPriceSemantic({
 })
 
 // Using a preset
-const usdDecimal = PRICE_PRESETS.USD_DECIMAL
+const usdDecimal = CURRENCY_PRESETS.USD_DECIMAL
 ```
 
 ## Configuration Examples
@@ -24,7 +24,7 @@ const usdDecimal = PRICE_PRESETS.USD_DECIMAL
 ### 1. Simple E-commerce Store (USD only)
 
 ```typescript
-const ecommercePrice = createPriceSemantic({
+const ecommerceCurrency = createCurrencySemantic({
   storageFormat: 'decimal',
   defaultCurrency: 'USD',
   decimalPlaces: 2,
@@ -35,7 +35,7 @@ const ecommercePrice = createPriceSemantic({
 ### 2. International E-commerce (Multi-currency)
 
 ```typescript
-const internationalPrice = createPriceSemantic({
+const internationalCurrency = createCurrencySemantic({
   storageFormat: 'complex_object',
   allowedCurrencies: ['USD', 'EUR', 'GBP', 'JPY', 'CAD', 'AUD'],
   decimalPlaces: 2,
@@ -46,7 +46,7 @@ const internationalPrice = createPriceSemantic({
 ### 3. Financial System (High precision, allows negatives)
 
 ```typescript
-const financialPrice = createPriceSemantic({
+const financialCurrency = createCurrencySemantic({
   storageFormat: 'integer_cents',
   defaultCurrency: 'USD',
   decimalPlaces: 4,
@@ -57,7 +57,7 @@ const financialPrice = createPriceSemantic({
 ### 4. Cryptocurrency Trading
 
 ```typescript
-const cryptoPrice = createPriceSemantic({
+const cryptoCurrency = createCurrencySemantic({
   storageFormat: 'decimal',
   defaultCurrency: 'BTC',
   decimalPlaces: 8,
@@ -142,10 +142,10 @@ CREATE INDEX idx_products_price_currency ON products USING GIN ((price->>'curren
 
 ## Validation Examples
 
-The Price semantic includes built-in validation:
+The Currency semantic includes built-in validation:
 
 ```typescript
-import { validatePriceConfig } from './Price.js'
+import { validateCurrencyConfig } from './Currency.js'
 
 const config = {
   storageFormat: 'decimal' as const,
@@ -153,6 +153,6 @@ const config = {
   decimalPlaces: 2,
 }
 
-const errors = validatePriceConfig(config)
+const errors = validateCurrencyConfig(config)
 console.log(errors) // ['defaultCurrency is required when storageFormat is not complex_object']
 ```

package/src/modeling/definitions/{Price.ts → Currency.ts}

@@ -4,13 +4,13 @@ import { SemanticType } from '../Semantics.js'
 /**
  * Supported storage formats for monetary values.
  */
-export type PriceStorageFormat = 'decimal' | 'integer_cents' | 'complex_object'
+export type CurrencyStorageFormat = 'decimal' | 'integer_cents' | 'complex_object'
 
 /**
- * Configuration options for the Price semantic.
+ * Configuration options for the Currency semantic.
  * Controls monetary value storage, validation, currency handling, and precision.
  */
-export interface PriceConfig {
+export interface CurrencyConfig {
   /**
    * How the monetary value is stored in the database.
    *
@@ -18,7 +18,7 @@ export interface PriceConfig {
    * - '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
+  storageFormat?: CurrencyStorageFormat
 
   /**
    * Default currency code (ISO 4217) when not specified.
@@ -50,7 +50,7 @@ export interface PriceConfig {
   validateCurrencyCode?: boolean
 
   /**
-   * Custom metadata for the price field.
+   * Custom metadata for the currency field.
    */
   metadata?: Record<string, unknown>
 
@@ -61,26 +61,26 @@ export interface PriceConfig {
 }
 
 /**
- * Type-safe configuration for Price semantic.
+ * Type-safe configuration for Currency semantic.
  */
-export interface AppliedPriceSemantic extends AppliedDataSemantic {
-  id: SemanticType.Price
-  config?: PriceConfig
+export interface AppliedCurrencySemantic extends AppliedDataSemantic {
+  id: SemanticType.Currency
+  config?: CurrencyConfig
 }
 
 /**
- * Type guard to check if a semantic is a Price semantic.
+ * Type guard to check if a semantic is a Currency semantic.
  */
-export const isPriceSemantic = (semantic: AppliedDataSemantic): semantic is AppliedPriceSemantic => {
-  return semantic.id === SemanticType.Price
+export const isCurrencySemantic = (semantic: AppliedDataSemantic): semantic is AppliedCurrencySemantic => {
+  return semantic.id === SemanticType.Currency
 }
 
 /**
- * Helper function to create a Price semantic with configuration.
+ * Helper function to create a Currency semantic with configuration.
  */
-export const createPriceSemantic = (config: PriceConfig = {}): AppliedPriceSemantic => {
+export const createCurrencySemantic = (config: CurrencyConfig = {}): AppliedCurrencySemantic => {
   const mergedConfig = {
-    ...DEFAULT_PRICE_CONFIG,
+    ...DEFAULT_CURRENCY_CONFIG,
     ...config,
   }
 
@@ -90,16 +90,16 @@ export const createPriceSemantic = (config: PriceConfig = {}): AppliedPriceSeman
   }
 
   return {
-    id: SemanticType.Price,
+    id: SemanticType.Currency,
     config: mergedConfig,
   }
 }
 
 /**
- * Default configuration for Price semantic.
+ * Default configuration for Currency semantic.
  * Optimized for common e-commerce use cases with USD currency.
  */
-export const DEFAULT_PRICE_CONFIG: PriceConfig = {
+export const DEFAULT_CURRENCY_CONFIG: CurrencyConfig = {
   storageFormat: 'decimal',
   defaultCurrency: 'USD',
   decimalPlaces: 2,
@@ -110,11 +110,11 @@ export const DEFAULT_PRICE_CONFIG: PriceConfig = {
 /**
  * Predefined configurations for common use cases.
  */
-export const PRICE_PRESETS = {
+export const CURRENCY_PRESETS = {
   /**
    * Simple USD decimal storage - good for most e-commerce sites.
    */
-  USD_DECIMAL: createPriceSemantic({
+  USD_DECIMAL: createCurrencySemantic({
     storageFormat: 'decimal',
     defaultCurrency: 'USD',
     decimalPlaces: 2,
@@ -124,7 +124,7 @@ export const PRICE_PRESETS = {
   /**
    * Integer cents storage - avoids floating point issues, good for financial calculations.
    */
-  USD_CENTS: createPriceSemantic({
+  USD_CENTS: createCurrencySemantic({
     storageFormat: 'integer_cents',
     defaultCurrency: 'USD',
     decimalPlaces: 2,
@@ -134,7 +134,7 @@ export const PRICE_PRESETS = {
   /**
    * Multi-currency support with complex object storage.
    */
-  MULTI_CURRENCY: createPriceSemantic({
+  MULTI_CURRENCY: createCurrencySemantic({
     storageFormat: 'complex_object',
     allowedCurrencies: ['USD', 'EUR', 'GBP', 'JPY', 'CAD'],
     decimalPlaces: 2,
@@ -144,7 +144,7 @@ export const PRICE_PRESETS = {
   /**
    * Configuration that allows negative values for refunds, discounts, etc.
    */
-  WITH_NEGATIVES: createPriceSemantic({
+  WITH_NEGATIVES: createCurrencySemantic({
     storageFormat: 'decimal',
     defaultCurrency: 'USD',
     decimalPlaces: 2,
@@ -154,7 +154,7 @@ export const PRICE_PRESETS = {
   /**
    * High-precision configuration for cryptocurrency or precious metals.
    */
-  HIGH_PRECISION: createPriceSemantic({
+  HIGH_PRECISION: createCurrencySemantic({
     storageFormat: 'decimal',
     defaultCurrency: 'BTC',
     decimalPlaces: 8,
@@ -163,9 +163,9 @@ export const PRICE_PRESETS = {
 } as const
 
 /**
- * Helper function to validate a price configuration.
+ * Helper function to validate a currency configuration.
  */
-export const validatePriceConfig = (config: PriceConfig): string[] => {
+export const validateCurrencyConfig = (config: CurrencyConfig): string[] => {
   const errors: string[] = []
 
   if (config.storageFormat !== 'complex_object' && !config.defaultCurrency) {

package/src/modeling/definitions/HTML.ts

@@ -10,12 +10,25 @@ export interface HTMLConfig {
    * List of allowed HTML tags in the content.
    */
   allowedTags?: string[]
-  /**
-   * Maximum length of the HTML content.
-   */
-  maxLength?: number
   /**
    * Render mode: 'html', 'text', or 'both'.
+   *
+   * - `html` - The API returns the HTML content as-is (after sanitization based on your other rules like allowedTags).
+   * - `text` - The API returns the text content, stripping out all HTML tags.
+   *    This is extremely useful for various backend and frontend tasks:
+   *    - **Search Indexing**: You can easily feed the plain text content into a search engine like Elasticsearch
+   *      without the noise of HTML tags.
+   *    - **Content Previews/Summaries**: Displaying a snippet of the content in a list view or a notification
+   *      where formatting is not desired.
+   *    - **Compatibility**: Sending the content to systems that don't support HTML, such as plain-text
+   *      emails or SMS notifications.
+   * - `both` - The API returns an object containing both the raw HTML and the plain text version. For example:
+   *   ```json
+   *   {
+   *     "html": "<p>Hello, <strong>world</strong>!</p>",
+   *     "text": "Hello, world!"
+   *   }
+   *   ```
    */
   renderMode?: 'html' | 'text' | 'both'
   /**
@@ -106,7 +119,6 @@ export const createHTMLSemantic = (config: HTMLConfig = {}): AppliedHTMLSemantic
  */
 export const DEFAULT_HTML_CONFIG: HTMLConfig = {
   allowedTags: ['b', 'i', 'em', 'strong', 'a', 'ul', 'ol', 'li', 'p', 'br', 'pre', 'code', 'div', 'span'],
-  maxLength: 10000,
   renderMode: 'html',
   sanitizeLevel: 'strict',
   allowImages: true,

package/src/modeling/definitions/Markdown.ts

@@ -10,12 +10,20 @@ 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'.
+   * This controls how the stored Markdown content is transformed and returned by the API.
+   *
+   * - `html` - The API converts the Markdown to HTML and returns the sanitized result.
+   * - `text` - The original Markdown as when created, but sanitized.
+   * - `both` - The API returns an object containing both the rendered HTML and the plain text version.
+   *   This provides maximum flexibility for client applications.
+   *   ```json
+   *   {
+   *     "html": "<h1>Title</h1><p>Some <strong>bold</strong> text.</p>",
+   *     "text": "Title Some bold text."
+   *   }
+   *   ```
    */
   renderMode?: 'html' | 'text' | 'both'
   /**
@@ -102,7 +110,6 @@ export const createMarkdownSemantic = (config: MarkdownConfig = {}): AppliedMark
  */
 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,

package/src/modeling/definitions/Status.ts

@@ -17,7 +17,7 @@ export interface StatusConfig {
    * Default state when creating new records.
    * Must be one of the allowedStates (if specified) or enum values from the schema.
    */
-  defaultState: string
+  defaultState?: string
 
   /**
    * State transitions configuration.
@@ -200,6 +200,7 @@ export const createStatusSemantic = (config: Partial<StatusConfig> = {}): Applie
  * Default configuration for Status semantic.
  */
 export const DEFAULT_STATUS_CONFIG: StatusConfig = {
+  allowedStates: ['draft', 'published', 'archived'],
   defaultState: 'draft',
   stateBehaviors: {
     draft: {