@uluops/ops-sdk 1.0.1 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,240 @@
+# Changelog
+
+All notable changes to `@uluops/ops-sdk` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [1.1.0] - 2026-04-09
+
+### Fixed
+- Package description updated to reflect full SDK scope (tracker, analytics, auth, org management)
+- `issues.search()` refactored to use `toApiQuery()` instead of manual query serialization
+- `normalizeKeys()` now guards against prototype pollution (`__proto__`, `constructor`, `prototype` keys) — matches `deepMerge()` behavior
+- README version updated from 0.7.0 to 1.0.1
+- README Quick Start base URL comment corrected (defaults to production, not localhost)
+- JSDoc on `OpsClientConfig.baseUrl` corrected to document NODE_ENV-conditional default
+- `files` field in package.json now includes README.md and CHANGELOG.md in published tarball
+
+## [1.0.0] - 2026-04-08
+
+### Changed
+- **Breaking:** All response types now derived from Zod schemas via `z.infer<>` — hand-written interfaces removed. Type shapes are identical but provenance changed. Consumers importing types may see different IDE hover text.
+- `SDK_VERSION` constant synced to `1.0.0`
+
+### Added
+- Phase 6: Response types derived from Zod schemas — single source of truth for all domain types (Run, Issue, Project, Auth, Analytics)
+
+## [0.10.1] - 2026-04-08
+
+### Fixed
+- `deleteProject` and `softDelete` return 204 no-content handling
+
+## [0.10.0] - 2026-04-08
+
+### Added
+- Phase 5: Response schemas wired into all analytics operations — runtime validation on all 14 analytics endpoints
+
+## [0.9.4] - 2026-04-08
+
+### Fixed
+- `ValidateRunResponse.preview` contains arrays not counts
+
+## [0.9.3] - 2026-04-08
+
+### Fixed
+- `ValidateRunResponse` and `ProjectTrends` schemas aligned to API reality
+
+## [0.9.2] - 2026-04-08
+
+### Fixed
+- `Issue.deletedAt` stripped by API `issueToPublic` — removed from schema
+
+## [0.9.1] - 2026-04-08
+
+### Fixed
+- `Project` and `ProjectSummary` schemas aligned to API reality
+
+## [0.9.0] - 2026-04-08
+
+### Added
+- Phase 4: Response schemas wired into issue, project, and auth operations
+
+## [0.8.2] - 2026-04-08
+
+### Fixed
+- `ArchiveRunsResult` schema aligned to API reality
+
+## [0.8.1] - 2026-04-08
+
+### Fixed
+- `RunDetailsResponseSchema` aligned to API reality
+
+## [0.8.0] - 2026-04-08
+
+### Added
+- Phase 3: Response schemas wired into all run operations — runtime Zod validation on every runs endpoint
+- Phase 1: All response schemas aligned to API reality (optional→required where API guarantees, missing fields added)
+- `@uluops/sdk-core` bumped to 0.3.0 (adds `patch()` schema support and `ResponseValidationError`)
+
+## [0.7.0] - 2026-04-08
+
+### Added
+- `archivedAt` and `archiveReason` fields on `UpdateRunInput` — enables archive/unarchive via the standard update endpoint
+- `updateById()` now forwards `archivedAt` and `archiveReason` to the API
+- `update()` (by project+number) now forwards `archivedAt` and `archiveReason` to the API
+- `orgSlug` constructor option on `OpsClient` for multi-tenancy (sets `X-Org-Slug` header)
+
+### Fixed
+- **Breaking:** `AgentInput.decision` and `AgentSnapshot.decision` now match Zod schemas — previously the TypeScript interfaces used `decision` while `AgentInputSchema` and `AgentSnapshotResponseSchema` used `status`, causing runtime validation failures for consumers following the TypeScript types
+- `SDK_VERSION` constant synced to `0.7.0`
+
+### Removed
+- Admin operations (`client.admin.*`) — removed from public SDK surface. Use the dashboard or direct API for admin tasks.
+- Dead admin test suites (16 tests referencing removed operations)
+
+### Docs
+- README: removed 165-line Admin Operations section documenting removed `client.admin.*`
+- README: Quick Start examples use `decision` (not `status`) and `inputTokens` (not `input_tokens`)
+- README: fixed stale type import (`SaveFeaturesListInput` → `SaveRunInput`)
+- README: version badge updated from 0.3.1 to 0.7.0
+- README: documented `orgSlug` constructor option
+
+## [0.6.0] - 2026-04-06
+
+### Added
+- `ULUOPS_SESSION_TOKEN` environment variable support for session-based auth
+
+## [0.4.0] - 2026-03-15
+
+### Removed
+- Admin operations removed from public SDK surface (moved to dashboard-only)
+
+### Changed
+- Bumped version to reflect breaking change
+
+## [0.2.0] - 2026-03-01
+
+### Added
+- Analysis operations: `getAnalysis()`, `getProjectAnalysis()`, `queryAnalysisRecords()`
+- `AnalysisRecord` and `AnalysisSummary` types for structured analysis data
+- `definitionType`, `definitionName`, `definitionVersion`, `definitionHash` fields on `SaveRunInput`
+
+## [0.1.5] - 2026-02-15
+
+### Fixed
+- `getVelocity`, `getDiscovery`, `getValidatorMatrix` now use `toApiQuery()` for consistent snake_case query parameter conversion (was manually constructing query objects, bypassing conversion)
+
+### Improved
+- `OpsClient` class JSDoc with authentication mode examples and usage patterns
+- `login()` JSDoc clarifies relationship with `auth.login()` (install-session vs raw-token)
+- `listValidators()` JSDoc documents O(n) complexity note
+- README: `updateProfile` documents "at least one field required" constraint
+- README: `getByMetric` lists all available metric names
+- README: low-level HTTP client section warns to prefer `OpsClient`
+
+## [0.1.4] - 2026-02-15
+
+### Fixed
+- Query parameters now sent as snake_case to match API expectations (`failureDomain` → `failure_domain`, `includeResolved` → `include_resolved`, etc.)
+- `priority=all` filter value stripped before sending (API rejects it; omitting means "all")
+- `lineNumber` field now accepts `null` in `RecommendationInputSchema` and `CreateUserIssueInputSchema` (`.optional()` → `.nullish()`)
+- `deepMerge` utility now guards against prototype pollution (`__proto__`, `constructor`, `prototype` keys)
+- `formatDate` now throws `RangeError` on invalid date strings instead of returning `"Invalid Date"`
+
+### Added
+- `toApiQuery()` utility for centralized camelCase→snake_case query parameter conversion
+- JSDoc descriptions on all 7 operation group properties in `OpsClient`
+- Documented `requestRaw` tradeoff in `listIssuesWithCount` (no retry/refresh for envelope access)
+
+### Changed
+- `RegisterResponseSchema` now requires `id`, `email`, `isActive`, `role`, `createdAt`, `updatedAt` (were optional)
+- `LoginResponseSchema` documented `sessionToken`/`token` backward compatibility
+
+## [0.1.3] - 2026-02-15
+
+### Added
+- `normalizeKeys<T>()` — recursive snake_case→camelCase key conversion with mapped types
+- `getFlexibleProperty()` — dual-case property access for mixed API responses
+- `retryMutations` option on `runs.save()` for idempotent retry safety
+- `loadEnvFiles()` — loads `.env` from cwd and `~/.uluops/.env`
+- `listIssuesWithCount()` — paginated issue listing preserving API envelope count
+- `listValidators()` — derived validator list from performance data
+- `updateById()` — update a run by UUID (vs by project+runNumber)
+- `updateStatusByFingerprint()` — update issue status by fingerprint hash
+
+### Fixed
+- Error guards on all SDK error classes (missing `instanceof` checks)
+- Delete operations now return `{ deleted: true }` result type
+
+## [0.1.2] - 2026-02-08
+
+### Added
+- `readFileOption` helper for CLI file argument parsing
+- `parseIntOption`/`parseFloatOption` for safe CLI numeric parsing
+- Global `unhandledRejection` handler in CLI entry point
+- `--timeout` flag for CLI commands
+- 503 `Retry-After` header support in retry logic
+- `retryMutations` option for POST requests that are safe to retry
+- EACCES error handling for config file writes
+
+### Fixed
+- Retry logic respects `Retry-After` header from 503/429 responses
+- Config directory creation handles permission errors gracefully
+
+## [0.1.1] - 2026-02-07
+
+### Changed
+- SDK core extraction: shared HTTP client, auth strategies, and utilities moved to `@uluops/sdk-core`
+- Aligned SDK types with actual API response shapes
+
+## [0.1.0] - 2026-02-05
+
+### Added
+- Initial SDK for UluOps validation tracker API
+- `OpsClient` with namespaced operations: auth, projects, runs, issues, analytics, taxonomy, admin
+- `OpsHttpClient` with native fetch, retry logic, timeout handling, and exponential backoff
+- JWT session auth and API key auth strategies with automatic token refresh
+- Typed error classes: `ValidationError`, `UnauthorizedError`, `NotFoundError`, `RateLimitError`, etc.
+- Configuration loading from environment variables, `.env` files, and `~/.uluops/credentials.json`
+- Runtime input validators using Zod schemas wired into all 5 operation modules
+- Granular package.json exports for tree-shaking (`/types`, `/errors`, `/config`)
+- ESLint with typescript-eslint flat config (ESLint 9)
+- Password schema with complexity requirements (lowercase, uppercase, digit)
+- Typed generic overloads for `analytics.getByMetric()` via `AnalyticsMetricResultMap`
+- Token refresh race condition protection with promise deduplication
+- Credential sanitization in `OpsApiError.toJSON()` via `sanitizeForDisplay()`
+- `QueryParams`/`QueryParamValue` types for HTTP client methods
+- Shared `buildIssueListParams()` utility for issue listing endpoints
+- JSDoc `@param`/`@returns` on all exported helpers
+- Comprehensive test suite with 467 tests across 16 files
+
+### Changed
+- Migrated HTTP layer from axios to native fetch (zero runtime HTTP dependencies)
+- Extracted CLI to dedicated `@uluops/cli` package
+- Retry logic now only retries idempotent methods (GET/PUT/DELETE)
+- SDK sends camelCase directly to API (removed snake_case conversion layer)
+- Restricted barrel exports: `config/index.ts` exposes consumer-facing constants only; `utils/index.ts` exposes `createLogger` and `Logger` type only
+- Removed 14 unnecessary `as Record<string, unknown>` type casts across operation files
+
+### Fixed
+- Safe JSON parsing on success-path responses (handles empty/non-JSON bodies)
+- Token refresh errors now logged instead of silently swallowed
+- Login response validated before destructuring to prevent undefined values
+- `getAvatar()` uses binary response handling instead of JSON parsing
+- `Error.captureStackTrace` guarded for non-V8 runtimes
+- `encodeURIComponent` applied to all URL path parameters
+- Debug logging for credential loading errors
+- Admin/analytics endpoints receiving snake_case when they expected camelCase
+- Test data corrected by validators: invalid role enums, non-UUID IDs, wrong field names
+
+### Testing
+- 467 tests across 16 test files (up from 314)
+- Schema-validated mock factories with contract helpers for all response types
+- Nock interceptor leak detection in test setup (unconsumed = implicit assertion)
+- Return value verification on all 18 validator test suites (mutation resistance)
+- Error path inspection on validation failures (message content, error paths, statusCode)
+- Explicit `nock.isDone()` assertions on retry logic tests
+- Shared test constants (`TEST_API_KEY`, `TEST_UUID`) eliminating magic strings
+- 52 error constructor edge case tests
+- HTTP timeout boundary tests
+- `query-utils.test.ts` with full branch coverage

package/README.md

@@ -11,7 +11,7 @@
 
 Official TypeScript SDK with Zod runtime validation for the UluOps validation tracker API. Track validation runs, manage issues, analyze trends, and integrate AI validation pipelines into your workflow.
 
-**Current version: 0.7.0** | [Changelog](./CHANGELOG.md)
+**Current version: 1.1.0** | [Changelog](./CHANGELOG.md)
 
 ## Quick Start
 
@@ -20,8 +20,8 @@ Official TypeScript SDK with Zod runtime validation for the UluOps validation tr
 ```typescript
 import { OpsClient } from '@uluops/ops-sdk';
 
-// Defaults to http://localhost:3100/api/v1 for local dev.
-// For production, set ULUOPS_BASE_URL env var or pass baseUrl below.
+// Defaults to https://api.uluops.ai/api/v1/ops in production.
+// Set NODE_ENV=development for localhost:3100, or pass baseUrl explicitly.
 const client = new OpsClient({
   apiKey: 'ulr_your-api-key-here', // Create via client.auth.createApiKey() or admin dashboard
 });
@@ -109,7 +109,7 @@ The SDK covers **83 API methods** across 7 operation domains with full TypeScrip
 
 ## Features
 
-- **Full API Coverage**: Access all 83 methods across auth, projects, runs, issues, analytics, taxonomy, and admin domains
+- **Full API Coverage**: Access all 83 methods across auth, projects, runs, issues, analytics, and taxonomy domains
 - **Type-Safe**: Complete TypeScript definitions with Zod runtime validation
 - **Dual Authentication**: API key (preferred) and JWT session support
 - **Automatic Retries**: Exponential backoff for transient errors (502, 503, 504, 429)
@@ -205,7 +205,7 @@ import type {
   Project,
   Issue,
   Run,
-  ValidatorPerformance,
+  AgentPerformance,
   Priority,
   Status,
   Severity,
@@ -260,7 +260,7 @@ const client = new OpsClient({
   password: 'password',        // Password for login
 
   // Connection settings
-  baseUrl: 'http://localhost:3100/api/v1',  // API base URL
+  baseUrl: 'https://api.uluops.ai/api/v1/ops',  // API base URL (localhost:3100 when NODE_ENV=development)
   timeout: 30000,              // Request timeout in ms (default: 30000)
   retries: 3,                  // Retry count for transient errors (default: 3)
   debug: false,                // Enable debug logging
@@ -1046,9 +1046,9 @@ const issue = await client.issues.updateStatus('issue-uuid', {
 });
 ```
 
-#### `client.issues.edit(issueId, input)`
+#### `client.issues.update(issueId, input)`
 
-Edit issue metadata.
+Update issue metadata.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -1060,7 +1060,7 @@ Edit issue metadata.
 | `failureCode` | `string` | No | New failure code |
 
 ```typescript
-const issue = await client.issues.edit('issue-uuid', {
+const issue = await client.issues.update('issue-uuid', {
   title: 'Updated title',
   severity: 'high',
 });
@@ -1322,6 +1322,19 @@ for (const v of agents) {
 }
 ```
 
+#### Deprecated Aliases
+
+The following analytics methods were renamed from "validator" to "agent" terminology. The old names still work but will be removed in a future major version:
+
+| Deprecated | Replacement |
+|-----------|-------------|
+| `getValidatorPerformance` | `getAgentPerformance` |
+| `getValidatorReliability` | `getAgentReliability` |
+| `getValidatorMatrix` | `getAgentMatrix` |
+| `listValidators` | `listAgents` |
+
+Similarly, `client.issues.edit()` is deprecated in favor of `client.issues.update()`.
+
 ---
 
 ### Taxonomy Operations
@@ -1337,14 +1350,14 @@ const taxonomy = await client.taxonomy.get();
 
 console.log('Domains:', taxonomy.domains);
 // [
-//   { code: 'STR', name: 'Structural', modes: ['OMI', 'RED', 'MIS'] },
-//   { code: 'SEM', name: 'Semantic', modes: ['VAL', 'TYP', 'LOG'] },
-//   { code: 'PRA', name: 'Pragmatic', modes: ['PER', 'SEC', 'MAI'] },
-//   { code: 'EPI', name: 'Epistemic', modes: ['DOC', 'NAM', 'CLR'] },
+//   { code: 'STR', name: 'Structural', description: '...', modes: [{ code: 'OMI', name: 'Omission', description: '...' }, ...] },
+//   { code: 'SEM', name: 'Semantic', description: '...', modes: [...] },
+//   { code: 'PRA', name: 'Pragmatic', description: '...', modes: [...] },
+//   { code: 'EPI', name: 'Epistemic', description: '...', modes: [...] },
 // ]
 
 console.log('Severities:', taxonomy.severities);
-// ['critical', 'high', 'medium', 'low', 'info']
+// [{ code: 'C', name: 'critical', weight: 10 }, { code: 'H', name: 'high', weight: 5 }, ...]
 
 console.log('Priorities:', taxonomy.priorities);
 // ['critical', 'suggested', 'backlog']
@@ -1380,7 +1393,8 @@ For command-line usage, see the dedicated CLI package: [`@uluops/cli`](https://w
 | `ULUOPS_API_KEY` | API key for authentication | - |
 | `ULUOPS_EMAIL` | Email for session auth | - |
 | `ULUOPS_PASSWORD` | Password for session auth | - |
-| `ULUOPS_BASE_URL` | API base URL | `http://localhost:3100/api/v1` |
+| `ULUOPS_SESSION_TOKEN` | Session token for auth | - |
+| `ULUOPS_BASE_URL` | API base URL | `https://api.uluops.ai/api/v1/ops` (localhost:3100 when `NODE_ENV=development`) |
 | `ULUOPS_DEBUG` | Enable debug logging | `false` |
 
 Create a `.env` file in your project:
@@ -1392,7 +1406,7 @@ ULUOPS_BASE_URL=https://api.uluops.com/api/v1
 
 Or configure globally in `~/.uluops/.env`.
 
-> **Note:** The SDK defaults to `http://localhost:3100/api/v1` for local development. For production use, always set `ULUOPS_BASE_URL` or pass `baseUrl` to the constructor.
+> **Note:** The SDK defaults to `https://api.uluops.ai/api/v1/ops` in production. Set `NODE_ENV=development` to default to `http://localhost:3100/api/v1`, or pass `baseUrl` explicitly.
 
 ## Error Handling
 
@@ -1441,9 +1455,12 @@ try {
 | `NotFoundError` | 404 | Resource not found |
 | `ConflictError` | 409 | Resource conflict |
 | `RateLimitError` | 429 | Rate limit exceeded |
+| `PayloadTooLargeError` | 413 | Request body too large |
+| `UnprocessableError` | 422 | Semantically invalid request |
 | `ServiceUnavailableError` | 503 | Server unavailable |
 | `NetworkError` | - | Connection error |
 | `TimeoutError` | - | Request timeout |
+| `InputValidationError` | - | Client-side Zod validation failure (import from `/config`) |
 
 ### Automatic Retries