@webpieces/core-util 0.4.762 → 0.4.763

package/README.md

@@ -4,9 +4,9 @@ Utility functions for WebPieces applications. Works in both browser and Node.js
 
 ## Portable API errors and IPC
 
-React Native consumers use `@webpieces/core-util/errors` for canonical semantic errors (`UserError`, `NotFoundError`, and the other API categories) and `@webpieces/core-util/ipc` for shared contracts and connection types. These two subpaths are checked with public declaration fixtures, Metro Android/iOS bundles, and Hermes compilation; the broad root barrel is not certified for React Native.
+React Native consumers use `@webpieces/core-util/errors` for canonical semantic errors (`ApiEndUserError`, `ApiNotFoundError`, and the other API categories) and `@webpieces/core-util/ipc` for shared contracts and connection types. These two subpaths are checked with public declaration fixtures, Metro Android/iOS bundles, and Hermes compilation; the broad root barrel is not certified for React Native.
 
-Use `@webpieces/ipc-bridge` for generated clients and typed receivers. HTTP preserves status 266 for `UserError`: monitoring succeeds, while generated clients throw it for GUI display. Old Http-prefixed names are deprecated aliases; neutral errors use standard `cause` and have no HTTP `.code`. See [the migration and verification guide](https://github.com/deanhiller/webpieces-ts/blob/main/docs/portable-ipc-and-errors.md).
+Use `@webpieces/ipc-bridge` for generated clients and typed receivers. HTTP preserves status 266 for `ApiEndUserError`: monitoring succeeds, while generated clients throw it for GUI display. All API errors are transport-neutral, use standard `cause`, and have no HTTP `.code`. See [the taxonomy and verification guide](https://github.com/deanhiller/webpieces-ts/blob/main/docs/portable-ipc-and-errors.md).
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/core-util",
-  "version": "0.4.762",
+  "version": "0.4.763",
   "description": "Utility functions for WebPieces - works in browser and Node.js",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/errors/ApiError.d.ts

@@ -1,70 +1,64 @@
-/** Portable semantic failures. HTTP status mapping belongs to the HTTP adapter. */
-export declare class ApiError extends Error {
-    readonly kind: string;
+export type ApiErrorKind = 'end-user' | 'bad-request' | 'unauthorized' | 'forbidden' | 'not-found' | 'endpoint-not-found' | 'request-timeout' | 'rate-limited' | 'implementation' | 'dependency' | 'unavailable' | 'dependency-timeout' | 'dependency-backoff' | 'connection';
+/** Category for portable API failures. Concrete subclasses alone define protocol mappings. */
+export declare abstract class ApiError extends Error {
+    abstract readonly kind: ApiErrorKind;
     subType?: string;
     constructor(message: string, cause?: Error);
 }
-/** NotFound failure, independent of transport. */
-export declare class NotFoundError extends ApiError {
-    readonly kind: string;
+export declare class ApiNotFoundError extends ApiError {
+    readonly kind: ApiErrorKind;
 }
-/** BadGateway failure, independent of transport. */
-export declare class BadGatewayError extends ApiError {
-    readonly kind: string;
+export declare class ApiDependencyError extends ApiError {
+    readonly kind: "dependency";
 }
-/** ServiceUnavailable failure, independent of transport. */
-export declare class ServiceUnavailableError extends ApiError {
-    readonly kind: string;
+export declare class ApiUnavailableError extends ApiError {
+    readonly kind: "unavailable";
 }
-/** GatewayTimeout failure, independent of transport. */
-export declare class GatewayTimeoutError extends ApiError {
-    readonly kind: string;
+export declare class ApiDependencyTimeoutError extends ApiError {
+    readonly kind: "dependency-timeout";
 }
-/** Internal failure, independent of transport. */
-export declare class InternalError extends ApiError {
-    readonly kind: string;
+/** A bug or invalid implementation state. Local errors become server errors only after a remote decode. */
+export declare class ApiImplementationError extends ApiError {
+    readonly serverError: boolean;
+    readonly kind: "implementation";
+    constructor(message: string, cause?: Error, serverError?: boolean);
 }
-/** TooManyRequests failure, independent of transport. */
-export declare class TooManyRequestsError extends ApiError {
-    readonly kind: string;
+export declare class ApiRateLimitedError extends ApiError {
+    readonly kind: "rate-limited";
 }
-/** Forbidden failure, independent of transport. */
-export declare class ForbiddenError extends ApiError {
-    readonly kind: string;
+export declare class ApiForbiddenError extends ApiError {
+    readonly kind: "forbidden";
 }
-/** RequestTimeout failure, independent of transport. */
-export declare class RequestTimeoutError extends ApiError {
-    readonly kind: string;
+export declare class ApiRequestTimeoutError extends ApiError {
+    readonly kind: "request-timeout";
 }
-/** Offline failure, independent of transport. */
-export declare class OfflineError extends ApiError {
-    readonly kind: string;
+/** A caller-local connection failure. HTTP servers normalize this to ApiImplementationError. */
+export declare class ApiConnectionError extends ApiError {
+    readonly kind: "connection";
 }
-/** The API endpoint is missing, distinct from an absent domain entity. */
-export declare class EndpointNotFoundError extends NotFoundError {
-    readonly kind: string;
+/** The API operation is missing, distinct from an absent domain entity. */
+export declare class ApiEndpointNotFoundError extends ApiNotFoundError {
+    readonly kind: "endpoint-not-found";
 }
-/** Expected user mistake: successful protocol/monitoring outcome; GUI catches this error. */
-export declare class UserError extends ApiError {
+/** Expected end-user mistake. Its message is deliberately caller-safe. */
+export declare class ApiEndUserError extends ApiError {
     errorCode?: string | undefined;
-    readonly kind: string;
+    readonly kind: "end-user";
     constructor(message: string, errorCode?: string | undefined, cause?: Error);
 }
-/** Invalid caller input with optional human-safe field feedback. */
-export declare class BadRequestError extends ApiError {
+/** Invalid API caller input. message is diagnostic; callerMessage is safe to publish. */
+export declare class ApiBadRequestError extends ApiError {
     field?: string | undefined;
-    guiMessage?: string | undefined;
-    readonly kind: string;
-    constructor(message: string, field?: string | undefined, guiMessage?: string | undefined, cause?: Error);
+    callerMessage?: string | undefined;
+    readonly kind: "bad-request";
+    constructor(message: string, field?: string | undefined, callerMessage?: string | undefined, cause?: Error);
 }
-/** Authentication failure with a contract-defined reason. */
-export declare class UnauthorizedError extends ApiError {
-    readonly kind: string;
+export declare class ApiUnauthorizedError extends ApiError {
+    readonly kind: "unauthorized";
     constructor(message: string, subType?: string, cause?: Error);
 }
-/** Dependency failure with bounded retry advice. */
-export declare class VendorError extends ApiError {
-    waitSeconds: number;
-    readonly kind: string;
-    constructor(message: string, waitSeconds?: number, cause?: Error);
+export declare class ApiDependencyBackoffError extends ApiError {
+    retryAfterSeconds: number;
+    readonly kind: "dependency-backoff";
+    constructor(message: string, retryAfterSeconds?: number, cause?: Error);
 }

package/src/errors/ApiError.js

@@ -1,9 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VendorError = exports.UnauthorizedError = exports.BadRequestError = exports.UserError = exports.EndpointNotFoundError = exports.OfflineError = exports.RequestTimeoutError = exports.ForbiddenError = exports.TooManyRequestsError = exports.InternalError = exports.GatewayTimeoutError = exports.ServiceUnavailableError = exports.BadGatewayError = exports.NotFoundError = exports.ApiError = void 0;
-/** Portable semantic failures. HTTP status mapping belongs to the HTTP adapter. */
+exports.ApiDependencyBackoffError = exports.ApiUnauthorizedError = exports.ApiBadRequestError = exports.ApiEndUserError = exports.ApiEndpointNotFoundError = exports.ApiConnectionError = exports.ApiRequestTimeoutError = exports.ApiForbiddenError = exports.ApiRateLimitedError = exports.ApiImplementationError = exports.ApiDependencyTimeoutError = exports.ApiUnavailableError = exports.ApiDependencyError = exports.ApiNotFoundError = exports.ApiError = void 0;
+/** Category for portable API failures. Concrete subclasses alone define protocol mappings. */
 class ApiError extends Error {
-    kind = 'internal';
     subType;
     constructor(message, cause) {
         super(message, { cause });
@@ -11,96 +10,92 @@ class ApiError extends Error {
     }
 }
 exports.ApiError = ApiError;
-/** NotFound failure, independent of transport. */
-class NotFoundError extends ApiError {
+class ApiNotFoundError extends ApiError {
     kind = 'not-found';
 }
-exports.NotFoundError = NotFoundError;
-/** BadGateway failure, independent of transport. */
-class BadGatewayError extends ApiError {
-    kind = 'bad-gateway';
+exports.ApiNotFoundError = ApiNotFoundError;
+class ApiDependencyError extends ApiError {
+    kind = 'dependency';
 }
-exports.BadGatewayError = BadGatewayError;
-/** ServiceUnavailable failure, independent of transport. */
-class ServiceUnavailableError extends ApiError {
-    kind = 'service-unavailable';
+exports.ApiDependencyError = ApiDependencyError;
+class ApiUnavailableError extends ApiError {
+    kind = 'unavailable';
 }
-exports.ServiceUnavailableError = ServiceUnavailableError;
-/** GatewayTimeout failure, independent of transport. */
-class GatewayTimeoutError extends ApiError {
-    kind = 'gateway-timeout';
+exports.ApiUnavailableError = ApiUnavailableError;
+class ApiDependencyTimeoutError extends ApiError {
+    kind = 'dependency-timeout';
 }
-exports.GatewayTimeoutError = GatewayTimeoutError;
-/** Internal failure, independent of transport. */
-class InternalError extends ApiError {
-    kind = 'internal';
+exports.ApiDependencyTimeoutError = ApiDependencyTimeoutError;
+/** A bug or invalid implementation state. Local errors become server errors only after a remote decode. */
+class ApiImplementationError extends ApiError {
+    serverError;
+    kind = 'implementation';
+    constructor(message, cause, serverError = false) {
+        super(message, cause);
+        this.serverError = serverError;
+    }
 }
-exports.InternalError = InternalError;
-/** TooManyRequests failure, independent of transport. */
-class TooManyRequestsError extends ApiError {
-    kind = 'too-many-requests';
+exports.ApiImplementationError = ApiImplementationError;
+class ApiRateLimitedError extends ApiError {
+    kind = 'rate-limited';
 }
-exports.TooManyRequestsError = TooManyRequestsError;
-/** Forbidden failure, independent of transport. */
-class ForbiddenError extends ApiError {
+exports.ApiRateLimitedError = ApiRateLimitedError;
+class ApiForbiddenError extends ApiError {
     kind = 'forbidden';
 }
-exports.ForbiddenError = ForbiddenError;
-/** RequestTimeout failure, independent of transport. */
-class RequestTimeoutError extends ApiError {
+exports.ApiForbiddenError = ApiForbiddenError;
+class ApiRequestTimeoutError extends ApiError {
     kind = 'request-timeout';
 }
-exports.RequestTimeoutError = RequestTimeoutError;
-/** Offline failure, independent of transport. */
-class OfflineError extends ApiError {
-    kind = 'offline';
+exports.ApiRequestTimeoutError = ApiRequestTimeoutError;
+/** A caller-local connection failure. HTTP servers normalize this to ApiImplementationError. */
+class ApiConnectionError extends ApiError {
+    kind = 'connection';
 }
-exports.OfflineError = OfflineError;
-/** The API endpoint is missing, distinct from an absent domain entity. */
-class EndpointNotFoundError extends NotFoundError {
+exports.ApiConnectionError = ApiConnectionError;
+/** The API operation is missing, distinct from an absent domain entity. */
+class ApiEndpointNotFoundError extends ApiNotFoundError {
     kind = 'endpoint-not-found';
 }
-exports.EndpointNotFoundError = EndpointNotFoundError;
-/** Expected user mistake: successful protocol/monitoring outcome; GUI catches this error. */
-class UserError extends ApiError {
+exports.ApiEndpointNotFoundError = ApiEndpointNotFoundError;
+/** Expected end-user mistake. Its message is deliberately caller-safe. */
+class ApiEndUserError extends ApiError {
     errorCode;
-    kind = 'user';
+    kind = 'end-user';
     constructor(message, errorCode, cause) {
         super(message, cause);
         this.errorCode = errorCode;
         this.subType = 'USER_ERROR';
     }
 }
-exports.UserError = UserError;
-/** Invalid caller input with optional human-safe field feedback. */
-class BadRequestError extends ApiError {
+exports.ApiEndUserError = ApiEndUserError;
+/** Invalid API caller input. message is diagnostic; callerMessage is safe to publish. */
+class ApiBadRequestError extends ApiError {
     field;
-    guiMessage;
+    callerMessage;
     kind = 'bad-request';
-    constructor(message, field, guiMessage, cause) {
+    constructor(message, field, callerMessage, cause) {
         super(message, cause);
         this.field = field;
-        this.guiMessage = guiMessage;
+        this.callerMessage = callerMessage;
     }
 }
-exports.BadRequestError = BadRequestError;
-/** Authentication failure with a contract-defined reason. */
-class UnauthorizedError extends ApiError {
+exports.ApiBadRequestError = ApiBadRequestError;
+class ApiUnauthorizedError extends ApiError {
     kind = 'unauthorized';
     constructor(message, subType, cause) {
         super(message, cause);
         this.subType = subType;
     }
 }
-exports.UnauthorizedError = UnauthorizedError;
-/** Dependency failure with bounded retry advice. */
-class VendorError extends ApiError {
-    waitSeconds;
-    kind = 'vendor';
-    constructor(message, waitSeconds = 30, cause) {
+exports.ApiUnauthorizedError = ApiUnauthorizedError;
+class ApiDependencyBackoffError extends ApiError {
+    retryAfterSeconds;
+    kind = 'dependency-backoff';
+    constructor(message, retryAfterSeconds = 30, cause) {
         super(message, cause);
-        this.waitSeconds = waitSeconds;
+        this.retryAfterSeconds = retryAfterSeconds;
     }
 }
-exports.VendorError = VendorError;
+exports.ApiDependencyBackoffError = ApiDependencyBackoffError;
 //# sourceMappingURL=ApiError.js.map

package/src/errors/ApiError.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiError.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ApiError.ts"],"names":[],"mappings":";;;AAAA,mFAAmF;AACnF,MAAa,QAAS,SAAQ,KAAK;IACtB,IAAI,GAAW,UAAU,CAAC;IAC5B,OAAO,CAAU;IACxB,YAAY,OAAe,EAAE,KAAa;QACtC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAChC,CAAC;CACJ;AAPD,4BAOC;AAED,kDAAkD;AAClD,MAAa,aAAc,SAAQ,QAAQ;IAAqB,IAAI,GAAW,WAAW,CAAC;CAAE;AAA7F,sCAA6F;AAE7F,oDAAoD;AACpD,MAAa,eAAgB,SAAQ,QAAQ;IAAqB,IAAI,GAAW,aAAa,CAAC;CAAE;AAAjG,0CAAiG;AAEjG,4DAA4D;AAC5D,MAAa,uBAAwB,SAAQ,QAAQ;IAAqB,IAAI,GAAW,qBAAqB,CAAC;CAAE;AAAjH,0DAAiH;AAEjH,wDAAwD;AACxD,MAAa,mBAAoB,SAAQ,QAAQ;IAAqB,IAAI,GAAW,iBAAiB,CAAC;CAAE;AAAzG,kDAAyG;AAEzG,kDAAkD;AAClD,MAAa,aAAc,SAAQ,QAAQ;IAAqB,IAAI,GAAW,UAAU,CAAC;CAAE;AAA5F,sCAA4F;AAE5F,yDAAyD;AACzD,MAAa,oBAAqB,SAAQ,QAAQ;IAAqB,IAAI,GAAW,mBAAmB,CAAC;CAAE;AAA5G,oDAA4G;AAE5G,mDAAmD;AACnD,MAAa,cAAe,SAAQ,QAAQ;IAAqB,IAAI,GAAW,WAAW,CAAC;CAAE;AAA9F,wCAA8F;AAE9F,wDAAwD;AACxD,MAAa,mBAAoB,SAAQ,QAAQ;IAAqB,IAAI,GAAW,iBAAiB,CAAC;CAAE;AAAzG,kDAAyG;AAEzG,iDAAiD;AACjD,MAAa,YAAa,SAAQ,QAAQ;IAAqB,IAAI,GAAW,SAAS,CAAC;CAAE;AAA1F,oCAA0F;AAE1F,0EAA0E;AAC1E,MAAa,qBAAsB,SAAQ,aAAa;IAAqB,IAAI,GAAW,oBAAoB,CAAC;CAAE;AAAnH,sDAAmH;AACnH,6FAA6F;AAC7F,MAAa,SAAU,SAAQ,QAAQ;IAEC;IADlB,IAAI,GAAW,MAAM,CAAC;IACxC,YAAY,OAAe,EAAS,SAAkB,EAAE,KAAa;QACjE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QADU,cAAS,GAAT,SAAS,CAAS;QAElD,IAAI,CAAC,OAAO,GAAG,YAAY,CAAC;IAChC,CAAC;CACJ;AAND,8BAMC;AACD,oEAAoE;AACpE,MAAa,eAAgB,SAAQ,QAAQ;IAEL;IAAuB;IADzC,IAAI,GAAW,aAAa,CAAC;IAC/C,YAAY,OAAe,EAAS,KAAc,EAAS,UAAmB,EAAE,KAAa;QACzF,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QADU,UAAK,GAAL,KAAK,CAAS;QAAS,eAAU,GAAV,UAAU,CAAS;IAE9E,CAAC;CACJ;AALD,0CAKC;AACD,6DAA6D;AAC7D,MAAa,iBAAkB,SAAQ,QAAQ;IACzB,IAAI,GAAW,cAAc,CAAC;IAChD,YAAY,OAAe,EAAE,OAAgB,EAAE,KAAa;QACxD,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;CACJ;AAND,8CAMC;AACD,oDAAoD;AACpD,MAAa,WAAY,SAAQ,QAAQ;IAED;IADlB,IAAI,GAAW,QAAQ,CAAC;IAC1C,YAAY,OAAe,EAAS,cAAc,EAAE,EAAE,KAAa;QAC/D,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QADU,gBAAW,GAAX,WAAW,CAAK;IAEpD,CAAC;CACJ;AALD,kCAKC","sourcesContent":["/** Portable semantic failures. HTTP status mapping belongs to the HTTP adapter. */\nexport class ApiError extends Error {\n    readonly kind: string = 'internal';\n    public subType?: string;\n    constructor(message: string, cause?: Error) {\n        super(message, { cause });\n        this.name = new.target.name;\n    }\n}\n\n/** NotFound failure, independent of transport. */\nexport class NotFoundError extends ApiError { override readonly kind: string = 'not-found'; }\n\n/** BadGateway failure, independent of transport. */\nexport class BadGatewayError extends ApiError { override readonly kind: string = 'bad-gateway'; }\n\n/** ServiceUnavailable failure, independent of transport. */\nexport class ServiceUnavailableError extends ApiError { override readonly kind: string = 'service-unavailable'; }\n\n/** GatewayTimeout failure, independent of transport. */\nexport class GatewayTimeoutError extends ApiError { override readonly kind: string = 'gateway-timeout'; }\n\n/** Internal failure, independent of transport. */\nexport class InternalError extends ApiError { override readonly kind: string = 'internal'; }\n\n/** TooManyRequests failure, independent of transport. */\nexport class TooManyRequestsError extends ApiError { override readonly kind: string = 'too-many-requests'; }\n\n/** Forbidden failure, independent of transport. */\nexport class ForbiddenError extends ApiError { override readonly kind: string = 'forbidden'; }\n\n/** RequestTimeout failure, independent of transport. */\nexport class RequestTimeoutError extends ApiError { override readonly kind: string = 'request-timeout'; }\n\n/** Offline failure, independent of transport. */\nexport class OfflineError extends ApiError { override readonly kind: string = 'offline'; }\n\n/** The API endpoint is missing, distinct from an absent domain entity. */\nexport class EndpointNotFoundError extends NotFoundError { override readonly kind: string = 'endpoint-not-found'; }\n/** Expected user mistake: successful protocol/monitoring outcome; GUI catches this error. */\nexport class UserError extends ApiError {\n    override readonly kind: string = 'user';\n    constructor(message: string, public errorCode?: string, cause?: Error) {\n        super(message, cause);\n        this.subType = 'USER_ERROR';\n    }\n}\n/** Invalid caller input with optional human-safe field feedback. */\nexport class BadRequestError extends ApiError {\n    override readonly kind: string = 'bad-request';\n    constructor(message: string, public field?: string, public guiMessage?: string, cause?: Error) {\n        super(message, cause);\n    }\n}\n/** Authentication failure with a contract-defined reason. */\nexport class UnauthorizedError extends ApiError {\n    override readonly kind: string = 'unauthorized';\n    constructor(message: string, subType?: string, cause?: Error) {\n        super(message, cause);\n        this.subType = subType;\n    }\n}\n/** Dependency failure with bounded retry advice. */\nexport class VendorError extends ApiError {\n    override readonly kind: string = 'vendor';\n    constructor(message: string, public waitSeconds = 30, cause?: Error) {\n        super(message, cause);\n    }\n}\n"]}
+{"version":3,"file":"ApiError.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ApiError.ts"],"names":[],"mappings":";;;AAgBA,8FAA8F;AAC9F,MAAsB,QAAS,SAAQ,KAAK;IAEjC,OAAO,CAAU;IAExB,YAAY,OAAe,EAAE,KAAa;QACtC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAChC,CAAC;CACJ;AARD,4BAQC;AAED,MAAa,gBAAiB,SAAQ,QAAQ;IACxB,IAAI,GAAiB,WAAW,CAAC;CACtD;AAFD,4CAEC;AACD,MAAa,kBAAmB,SAAQ,QAAQ;IAC1B,IAAI,GAAG,YAAqB,CAAC;CAClD;AAFD,gDAEC;AACD,MAAa,mBAAoB,SAAQ,QAAQ;IAC3B,IAAI,GAAG,aAAsB,CAAC;CACnD;AAFD,kDAEC;AACD,MAAa,yBAA0B,SAAQ,QAAQ;IACjC,IAAI,GAAG,oBAA6B,CAAC;CAC1D;AAFD,8DAEC;AAED,2GAA2G;AAC3G,MAAa,sBAAuB,SAAQ,QAAQ;IAM5B;IALF,IAAI,GAAG,gBAAyB,CAAC;IAEnD,YACI,OAAe,EACf,KAAa,EACG,cAAc,KAAK;QAEnC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAFN,gBAAW,GAAX,WAAW,CAAQ;IAGvC,CAAC;CACJ;AAVD,wDAUC;AAED,MAAa,mBAAoB,SAAQ,QAAQ;IAC3B,IAAI,GAAG,cAAuB,CAAC;CACpD;AAFD,kDAEC;AACD,MAAa,iBAAkB,SAAQ,QAAQ;IACzB,IAAI,GAAG,WAAoB,CAAC;CACjD;AAFD,8CAEC;AACD,MAAa,sBAAuB,SAAQ,QAAQ;IAC9B,IAAI,GAAG,iBAA0B,CAAC;CACvD;AAFD,wDAEC;AAED,gGAAgG;AAChG,MAAa,kBAAmB,SAAQ,QAAQ;IAC1B,IAAI,GAAG,YAAqB,CAAC;CAClD;AAFD,gDAEC;AAED,2EAA2E;AAC3E,MAAa,wBAAyB,SAAQ,gBAAgB;IACxC,IAAI,GAAG,oBAA6B,CAAC;CAC1D;AAFD,4DAEC;AAED,0EAA0E;AAC1E,MAAa,eAAgB,SAAQ,QAAQ;IAK9B;IAJO,IAAI,GAAG,UAAmB,CAAC;IAE7C,YACI,OAAe,EACR,SAAkB,EACzB,KAAa;QAEb,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAHf,cAAS,GAAT,SAAS,CAAS;QAIzB,IAAI,CAAC,OAAO,GAAG,YAAY,CAAC;IAChC,CAAC;CACJ;AAXD,0CAWC;AAED,yFAAyF;AACzF,MAAa,kBAAmB,SAAQ,QAAQ;IAKjC;IACA;IALO,IAAI,GAAG,aAAsB,CAAC;IAEhD,YACI,OAAe,EACR,KAAc,EACd,aAAsB,EAC7B,KAAa;QAEb,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAJf,UAAK,GAAL,KAAK,CAAS;QACd,kBAAa,GAAb,aAAa,CAAS;IAIjC,CAAC;CACJ;AAXD,gDAWC;AAED,MAAa,oBAAqB,SAAQ,QAAQ;IAC5B,IAAI,GAAG,cAAuB,CAAC;IAEjD,YAAY,OAAe,EAAE,OAAgB,EAAE,KAAa;QACxD,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;CACJ;AAPD,oDAOC;AAED,MAAa,yBAA0B,SAAQ,QAAQ;IAKxC;IAJO,IAAI,GAAG,oBAA6B,CAAC;IAEvD,YACI,OAAe,EACR,oBAAoB,EAAE,EAC7B,KAAa;QAEb,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAHf,sBAAiB,GAAjB,iBAAiB,CAAK;IAIjC,CAAC;CACJ;AAVD,8DAUC","sourcesContent":["export type ApiErrorKind =\n    | 'end-user'\n    | 'bad-request'\n    | 'unauthorized'\n    | 'forbidden'\n    | 'not-found'\n    | 'endpoint-not-found'\n    | 'request-timeout'\n    | 'rate-limited'\n    | 'implementation'\n    | 'dependency'\n    | 'unavailable'\n    | 'dependency-timeout'\n    | 'dependency-backoff'\n    | 'connection';\n\n/** Category for portable API failures. Concrete subclasses alone define protocol mappings. */\nexport abstract class ApiError extends Error {\n    abstract readonly kind: ApiErrorKind;\n    public subType?: string;\n\n    constructor(message: string, cause?: Error) {\n        super(message, { cause });\n        this.name = new.target.name;\n    }\n}\n\nexport class ApiNotFoundError extends ApiError {\n    override readonly kind: ApiErrorKind = 'not-found';\n}\nexport class ApiDependencyError extends ApiError {\n    override readonly kind = 'dependency' as const;\n}\nexport class ApiUnavailableError extends ApiError {\n    override readonly kind = 'unavailable' as const;\n}\nexport class ApiDependencyTimeoutError extends ApiError {\n    override readonly kind = 'dependency-timeout' as const;\n}\n\n/** A bug or invalid implementation state. Local errors become server errors only after a remote decode. */\nexport class ApiImplementationError extends ApiError {\n    override readonly kind = 'implementation' as const;\n\n    constructor(\n        message: string,\n        cause?: Error,\n        public readonly serverError = false,\n    ) {\n        super(message, cause);\n    }\n}\n\nexport class ApiRateLimitedError extends ApiError {\n    override readonly kind = 'rate-limited' as const;\n}\nexport class ApiForbiddenError extends ApiError {\n    override readonly kind = 'forbidden' as const;\n}\nexport class ApiRequestTimeoutError extends ApiError {\n    override readonly kind = 'request-timeout' as const;\n}\n\n/** A caller-local connection failure. HTTP servers normalize this to ApiImplementationError. */\nexport class ApiConnectionError extends ApiError {\n    override readonly kind = 'connection' as const;\n}\n\n/** The API operation is missing, distinct from an absent domain entity. */\nexport class ApiEndpointNotFoundError extends ApiNotFoundError {\n    override readonly kind = 'endpoint-not-found' as const;\n}\n\n/** Expected end-user mistake. Its message is deliberately caller-safe. */\nexport class ApiEndUserError extends ApiError {\n    override readonly kind = 'end-user' as const;\n\n    constructor(\n        message: string,\n        public errorCode?: string,\n        cause?: Error,\n    ) {\n        super(message, cause);\n        this.subType = 'USER_ERROR';\n    }\n}\n\n/** Invalid API caller input. message is diagnostic; callerMessage is safe to publish. */\nexport class ApiBadRequestError extends ApiError {\n    override readonly kind = 'bad-request' as const;\n\n    constructor(\n        message: string,\n        public field?: string,\n        public callerMessage?: string,\n        cause?: Error,\n    ) {\n        super(message, cause);\n    }\n}\n\nexport class ApiUnauthorizedError extends ApiError {\n    override readonly kind = 'unauthorized' as const;\n\n    constructor(message: string, subType?: string, cause?: Error) {\n        super(message, cause);\n        this.subType = subType;\n    }\n}\n\nexport class ApiDependencyBackoffError extends ApiError {\n    override readonly kind = 'dependency-backoff' as const;\n\n    constructor(\n        message: string,\n        public retryAfterSeconds = 30,\n        cause?: Error,\n    ) {\n        super(message, cause);\n    }\n}\n"]}

package/src/errors/ApiErrorCodec.d.ts

@@ -1,25 +1,30 @@
 import { ApiError } from './ApiError';
-/** Allowlisted error envelope shared by non-HTTP transports. Contains only bounded semantic causes, never stacks or arbitrary properties. */
+/** Allowlisted transport-neutral envelope. It never contains stacks or arbitrary properties. */
 export declare class ApiErrorPayload {
     kind: string;
     message: string;
     cause?: ApiErrorPayload;
     subType?: string;
     field?: string;
-    guiAlertMessage?: string;
+    callerMessage?: string;
     errorCode?: string;
-    waitSeconds?: number;
-    constructor(kind: string, message: string);
+    retryAfterSeconds?: number;
+    constructor(kind?: string, message?: string);
 }
-/** Bounded, safe, transport-neutral encoding. Unrecognized types become generic internal failures. */
+/** Bounded safe codec shared by HTTP, IPC, and other remote adapters. */
 export declare class ApiErrorCodec {
     static encode(error: unknown): ApiErrorPayload;
     private static encodeDepth;
+    /** Decode a value received from another process. Implementation failures are marked remote. */
     static decode(value: unknown): ApiError;
+    /** Whether a body carries a recognized Webpieces semantic discriminator. */
+    static isPayload(value: unknown): boolean;
     private static decodeDepth;
     private static decodeOne;
-    private static kind;
+    private static remoteImplementationError;
+    private static publicMessage;
     private static text;
     private static wait;
     private static message;
+    private static readonly kinds;
 }