@37signals/fizzy 0.1.0

package/dist/errors.js

@@ -0,0 +1,187 @@
+/**
+ * Structured error types for the Fizzy SDK.
+ *
+ * Provides typed errors with error codes, hints, and exit codes
+ * for CLI-friendly error handling.
+ */
+const MAX_ERROR_MESSAGE_LENGTH = 500;
+function truncateErrorMessage(s, maxLen = MAX_ERROR_MESSAGE_LENGTH) {
+    if (s.length <= maxLen)
+        return s;
+    return s.slice(0, maxLen - 3) + "...";
+}
+const EXIT_CODES = {
+    usage: 1,
+    not_found: 2,
+    auth_required: 3,
+    forbidden: 4,
+    rate_limit: 5,
+    network: 6,
+    api_error: 7,
+    ambiguous: 8,
+    validation: 9,
+};
+/**
+ * Structured error class for Fizzy API errors.
+ */
+export class FizzyError extends Error {
+    code;
+    hint;
+    httpStatus;
+    retryable;
+    retryAfter;
+    requestId;
+    constructor(code, message, options) {
+        super(message);
+        this.name = "FizzyError";
+        this.code = code;
+        this.hint = options?.hint;
+        this.httpStatus = options?.httpStatus;
+        this.retryable = options?.retryable ?? false;
+        this.retryAfter = options?.retryAfter;
+        this.requestId = options?.requestId;
+        if (options?.cause) {
+            this.cause = options.cause;
+        }
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, FizzyError);
+        }
+    }
+    get exitCode() {
+        return EXIT_CODES[this.code];
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            hint: this.hint,
+            httpStatus: this.httpStatus,
+            retryable: this.retryable,
+            retryAfter: this.retryAfter,
+            requestId: this.requestId,
+        };
+    }
+}
+/**
+ * Factory functions for creating common error types.
+ */
+export const Errors = {
+    auth: (hint, cause) => new FizzyError("auth_required", "Authentication required", {
+        hint: hint ?? "Check your access token or cookie session",
+        httpStatus: 401,
+        cause,
+    }),
+    forbidden: (hint, cause) => new FizzyError("forbidden", "Access denied", {
+        hint: hint ?? "You do not have permission to access this resource",
+        httpStatus: 403,
+        cause,
+    }),
+    notFound: (resource, id) => new FizzyError("not_found", id ? `${resource} ${id} not found` : `${resource} not found`, { httpStatus: 404 }),
+    rateLimit: (retryAfter, cause) => new FizzyError("rate_limit", "Rate limit exceeded", {
+        retryable: true,
+        httpStatus: 429,
+        hint: retryAfter ? `Retry after ${retryAfter} seconds` : "Please slow down requests",
+        retryAfter,
+        cause,
+    }),
+    validation: (message, hint) => new FizzyError("validation", message, {
+        httpStatus: 400,
+        hint,
+    }),
+    ambiguous: (resource, matches) => {
+        const hint = matches.length > 0 && matches.length <= 5
+            ? `Did you mean: ${matches.join(", ")}`
+            : "Be more specific";
+        return new FizzyError("ambiguous", `Ambiguous ${resource}`, { hint });
+    },
+    network: (message, cause) => new FizzyError("network", message, {
+        retryable: true,
+        hint: "Check your network connection",
+        cause,
+    }),
+    apiError: (message, httpStatus, options) => new FizzyError("api_error", message, {
+        httpStatus,
+        ...options,
+    }),
+};
+/**
+ * Creates a FizzyError from an HTTP response.
+ */
+export async function errorFromResponse(response, requestId) {
+    const httpStatus = response.status;
+    const retryAfter = parseRetryAfter(response.headers.get("Retry-After"));
+    let message = response.statusText || "Request failed";
+    let hint;
+    try {
+        const body = await response.json();
+        if (typeof body === "object" && body !== null) {
+            if ("error" in body && typeof body.error === "string") {
+                message = truncateErrorMessage(body.error);
+            }
+            if ("error_description" in body && typeof body.error_description === "string") {
+                hint = truncateErrorMessage(body.error_description);
+            }
+        }
+    }
+    catch {
+        // Body is not JSON or empty
+    }
+    switch (httpStatus) {
+        case 401:
+            return new FizzyError("auth_required", message, { httpStatus, hint, requestId });
+        case 403:
+            return new FizzyError("forbidden", message, { httpStatus, hint, requestId });
+        case 404:
+            return new FizzyError("not_found", message, { httpStatus, hint, requestId });
+        case 429:
+            return new FizzyError("rate_limit", message, {
+                httpStatus,
+                retryable: true,
+                retryAfter,
+                hint: retryAfter ? `Retry after ${retryAfter} seconds` : hint,
+                requestId,
+            });
+        case 400:
+        case 422:
+            return new FizzyError("validation", message, { httpStatus, hint, requestId });
+        default: {
+            const retryable = httpStatus >= 500 && httpStatus < 600;
+            return new FizzyError("api_error", message, {
+                httpStatus,
+                retryable,
+                hint,
+                requestId,
+            });
+        }
+    }
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return undefined;
+    const seconds = parseInt(value, 10);
+    if (!isNaN(seconds) && seconds > 0) {
+        return seconds;
+    }
+    const date = Date.parse(value);
+    if (!isNaN(date)) {
+        const diffMs = date - Date.now();
+        if (diffMs > 0) {
+            return Math.ceil(diffMs / 1000);
+        }
+    }
+    return undefined;
+}
+/**
+ * Type guard to check if an error is a FizzyError.
+ */
+export function isFizzyError(error) {
+    return error instanceof FizzyError;
+}
+/**
+ * Type guard to check if an error is a specific type of FizzyError.
+ */
+export function isErrorCode(error, code) {
+    return isFizzyError(error) && error.code === code;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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