How ozmap/ozmap-sdk works
Project type and purpose
• This is a TypeScript-based SDK (an open-source client library) for interacting with the OZmap REST API. Its sole purpose is to provide a high-level, strongly-typed interface (CRUD, batch ops, filtering, pagination) to OZmap’s georeferenced data services.
File structure
Top-level:
• config files (.eslintrc, tsconfig.json, tsup.config.ts, GitHub workflows, Husky hooks)
• docs/ (one Markdown file per model for user reference)
• src/
– OZMapSDK.ts (the main SDK façade exposed to consumers)
– index.ts (public export)
– util/Api.ts (generic HTTP client wrapper)
– interface/ (TypeScript interfaces/DTOs for requests, responses, filter/pagination)
– proxy/
• Proxy.ts, ReadableProxy.ts, UpdatableProxy.ts, WritableProxy.ts (generic proxy classes encapsulating CRUD patterns)
• entities/ (one class per model that maps raw API JSON to a richer entity object)
Build & packaging: tsup, package.json, package-lock.json.
README for additional insights
• States features (CRUD, batch, pagination, filter) and usage examples.
• Shows two instantiation modes (login/password or API key).
• Describes direct-API methods via sdk.apiInstance.
How to model this
a. Main components
1. Client Application (TypeScript consumer code)
2. SDK Facade (OZMapSDK class)
3. HTTP Client Layer (util/Api.ts)
4. Proxy Layer (generic Proxy classes)
5. Entity Layer (proxy/entities/*)
6. Interface Layer (interface/model DTOs + filter/pagination)
7. External OZmap REST API
8. Build & Config (tsup, tsconfig, linters, CI workflows)
9. Documentation (docs/)
b. Relationships & interactions
• Client calls methods on OZMapSDK →
• internally selects correct Proxy (ReadableProxy, UpdatableProxy, etc.) →
• Proxy uses Api.ts to send HTTP requests to External OZmap API →
• API returns JSON →
• Api.ts hands raw JSON back to Proxy →
• Proxy instantiates Entities (mapping JSON to class instances) →
• SDK returns Entities or DTOs back to Client
• Build & Config sit aside to package and enforce code quality; docs/ support user understanding.
c. Architectural patterns & design principles
• Façade (OZMapSDK hides complexity)
• Proxy (abstracts remote calls behind common CRUD interfaces)
• Adapter/Mapper (entities map raw JSON to rich objects)
• Layered separation (interface → proxy → util → external service)
• Single Responsibility (each folder/class has one concern)
d. Key technologies/frameworks
• TypeScript (static typing, interfaces, generics)
• axios or fetch (inside util/Api.ts)
• tsup (build/bundle)
• ESLint, Prettier, Husky (quality & automation)
• GitHub Actions (CI for tests & publishing)
Detail & coverage
• Data-flow paths for all CRUD operations and for direct apiInstance calls.
• Do not omit the docs/ folder or CI config—they are essential for an open-source project.