SDK Architecture & Design

Structure

• src/types.ts: All shared types, Zod schemas, and type guards.
• src/shared/: Helpers for auth, validation, and cross-env logic.
• src/browser/: Browser-specific client and upload logic.
• src/server/: Node.js-specific client and upload logic.

Dual Entrypoint Pattern

• The SDK exposes separate entrypoints for browser and Node.js via package exports.
• Top-level index.ts and server.ts re-export from their respective environment directories.

Zod & OpenAPI Integration

• All input/output schemas are defined with Zod for type safety and runtime validation.
• The same Zod schemas are used for OpenAPI documentation (see /apps/imagineoai-api/docs/openapi-integration.md).
• This ensures that API docs and validation are always in sync.

Shared Logic

• Auth and validation logic is DRY and shared via helpers in src/shared/.
• All error shapes and types are unified.

Extensibility

• Add new endpoints by creating new methods in both browser and server clients, using shared types.
• For new file types or auth methods, update types and helpers in one place.

Testing & Linting

• Linting via ESLint.
• Type checking with TypeScript strict mode.
• Write tests for both environments as features are added.