@k9o/gate 0.0.0-stage → 1.0.0

package/dist/errors.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Gate error shapes. `GateError` is `KError`-compatible per ch01 §2 —
+ * downstream catch blocks can `instanceof GateError`-narrow without
+ * importing the gateway's `KError` class directly (the SDK is a customer-
+ * facing dependency; reaching across to the gateway's internal error
+ * type would be a layering violation).
+ *
+ * The taxonomy below is the v0.1.0 closed set; additions follow the
+ * ch11 error-catalogue freeze cycle.
+ */
+/**
+ * Closed-taxonomy error code per ch01 §2. Strings are the wire format —
+ * camelCase-cased KError families per the convention.
+ */
+type GateErrorCode = "UNAUTHENTICATED" | "INVALID_FIELD_VALUE" | "EMAIL_ALREADY_REGISTERED" | "INVALID_CREDENTIALS" | "SESSION_EXPIRED" | "REFRESH_TOKEN_INVALID" | "TIER_FEATURE_GATED" | "RBAC_DENY" | "FORBIDDEN" | "NOT_FOUND" | "GATE_REDIRECT_NOT_ALLOWED" | "POLICY_AUTHORING_AUTHORITY_INSUFFICIENT" | "UPSTREAM_UNAVAILABLE" | "INTERNAL_ERROR";
+/**
+ * Surface error thrown by the SDK. Mirrors the gateway's `KError` shape
+ * per ch01 §2.1 — `code` (closed taxonomy), `message` (human-readable),
+ * `context` (structured per-code payload), `recommendation` (action the
+ * caller can take, or null when there's no canonical recommendation).
+ */
+declare class GateError extends Error {
+    readonly code: GateErrorCode;
+    readonly context: Readonly<Record<string, unknown>>;
+    readonly recommendation: string | null;
+    /** HTTP status the gateway returned (if the error came from a wire response). */
+    readonly status: number | null;
+    constructor(init: {
+        code: GateErrorCode;
+        message: string;
+        context?: Record<string, unknown>;
+        recommendation?: string | null;
+        status?: number | null;
+    });
+}
+/**
+ * Wire-shape sentinel matching the gateway's `KError` JSON payload. The
+ * client uses this to recognise gateway responses and rehydrate them
+ * into a `GateError` instance with the right code + context preserved.
+ */
+type KErrorWire = {
+    code: string;
+    message: string;
+    context?: Record<string, unknown>;
+    recommendation?: string | null;
+};
+/**
+ * Narrow a wire `KError` to a strongly-typed `GateError`. Unknown codes
+ * pass through as `INTERNAL_ERROR` with the original code preserved in
+ * `context.originalCode` so consumers don't lose telemetry when the
+ * server-side taxonomy outpaces the SDK's bundled enum.
+ */
+declare function gateErrorFromWire(wire: KErrorWire, status: number): GateError;
+
+export { GateError, type GateErrorCode, type KErrorWire, gateErrorFromWire };

package/dist/errors.js

@@ -0,0 +1,9 @@
+import {
+  GateError,
+  gateErrorFromWire
+} from "./chunk-PEW6HZFB.js";
+export {
+  GateError,
+  gateErrorFromWire
+};
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}