@zap-studio/fetch 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -1,145 +1,134 @@
 # @zap-studio/fetch
 
-## 0.4.5
+## 0.4.7
 
 ### Patch Changes
 
-- Updated dependencies [f75b984]
-  - @zap-studio/validation@0.3.0
+- e26293e: Updated dependencies.
+  - @zap-studio/validation@0.3.2
 
-## 0.4.4
+## 0.4.6
 
 ### Patch Changes
 
-- 59a8d71: Fix request body handling for JSON payloads.
+- 5ea3d3b: Updated dependencies.
+  - @zap-studio/validation@0.3.1
 
-  - Accept JSON values (including arrays) in `ExtendedRequestInit.body`
-  - Auto-stringify plain JSON body values regardless of whether a response schema is provided
-  - Set `Content-Type: application/json` only when auto-stringifying and no explicit content type is set
+## 0.4.5
 
-## 0.4.3
+### Dependencies
 
-### Patch Changes
+- f75b984: Updated dependency `@zap-studio/validation` to `0.3.0`.
 
-- e4542bb: Refine `standardValidate` typings so the return type depends on the `throwOnError` flag, and update `@zap-studio/fetch` to integrate with the new overloads while preserving its boolean configuration API.
-- Updated dependencies [e4542bb]
-  - @zap-studio/validation@0.2.1
+## 0.4.4
 
-## 0.4.2
+### Fixed
 
-### Patch Changes
+- 59a8d71: Fixed JSON request body handling.
+  - Accept JSON values (including arrays) in `ExtendedRequestInit.body`.
+  - Auto-stringify plain JSON body values even when no response schema is provided.
+  - Set `Content-Type: application/json` only when auto-stringifying and no explicit content type is set.
 
-- Updated dependencies [2de8183]
-  - @zap-studio/validation@0.2.0
+## 0.4.3
 
-## 0.4.1
+### Changed
 
-### Patch Changes
+- e4542bb: Refined `standardValidate` typings so return types depend on `throwOnError`, and updated `@zap-studio/fetch` integration while preserving the existing boolean configuration API.
 
-- 447dbda: Extract shared Standard Schema validation utilities into `@zap-studio/validation` and update `@zap-studio/fetch` to depend on them.
-- Updated dependencies [447dbda]
-  - @zap-studio/validation@0.1.0
+### Dependencies
 
-## 0.4.0
+- e4542bb: Updated dependency `@zap-studio/validation` to `0.2.1`.
 
-### Minor Changes
+## 0.4.2
 
-- 69057cd: Expose fetch defaults constants and utility helpers as public exports.
+### Dependencies
 
-## 0.3.1
+- 2de8183: Updated dependency `@zap-studio/validation` to `0.2.0`.
 
-### Patch Changes
+## 0.4.1
 
-- 9919f63: Add discriminated return types based on `throwOnValidationError` option
+### Changed
 
-  The return type of `$fetch` and `api.*` methods now correctly narrows based on the `throwOnValidationError` option:
+- 447dbda: Switched shared Standard Schema validation utilities to `@zap-studio/validation`.
 
-  - When `throwOnValidationError: true` (default) or unspecified: returns `Promise<TSchema>` (the validated data directly)
-  - When `throwOnValidationError: false`: returns `Promise<StandardSchemaV1.Result<TSchema>>` (the result object with `value` or `issues`)
+### Dependencies
 
-  This improves type safety by eliminating the need for manual type narrowing when using the default behavior.
+- 447dbda: Updated dependency `@zap-studio/validation` to `0.1.0`.
 
-## 0.3.0
+## 0.4.0
 
-### Minor Changes
+### Added
 
-- 659621c: Add `searchParams` option to `createFetch` to allow factory-level default query/search parameters. Per-request `searchParams` continue to override factory defaults.
+- 69057cd: Exposed fetch defaults constants and utility helpers as public exports.
 
-## 0.2.2
+## 0.3.1
 
-### Patch Changes
+### Changed
 
-- 5c3abbf: Prepare JSR publish and isolatedDeclarations support with new explicit types for `$Fetch` and `ApiMethods`
+- 9919f63: Added discriminated return types based on `throwOnValidationError`.
+  - `throwOnValidationError: true` (default) returns `Promise<TSchema>`.
+  - `throwOnValidationError: false` returns `Promise<StandardSchemaV1.Result<TSchema>>`.
+  - This improves type safety and removes manual narrowing in default usage.
 
-## 0.2.1
+## 0.3.0
 
-### Patch Changes
+### Added
 
-- 82bac5c: Replace regex-based slash trimming with more efficient string manipulation functions for URL normalization
+- 659621c: Added `searchParams` support in `createFetch` for factory-level default query parameters.
+  - Per-request `searchParams` still override factory defaults.
 
-## 0.2.0
+## 0.2.2
 
-### Minor Changes
+### Changed
 
-- 78afb76: ### Standard Schema Support
+- 5c3abbf: Prepared JSR publish and `isolatedDeclarations` support with explicit `$Fetch` and `ApiMethods` types.
 
-  Migrated from Zod-only validation to **Standard Schema v1** specification, enabling support for multiple validation libraries:
+## 0.2.1
 
-  - Zod
-  - Valibot
-  - ArkType
-  - Any Standard Schema compliant library
+### Changed
 
-  ### New Features
+- 82bac5c: Replaced regex-based slash trimming with more efficient string manipulation for URL normalization.
 
-  - **Factory Pattern**: `createFetch()` for creating pre-configured fetch instances with `baseURL`, default `headers`, and error handling options
-  - **Smart URL Handling**: Absolute URLs bypass `baseURL` configuration
-  - **Auto JSON Body**: Automatic `JSON.stringify()` and `Content-Type` header when using schemas with request bodies
+## 0.2.0
 
-  ### Breaking Changes
+### Changed
 
-  - Schema validation now requires Standard Schema compliant libraries (Zod 3.23+, Valibot 1.0+, ArkType 2.0+)
-  - Internal file structure reorganized (affects deep imports if any were used)
-  - `FetchError` constructor signature changed: now requires `(message, response)`
+- 78afb76: Migrated from Zod-only validation to Standard Schema v1 for broader validator compatibility.
+  - Supported libraries include Zod, Valibot, ArkType, and other Standard Schema-compliant validators.
 
-  ### Migration Guide
+### Added
 
-  ```typescript
-  // Before (Zod-only)
-  import { $fetch } from "@zap-studio/fetch";
-  import { z } from "zod";
+- 78afb76: Added `createFetch()` factory pattern for pre-configured instances.
+- 78afb76: Added smart URL behavior so absolute URLs bypass `baseURL`.
+- 78afb76: Added automatic JSON body serialization and `Content-Type` handling for schema-based requests.
 
-  // After (Standard Schema - works the same with Zod!)
-  import { $fetch } from "@zap-studio/fetch";
-  import { z } from "zod"; // Zod 3.23+ is Standard Schema compliant
+### Breaking
 
-  // Or use other libraries
-  import * as v from "valibot";
-  import { type } from "arktype";
-  ```
+- 78afb76: Standard Schema-compliant validator libraries are now required (for example Zod 3.23+, Valibot 1.0+, ArkType 2.0+).
+- 78afb76: Internal file structure was reorganized (affects deep imports).
+- 78afb76: `FetchError` constructor now requires `(message, response)`.
 
 ## 0.1.2
 
-### Patch Changes
+### Changed
 
-- 69c2b21: Change `safeFetch` to `$fetch` syntax and make sure `safeFetch` can also be used for legacy
+- 69c2b21: Renamed `safeFetch` to `$fetch` while preserving `safeFetch` compatibility for legacy usage.
 
 ## 0.1.1
 
-### Patch Changes
+### Changed
 
-- 5f1812b: Change files field in package.json to distribute only necessary artifacts
+- 5f1812b: Updated `files` in `package.json` to publish only required artifacts.
 
 ## 0.1.0
 
-### Minor Changes
-
-- 1644006: Comprehensive description of the initial release features including:
+### Added
 
-  - Type-safe HTTP requests with Zod validation
-  - Automatic content-type handling
-  - Multiple response type support
-  - Convenient API methods (GET, POST, PUT, PATCH, DELETE)
-  - Flexible error handling
-  - Custom FetchError class
-  - Full TypeScript support
+- 1644006: Initial release of `@zap-studio/fetch`.
+  - Type-safe HTTP requests with Zod validation.
+  - Automatic content-type handling.
+  - Multiple response type support.
+  - API methods for GET, POST, PUT, PATCH, and DELETE.
+  - Flexible error handling.
+  - Custom `FetchError` class.
+  - Full TypeScript support.

package/bin/intent.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Auto-generated by @tanstack/intent setup
+// Exposes the intent end-user CLI for consumers of this library.
+await import("@tanstack/intent/intent-library");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zap-studio/fetch",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "type": "module",
   "license": "MIT",
   "private": false,
@@ -34,12 +34,15 @@
   "files": [
     "dist",
     "CHANGELOG.md",
-    "LICENSE.md",
-    "README.md"
+    "LICENSE",
+    "README.md",
+    "skills",
+    "bin",
+    "!skills/_artifacts"
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
-    "@zap-studio/validation": "0.3.0"
+    "@zap-studio/validation": "0.3.2"
   },
   "devDependencies": {
     "@types/node": "^25.0.2",
@@ -50,9 +53,9 @@
     "valibot": "^1.2.0",
     "vitest": "^4.0.18",
     "zod": "^4.2.0",
-    "@zap-studio/vitest-config": "0.0.0",
     "@zap-studio/tsdown-config": "0.0.0",
-    "@zap-studio/typescript-config": "0.0.0"
+    "@zap-studio/typescript-config": "0.0.0",
+    "@zap-studio/vitest-config": "0.0.0"
   },
   "exports": {
     ".": "./dist/index.mjs",
@@ -65,9 +68,12 @@
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
+  "bin": {
+    "intent": "./bin/intent.js"
+  },
   "scripts": {
     "build": "tsdown --config tsdown.config.ts",
-    "check": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest --watch"
   }

package/skills/zap-fetch-typed-http/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: zap-fetch-typed-http
+description: >
+  Implement type-safe HTTP requests with @zap-studio/fetch using $fetch,
+  api.get/post/put/patch/delete, createFetch defaults, searchParams merging,
+  and throwOnFetchError/throwOnValidationError return modes.
+type: core
+library: '@zap-studio/fetch'
+library_version: '0.4.6'
+sources:
+  - 'zap-studio/monorepo:packages/fetch/README.md'
+  - 'zap-studio/monorepo:packages/fetch/src/index.ts'
+  - 'zap-studio/monorepo:packages/fetch/src/utils.ts'
+---
+
+# @zap-studio/fetch — Typed HTTP Client
+
+## Setup
+
+```ts
+import { createFetch } from '@zap-studio/fetch';
+import { z } from 'zod';
+
+const UserSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+const { api } = createFetch({
+  baseURL: 'https://api.example.com',
+  headers: { Authorization: 'Bearer token' },
+  searchParams: { locale: 'en' },
+});
+
+const user = await api.get('/users/1', UserSchema);
+```
+
+## Core Patterns
+
+### Return raw `Response` when no schema is provided
+
+```ts
+import { $fetch } from '@zap-studio/fetch';
+
+const response = await $fetch('https://api.example.com/health');
+const data = await response.json();
+```
+
+### Request validated payload via schema
+
+```ts
+import { api } from '@zap-studio/fetch';
+import { z } from 'zod';
+
+const PostSchema = z.object({ id: z.number(), title: z.string() });
+const post = await api.get('https://api.example.com/posts/1', PostSchema);
+```
+
+### Handle non-throw validation mode explicitly
+
+```ts
+import { $fetch } from '@zap-studio/fetch';
+import { z } from 'zod';
+
+const UserSchema = z.object({ id: z.number() });
+
+const result = await $fetch('/users/1', UserSchema, {
+  throwOnValidationError: false,
+});
+
+if (result.issues) {
+  throw new Error('Invalid response payload');
+}
+
+console.log(result.value.id);
+```
+
+## Common Mistakes
+
+### HIGH Assuming `api.get` returns raw `Response`
+
+Wrong:
+
+```ts
+const res = await api.get('/users/1', { headers: { Authorization: token } });
+const body = await res.json();
+```
+
+Correct:
+
+```ts
+const user = await api.get('/users/1', UserSchema, {
+  headers: { Authorization: token },
+});
+console.log(user.id);
+```
+
+`api.*` overloads are schema-based helpers; they return validated payloads, not a `Response`.
+
+Source: zap-studio/monorepo:packages/fetch/src/index.ts
+
+### HIGH Ignoring validation result branch
+
+Wrong:
+
+```ts
+const user = await $fetch('/users/1', UserSchema, {
+  throwOnValidationError: false,
+});
+console.log(user.id);
+```
+
+Correct:
+
+```ts
+const result = await $fetch('/users/1', UserSchema, {
+  throwOnValidationError: false,
+});
+
+if (result.issues) throw new Error('Invalid payload');
+console.log(result.value.id);
+```
+
+With `throwOnValidationError: false`, return type is `{ value?, issues? }` and must be narrowed.
+
+Source: zap-studio/monorepo:packages/fetch/src/index.ts
+
+### MEDIUM Relying on implicit body semantics for non-JSON inputs
+
+Wrong:
+
+```ts
+await api.post('/users', UserSchema, {
+  body: new URLSearchParams({ name: 'Ada' }),
+});
+```
+
+Correct:
+
+```ts
+await api.post('/users', UserSchema, {
+  body: { name: 'Ada' },
+  headers: { 'Content-Type': 'application/json' },
+});
+```
+
+Only plain object bodies are auto-JSON-stringified; other `BodyInit` forms keep their native encoding behavior.
+
+Source: zap-studio/monorepo:packages/fetch/src/utils.ts
+
+See also: zap-validation-standard-schema/SKILL.md — response validation result handling.