orbitmap 0.4.2 → 0.4.4

package/dist/errors.d.ts

@@ -17,16 +17,83 @@ export interface FlatApiErrorBody {
 }
 /** No local workspace directory could be resolved (see workspace-resolve.ts). */
 export declare const WORKSPACE_NOT_FOUND = "WORKSPACE_NOT_FOUND";
+/**
+ * Code every *client-side* argument rejection carries — the same code and status the API
+ * uses for a validation failure, so a `--json` consumer can branch on `error.code` without
+ * caring whether the CLI or the server rejected the call.
+ */
+export declare const VALIDATION_ERROR = "VALIDATION_ERROR";
+/** HTTP status the API uses for validation failures. */
+export declare const VALIDATION_STATUS = 422;
 /** The command needs an area but none could be resolved (same code the API uses). */
 export declare const AREA_CONTEXT_REQUIRED = "AREA_CONTEXT_REQUIRED";
+/**
+ * The API could not resolve a workspace: no `X-Orbitmap-Workspace`, no area to derive one
+ * from, and no unique workspace to auto-detect. Raised server-side only.
+ */
+export declare const WORKSPACE_CONTEXT_REQUIRED = "WORKSPACE_CONTEXT_REQUIRED";
+/**
+ * `X-Orbitmap-Workspace` and `X-Orbitmap-Area` named different workspaces (422). Raised
+ * server-side only.
+ */
+export declare const AREA_WORKSPACE_MISMATCH = "AREA_WORKSPACE_MISMATCH";
+/** The caller's agent has no access to the area (same code the API uses). */
+export declare const NO_AREA_ACCESS = "NO_AREA_ACCESS";
+/** The caller's role in the area is too low for the operation (same code the API uses). */
+export declare const INSUFFICIENT_AREA_ROLE = "INSUFFICIENT_AREA_ROLE";
+/** The agent's owner is not a member of the area (403). Raised server-side only. */
+export declare const OWNER_NO_AREA_ACCESS = "OWNER_NO_AREA_ACCESS";
+/** A referenced agent is not assigned to the area (422). Raised server-side only. */
+export declare const AGENT_NOT_IN_AREA = "AGENT_NOT_IN_AREA";
+/** A referenced user is not a member of the area (422). Raised server-side only. */
+export declare const USER_NOT_IN_AREA = "USER_NOT_IN_AREA";
+/**
+ * Legacy → canonical error-code aliases, in ONE place.
+ *
+ * The API is renaming its `PROJECT_*` codes to `AREA_*`. Both spellings mean exactly the
+ * same thing, and a client that understands only one of them breaks the moment the server
+ * flips: an old CLI would stop recognising the new codes, a new CLI would stop recognising
+ * the ones still in flight. Every site that *dispatches* on an error code must therefore
+ * compare against {@link OrbitMapAPIError.canonicalCode} (or use {@link isErrorCode}), never
+ * against the raw wire code.
+ *
+ * This map is read-only in one direction on purpose — `AREA_*` is canonical; the `PROJECT_*`
+ * spellings are accepted, never produced. The wire code itself is preserved verbatim on the
+ * error (and in `--json` output), so user-facing messages and exit codes do not change for
+ * either spelling.
+ */
+export declare const ERROR_CODE_ALIASES: Readonly<Record<string, string>>;
+/**
+ * The canonical spelling of an error code: legacy `PROJECT_*` codes map to their `AREA_*`
+ * equivalent, everything else is returned unchanged.
+ */
+export declare function normalizeErrorCode(code: string): string;
+/**
+ * `true` when `code` is the given canonical code or any of its accepted aliases. Use this
+ * instead of `error.code === SOME_CODE` at dispatch sites.
+ */
+export declare function isErrorCode(code: string, canonical: string): boolean;
 export declare class OrbitMapAPIError extends Error {
+    /** The code exactly as it arrived on the wire — what gets printed and JSON-serialised. */
     readonly code: string;
+    /**
+     * {@link code} normalised through {@link ERROR_CODE_ALIASES}. Compare against this (never
+     * against {@link code}) when branching on an error code, so the CLI keeps working across
+     * the API's `PROJECT_*` → `AREA_*` rename.
+     */
+    readonly canonicalCode: string;
     readonly status: number;
     readonly details?: Record<string, unknown>;
     constructor(message: string, code: string, status: number, details?: Record<string, unknown>);
     static fromResponse(body: ApiErrorBody): OrbitMapAPIError;
     static fromFlatResponse(body: FlatApiErrorBody, httpStatus: number): OrbitMapAPIError;
     static workspaceNotFound(message?: string): OrbitMapAPIError;
+    /**
+     * A client-side argument rejection (bad enum value, missing required input, unparsable
+     * JSON, …), shaped exactly like a server validation error so `--json` consumers see one
+     * envelope with `code`/`status`/`details` no matter who rejected the call.
+     */
+    static validation(message: string, details?: Record<string, unknown>): OrbitMapAPIError;
     static areaContextRequired(message?: string, details?: Record<string, unknown>): OrbitMapAPIError;
     static isApiErrorBody(body: unknown): body is ApiErrorBody;
     static isFlatApiErrorBody(body: unknown): body is FlatApiErrorBody;

package/dist/errors.js

@@ -1,19 +1,93 @@
 /** No local workspace directory could be resolved (see workspace-resolve.ts). */
 export const WORKSPACE_NOT_FOUND = 'WORKSPACE_NOT_FOUND';
+/**
+ * Code every *client-side* argument rejection carries — the same code and status the API
+ * uses for a validation failure, so a `--json` consumer can branch on `error.code` without
+ * caring whether the CLI or the server rejected the call.
+ */
+export const VALIDATION_ERROR = 'VALIDATION_ERROR';
+/** HTTP status the API uses for validation failures. */
+export const VALIDATION_STATUS = 422;
 /** The command needs an area but none could be resolved (same code the API uses). */
 export const AREA_CONTEXT_REQUIRED = 'AREA_CONTEXT_REQUIRED';
+/**
+ * The API could not resolve a workspace: no `X-Orbitmap-Workspace`, no area to derive one
+ * from, and no unique workspace to auto-detect. Raised server-side only.
+ */
+export const WORKSPACE_CONTEXT_REQUIRED = 'WORKSPACE_CONTEXT_REQUIRED';
+/**
+ * `X-Orbitmap-Workspace` and `X-Orbitmap-Area` named different workspaces (422). Raised
+ * server-side only.
+ */
+export const AREA_WORKSPACE_MISMATCH = 'AREA_WORKSPACE_MISMATCH';
+/** The caller's agent has no access to the area (same code the API uses). */
+export const NO_AREA_ACCESS = 'NO_AREA_ACCESS';
+/** The caller's role in the area is too low for the operation (same code the API uses). */
+export const INSUFFICIENT_AREA_ROLE = 'INSUFFICIENT_AREA_ROLE';
+/** The agent's owner is not a member of the area (403). Raised server-side only. */
+export const OWNER_NO_AREA_ACCESS = 'OWNER_NO_AREA_ACCESS';
+/** A referenced agent is not assigned to the area (422). Raised server-side only. */
+export const AGENT_NOT_IN_AREA = 'AGENT_NOT_IN_AREA';
+/** A referenced user is not a member of the area (422). Raised server-side only. */
+export const USER_NOT_IN_AREA = 'USER_NOT_IN_AREA';
+/**
+ * Legacy → canonical error-code aliases, in ONE place.
+ *
+ * The API is renaming its `PROJECT_*` codes to `AREA_*`. Both spellings mean exactly the
+ * same thing, and a client that understands only one of them breaks the moment the server
+ * flips: an old CLI would stop recognising the new codes, a new CLI would stop recognising
+ * the ones still in flight. Every site that *dispatches* on an error code must therefore
+ * compare against {@link OrbitMapAPIError.canonicalCode} (or use {@link isErrorCode}), never
+ * against the raw wire code.
+ *
+ * This map is read-only in one direction on purpose — `AREA_*` is canonical; the `PROJECT_*`
+ * spellings are accepted, never produced. The wire code itself is preserved verbatim on the
+ * error (and in `--json` output), so user-facing messages and exit codes do not change for
+ * either spelling.
+ */
+export const ERROR_CODE_ALIASES = Object.freeze({
+    PROJECT_CONTEXT_REQUIRED: AREA_CONTEXT_REQUIRED,
+    NO_PROJECT_ACCESS: NO_AREA_ACCESS,
+    INSUFFICIENT_PROJECT_ROLE: INSUFFICIENT_AREA_ROLE,
+    PROJECT_WORKSPACE_MISMATCH: AREA_WORKSPACE_MISMATCH,
+    OWNER_NO_PROJECT_ACCESS: OWNER_NO_AREA_ACCESS,
+    AGENT_NOT_IN_PROJECT: AGENT_NOT_IN_AREA,
+    USER_NOT_IN_PROJECT: USER_NOT_IN_AREA,
+});
+/**
+ * The canonical spelling of an error code: legacy `PROJECT_*` codes map to their `AREA_*`
+ * equivalent, everything else is returned unchanged.
+ */
+export function normalizeErrorCode(code) {
+    return ERROR_CODE_ALIASES[code] ?? code;
+}
+/**
+ * `true` when `code` is the given canonical code or any of its accepted aliases. Use this
+ * instead of `error.code === SOME_CODE` at dispatch sites.
+ */
+export function isErrorCode(code, canonical) {
+    return normalizeErrorCode(code) === normalizeErrorCode(canonical);
+}
 const FLAT_ERROR_CODES = {
     402: 'PAYMENT_REQUIRED',
     429: 'RATE_LIMITED',
 };
 export class OrbitMapAPIError extends Error {
+    /** The code exactly as it arrived on the wire — what gets printed and JSON-serialised. */
     code;
+    /**
+     * {@link code} normalised through {@link ERROR_CODE_ALIASES}. Compare against this (never
+     * against {@link code}) when branching on an error code, so the CLI keeps working across
+     * the API's `PROJECT_*` → `AREA_*` rename.
+     */
+    canonicalCode;
     status;
     details;
     constructor(message, code, status, details) {
         super(message);
         this.name = 'OrbitMapAPIError';
         this.code = code;
+        this.canonicalCode = normalizeErrorCode(code);
         this.status = status;
         this.details = details;
     }
@@ -36,6 +110,14 @@ export class OrbitMapAPIError extends Error {
             'No OrbitMap workspace found. Run `orbitmap init` to create one, or point at an ' +
                 'existing workspace with --workspace <path> or ORBITMAP_WORKSPACE.', WORKSPACE_NOT_FOUND, 404);
     }
+    /**
+     * A client-side argument rejection (bad enum value, missing required input, unparsable
+     * JSON, …), shaped exactly like a server validation error so `--json` consumers see one
+     * envelope with `code`/`status`/`details` no matter who rejected the call.
+     */
+    static validation(message, details) {
+        return new OrbitMapAPIError(message, VALIDATION_ERROR, VALIDATION_STATUS, details);
+    }
     static areaContextRequired(message, details) {
         return new OrbitMapAPIError(message ||
             'Area context is required. Pass --area <slug>, set ORBITMAP_AREA, or set a default ' +

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}