@codewithagents/api-errors 0.1.0

package/README.md

@@ -0,0 +1,113 @@
+# @codewithagents/api-errors
+
+Backend API errors don't automatically map to form field errors. Every project writes the same glue code from scratch: catch the error, inspect its shape, figure out which field each message belongs to, then call your form library's error setter. This package does that for you — framework-agnostic core with a first-class React Hook Form adapter.
+
+## Installation
+
+```bash
+npm install @codewithagents/api-errors
+```
+
+## Usage
+
+### With React Hook Form
+
+```tsx
+import { useForm } from 'react-hook-form'
+import { mapApiErrors } from '@codewithagents/api-errors'
+
+function SignupForm() {
+  const { register, handleSubmit, setError, formState: { errors } } = useForm()
+
+  const onSubmit = async (data) => {
+    try {
+      await api.post('/signup', data)
+    } catch (error) {
+      // Automatically maps backend field errors to RHF setError calls
+      mapApiErrors(error, setError)
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email')} />
+      {errors.email && <p>{errors.email.message}</p>}
+
+      <input {...register('name')} />
+      {errors.name && <p>{errors.name.message}</p>}
+
+      <button type="submit">Sign up</button>
+    </form>
+  )
+}
+```
+
+### Standalone with `extractFieldErrors`
+
+Use `extractFieldErrors` when you need the normalized error list without a form library:
+
+```ts
+import { extractFieldErrors } from '@codewithagents/api-errors'
+
+try {
+  await submitData(payload)
+} catch (error) {
+  const fieldErrors = extractFieldErrors(error)
+  // [{ field: 'email', message: 'must not be blank' }, ...]
+
+  for (const { field, message } of fieldErrors) {
+    console.warn(`${field}: ${message}`)
+  }
+}
+```
+
+You can customize the fallback field name and transform field names:
+
+```ts
+const fieldErrors = extractFieldErrors(error, {
+  fallbackField: 'root',               // used when no field is found (default: 'root')
+  transformField: (f) => f.replace(/([A-Z])/g, '.$1').toLowerCase(), // camelCase → dot.path
+})
+```
+
+## Supported Error Formats
+
+**RFC 7807 Problem Details** (Spring Boot 3+, standard):
+```json
+{
+  "type": "...",
+  "title": "Validation failed",
+  "status": 400,
+  "errors": {
+    "email": ["must not be blank"],
+    "name": ["too short"]
+  }
+}
+```
+
+**Spring Boot default validation format** (older):
+```json
+{
+  "status": 400,
+  "errors": [
+    { "field": "email", "defaultMessage": "must not be blank" }
+  ]
+}
+```
+
+**Simple flat format** (custom APIs):
+```json
+{ "field": "email", "message": "Invalid email" }
+```
+or as an array:
+```json
+[{ "field": "email", "message": "Invalid email" }]
+```
+
+## TypeScript
+
+This package is written in TypeScript and ships full type declarations. No `@types` package needed.
+
+```ts
+import type { FieldError, MapApiErrorsOptions } from '@codewithagents/api-errors'
+```

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Normalized representation of a single field-level error.
+ */
+export interface FieldError {
+    field: string;
+    message: string;
+}
+/**
+ * Options for mapApiErrors and extractFieldErrors.
+ */
+export interface MapApiErrorsOptions {
+    /**
+     * Fallback field name when no field can be determined from the error.
+     * Defaults to 'root'.
+     */
+    fallbackField?: string;
+    /**
+     * Optional transform applied to every field name before it is returned.
+     * Useful for mapping backend camelCase field names to nested React Hook Form
+     * paths, e.g. `"addressCity"` → `"address.city"`.
+     */
+    transformField?: (field: string) => string;
+}
+/**
+ * Extract normalized field errors from an unknown API error response.
+ *
+ * Supports:
+ * - RFC 7807 Problem Details (Spring Boot 3+)
+ * - Spring Boot default validation format
+ * - Simple flat `{ field, message }` object
+ * - Array of `{ field, message }` objects
+ *
+ * Never throws — returns an empty array for unrecognized shapes.
+ */
+export declare function extractFieldErrors(error: unknown, options?: MapApiErrorsOptions): FieldError[];
+/**
+ * React Hook Form adapter.
+ *
+ * Extracts field errors from an unknown API error response and calls
+ * React Hook Form's `setError` for each one.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await submitForm(data)
+ * } catch (error) {
+ *   mapApiErrors(error, setError)
+ * }
+ * ```
+ */
+export declare function mapApiErrors(error: unknown, setError: (field: string, error: {
+    type: string;
+    message: string;
+}) => void, options?: MapApiErrorsOptions): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;CAC3C;AAmID;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,mBAAmB,GAC5B,UAAU,EAAE,CAyCd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,EAC3E,OAAO,CAAC,EAAE,mBAAmB,GAC5B,IAAI,CAKN"}

package/dist/index.js

@@ -0,0 +1,163 @@
+// ---------------------------------------------------------------------------
+// Internal type guards
+// ---------------------------------------------------------------------------
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === 'string');
+}
+// ---------------------------------------------------------------------------
+// Format detectors + parsers
+// ---------------------------------------------------------------------------
+/**
+ * RFC 7807 Problem Details (Spring Boot 3+ default):
+ * { "errors": { "email": ["must not be blank"], "name": ["too short"] } }
+ */
+function tryParseRfc7807(body, fallbackField, transformField) {
+    const { errors } = body;
+    if (!isObject(errors))
+        return null;
+    const result = [];
+    for (const [rawField, messages] of Object.entries(errors)) {
+        const field = transformField(rawField);
+        if (isStringArray(messages)) {
+            for (const message of messages) {
+                result.push({ field, message });
+            }
+        }
+        else if (typeof messages === 'string') {
+            result.push({ field, message: messages });
+        }
+        else {
+            // Unknown value shape — use fallback field with stringified message
+            result.push({ field: transformField(fallbackField), message: String(messages) });
+        }
+    }
+    return result.length > 0 ? result : null;
+}
+/**
+ * Spring Boot default validation format (pre-3):
+ * { "errors": [{ "field": "email", "defaultMessage": "must not be blank" }] }
+ */
+function tryParseSpringArray(body, fallbackField, transformField) {
+    const { errors } = body;
+    if (!Array.isArray(errors))
+        return null;
+    const result = [];
+    for (const item of errors) {
+        if (!isObject(item))
+            continue;
+        const rawField = typeof item['field'] === 'string' ? item['field'] : fallbackField;
+        const message = typeof item['defaultMessage'] === 'string'
+            ? item['defaultMessage']
+            : typeof item['message'] === 'string'
+                ? item['message']
+                : 'Unknown error';
+        result.push({ field: transformField(rawField), message });
+    }
+    return result.length > 0 ? result : null;
+}
+/**
+ * Simple flat object format:
+ * { "field": "email", "message": "Invalid email" }
+ */
+function tryParseFlatObject(body, fallbackField, transformField) {
+    const rawField = typeof body['field'] === 'string' ? body['field'] : null;
+    const message = typeof body['message'] === 'string' ? body['message'] : null;
+    if (message === null)
+        return null;
+    const field = rawField !== null ? rawField : fallbackField;
+    return [{ field: transformField(field), message }];
+}
+/**
+ * Array of simple flat objects:
+ * [{ "field": "email", "message": "Invalid email" }]
+ */
+function tryParseFlatArray(body, fallbackField, transformField) {
+    const result = [];
+    for (const item of body) {
+        if (!isObject(item))
+            continue;
+        const rawField = typeof item['field'] === 'string' ? item['field'] : fallbackField;
+        const message = typeof item['message'] === 'string' ? item['message'] : null;
+        if (message === null)
+            continue;
+        result.push({ field: transformField(rawField), message });
+    }
+    return result.length > 0 ? result : null;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Extract normalized field errors from an unknown API error response.
+ *
+ * Supports:
+ * - RFC 7807 Problem Details (Spring Boot 3+)
+ * - Spring Boot default validation format
+ * - Simple flat `{ field, message }` object
+ * - Array of `{ field, message }` objects
+ *
+ * Never throws — returns an empty array for unrecognized shapes.
+ */
+export function extractFieldErrors(error, options) {
+    const fallbackField = options?.fallbackField ?? 'root';
+    const transformField = options?.transformField ?? ((f) => f);
+    try {
+        // Unwrap common error wrapper shapes (e.g. Axios response, fetch response body)
+        let body = error;
+        // Support objects with a `response.data` shape (Axios-style)
+        if (isObject(body) && isObject(body['response']) && body['response']['data'] !== undefined) {
+            body = body['response']['data'];
+        }
+        // Support objects with a `data` property that contains the actual error body
+        if (isObject(body) && isObject(body['data']) && !('field' in body) && !('errors' in body)) {
+            body = body['data'];
+        }
+        // Array of flat error objects
+        if (Array.isArray(body)) {
+            return tryParseFlatArray(body, fallbackField, transformField) ?? [];
+        }
+        if (!isObject(body))
+            return [];
+        // Try RFC 7807 / Spring Boot 3 format first (object-style errors map)
+        const rfc7807 = tryParseRfc7807(body, fallbackField, transformField);
+        if (rfc7807 !== null)
+            return rfc7807;
+        // Try Spring Boot default format (array-style errors list)
+        const springArray = tryParseSpringArray(body, fallbackField, transformField);
+        if (springArray !== null)
+            return springArray;
+        // Try simple flat object
+        const flat = tryParseFlatObject(body, fallbackField, transformField);
+        if (flat !== null)
+            return flat;
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * React Hook Form adapter.
+ *
+ * Extracts field errors from an unknown API error response and calls
+ * React Hook Form's `setError` for each one.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await submitForm(data)
+ * } catch (error) {
+ *   mapApiErrors(error, setError)
+ * }
+ * ```
+ */
+export function mapApiErrors(error, setError, options) {
+    const fieldErrors = extractFieldErrors(error, options);
+    for (const { field, message } of fieldErrors) {
+        setError(field, { type: 'server', message });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/dist/index.test.js

@@ -0,0 +1,161 @@
+import { describe, expect, it, vi } from 'vitest';
+import { extractFieldErrors, mapApiErrors } from './index.js';
+// ---------------------------------------------------------------------------
+// extractFieldErrors
+// ---------------------------------------------------------------------------
+describe('extractFieldErrors', () => {
+    describe('RFC 7807 / Spring Boot 3+ format', () => {
+        it('maps a single field with one message', () => {
+            const error = { errors: { email: ['must not be blank'] } };
+            expect(extractFieldErrors(error)).toEqual([
+                { field: 'email', message: 'must not be blank' },
+            ]);
+        });
+        it('maps multiple fields', () => {
+            const error = {
+                errors: {
+                    email: ['must not be blank'],
+                    name: ['too short'],
+                },
+            };
+            const result = extractFieldErrors(error);
+            expect(result).toHaveLength(2);
+            expect(result).toContainEqual({ field: 'email', message: 'must not be blank' });
+            expect(result).toContainEqual({ field: 'name', message: 'too short' });
+        });
+        it('expands multiple messages per field into separate FieldErrors', () => {
+            const error = { errors: { email: ['must not be blank', 'invalid format'] } };
+            expect(extractFieldErrors(error)).toEqual([
+                { field: 'email', message: 'must not be blank' },
+                { field: 'email', message: 'invalid format' },
+            ]);
+        });
+    });
+    describe('Spring Boot default validation format (array)', () => {
+        it('maps field + defaultMessage', () => {
+            const error = {
+                status: 400,
+                errors: [{ field: 'email', defaultMessage: 'must not be blank' }],
+            };
+            expect(extractFieldErrors(error)).toEqual([
+                { field: 'email', message: 'must not be blank' },
+            ]);
+        });
+        it('falls back to message when defaultMessage is absent', () => {
+            const error = {
+                errors: [{ field: 'email', message: 'must not be blank' }],
+            };
+            expect(extractFieldErrors(error)).toEqual([
+                { field: 'email', message: 'must not be blank' },
+            ]);
+        });
+        it('maps multiple entries', () => {
+            const error = {
+                errors: [
+                    { field: 'email', defaultMessage: 'must not be blank' },
+                    { field: 'name', defaultMessage: 'too short' },
+                ],
+            };
+            expect(extractFieldErrors(error)).toHaveLength(2);
+        });
+    });
+    describe('flat object format', () => {
+        it('maps { field, message } directly', () => {
+            const error = { field: 'email', message: 'Invalid email' };
+            expect(extractFieldErrors(error)).toEqual([
+                { field: 'email', message: 'Invalid email' },
+            ]);
+        });
+        it('uses fallbackField when field is absent', () => {
+            const error = { message: 'Something went wrong' };
+            expect(extractFieldErrors(error, { fallbackField: 'root' })).toEqual([
+                { field: 'root', message: 'Something went wrong' },
+            ]);
+        });
+    });
+    describe('flat array format', () => {
+        it('maps an array of { field, message } objects', () => {
+            const error = [
+                { field: 'email', message: 'Invalid' },
+                { field: 'name', message: 'Required' },
+            ];
+            expect(extractFieldErrors(error)).toEqual([
+                { field: 'email', message: 'Invalid' },
+                { field: 'name', message: 'Required' },
+            ]);
+        });
+        it('skips entries without a message', () => {
+            const error = [{ field: 'email' }, { field: 'name', message: 'Required' }];
+            expect(extractFieldErrors(error)).toEqual([
+                { field: 'name', message: 'Required' },
+            ]);
+        });
+    });
+    describe('Axios-style response wrapper', () => {
+        it('unwraps response.data before parsing', () => {
+            const error = {
+                response: {
+                    data: { errors: { email: ['must not be blank'] } },
+                },
+            };
+            expect(extractFieldErrors(error)).toEqual([
+                { field: 'email', message: 'must not be blank' },
+            ]);
+        });
+    });
+    describe('unrecognized / unknown shapes', () => {
+        it('returns [] for an unrecognized object', () => {
+            expect(extractFieldErrors({ foo: 'bar' })).toEqual([]);
+        });
+        it('returns [] for null', () => {
+            expect(extractFieldErrors(null)).toEqual([]);
+        });
+        it('returns [] for undefined', () => {
+            expect(extractFieldErrors(undefined)).toEqual([]);
+        });
+        it('returns [] for a plain string', () => {
+            expect(extractFieldErrors('something went wrong')).toEqual([]);
+        });
+        it('never throws', () => {
+            expect(() => extractFieldErrors({ deeply: { nested: { evil: true } } })).not.toThrow();
+        });
+    });
+    describe('options', () => {
+        it('uses fallbackField for errors without a field name', () => {
+            const error = { message: 'Unauthorised' };
+            const result = extractFieldErrors(error, { fallbackField: 'serverError' });
+            expect(result).toEqual([{ field: 'serverError', message: 'Unauthorised' }]);
+        });
+        it('applies transformField to every resolved field name', () => {
+            const error = { errors: { emailAddress: ['invalid'] } };
+            const result = extractFieldErrors(error, {
+                transformField: (f) => f.replace(/([A-Z])/g, '.$1').toLowerCase(),
+            });
+            expect(result).toEqual([{ field: 'email.address', message: 'invalid' }]);
+        });
+    });
+});
+// ---------------------------------------------------------------------------
+// mapApiErrors
+// ---------------------------------------------------------------------------
+describe('mapApiErrors', () => {
+    it('calls setError for each field error with type "server"', () => {
+        const setError = vi.fn();
+        const error = { errors: { email: ['must not be blank'], name: ['too short'] } };
+        mapApiErrors(error, setError);
+        expect(setError).toHaveBeenCalledTimes(2);
+        expect(setError).toHaveBeenCalledWith('email', { type: 'server', message: 'must not be blank' });
+        expect(setError).toHaveBeenCalledWith('name', { type: 'server', message: 'too short' });
+    });
+    it('never calls setError for unrecognized errors', () => {
+        const setError = vi.fn();
+        mapApiErrors({ foo: 'bar' }, setError);
+        expect(setError).not.toHaveBeenCalled();
+    });
+    it('never calls setError for null', () => {
+        const setError = vi.fn();
+        mapApiErrors(null, setError);
+        expect(setError).not.toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/dist/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@codewithagents/api-errors",
+  "version": "0.1.0",
+  "description": "Map backend API errors to form field errors. Framework-agnostic core with React Hook Form adapter.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "api",
+    "errors",
+    "form",
+    "react-hook-form",
+    "validation",
+    "typescript"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  }
+}