| name | sdk-implement |
| description | Implement an SDK against a versioned spec. Use when sdk-bootstrap dispatches to Phase 5 — read the spec from specs/<type>/SPEC.md, implement per requirements, validate, and package. Takes SDK type (product-analytics, lakehouse) as input. |
Implement SDK
Dispatched by sdk-bootstrap Phase 5. Read the spec from the SDK repo's specs/ submodule, implement, validate, and package.
Rules: specs · contribution · quality
Spec Mapping
| SDK type | Spec path | Additional files |
|---|
lakehouse | specs/lakehouse/SPEC.md | — |
product-analytics | specs/product-analytics/SPEC.md | specs/product-analytics/CONSTANTS.md, specs/product-analytics/TEST_PLAN.md, specs/product-analytics/fixtures/*.json |
For HTTP transport requirements (keep-alive, timeouts, language recommendations), read specs/http/SPEC.md — both lakehouse and product-analytics specs reference it.
Workflow
0. Impact analysis (before writing any code)
Produce a short written summary — in the PR body or a local scratch file — covering:
- Which public API methods are added, changed, or removed
- Which existing tests need updating
- Which docs sections are affected
- Whether this change applies to other SDKs in the same category (if so, note which ones and whether they're already handled)
Do not skip this step. It forces you to understand the scope before committing to an implementation path.
1. Read the spec
Read specs/<type>/SPEC.md. Treat it as the source of truth. If anything in the spec is ambiguous, note it explicitly in the PR — do not silently assume an interpretation.
2. Scaffold
Per the spec's first phases (package structure, license, lint/test scripts).
3. Implement
Each requirement phase in order. Do not skip phases applicable to the target tier (web/mobile/server for product-analytics).
4. Test — happy path and failure cases
For every behavior you implement, write:
- A test that proves it works correctly (happy path)
- A test for at least one failure case: invalid input, disabled feature, network error, or storage unavailable
Fixture compliance for product-analytics: run all fixtures in specs/product-analytics/fixtures/ through the serializer and assert exact output match.
5. Cross-SDK consistency check
After implementing, compare the public API surface against at least one existing SDK of the same type:
- Method names (language-idiomatic, but semantically equivalent)
- Config option names and defaults (must match
specs/product-analytics/CONSTANTS.md or specs/lakehouse/SPEC.md)
- Error handling behavior
Flag any divergence as a follow-up issue with the cross-sdk-divergence label — don't fix other SDKs in the same PR, but don't ignore the gap either. Routine-maintainer will check these issues periodically to see if they've been resolved by a subsequent PR.
6. Validate before opening PR
7. Package
Run in this order:
- Apply release conventions per sdk-release (versioning, changelog, registry metadata)
- Generate README per sdk-readme
Spec update (not initial bootstrap): use git -C specs diff <old-tag>..<new-tag> -- . to identify changes. Only implement what is new or modified. Document breaking changes in CHANGELOG.md.
When Things Go Wrong
OpenAPI spec unavailable
If the OpenAPI URL cannot be fetched (timeout, 404):
- Product Analytics: Read the OpenAPI URL from
specs/product-analytics/SPEC.md (it is documented there). If it cannot be fetched, use the reference JS implementation's types as the source of truth. Document which spec version you based the models on.
- Lakehouse: Use the endpoint reference in
specs/lakehouse/SPEC.md as the source of truth.
Missing platform APIs
Some platforms lack certain APIs (crypto.randomUUID, navigator.sendBeacon, etc.). Always provide a polyfill or fallback:
- UUID generation: Fall back to a manual v4 UUID implementation.
- Beacon transport: Fall back to
fetch with keepalive: true, then plain fetch.
- Storage APIs: Follow the fallback chain in the spec. If all fail, use in-memory storage.
Streaming parse failures (Lakehouse)
If NDJSON streaming produces unexpected line formats, fail loudly with line index and raw content in the error. Never silently drop rows.
Tests cannot run
Integration tests use the mock server and require no live credentials. If blocked (e.g., Docker unavailable, missing Testcontainers bindings), skip with a clear TODO and a logged warning. Document what is skipped and why in the PR description. Do not silently omit test coverage.
Notes
- Monorepo exception: Product Analytics web framework wrappers (React, Vue, Svelte) live in
altertable-js under packages/. Work directly in the monorepo — sdk-bootstrap handles this before dispatching here, but be aware the repo structure differs.
