Implement the Gradient Labs Node.js / TypeScript client#1
Merged
Conversation
Full client for the public Gradient Labs API per nodejs_CLIENT_PLAN.md: - Resource-namespaced API (client.conversations.start, client.tools.list, ...) covering all Integration and Management endpoints in the OpenAPI spec. - Zero runtime dependencies: built-in fetch + node:crypto. - Typed error hierarchy (GradientLabsError / ConfigurationError / ApiError) with traceId helper and typed ErrorCode constants. - Open string enums sourced from the Go source. - Cursor pagination with Page<T> + listAll() async iterators. - WebhookVerifier: HMAC-SHA256 signature + leeway check, constant-time compare, typed discriminated-union events, X-GradientLabs-Token passthrough. - 36 offline tests (webhook, errors, http, types), examples for 7 groups, dual ESM/CJS build via tsup, CI + publish workflows. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…end review
Cross-checked against the Go backend webhook publishers and request validators:
- Webhooks: back-office events carry the full task under a single
'back_office_task' key (was a wrong '{task, ...siblings}' shape); the three
back-office events now reuse the full BackOfficeTask model.
- Webhooks: split conversation payload types — agent.message/hand_off/finished
carry {id, customer_id} only (no metadata); action.execute/resource.pull use
ActionWebhookConversation ({id, customer_id, customer_source, metadata}) and an
optional back_office_task ref; both are optional. Added last_customer_message_id
to AgentMessageEvent.
- Required fields: ReturnAsyncToolResultParams.payload and
CreateBackOfficeTaskParams.agent_id are required server-side (validation.Required).
- Optional fields: ResumeConversationParams.resources, Attachment.summary/
description, and ProcedureVersion.GatedConfig are optional/nullable in the API.
- Tests: added pagination.test.ts (paginate + procedures.listAll) and corrected
the webhook event fixtures to the real shapes. 40 tests pass.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
agent_id is an ordinary parameter (e.g. "boagent_12345"), not an environment concern; use a literal placeholder in the example. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The npm organization is 'gradientlabs', so the package is @gradientlabs/client. Updated package.json/lockfile, README, examples, plan, and source references. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The plan file has served its purpose now the client is implemented. Drop it along with the .prettierignore entry and the enums.ts comment that pointed at it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.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.
Implements
@gradient-labs/client, the official Node.js / TypeScript client for the public Gradient Labs API, followingnodejs_CLIENT_PLAN.md.What's included
client.conversations.start(...),client.tools.list(...), etc. Covers every endpoint inplatform/openapi/spec.json(Integration + Management roles).GET /spec.jsonis intentionally omitted; the deprecatedGET /conversations/{id}is exposed asconversations.getDeprecated().fetch+node:crypto. Node 20+.GradientLabsError→ConfigurationError/ApiError(withstatusCode,code,details,traceId) and typedErrorCodeconstants.Page<T>+listAll()async iterators.WebhookVerifier.verify/.parse— HMAC-SHA256 over<ts>.<body>, leeway check, constant-time compare, discriminated-union events, andX-GradientLabs-Tokenpassthrough..d.tsvia tsup. Examples for 7 resource groups. CI (Node 20/22) + tag-triggered npm publish (provenance).Correctness review
A dedicated review pass cross-checked every endpoint, field, enum, and webhook payload against the Go backend (
platform/support-platforms/public-api,platform/apis/public-management-api, and the webhook publishers). Findings were fixed in this branch:{ back_office_task: ... }shape.action.execute/resource.pullconversation payloads split out (withcustomer_source+metadata+ optionalback_office_task); plain conversation events carry{id, customer_id}only; addedlast_customer_message_id.payload,agent_idrequired;resources, attachmentsummary/description,GatedConfigoptional).Quality gate
tsc,eslint,prettier --check,tsupbuild, and 40/40 vitest tests all pass (no network required).🤖 Generated with Claude Code