@porulle/sdk 0.1.0 → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unified-commerce-engine contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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.6.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -18,26 +18,20 @@
   "bin": {
     "unifiedcommerce-sdk": "./dist/cli.js"
   },
-  "scripts": {
-    "build": "rm -rf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
-    "check-types": "tsc --noEmit",
-    "lint": "eslint . --max-warnings 1000",
-    "test": "vitest run"
-  },
   "dependencies": {
     "openapi-fetch": "^0.17.0",
     "openapi-typescript-helpers": "^0.1.0"
   },
   "devDependencies": {
-    "@repo/eslint-config": "*",
-    "@repo/typescript-config": "*",
     "@types/node": "^24.5.2",
     "eslint": "^9.39.1",
     "openapi-react-query": "^0.5.4",
     "@tanstack/react-query": "^5.94.5",
     "openapi-typescript": "^7.13.0",
     "typescript": "5.9.2",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@porulle/eslint-config": "0.1.0",
+    "@porulle/typescript-config": "0.1.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",
@@ -73,5 +67,11 @@
     "url": "git+https://github.com/asyncdotengineering/porulle.git",
     "directory": "packages/sdk"
   },
-  "author": "Porulle contributors"
-}
+  "author": "Porulle contributors",
+  "scripts": {
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run"
+  }
+}

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";