@gleanfeed/sdk is the typed server-side client for the public /api/v1
contract. Use it when trusted JavaScript or TypeScript code needs in-process
feedback, roadmap, changelog, workspace, tag, comment, pagination, timeout, and
error handling.
API keys are server credentials. The SDK refuses to initialize in a browser by default. Never put
a key in a public bundle, mobile app, client component, or NEXT_PUBLIC_... variable.
Requirements and install
- Node.js 20 or later, or a server/edge runtime with standards-compatible
fetch, Headers, URL, AbortController, and Response globals.
- A workspace API key with the scopes required by each operation.
Read feedback
Async iterators follow opaque cursors without loading an unbounded workspace into
memory. The API key determines the workspace; the SDK does not accept a workspace
override.
Create feedback safely
Use a stable source.externalId when the same external record can be delivered
again. Source metadata is private triage context, but it must not contain
credentials, raw connector payloads, unnecessary personal data, or message
history. Use a stable idempotency key when a separate process may retry the same
logical create.
Handle errors, timeouts, and cancellation
Pass an AbortSignal to any operation. API failures expose the HTTP status,
stable error code, optional safe details, and retry interval where applicable.
Compatibility and versions
The SDK ships ESM and TypeScript declarations. Its major version tracks breaking
SDK interface changes. It targets /api/v1 and is contract-tested against the
OpenAPI reference; additive v1 response fields do not require
an SDK major release. A future /api/v2 will require explicit SDK support rather
than silently changing this package’s base path.
Pin an exact version for controlled production rollouts, or use a compatible
range when additive SDK releases are acceptable. Verify the package publisher,
repository, version, and changelog before upgrading.
Use the Headless SDK guides for customer-facing UI patterns,
the widget package for a ready-made browser
interface, or the CLI for repository and terminal workflows.