Add comprehensive tests and documentation for TS SDK features#13
Merged
Add comprehensive tests and documentation for TS SDK features#13
Conversation
Implements full TypeScript SDK with feature parity to the Python SDK: - AgentQClient with full CRUD for agents, heartbeat, and task management - @agent decorator for declarative agent registration (mirrors Python @agent) - AgentRegistry singleton for collecting and bulk-syncing agents - Comprehensive type definitions for all API models - Custom error hierarchy (ApiError, ConfigError, NetworkError, TimeoutError) - Dual CJS/ESM build via tsup with full .d.ts type declarations - 35 unit tests covering client, decorators, registry, and errors - README with usage examples, API reference, and development guide Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add ESLint config with TypeScript rules and consistent-type-imports - Add .npmignore for cleaner published package - Add CHANGELOG.md following Keep a Changelog format - Add sideEffects: false for tree-shaking support - Add package.json/exports entry for bundler compatibility - Add repository, bugs, homepage metadata for npm registry - Add dev, typecheck, test:coverage, lint:fix scripts - Strengthen prepublishOnly to run lint + typecheck + tests before build - Remove emitDecoratorMetadata (unused, caused @swc/core warning) - Enable noUncheckedIndexedAccess and isolatedModules for stricter types Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Types: - Add AGENT_FRAMEWORKS, AGENT_STATUSES, TASK_STATUSES const arrays (derive types with `as const` for single source of truth) - Add TaskStatus type (was inline "pending"|"running"|... in AgentTask) - Add RetryConfig type for upcoming retry support in HTTP client - Add RegistryEvents and RegistryEventListener types - Add type guard functions: isAgentFramework, isAgentStatus, isTaskStatus, isAgent for runtime validation Registry: - Add event emitter with on()/off() for "registered", "unregistered", "synced" lifecycle events - on() returns unsubscribe function for ergonomic cleanup - Emit events on register, unregister, and syncAll operations Exports: - Re-export all new types, constants, and type guards from barrel Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
HTTP Client: - Add configurable retry with exponential backoff and full jitter (configure via retry option in AgentQConfig) - Retry on 429, 500, 502, 503, 504 by default (customizable) - Also retry on network errors and timeouts - Add onRequest() hook for pre-request logging/header injection - Add onResponse() hook for post-response metrics/latency tracking - Extract sleep() method for testability AgentQClient: - Expose onRequest()/onResponse() chainable methods - Export RequestHook and ResponseHook types Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Tests (43 new tests, 78 total): - types.test.ts: 18 tests for type guards (isAgentFramework, isAgentStatus, isTaskStatus, isAgent) and constant arrays - registry-events.test.ts: 9 tests for on/off/unsubscribe, registered/unregistered/synced events - client-retry.test.ts: 16 tests for retry logic (500, 429, 502/503/504 retries, non-retryable 400/404, network errors, custom retryable statuses, retry exhaustion) and request/ response hooks (header injection, chaining, multiple hooks) Documentation: - Add Retry with Exponential Backoff section with config example - Add Request & Response Hooks section with usage examples - Add Type Guards section showing runtime validation - Add Registry Events section with lifecycle hook examples - Update API reference tables with new methods - Expand Configuration section to show retry options Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ryandao
commented
Apr 14, 2026
Owner
Author
ryandao
left a comment
ryandao
left a comment
There was a problem hiding this comment.
Review: Add comprehensive tests and documentation for TS SDK features
Verdict: APPROVE (submitted as comment due to self-review limitation)
Strong test suite and production-quality README. The 43 new tests (78 total) across types.test.ts, registry-events.test.ts, and client-retry.test.ts provide solid coverage of type guards, registry lifecycle events, retry logic, and hooks. Edge cases are well-covered. The README is comprehensive with installation, 3 quick-start approaches, lifecycle, error handling, retry config, hooks, type guards, registry events, and API reference tables.
CI failure is pre-existing (FeatherClock not defined in server infrastructure.tsx) - not caused by this PR.
Minor non-blocking suggestions:
- Extract duplicated
mockResponsehelper to sharedtests/helpers.ts - Add a timeout retry test (AbortError triggering retry)
isAgenttype guard should also validate thetagsfield- README could mention
AgentNotFoundErrorandAgentQConfigErrorin error handling section - Add a test for
listAgents()with no params
Ship it!
This was referenced Apr 14, 2026
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
types.test.ts— 18 tests for type guards (isAgentFramework,isAgentStatus,isTaskStatus,isAgent) and constant arraysregistry-events.test.ts— 9 tests foron/off/unsubscribe,registered/unregistered/syncedeventsclient-retry.test.ts— 16 tests for retry logic (500, 429, 502-504, non-retryable 400/404, network errors, custom retryable statuses, retry exhaustion) and request/response hooks (header injection, chaining, multiple hooks)Test plan
npx vitest run— 78/78 tests pass across 7 filesnpx tsc --noEmit— clean typechecknpx tsup— CJS/ESM/DTS build succeedsSubmitted by ✨ Rin (DevSquad) for task
cmny3jxrp000bg5e08q8dn8s1