ts-procedures 6.1.0 → 7.0.0-beta.0

package/README.md

@@ -52,6 +52,8 @@ const user2 = await procedure({}, { userId: '456' })
 
 - **[Typed Error Handling](docs/http-integrations.md#error-handling)** — Declarative `defineErrorTaxonomy` maps thrown error classes to HTTP responses across every builder; generated clients throw typed class instances you can catch with `instanceof`.
 
+- **[Client Error Handling](docs/client-error-handling.md)** — Normalized framework error classes (`ClientHttpError`, `ClientNetworkError`, `ClientTimeoutError`, `ClientAbortError`, `ClientParseError`), `.safe()` Result API for exhaustive narrowing without try/catch, and augmentable `ClientErrorMap` for custom error categories.
+
 - **[AI Agent Setup](docs/ai-agent-setup.md)** — Built-in configuration for Claude Code, Cursor, and GitHub Copilot. Auto-updates on `npm install`.
 
 Full documentation is available on [GitHub](https://github.com/thermsio/ts-procedures).

package/agent_config/bin/setup.mjs

@@ -92,7 +92,7 @@ function setupClaude({ dryRun, check } = {}) {
     // Mirror install-claude.mjs: copy every file under each source skill dir, plus the agent.
     const claudeFiles = [];
     const skillsSrc = join(AGENT_CONFIG_DIR, 'claude-code', 'skills');
-    for (const skill of ['ts-procedures', 'ts-procedures-review', 'ts-procedures-scaffold']) {
+    for (const skill of ['ts-procedures', 'ts-procedures-review', 'ts-procedures-scaffold', 'ts-procedures-kotlin', 'ts-procedures-swift']) {
       const walk = (dir, prefix) => {
         for (const entry of readdirSync(dir)) {
           const full = join(dir, entry);
@@ -128,7 +128,7 @@ function setupClaude({ dryRun, check } = {}) {
     console.log(`    ${f}`);
   }
   console.log('');
-  console.log('  Skills:  ts-procedures, ts-procedures-scaffold, ts-procedures-review');
+  console.log('  Skills:  ts-procedures, ts-procedures-scaffold, ts-procedures-review, ts-procedures-kotlin, ts-procedures-swift');
   console.log('  Agent:   ts-procedures-architect (architecture planning)\n');
   return false;
 }

package/agent_config/claude-code/skills/ts-procedures/SKILL.md

@@ -16,6 +16,7 @@ Load the right reference for your task:
 - **Reviewing or debugging existing code?** Read [anti-patterns.md](anti-patterns.md) — 20 common mistakes with before/after fixes and severity ratings
 - **Need exact API signatures or type definitions?** Read [api-reference.md](api-reference.md) — complete API documentation with type signatures for every export
 - **Generating a Kotlin client for Android/JVM consumers?** Use the separate `ts-procedures-kotlin` skill — it covers `--target kotlin` end-to-end and won't load unless the user mentions Kotlin/Android.
+- **Generating a Swift client for iOS/macOS/Apple-platform consumers?** Use the separate `ts-procedures-swift` skill — it covers `--target swift` end-to-end and won't load unless the user mentions Swift/iOS/Apple platforms.
 
 ## Core Flow
 
@@ -174,7 +175,8 @@ The npm package ships user-facing documentation with narrative explanations and
 | `docs/streaming.md` | Streaming procedures, AbortSignal, SSE patterns |
 | `docs/http-integrations.md` | Express RPC, Hono RPC/Stream/API builders, **error taxonomy (canonical)**, DocRegistry (unified constructor, `.documentError()`) |
 | `docs/client-and-codegen.md` | Client code generation, `createApiClient`/`createClient`, typed error dispatch, per-route `Errors` unions, per-call options, client-level defaults, typed RequestMeta augmentation, CLI options |
-| `CHANGELOG.md` | Release notes — see `[6.0.0]` for the current peer error-handling model (taxonomy + `onError` + `onRequestError`), per-route errors, and client runtime error classes. |
+| `docs/client-error-handling.md` | **Canonical guide** for 7.0+ client error surface: normalized error classes, `.safe()` Result API, `ClientErrorMap` augmentation, custom `ErrorClassifier`, migration from `ClientRequestError`. |
+| `CHANGELOG.md` | Release notes — see `[7.0.0]` for the safe-result API, new error classes, and `ClientRequestError` → `ClientHttpError` rename. See `[6.0.0]` for the peer error-handling model (taxonomy + `onError` + `onRequestError`). |
 
 ## Workflow
 

package/agent_config/claude-code/skills/ts-procedures/anti-patterns.md

@@ -612,7 +612,7 @@ Create('GetUser', {
 
 ## 20. Hand-writing `onError` instanceof ladders
 
-**Problem:** Writing manual `instanceof` ladders inside `onError` to map each error class to a status + body. Every builder gets its own copy; generated clients see opaque `ClientRequestError` objects instead of typed instances; response shapes drift between routes.
+**Problem:** Writing manual `instanceof` ladders inside `onError` to map each error class to a status + body. Every builder gets its own copy; generated clients see opaque `ClientHttpError` objects instead of typed instances; response shapes drift between routes.
 
 ```typescript
 // BAD — duplicated across builders, invisible to generated clients
@@ -659,6 +659,42 @@ The same `errors` / `unknownError` shape plugs into every builder (`HonoAPIAppBu
 
 ---
 
+## 21. Catching raw `DOMException` or `TypeError` from generated callables
+
+**Problem:** Checking `instanceof DOMException` or `instanceof TypeError` in `catch` blocks after calling a generated RPC/API callable. The framework normalizes these platform errors into typed framework classes at the `executeCall` boundary — after 7.0.0, raw platform errors will not reach your `catch` block from a generated callable. The original platform error is preserved on `error.cause` if you need it.
+
+```typescript
+// BAD — platform error classes won't reach here from a generated callable
+catch (e) {
+  if (e instanceof DOMException && e.name === 'AbortError') {
+    // Was this a timeout or a user cancel? Hard to tell.
+  }
+  if (e instanceof TypeError) {
+    // Network failure? Something else?
+  }
+}
+```
+
+**Fix:** Catch the framework error classes instead.
+
+```typescript
+// GOOD
+import { ClientTimeoutError, ClientAbortError, ClientNetworkError } from 'ts-procedures/client'
+
+catch (e) {
+  if (e instanceof ClientTimeoutError)  Alerts.error('Timed out')
+  else if (e instanceof ClientAbortError)  { /* user cancelled — silent */ }
+  else if (e instanceof ClientNetworkError)  Alerts.error('Network error')
+  else throw e  // unknown — let it propagate
+}
+```
+
+Or use the `.safe()` sibling for exhaustive Result-based narrowing (see `patterns.md` — "Handling errors in client code").
+
+**Why:** The framework wraps `AbortError` (from timeout or signal) into `ClientTimeoutError` / `ClientAbortError` and `TypeError`/fetch network failures into `ClientNetworkError`. This gives you distinct, meaningful types and removes ambiguity. Streams keep the throwing form — `.safe()` is only available on RPC and API callables.
+
+---
+
 ## Summary Table
 
 | # | Anti-Pattern | Risk | Severity |
@@ -683,3 +719,4 @@ The same `errors` / `unknownError` shape plugs into every builder (`HonoAPIAppBu
 | 18 | Both schema.params and schema.input | ProcedureRegistrationError at startup | CRITICAL |
 | 19 | Mismatched path param names | Build-time error or confusing validation failures | CRITICAL |
 | 20 | Hand-writing onError instanceof ladders | Drifting response shapes, untyped client errors | WARNING |
+| 21 | Catching raw DOMException/TypeError from generated callables | Framework normalizes these; raw platform errors won't reach catch blocks after 7.0.0 | WARNING |

package/agent_config/claude-code/skills/ts-procedures/api-reference.md

@@ -354,7 +354,7 @@ Returns a typed error instance when:
 - `body` is an object with a string `name`, AND
 - `registry[body.name].fromResponse(body, meta)` returns an `Error` subclass.
 
-Otherwise returns `null`; callers fall back to `ClientRequestError`.
+Otherwise returns `null`; callers fall back to `ClientHttpError`.
 
 ### CreateClientConfig.errorRegistry
 
@@ -369,6 +369,189 @@ Threaded into both `executeCall` and `executeStream`. The generated `create${Ser
 
 ---
 
+## Client Error Classes (7.0+)
+
+All framework errors are normalized at the `executeCall` / `executeStream` boundary — raw `TypeError` and `DOMException` from the platform never reach consumer catch blocks.
+
+### ClientHttpError
+
+```typescript
+class ClientHttpError extends Error {
+  readonly status: number
+  readonly cause?: unknown
+}
+```
+
+Thrown for non-2xx HTTP responses whose body does not match any registry entry (or when no registry is configured). Renamed from `ClientRequestError` in 7.0.0; the old name is re-exported as a deprecated alias for one minor cycle.
+
+### ClientNetworkError
+
+```typescript
+class ClientNetworkError extends Error {
+  readonly cause?: unknown
+}
+```
+
+Thrown when the network request itself fails (e.g., DNS failure, connection refused — a `TypeError` from `fetch`). The original error is available on `cause`.
+
+### ClientTimeoutError
+
+```typescript
+class ClientTimeoutError extends Error {
+  readonly cause?: unknown
+}
+```
+
+Thrown when the request is aborted by a timeout (`AbortSignal.timeout`). The original `DOMException` is available on `cause`.
+
+### ClientAbortError
+
+```typescript
+class ClientAbortError extends Error {
+  readonly cause?: unknown
+}
+```
+
+Thrown when the request is aborted by a caller-supplied `AbortSignal`. The original `DOMException` is available on `cause`.
+
+### ClientParseError
+
+```typescript
+class ClientParseError extends Error {
+  readonly cause?: unknown
+}
+```
+
+Thrown when the response body cannot be parsed as JSON (e.g., the server returned HTML for a non-2xx status). The parse error is available on `cause`.
+
+### ClientPathParamError
+
+```typescript
+class ClientPathParamError extends Error {}
+```
+
+Thrown at call time when a required path parameter is missing in the options. This is a programming error (the generated callable could not interpolate the URL path).
+
+### ClientStreamError
+
+```typescript
+class ClientStreamError extends Error {
+  readonly cause?: unknown
+}
+```
+
+Thrown for stream-level transport errors (SSE connection failures, unexpected stream termination).
+
+---
+
+## Safe-Result API (7.0+)
+
+### Result\<T, ETyped\>
+
+```typescript
+type Result<T, ETyped = never> =
+  | { ok: true; value: T }
+  | FrameworkFailure<ETyped>
+```
+
+Returned by every generated `.safe()` callable. When `ok` is `true`, `value` is the typed response. When `ok` is `false`, the failure is discriminated by `kind`.
+
+### ResultNoTyped\<T\>
+
+```typescript
+type ResultNoTyped<T> = Result<T, never>
+```
+
+Convenience alias when no typed error registry is wired (all failures are framework-level).
+
+### FrameworkFailure\<ETyped\>
+
+```typescript
+type FrameworkFailure<ETyped = never> =
+  | { ok: false; kind: 'typed';   error: ETyped }
+  | { ok: false; kind: 'http';    error: ClientHttpError }
+  | { ok: false; kind: 'network'; error: ClientNetworkError }
+  | { ok: false; kind: 'timeout'; error: ClientTimeoutError }
+  | { ok: false; kind: 'aborted'; error: ClientAbortError }
+  | { ok: false; kind: 'parse';   error: ClientParseError }
+  | { ok: false; kind: 'usage';   error: ClientPathParamError }
+  | { ok: false; kind: 'unknown'; error: unknown }
+  // + any augmented kinds from ClientErrorMap
+```
+
+The failure branch of `Result`. Discriminate on `kind` to narrow `error`.
+
+### ClientErrorMap
+
+```typescript
+interface ClientErrorMap {
+  // empty — designed for declaration merging
+}
+```
+
+Augment this interface to add custom `kind` entries to `FrameworkFailure`. Example:
+
+```typescript
+declare module 'ts-procedures/client' {
+  interface ClientErrorMap {
+    rateLimit: RateLimitError
+  }
+}
+```
+
+After augmentation, `r.kind === 'rateLimit'` is a valid branch in a `switch` over `FrameworkFailure`.
+
+### ClientInstance.safeCall\<TResponse, ETyped\>(descriptor, options)
+
+```typescript
+interface ClientInstance {
+  safeCall<TResponse, ETyped = never>(
+    descriptor: CallDescriptor,
+    options?: ProcedureCallOptions
+  ): Promise<Result<TResponse, ETyped>>
+}
+```
+
+The underlying method that all generated `.safe()` callables delegate to. When `ETyped` is provided, it is the type of the `typed` failure branch (the registry-dispatched error class). Streams do not expose a `.safe()` sibling — `safeCall` applies to RPC and API calls only.
+
+---
+
+## Error Classifier API (7.0+)
+
+### defaultClassifyError
+
+```typescript
+function defaultClassifyError(err: unknown, ctx: ClassifyErrorContext): ClassifiedError | null
+```
+
+The built-in classifier that maps raw platform errors to framework classes. Returns a `ClassifiedError` (with `kind` + `error`) when the error is recognized, or `null` to fall through to `unknown`. Pass a custom `ErrorClassifier` to `createFetchAdapter` / `ClientAdapter` to override or extend.
+
+### ErrorClassifier
+
+```typescript
+type ErrorClassifier = (err: unknown, ctx: ClassifyErrorContext) => ClassifiedError | null
+```
+
+### ClassifyErrorContext
+
+```typescript
+interface ClassifyErrorContext {
+  request: AdapterRequest
+  signal?: AbortSignal
+}
+```
+
+### ClassifiedError
+
+```typescript
+interface ClassifiedError {
+  kind: keyof ClientErrorMap | 'network' | 'timeout' | 'aborted' | 'parse' | 'unknown'
+  error: Error
+}
+```
+
+---
+
 ## Schema Utilities
 
 ### extractJsonSchema(libSchema)
@@ -986,12 +1169,14 @@ Creates a `ClientAdapter` using the global `fetch` API.
 ```typescript
 function createFetchAdapter(options?: {
   fetch?: typeof globalThis.fetch
+  classifyError?: ErrorClassifier
 }): ClientAdapter
 ```
 
 ### Parameters
 
 - `options.fetch` — Optional custom fetch implementation. Defaults to `globalThis.fetch`.
+- `options.classifyError` — Optional classifier override. When provided, replaces `defaultClassifyError` for mapping raw platform errors to framework classes. Use this to add custom `ClientErrorMap` categories or to adjust the default mapping.
 
 ### Return Value
 
@@ -1013,7 +1198,7 @@ const adapter = createFetchAdapter({ fetch: customFetch })
 
 ## generateClient(options)
 
-> For **Kotlin** client codegen (Android/JVM, types-only output), see the dedicated `ts-procedures-kotlin` skill. The reference below covers TypeScript codegen only.
+> For **Kotlin** client codegen (Android/JVM, types-only output), see the dedicated `ts-procedures-kotlin` skill. For **Swift** client codegen (iOS/macOS/Apple platforms, types-only output), see the dedicated `ts-procedures-swift` skill. The reference below covers TypeScript codegen only.
 
 Build-time CLI and programmatic API for generating typed client files from a `DocEnvelope`.
 
@@ -1212,8 +1397,35 @@ import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
 import type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod } from 'ts-procedures/hono-api'
 
 // Client
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-import type { ClientAdapter, ClientHooks, ClientInstance, TypedStream } from 'ts-procedures/client'
+import {
+  createClient,
+  createFetchAdapter,
+  dispatchTypedError,
+  defaultClassifyError,
+  // Error classes (7.0+)
+  ClientHttpError,       // renamed from ClientRequestError; deprecated alias retained one cycle
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientParseError,
+  ClientPathParamError,
+  ClientStreamError,
+} from 'ts-procedures/client'
+import type {
+  ClientAdapter,
+  ClientHooks,
+  ClientInstance,
+  TypedStream,
+  // Safe-result types (7.0+)
+  Result,
+  ResultNoTyped,
+  FrameworkFailure,
+  ClientErrorMap,
+  // Classifier types (7.0+)
+  ErrorClassifier,
+  ClassifyErrorContext,
+  ClassifiedError,
+} from 'ts-procedures/client'
 
 // Code generation
 import { generateClient } from 'ts-procedures/codegen'

package/agent_config/claude-code/skills/ts-procedures/patterns.md

@@ -242,7 +242,7 @@ try {
   } else if (err instanceof ApiErrors.ApiProcedureError) {
     // Catch-all for any generated service error.
   } else {
-    // Transport error (network, non-JSON body) — still a ClientRequestError.
+    // Transport error (network, non-JSON body) — still a ClientHttpError.
   }
 }
 ```
@@ -263,13 +263,71 @@ export namespace Users {
 catch (err: unknown) {
   // Cast is manual today (TS has no typed throws); the union documents
   // which errors this specific route can throw.
-  const e = err as Users.GetUser.Errors | ClientRequestError
+  const e = err as Users.GetUser.Errors | ClientHttpError
   if (e instanceof ApiErrors.UseCaseError) { /* ... */ }
 }
 ```
 
 ---
 
+## Handling errors in client code
+
+The framework normalizes platform errors (`TypeError`, `DOMException`) into framework error classes at the `executeCall` boundary. Consumers see typed framework classes, not raw platform errors.
+
+### Throwing form (canonical)
+
+```typescript
+import { ClientHttpError, ClientTimeoutError, ClientNetworkError, ClientAbortError } from 'ts-procedures/client'
+import { createApiClient, ApiErrors, createFetchAdapter } from './generated'
+
+const api = createApiClient({ adapter: createFetchAdapter(), basePath: 'https://api.example.com' })
+
+try {
+  const response = await api.records.DownloadRecord(params, { timeout: 60_000 })
+  if (response.pdfBase64) downloadBase64AsPdf(response.pdfBase64)
+} catch (err) {
+  if (err instanceof ApiErrors.UseCaseError) {
+    Alerts.error(err.body.message)
+  } else if (err instanceof ClientHttpError) {
+    Alerts.error(`Server returned ${err.status}`)
+  } else if (err instanceof ClientTimeoutError) {
+    Alerts.error('Request timed out')
+  } else if (err instanceof ClientNetworkError) {
+    Alerts.error('Network error')
+  } else if (err instanceof ClientAbortError) {
+    // user cancelled — silent
+  } else {
+    throw err  // programmer/framework bug
+  }
+}
+```
+
+### Safe form (Result-returning, exhaustive narrowing)
+
+Every RPC and API callable has a `.safe()` sibling that returns `Result<T, ETyped>` instead of throwing:
+
+```typescript
+const r = await api.records.DownloadRecord.safe(params, { timeout: 60_000 })
+if (r.ok) {
+  if (r.value.pdfBase64) downloadBase64AsPdf(r.value.pdfBase64)
+  return
+}
+switch (r.kind) {
+  case 'typed':    /* registry-dispatched typed error, e.g. ApiErrors.UseCaseError */; break
+  case 'http':     Alerts.error(`Server ${r.error.status}`); break
+  case 'network':  Alerts.error('Network error'); break
+  case 'timeout':  Alerts.error('Timed out'); break
+  case 'aborted':  break  // user cancelled
+  case 'parse':
+  case 'usage':    throw r.error  // programmer/framework bug
+  case 'unknown':  console.error(r.error); break
+}
+```
+
+Streams keep the throwing form (no `.safe`). Custom error categories can be added via `ClientErrorMap` interface augmentation — see `docs/client-error-handling.md`.
+
+---
+
 ## Stream Procedures
 
 ```typescript

package/agent_config/claude-code/skills/ts-procedures-kotlin/SKILL.md

@@ -14,7 +14,7 @@ You are assisting a developer who needs to generate Kotlin types from a `ts-proc
 - The user wants to share API types between a `ts-procedures` server and a Kotlin/JVM consumer.
 - The user is debugging Kotlin codegen output, Gradle setup, or contextual serializer registration.
 
-If the user is generating a **TypeScript** client, redirect them to the main `ts-procedures` skill instead.
+If the user is generating a **TypeScript** client, redirect them to the main `ts-procedures` skill. For **Swift / iOS / macOS / Apple-platform** consumers, redirect to `ts-procedures-swift`.
 
 ## Quickstart
 

package/agent_config/claude-code/skills/ts-procedures-scaffold/templates/client.md

@@ -50,7 +50,7 @@ export const {{name}}Client = createApiClient({
 // } catch (err) {
 //   if (err instanceof ApiErrors.UseCaseError) { /* err.body typed; err.status, procedureName, scope */ }
 //   else if (err instanceof ApiErrors.ApiProcedureError) { /* catch-all for service errors */ }
-//   else { /* transport error — ClientRequestError */ }
+//   else { /* transport error — ClientHttpError */ }
 // }
 
 // --- RPC call example ---

package/agent_config/claude-code/skills/ts-procedures-swift/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: ts-procedures-swift
+description: "Swift client codegen for ts-procedures — generate types-only Swift source from a ts-procedures DocEnvelope for iOS/macOS/Apple-platform consumers. Use when the user mentions Swift, iOS, macOS, Apple platforms, Codable, or asks how to generate non-TypeScript types from a ts-procedures server."
+user-invocable: false
+---
+
+# ts-procedures — Swift Client Codegen
+
+You are assisting a developer who needs to generate Swift types from a `ts-procedures` server's `DocEnvelope`. The Swift target is **types-only** — no runtime, no adapter, no error registry. iOS / macOS / Apple-platform consumers own the HTTP layer.
+
+## When this skill applies
+
+- The user mentions Swift, iOS, macOS, watchOS, tvOS, visionOS, Apple platforms, `Codable`, `URLSession`, or `--target swift`.
+- The user wants to share API types between a `ts-procedures` server and a Swift consumer.
+- The user is debugging Swift codegen output, SPM/Xcode integration, `JSONDecoder` configuration, or `Codable` conformance issues.
+
+If the user is generating a **TypeScript** client, redirect them to the main `ts-procedures` skill. For **Kotlin/Android** consumers, redirect to `ts-procedures-kotlin`.
+
+## Quickstart
+
+```bash
+npx ts-procedures-codegen \
+  --target swift \
+  --url https://api.example.com/_ts-procedures.json \
+  --out ./Sources/MyApp/Generated
+```
+
+One `.swift` file per scope. Types accessed as `Users.GetUser.Response`, `Users.GetUser.PathParams`, `Users.GetUser.Response.Address` (nested structs via `inlineTypes: true`), `Users.GetUser.Errors.NotFound`.
+
+**Note:** unlike the Kotlin target, no `--swift-package` flag exists or is required. Swift modules are defined by Xcode/SPM targets.
+
+## CLI flags (Swift-specific)
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--target swift` | `ts` | Switch to the Swift codegen path |
+| `--swift-serializer <codable\|none>` | `codable` | `codable` emits `: Codable` + `CodingKeys`; `none` emits plain structs (consumer handles serialization) |
+| `--swift-access-level <public\|internal>` | `public` | Threads through to ajsc's `accessLevel`; use `internal` when generated types shouldn't appear in module ABI |
+| `--unsupported-unions <throw\|fallback>` | `throw` | **Functional for Swift** (unlike Kotlin where it's a no-op) — `fallback` emits a self-contained `AnyCodable` helper for untagged `anyOf`/`oneOf` |
+
+`--array-item-naming`, `--depluralize`, `--uncountable-words` also apply to the Swift target.
+
+## Output shape (what consumers see)
+
+```swift
+import Foundation
+
+public enum Users {
+    public enum GetUser {
+        public static let method = "GET"
+        public static let pathTemplate = "/users/{id}"
+        public static func path(_ p: PathParams) -> String { return "/users/\(p.id)" }
+
+        public struct PathParams: Codable {
+            public let id: String
+        }
+
+        public struct Response: Codable {
+            public let id: String
+            public let createdAt: Date
+            public let address: Address
+
+            enum CodingKeys: String, CodingKey {
+                case id
+                case createdAt = "created-at"
+                case address
+            }
+
+            public struct Address: Codable {
+                public let street: String
+                public let city: String
+            }
+        }
+
+        public enum Errors {
+            public struct NotFound: Codable {
+                public let name: String
+                public let message: String
+            }
+        }
+    }
+}
+```
+
+For routes without path params, `path` is a `static let`, not a function. Namespaces are caseless `enum`s (the standard Swift idiom — uninstantiable, zero runtime cost).
+
+## Consumer-side setup the dev MUST do
+
+The generated code requires these on the Apple-platform side. **Don't let the user assume the codegen handles them.**
+
+1. **Drop generated files into your SPM target or Xcode source group.** Any target containing the generated dir picks them up — no special build config. SPM globs sources recursively; for Xcode, use **File → Add Files to "<TargetName>"…** and ensure target membership is checked.
+
+2. **Configure `JSONDecoder.dateDecodingStrategy = .iso8601`.** **Required** if the schema uses any `format: date-time` field (which become `Foundation.Date`). Without this, decoding fails with `DecodingError.typeMismatch`. Symmetric: set `JSONEncoder.dateEncodingStrategy = .iso8601` for request bodies.
+
+3. **HTTP transport is the consumer's choice.** `URLSession` (with `async/await`) is the default recommendation — it's built-in and works on all Apple platforms with no dependencies. Alamofire / other libraries are fine but never required.
+
+4. **No runtime dispatch.** Error types are emitted as nested structs (`Users.GetUser.Errors.NotFound`), but there's no registry, no `instanceof`-style lookup, no `dispatchTypedError`. Consumers catch HTTP failures themselves and dispatch on status code or `body.name` (a regular `String` field, not a type-system discriminator) to decide which error struct to decode against. To make error structs throwable, declare a one-line `extension X.Errors.NotFound: Error {}` in user code (keep it out of the generated file so re-runs don't clobber it). This is by design; don't suggest implementing a registry.
+
+The full setup guide lives at `docs/codegen-swift.md` in the `ts-procedures` repo.
+
+## Documented limitations to flag during reviews
+
+- **`format: date` and `format: time` map to `String`.** Foundation has no native date-only or time-only type. Parse with `DateFormatter` if a typed value is needed.
+- **`type: integer` maps to `Int64`** (not `Int`). 32-bit Apple platforms exist; `Int64` guarantees range parity.
+- **`type: number` maps to `Double`.** For monetary values, convert to `Decimal` at the parse boundary.
+- **Heterogeneous tuples throw under `Codable`.** Swift tuples aren't `Codable`. Schemas with positional-tuple `items: [...]` arrays throw at codegen time. Refactor to a struct schema upstream.
+- **`additionalProperties: { type: T }` is silently dropped** with a doc-comment. Add a sibling `[String: T]` field by hand if your contract uses extra keys.
+- **`not` and `patternProperties` throw at codegen time.** Simplify the schema upstream.
+- **Untagged `oneOf` throws by default.** Add a discriminator, or pass `--unsupported-unions fallback` to emit `AnyCodable`-typed values (loses static typing).
+
+## Anti-patterns
+
+- **Suggesting the Swift target ships a networking layer or HTTP adapter.** It does not — consumers own `URLSession`/etc. entirely.
+- **Recommending Alamofire as required.** `URLSession` + `async/await` is fine and ships with the OS. Alamofire is a personal-preference choice, not a dependency of the generated code.
+- **Conflating `--swift-serializer none` with "no setup needed".** `none` removes `Codable` conformance and `CodingKeys` — the consumer then needs their own serialization plan (hand-rolled, SwiftyJSON, etc.). It's strictly *more* setup, not less.
+- **Treating `--unsupported-unions fallback` as a no-op for Swift.** Unlike Kotlin (where it's silently dropped), the Swift target actually emits an `AnyCodable` helper that round-trips correctly. Use it when needed.
+- **Suggesting backwards compatibility with Swift 4 / pre-async-await.** Assume Swift 5.5+ (the async/await era). Sample dispatch code in docs uses `async throws`.
+- **Suggesting the codegen emits `: Error` conformance on error structs.** It doesn't (`Codable` only) — consumers add a one-line extension. Don't ask for this to be added to the codegen; it would force users into a particular error model.
+- **Mixing `--target swift` flags into a TypeScript-target invocation.** The flags are silently ignored; no harm, but the user is probably running the wrong target.

package/agent_config/copilot/copilot-instructions.md

@@ -280,6 +280,8 @@ try {
 
 Per-route error unions: routes with `errors: [...]` get an `Errors` type in their namespace (e.g. `Users.GetUser.Errors = ApiErrors.UseCaseError | ApiErrors.AuthError`).
 
+- Generated client error handling: catch the framework classes (`ClientHttpError`, `ClientNetworkError`, `ClientTimeoutError`, `ClientAbortError`), not raw `DOMException`/`TypeError` — the framework normalizes platform errors at the `executeCall` boundary, so raw platform errors no longer reach `catch` blocks after 7.0.0 (original is on `error.cause`). Use the `.safe()` sibling on RPC/API callables for an exhaustive `Result<T, E>` switch (`ok`, `typed`, `http`, `network`, `timeout`, `aborted`, `parse`, `usage`, `unknown`). Streams keep the throwing form — no `.safe()`.
+
 ## Lifecycle Hook Order
 
 ### Standard RPC
@@ -327,6 +329,7 @@ onRequestStart → factoryContext() → validation → onStreamStart → handler
 9. **Never assume extra params fields survive** — `removeAdditional: true` strips them
 10. **Never manually parse types AJV coerces** — `coerceTypes: true` handles it
 11. **Never define both schema.params and schema.input** — mutually exclusive, throws ProcedureRegistrationError
+12. **Never catch raw DOMException/TypeError from generated callables** — catch `ClientTimeoutError`, `ClientAbortError`, `ClientNetworkError` instead; or use `.safe()` for Result-based narrowing
 
 ## Testing
 
@@ -387,6 +390,7 @@ npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated
 ```
 
 For Kotlin codegen (Android/JVM consumers), see `docs/codegen-kotlin.md` in the ts-procedures repo. The Kotlin target is types-only; consumer apps own HTTP/error handling.
+For Swift codegen (iOS/macOS/Apple-platform consumers), see `docs/codegen-swift.md` in the ts-procedures repo. The Swift target is types-only; consumer apps own HTTP/error handling.
 
 Generates one `.ts` file per scope plus a root `index.ts` that imports each scope as a namespace and exports a `create${ServiceName}Bindings(client)` factory AND a `create${ServiceName}Client(config)` convenience factory that pre-wires the error registry (defaults to `createApiBindings` / `createApiClient`; pass `--service-name <Name>` to rename). When namespace mode is on (the default), `index.ts` also wraps every scope namespace in an outer `export namespace ${ServiceName} { ... }` block so types are reachable as `Api.Users.GetUser.Params`, `Api.Errors.UseCaseError`, etc. The errors file (`_errors.ts`) emits runtime error classes extending a shared `${ServiceName}ProcedureError` base, each with `static fromResponse(body, meta)`, plus `${ServiceName}ErrorRegistry` (runtime dispatch map) and `${ServiceName}ProcedureErrorUnion` (type union). Defaults: `ApiErrors`, `ApiProcedureError`, `ApiErrorRegistry`, `ApiProcedureErrorUnion`.
 By default, types are wrapped in nested TS namespaces (`Scope.Route.Params`), JSDoc comments are emitted, and output is self-contained (no runtime dependency on `ts-procedures`). Use `--no-namespace-types` to revert to flat type names (`RouteParams`); this also disables the outer service namespace in `index.ts` and skips importing `_errors` from there.

package/agent_config/cursor/cursorrules

@@ -280,6 +280,8 @@ try {
 
 Per-route error unions: routes with `errors: [...]` get an `Errors` type in their namespace (e.g. `Users.GetUser.Errors = ApiErrors.UseCaseError | ApiErrors.AuthError`).
 
+- Generated client error handling: catch the framework classes (`ClientHttpError`, `ClientNetworkError`, `ClientTimeoutError`, `ClientAbortError`), not raw `DOMException`/`TypeError` — the framework normalizes platform errors at the `executeCall` boundary, so raw platform errors no longer reach `catch` blocks after 7.0.0 (original is on `error.cause`). Use the `.safe()` sibling on RPC/API callables for an exhaustive `Result<T, E>` switch (`ok`, `typed`, `http`, `network`, `timeout`, `aborted`, `parse`, `usage`, `unknown`). Streams keep the throwing form — no `.safe()`.
+
 ## Lifecycle Hook Order
 
 ### Standard RPC
@@ -327,6 +329,7 @@ onRequestStart → factoryContext() → validation → onStreamStart → handler
 9. **Never assume extra params fields survive** — `removeAdditional: true` strips them
 10. **Never manually parse types AJV coerces** — `coerceTypes: true` handles it
 11. **Never define both schema.params and schema.input** — mutually exclusive, throws ProcedureRegistrationError
+12. **Never catch raw DOMException/TypeError from generated callables** — catch `ClientTimeoutError`, `ClientAbortError`, `ClientNetworkError` instead; or use `.safe()` for Result-based narrowing
 
 ## Testing
 
@@ -387,6 +390,7 @@ npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated
 ```
 
 For Kotlin codegen (Android/JVM consumers), see `docs/codegen-kotlin.md` in the ts-procedures repo. The Kotlin target is types-only; consumer apps own HTTP/error handling.
+For Swift codegen (iOS/macOS/Apple-platform consumers), see `docs/codegen-swift.md` in the ts-procedures repo. The Swift target is types-only; consumer apps own HTTP/error handling.
 
 Generates one `.ts` file per scope plus a root `index.ts` that imports each scope as a namespace and exports a `create${ServiceName}Bindings(client)` factory AND a `create${ServiceName}Client(config)` convenience factory that pre-wires the error registry (defaults to `createApiBindings` / `createApiClient`; pass `--service-name <Name>` to rename). When namespace mode is on (the default), `index.ts` also wraps every scope namespace in an outer `export namespace ${ServiceName} { ... }` block so types are reachable as `Api.Users.GetUser.Params`, `Api.Errors.UseCaseError`, etc. The errors file (`_errors.ts`) emits runtime error classes extending a shared `${ServiceName}ProcedureError` base, each with `static fromResponse(body, meta)`, plus `${ServiceName}ErrorRegistry` (runtime dispatch map) and `${ServiceName}ProcedureErrorUnion` (type union). Defaults: `ApiErrors`, `ApiProcedureError`, `ApiErrorRegistry`, `ApiProcedureErrorUnion`.
 By default, types are wrapped in nested TS namespaces (`Scope.Route.Params`), JSDoc comments are emitted, and output is self-contained (no runtime dependency on `ts-procedures`). Use `--no-namespace-types` to revert to flat type names (`RouteParams`); this also disables the outer service namespace in `index.ts` and skips importing `_errors` from there.

package/agent_config/lib/install-claude.mjs

@@ -6,7 +6,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const SOURCE_DIR = join(__dirname, '..', 'claude-code');
 
-const SKILL_NAMES = ['ts-procedures', 'ts-procedures-review', 'ts-procedures-scaffold'];
+const SKILL_NAMES = ['ts-procedures', 'ts-procedures-review', 'ts-procedures-scaffold', 'ts-procedures-kotlin', 'ts-procedures-swift'];
 const AGENT_FILES = ['ts-procedures-architect.md'];
 
 function listFilesRecursive(dir) {

package/build/client/augment-error-map.test-d.d.ts

@@ -0,0 +1,10 @@
+declare class RateLimitError extends Error {
+    retryAfter: number;
+    constructor(retryAfter: number);
+}
+declare module './types.js' {
+    interface ClientErrorMap {
+        rateLimited: RateLimitError;
+    }
+}
+export {};