[nbsp1221]

Summary

Adds the initial TypeScript implementation for the Toss Securities OpenAPI SDK.

This PR introduces:

• generated TypeScript contract types from the pinned OpenAPI spec
• a fetch-based TossInvestClient with flat methods for all pinned operation IDs
• OAuth2 client-credentials token issuance, in-memory caching, expiry handling, and in-flight token coalescing
• unwrapped business API result responses by default, with { withResponse: true } for raw envelope and HTTP metadata access
• predictable API and connection error classes
• request timeout support with client-level and per-call overrides
• TypeScript package README and npm metadata for the public package shape

Scope

Included:

• TypeScript SDK package implementation
• generated OpenAPI type drift check
• unit tests for exports, auth, HTTP helpers, errors, and client request mapping/response behavior
• docs for authentication, response shape, order usage, timeout, errors, and pagination policy
• npm package dry-run validation

Not included:

• Python SDK implementation
• npm publishing or release automation
• retry/backoff, runtime response validation, or auto-pagination helpers

Validation

Fresh validation after PR QA updates:

mise run check
pnpm --dir packages/typescript pack --dry-run

Result:

• OpenAPI spec check passed: 1.1.1, 20 paths
• TypeScript format, lint, typecheck, test, and build passed
• TypeScript tests: 6 files, 37 tests passed
• Python lint, typecheck, test, and build passed
• TypeScript package dry-run includes dist/index.js, dist/index.js.map, dist/index.d.ts, package.json, and README.md

Testnet Order QA

The SDK was also exercised against Toss OpenAPI credentials that the user confirmed were configured for testnet/mock trading.

Successful flow covered:

• OAuth token issuance
• account, holdings, open orders, buying power, orderbook, price limit, price, stock warning, commission, and sellable quantity APIs
• KR limit order create/modify/cancel using 035720
• KR buy filled then sell filled using 035720
• US buy filled then sell filled using PFE
• final open order count: 0
• final target holdings: []

A first run using 252670 failed with 422 prerequisite-required because that instrument requires prior education. The SDK correctly surfaced the failure as TossInvestApiError with status, code, requestId, and body, so this was treated as an instrument eligibility issue rather than an SDK defect.

Raw QA artifacts are intentionally left under /tmp/tossinvest-live-order-qa and are not committed because they contain temporary account/order details.

Review Notes

• Endpoint surface coverage is 100% against the repository-pinned OpenAPI spec: 21/21 operation IDs including issueOAuth2Token, or 20/20 business API operations.
• Generated OpenAPI types are excluded from Prettier and ESLint so generator output remains the canonical source for openapi-typescript --check.
• The package intentionally does not choose an open-source license in this PR. A license decision is still required before public release.
• This is intentionally a draft PR for review of API shape, safety boundaries, and merge readiness.