@snaptrude/plugin-core 0.9.17 → 0.9.18-edgesetbacks-20261021.1

package/src/errors/plugin-error.ts

@@ -1,134 +1,134 @@
-import { CODE_META, isPluginErrorCode } from "./codes"
-import type { PluginErrorCategory, PluginErrorCode, WirePluginErrorCode } from "./codes"
-import { ERROR_ENVELOPE_VERSION, newErrorId } from "./envelope"
-import type { ErrorEnvelope } from "./envelope"
-
-/**
- * Cross-copy brand: a plugin bundle may contain its OWN copy of this module,
- * in which case `instanceof` fails across the two class identities.
- * `Symbol.for` resolves to the same symbol in every copy within a realm, so
- * `PluginError.is()` keeps working. Canonical check = `.is()` + `code`.
- */
-const BRAND = Symbol.for("snaptrude.pluginError")
-
-interface Branded {
-  [BRAND]?: boolean
-}
-
-/**
- * Typed error every failed plugin API call rejects with.
- *
- * Rehydrated client-side from the wire `ErrorEnvelope` (`fromEnvelope`) — the
- * class itself never crosses the worker boundary. Branch on the stable string
- * `code`; use `PluginError.is()` rather than `instanceof` (a bundled duplicate
- * SDK copy breaks `instanceof`, never the brand).
- *
- * @example
- * ```ts
- * try {
- *   await snaptrude.design.boolean.union(handles)
- * } catch (e) {
- *   if (PluginError.is(e) && e.code === "RATE_LIMITED") {
- *     await sleep(e.details?.retryAfterMs as number)
- *   } else {
- *     throw e
- *   }
- * }
- * ```
- */
-export class PluginError extends Error {
-  readonly code: WirePluginErrorCode
-  readonly errorId: string
-  readonly details?: Record<string, unknown>
-  readonly handle?: string
-  readonly methodPath?: string
-  readonly hint?: string
-
-  constructor(envelope: ErrorEnvelope) {
-    super(envelope.message)
-    this.name = new.target.name
-    this.code = envelope.code
-    this.errorId = envelope.errorId
-    this.details = envelope.details
-    this.handle = envelope.handle
-    this.methodPath = envelope.methodPath
-    this.hint = envelope.hint ?? hintFor(envelope.code)
-    ;(this as Branded)[BRAND] = true
-  }
-
-  /** Canonical check — survives bundled duplicate SDK copies where `instanceof` fails. */
-  static is(value: unknown): value is PluginError {
-    return (
-      typeof value === "object" &&
-      value !== null &&
-      (value as Branded)[BRAND] === true
-    )
-  }
-
-  /** Derived (not wire-carried) family of the code; unknown codes map to "internal". */
-  get category(): PluginErrorCategory {
-    return isPluginErrorCode(this.code) ? CODE_META[this.code].category : "internal"
-  }
-}
-
-// Category sugar — same brand, so `PluginError.is()` matches all of them.
-// Convenience for single-SDK-copy plugins; docs teach `.is()` + `code`.
-export class PluginValidationError extends PluginError {}
-export class PluginNotFoundError extends PluginError {}
-export class PluginPermissionError extends PluginError {}
-export class PluginHandleError extends PluginError {}
-export class PluginQuotaError extends PluginError {}
-export class PluginTimeoutError extends PluginError {}
-export class PluginTransportError extends PluginError {}
-export class PluginLifecycleError extends PluginError {}
-export class PluginExecutionError extends PluginError {}
-export class PluginInternalError extends PluginError {}
-
-type PluginErrorConstructor = new (envelope: ErrorEnvelope) => PluginError
-
-const CATEGORY_CLASS: Record<PluginErrorCategory, PluginErrorConstructor> = {
-  validation: PluginValidationError,
-  not_found: PluginNotFoundError,
-  permission: PluginPermissionError,
-  handle: PluginHandleError,
-  quota: PluginQuotaError,
-  timeout: PluginTimeoutError,
-  transport: PluginTransportError,
-  lifecycle: PluginLifecycleError,
-  execution: PluginExecutionError,
-  internal: PluginInternalError,
-}
-
-function hintFor(code: WirePluginErrorCode): string | undefined {
-  return isPluginErrorCode(code) ? CODE_META[code].hintTemplate : undefined
-}
-
-/**
- * Rehydrate a wire envelope into the typed error the plugin catches.
- * A code outside the known union (newer host) constructs the base
- * `PluginError` with the code preserved verbatim.
- */
-export function fromEnvelope(envelope: ErrorEnvelope): PluginError {
-  if (!isPluginErrorCode(envelope.code)) return new PluginError(envelope)
-  const ErrorClass = CATEGORY_CLASS[CODE_META[envelope.code].category]
-  return new ErrorClass(envelope)
-}
-
-/**
- * Build an envelope for a CLIENT-detected failure (transport rejection,
- * legacy host without `errorInfo`). Host-originated envelopes are built by
- * the host's `toErrorEnvelope` mapper, never by this.
- */
-export function makeClientEnvelope(
-  code: PluginErrorCode,
-  message: string,
-  extra?: Partial<Pick<ErrorEnvelope, "details" | "handle" | "methodPath" | "hint">>
-): ErrorEnvelope {
-  return {
-    envelopeVersion: ERROR_ENVELOPE_VERSION,
-    code,
-    message,
-    errorId: newErrorId("c-"),
-    ...extra,
-  }
-}
+import { CODE_META, isPluginErrorCode } from "./codes"
+import type { PluginErrorCategory, PluginErrorCode, WirePluginErrorCode } from "./codes"
+import { ERROR_ENVELOPE_VERSION, newErrorId } from "./envelope"
+import type { ErrorEnvelope } from "./envelope"
+
+/**
+ * Cross-copy brand: a plugin bundle may contain its OWN copy of this module,
+ * in which case `instanceof` fails across the two class identities.
+ * `Symbol.for` resolves to the same symbol in every copy within a realm, so
+ * `PluginError.is()` keeps working. Canonical check = `.is()` + `code`.
+ */
+const BRAND = Symbol.for("snaptrude.pluginError")
+
+interface Branded {
+  [BRAND]?: boolean
+}
+
+/**
+ * Typed error every failed plugin API call rejects with.
+ *
+ * Rehydrated client-side from the wire `ErrorEnvelope` (`fromEnvelope`) — the
+ * class itself never crosses the worker boundary. Branch on the stable string
+ * `code`; use `PluginError.is()` rather than `instanceof` (a bundled duplicate
+ * SDK copy breaks `instanceof`, never the brand).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await snaptrude.design.boolean.union(handles)
+ * } catch (e) {
+ *   if (PluginError.is(e) && e.code === "RATE_LIMITED") {
+ *     await sleep(e.details?.retryAfterMs as number)
+ *   } else {
+ *     throw e
+ *   }
+ * }
+ * ```
+ */
+export class PluginError extends Error {
+  readonly code: WirePluginErrorCode
+  readonly errorId: string
+  readonly details?: Record<string, unknown>
+  readonly handle?: string
+  readonly methodPath?: string
+  readonly hint?: string
+
+  constructor(envelope: ErrorEnvelope) {
+    super(envelope.message)
+    this.name = new.target.name
+    this.code = envelope.code
+    this.errorId = envelope.errorId
+    this.details = envelope.details
+    this.handle = envelope.handle
+    this.methodPath = envelope.methodPath
+    this.hint = envelope.hint ?? hintFor(envelope.code)
+    ;(this as Branded)[BRAND] = true
+  }
+
+  /** Canonical check — survives bundled duplicate SDK copies where `instanceof` fails. */
+  static is(value: unknown): value is PluginError {
+    return (
+      typeof value === "object" &&
+      value !== null &&
+      (value as Branded)[BRAND] === true
+    )
+  }
+
+  /** Derived (not wire-carried) family of the code; unknown codes map to "internal". */
+  get category(): PluginErrorCategory {
+    return isPluginErrorCode(this.code) ? CODE_META[this.code].category : "internal"
+  }
+}
+
+// Category sugar — same brand, so `PluginError.is()` matches all of them.
+// Convenience for single-SDK-copy plugins; docs teach `.is()` + `code`.
+export class PluginValidationError extends PluginError {}
+export class PluginNotFoundError extends PluginError {}
+export class PluginPermissionError extends PluginError {}
+export class PluginHandleError extends PluginError {}
+export class PluginQuotaError extends PluginError {}
+export class PluginTimeoutError extends PluginError {}
+export class PluginTransportError extends PluginError {}
+export class PluginLifecycleError extends PluginError {}
+export class PluginExecutionError extends PluginError {}
+export class PluginInternalError extends PluginError {}
+
+type PluginErrorConstructor = new (envelope: ErrorEnvelope) => PluginError
+
+const CATEGORY_CLASS: Record<PluginErrorCategory, PluginErrorConstructor> = {
+  validation: PluginValidationError,
+  not_found: PluginNotFoundError,
+  permission: PluginPermissionError,
+  handle: PluginHandleError,
+  quota: PluginQuotaError,
+  timeout: PluginTimeoutError,
+  transport: PluginTransportError,
+  lifecycle: PluginLifecycleError,
+  execution: PluginExecutionError,
+  internal: PluginInternalError,
+}
+
+function hintFor(code: WirePluginErrorCode): string | undefined {
+  return isPluginErrorCode(code) ? CODE_META[code].hintTemplate : undefined
+}
+
+/**
+ * Rehydrate a wire envelope into the typed error the plugin catches.
+ * A code outside the known union (newer host) constructs the base
+ * `PluginError` with the code preserved verbatim.
+ */
+export function fromEnvelope(envelope: ErrorEnvelope): PluginError {
+  if (!isPluginErrorCode(envelope.code)) return new PluginError(envelope)
+  const ErrorClass = CATEGORY_CLASS[CODE_META[envelope.code].category]
+  return new ErrorClass(envelope)
+}
+
+/**
+ * Build an envelope for a CLIENT-detected failure (transport rejection,
+ * legacy host without `errorInfo`). Host-originated envelopes are built by
+ * the host's `toErrorEnvelope` mapper, never by this.
+ */
+export function makeClientEnvelope(
+  code: PluginErrorCode,
+  message: string,
+  extra?: Partial<Pick<ErrorEnvelope, "details" | "handle" | "methodPath" | "hint">>
+): ErrorEnvelope {
+  return {
+    envelopeVersion: ERROR_ENVELOPE_VERSION,
+    code,
+    message,
+    errorId: newErrorId("c-"),
+    ...extra,
+  }
+}