@api-client/core 0.15.0 → 0.16.0

package/TESTING_READY.md

@@ -0,0 +1,114 @@
+# Testing Setup Complete! 🎉
+
+Your API Client Core project now has a comprehensive testing setup with documentation and utilities.
+
+## What's Been Added
+
+### 📚 Documentation
+
+- **`TESTING_SETUP.md`** - Complete testing guide and reference
+- **Test Templates** - Ready-to-use templates for new tests
+
+### 🛠️ Utilities
+
+- **`tests/test-utils.ts`** - Common testing utilities and helpers
+- **`tests/example-test-setup.ts`** - Working examples of test patterns
+- **`tests/template-node.spec.ts`** - Template for Node.js tests
+- **`test/template-browser.test.ts`** - Template for browser tests
+
+### ⚡ VS Code Tasks
+
+- **Test: Run All Tests** - Runs both Node.js and browser tests
+- Additional test tasks available in the Command Palette
+
+## Quick Start
+
+### Run All Tests
+
+```bash
+npm test
+```
+
+### Run Node.js Tests Only
+
+```bash
+npm run test:node
+```
+
+### Run Browser Tests Only  
+
+```bash
+npm run test:browser
+```
+
+### Run Tests with Coverage
+
+```bash
+npm run test:coverage
+```
+
+### Run Tests in Watch Mode
+
+```bash
+npm run test:browser:watch
+```
+
+## Your Testing Stack
+
+### Node.js Tests (Japa)
+
+- **Location**: `tests/unit/**/*.spec.ts`
+- **Framework**: Japa with Assert plugin
+- **Features**: Sinon mocking, API client testing, type checking
+- **Run with**: `npm run test:node`
+
+### Browser Tests (Web Test Runner)  
+
+- **Location**: `test/**/*.browser.test.ts` or `test/**/*.spec.ts`
+- **Framework**: Web Test Runner with Chai
+- **Features**: Playwright automation, OAuth2 mock server, DOM testing
+- **Run with**: `npm run test:browser`
+
+## File Naming Conventions
+
+- **Node.js tests**: `*.spec.ts` in `tests/unit/`
+- **Browser tests**: `*.browser.test.ts` or `*.spec.ts` in `test/`
+- **Shared utilities**: Place in `test/` directory
+
+## Next Steps
+
+1. **Review the documentation** in `TESTING_SETUP.md`
+2. **Explore the examples** in `test/example-test-setup.ts`
+3. **Use the templates** to create new tests:
+   - Copy `test/template-node.spec.ts` for Node.js tests
+   - Copy `test/template-browser.test.ts` for browser tests
+4. **Run the existing tests** to ensure everything works
+5. **Write tests for your modules** using the patterns shown
+
+## Testing Best Practices
+
+✅ **Separate Node.js and browser tests** - Use appropriate file naming  
+✅ **Use test utilities** - Leverage `TestUtils` for common operations  
+✅ **Mock external dependencies** - Use Sinon for consistent mocking  
+✅ **Test both success and error cases** - Ensure comprehensive coverage  
+✅ **Group related tests** - Use test groups for better organization  
+✅ **Clean up after tests** - Restore mocks and clean up resources  
+
+## Available Test Utilities
+
+- `TestUtils.createMockResponse()` - HTTP response mocking
+- `TestUtils.createTestRequest()` - HTTP request creation  
+- `TestUtils.generateTestData()` - Random test data
+- `TestUtils.assertThrows()` - Error testing
+- `TestUtils.mockFetch()` - Fetch API mocking
+- `BrowserTestUtils.waitForElement()` - DOM element waiting
+- `BrowserTestUtils.createMockLocalStorage()` - Storage mocking
+
+## Need Help?
+
+- Check `TESTING_SETUP.md` for detailed documentation
+- Look at existing tests in `tests/unit/` for examples
+- Review the templates for common patterns
+- Run tests with `--verbose` flag for more output
+
+Happy testing! 🚀

package/TESTING_SETUP.md

@@ -0,0 +1,198 @@
+# Testing Setup Guide
+
+## Overview
+
+This project uses a sophisticated dual-testing approach with:
+
+- **Japa** for Node.js unit tests (server-side)
+- **Web Test Runner** for browser tests (client-side)
+
+## Test Structure
+
+```text
+├── test/                    # Browser tests (Web Test Runner)
+│   ├── **/*.browser.test.ts # Browser-specific tests
+│   ├── **/*.spec.ts         # Browser test specs
+│   └── env.ts               # Test environment configuration
+├── tests/                   # Node.js tests (Japa)
+│   └── unit/                # Unit tests for server-side code
+│       └── **/*.spec.ts     # Node.js test specs
+└── bin/
+    ├── test.ts              # Japa test runner
+    ├── test-web.ts          # Web Test Runner launcher
+    └── plugins/             # Custom test plugins
+```
+
+## Available Test Commands
+
+### Node.js Tests
+
+```bash
+npm run test:node           # Run all Node.js tests
+npm run test:node:coverage  # Run with coverage
+```
+
+### Browser Tests
+
+```bash
+npm run test:browser        # Run all browser tests
+npm run test:browser:watch  # Run in watch mode
+```
+
+### Combined Tests
+
+```bash
+npm test                    # Run both Node.js and browser tests
+npm run test:coverage       # Run both with coverage
+```
+
+## Test Frameworks & Libraries
+
+### Node.js Testing Stack
+
+- **@japa/runner** - Test runner
+- **@japa/assert** - Assertions
+- **@japa/api-client** - HTTP client for API testing
+- **@japa/expect-type** - TypeScript type testing
+- **sinon** - Mocking and spying
+- **c8** - Code coverage
+
+### Browser Testing Stack
+
+- **@web/test-runner** - Test runner
+- **@esm-bundle/chai** - Assertions for browser
+- **@web/test-runner-playwright** - Browser automation
+- **sinon** - Mocking (browser compatible)
+
+## Writing Tests
+
+### Node.js Tests Example
+
+```typescript
+import { test } from '@japa/runner'
+
+test.group('YourModule', (group) => {
+  group.each.setup(() => {
+    // Setup before each test
+  })
+
+  test('should do something', ({ assert }) => {
+    // Your test logic
+    assert.equal(actual, expected)
+  })
+})
+```
+
+### Browser Tests Example
+
+```typescript
+import { assert } from '@esm-bundle/chai'
+
+describe('YourModule', () => {
+  it('should work in browser', () => {
+    // Your browser test logic
+    assert.equal(actual, expected)
+  })
+})
+```
+
+## Test Environment Setup
+
+### OAuth2 Mock Server
+
+- Automatically starts on available port 8000-8100
+- Provides endpoints for various OAuth2 flows
+- Configured in `web-test-runner.config.js`
+
+### HTTP Servers
+
+- Express servers with CORS support
+- NTLM authentication support
+- Custom middleware for specific test scenarios
+
+## Test Plugins
+
+### Sinon Plugin
+
+```typescript
+test('should mock', ({ sinon, assert }) => {
+  const stub = sinon.stub(obj, 'method')
+  // ... test logic
+})
+```
+
+### Events Plugin
+
+```typescript
+test('should handle events', ({ events, assert }) => {
+  // Custom event testing logic
+})
+```
+
+## Configuration Files
+
+### TypeScript Configurations
+
+- `test/tsconfig.json` - Browser test compilation
+- `tests/tsconfig.json` - Node.js test compilation
+- `tsconfig.browser.json` - Browser build configuration
+- `tsconfig.node.json` - Node.js build configuration
+
+### Test Runner Configurations
+
+- `web-test-runner.config.js` - Browser test configuration
+- `bin/test.ts` - Japa test configuration
+
+## Running Specific Tests
+
+### Run specific test files
+
+```bash
+# Node.js specific file
+npm run test:node  -- --files=tests/unit/specific-test.spec.ts
+
+# Browser specific file
+npm run test:browser -- --files=test/specific-test.browser.test.ts
+```
+
+### Run tests with debugging
+
+```bash
+# Node.js with debugging
+node --inspect --import ts-node-maintained/register/esm bin/test.ts
+
+# Browser with debugging
+npm run test:browser -- --open --manual
+```
+
+## Coverage Reports
+
+Coverage is generated using **c8** for Node.js tests:
+
+- Reports in `lcov` and `text` formats
+- Configured to work with TypeScript source maps
+- Excludes test files and build artifacts
+
+## Best Practices
+
+1. **Separate browser and Node.js tests** - Use appropriate file naming
+2. **Use proper assertions** - Japa's assert for Node.js, Chai for browser
+3. **Mock external dependencies** - Use Sinon for consistent mocking
+4. **Test async code properly** - Use proper async/await patterns
+5. **Group related tests** - Use test groups for better organization
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Port conflicts** - OAuth2 server uses dynamic ports
+2. **TypeScript compilation** - Check tsconfig files
+3. **Browser timeouts** - Increase timeout in web-test-runner config
+4. **Import issues** - Ensure proper ES module imports
+
+### Debug Tips
+
+1. Use `--watch` mode for development
+2. Check browser console for client-side errors
+3. Use `console.log` or debugger statements
+4. Verify mock server responses

package/build/src/modeling/Semantics.d.ts

@@ -38,11 +38,19 @@ export declare enum SemanticType {
      */
     DeletedFlag = "Semantic#DeletedFlag",
     /**
-     * Designates a Data Property as a unique public identifier for a resource.
+     * Designates a Data Property as a unique public identifier for a resource (the slug).
      * This is often used in URLs to provide a user-friendly way to access the resource.
      * For example, a blog post might have a public unique name like "my-first-post".
+     * A URL-friendly text field. The runtime automatically generates a unique, URL-safe string from another field (like a title or name). The user needs to specify which field is used to generate
+     * the slug.
      */
     PublicUniqueName = "Semantic#PublicUniqueName",
+    /**
+     * A semantic that describes a title of an article, blog post, and so on. This semantic is used with
+     * the `PublicUniqueName` to determine which field is responsible for the slug generation. However,
+     * we may add more automation related to the `title` property in the future.
+     */
+    Title = "Semantic#Title",
     /**
      * Designates a Data Property as the `role` of a user within the system.
      * This is used to define the user's permissions and access levels.
@@ -51,12 +59,128 @@ export declare enum SemanticType {
      * Roles are defined on the entity as enums, or as a string property with a controlled vocabulary.
      */
     UserRole = "Semantic#UserRole",
+    /**
+     * A text or enum field to represent the state of a record (e.g., `draft`, `published`, `pending_review`, `archived`).
+     *
+     * Defined behaviors:
+     * - State-Based Filtering: Automatically prevents public users from seeing records in a draft state.
+     * - State Transitions: In principle, the runtime should prevent the user from skipping some states.
+     * For example, when the record is in the `draft` state, it cannot be moved to the `archived` state without publishing it first. However,
+     * we do not have enough customer feedback to design this functionality correctly right now, so
+     * it serves as a placeholder semantic annotation.
+     */
+    Status = "Semantic#Status",
+    /**
+     * Annotates an integer field that automatically increments.
+     * The runtime automatically increments this number on every update, providing a simple way
+     * to track changes and implement optimistic locking to prevent mid-air collisions.
+     */
+    Version = "Semantic#Version",
+    /**
+     * Annotates a field that holds a reference to an image data via an URL.
+     * The application + runtime should validate that the input is a well-formed URL.
+     */
+    ImageURL = "Semantic#ImageURL",
+    /**
+     * Annotates a field that holds a reference to a file object via an URL. Ity is distinct from the
+     * `ImageURL` semantic as it implicitly states that the target is non-image, binary data (an attachment, for example).
+     */
+    FileURL = "Semantic#FileURL",
+    /**
+     * Annotates the field as a markdown-interpreted field.
+     * When an object is created, the runtime performs additional sanitization to prevent XSS attacks.
+     *
+     * The annotation describes whether the data should be translated to the HTML output when
+     * record is read or the original MD content should be returned.
+     */
+    Markdown = "Semantic#Markdown",
+    /**
+     * Annotates the field as containing HTML content.
+     * The runtime performs sanitization to prevent XSS attacks and validates HTML structure.
+     *
+     * The annotation describes whether the data should be rendered as HTML output when
+     * record is read or the original HTML content should be returned.
+     */
+    HTML = "Semantic#HTML",
+    /**
+     * Annotates a field that holds geospatial coordinate data (latitude/longitude).
+     * The runtime automatically generates API capabilities for location-based queries,
+     * such as "find all restaurants within a 5-mile radius."
+     *
+     * The field should contain coordinate data in a standard format:
+     * - "40.7128,-74.0060" (lat,lon)
+     * - "POINT(-74.0060 40.7128)" (PostGIS format)
+     * - "40.7128°N, 74.0060°W" (degree format)
+     *
+     * Defined behaviors:
+     * - Spatial Indexing: The runtime automatically creates spatial indexes for efficient location-based queries
+     * - Distance Queries: Enables API endpoints for finding records within specified distances
+     * - Coordinate Validation: Validates that the input follows proper coordinate format
+     * - PostGIS Integration: When using PostgreSQL, automatically maps to PostGIS geometry types
+     */
+    GeospatialCoordinates = "Semantic#GeospatialCoordinates",
+    /**
+     * Annotates a field as an email address with validation and verification options.
+     */
+    Email = "Semantic#Email",
+    /**
+     * Annotates a field as a phone number with validation and formatting options.
+     */
+    Phone = "Semantic#Phone",
+    /**
+     * Annotates a field as a monetary value with currency support and precision control.
+     * Can store simple decimal amounts or complex objects with amount and currency.
+     * Enforces proper decimal handling to avoid floating-point errors.
+     */
+    Price = "Semantic#Price",
+    /**
+     * Annotates a field as a URL with validation and allowed protocols.
+     */
+    URL = "Semantic#URL",
+    /**
+     * Annotates a field as a Stock Keeping Unit (SKU).
+     * Enforces uniqueness at the database level, critical for product catalogs.
+     * Provides automatic validation and formatting for product identification codes.
+     */
+    SKU = "Semantic#SKU",
+    /**
+     * Annotates a field as a long-form description.
+     */
+    Description = "Semantic#Description",
+    /**
+     * Annotates a field as a short summary.
+     */
+    Summary = "Semantic#Summary",
+    /**
+     * Annotates a field as a calculated value based on a formula.
+     */
+    Calculated = "Semantic#Calculated",
+    /**
+     * Annotates a field as derived from other fields.
+     */
+    Derived = "Semantic#Derived",
     /**
      * Designates an association that links a resource to a "User" entity instance.
      * This is used to indicate ownership of the resource for access control purposes.
      * For example, a blog post might have a resource owner identifier that points to the user who created it.
+     *
+     * Defined behaviors:
+     * - Automatic Ownership: When a new record is created, this field is automatically populated with the ID of the authenticated user. It also creates a foreign relationship to the `User` semantic object.
+     * - Scoped Access: The runtime automatically filters list and read operations to show only records where the Owner matches the current user. update and delete operations are similarly restricted.
+     */
+    ResourceOwnerIdentifier = "Semantic#ResourceOwnerIdentifier",
+    /**
+     * Annotates an association as supporting tag functionality.
+     * Applied to associations between entities to enable tagging behavior.
+     * For example, a Product-Category association with Tags semantic enables product tagging.
+     */
+    Tags = "Semantic#Tags",
+    /**
+     * Annotates an association as supporting category functionality.
+     * Applied to associations between entities to enable categorization behavior.
+     * For example, a Product-Category association with Categories semantic enables product categorization.
      */
-    ResourceOwnerIdentifier = "Semantic#ResourceOwnerIdentifier"
+    Categories = "Semantic#Categories"
 }
 /**
  * Defines the scope at which a semantic can be applied.

package/build/src/modeling/Semantics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Semantics.d.ts","sourceRoot":"","sources":["../../../src/modeling/Semantics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAEzD;;;GAGG;AACH,oBAAY,YAAY;IAEtB;;OAEG;IACH,IAAI,kBAAkB;IAGtB;;;;OAIG;IACH,QAAQ,sBAAsB;IAC9B;;;OAGG;IACH,gBAAgB,8BAA8B;IAC9C;;;OAGG;IACH,gBAAgB,8BAA8B;IAC9C;;;;;OAKG;IACH,gBAAgB,8BAA8B;IAC9C;;;;OAIG;IACH,WAAW,yBAAyB;IACpC;;;;OAIG;IACH,gBAAgB,8BAA8B;IAC9C;;;;;;OAMG;IACH,QAAQ,sBAAsB;IAE9B;;;;OAIG;IACH,uBAAuB,qCAAqC;CAC7D;AAED;;GAEG;AACH,oBAAY,aAAa;IACvB;;;OAGG;IACH,MAAM,WAAW;IACjB;;;OAGG;IACH,QAAQ,aAAa;IACrB;;;OAGG;IACH,WAAW,gBAAgB;CAC5B;AAED;;;;;GAKG;AACH,UAAU,gBAAgB;IACxB;;OAEG;IACH,EAAE,EAAE,YAAY,CAAA;IAChB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,KAAK,EAAE,aAAa,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,KAAK,EAAE,aAAa,CAAC,MAAM,CAAA;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACxD,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAA;IAC7B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,kBAAkB,EAAE,CAAA;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,KAAK,EAAE,aAAa,CAAC,WAAW,CAAA;CACjC;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,UAAU,YAAY,KAAG,QAAQ,IAAI,cAC7B,CAAA;AAEzC;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,YAAY,KAAG,QAAQ,IAAI,gBAC7B,CAAA;AAE3C;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAI,UAAU,YAAY,KAAG,QAAQ,IAAI,mBAC7B,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,gBAAgB,GAAG,mBAAmB,CAAA;AAElF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,YAAY,EAAE,YAAY,CAmE5D,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,EAAE,EAAE,YAAY,CAAA;IAEhB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC"}
+{"version":3,"file":"Semantics.d.ts","sourceRoot":"","sources":["../../../src/modeling/Semantics.ts"],"names":[],"mappings":"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"}