docs: Adding llm file for AI and scaffold claude folder

.claude/CLAUDE.md

@@ -0,0 +1,96 @@
+# DXtrade API
+
+Unofficial TypeScript client for the DXtrade trading API.
+
+## Commands
+
+- `npm run build` — Build the project (tsup)
+- `npm run dev` — Build in watch mode
+- `npm test` — Run tests once (vitest)
+- `npm run test:watch` — Run tests in watch mode
+- `npm run lint` — Lint source and examples
+- `npm run lint:fix` — Lint and auto-fix
+- `npm run format` — Format with prettier
+- `npm run format:check` — Check formatting
+- `npm run commit` — Commit using commitizen (required — `git commit` is disabled via pre-commit hook)
+
+## Project Structure
+
+```
+src/
+├── client.ts              # Main DxtradeClient class — delegates to domain functions
+├── client.types.ts        # Config, callbacks, and context types
+├── constants/             # Enums, broker URLs, endpoints, errors
+├── domains/               # Feature modules (one folder per domain)
+│   ├── {domain}/
+│   │   ├── {domain}.ts        # Implementation
+│   │   ├── {domain}.types.ts  # Types (namespace pattern)
+│   │   └── index.ts           # Barrel exports
+│   └── index.ts           # Re-exports all domains
+└── utils/                 # Helpers (websocket, cookies, headers, retry)
+tests/                     # Unit tests (vitest)
+examples/                  # Runnable example scripts
+```
+
+## Path Aliases
+
+`@/*` maps to `src/*` — configured in tsconfig.json, tsup.config.ts, and vitest.config.ts.
+
+## Code Style
+
+- **Quotes**: Double quotes
+- **Semicolons**: Always
+- **Trailing commas**: Always
+- **Print width**: 120 characters
+- **Indent**: 2 spaces
+- **Naming**: camelCase (functions/vars), PascalCase (classes/types/interfaces), SCREAMING_SNAKE_CASE (enum values)
+- **Private fields**: Underscore prefix (`_ctx`)
+- **Imports**: Named imports, `import type` for type-only imports, `@/` path alias for src
+- **Types**: Namespace pattern for domain types (`Order.SubmitParams`, `Symbol.Info`), `interface` for objects, `type` for unions
+- **Async**: async/await, Promise wrappers for WebSocket operations with timeout + cleanup
+- **Error handling**: Custom `DxtradeError` class, try-catch with `error: unknown` type guards
+- **Nullish coalescing**: `??` over `||` for defaults
+
+## Domain Pattern
+
+When adding a new domain:
+1. Create `src/domains/{name}/{name}.ts` — implementation functions that take `ClientContext` as first param
+2. Create `src/domains/{name}/{name}.types.ts` — types using namespace pattern
+3. Create `src/domains/{name}/index.ts` — barrel exports
+4. Re-export from `src/domains/index.ts`
+5. Add public method(s) to `src/client.ts` with JSDoc comment
+
+## Example Pattern
+
+```typescript
+import "dotenv/config";
+import { DxtradeClient, BROKER } from "../src";
+
+const client = new DxtradeClient({
+  username: process.env.DXTRADE_USERNAME!,
+  password: process.env.DXTRADE_PASSWORD!,
+  broker: process.env.DXTRADE_BROKER! || BROKER.FTMO,
+  accountId: process.env.DXTRADE_ACCOUNT_ID,
+  debug: process.env.DXTRADE_DEBUG || false,
+});
+
+(async () => {
+  await client.connect();
+  // ...
+})().catch(console.error);
+```
+
+## Rules
+
+### When adding or removing a feature:
+1. Update `README.md` — Features checklist, API section, and Examples section
+2. Update `llms.txt` — Keep the LLM reference in sync with the actual API
+3. Add JSDoc comment to any new public method in `src/client.ts`
+4. Add an example script in `examples/` if the feature is user-facing
+5. Add a corresponding npm script in package.json
+6. Add or update tests in `tests/`
+
+### General:
+- Do not commit with `git commit` directly — use `npm run commit`
+- Run `npm run lint` and `npm test` before committing
+- Follow the existing domain pattern for new features

.claude/skills/broker.md

@@ -0,0 +1,24 @@
+# Broker
+
+Guide for adding, modifying, or removing a broker.
+
+## Adding a broker
+
+1. Add the broker URL to `src/constants/brokers.ts` in the `BROKER` object
+2. Update `README.md`: Built-in Brokers section
+3. Update `llms.txt`: Enums section (BROKER list)
+4. Add a test for the new broker URL in `tests/constants.test.ts`
+
+## Modifying a broker
+
+1. Update the URL in `src/constants/brokers.ts`
+2. Update `README.md`: Built-in Brokers section
+3. Update `llms.txt`: Enums section (BROKER list)
+4. Update the test in `tests/constants.test.ts`
+
+## Removing a broker
+
+1. Remove the entry from `src/constants/brokers.ts`
+2. Update `README.md`: Built-in Brokers section
+3. Update `llms.txt`: Enums section (BROKER list)
+4. Remove the test from `tests/constants.test.ts`

.claude/skills/domain.md

@@ -0,0 +1,43 @@
+# Domain
+
+Guide for adding, modifying, or removing a domain module.
+
+## Adding a domain
+
+1. Create the domain folder: `src/domains/{name}/`
+2. Create `{name}.types.ts` with namespace pattern:
+   ```typescript
+   export namespace {Name} {
+     export interface ... { }
+   }
+   ```
+3. Create `{name}.ts` with implementation functions that take `ClientContext` as first param
+4. Create `index.ts` with barrel exports
+5. Re-export from `src/domains/index.ts`
+6. Add public method(s) to `src/client.ts` with JSDoc comment
+7. Add example script in `examples/`
+8. Add npm script in package.json for the example
+9. Add unit test in `tests/`
+10. Update `README.md`: Features checklist, API section, Examples section
+11. Update `llms.txt` with the new method(s)
+
+## Modifying a domain
+
+1. Update the implementation in `src/domains/{name}/{name}.ts`
+2. Update types in `src/domains/{name}/{name}.types.ts` if signatures changed
+3. Update the public method(s) and JSDoc in `src/client.ts`
+4. Update the example script in `examples/`
+5. Update or add tests in `tests/`
+6. Update `README.md`: Features checklist, API section, Examples section
+7. Update `llms.txt` to reflect the current API
+
+## Removing a domain
+
+1. Delete the domain folder: `src/domains/{name}/`
+2. Remove the re-export from `src/domains/index.ts`
+3. Remove the public method(s) and import from `src/client.ts`
+4. Delete the example script from `examples/`
+5. Remove the npm script from package.json
+6. Remove or update tests in `tests/`
+7. Update `README.md`: Features checklist, API section, Examples section
+8. Update `llms.txt` to remove the method(s)

.claude/skills/release.md

@@ -0,0 +1,19 @@
+# Release
+
+Publishing is automated. When a PR is squash-merged to master, the publish workflow:
+
+1. Bumps the patch version in package.json
+2. Publishes to npm with OIDC provenance
+3. Creates a GitHub Release with auto-generated notes
+
+## Manual version bumps
+
+For minor or major releases, bump the version locally before merging:
+
+```bash
+npm version minor --no-git-tag-version
+# or
+npm version major --no-git-tag-version
+```
+
+Then commit the version change and merge the PR. The workflow will skip the auto-bump if the version already changed.

.claude/skills/testing.md

@@ -0,0 +1,11 @@
+# Testing
+
+> **Note:** Testing patterns still need to be thought out. Update this file as conventions are established.
+
+## Setup
+
+- Framework: vitest
+- Config: `vitest.config.ts`
+- Test location: `tests/`
+- Run once: `npm test`
+- Watch mode: `npm run test:watch`

README.md

@@ -4,11 +4,17 @@
 [![npm downloads](https://img.shields.io/npm/dm/@danielgroen/dxtrade-api)](https://www.npmjs.com/package/@danielgroen/dxtrade-api)
 [![license](https://img.shields.io/npm/l/@danielgroen/dxtrade-api)](LICENSE)
 [![Tests](https://github.com/danielgroen/dxtrade-api/actions/workflows/tests.yml/badge.svg)](https://github.com/danielgroen/dxtrade-api/actions/workflows/tests.yml)
-[![Publish to npm](https://github.com/danielgroen/dxtrade-api/actions/workflows/publish.yml/badge.svg)](https://github.com/danielgroen/dxtrade-api/actions/workflows/publish.yml)
+[![Publish](https://github.com/danielgroen/dxtrade-api/actions/workflows/publish.yml/badge.svg)](https://github.com/danielgroen/dxtrade-api/actions/workflows/publish.yml)
 
 [![DXtrade API](https://raw.githubusercontent.com/danielgroen/dxtrade-api/master/public/logo-dxtrade.svg)](https://demo.dx.trade/developers/#/)
 
-TypeScript client library for the DXtrade trading API based upon Nodejs.
+Unofficial TypeScript client for the DXtrade trading API. Connect, trade, and manage positions on any broker that supports DXtrade.
+
+## Install
+
+```bash
+npm install dxtrade-api
+```
 
 ## Features
 
@@ -25,12 +31,6 @@ TypeScript client library for the DXtrade trading API based upon Nodejs.
 - [ ] Real-time price streaming
 - [ ] Order history
 
-## Install
-
-```bash
-npm install dxtrade-api
-```
-
 ## Quick Start
 
 ```ts

llms.txt

@@ -0,0 +1,79 @@
+# DXtrade API
+
+Unofficial TypeScript client for the DXtrade trading API.
+Connect, trade, and manage positions on any broker that supports DXtrade.
+
+## Installation
+
+npm install dxtrade-api
+
+## Quick Start
+
+import { DxtradeClient, ORDER_TYPE, SIDE, BROKER } from "dxtrade-api";
+
+const client = new DxtradeClient({
+  username: "your_username",
+  password: "your_password",
+  broker: BROKER.FTMO,
+  accountId: "optional_account_id",
+});
+
+await client.connect();
+
+## Available Methods
+
+### Session
+- client.connect() — Login, fetch CSRF, WebSocket handshake, optional account switch. Call this first.
+- client.login() — Authenticate with broker (called automatically by connect)
+- client.fetchCsrf() — Fetch CSRF token (called automatically by connect)
+- client.switchAccount(accountId: string) — Switch to a specific trading account
+
+### Market Data
+- client.getSymbolSuggestions(text: string) — Search symbols by name, returns Symbol.Suggestion[]
+- client.getSymbolInfo(symbol: string) — Get instrument info (volume limits, lot size), returns Symbol.Info
+- client.getSymbolLimits() — Get order size limits for all symbols, returns Symbol.Limits[]
+- client.getInstruments(params?: Partial<Instrument.Info>) — Get all instruments, optionally filtered (e.g. { type: "FOREX" })
+
+### Trading
+- client.submitOrder(params: Order.SubmitParams) — Submit order and wait for WebSocket confirmation, returns Order.Update
+  Required params: symbol, side (SIDE.BUY | SIDE.SELL), quantity, orderType (ORDER_TYPE.MARKET | LIMIT | STOP), instrumentId
+  Optional params: limitPrice, stopPrice, stopLoss, takeProfit, timeInForce (TIF.GTC | DAY | GTD)
+
+### Positions
+- client.getPositions() — Get all open positions via WebSocket, returns Position.Get[]
+- client.closePosition(params: Position.Close) — Close a position
+
+### Account
+- client.getAccountMetrics() — Get equity, balance, margin, open P&L, returns Account.Metrics
+- client.getTradeJournal({ from: number, to: number }) — Fetch trade journal for date range (Unix timestamps)
+
+### Analytics
+- client.getAssessments(params: Assessments.Params) — Fetch PnL assessments for a date range
+
+## Enums
+
+import { ORDER_TYPE, SIDE, ACTION, TIF, BROKER } from "dxtrade-api";
+
+ORDER_TYPE: MARKET, LIMIT, STOP
+SIDE: BUY, SELL
+ACTION: OPENING, CLOSING
+TIF: GTC, DAY, GTD
+BROKER: LARKFUNDING, EIGHTCAP, FTMO
+
+## Callbacks
+
+const client = new DxtradeClient({
+  ...config,
+  callbacks: {
+    onLogin: () => {},
+    onAccountSwitch: (accountId: string) => {},
+    onOrderPlaced: (order: Order.Response) => {},
+    onOrderUpdate: (order: Order.Update) => {},
+    onError: (error: DxtradeError) => {},
+  },
+});
+
+## Error Handling
+
+All errors are instances of DxtradeError with properties: code (string) and message (string).
+Common error codes: NO_SESSION, ORDER_TIMEOUT, ORDER_ERROR, POSITION_CLOSE_ERROR.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielgroen/dxtrade-api",
   "version": "1.0.18",
-  "description": "DXtrade trading API client library",
+  "description": "Unofficial TypeScript client for the DXtrade trading API. Connect, trade, and manage positions on any broker that supports DXtrade.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -13,7 +13,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "llms.txt"
   ],
   "scripts": {
     "================ Build ===============": "",