@adhd/apigen-errors 0.1.0

package/index.d.ts

@@ -0,0 +1 @@
+export { ERROR_CODES, type ApiErrorCode, HTTP_STATUS, GRPC_CODE, CLI_EXIT_CODE, MCP_ERROR_KIND, statusMaps, ApiError, type StreamingPhase, type BeforeFirstChunkError, type AfterFirstChunkError, type StreamingErrorCarrier, toStreamingError, isBeforeFirstChunk, isAfterFirstChunk, } from './lib/errors';

package/index.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=["invalid_argument","unauthenticated","permission_denied","not_found","internal"],r={invalid_argument:400,unauthenticated:401,permission_denied:403,not_found:404,internal:500},i={invalid_argument:"INVALID_ARGUMENT",unauthenticated:"UNAUTHENTICATED",permission_denied:"PERMISSION_DENIED",not_found:"NOT_FOUND",internal:"INTERNAL"},s={invalid_argument:2,unauthenticated:3,permission_denied:3,not_found:4,internal:1},o={invalid_argument:"error",unauthenticated:"error",permission_denied:"error",not_found:"error",internal:"error"},d={http:r,grpc:i,cli:s,mcp:o};class _ extends Error{constructor(e,n,a){super(n),this.name="ApiError",this.code=e,this.details=a,Object.setPrototypeOf(this,new.target.prototype)}toJSON(){const e={code:this.code,message:this.message};return this.details!==void 0&&(e.details=this.details),e}}function c(t,e,n=0){return t==="before-first-chunk"?{phase:t,error:e}:{phase:t,error:e,chunksDelivered:n}}function E(t){return t.phase==="before-first-chunk"}function f(t){return t.phase==="after-first-chunk"}exports.ApiError=_;exports.CLI_EXIT_CODE=s;exports.ERROR_CODES=u;exports.GRPC_CODE=i;exports.HTTP_STATUS=r;exports.MCP_ERROR_KIND=o;exports.isAfterFirstChunk=f;exports.isBeforeFirstChunk=E;exports.statusMaps=d;exports.toStreamingError=c;

package/index.mjs

@@ -0,0 +1,70 @@
+const u = [
+  "invalid_argument",
+  "unauthenticated",
+  "permission_denied",
+  "not_found",
+  "internal"
+], i = {
+  invalid_argument: 400,
+  unauthenticated: 401,
+  permission_denied: 403,
+  not_found: 404,
+  internal: 500
+}, o = {
+  invalid_argument: "INVALID_ARGUMENT",
+  unauthenticated: "UNAUTHENTICATED",
+  permission_denied: "PERMISSION_DENIED",
+  not_found: "NOT_FOUND",
+  internal: "INTERNAL"
+}, s = {
+  invalid_argument: 2,
+  unauthenticated: 3,
+  permission_denied: 3,
+  not_found: 4,
+  internal: 1
+}, a = {
+  invalid_argument: "error",
+  unauthenticated: "error",
+  permission_denied: "error",
+  not_found: "error",
+  internal: "error"
+}, d = {
+  http: i,
+  grpc: o,
+  cli: s,
+  mcp: a
+};
+class c extends Error {
+  constructor(n, e, r) {
+    super(e), this.name = "ApiError", this.code = n, this.details = r, Object.setPrototypeOf(this, new.target.prototype);
+  }
+  /** Serialise to a plain object suitable for JSON transport. */
+  toJSON() {
+    const n = {
+      code: this.code,
+      message: this.message
+    };
+    return this.details !== void 0 && (n.details = this.details), n;
+  }
+}
+function _(t, n, e = 0) {
+  return t === "before-first-chunk" ? { phase: t, error: n } : { phase: t, error: n, chunksDelivered: e };
+}
+function f(t) {
+  return t.phase === "before-first-chunk";
+}
+function h(t) {
+  return t.phase === "after-first-chunk";
+}
+export {
+  c as ApiError,
+  s as CLI_EXIT_CODE,
+  u as ERROR_CODES,
+  o as GRPC_CODE,
+  i as HTTP_STATUS,
+  a as MCP_ERROR_KIND,
+  h as isAfterFirstChunk,
+  f as isBeforeFirstChunk,
+  d as statusMaps,
+  _ as toStreamingError
+};

package/lib/errors.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @adhd/apigen-errors
+ *
+ * Canonical error taxonomy for apigen — §9.1 of the apigen SPEC.
+ *
+ * Exports:
+ *  - `ApiErrorCode`   — the gRPC-style canonical code set (string union + const object)
+ *  - `ApiError`       — the thrown error class carrying code + message + details
+ *  - `HTTP_STATUS`    — code → HTTP status code map
+ *  - `GRPC_CODE`      — code → gRPC status code name map
+ *  - `CLI_EXIT_CODE`  — code → CLI process exit code map
+ *  - `MCP_ERROR_KIND` — code → MCP error shape indicator ('error')
+ *  - `statusMaps`     — convenience bundle of all four maps
+ *  - `StreamingPhase` — 'before-first-chunk' | 'after-first-chunk' discriminant
+ *  - `StreamingErrorCarrier` — discriminated union: how an in-flight stream delivers a terminal error
+ *  - `toStreamingError` — factory that wraps an ApiError into the correct carrier for the phase
+ */
+/** The five gRPC-style canonical error codes recognised by apigen. */
+export declare const ERROR_CODES: readonly ["invalid_argument", "unauthenticated", "permission_denied", "not_found", "internal"];
+/** String-union type for the canonical error codes. */
+export type ApiErrorCode = (typeof ERROR_CODES)[number];
+/** Maps each canonical code to its HTTP status code. */
+export declare const HTTP_STATUS: Record<ApiErrorCode, number>;
+/** Maps each canonical code to its gRPC status name. */
+export declare const GRPC_CODE: Record<ApiErrorCode, string>;
+/** Maps each canonical code to its CLI process exit code. */
+export declare const CLI_EXIT_CODE: Record<ApiErrorCode, number>;
+/**
+ * MCP surfaces all apigen errors as the MCP `error` result kind.
+ * Maps each canonical code to the MCP error shape indicator.
+ */
+export declare const MCP_ERROR_KIND: Record<ApiErrorCode, 'error'>;
+/** Convenience bundle: all four transport maps keyed by transport name. */
+export declare const statusMaps: {
+    readonly http: Record<"invalid_argument" | "unauthenticated" | "permission_denied" | "not_found" | "internal", number>;
+    readonly grpc: Record<"invalid_argument" | "unauthenticated" | "permission_denied" | "not_found" | "internal", string>;
+    readonly cli: Record<"invalid_argument" | "unauthenticated" | "permission_denied" | "not_found" | "internal", number>;
+    readonly mcp: Record<"invalid_argument" | "unauthenticated" | "permission_denied" | "not_found" | "internal", "error">;
+};
+/**
+ * The canonical apigen error.  Every transport adapter catches this and maps
+ * `code` to the native status using the tables above.
+ */
+export declare class ApiError extends Error {
+    /** gRPC-style canonical error code. */
+    readonly code: ApiErrorCode;
+    /** Optional structured details (passed through to MCP / HTTP body). */
+    readonly details?: unknown;
+    constructor(code: ApiErrorCode, message: string, details?: unknown);
+    /** Serialise to a plain object suitable for JSON transport. */
+    toJSON(): {
+        code: ApiErrorCode;
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * Discriminant that records whether the first chunk was already flushed.
+ * Determines the carrier shape used to deliver a terminal stream error.
+ */
+export type StreamingPhase = 'before-first-chunk' | 'after-first-chunk';
+/**
+ * Carrier for a terminal streaming error **before** the first chunk was sent.
+ * Adapters handle this identically to a normal (non-streaming) §9 error.
+ */
+export interface BeforeFirstChunkError {
+    readonly phase: 'before-first-chunk';
+    /** The underlying canonical error. */
+    readonly error: ApiError;
+}
+/**
+ * Carrier for a terminal streaming error **after** the first chunk was flushed.
+ * The status line is already gone; error must be delivered in-band per transport:
+ *
+ * | Transport        | Mechanism                                            |
+ * |------------------|------------------------------------------------------|
+ * | HTTP SSE/chunked | terminal `event: error` frame carrying the ApiError  |
+ * | gRPC             | trailing status (native gRPC trailers)                |
+ * | MCP              | progressive error notification                       |
+ * | CLI              | flush partial stdout, write ApiError to stderr, exit |
+ */
+export interface AfterFirstChunkError {
+    readonly phase: 'after-first-chunk';
+    /** The underlying canonical error, to be delivered in-band. */
+    readonly error: ApiError;
+    /**
+     * The number of chunks successfully delivered before the error occurred.
+     * Informational — lets CLI adapters decide whether stdout has content.
+     */
+    readonly chunksDelivered: number;
+}
+/** Discriminated union of the two streaming error carrier shapes. */
+export type StreamingErrorCarrier = BeforeFirstChunkError | AfterFirstChunkError;
+/**
+ * Factory: wrap an `ApiError` in the appropriate streaming carrier.
+ *
+ * @param phase           - whether the first chunk was already flushed
+ * @param error           - the terminal error
+ * @param chunksDelivered - (after-first-chunk only) chunks sent before failure
+ */
+export declare function toStreamingError(phase: 'before-first-chunk', error: ApiError): BeforeFirstChunkError;
+export declare function toStreamingError(phase: 'after-first-chunk', error: ApiError, chunksDelivered: number): AfterFirstChunkError;
+/**
+ * Type guard: narrows a `StreamingErrorCarrier` to `BeforeFirstChunkError`.
+ */
+export declare function isBeforeFirstChunk(c: StreamingErrorCarrier): c is BeforeFirstChunkError;
+/**
+ * Type guard: narrows a `StreamingErrorCarrier` to `AfterFirstChunkError`.
+ */
+export declare function isAfterFirstChunk(c: StreamingErrorCarrier): c is AfterFirstChunkError;

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@adhd/apigen-errors",
+  "version": "0.1.0",
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "typings": "./index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}