@vertesia/api-fetch-client 0.24.0-dev.202601221707

package/src/base.ts

@@ -0,0 +1,225 @@
+import { ConnectionError, RequestError, ServerError } from "./errors.js";
+import { sse } from "./sse/index.js";
+import { buildQueryString, join, removeTrailingSlash } from "./utils.js";
+
+export type FETCH_FN = (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+type IPrimitives = string | number | boolean | null | undefined | string[] | number[] | boolean[];
+
+export interface IRequestParams {
+    query?: Record<string, IPrimitives> | null;
+    headers?: Record<string, string> | null;
+    /*
+     * custom response reader. The default is to read a JSON object using the jsonParse method
+     * The reader function is called with the client as the `this` context
+     * This can be an async function (i.e. return a promise). If a promise is returned
+     * it will wait for the promise to resolve before returning the result
+     *
+     * If set to 'sse' the response will be treated as a server-sent event stream
+     * and the request will return a Promise<ReadableStream<ServerSentEvent>> object
+     */
+    reader?: 'sse' | ((response: Response) => any);
+    /**
+     * Set to false to disable automatic JSON payload serialization
+     * If you need to post other data than a json payload, set this to false and use the `payload` property to set the desired payload
+     */
+    jsonPayload?: boolean
+}
+
+export interface IRequestParamsWithPayload extends IRequestParams {
+    payload?: object | BodyInit | null;
+}
+
+export function fetchPromise(fetchImpl?: FETCH_FN | Promise<FETCH_FN>) {
+    if (fetchImpl) {
+        return Promise.resolve(fetchImpl);
+    } else if (typeof globalThis.fetch === 'function') {
+        return Promise.resolve(globalThis.fetch);
+    } else {
+        // install an error impl
+        return Promise.resolve(() => {
+            throw new Error('No Fetch implementation found')
+        });
+    }
+}
+
+export abstract class ClientBase {
+
+    _fetch: Promise<FETCH_FN>;
+    baseUrl: string;
+    errorFactory: (err: RequestError) => Error = (err) => err;
+    verboseErrors = true;
+
+    abstract get headers(): Record<string, string>;
+
+    constructor(baseUrl: string, fetchImpl?: FETCH_FN | Promise<FETCH_FN>) {
+        this.baseUrl = removeTrailingSlash(baseUrl);
+        this._fetch = fetchPromise(fetchImpl);
+    }
+
+    /**
+     * Can be subclassed to map to custom errors
+     * @param err
+     */
+    throwError(err: RequestError): never {
+        throw this.errorFactory(err);
+    }
+
+    getUrl(path: string) {
+        return removeTrailingSlash(join(this.baseUrl, path));
+    }
+
+    get(path: string, params?: IRequestParams) {
+        return this.request('GET', path, params);
+    }
+
+    del(path: string, params?: IRequestParams) {
+        return this.request('DELETE', path, params);
+    }
+
+    delete(path: string, params?: IRequestParams) {
+        return this.request('DELETE', path, params);
+    }
+
+    post(path: string, params?: IRequestParamsWithPayload) {
+        return this.request('POST', path, params);
+    }
+
+    put(path: string, params?: IRequestParamsWithPayload) {
+        return this.request('PUT', path, params);
+    }
+
+    /**
+     * You can customize the json parser by overriding this method
+     * @param text
+     * @returns
+     */
+    jsonParse(text: string) {
+        return JSON.parse(text);
+    }
+
+    /**
+    * Can be overridden to create the request
+    * @param fetch
+    * @param url
+    * @param init
+    * @returns
+    */
+    createRequest(url: string, init: RequestInit): Promise<Request> {
+        return Promise.resolve(new Request(url, init));
+    }
+
+    createServerError(req: Request, res: Response, payload: any): RequestError {
+        const status = res.status;
+        let message = 'Server Error: ' + status;
+        if (payload) {
+            if (payload.message) {
+                message = String(payload.message);
+            } else if (payload.error) {
+                if (typeof payload.error === 'string') {
+                    message = String(payload.error);
+                } else if (typeof payload.error.message === 'string') {
+                    message = String(payload.error.message);
+                }
+            }
+        }
+        return new ServerError(message, req, res.status, payload, this.verboseErrors);
+    }
+
+
+    async readJSONPayload(res: Response) {
+        return res.text().then(text => {
+            if (!text) {
+                return undefined;
+            } else {
+                try {
+                    return this.jsonParse(text);
+                } catch (err: any) {
+                    return {
+                        status: res.status,
+                        error: "Not a valid JSON payload",
+                        message: err.message,
+                        text: text,
+                    };
+                }
+            }
+        }).catch((err) => {
+            return {
+                status: res.status,
+                error: "Unable to load response content",
+                message: err.message,
+            };
+        });
+    }
+
+    /**
+     * Subclasses You can override this to do something with the response
+     * @param res
+     */
+    handleResponse(req: Request, res: Response, params: IRequestParamsWithPayload | undefined) {
+        res.url
+        if (params && params.reader) {
+            if (params.reader === 'sse') {
+                return sse(res);
+            } else {
+                return params.reader.call(this, res);
+            }
+        } else {
+            return this.readJSONPayload(res).then((payload) => {
+                if (res.ok) {
+                    return payload;
+                } else {
+                    this.throwError(this.createServerError(req, res, payload));
+                }
+            });
+        }
+    }
+
+    async request(method: string, path: string, params?: IRequestParamsWithPayload) {
+        let url = this.getUrl(path);
+        if (params?.query) {
+            url += '?' + buildQueryString(params.query);
+        }
+        const headers = this.headers ? Object.assign({}, this.headers) : {};
+        const paramsHeaders = params?.headers;
+        if (paramsHeaders) {
+            for (const key in paramsHeaders) {
+                headers[key.toLowerCase()] = paramsHeaders[key];
+            }
+        }
+        let body: BodyInit | undefined;
+        const payload = params?.payload;
+        if (payload) {
+            if (params && params.jsonPayload === false) {
+                body = payload as BodyInit;
+            } else {
+                body = (typeof payload !== 'string') ? JSON.stringify(payload) : payload;
+                if (!('content-type' in headers)) {
+                    headers['content-type'] = 'application/json';
+                }
+            }
+        }
+        const init: RequestInit = {
+            method: method,
+            headers: headers,
+            body: body,
+        }
+        const req = await this.createRequest(url, init);
+        return this._fetch.then(fetch => fetch(req).catch(err => {
+            console.error(`Failed to connect to ${url}`, err);
+            this.throwError(new ConnectionError(req, err));
+        }).then(res => {
+            return this.handleResponse(req, res, params);
+        }));
+    }
+
+    /**
+     * Expose the fetch method
+     * @param input
+     * @param init
+     * @returns
+     */
+    fetch(input: RequestInfo, init?: RequestInit): Promise<Response> {
+        return this._fetch.then(fetch => fetch(input, init));
+    }
+
+}

package/src/client.ts

@@ -0,0 +1,126 @@
+import { ClientBase, FETCH_FN, IRequestParamsWithPayload } from "./base.js";
+import { RequestError } from "./errors.js";
+
+function isAuthorizationHeaderSet(headers: HeadersInit | undefined): boolean {
+    if (!headers) return false;
+    return "authorization" in headers;
+}
+
+export class AbstractFetchClient<T extends AbstractFetchClient<T>> extends ClientBase {
+
+    headers: Record<string, string>;
+    _auth?: () => Promise<string>;
+    // callbacks useful to log requests and responses
+    onRequest?: (req: Request) => void;
+    onResponse?: (res: Response, req: Request) => void;
+    // the last response. Can be used to inspect the response headers
+    response?: Response;
+
+    constructor(baseUrl: string, fetchImpl?: FETCH_FN | Promise<FETCH_FN>) {
+        super(baseUrl, fetchImpl);
+        this.baseUrl = baseUrl[baseUrl.length - 1] === '/' ? baseUrl.substring(0, baseUrl.length - 1) : baseUrl;
+        this.headers = this.initialHeaders;
+    }
+
+    get initialHeaders() {
+        return { accept: 'application/json' };
+    }
+
+    /**
+     * Install an auth callback. If the callback is undefined or null then remove the auth callback.
+     * @param authCb a function returning a promise that resolves to the value to use for the authorization header
+     * @returns the client instance
+     */
+    withAuthCallback(authCb?: (() => Promise<string>) | null) {
+        this._auth = authCb || undefined;
+        return this;
+    }
+
+    withErrorFactory(factory: (err: RequestError) => Error) {
+        this.errorFactory = factory;
+        return this as unknown as T;
+    }
+
+    withLang(locale: string | undefined | null) {
+        if (locale) {
+            this.headers['accept-language'] = locale;
+        } else {
+            delete this.headers['accept-language'];
+        }
+        return this as unknown as T;
+    }
+
+    withHeaders(headers: Record<string, string>) {
+        const thisHeaders = this.headers;
+        for (const key in headers) {
+            const value = headers[key];
+            if (value != null) {
+                thisHeaders[key.toLowerCase()] = value;
+            }
+        }
+        return this as unknown as T;
+    }
+
+    setHeader(key: string, value: string | undefined) {
+        if (!value) {
+            delete this.headers[key.toLowerCase()];
+        } else {
+            this.headers[key.toLowerCase()] = value;
+        }
+    }
+
+    async createRequest(url: string, init: RequestInit) {
+        if (this._auth && !isAuthorizationHeaderSet(init.headers)) {
+            const headers = (init.headers ? init.headers : {}) as Record<string, string>;
+            init.headers = headers;
+            const auth = await this._auth();
+            if (auth) {
+                init.headers["authorization"] = auth;
+            }
+        }
+        this.response = undefined;
+        const request = await super.createRequest(url, init);
+        this.onRequest && this.onRequest(request);
+        return request;
+    }
+
+    async handleResponse(req: Request, res: Response, params: IRequestParamsWithPayload | undefined): Promise<any> {
+        this.response = res; // store last response
+        this.onResponse && this.onResponse(res, req);
+        return super.handleResponse(req, res, params);
+    }
+
+}
+
+export class FetchClient extends AbstractFetchClient<FetchClient> {
+
+    constructor(baseUrl: string, fetchImpl?: FETCH_FN | Promise<FETCH_FN>) {
+        super(baseUrl, fetchImpl);
+    }
+
+}
+
+export abstract class ApiTopic extends ClientBase {
+
+    constructor(public client: ClientBase, basePath: string) {
+        //TODO we should refactor the way ClientBase and ApiTopic is created
+        // to avoid cloning all customizations
+        super(client.getUrl(basePath), client._fetch);
+        this.createServerError = client.createServerError
+        this.errorFactory = client.errorFactory;
+        this.verboseErrors = client.verboseErrors;
+    }
+
+    createRequest(url: string, init: RequestInit): Promise<Request> {
+        return this.client.createRequest(url, init);
+    }
+
+    handleResponse(req: Request, res: Response, params: IRequestParamsWithPayload | undefined): Promise<any> {
+        return this.client.handleResponse(req, res, params);
+    }
+
+    get headers() {
+        return this.client.headers;
+    }
+
+}

package/src/errors.ts

@@ -0,0 +1,61 @@
+
+function createMessage(message: string, request: Request, status: number, payload: any, displayDetails: boolean) {
+    let msg = message;
+    if (displayDetails) {
+        msg += '\nRequest: ' + request.method + ' ' + request.url + ' => ' + status;
+        const details = payload?.details || payload?.error?.details;
+        if (details) {
+            const detailsType = typeof details;
+            if (detailsType === 'string') {
+                msg += '\nDetails: ' + details;
+            } else if (detailsType === "object") {
+                msg += '\nDetails: ' + JSON.stringify(details, undefined, 2);
+            }
+        }
+        msg += '\nStack Trace: ';
+    }
+    return msg;
+}
+
+export class RequestError extends Error {
+    status: number;
+    payload: any;
+    request: Request;
+    request_info: string;
+    displayDetails: boolean;
+    original_message: string;
+    constructor(message: string, request: Request, status: number, payload: any, displayDetails = true) {
+        super(createMessage(message, request, status, payload, displayDetails));
+        this.original_message = message;
+        this.request = request;
+        this.status = status;
+        this.payload = payload;
+        this.request_info = request.method + ' ' + request.url + ' => ' + status;
+        this.displayDetails = displayDetails;
+    }
+
+    get details() {
+        return this.payload?.details || this.payload?.error?.details;
+    }
+
+}
+
+export class ServerError extends RequestError {
+    constructor(message: string, req: Request, status: number, payload: any, displayDetails = true) {
+        super(message, req, status, payload, displayDetails);
+    }
+
+    updateDetails(details: any) {
+        if (details !== this.details) {
+            return new ServerError(this.original_message, this.request, this.status, { ...this.payload, details }, this.displayDetails)
+        } else {
+            return this;
+        }
+    }
+}
+
+export class ConnectionError extends RequestError {
+    constructor(req: Request, err: Error) {
+        super("Failed to connect to server: " + err.message, req, 0, err);
+    }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./base.js";
+export * from "./client.js";
+export * from "./errors.js";
+export * from "./sse/index.js";

package/src/sse/EventSourceParserStream.ts

@@ -0,0 +1,39 @@
+import { createParser, ReconnectInterval, type EventSourceParser, type ParsedEvent } from 'eventsource-parser'
+
+/**
+ * We copied this file from the eventsource-parser/stream package and made it a part of our project.
+ * because importing the eventsource-parser/stream breaks tsc build when building the commonjs version
+ * see for a similar error: 
+ * https://stackoverflow.com/questions/77280140/why-typescript-dont-see-exports-of-package-with-module-commonjs-and-moduleres
+ */
+
+/**
+ * A TransformStream that ingests a stream of strings and produces a stream of ParsedEvents.
+ *
+ * @example
+ * ```
+ * const eventStream =
+ *   response.body
+ *     .pipeThrough(new TextDecoderStream())
+ *     .pipeThrough(new EventSourceParserStream())
+ * ```
+ * @public
+ */
+export class EventSourceParserStream extends TransformStream<string, ParsedEvent> {
+    constructor() {
+        let parser!: EventSourceParser
+
+        super({
+            start(controller) {
+                parser = createParser((event: ParsedEvent | ReconnectInterval) => {
+                    if (event.type === 'event') {
+                        controller.enqueue(event)
+                    }
+                })
+            },
+            transform(chunk) {
+                parser.feed(chunk)
+            },
+        })
+    }
+}

package/src/sse/TextDecoderStream.ts

@@ -0,0 +1,62 @@
+/**
+ * Decode a stream of bytes into a stream of characters.
+ * Some javascript env like Bun.js doesn't supports the TextDecoderStream (as for jan 2024)
+ * This is a polyfill for bunJS
+ */
+let _TextDecoderStream: typeof TextDecoderStream;
+if (globalThis.TextDecoderStream && typeof globalThis.TextDecoderStream === 'function') {
+    _TextDecoderStream = globalThis.TextDecoderStream;
+} else {
+    class MyTextDecoderStream extends TransformStream<ArrayBuffer | Uint8Array, string> {
+        private _options: {
+            encoding: string,
+            fatal?: boolean,
+            ignoreBOM?: boolean
+        }
+        constructor(encoding = "utf-8", { fatal = false, ignoreBOM = false }: {
+            fatal?: boolean,
+            ignoreBOM?: boolean
+        } = {}) {
+            super(new TextDecodeTransformer(new TextDecoder(encoding, { fatal, ignoreBOM })));
+            this._options = { fatal, ignoreBOM, encoding };
+        }
+
+        get encoding() {
+            return this._options.encoding;
+        }
+        get fatal() {
+            return this._options.fatal;
+        }
+        get ignoreBOM() {
+            return this._options.ignoreBOM;
+        }
+    }
+    class TextDecodeTransformer implements Transformer<ArrayBuffer | Uint8Array, string> {
+        private decoder: TextDecoder;
+
+        constructor(decoder: TextDecoder) {
+            this.decoder = decoder;
+        }
+
+        transform(chunk: ArrayBuffer | Uint8Array, controller: TransformStreamDefaultController<string>) {
+            if (!(chunk instanceof ArrayBuffer || ArrayBuffer.isView(chunk))) {
+                throw new TypeError("Input must be a compatible with: ArrayBuffer | Uint8Array");
+            }
+            const text = this.decoder.decode(chunk, { stream: true });
+            if (text.length !== 0) {
+                controller.enqueue(text);
+            }
+        }
+
+        flush(controller: TransformStreamDefaultController<string>) {
+            const text = this.decoder.decode();
+            if (text.length !== 0) {
+                controller.enqueue(text);
+            }
+        }
+    }
+    _TextDecoderStream = MyTextDecoderStream as any;
+}
+
+export { _TextDecoderStream as TextDecoderStream };
+

package/src/sse/index.ts

@@ -0,0 +1,27 @@
+import { TextDecoderStream } from "./TextDecoderStream.js";
+import { EventSourceParserStream } from "./EventSourceParserStream.js";
+import { ParsedEvent, ReconnectInterval } from "eventsource-parser";
+
+export type ServerSentEvent = ParsedEvent | ReconnectInterval;
+/**
+ * A SSE response reader.
+ * Usage client.get('/path', {reader: sse}) or client.post('/path', {reader: sse})
+ * where sse is this function
+ * @param response 
+ * @returns 
+ */
+export async function sse(response: Response): Promise<ReadableStream<ServerSentEvent>> {
+    if (!response.ok) {
+        const text = await response.text();
+        const error = new Error("SSE error: " + response.status + ". Content:\n" + text);
+        (error as any).status = response.status;
+        throw error;
+    }
+    if (!response.body) {
+        throw new Error('No body in response');
+    }
+    return response.body.pipeThrough(new TextDecoderStream()).pipeThrough(new EventSourceParserStream());
+}
+
+// re-export TextDecoderStream (in case it was polyfilled)
+export { TextDecoderStream }

package/src/utils.ts

@@ -0,0 +1,31 @@
+
+export function buildQueryString(query: any) {
+    const parts = [];
+    for (const key of Object.keys(query)) {
+        const val = query[key];
+        if (val != null) {
+            parts.push(encodeURIComponent(key) + "=" + encodeURIComponent(String(val)));
+        }
+    }
+    return parts.join("&");
+}
+
+export function join(left: string, right: string) {
+    if (left.endsWith('/')) {
+        if (right.startsWith('/')) {
+            return left + right.substring(1);
+        } else {
+            return left + right;
+        }
+    } else if (right.startsWith('/')) {
+        return left + right;
+    } else {
+        return left + '/' + right;
+    }
+}
+export function removeTrailingSlash(path: string) {
+    if (path[path.length - 1] === '/') {
+        return path.slice(0, -1);
+    }
+    return path;
+}