@rustrak/client 0.13.0 → 0.14.0

package/README.md

@@ -58,17 +58,24 @@ const client = new RustrakClient({
   token: process.env.RUSTRAK_API_TOKEN!,
 });
 
-// List all projects
+// Every method returns a Result. Nothing throws for an expected failure.
 const projects = await client.projects.list();
+if (!projects.success) {
+  console.error(projects.error.kind, projects.error.message);
+  return;
+}
+console.log(projects.data.items);
 
 // Paginate through open issues
-const { items, next_cursor, has_more } = await client.issues.list(1, {
-  sort: 'last_seen',
-  order: 'desc',
-});
+const issues = await client.issues.list(1, { sort: 'last_seen', order: 'desc' });
+if (issues.success) {
+  const { items, next_cursor, has_more } = issues.data;
+}
 
 // Resolve an issue
-await client.issues.updateState(1, 'issue-id', { is_resolved: true });
+const resolved = await client.issues.updateState(1, 'issue-id', {
+  is_resolved: true,
+});
 ```
 
 **[Full documentation →](https://rustrak.github.io/rustrak/sdks/client)**
@@ -78,9 +85,10 @@ await client.issues.updateState(1, 'issue-id', { is_resolved: true });
 - **Type-safe** — All API responses validated at runtime with Zod; types are inferred from schemas
 - **Lightweight** — ~28 KB total (ky 3 KB + zod 10 KB + client 15 KB)
 - **Automatic retry** — Exponential backoff on transient failures (408, 429, 5xx)
-- **Structured errors** — Typed error classes for every HTTP status and failure mode
+- **No exceptions**: every method returns `Result<T, RustrakError>`, so failure is in the type, and the value survives the React server/client boundary
 - **Cursor pagination** — First-class support for paginated responses across all list endpoints
-- **97% test coverage** — 133 tests (unit + integration with MSW)
+- **Redacted 5xx**: a server error never carries a server-supplied message, so internal detail cannot reach a UI
+- **High test coverage**: 430+ tests (unit + integration with MSW)
 
 ## API Reference
 
@@ -135,44 +143,108 @@ console.log(event.data); // Full Sentry event payload
 ```typescript
 const tokens  = await client.tokens.list();
 const created = await client.tokens.create({ description: 'CI token' });
-console.log(created.token); // Save this — shown only once
+if (created.success) {
+  console.log(created.data.token); // Save this, shown only once
+}
 await client.tokens.delete(1);
 ```
 
 ## Error Handling
 
+Resource methods do not throw. Each returns a `Result`, a plain discriminated
+union mirroring Zod's `safeParse`:
+
 ```typescript
-import {
-  AuthenticationError,
-  AuthorizationError,
-  NotFoundError,
-  RateLimitError,
-  NetworkError,
-  ServerError,
-  ValidationError,
-} from '@rustrak/client';
+type Result<T, E> =
+  | { success: true;  data: T }
+  | { success: false; error: E };
+```
 
-try {
-  await client.projects.list();
-} catch (error) {
-  if (error instanceof RateLimitError)       console.log(`Retry after ${error.retryAfter}s`);
-  else if (error instanceof AuthenticationError) redirect('/login');
-  else if (error instanceof NotFoundError)   console.log('Not found');
-  else if (error instanceof NetworkError)    console.log('Will retry automatically');
-  else if (error instanceof ValidationError) console.log(error.getValidationDetails());
+Failures are one closed union keyed on `kind`, so the compiler forces you to
+handle the case you care about and lets you ignore the rest deliberately:
+
+```typescript
+import { isRetryable, type RustrakError } from '@rustrak/client';
+
+const result = await client.projects.list();
+
+if (!result.success) {
+  switch (result.error.kind) {
+    case 'unauthenticated':
+      redirect('/login');
+      break;
+    case 'rate_limited':
+      console.log(`Retry after ${result.error.retryAfter ?? '?'}s`);
+      break;
+    case 'not_found':
+      console.log('Gone');
+      break;
+    default:
+      if (isRetryable(result.error)) scheduleRetry();
+      else console.error(result.error.message);
+  }
+  return;
 }
+
+console.log(result.data.items);
 ```
 
-| Error Class | HTTP | Retryable |
-|---|---|---|
-| `NetworkError` | — | ✅ |
-| `AuthenticationError` | 401 | ❌ |
-| `AuthorizationError` | 403 | ❌ |
-| `NotFoundError` | 404 | ❌ |
-| `BadRequestError` | 400 | ❌ |
-| `RateLimitError` | 429 | ✅ |
-| `ServerError` | 500+ | ✅ |
-| `ValidationError` | — | ❌ |
+### The error union
+
+| `kind` | HTTP | `status` | Retryable | Notes |
+|---|---|---|---|---|
+| `validation` | 400 | ✅ | ❌ | The server rejected the request |
+| `unauthenticated` | 401 | ✅ | ❌ | No session, or it expired |
+| `forbidden` | 403 | ✅ | ❌ | Authenticated but not allowed |
+| `not_found` | 404 | ✅ | ❌ | |
+| `conflict` | 409 | ✅ | ❌ | |
+| `gone` | 410 | ✅ | ❌ | |
+| `payload_too_large` | 413 | ✅ | ❌ | Envelope ingestion only |
+| `rate_limited` | 429 | ✅ | ✅ | Optional `retryAfter` in seconds |
+| `client_error` | other 4xx | ✅ | ❌ | Catch-all, so no status is unrepresentable |
+| `server_error` | 5xx | ✅ | ✅ | **Message is always a fixed generic string** |
+| `network` | n/a | no | ✅ | DNS, refused connection, TLS, timeout |
+| `invalid_response` | n/a | no | ❌ | 2xx whose body failed its schema |
+| `invalid_request` | n/a | no | ❌ | Your input failed a pre-flight check; nothing was sent |
+
+`status` is `number`, never a literal, so a proxy-generated 502 or a future
+status is a value you can log rather than a type error.
+
+Three things the union deliberately does **not** carry, because each embeds
+information that must not cross a serialization boundary:
+
+- `server_error` never carries the server's message. `AppError::Internal` and
+  `AppError::Database` interpolate arbitrary internal text (a pool error, an OS
+  errno, a filesystem path); the client discards it at construction and
+  substitutes `SERVER_ERROR_MESSAGE`.
+- `network` carries no `cause`. The underlying error embeds the resolved host
+  and port.
+- `invalid_response` carries no Zod issues. They embed the offending response
+  data.
+
+### Result helpers
+
+```typescript
+import { Ok, Err, unwrap, unwrapOr, mapResult } from '@rustrak/client';
+
+mapResult(await client.projects.get(1), (project) => project.name);
+unwrap(await client.projects.get(1)); // throws on failure: opting back in
+unwrapOr(await client.stats.summary(1, "24h"), null); // see the warning below
+```
+
+> **`unwrapOr` is not for rendering.** `unwrapOr(await client.projects.list(),
+> [])` shows the same empty state for "this account has no projects" and "the
+> server is unreachable": the exact confusion the `Result` API exists to
+> prevent, one line after the failure was produced. Use it only where the
+> fallback is correct regardless of *why* the call failed (a cached-count
+> optimisation, a best-effort telemetry read, a script that already logged the
+> error). Anywhere a human sees the outcome, branch on `result.success` and read
+> `error.kind`.
+
+Every value in a `Result` is a plain object with `Object.prototype`. That is
+what lets a failure be returned from a Server Component or a Server Action and
+read in a Client Component: React's Flight serializer rejects class instances,
+which is why there are no error classes here.
 
 ## Next.js Integration
 
@@ -187,7 +259,16 @@ export default async function ProjectsPage() {
     token: process.env.RUSTRAK_API_TOKEN!,
   });
   const projects = await client.projects.list();
-  return <ProjectsList projects={projects} />;
+
+  if (!projects.success) {
+    // `kind` is what decides: only 'unauthenticated' means "send to login".
+    // Redirecting on 'network' or 'server_error' turns a flaky connection
+    // into a login loop.
+    if (projects.error.kind === 'unauthenticated') redirect('/auth/login');
+    return <LoadFailed error={projects.error} />;
+  }
+
+  return <ProjectsList projects={projects.data.items} />;
 }
 ```
 
@@ -202,6 +283,8 @@ export async function resolveIssue(projectId: number, issueId: string) {
     baseUrl: process.env.RUSTRAK_API_URL!,
     token: process.env.RUSTRAK_API_TOKEN!,
   });
+  // The Result is returned as-is: it is serializable, so the client component
+  // receives the failure instead of an opaque "An error occurred" digest.
   return client.issues.updateState(projectId, issueId, { is_resolved: true });
 }
 ```
@@ -220,6 +303,9 @@ import type {
   PaginatedResponse,
   CreateProject,
   UpdateIssueState,
+  Result,
+  RustrakError,
+  RustrakErrorKind,
 } from '@rustrak/client';
 ```