@porulle/sdk 0.1.0 → 0.5.0

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Client-side helpers for the uniform API error envelope.
+ *
+ * The server returns `{ error: { code, message, details?: { issues[] } } }`.
+ * `openapi-fetch` surfaces that body as the `error` field of a result, or it
+ * may arrive as a thrown value. These helpers normalize either shape so forms
+ * can bind field errors without ad-hoc parsing.
+ */
+export interface ValidationIssue {
+    path: string;
+    message: string;
+    code?: string;
+}
+export interface ApiErrorBody {
+    code: string;
+    message: string;
+    details?: {
+        issues?: ValidationIssue[];
+        [key: string]: unknown;
+    };
+}
+/** Type guard: is this value a Porulle API error (envelope or bare body)? */
+export declare function isApiError(e: unknown): boolean;
+/**
+ * Flatten an API error into field-level and form-level messages for binding
+ * to a form. `fieldErrors` is keyed by the issue's dotted path; `formError`
+ * is the top-level message.
+ *
+ * ```ts
+ * const { data, error } = await client.POST("/api/things", { body });
+ * if (error) {
+ *   const { fieldErrors, formError } = mapApiErrorToFields(error);
+ * }
+ * ```
+ */
+export declare function mapApiErrorToFields(e: unknown): {
+    fieldErrors: Record<string, string>;
+    formError: string;
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;CAClE;AA+BD,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAE9C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG;IAC/C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;CACnB,CASA"}

package/dist/errors.js

@@ -0,0 +1,61 @@
+/**
+ * Client-side helpers for the uniform API error envelope.
+ *
+ * The server returns `{ error: { code, message, details?: { issues[] } } }`.
+ * `openapi-fetch` surfaces that body as the `error` field of a result, or it
+ * may arrive as a thrown value. These helpers normalize either shape so forms
+ * can bind field errors without ad-hoc parsing.
+ */
+/** Pull the inner error body out of an envelope, a bare body, or a thrown wrapper. */
+function extractErrorBody(e) {
+    if (!e || typeof e !== "object")
+        return undefined;
+    const obj = e;
+    // Full envelope: { error: { code, message, details } }
+    if (obj.error && typeof obj.error === "object") {
+        const inner = obj.error;
+        if (typeof inner.code === "string" && typeof inner.message === "string") {
+            return inner;
+        }
+    }
+    // Bare body: { code, message, details }
+    if (typeof obj.code === "string" && typeof obj.message === "string") {
+        return obj;
+    }
+    // Thrown wrapper exposing the body on common fields.
+    for (const key of ["body", "data", "response"]) {
+        if (obj[key]) {
+            const nested = extractErrorBody(obj[key]);
+            if (nested)
+                return nested;
+        }
+    }
+    return undefined;
+}
+/** Type guard: is this value a Porulle API error (envelope or bare body)? */
+export function isApiError(e) {
+    return extractErrorBody(e) !== undefined;
+}
+/**
+ * Flatten an API error into field-level and form-level messages for binding
+ * to a form. `fieldErrors` is keyed by the issue's dotted path; `formError`
+ * is the top-level message.
+ *
+ * ```ts
+ * const { data, error } = await client.POST("/api/things", { body });
+ * if (error) {
+ *   const { fieldErrors, formError } = mapApiErrorToFields(error);
+ * }
+ * ```
+ */
+export function mapApiErrorToFields(e) {
+    const body = extractErrorBody(e);
+    const fieldErrors = {};
+    for (const issue of body?.details?.issues ?? []) {
+        if (issue.path && fieldErrors[issue.path] === undefined) {
+            fieldErrors[issue.path] = issue.message;
+        }
+    }
+    return { fieldErrors, formError: body?.message ?? "" };
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH,sFAAsF;AACtF,SAAS,gBAAgB,CAAC,CAAU;IAClC,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAClD,MAAM,GAAG,GAAG,CAA4B,CAAC;IAEzC,uDAAuD;IACvD,IAAI,GAAG,CAAC,KAAK,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAgC,CAAC;QACnD,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YACxE,OAAO,KAAgC,CAAC;QAC1C,CAAC;IACH,CAAC;IAED,wCAAwC;IACxC,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACpE,OAAO,GAA8B,CAAC;IACxC,CAAC;IAED,qDAAqD;IACrD,KAAK,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC;QAC/C,IAAI,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1C,IAAI,MAAM;gBAAE,OAAO,MAAM,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,UAAU,CAAC,CAAU;IACnC,OAAO,gBAAgB,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAU;IAI5C,MAAM,IAAI,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACjC,MAAM,WAAW,GAA2B,EAAE,CAAC;IAC/C,KAAK,MAAM,KAAK,IAAI,IAAI,EAAE,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,CAAC;QAChD,IAAI,KAAK,CAAC,IAAI,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YACxD,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC;QAC1C,CAAC;IACH,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,IAAI,EAAE,EAAE,CAAC;AACzD,CAAC"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { createSDK, createClient, type SDKOptions } from "./client.js";
 export { authMiddleware, type AuthCredential, type ApiKeyAuth, type BearerAuth } from "./middleware.js";
+export { isApiError, mapApiErrorToFields, type ApiErrorBody, type ValidationIssue, } from "./errors.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxG,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { createSDK, createClient } from "./client.js";
 export { authMiddleware } from "./middleware.js";
+export { isApiError, mapApiErrorToFields, } from "./errors.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAmB,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,cAAc,EAAyD,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAmB,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,cAAc,EAAyD,MAAM,iBAAiB,CAAC;AACxG,OAAO,EACL,UAAU,EACV,mBAAmB,GAGpB,MAAM,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/sdk",
-  "version": "0.1.0",
+  "version": "0.5.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -29,8 +29,8 @@
     "openapi-typescript-helpers": "^0.1.0"
   },
   "devDependencies": {
-    "@repo/eslint-config": "*",
-    "@repo/typescript-config": "*",
+    "@porulle/eslint-config": "*",
+    "@porulle/typescript-config": "*",
     "@types/node": "^24.5.2",
     "eslint": "^9.39.1",
     "openapi-react-query": "^0.5.4",

package/src/errors.ts

@@ -0,0 +1,80 @@
+/**
+ * Client-side helpers for the uniform API error envelope.
+ *
+ * The server returns `{ error: { code, message, details?: { issues[] } } }`.
+ * `openapi-fetch` surfaces that body as the `error` field of a result, or it
+ * may arrive as a thrown value. These helpers normalize either shape so forms
+ * can bind field errors without ad-hoc parsing.
+ */
+
+export interface ValidationIssue {
+  path: string;
+  message: string;
+  code?: string;
+}
+
+export interface ApiErrorBody {
+  code: string;
+  message: string;
+  details?: { issues?: ValidationIssue[]; [key: string]: unknown };
+}
+
+/** Pull the inner error body out of an envelope, a bare body, or a thrown wrapper. */
+function extractErrorBody(e: unknown): ApiErrorBody | undefined {
+  if (!e || typeof e !== "object") return undefined;
+  const obj = e as Record<string, unknown>;
+
+  // Full envelope: { error: { code, message, details } }
+  if (obj.error && typeof obj.error === "object") {
+    const inner = obj.error as Record<string, unknown>;
+    if (typeof inner.code === "string" && typeof inner.message === "string") {
+      return inner as unknown as ApiErrorBody;
+    }
+  }
+
+  // Bare body: { code, message, details }
+  if (typeof obj.code === "string" && typeof obj.message === "string") {
+    return obj as unknown as ApiErrorBody;
+  }
+
+  // Thrown wrapper exposing the body on common fields.
+  for (const key of ["body", "data", "response"]) {
+    if (obj[key]) {
+      const nested = extractErrorBody(obj[key]);
+      if (nested) return nested;
+    }
+  }
+
+  return undefined;
+}
+
+/** Type guard: is this value a Porulle API error (envelope or bare body)? */
+export function isApiError(e: unknown): boolean {
+  return extractErrorBody(e) !== undefined;
+}
+
+/**
+ * Flatten an API error into field-level and form-level messages for binding
+ * to a form. `fieldErrors` is keyed by the issue's dotted path; `formError`
+ * is the top-level message.
+ *
+ * ```ts
+ * const { data, error } = await client.POST("/api/things", { body });
+ * if (error) {
+ *   const { fieldErrors, formError } = mapApiErrorToFields(error);
+ * }
+ * ```
+ */
+export function mapApiErrorToFields(e: unknown): {
+  fieldErrors: Record<string, string>;
+  formError: string;
+} {
+  const body = extractErrorBody(e);
+  const fieldErrors: Record<string, string> = {};
+  for (const issue of body?.details?.issues ?? []) {
+    if (issue.path && fieldErrors[issue.path] === undefined) {
+      fieldErrors[issue.path] = issue.message;
+    }
+  }
+  return { fieldErrors, formError: body?.message ?? "" };
+}

package/src/index.ts

@@ -1,2 +1,8 @@
 export { createSDK, createClient, type SDKOptions } from "./client.js";
 export { authMiddleware, type AuthCredential, type ApiKeyAuth, type BearerAuth } from "./middleware.js";
+export {
+  isApiError,
+  mapApiErrorToFields,
+  type ApiErrorBody,
+  type ValidationIssue,
+} from "./errors.js";