@videxo/sdk 0.0.0-stage → 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,80 @@
+import type { CommandProblem, FieldError, Problem } from './types.ts';
+/** The API's documented error codes (`code` of a problem details answer). */
+export type ApiErrorCode = Problem['code'];
+/**
+ * Codes the SDK sets itself, when there is no problem details answer to read:
+ *
+ * - `network_error`: the request did not get an answer (DNS, TLS, a reset connection).
+ * - `timeout`: no answer within `timeoutMs`.
+ * - `aborted`: the caller's `AbortSignal` stopped the request or the wait.
+ * - `wait_timeout`: `jobs.wait()` gave up before the job ended.
+ * - `http_error`: an error answer that is not problem details (a proxy's HTML page, for example).
+ * - `invalid_response`: a successful answer the SDK could not read.
+ * - `output_not_found`, `output_ambiguous`: `outputs.url()` or `outputs.download()` named an output
+ *   the job does not have, or a name several of its files share (use the file's alias).
+ */
+export declare const SDK_ERROR_CODES: readonly ["network_error", "timeout", "aborted", "wait_timeout", "http_error", "invalid_response", "output_not_found", "output_ambiguous"];
+export type SdkErrorCode = (typeof SDK_ERROR_CODES)[number];
+export type VidexoErrorCode = ApiErrorCode | SdkErrorCode;
+export type VidexoErrorInit = {
+    status: number | null;
+    code: VidexoErrorCode;
+    title: string;
+    detail: string;
+    type?: string | null;
+    errors?: FieldError[];
+    problems?: CommandProblem[];
+    retryAfter?: number | null;
+    reason?: string | null;
+    retryable?: boolean | null;
+    requestId?: string | null;
+    body?: unknown;
+    cause?: unknown;
+};
+/**
+ * Every failure of a call: a problem details answer of the API (`status`, `code`, `reason`, `title`,
+ * `detail`, `type`, `retryable`, `requestId`, `errors`, `problems`), or one of the SDK's own codes
+ * with `status` null. Programs branch on `code`, and on `reason` for the finer case. The message
+ * never holds the API key.
+ */
+export declare class VidexoError extends Error {
+    readonly name = "VidexoError";
+    /** The HTTP status; null when no answer came (`network_error`, `timeout`, `aborted`, ...). */
+    readonly status: number | null;
+    readonly code: VidexoErrorCode;
+    /** The code's fixed sentence. */
+    readonly title: string;
+    /** What happened this time, for people; it may change. */
+    readonly detail: string;
+    /** `https://videxo.io/docs/errors#<code>` for an API error; null otherwise. */
+    readonly type: string | null;
+    /** With `invalid_request`: one entry per field that failed. */
+    readonly errors: FieldError[];
+    /** With `command_invalid`: why the command is not accepted. */
+    readonly problems: CommandProblem[];
+    /** The documented finer case of `code` (the Errors page lists them); null without one. */
+    readonly reason: string | null;
+    /** The API's hint whether the same request can succeed later; null for the SDK's own codes. */
+    readonly retryable: boolean | null;
+    /** The answer's `Request-Id` (body or header); quote it to support. Null when no answer came. */
+    readonly requestId: string | null;
+    /** Seconds from the answer's `Retry-After` header (429, 503); null without one. */
+    readonly retryAfter: number | null;
+    /** The answer's body as received (parsed JSON or text); undefined when no answer came. */
+    readonly body: unknown;
+    constructor(init: VidexoErrorInit);
+}
+/** An error with one of the SDK's own codes. */
+export declare function sdkError(code: SdkErrorCode, detail: string, extra?: Partial<VidexoErrorInit>): VidexoError;
+/** Seconds of a `Retry-After` header, as a number of seconds or an HTTP date; null when absent or unreadable. */
+export declare function retryAfterSeconds(value: string | null, now?: number): number | null;
+/** The error of a non-2xx answer whose body was read as `body` (parsed JSON, or the text when it was not JSON). */
+export declare function errorFromResponse(response: Response, body: unknown): VidexoError;
+/** Why a webhook was refused by `verifyWebhook`. */
+export type VidexoWebhookErrorCode = 'missing_headers' | 'invalid_secret' | 'invalid_timestamp' | 'invalid_signature' | 'invalid_payload';
+/** A webhook that did not pass verification: answer it with a 400 and do not act on it. */
+export declare class VidexoWebhookError extends Error {
+    readonly name = "VidexoWebhookError";
+    readonly code: VidexoWebhookErrorCode;
+    constructor(code: VidexoWebhookErrorCode, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,132 @@
+/**
+ * Codes the SDK sets itself, when there is no problem details answer to read:
+ *
+ * - `network_error`: the request did not get an answer (DNS, TLS, a reset connection).
+ * - `timeout`: no answer within `timeoutMs`.
+ * - `aborted`: the caller's `AbortSignal` stopped the request or the wait.
+ * - `wait_timeout`: `jobs.wait()` gave up before the job ended.
+ * - `http_error`: an error answer that is not problem details (a proxy's HTML page, for example).
+ * - `invalid_response`: a successful answer the SDK could not read.
+ * - `output_not_found`, `output_ambiguous`: `outputs.url()` or `outputs.download()` named an output
+ *   the job does not have, or a name several of its files share (use the file's alias).
+ */
+export const SDK_ERROR_CODES = [
+    'network_error',
+    'timeout',
+    'aborted',
+    'wait_timeout',
+    'http_error',
+    'invalid_response',
+    'output_not_found',
+    'output_ambiguous',
+];
+/**
+ * Every failure of a call: a problem details answer of the API (`status`, `code`, `reason`, `title`,
+ * `detail`, `type`, `retryable`, `requestId`, `errors`, `problems`), or one of the SDK's own codes
+ * with `status` null. Programs branch on `code`, and on `reason` for the finer case. The message
+ * never holds the API key.
+ */
+export class VidexoError extends Error {
+    name = 'VidexoError';
+    /** The HTTP status; null when no answer came (`network_error`, `timeout`, `aborted`, ...). */
+    status;
+    code;
+    /** The code's fixed sentence. */
+    title;
+    /** What happened this time, for people; it may change. */
+    detail;
+    /** `https://videxo.io/docs/errors#<code>` for an API error; null otherwise. */
+    type;
+    /** With `invalid_request`: one entry per field that failed. */
+    errors;
+    /** With `command_invalid`: why the command is not accepted. */
+    problems;
+    /** The documented finer case of `code` (the Errors page lists them); null without one. */
+    reason;
+    /** The API's hint whether the same request can succeed later; null for the SDK's own codes. */
+    retryable;
+    /** The answer's `Request-Id` (body or header); quote it to support. Null when no answer came. */
+    requestId;
+    /** Seconds from the answer's `Retry-After` header (429, 503); null without one. */
+    retryAfter;
+    /** The answer's body as received (parsed JSON or text); undefined when no answer came. */
+    body;
+    constructor(init) {
+        super(`${init.code}${init.status ? ` (${init.status})` : ''}: ${init.detail}`, init.cause === undefined ? undefined : { cause: init.cause });
+        this.status = init.status;
+        this.code = init.code;
+        this.title = init.title;
+        this.detail = init.detail;
+        this.type = init.type ?? null;
+        this.errors = init.errors ?? [];
+        this.problems = init.problems ?? [];
+        this.retryAfter = init.retryAfter ?? null;
+        this.reason = init.reason ?? null;
+        this.retryable = init.retryable ?? null;
+        this.requestId = init.requestId ?? null;
+        this.body = init.body;
+    }
+}
+const SDK_TITLES = {
+    network_error: 'The request did not get an answer.',
+    timeout: 'The request timed out.',
+    aborted: 'The request was aborted.',
+    wait_timeout: 'The job did not end within the wait.',
+    http_error: 'The API answered with an error that is not problem details.',
+    invalid_response: 'The API answered with a body the SDK could not read.',
+    output_not_found: 'The job has no output with this alias or name.',
+    output_ambiguous: 'Several files of the job have this name. Use the alias of one.',
+};
+/** An error with one of the SDK's own codes. */
+export function sdkError(code, detail, extra = {}) {
+    return new VidexoError({ status: null, title: SDK_TITLES[code], detail, ...extra, code });
+}
+/** Seconds of a `Retry-After` header, as a number of seconds or an HTTP date; null when absent or unreadable. */
+export function retryAfterSeconds(value, now = Date.now()) {
+    if (value === null || value.trim() === '')
+        return null;
+    const text = value.trim();
+    if (/^\d+$/.test(text))
+        return Number(text);
+    const date = Date.parse(text);
+    if (Number.isNaN(date))
+        return null;
+    return Math.max(0, Math.ceil((date - now) / 1000));
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** The error of a non-2xx answer whose body was read as `body` (parsed JSON, or the text when it was not JSON). */
+export function errorFromResponse(response, body) {
+    const retryAfter = retryAfterSeconds(response.headers.get('retry-after'));
+    const headerId = response.headers.get('request-id');
+    if (isRecord(body) && typeof body.code === 'string' && typeof body.title === 'string') {
+        return new VidexoError({
+            status: response.status,
+            code: body.code,
+            title: body.title,
+            detail: typeof body.detail === 'string' ? body.detail : body.title,
+            type: typeof body.type === 'string' ? body.type : null,
+            errors: Array.isArray(body.errors) ? body.errors : [],
+            problems: Array.isArray(body.problems) ? body.problems : [],
+            reason: typeof body.reason === 'string' ? body.reason : null,
+            retryable: typeof body.retryable === 'boolean' ? body.retryable : null,
+            requestId: typeof body.request_id === 'string' ? body.request_id : headerId,
+            retryAfter,
+            body,
+        });
+    }
+    return sdkError('http_error', `The API answered ${response.status}${response.statusText ? ` ${response.statusText}` : ''}.`, {
+        status: response.status,
+        retryAfter,
+        requestId: headerId,
+        body,
+    });
+}
+/** A webhook that did not pass verification: answer it with a 400 and do not act on it. */
+export class VidexoWebhookError extends Error {
+    name = 'VidexoWebhookError';
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}