TypeScript SDK

Free — GPL coresize Lplanned, not built

Generated from docs/plan/core/typescript-sdk/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A TypeScript-native client library with full type definitions generated from the OpenAPI schema. Provides autocomplete, type safety, builder patterns for queries, and discriminated error types. A zero-cost abstraction over the JavaScript SDK.

The problem

TypeScript developers lack autocomplete for API queries; they lose static type checking and must manually define response types or cast to any. Storefront teams write fetch() calls with inline type casts, defeating TypeScript’s safety benefits and slowing development.

What it does

• Auto-generated TypeScript types for all API resources (Product, Order, Customer, Category, etc.) from OpenAPI schema
• Generic type parameters for custom fields with runtime validation (merchant-defined fields are type-safe)
• Fluent builder/chainable API for complex queries (filters, sorting, pagination, field selection)
• Typed error responses using discriminated unions (catch blocks can branch on error.type === ‘NOT_FOUND’ etc)
• Async/await throughout; no callback-style or Promise chaining boilerplate
• Type-safe webhook signature verification with ed25519 key validation
• ESM-only build (no CommonJS; TypeScript users expect modern bundlers)
• TypeScript 4.8+ strict mode compatibility (zero any types leaked to users)
• Runtime validation using Zod or io-ts (validates untrusted API responses against schemas)
• Typed plugin hook responses if plugins export type definitions

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Automatic query optimization or smart batching — caching and request batching are the app’s responsibility; SDK is thin
• GraphQL schema generation or support — REST is the honest interface; GraphQL is a paid architectural decision
• ORM features (lazy loading, relationship traversal, migrations) — SDK is a thin REST client, not a database abstraction layer
• React hooks (useProduct, useWishlist, etc.) — framework-specific hooks belong in product-card-component, not the core SDK
• Custom tree-shaking configuration — SDK ships one minified .js file; bundlers tree-shake automatically
• Automatic retry strategies on network errors — error handling is app-specific; SDK signals errors cleanly and lets app decide

Data model

none

API

• No new routes. Wraps existing REST API; may add optional OpenAPI x-typescript fields for SDK hints (e.g., x-typeOverride)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

TypeScript SDK reference docs and integration examples in admin portal. Link to OpenAPI schema for reference. Nothing new for merchant to configure; SDK is developer infrastructure.

The seam — why this is core

Core owns the TypeScript SDK, type generation, builder patterns, error discriminated unions, Zod validation schemas, and all documentation. Paid pack owns nothing; type safety is infrastructure, not a per-country obligation or credential.

Core owns the interface + honest TypeScript SDK; developer tools are infrastructure, not a per-country obligation or credential.

Dependencies

• JavaScript SDK (core; TypeScript SDK wraps or extends it)
• OpenAPI document (core; used for type generation and validation schema extraction)
• TypeScript 4.8+ toolchain (external; customer provides)
• Zod 3.20+ for runtime validation (vendored or peer dependency)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• TypeScript developer writes sdk.products().filter({price: {lt: 5000}}).limit(10) and gets full type inference; hovering shows exact return type
• Fetching a product list returns ProductResponse type automatically; fields are narrowed and no casting needed
• Custom fields (merchant-defined) are inferred from OpenAPI x-customFields; hovering shows their exact types
• A 404 error response is caught as error.type === ‘NOT_FOUND’ (discriminated union); TypeScript enforces handling all error types
• Webhook signature verification rejects unsigned payloads at compile time (Zod throws, caught as error)
• SDK passes full test suite on TypeScript 4.8, 5.0, 5.1 without regressions or version-specific workarounds
• Tree-shaking unused imports results in zero JavaScript emissions (types-only re-exports are removed by bundlers)
• Zod validation schema matches OpenAPI spec exactly: fields marked required in OpenAPI are required by Zod; optional fields can be undefined

Risks

If OpenAPI schema changes, generated TypeScript types regenerate; old builds with old types become stale (version mismatch). If a custom field is marked as unknown or any, TypeScript users cannot narrow it further (breaks type safety). If a new error type is added to the API, old TypeScript code won’t be forced to handle it (exhaustiveness check fails). If the Zod schema is hand-coded incorrectly, runtime values won’t match compile-time types (needs property-based testing).

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.