@eleva-io/erp-sdk 0.1.150 → 0.1.152

package/dist/cjs/src/errors/catalog_base.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASE_ERRORS_CATALOG = exports.BASE_ERROR_CODES = void 0;
+const zod_1 = require("zod");
+const catalog_types_1 = require("./catalog_types");
+/**
+ * Generic HTTP-level error codes shared across all API domains.
+ * Domain-specific codes live in `catalog_api.ts`.
+ */
+var BASE_ERROR_CODES;
+(function (BASE_ERROR_CODES) {
+    // >= 400
+    /** Input data failed schema or business-rule validation. */
+    BASE_ERROR_CODES["VALIDATION"] = "VALIDATION";
+    /** The request is malformed or contains invalid parameters. */
+    BASE_ERROR_CODES["BAD_REQUEST"] = "BAD_REQUEST";
+    /** Credentials are missing, expired, or invalid. */
+    BASE_ERROR_CODES["AUTHENTICATION"] = "AUTHENTICATION";
+    /** Authenticated but lacks the required permissions. */
+    BASE_ERROR_CODES["UNAUTHORIZED"] = "UNAUTHORIZED";
+    /** The requested resource does not exist. */
+    BASE_ERROR_CODES["NOT_FOUND"] = "NOT_FOUND";
+    /** Server cannot produce a response matching the `Accept` header. */
+    BASE_ERROR_CODES["NOT_ACCEPTABLE"] = "NOT_ACCEPTABLE";
+    /** Operation would violate a uniqueness or integrity constraint. */
+    BASE_ERROR_CODES["CONFLICT"] = "CONFLICT";
+    /** Resource existed but has been permanently removed (unlike 404, retrying is futile). */
+    BASE_ERROR_CODES["GONE"] = "GONE";
+    /** Request is syntactically valid but semantically unprocessable (e.g. invalid state transition). */
+    BASE_ERROR_CODES["UNPROCESSABLE_ENTITY"] = "UNPROCESSABLE_ENTITY";
+    /** A required field was omitted from the request. */
+    BASE_ERROR_CODES["MANDATORY_FIELD"] = "MANDATORY_FIELD";
+    // >= 500
+    /** Unexpected server-side error (`SYSTEM` — message sanitised before being sent to clients). */
+    BASE_ERROR_CODES["INTERNAL_SERVER_ERROR"] = "INTERNAL_SERVER_ERROR";
+    /** Upstream gateway received an invalid response from the origin server (`SYSTEM`). */
+    BASE_ERROR_CODES["BAD_GATEWAY"] = "BAD_GATEWAY";
+    /** Service is temporarily unavailable (`SYSTEM`). */
+    BASE_ERROR_CODES["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
+})(BASE_ERROR_CODES || (exports.BASE_ERROR_CODES = BASE_ERROR_CODES = {}));
+/** Maps every `BASE_ERROR_CODES` member to its HTTP status, kind, default message, and details schema. */
+exports.BASE_ERRORS_CATALOG = {
+    // >= 400
+    [BASE_ERROR_CODES.VALIDATION]: {
+        kind: catalog_types_1.ErrorKind.DOMAIN,
+        status: 400,
+        details: zod_1.z.object({
+            errors: zod_1.z
+                .object({
+                /** Dot-separated field path (e.g. `"address.zipCode"`) or `"root"` for top-level issues. */
+                validation: zod_1.z.string(),
+                /** Zod issue code (e.g. `"invalid_type"`, `"too_small"`). */
+                code: zod_1.z.string(),
+                message: zod_1.z.string(),
+                path: zod_1.z.array(zod_1.z.string()),
+            })
+                .array(),
+        }),
+        message: 'Validation error',
+    },
+    [BASE_ERROR_CODES.BAD_REQUEST]: {
+        kind: catalog_types_1.ErrorKind.DOMAIN,
+        status: 400,
+        details: zod_1.z
+            .object({
+            field: zod_1.z.string(),
+            reason: zod_1.z.string(),
+        })
+            .partial(),
+        message: 'Bad request',
+    },
+    [BASE_ERROR_CODES.AUTHENTICATION]: {
+        kind: catalog_types_1.ErrorKind.DOMAIN,
+        status: 401,
+        details: zod_1.z
+            .object({
+            /** Why authentication failed (e.g. `"token_expired"`). */
+            reason: zod_1.z.string(),
+        })
+            .partial(),
+        message: 'Authentication failed',
+    },
+    [BASE_ERROR_CODES.UNAUTHORIZED]: {
+        kind: catalog_types_1.ErrorKind.DOMAIN,
+        status: 403,
+        details: zod_1.z
+            .object({
+            requiredScope: zod_1.z.string(),
+            resource: zod_1.z.string(),
+        })
+            .partial(),
+        message: 'You do not have permission to perform this action',
+    },
+    [BASE_ERROR_CODES.NOT_FOUND]: {
+        kind: catalog_types_1.ErrorKind.DOMAIN,
+        status: 404,
+        details: zod_1.z
+            .object({
+            /** Entity type that was not found (e.g. `"Invoice"`). */
+            entity: zod_1.z.string(),
+        })
+            .partial(),
+        message: 'Not found',
+    },
+    [BASE_ERROR_CODES.NOT_ACCEPTABLE]: {
+        kind: catalog_types_1.ErrorKind.DOMAIN,
+        status: 406,
+        details: zod_1.z
+            .object({
+            acceptedTypes: zod_1.z.array(zod_1.z.string()),
+        })
+            .partial(),
+        message: 'Not acceptable',
+    },
+    /** Each item in the array identifies one conflicting field. */
+    [BASE_ERROR_CODES.CONFLICT]: {
+        kind: catalog_types_1.ErrorKind.DOMAIN,
+        status: 409,
+        details: zod_1.z
+            .object({
+            key: zod_1.z.string(),
+            value: zod_1.z.string(),
+            cause: zod_1.z.string(),
+        })
+            .array(),
+        message: 'Conflict',
+    },
+    [BASE_ERROR_CODES.GONE]: {
+        kind: catalog_types_1.ErrorKind.DOMAIN,
+        status: 410,
+        details: zod_1.z
+            .object({
+            /** ISO 8601 timestamp of when the resource was removed. */
+            since: zod_1.z.string(),
+        })
+            .partial(),
+        message: 'Gone',
+    },
+    [BASE_ERROR_CODES.UNPROCESSABLE_ENTITY]: {
+        kind: catalog_types_1.ErrorKind.DOMAIN,
+        status: 422,
+        details: zod_1.z
+            .object({
+            field: zod_1.z.string(),
+            reason: zod_1.z.string(),
+        })
+            .partial(),
+        message: 'Unprocessable entity',
+    },
+    [BASE_ERROR_CODES.MANDATORY_FIELD]: {
+        kind: catalog_types_1.ErrorKind.DOMAIN,
+        status: 400,
+        details: zod_1.z.object({ field: zod_1.z.string() }),
+        message: 'Mandatory field is missing',
+    },
+    // >= 500
+    [BASE_ERROR_CODES.INTERNAL_SERVER_ERROR]: {
+        kind: catalog_types_1.ErrorKind.SYSTEM,
+        status: 500,
+        details: zod_1.z
+            .object({
+            reason: zod_1.z.string(),
+        })
+            .partial(),
+        message: 'Internal server error',
+    },
+    [BASE_ERROR_CODES.BAD_GATEWAY]: {
+        kind: catalog_types_1.ErrorKind.SYSTEM,
+        status: 502,
+        details: zod_1.z
+            .object({
+            /** Name of the upstream service that returned the invalid response. */
+            upstream: zod_1.z.string(),
+        })
+            .partial(),
+        message: 'Bad gateway',
+    },
+    [BASE_ERROR_CODES.SERVICE_UNAVAILABLE]: {
+        kind: catalog_types_1.ErrorKind.SYSTEM,
+        status: 503,
+        details: zod_1.z
+            .object({
+            /** Seconds the client should wait before retrying. */
+            retryAfter: zod_1.z.number(),
+        })
+            .partial(),
+        message: 'Service unavailable',
+    },
+};
+//# sourceMappingURL=catalog_base.js.map

package/dist/cjs/src/errors/catalog_base.js.map

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

package/dist/cjs/src/errors/catalog_types.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+/**
+ * Classifies an error by origin and visibility.
+ *
+ * - `DOMAIN` – predictable business-logic error; details are safe to expose to the client.
+ * - `SYSTEM` – unexpected infrastructure error; message is sanitised before being sent.
+ */
+export declare enum ErrorKind {
+    SYSTEM = "system",
+    DOMAIN = "domain"
+}
+/**
+ * Source-of-truth definition for a single error code.
+ *
+ * - `kind`    – domain (safe to expose) or system (sanitised).
+ * - `status`  – HTTP status code.
+ * - `details` – Zod schema for both runtime validation and TypeScript type inference.
+ * - `message` – Default human-readable description.
+ */
+export type ErrorCatalogEntry = {
+    kind: ErrorKind;
+    status: number;
+    details: z.ZodTypeAny;
+    message: string;
+};
+/**
+ * Infers the `details` payload type for code `C` by indexing the catalog object `Cat`.
+ * Keeps per-catalog `*ErrorDetails` aliases to a single line.
+ *
+ * @example
+ * export type MyDetails<C extends MY_CODES> = CatalogDetails<C, typeof MY_CATALOG>
+ */
+export type CatalogDetails<C extends string, Cat extends Record<string, {
+    details: z.ZodTypeAny;
+}>> = C extends keyof Cat ? z.infer<Cat[C]['details']> : never;
+//# sourceMappingURL=catalog_types.d.ts.map

package/dist/cjs/src/errors/catalog_types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog_types.d.ts","sourceRoot":"","sources":["../../../../src/errors/catalog_types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;GAKG;AACH,oBAAY,SAAS;IACnB,MAAM,WAAW;IACjB,MAAM,WAAW;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,SAAS,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,CAAC,CAAC,UAAU,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,CACxB,CAAC,SAAS,MAAM,EAChB,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,CAAC,CAAC,UAAU,CAAA;CAAE,CAAC,IACnD,CAAC,SAAS,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,KAAK,CAAA"}

package/dist/cjs/src/errors/catalog_types.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorKind = void 0;
+/**
+ * Classifies an error by origin and visibility.
+ *
+ * - `DOMAIN` – predictable business-logic error; details are safe to expose to the client.
+ * - `SYSTEM` – unexpected infrastructure error; message is sanitised before being sent.
+ */
+var ErrorKind;
+(function (ErrorKind) {
+    ErrorKind["SYSTEM"] = "system";
+    ErrorKind["DOMAIN"] = "domain";
+})(ErrorKind || (exports.ErrorKind = ErrorKind = {}));
+//# sourceMappingURL=catalog_types.js.map

package/dist/cjs/src/errors/catalog_types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog_types.js","sourceRoot":"","sources":["../../../../src/errors/catalog_types.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACH,IAAY,SAGX;AAHD,WAAY,SAAS;IACnB,8BAAiB,CAAA;IACjB,8BAAiB,CAAA;AACnB,CAAC,EAHW,SAAS,yBAAT,SAAS,QAGpB"}

package/dist/cjs/src/errors/errors.d.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+import { ErrorCode, type ErrorDetails } from './catalog';
+import { ErrorKind } from './catalog_types';
+import { BASE_ERROR_CODES } from './catalog_base';
+import { API_ERROR_CODES } from './catalog_api';
+/** Plain-object representation of an `ElevaError`, suitable for serialisation. */
+export interface ElevaErrorJSON<C extends ErrorCode = ErrorCode> {
+    code: C | string;
+    kind: ErrorKind;
+    status: number;
+    message: string;
+    details: ErrorDetails<C>;
+}
+/**
+ * Slim response payload for API consumers.
+ * `SYSTEM` errors omit `details`; `DOMAIN` errors include it.
+ */
+export interface ElevaErrorResponse<C extends ErrorCode = ErrorCode> {
+    code: ElevaErrorJSON<C>['code'];
+    message: ElevaErrorJSON<C>['message'];
+    details?: ElevaErrorJSON<C>['details'];
+}
+/** Constructor arguments for `ElevaError`. Adds optional `cause` for error chaining. */
+export type ElevaErrorArgs<C extends ErrorCode> = ElevaErrorJSON<C> & {
+    /** The original error forwarded to `Error.cause`. */
+    cause?: unknown;
+};
+/**
+ * Central error class for the Eleva ERP SDK.
+ *
+ * Extends `Error` with structured metadata: `code`, `kind`, `status`, and typed `details`.
+ *
+ * ```ts
+ * // Create
+ * throw ElevaError.notFound({ entity: 'Invoice' })
+ * throw ElevaError.conflict({ details: [{ key: 'email', value: 'a@b.com', cause: 'duplicate' }] })
+ *
+ * // Narrow
+ * if (err instanceof ElevaError && err.is(ERROR_CODES.NOT_FOUND)) {
+ *   console.log(err.details.entity) // string
+ * }
+ * ```
+ *
+ * Serialisation: `toJSON()` for logging, `toResponse()` for sanitised API output.
+ */
+export declare class ElevaError<C extends ErrorCode = ErrorCode> extends Error {
+    /** Error code constant identifying the failure condition. */
+    readonly code: C | string;
+    /** `DOMAIN` (safe to expose) or `SYSTEM` (sanitised before sending to clients). */
+    readonly kind: ErrorKind;
+    /** HTTP status code for this error. */
+    readonly status: number;
+    /** Structured, code-specific failure context. */
+    readonly details: ErrorDetails<C>;
+    constructor(args: ElevaErrorArgs<C>);
+    /**
+     * Type-guard: narrows to `ElevaError<K>` when `this.code === code`.
+     * After a positive check `this.details` is fully typed for `K`.
+     * @example
+     * if (err.is(ERROR_CODES.NOT_FOUND)) console.log(err.details.entity)
+     */
+    is<K extends ErrorCode>(code: K | string): this is ElevaError<K>;
+    /** Full serialised representation for logging / diagnostics. */
+    toJSON(): ElevaErrorJSON<C>;
+    toString(): string;
+    /**
+     * Sanitised payload safe for API responses.
+     * `SYSTEM` errors replace the message with a generic string; `DOMAIN` errors include `details`.
+     */
+    toResponse(): ElevaErrorResponse<C>;
+    /**
+     * Parses an unknown value into `ElevaErrorArgs`. Shared by `parse()` and `RemoteElevaError.from()`.
+     *
+     * Strategy: validate against `errorSchema` → look up known codes in the catalog →
+     * fall back to `INTERNAL_SERVER_ERROR` for unrecognised codes or malformed payloads →
+     * accept legacy `errors` field as a fallback for `details`.
+     */
+    protected static _parsePayload(value: unknown): ElevaErrorArgs<ErrorCode>;
+    /** Deserialises an unknown value into an `ElevaError`. Unrecognised payloads become `INTERNAL_SERVER_ERROR`. */
+    static parse(value: unknown): ElevaError<ErrorCode>;
+    /** Converts a `ZodError` into a `VALIDATION` error, preserving field paths and rule codes. */
+    static fromZodError<T>(error: z.ZodError<T>): ElevaError<BASE_ERROR_CODES.VALIDATION>;
+    /** Creates a `VALIDATION` error from a pre-built array of issue descriptors. */
+    static validation(args: {
+        errors: ErrorDetails<BASE_ERROR_CODES.VALIDATION>['errors'];
+        message?: string;
+    }): ElevaError<BASE_ERROR_CODES.VALIDATION>;
+    /** Creates a `VALIDATION` error for a single invalid field. Convenience wrapper around `validation()`. */
+    static invalidField(args: {
+        error: ErrorDetails<BASE_ERROR_CODES.VALIDATION>['errors'][number];
+        message?: string;
+    }): ElevaError<BASE_ERROR_CODES.VALIDATION>;
+    /** HTTP 400 — request is malformed or has invalid parameters outside of validation. */
+    static readonly badRequest: (args?: {
+        message?: string;
+        details?: any;
+    } | undefined) => ElevaError<BASE_ERROR_CODES.BAD_REQUEST>;
+    /** HTTP 401 — credentials are missing, expired, or invalid. Caller must re-authenticate. */
+    static readonly authentication: (args?: {
+        message?: string;
+        details?: any;
+    } | undefined) => ElevaError<BASE_ERROR_CODES.AUTHENTICATION>;
+    /** HTTP 403 — authenticated but lacks the required scope or permission. */
+    static readonly unauthorized: (args?: {
+        message?: string;
+        details?: any;
+    } | undefined) => ElevaError<BASE_ERROR_CODES.UNAUTHORIZED>;
+    /**
+     * HTTP 404 — no resource found for the given identifier.
+     * @param args.entity - Entity type that was not found (e.g. `"Invoice"`).
+     */
+    static readonly notFound: (args: Record<"entity", string> & {
+        message?: string;
+    }) => ElevaError<BASE_ERROR_CODES.NOT_FOUND>;
+    /** HTTP 406 — server cannot produce a response matching the `Accept` header. */
+    static readonly notAcceptable: (args?: {
+        message?: string;
+        details?: any;
+    } | undefined) => ElevaError<BASE_ERROR_CODES.NOT_ACCEPTABLE>;
+    /** HTTP 409 — operation violates a uniqueness or integrity constraint. */
+    static readonly conflict: (args: {
+        details: z.infer<Cat[C_1]["details"]>;
+        message?: string;
+    }) => ElevaError<BASE_ERROR_CODES.CONFLICT>;
+    /** HTTP 410 — resource permanently removed; retrying will never succeed. */
+    static readonly gone: (args?: {
+        message?: string;
+        details?: any;
+    } | undefined) => ElevaError<BASE_ERROR_CODES.GONE>;
+    /** HTTP 422 — request is syntactically valid but semantically unprocessable. */
+    static readonly unprocessableEntity: (args?: {
+        message?: string;
+        details?: any;
+    } | undefined) => ElevaError<BASE_ERROR_CODES.UNPROCESSABLE_ENTITY>;
+    /**
+     * HTTP 502 — upstream service returned an invalid response (`SYSTEM`).
+     * @param args.details.upstream - Name of the misbehaving upstream service.
+     */
+    static readonly badGateway: (args?: {
+        message?: string;
+        details?: any;
+    } | undefined) => ElevaError<BASE_ERROR_CODES.BAD_GATEWAY>;
+    /** HTTP 503 — service temporarily unavailable (`SYSTEM`). Pass `retryAfter` (seconds) if known. */
+    static readonly serviceUnavailable: (args?: {
+        message?: string;
+        details?: any;
+    } | undefined) => ElevaError<BASE_ERROR_CODES.SERVICE_UNAVAILABLE>;
+    /**
+     * HTTP 400 — a required field was missing from the request.
+     * @param args.field - Name of the missing field.
+     */
+    static readonly mandatoryField: (args: Record<"field", string> & {
+        message?: string;
+    }) => ElevaError<BASE_ERROR_CODES.MANDATORY_FIELD>;
+    /**
+     * HTTP 500 — unexpected server error (`SYSTEM`).
+     * Pass the original exception as `cause` to preserve the full stack chain for logging.
+     */
+    static internal(args?: {
+        message?: string;
+        cause?: unknown;
+        details?: ErrorDetails<BASE_ERROR_CODES.INTERNAL_SERVER_ERROR>;
+    }): ElevaError<BASE_ERROR_CODES.INTERNAL_SERVER_ERROR>;
+    /**
+     * HTTP 403 — caller is not authorised to access the given contact person.
+     * @param args.details.contactId - UUID of the blocked contact.
+     */
+    static readonly forbiddenContact: (args: {
+        details: z.infer<Cat[C_1]["details"]>;
+        message?: string;
+    }) => ElevaError<API_ERROR_CODES>;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/src/errors/errors.d.ts.map

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