feat: add complete TypeScript client infrastructure

- Add complete build infrastructure (rollup, jest, eslint)
- Add comprehensive test suite with jest
- Add CHANGELOG and proper versioning
- Add LICENSE file
- Add examples directory with usage examples
- Add scripts for build automation
- Add source code in src/ directory
- Add proper TypeScript configuration
- Add ESLint configuration for code quality

This provides a production-ready TypeScript client library
with complete build, test, and development infrastructure.

Author: AlmostBald-TRADING

clients/python/test_import.py

@@ -0,0 +1,125 @@
+"""Import tests for contextforge_memory_client package."""
+
+
+def test_package_importable():
+    """Test that the package can be imported."""
+    import contextforge_memory_client  # noqa: F401
+
+
+def test_client_class_importable():
+    """Test ContextForgeClient import and validate runtime type."""
+    from contextforge_memory_client import ContextForgeClient  # noqa: F401
+
+    assert ContextForgeClient is not None
+    # Validate that ContextForgeClient is a class
+    assert isinstance(ContextForgeClient, type)
+
+    # Verify it has an __init__ method
+    assert hasattr(ContextForgeClient, "__init__")
+    assert callable(ContextForgeClient.__init__)
+
+    # Validate connection lifecycle methods
+    expected_lifecycle_methods = ["close", "__enter__", "__exit__", "__del__"]
+    for method_name in expected_lifecycle_methods:
+        assert hasattr(
+            ContextForgeClient, method_name
+        ), f"Missing lifecycle method: {method_name}"
+        method = getattr(ContextForgeClient, method_name)
+        assert callable(method), f"Method {method_name} is not callable"
+
+    # Validate core API methods
+    expected_api_methods = ["health", "search"]
+    for method_name in expected_api_methods:
+        assert hasattr(
+            ContextForgeClient, method_name
+        ), f"Missing API method: {method_name}"
+        method = getattr(ContextForgeClient, method_name)
+        assert callable(method), f"Method {method_name} is not callable"
+
+
+def test_all_exports_available():
+    """Test all expected exports are available and validate runtime types."""
+    from contextforge_memory_client import (
+        ContextForgeAPIError,
+        ContextForgeClient,
+        PermanentAPIError,
+        RetryConfig,
+        TimeoutAPIError,
+        TransientAPIError,
+    )  # noqa: F401
+
+    # Verify all classes are importable
+    assert ContextForgeClient is not None
+    assert ContextForgeAPIError is not None
+    assert TransientAPIError is not None
+    assert PermanentAPIError is not None
+    assert TimeoutAPIError is not None
+    assert RetryConfig is not None
+
+    # Validate that ContextForgeClient and RetryConfig are classes
+    assert isinstance(ContextForgeClient, type)
+    assert isinstance(RetryConfig, type)
+
+    # Verify ContextForgeClient has expected methods
+    assert hasattr(ContextForgeClient, "__init__")
+
+    # Validate that error types are subclasses of Exception
+    assert issubclass(ContextForgeAPIError, Exception)
+    assert issubclass(TransientAPIError, Exception)
+    assert issubclass(PermanentAPIError, Exception)
+    assert issubclass(TimeoutAPIError, Exception)
+
+
+def test_retry_config_validation():
+    """Test RetryConfig class structure and default values."""
+    from contextforge_memory_client import RetryConfig
+
+    # Verify RetryConfig has __init__ method
+    assert hasattr(RetryConfig, "__init__")
+    assert callable(RetryConfig.__init__)
+
+    # Create a minimal RetryConfig instance with defaults
+    retry_config = RetryConfig()
+
+    # Validate expected attributes are present
+    expected_attributes = [
+        "max_attempts",
+        "base_wait",
+        "max_wait",
+        "exponential_multiplier",
+        "jitter",
+    ]
+
+    for attr in expected_attributes:
+        assert hasattr(retry_config, attr), f"Missing attribute: {attr}"
+
+    # Validate default values and types
+    assert isinstance(retry_config.max_attempts, int)
+    assert retry_config.max_attempts == 3
+
+    assert isinstance(retry_config.base_wait, float)
+    assert retry_config.base_wait == 1.0
+
+    assert isinstance(retry_config.max_wait, float)
+    assert retry_config.max_wait == 60.0
+
+    assert isinstance(retry_config.exponential_multiplier, float)
+    assert retry_config.exponential_multiplier == 2.0
+
+    assert isinstance(retry_config.jitter, bool)
+    assert retry_config.jitter is True
+
+    # Test custom initialization
+    custom_config = RetryConfig(
+        max_attempts=5,
+        base_wait=0.5,
+        max_wait=30.0,
+        exponential_multiplier=1.5,
+        jitter=False,
+    )
+
+    assert custom_config.max_attempts == 5
+    assert custom_config.base_wait == 0.5
+    assert custom_config.max_wait == 30.0
+    assert custom_config.exponential_multiplier == 1.5
+    assert custom_config.jitter is False

clients/typescript/.eslintignore

@@ -0,0 +1,4 @@
+.eslintrc.js
+*.config.js
+node_modules/
+dist/

clients/typescript/.eslintrc.js

@@ -0,0 +1,32 @@
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+  ],
+  plugins: ['@typescript-eslint'],
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+    lib: ['ES2020', 'DOM'],
+  },
+  rules: {
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/explicit-function-return-type': ['error', {
+      allowExpressions: true,
+      allowTypedFunctionExpressions: true
+    }],
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/no-inferrable-types': 'off',
+    '@typescript-eslint/strict-boolean-expressions': 'warn',
+    'prefer-const': 'error',
+    'no-var': 'error',
+    'no-unused-vars': 'off', // Turn off base rule as it can conflict with @typescript-eslint/no-unused-vars
+  },
+  env: {
+    node: true,
+    es6: true,
+    jest: true,
+  },
+};

clients/typescript/.gitignore

@@ -0,0 +1,84 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build outputs
+dist/
+build/
+*.tsbuildinfo
+
+# Coverage reports
+coverage/
+*.lcov
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Environment files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Logs
+logs/
+*.log
+
+# Runtime data
+pids/
+*.pid
+*.seed
+*.pid.lock
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# next.js build output
+.next
+
+# nuxt.js build output
+.nuxt
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/

clients/typescript/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to the ContextForge Memory Client will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- NPM package distribution with `@contextforge/memory-client`
+- TypeScript definitions included in package
+- CommonJS and ES module builds
+- CI/CD pipeline for automated testing and publishing
+- Comprehensive test suite with Jest
+- Build configuration with TypeScript and Rollup
+- Initial release of ContextForge Memory Client
+- Support for both v0 and v1 API endpoints
+- Memory item storage and retrieval
+- Vector search capabilities
+- Embedding generation
+- Session checkpoint and restore functionality
+- Comprehensive error handling with custom error types
+- Retry logic with exponential backoff
+- Request timeout handling
+- TypeScript support with full type definitions
+
+### Features
+- **v0 API Support**: Health checks, store, search, and embed endpoints
+- **v1 API Support**: Enhanced store, search, embed, checkpoint, and restore endpoints
+- **Authentication**: Optional API key support for v1 endpoints
+- **Error Handling**: Custom error types for better debugging
+- **Retry Logic**: Configurable retry behavior for transient failures
+- **Timeout Support**: Configurable request timeouts
+- **Type Safety**: Full TypeScript definitions for all APIs
+
+### API Endpoints
+- `health()` - Check service health
+- `store(items)` - Store memory items (v0)
+- `search(namespace, project_id, query, top_k)` - Search memory items (v0)
+- `embed(texts)` - Generate embeddings (v0)
+- `v1Store(items, vectors?)` - Store memory items with optional vectors (v1)
+- `v1Search(namespace, project_id, query, top_k)` - Search memory items (v1)
+- `v1Embed(texts)` - Generate embeddings (v1)
+- `v1Checkpoint(session_id, phase, summary?, metadata?)` - Create session checkpoint (v1)
+- `v1Restore(session_id, task, top_k)` - Restore session context (v1)
+
+### Changed
+- Enhanced README with dual installation options (NPM + single-file)
+- Improved documentation with migration guides
+- Added semantic versioning guidance
+
+## [0.1.0] - TBD
+
+### Added
+- Initial release of ContextForge Memory Client
+- Support for both v0 and v1 API endpoints
+- Memory item storage and retrieval
+- Vector search capabilities
+- Embedding generation
+- Session checkpoint and restore functionality
+- Comprehensive error handling with custom error types
+- Retry logic with exponential backoff
+- Request timeout handling
+- TypeScript support with full type definitions
+
+### Features
+- **v0 API Support**: Health checks, store, search, and embed endpoints
+- **v1 API Support**: Enhanced store, search, embed, checkpoint, and restore endpoints
+- **Authentication**: Optional API key support for v1 endpoints
+- **Error Handling**: Custom error types for better debugging
+- **Retry Logic**: Configurable retry behavior for transient failures
+- **Timeout Support**: Configurable request timeouts
+- **Type Safety**: Full TypeScript definitions for all APIs
+
+### API Endpoints
+- `health()` - Check service health
+- `store(items)` - Store memory items (v0)
+- `search(namespace, project_id, query, top_k)` - Search memory items (v0)
+- `embed(texts)` - Generate embeddings (v0)
+- `v1Store(items, vectors?)` - Store memory items with optional vectors (v1)
+- `v1Search(namespace, project_id, query, top_k)` - Search memory items (v1)
+- `v1Embed(texts)` - Generate embeddings (v1)
+- `v1Checkpoint(session_id, phase, summary?, metadata?)` - Create session checkpoint (v1)
+- `v1Restore(session_id, task, top_k)` - Restore session context (v1)

clients/typescript/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 bofh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.