docs: add README#15
Merged
Merged
Conversation
The npm registry page for @devhelm/sdk has been blank since publication (`npm view @devhelm/sdk readme` → "No README data found"). Customers landing on https://www.npmjs.com/package/@devhelm/sdk see only the package metadata, with no quickstart, API surface, error model, or TypeScript usage notes — a poor first impression for a developer artifact. Mirrors the structure of sdk-python's README (which does ship to PyPI and renders correctly): - Installation - Quick Start (matches sdk-python's create/get/pause/resume/delete flow) - Configuration (constructor + env-var fallbacks) - Resources table (one row per `client.<resource>` module) - Pagination (auto vs manual page vs cursor) - Error Handling (DevhelmAuthError / NotFound / Conflict / RateLimit / Server / Validation / Transport) - TypeScript section calling out the re-exported DTO types - Compatibility (Node 18+, browser bundlers, CF Workers) - License Notes the surface telemetry headers (X-DevHelm-Surface: sdk-js + X-DevHelm-Surface-Version) so users understand version-EOL behavior. The Quick Start example uses `managedBy: 'CLI'` — which matches the field's IaC-drift semantic for SDK callers who script reconciliation. A non-`managedBy` value would also work for one-off imperative scripts; this is the safer default for example code that gets copy-pasted into CI/automation. Co-authored-by: Cursor <cursoragent@cursor.com>
DASHBOARD is the more honest default for SDK callers: an SDK call from a one-off script is morally an imperative API call (no reconciliation), just from code instead of from the dashboard UI. The previous CLI value would lie about IaC ownership and trigger a misleading 'managed by CLI, edit in code' banner in the dashboard for monitors that have no actual reconciliation loop. Adds a short inline comment so users understand the field's semantic and can override it for their use case. Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The npm registry page for `@devhelm/sdk` has been blank since publication (`npm view @devhelm/sdk readme` → `No README data found`). Customers landing on https://www.npmjs.com/package/@devhelm/sdk see only the package metadata — no quickstart, no API surface, no error model, no TypeScript notes.
This PR adds a README that mirrors the structure of the sdk-python README (which already ships to PyPI and renders correctly):
Notes the surface telemetry headers (`X-DevHelm-Surface: sdk-js` + `X-DevHelm-Surface-Version`) so users understand version-EOL behavior.
A note on the `managedBy` field in the example
The Quick Start example uses `managedBy: 'DASHBOARD'` with a short inline comment. This is the more honest default for SDK callers: an SDK call from a script is morally an imperative API call (no reconciliation), just from code instead of from the dashboard UI. Users who script reconciliation can override with `'CLI'` or `'TERRAFORM'`.
Test plan
Made with Cursor