feat(sdk-ts): implement unified typescript sdk wrapper with examples and default export

Author: realfishsam

core/package.json

@@ -25,7 +25,8 @@
     "server": "tsx watch src/server/index.ts",
     "server:prod": "node dist/server/index.js",
     "generate:sdk:python": "npx @openapitools/openapi-generator-cli generate -i src/server/openapi.yaml -g python -o ../sdks/python/generated --package-name pmxt_internal --additional-properties=projectName=pmxt-internal,packageVersion=0.4.4,library=urllib3",
-    "generate:sdk:all": "npm run generate:sdk:python"
+    "generate:sdk:typescript": "npx @openapitools/openapi-generator-cli generate -i src/server/openapi.yaml -g typescript-fetch -o ../sdks/typescript --additional-properties=npmName=pmxtjs,npmVersion=0.0.1,supportsES6=true,typescriptThreePlus=true",
+    "generate:sdk:all": "npm run generate:sdk:python && npm run generate:sdk:typescript"
   },
   "keywords": [],
   "author": "",

package-lock.json

@@ -27,158 +27,131 @@ PMXT uses a **"Sidecar" architecture** for multi-language support:
 
 ### Why This Approach?
 
-1. **Single Source of Truth**: The Node.js implementation is the canonical version
+1. **Single Source of Truth**: The implementation in `core/` is the canonical version
 2. **Consistency**: All languages get identical behavior
 3. **Rapid Iteration**: Update the server, all SDKs update automatically
 4. **Quality**: We can write the core logic once, in TypeScript, with full testing
 
-## Directory Structure
+## General Directory Structure
+
+All SDKs follow this pattern:
 
 ```
 sdks/
-└── python/
+└── {language}/
     ├── pmxt/                    # Human-written wrapper (EDIT THIS)
-    │   ├── __init__.py
-    │   ├── client.py           # Main Exchange classes
-    │   └── models.py           # Clean dataclasses
-    ├── generated/               # Auto-generated (DO NOT EDIT)
-    │   └── pmxt_internal/      # Raw OpenAPI client
+    │   └── ...                 # Clean, idiomatic code
+    ├── {generated}/             # Auto-generated client (DO NOT EDIT)
+    │   └── ...                 # Raw OpenAPI client
     ├── examples/
-    │   └── basic_usage.py
-    ├── pyproject.toml
-    └── README.md
+    └── {package-manager-files}
 ```
 
 ### The Golden Rule
 
-**NEVER manually edit files in `generated/`**. They will be overwritten.
+**NEVER manually edit files in the generated directory**. They will be overwritten.
 
-All human code goes in `pmxt/` (the wrapper).
+All human logic goes in the `pmxt/` directory (the wrapper).
 
-## Generating SDKs
+## Supported Languages
 
-### Python
+### 1. Python (`sdks/python`)
 
-```bash
-# Generate the raw OpenAPI client
-npm run generate:sdk:python
+- **Reference**: [sdks/python/README.md](./python/README.md)
+- **Generator**: `python`
+- **Generated Dir**: `sdks/python/generated/`
+- **Wrapper Dir**: `sdks/python/pmxt/`
 
-# Or manually:
-npx @openapitools/openapi-generator-cli generate \
-  -i src/server/openapi.yaml \
-  -g python \
-  -o sdks/python/generated \
-  --package-name pmxt_internal \
-  --additional-properties=projectName=pmxt-internal,packageVersion=0.4.4,library=urllib3
-```
+### 2. TypeScript (`sdks/typescript`)
 
-This creates the "ugly" auto-generated client in `sdks/python/generated/pmxt_internal/`.
+- **Reference**: [sdks/typescript/README.md](./typescript/README.md)
+- **Generator**: `typescript-fetch`
+- **Generated Dir**: `sdks/typescript/src/`
+- **Wrapper Dir**: `sdks/typescript/pmxt/`
 
-The human wrapper in `sdks/python/pmxt/` imports this and provides a clean API.
+## Generating SDKs
 
-### Future Languages
+To regenerate all SDKs after updating the server specification:
 
-When adding Go, Java, etc.:
+```bash
+# In the root or core directory
+npm run generate:sdk:all
+```
+
+To generate a specific language:
 
 ```bash
-# Go
-npm run generate:sdk:go
+# Python
+npm run generate:sdk:python
 
-# Java
-npm run generate:sdk:java
+# TypeScript
+npm run generate:sdk:typescript
 ```
 
-Each will follow the same pattern:
-- `sdks/{language}/generated/` - Auto-generated client
-- `sdks/{language}/pmxt/` - Human wrapper
-
 ## The Human Wrapper Pattern
 
-The wrapper does three things:
+The "wrapper" is a handwritten layer that sits on top of the auto-generated code. Its job is to make the API feel native and clean for that language.
 
-### 1. Clean Imports
+### Responsibilities
 
-```python
-# User writes:
-import pmxt
-poly = pmxt.Polymarket()
-
-# Not:
-from pmxt_internal.api.default_api import DefaultApi
-from pmxt_internal.configuration import Configuration
-# ... etc
-```
+1.  **Hide the Ugly**: Generated code is often verbose. The wrapper hides this.
+2.  **Provide Idiomatic API**: Use language-specific features (e.g., Python properties, TypeScript interfaces).
+3.  **Manage Server Lifecycle**: Include the `ServerManager` to auto-start the sidecar.
+4.  **Simplify Models**: Convert complex generated schemas into simple data classes/interfaces.
 
-### 2. Pythonic API
+### Example: Python vs TypeScript
 
-```python
-# User writes:
-markets = poly.search_markets("Trump", MarketFilterParams(limit=10))
+**Python Wrapper (`sdks/python/pmxt/client.py`)**:
 
-# Not:
-request = SearchMarketsRequest(args=["Trump", {"limit": 10}])
-response = api.search_markets(exchange="polymarket", search_markets_request=request)
-data = response.to_dict()["data"]
+```python
+class Exchange(ABC):
+    def search_markets(self, query):
+        # Calls self._api.search_markets()
+        # Converts response to UnifiedMarket dataclass
+        pass
 ```
 
-### 3. Clean Data Models
+**TypeScript Wrapper (`sdks/typescript/pmxt/client.ts`)**:
 
-```python
-# User gets:
-@dataclass
-class UnifiedMarket:
-    id: str
-    title: str
-    outcomes: List[MarketOutcome]
-    # ...
-
-# Not:
-class UnifiedMarket(BaseModel):
-    def __init__(self, id=None, title=None, outcomes=None, ...):
-        # 100 lines of generated code
+```typescript
+export abstract class Exchange {
+  async searchMarkets(query: string): Promise<UnifiedMarket[]> {
+    // Calls this.api.searchMarkets()
+    // Converts response to UnifiedMarket interface
+    return markets;
+  }
+}
 ```
 
-## Maintaining the Wrapper
+## Maintaining the SDKs
 
 When you add a new endpoint to the OpenAPI spec:
 
-1. **Update `src/server/openapi.yaml`** with the new endpoint
-2. **Regenerate**: `npm run generate:sdk:python`
-3. **Update the wrapper**:
-   - Add the method to `pmxt/client.py`
-   - Add any new models to `pmxt/models.py`
-   - Add a converter function if needed
+1.  **Update `src/server/openapi.yaml`** with the new endpoint.
+2.  **Regenerate** SDKs: `npm run generate:sdk:all`.
+3.  **Update the wrappers**:
+    *   **Python**: Update `sdks/python/pmxt/client.py` & `models.py`.
+    *   **TypeScript**: Update `sdks/typescript/pmxt/client.ts` & `models.ts`.
 
-Example:
+## Testing
 
-```python
-# In pmxt/client.py
-def fetch_new_thing(self, thing_id: str) -> NewThing:
-    """Fetch a new thing."""
-    try:
-        request_body = {"args": [thing_id]}
-        
-        response = self._api.fetch_new_thing(
-            exchange=self.exchange_name,
-            fetch_new_thing_request=request_body,
-        )
-        
-        data = self._handle_response(response.to_dict())
-        return _convert_new_thing(data)
-    except ApiException as e:
-        raise Exception(f"Failed to fetch new thing: {e}")
-```
+Always test your changes in **both** languages.
 
-## Testing
+### Python
 
 ```bash
 cd sdks/python
-
-# Install in development mode
 pip install -e ".[dev]"
+python examples/*
+```
+
+### TypeScript
 
-# Run the example (requires server running)
-python examples/basic_usage.py
+```bash
+cd sdks/typescript
+npm install
+npm run build
+npx tsx examples/*
 ```
 
 ## Publishing
@@ -187,61 +160,31 @@ python examples/basic_usage.py
 
 ```bash
 cd sdks/python
-
-# Build
 python -m build
-
-# Upload to PyPI
 python -m twine upload dist/*
 ```
 
-### Version Bumping
-
-When releasing a new version:
-
-1. Update `package.json` version
-2. Update `sdks/python/pyproject.toml` version
-3. Regenerate SDKs: `npm run generate:sdk:all`
-4. Commit and tag: `git tag v0.4.5`
-
-## Common Issues
-
-### "Module not found: pmxt_internal"
+### TypeScript (NPM)
 
-The generated client isn't in the Python path. The wrapper adds it dynamically:
-
-```python
-# In pmxt/client.py
-_GENERATED_PATH = os.path.join(os.path.dirname(__file__), "..", "generated")
-sys.path.insert(0, _GENERATED_PATH)
+```bash
+cd sdks/typescript
+npm publish --access public
 ```
 
-### "OpenAPI validation error"
-
-Your `openapi.yaml` has a schema issue. Common problems:
-
-- Empty arrays without `items: {}`
-- Missing required fields
-- Invalid enum values
-
-Run the generator with `--skip-validate-spec` to see the raw error.
+## Version Bumping
 
-### "Server not running"
-
-The Python SDK requires the sidecar server:
-
-```bash
-# Terminal 1: Start server
-npm run server
+When releasing a new version:
 
-# Terminal 2: Run Python code
-python examples/basic_usage.py
-```
+1.  Update `core/package.json` version.
+2.  Update `sdks/python/pyproject.toml` version.
+3.  Update `sdks/typescript/package.json` version.
+4.  Regenerate SDKs: `npm run generate:sdk:all`.
+5.  Commit and tag.
 
 ## Future: Native Bindings (v2.0.0)
 
 Eventually, we'll move to native bindings (Rust + FFI) to eliminate the sidecar dependency. But for v1.0.0, the sidecar approach lets us move fast and support many languages with minimal effort.
 
 ## Questions?
 
-See the main [ROADMAP.md](../../ROADMAP.md) for the overall project vision.
+See the main [ROADMAP.md](../ROADMAP.md) for the overall project vision.

sdks/SDK_DEVELOPMENT.md

@@ -0,0 +1,30 @@
+# Dependencies
+node_modules/
+package-lock.json
+
+# Build output
+dist/
+*.tsbuildinfo
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+
+# Testing
+coverage/
+.nyc_output/
+
+# Environment
+.env
+.env.local

sdks/typescript/.gitignore

@@ -0,0 +1 @@
+README.md

sdks/typescript/.npmignore

@@ -0,0 +1,23 @@
+# OpenAPI Generator Ignore
+# Generated by openapi-generator https://github.com/openapitools/openapi-generator
+
+# Use this file to prevent files from being overwritten by the generator.
+# The patterns follow closely to .gitignore or .dockerignore.
+
+# As an example, the C# client generator defines ApiClient.cs.
+# You can make changes and tell OpenAPI Generator to ignore just this file by uncommenting the following line:
+#ApiClient.cs
+
+# You can match any string of characters against a directory, file or extension with a single asterisk (*):
+#foo/*/qux
+# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux
+
+# You can recursively match patterns against a directory, file or extension with a double asterisk (**):
+#foo/**/qux
+# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux
+
+# You can also negate patterns with an exclamation (!).
+# For example, you can ignore all files in a docs folder with the file extension .md:
+#docs/*.md
+# Then explicitly reverse the ignore rule for a single file:
+#!docs/README.md