JavaScript SDK

Free — GPL coresize Lplanned, not built

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

A JavaScript client library for the AstroBaaS REST API, with request signing, pagination, error handling, and dual auth modes (cookies and API keys). Lets developers build storefronts without reinventing HTTP mechanics.

The problem

Developers manually construct HTTP requests to the AstroBaaS API; they waste time implementing request signing for API keys, CSRF token handling in browsers, pagination wrappers, and consistent error parsing. Each storefront team rebuilds the same primitives, slowing launches.

What it does

• Dual auth modes: cookie-based (browser, automatic) and bearer-key-based (server-to-server) with HMAC signing
• CSRF token injection for browser POST requests (reads from response headers and includes in subsequent requests)
• Cursor-based and offset-based pagination helpers with automatic link following
• Automatic retry logic for transient errors (5xx, timeouts) with exponential backoff
• Consistent error parsing with error codes and merchant-friendly messages
• Request/response logging with automatic redaction of API keys and secrets
• Timeout and AbortSignal support for long operations
• Form-data upload support for file fields (multipart/form-data handling)
• Mock/test mode with recorded response playback for offline testing
• Dual-build ESM and CommonJS outputs for maximum compatibility
• OpenAPI schema introspection for runtime type validation hints

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.

• GraphQL support — REST is the honest interface; GraphQL is a paid layer decision, not core
• WebSocket subscriptions or real-time push — webhooks are the async event model; live streams require support commitment
• Custom HTTP transport layers (HTTP/2, gRPC) — HTTP/1.1 REST only; advanced transports need support infrastructure
• Automatic retry on 429 rate-limiting — merchant’s infrastructure is their concern; SDK respects headers but doesn’t retry
• Offline sync queue or persistent request buffering — requires device storage; SDK is stateless, app owns persistence
• Automatic API key refresh or token rotation — no secret handling beyond per-request signing; merchant regenerates keys

Data model

none

API

• No new routes. SDK wraps existing REST API; may document x-javascript-sdk OpenAPI extensions for SDK hints (optional)

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

Admin

SDK reference docs and usage examples in admin portal, generated from OpenAPI. API key creation UI already exists. Nothing new for merchant to configure; SDK is developer-facing infrastructure.

The seam — why this is core

Core owns the SDK interface, dual-mode auth implementation, pagination, retries, error parsing, and all documentation. Paid pack owns nothing; SDKs are developer infrastructure, not credentials or country-specific obligations.

Core owns the interface + honest SDK implementation; developer tools are infrastructure, not a credential or support commitment.

Dependencies

• REST API (core; already exists)
• OpenAPI document (core; already exists)
• Authentication system with API keys and CSRF tokens (core; already exists)

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.

• JavaScript developer fetches a paginated product list using the SDK without calling fetch() directly; SDK handles signing and pagination
• API key requests are signed correctly with HMAC-SHA256; merchant can verify signature matches the OpenAPI specification
• Cookie-mode requests in a browser automatically inject CSRF tokens without explicit SDK configuration
• A 401 error response raises a clear, actionable error message (e.g., ‘Invalid API key’) not a cryptic raw JSON error
• Timeouts fail fast in under 5 seconds and trigger automatic retry on 5xx errors up to 3 attempts
• SDK runs on Node.js 18+, modern browsers (ES2020+), and works with both CommonJS and ESM imports
• Form data uploads (e.g., product image) are handled transparently by the SDK without manual multipart assembly
• Pagination cursor is opaque and never decoded by the SDK user; next-page links are simple strings, not objects

Risks

If SDK and API disagree on the HMAC algorithm, all key-authenticated requests fail silently with 401 (needs clear error). If CSRF token header name changes, POST requests fail only in browsers (server-to-server works). If error response format changes, SDK breaks and cannot parse; tests must verify every error code format. If pagination cursor format is not preserved, cursor-based pagination fails and loops endlessly.

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.