@capxul/sdk 0.1.0-alpha.0

package/dist/errors.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+// src/errors.ts
+var CapxulError = class extends Error {
+  code;
+  details;
+  operationId;
+  correlationId;
+  retryable;
+  constructor(init) {
+    super(
+      init.message,
+      init.cause !== void 0 ? { cause: init.cause } : void 0
+    );
+    this.name = "CapxulError";
+    this.code = init.code;
+    this.details = init.details;
+    this.operationId = init.operationId;
+    this.correlationId = init.correlationId;
+    this.retryable = init.retryable;
+  }
+};
+function notImplemented(method) {
+  return new CapxulError({
+    code: "NOT_IMPLEMENTED",
+    message: `${method} is not yet implemented in @capxul/sdk (Slice C scaffold).`
+  });
+}
+function stub(method) {
+  return [notImplemented(method), null];
+}
+
+exports.CapxulError = CapxulError;
+exports.notImplemented = notImplemented;
+exports.stub = stub;

package/dist/errors.d.cts

@@ -0,0 +1,55 @@
+import { CapxulErrorCode, CapxulErrorDetails, OperationId, CorrelationId } from '@repo/platform-kernel';
+
+/**
+ * Unified error class surfaced by every SDK method.
+ *
+ * Parameterized on `Codes` so individual method signatures can narrow
+ * to the subset of `CapxulErrorCode` they actually produce (per
+ * CANON.md §4.39 + §4.44 + sdk-surface.md §3a). The default
+ * `Codes = CapxulErrorCode` is the global catalog from
+ * `@repo/platform-kernel` — 34 values aligned with the wire
+ * `ErrorEnvelope.error.code` enum.
+ */
+declare class CapxulError<Codes extends CapxulErrorCode = CapxulErrorCode> extends Error {
+    readonly code: Codes;
+    readonly details?: CapxulErrorDetails;
+    readonly operationId?: OperationId;
+    readonly correlationId?: CorrelationId;
+    readonly retryable?: boolean;
+    constructor(init: {
+        code: Codes;
+        message: string;
+        cause?: unknown;
+        details?: CapxulErrorDetails;
+        operationId?: OperationId;
+        correlationId?: CorrelationId;
+        retryable?: boolean;
+    });
+}
+/**
+ * Direct tuple-return shape per CANON.md §4.39: every SDK mutation or
+ * read returns `[null, value]` on success or `[CapxulError<Codes>, null]`
+ * on failure. The tuple is `readonly` so callers can destructure
+ * without worrying about mutation.
+ */
+type CapxulResult<T, Codes extends CapxulErrorCode = CapxulErrorCode> = readonly [null, T] | readonly [CapxulError<Codes>, null];
+/**
+ * Internal helper. Returns a concrete `CapxulError<"NOT_IMPLEMENTED">`
+ * suitable for `throw` from non-tuple surfaces (e.g. `verifyWebhook`).
+ */
+declare function notImplemented(method: string): CapxulError<"NOT_IMPLEMENTED">;
+/**
+ * Scaffold-only stub helper for every tuple-return SDK method. Returns
+ * the failed tuple `[CapxulError<Codes>, null]` carrying a
+ * `NOT_IMPLEMENTED` error.
+ *
+ * The `as CapxulError<Codes>` cast is intentionally unsound: runtime
+ * `code` is `"NOT_IMPLEMENTED"` even though the method's narrowed
+ * `Codes` union may not list it. This goes away in Slice F when real
+ * HTTP bodies replace every call site. Until then, callers shouldn't
+ * switch on the runtime `code` inside tests — the scaffold's contract
+ * is strictly type-level.
+ */
+declare function stub<T, Codes extends CapxulErrorCode = CapxulErrorCode>(method: string): CapxulResult<T, Codes>;
+
+export { CapxulError, type CapxulResult, notImplemented, stub };

package/dist/errors.d.ts

@@ -0,0 +1,55 @@
+import { CapxulErrorCode, CapxulErrorDetails, OperationId, CorrelationId } from '@repo/platform-kernel';
+
+/**
+ * Unified error class surfaced by every SDK method.
+ *
+ * Parameterized on `Codes` so individual method signatures can narrow
+ * to the subset of `CapxulErrorCode` they actually produce (per
+ * CANON.md §4.39 + §4.44 + sdk-surface.md §3a). The default
+ * `Codes = CapxulErrorCode` is the global catalog from
+ * `@repo/platform-kernel` — 34 values aligned with the wire
+ * `ErrorEnvelope.error.code` enum.
+ */
+declare class CapxulError<Codes extends CapxulErrorCode = CapxulErrorCode> extends Error {
+    readonly code: Codes;
+    readonly details?: CapxulErrorDetails;
+    readonly operationId?: OperationId;
+    readonly correlationId?: CorrelationId;
+    readonly retryable?: boolean;
+    constructor(init: {
+        code: Codes;
+        message: string;
+        cause?: unknown;
+        details?: CapxulErrorDetails;
+        operationId?: OperationId;
+        correlationId?: CorrelationId;
+        retryable?: boolean;
+    });
+}
+/**
+ * Direct tuple-return shape per CANON.md §4.39: every SDK mutation or
+ * read returns `[null, value]` on success or `[CapxulError<Codes>, null]`
+ * on failure. The tuple is `readonly` so callers can destructure
+ * without worrying about mutation.
+ */
+type CapxulResult<T, Codes extends CapxulErrorCode = CapxulErrorCode> = readonly [null, T] | readonly [CapxulError<Codes>, null];
+/**
+ * Internal helper. Returns a concrete `CapxulError<"NOT_IMPLEMENTED">`
+ * suitable for `throw` from non-tuple surfaces (e.g. `verifyWebhook`).
+ */
+declare function notImplemented(method: string): CapxulError<"NOT_IMPLEMENTED">;
+/**
+ * Scaffold-only stub helper for every tuple-return SDK method. Returns
+ * the failed tuple `[CapxulError<Codes>, null]` carrying a
+ * `NOT_IMPLEMENTED` error.
+ *
+ * The `as CapxulError<Codes>` cast is intentionally unsound: runtime
+ * `code` is `"NOT_IMPLEMENTED"` even though the method's narrowed
+ * `Codes` union may not list it. This goes away in Slice F when real
+ * HTTP bodies replace every call site. Until then, callers shouldn't
+ * switch on the runtime `code` inside tests — the scaffold's contract
+ * is strictly type-level.
+ */
+declare function stub<T, Codes extends CapxulErrorCode = CapxulErrorCode>(method: string): CapxulResult<T, Codes>;
+
+export { CapxulError, type CapxulResult, notImplemented, stub };

package/dist/errors.js

@@ -0,0 +1,31 @@
+// src/errors.ts
+var CapxulError = class extends Error {
+  code;
+  details;
+  operationId;
+  correlationId;
+  retryable;
+  constructor(init) {
+    super(
+      init.message,
+      init.cause !== void 0 ? { cause: init.cause } : void 0
+    );
+    this.name = "CapxulError";
+    this.code = init.code;
+    this.details = init.details;
+    this.operationId = init.operationId;
+    this.correlationId = init.correlationId;
+    this.retryable = init.retryable;
+  }
+};
+function notImplemented(method) {
+  return new CapxulError({
+    code: "NOT_IMPLEMENTED",
+    message: `${method} is not yet implemented in @capxul/sdk (Slice C scaffold).`
+  });
+}
+function stub(method) {
+  return [notImplemented(method), null];
+}
+
+export { CapxulError, notImplemented, stub };