@layervai/qurl 0.2.0

package/dist/cjs/errors.d.ts

@@ -0,0 +1,125 @@
+import type { QURLErrorData } from "./types.js";
+/**
+ * Sentinel `.code` values for SDK-internal failure modes (no real HTTP
+ * status applies). Exported as constants so consumers branching on
+ * `.code` don't have to duplicate string literals — e.g.
+ * `if (err.code === ERROR_CODE_CLIENT_VALIDATION) ...`.
+ *
+ * Server-driven `.code` values (e.g. `"rate_limited"`, `"forbidden"`)
+ * come from the API and aren't enumerated here — branch on the typed
+ * error subclass (`RateLimitError`, `AuthorizationError`, …) instead.
+ */
+export declare const ERROR_CODE_CLIENT_VALIDATION = "client_validation";
+export declare const ERROR_CODE_UNEXPECTED_RESPONSE = "unexpected_response";
+export declare const ERROR_CODE_NETWORK = "network_error";
+export declare const ERROR_CODE_TIMEOUT = "timeout";
+export declare const ERROR_CODE_RUNTIME = "runtime_error";
+/** Fallback `.code` when the server returns a non-RFC-7807 response (HTML proxy page, plaintext gateway error, JSON without `error` envelope). */
+export declare const ERROR_CODE_UNKNOWN = "unknown";
+/**
+ * Base error thrown by the qURL API client. Catch this to handle all SDK errors.
+ *
+ * **`status: 0` convention:** Client-detected failures — validation errors
+ * (`code: "client_validation"`), unexpected response shapes
+ * (`code: "unexpected_response"`), runtime capability errors
+ * (`code: "runtime_error"`), network errors (`code: "network_error"`), and
+ * timeouts (`code: "timeout"`) — all use `status: 0` because no real HTTP
+ * status code applies. To distinguish between these cases, branch on `.code`
+ * rather than `.status`. Non-zero `.status` always reflects a real HTTP
+ * status from the API (e.g. 400, 401, 429, 500).
+ *
+ * **`.code === "unknown"`** is a possible value when the server returns a
+ * non-RFC-7807 response (e.g. a Cloudflare HTML error page, a gateway
+ * timeout with a plaintext body, or a JSON body whose `error` envelope
+ * is missing). The HTTP `.status` is still real in those cases — use
+ * `.status` for the route, `.code` for the SDK-vs-API discriminant.
+ */
+export declare class QURLError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /**
+     * Human-readable error detail. **Always non-empty** — when the API
+     * omits `detail` (RFC 7807 allows this), the constructor falls back
+     * to `title`. Callers never need to null-check this property, even
+     * though `QURLErrorData.detail` is optional on the wire type.
+     */
+    readonly detail: string;
+    /** RFC 7807 problem-type URI, if the API includes one. */
+    readonly type?: string;
+    /** RFC 7807 occurrence URI, if the API includes one. */
+    readonly instance?: string;
+    readonly invalidFields?: Record<string, string>;
+    readonly requestId?: string;
+    readonly retryAfter?: number;
+    constructor(data: QURLErrorData);
+}
+/** 401 Unauthorized — invalid or missing API key. */
+export declare class AuthenticationError extends QURLError {
+    constructor(data: QURLErrorData);
+}
+/** 403 Forbidden — valid key but insufficient permissions/scope. */
+export declare class AuthorizationError extends QURLError {
+    constructor(data: QURLErrorData);
+}
+/** 404 Not Found — resource does not exist. */
+export declare class NotFoundError extends QURLError {
+    constructor(data: QURLErrorData);
+}
+/**
+ * 400/422 — invalid request parameters. Check `invalidFields` for per-field details.
+ *
+ * **Note:** This class covers two distinct failure modes:
+ * - `code: "client_validation"` — client-side preflight failures (bad
+ *   input caught before a round-trip).
+ * - `code: "unexpected_response"` — the server returned a response body
+ *   whose shape doesn't match the expected contract (e.g. a proxy
+ *   returning HTML on a passthrough status, or a batch response missing
+ *   required fields).
+ *
+ * `instanceof ValidationError` catches both. To distinguish them, check
+ * `.code` rather than using `instanceof` alone.
+ *
+ * **`.status` asymmetry within `code: "unexpected_response"`:**
+ * - Shape-guard failure on a parsed JSON body (wrong field types,
+ *   counts/length mismatch, per-entry contract violation): `.status`
+ *   is `0`. The HTTP status that produced the bad body is appended
+ *   to `.detail` as `(HTTP 400)` / `(HTTP 207)` etc. for diagnostics.
+ * - Non-JSON body on a 2xx or passthrough status (e.g. proxy HTML
+ *   error page, plaintext gateway error, truncated body): `.status`
+ *   is the actual HTTP status (e.g. `400`, `200`).
+ *
+ * Consumers branching purely on `.status` should branch on `.code`
+ * first, then `.detail` for shape-guard cases. See #59 for tracking
+ * a future unification of the two paths.
+ */
+export declare class ValidationError extends QURLError {
+    constructor(data: QURLErrorData);
+}
+/** 429 Too Many Requests. Check `retryAfter` for the server-suggested wait time. */
+export declare class RateLimitError extends QURLError {
+    constructor(data: QURLErrorData);
+}
+/** 5xx server-side error. */
+export declare class ServerError extends QURLError {
+    constructor(data: QURLErrorData);
+}
+/** Transport-level error — DNS failure, connection refused, etc. */
+export declare class NetworkError extends QURLError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Request timed out. */
+export declare class TimeoutError extends QURLError {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/** SDK runtime capability error — unsupported JS runtime, missing Web Crypto, etc. */
+export declare class RuntimeError extends QURLError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Create the appropriate QURLError subclass for an HTTP status code. */
+export declare function createError(data: QURLErrorData): QURLError;

package/dist/cjs/errors.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeError = exports.TimeoutError = exports.NetworkError = exports.ServerError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthorizationError = exports.AuthenticationError = exports.QURLError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_RUNTIME = exports.ERROR_CODE_TIMEOUT = exports.ERROR_CODE_NETWORK = exports.ERROR_CODE_UNEXPECTED_RESPONSE = exports.ERROR_CODE_CLIENT_VALIDATION = void 0;
+exports.createError = createError;
+/**
+ * Sentinel `.code` values for SDK-internal failure modes (no real HTTP
+ * status applies). Exported as constants so consumers branching on
+ * `.code` don't have to duplicate string literals — e.g.
+ * `if (err.code === ERROR_CODE_CLIENT_VALIDATION) ...`.
+ *
+ * Server-driven `.code` values (e.g. `"rate_limited"`, `"forbidden"`)
+ * come from the API and aren't enumerated here — branch on the typed
+ * error subclass (`RateLimitError`, `AuthorizationError`, …) instead.
+ */
+exports.ERROR_CODE_CLIENT_VALIDATION = "client_validation";
+exports.ERROR_CODE_UNEXPECTED_RESPONSE = "unexpected_response";
+exports.ERROR_CODE_NETWORK = "network_error";
+exports.ERROR_CODE_TIMEOUT = "timeout";
+exports.ERROR_CODE_RUNTIME = "runtime_error";
+/** Fallback `.code` when the server returns a non-RFC-7807 response (HTML proxy page, plaintext gateway error, JSON without `error` envelope). */
+exports.ERROR_CODE_UNKNOWN = "unknown";
+/**
+ * Base error thrown by the qURL API client. Catch this to handle all SDK errors.
+ *
+ * **`status: 0` convention:** Client-detected failures — validation errors
+ * (`code: "client_validation"`), unexpected response shapes
+ * (`code: "unexpected_response"`), runtime capability errors
+ * (`code: "runtime_error"`), network errors (`code: "network_error"`), and
+ * timeouts (`code: "timeout"`) — all use `status: 0` because no real HTTP
+ * status code applies. To distinguish between these cases, branch on `.code`
+ * rather than `.status`. Non-zero `.status` always reflects a real HTTP
+ * status from the API (e.g. 400, 401, 429, 500).
+ *
+ * **`.code === "unknown"`** is a possible value when the server returns a
+ * non-RFC-7807 response (e.g. a Cloudflare HTML error page, a gateway
+ * timeout with a plaintext body, or a JSON body whose `error` envelope
+ * is missing). The HTTP `.status` is still real in those cases — use
+ * `.status` for the route, `.code` for the SDK-vs-API discriminant.
+ */
+class QURLError extends Error {
+    status;
+    code;
+    /**
+     * Human-readable error detail. **Always non-empty** — when the API
+     * omits `detail` (RFC 7807 allows this), the constructor falls back
+     * to `title`. Callers never need to null-check this property, even
+     * though `QURLErrorData.detail` is optional on the wire type.
+     */
+    detail;
+    /** RFC 7807 problem-type URI, if the API includes one. */
+    type;
+    /** RFC 7807 occurrence URI, if the API includes one. */
+    instance;
+    invalidFields;
+    requestId;
+    retryAfter;
+    constructor(data) {
+        // RFC 7807 leaves `detail` optional; the API can legitimately omit it and
+        // `title` is required, so falling back to title keeps the Error.message
+        // meaningful instead of "Title (400): undefined".
+        const detail = data.detail ?? data.title;
+        super(`${data.title} (${data.status}): ${detail}`);
+        this.name = "QURLError";
+        this.status = data.status;
+        this.code = data.code;
+        this.detail = detail;
+        this.type = data.type;
+        this.instance = data.instance;
+        this.invalidFields = data.invalid_fields;
+        this.requestId = data.request_id;
+        this.retryAfter = data.retry_after;
+    }
+}
+exports.QURLError = QURLError;
+/** 401 Unauthorized — invalid or missing API key. */
+class AuthenticationError extends QURLError {
+    constructor(data) {
+        super(data);
+        this.name = "AuthenticationError";
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+/** 403 Forbidden — valid key but insufficient permissions/scope. */
+class AuthorizationError extends QURLError {
+    constructor(data) {
+        super(data);
+        this.name = "AuthorizationError";
+    }
+}
+exports.AuthorizationError = AuthorizationError;
+/** 404 Not Found — resource does not exist. */
+class NotFoundError extends QURLError {
+    constructor(data) {
+        super(data);
+        this.name = "NotFoundError";
+    }
+}
+exports.NotFoundError = NotFoundError;
+/**
+ * 400/422 — invalid request parameters. Check `invalidFields` for per-field details.
+ *
+ * **Note:** This class covers two distinct failure modes:
+ * - `code: "client_validation"` — client-side preflight failures (bad
+ *   input caught before a round-trip).
+ * - `code: "unexpected_response"` — the server returned a response body
+ *   whose shape doesn't match the expected contract (e.g. a proxy
+ *   returning HTML on a passthrough status, or a batch response missing
+ *   required fields).
+ *
+ * `instanceof ValidationError` catches both. To distinguish them, check
+ * `.code` rather than using `instanceof` alone.
+ *
+ * **`.status` asymmetry within `code: "unexpected_response"`:**
+ * - Shape-guard failure on a parsed JSON body (wrong field types,
+ *   counts/length mismatch, per-entry contract violation): `.status`
+ *   is `0`. The HTTP status that produced the bad body is appended
+ *   to `.detail` as `(HTTP 400)` / `(HTTP 207)` etc. for diagnostics.
+ * - Non-JSON body on a 2xx or passthrough status (e.g. proxy HTML
+ *   error page, plaintext gateway error, truncated body): `.status`
+ *   is the actual HTTP status (e.g. `400`, `200`).
+ *
+ * Consumers branching purely on `.status` should branch on `.code`
+ * first, then `.detail` for shape-guard cases. See #59 for tracking
+ * a future unification of the two paths.
+ */
+class ValidationError extends QURLError {
+    constructor(data) {
+        super(data);
+        this.name = "ValidationError";
+    }
+}
+exports.ValidationError = ValidationError;
+/** 429 Too Many Requests. Check `retryAfter` for the server-suggested wait time. */
+class RateLimitError extends QURLError {
+    constructor(data) {
+        super(data);
+        this.name = "RateLimitError";
+    }
+}
+exports.RateLimitError = RateLimitError;
+/** 5xx server-side error. */
+class ServerError extends QURLError {
+    constructor(data) {
+        super(data);
+        this.name = "ServerError";
+    }
+}
+exports.ServerError = ServerError;
+/** Transport-level error — DNS failure, connection refused, etc. */
+class NetworkError extends QURLError {
+    constructor(message, options) {
+        super({ status: 0, code: exports.ERROR_CODE_NETWORK, title: "Network Error", detail: message });
+        this.name = "NetworkError";
+        if (options?.cause) {
+            this.cause = options.cause;
+        }
+    }
+}
+exports.NetworkError = NetworkError;
+/** Request timed out. */
+class TimeoutError extends QURLError {
+    constructor(message = "Request timed out", options) {
+        super({ status: 0, code: exports.ERROR_CODE_TIMEOUT, title: "Timeout", detail: message });
+        this.name = "TimeoutError";
+        if (options?.cause) {
+            this.cause = options.cause;
+        }
+    }
+}
+exports.TimeoutError = TimeoutError;
+/** SDK runtime capability error — unsupported JS runtime, missing Web Crypto, etc. */
+class RuntimeError extends QURLError {
+    constructor(message, options) {
+        super({ status: 0, code: exports.ERROR_CODE_RUNTIME, title: "Runtime Error", detail: message });
+        this.name = "RuntimeError";
+        if (options && "cause" in options) {
+            this.cause = options.cause;
+        }
+    }
+}
+exports.RuntimeError = RuntimeError;
+const STATUS_ERROR_MAP = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: AuthorizationError,
+    404: NotFoundError,
+    422: ValidationError,
+    429: RateLimitError,
+};
+/** Create the appropriate QURLError subclass for an HTTP status code. */
+function createError(data) {
+    // Route by code first for SDK-internal failure modes that aren't a
+    // function of the HTTP status. `unexpected_response` is the canonical
+    // case: a 200 body with malformed JSON, a 500 body that isn't an
+    // error envelope, and a 400 body that isn't a batch result are all
+    // the same SDK failure (server returned a shape we can't interpret).
+    // Routing them all to `ValidationError` keeps `instanceof
+    // ValidationError` complete for code === "unexpected_response", as
+    // documented on the class.
+    if (data.code === exports.ERROR_CODE_UNEXPECTED_RESPONSE) {
+        return new ValidationError(data);
+    }
+    if (data.status >= 500) {
+        return new ServerError(data);
+    }
+    const ErrorClass = STATUS_ERROR_MAP[data.status] ?? QURLError;
+    return new ErrorClass(data);
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,4 @@
+export { QURLClient } from "./client.js";
+export { AuthenticationError, AuthorizationError, createError, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_NETWORK, ERROR_CODE_RUNTIME, ERROR_CODE_TIMEOUT, ERROR_CODE_UNEXPECTED_RESPONSE, ERROR_CODE_UNKNOWN, NetworkError, NotFoundError, QURLError, RateLimitError, RuntimeError, ServerError, TimeoutError, ValidationError, } from "./errors.js";
+export { VERSION } from "./version.js";
+export type { AccessCode, AccessCodeListOutput, AccessGrant, AccessPolicy, AccessToken, AgentBootstrapInput, AgentBootstrapOutput, AIAgentCategory, AIAgentPolicy, ApiKey, ApiKeyListOutput, ApiKeyScope, BatchCreateInput, BatchCreateOutput, BatchItemFailure, BatchItemResult, BatchItemSuccess, BillingInvoiceListOutput, ClientOptions, ConnectorInstallation, ConnectorInstallationCapabilities, ConnectorInstallationListOutput, ConnectorInstallationStats, CreateAccessCodeInput, CreateAccessCodeOutput, CreateApiKeyInput, CreateApiKeyOutput, CreateBillingCheckoutInput, CreateInput, CreateOutput, CreateQurlForResourceInput, CreateResourceInput, CreateWebhookInput, Customer, CheckoutSession, DnsRecord, Domain, DomainCheckDetail, DomainListOutput, DomainVerifyResult, ExtendInput, Invoice, ListApiKeysInput, ListBillingInvoicesInput, ListConnectorInstallationsInput, ListDomainsInput, ListInput, ListOutput, ListWebhooksInput, ListWebhookDeliveriesInput, Meta, MintInput, MintOutput, NHPServerPeerInfo, PaginatedOutput, PortalSession, QURL, QURLErrorData, QurlSummary, Quota, RedeemAccessCodeInput, RedeemAccessCodeOutput, RegisterDomainInput, Resource, ResourceDetail, ResourceListInput, ResourceListOutput, ResourceType, RequestOptions, ResolveInput, ResolveOutput, Session, SessionListOutput, SessionTerminateOutput, TombstoneInfo, UnpaginatedOutput, UpdateApiKeyInput, UpdateCustomerInput, UpdateInput, UpdateResourceInput, UpdateResourceQurlInput, UpdateWebhookInput, UsageCostEstimate, UsageCurrentPeriod, UsageDaily, UsageDailyEntry, Webhook, WebhookDelivery, WebhookDeliveryListOutput, WebhookEventType, WebhookEventTypeInfo, WebhookListOutput, WebhookPayload, WebhookWithSecret, } from "./types.js";

package/dist/cjs/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = exports.ValidationError = exports.TimeoutError = exports.ServerError = exports.RuntimeError = exports.RateLimitError = exports.QURLError = exports.NotFoundError = exports.NetworkError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_UNEXPECTED_RESPONSE = exports.ERROR_CODE_TIMEOUT = exports.ERROR_CODE_RUNTIME = exports.ERROR_CODE_NETWORK = exports.ERROR_CODE_CLIENT_VALIDATION = exports.createError = exports.AuthorizationError = exports.AuthenticationError = exports.QURLClient = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "QURLClient", { enumerable: true, get: function () { return client_js_1.QURLClient; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_js_1.AuthenticationError; } });
+Object.defineProperty(exports, "AuthorizationError", { enumerable: true, get: function () { return errors_js_1.AuthorizationError; } });
+Object.defineProperty(exports, "createError", { enumerable: true, get: function () { return errors_js_1.createError; } });
+Object.defineProperty(exports, "ERROR_CODE_CLIENT_VALIDATION", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_CLIENT_VALIDATION; } });
+Object.defineProperty(exports, "ERROR_CODE_NETWORK", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_NETWORK; } });
+Object.defineProperty(exports, "ERROR_CODE_RUNTIME", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_RUNTIME; } });
+Object.defineProperty(exports, "ERROR_CODE_TIMEOUT", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_TIMEOUT; } });
+Object.defineProperty(exports, "ERROR_CODE_UNEXPECTED_RESPONSE", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_UNEXPECTED_RESPONSE; } });
+Object.defineProperty(exports, "ERROR_CODE_UNKNOWN", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_UNKNOWN; } });
+Object.defineProperty(exports, "NetworkError", { enumerable: true, get: function () { return errors_js_1.NetworkError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_js_1.NotFoundError; } });
+Object.defineProperty(exports, "QURLError", { enumerable: true, get: function () { return errors_js_1.QURLError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_js_1.RateLimitError; } });
+Object.defineProperty(exports, "RuntimeError", { enumerable: true, get: function () { return errors_js_1.RuntimeError; } });
+Object.defineProperty(exports, "ServerError", { enumerable: true, get: function () { return errors_js_1.ServerError; } });
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_js_1.TimeoutError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_js_1.ValidationError; } });
+var version_js_1 = require("./version.js");
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_js_1.VERSION; } });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}