bolbol-sdk 1.0.0

package/dist/HTTPClient.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTTPClient = void 0;
+const HTTPError_1 = require("./HTTPError");
+// The single transport behind every scope. Resolves to the API's envelope
+// (`BolbolResponseType<T>`) untouched so callers keep its metadata; throws
+// HTTPError for anything that is not a 2xx answer.
+class HTTPClient {
+    options;
+    baseUrl;
+    constructor(options) {
+        this.options = options;
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    }
+    // Origin of the API ("https://bolbol.io"). Static asset paths the API hands
+    // out already carry the mount prefix ("/api/static/..."), so they resolve
+    // against this rather than against baseUrl.
+    get origin() {
+        return new URL(this.baseUrl).origin;
+    }
+    get(path, options = {}) {
+        return this.request("GET", path, options);
+    }
+    post(path, options = {}) {
+        return this.request("POST", path, options);
+    }
+    put(path, options = {}) {
+        return this.request("PUT", path, options);
+    }
+    patch(path, options = {}) {
+        return this.request("PATCH", path, options);
+    }
+    delete(path, options = {}) {
+        return this.request("DELETE", path, options);
+    }
+    // Binary GET, for the endpoints that stream their payload instead of
+    // wrapping it in an envelope (e.g. a user file download). A failure still
+    // answers with the JSON envelope, so it is thrown as HTTPError as usual.
+    async blob(path, options = {}) {
+        const response = await this.send("GET", path, options);
+        if (!response.ok)
+            throw HTTPClient.failure(response.status, await HTTPClient.parse(response));
+        return response.blob();
+    }
+    async request(method, path, options = {}) {
+        const response = await this.send(method, path, options);
+        const data = await HTTPClient.parse(response);
+        if (!response.ok)
+            throw HTTPClient.failure(response.status, data);
+        return data;
+    }
+    // Absolute URL for an API path plus query string, for callers that hand
+    // the address to something else (an <img src>, a download link).
+    url(path, query) {
+        const search = HTTPClient.search(query);
+        return `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}${search}`;
+    }
+    async send(method, path, options) {
+        const headers = { accept: "application/json" };
+        if (options.body !== undefined)
+            headers["content-type"] = "application/json";
+        // The session token goes on every request that has one, public
+        // endpoints included. The API reads it from `b-token`
+        // (BaseEndpoint.ts); a public endpoint treats a missing or stale token
+        // as a guest, and a valid one personalises the answer - member-only
+        // items, the owner's private files, errors in the user's language.
+        // Sending it only to endpoints that require sign-in would silently
+        // lose all of that.
+        if (this.options.getToken !== undefined) {
+            const token = await this.options.getToken();
+            if (token)
+                headers["b-token"] = token;
+        }
+        const controller = new AbortController();
+        const timer = this.options.timeoutMs === undefined ? null : setTimeout(() => controller.abort(), this.options.timeoutMs);
+        const url = this.url(path, options.query);
+        try {
+            return await fetch(url, {
+                ...this.options.init,
+                method,
+                headers: { ...this.options.init?.headers, ...headers },
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError")
+                throw new HTTPError_1.HTTPError(HTTPError_1.HTTPError.UNREACHABLE, `Request to ${url} timed out after ${this.options.timeoutMs}ms.`);
+            throw new HTTPError_1.HTTPError(HTTPError_1.HTTPError.UNREACHABLE, `Could not reach the Bolbol API at ${url}: ${HTTPClient.reason(error)}`);
+        }
+        finally {
+            if (timer !== null)
+                clearTimeout(timer);
+        }
+    }
+    static search(query) {
+        if (query === undefined)
+            return "";
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            if (value === null || value === undefined)
+                continue;
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    params.append(key, String(item));
+            }
+            else
+                params.set(key, String(value));
+        }
+        const text = params.toString();
+        return text === "" ? "" : `?${text}`;
+    }
+    // Answers are JSON by contract, but a proxy error page is not, so an
+    // unparseable body reads as null instead of throwing.
+    static async parse(response) {
+        const text = await response.text();
+        if (text === "")
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    static failure(status, data) {
+        const payload = data?.result;
+        if (payload !== null && typeof payload === "object" && typeof payload.message === "string") {
+            const { message, lang, errors } = payload;
+            // A validation 400 lists the failed rules next to its generic
+            // message - without them "Invalid request body." names no field.
+            const issues = Array.isArray(errors)
+                ? errors.filter((issue) => typeof issue?.path === "string" && typeof issue?.message === "string")
+                : [];
+            return new HTTPError_1.HTTPError(status, message, typeof lang === "string" ? lang : undefined, issues);
+        }
+        return new HTTPError_1.HTTPError(status, `The Bolbol API answered with status ${status}.`);
+    }
+    // Node wraps transport failures as `TypeError: fetch failed` with the real
+    // reason on `cause`; walk down to the first cause that says something.
+    static reason(error) {
+        if (!(error instanceof Error))
+            return String(error);
+        if (error.cause !== undefined && error.cause !== null) {
+            const nested = HTTPClient.reason(error.cause);
+            if (nested !== "")
+                return nested;
+        }
+        const code = error.code;
+        if (error.message !== "")
+            return code === undefined ? error.message : `${error.message} (${code})`;
+        return code ?? "";
+    }
+}
+exports.HTTPClient = HTTPClient;
+//# sourceMappingURL=HTTPClient.js.map

package/dist/HTTPClient.js.map

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

package/dist/HTTPError.d.ts

@@ -0,0 +1,13 @@
+export interface HTTPErrorIssue {
+    path: string;
+    message: string;
+}
+export declare class HTTPError extends Error {
+    static readonly UNREACHABLE = 0;
+    readonly code: number;
+    readonly lang?: string;
+    readonly errors: HTTPErrorIssue[];
+    constructor(code: number, message: string, lang?: string, errors?: HTTPErrorIssue[]);
+    get unreachable(): boolean;
+}
+//# sourceMappingURL=HTTPError.d.ts.map

package/dist/HTTPError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HTTPError.d.ts","sourceRoot":"","sources":["../src/HTTPError.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAE3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACnB;AAMD,qBAAa,SAAU,SAAQ,KAAK;IAEhC,gBAAuB,WAAW,KAAK;IAEvC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,IAAI,CAAC,EAAE,MAAM,CAAC;IAC9B,SAAgB,MAAM,EAAE,cAAc,EAAE,CAAC;gBAE7B,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,GAAE,cAAc,EAAO;IAWvF,IAAW,WAAW,IAAI,OAAO,CAGhC;CACJ"}

package/dist/HTTPError.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTTPError = void 0;
+// Thrown by HTTPClient for every failed call. `code` is the HTTP status, or 0
+// when the API could not be reached at all (network down, DNS, timeout).
+// `message` is the API's own, already localized explanation when it sent one,
+// with `lang` naming its language; otherwise an English fallback.
+class HTTPError extends Error {
+    static UNREACHABLE = 0;
+    code;
+    lang;
+    errors;
+    constructor(code, message, lang, errors = []) {
+        super(message);
+        this.name = "HTTPError";
+        this.code = code;
+        this.lang = lang;
+        this.errors = errors;
+    }
+    // True when the request never got an answer, as opposed to the API
+    // answering with a failure.
+    get unreachable() {
+        return this.code === HTTPError.UNREACHABLE;
+    }
+}
+exports.HTTPError = HTTPError;
+//# sourceMappingURL=HTTPError.js.map

package/dist/HTTPError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HTTPError.js","sourceRoot":"","sources":["../src/HTTPError.ts"],"names":[],"mappings":";;;AAQA,8EAA8E;AAC9E,yEAAyE;AACzE,8EAA8E;AAC9E,kEAAkE;AAClE,MAAa,SAAU,SAAQ,KAAK;IAEzB,MAAM,CAAU,WAAW,GAAG,CAAC,CAAC;IAEvB,IAAI,CAAS;IACb,IAAI,CAAU;IACd,MAAM,CAAmB;IAEzC,YAAY,IAAY,EAAE,OAAe,EAAE,IAAa,EAAE,SAA2B,EAAE;QAEnF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAED,mEAAmE;IACnE,4BAA4B;IAC5B,IAAW,WAAW;QAElB,OAAO,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,WAAW,CAAC;IAC/C,CAAC;;AAtBL,8BAuBC"}