@zcatalyst/transport 0.0.1 → 0.0.3

package/dist-es/utils/form-data.js

@@ -0,0 +1,218 @@
+import { basename } from 'path';
+import { Readable, Stream } from 'stream';
+import { inspect } from 'util';
+import CloneableStream from './clonable-stream';
+class FormData extends Stream {
+    constructor(streams) {
+        super();
+        this.writable = false;
+        this.readable = true;
+        this.released = false;
+        this.streams = streams || [];
+        this.insideLoop = false;
+        this.pendingNext = false;
+    }
+    isStream(value) {
+        return (value !== undefined &&
+            value !== null &&
+            ((typeof value.on === 'function' &&
+                typeof value.pipe === 'function') ||
+                value instanceof Readable));
+    }
+    _multiPartHeader(field, value) {
+        const contentDisposition = this._getContentDisposition(value);
+        const contentType = this._getContentType(value);
+        let contents = '';
+        const headers = {
+            'Content-Disposition': ['form-data', 'name="' + field + '"'].concat(contentDisposition || []),
+            'Content-Type': [contentType]
+        };
+        for (const prop in headers) {
+            if (headers[prop]) {
+                const header = headers[prop];
+                if (header.length > 0) {
+                    contents += prop + ': ' + header.join('; ') + FormData.LINE_BREAK;
+                }
+            }
+        }
+        return '--' + this.getBoundary() + FormData.LINE_BREAK + contents + FormData.LINE_BREAK;
+    }
+    _getContentDisposition(value) {
+        let filename = '';
+        let contentDisposition = '';
+        if (typeof value === 'object' && value !== null && ('name' in value || 'path' in value)) {
+            const val = value;
+            filename = basename(val.name || val.path || '');
+        }
+        else if (typeof value === 'object' &&
+            value !== null &&
+            'readable' in value &&
+            'httpVersion' in value &&
+            'client' in value) {
+            const httpValue = value;
+            filename = basename(httpValue.client._httpMessage.path || '');
+        }
+        if (filename) {
+            contentDisposition = 'filename="' + filename + '"';
+        }
+        return contentDisposition;
+    }
+    _getContentType(value) {
+        let contentType = '';
+        if (value.readable && value.hasOwnProperty('httpVersion')) {
+            contentType = value.headers['content-type'];
+        }
+        if (!contentType) {
+            contentType = FormData.CONTENT_TYPE;
+        }
+        return contentType;
+    }
+    _lastBoundary() {
+        return '--' + this.getBoundary() + '--' + FormData.LINE_BREAK;
+    }
+    _generateBoundary() {
+        let boundary = '--------------------------';
+        for (let i = 0; i < 24; i++) {
+            boundary += Math.floor(Math.random() * 10).toString(16);
+        }
+        this.boundary = boundary;
+        return boundary;
+    }
+    _error(err) {
+        this._reset();
+        this.emit('error', err);
+    }
+    _handleStreamErrors(stream) {
+        stream.on('error', (err) => {
+            this._error(err);
+        });
+    }
+    _pipeNext(stream) {
+        this.currentStream = stream;
+        if (this.isStream(stream)) {
+            stream.on('end', this._getNext.bind(this));
+            stream.pipe(this, {
+                end: false
+            });
+            return;
+        }
+        const value = stream;
+        this.write(value);
+        this._getNext();
+    }
+    _getNext() {
+        this.currentStream = undefined;
+        if (this.insideLoop) {
+            this.pendingNext = true;
+            return;
+        }
+        this.insideLoop = true;
+        try {
+            do {
+                this.pendingNext = false;
+                const stream = this.streams.shift();
+                if (typeof stream === 'undefined') {
+                    this.end();
+                }
+                else {
+                    this._pipeNext(stream);
+                }
+            } while (this.pendingNext);
+        }
+        finally {
+            this.insideLoop = false;
+        }
+    }
+    _reset() {
+        this.writable = false;
+        this.streams = [];
+        this.currentStream = undefined;
+    }
+    createClone() {
+        const newStreams = [];
+        this.streams.forEach((stream) => {
+            const clone = this.isStream(stream)
+                ? new CloneableStream(stream).clone()
+                : stream;
+            newStreams.push(clone);
+        });
+        return new FormData(newStreams);
+    }
+    append(field, value) {
+        if (Array.isArray(value)) {
+            this._error(new Error('Arrays are not supported.'));
+            return this;
+        }
+        if (typeof value !== 'string' && !Buffer.isBuffer(value) && !this.isStream(value)) {
+            value = inspect(value);
+        }
+        if (this.isStream(value)) {
+            this._handleStreamErrors(value);
+        }
+        this.streams.push(this._multiPartHeader(field, value));
+        this.streams.push(value);
+        this.streams.push(FormData.LINE_BREAK);
+        return this;
+    }
+    getHeaders(userHeaders) {
+        const formHeaders = {};
+        for (const header in userHeaders) {
+            if (userHeaders[header]) {
+                formHeaders[header.toLowerCase()] = userHeaders[header];
+            }
+        }
+        formHeaders['content-type'] = 'multipart/form-data; boundary=' + this.getBoundary();
+        return formHeaders;
+    }
+    getBoundary() {
+        if (this.boundary === undefined) {
+            return this._generateBoundary();
+        }
+        return this.boundary;
+    }
+    pipe(dest, options) {
+        Stream.prototype.pipe.call(this, dest, options);
+        this.resume();
+        return dest;
+    }
+    write(data) {
+        const lastPart = this.streams.length === 0;
+        this.emit('data', data);
+        if (lastPart) {
+            this.emit('data', this._lastBoundary());
+        }
+        return true;
+    }
+    pause() {
+        if (this.currentStream !== undefined &&
+            typeof this.currentStream.pause === 'function') {
+            this.currentStream.pause();
+        }
+        this.emit('pause');
+    }
+    resume() {
+        if (!this.released) {
+            this.released = true;
+            this.writable = true;
+            this._getNext();
+        }
+        if (this.currentStream && typeof this.currentStream.resume === 'function') {
+            this.currentStream.resume();
+        }
+        this.emit('resume');
+    }
+    end() {
+        this._reset();
+        this.emit('end');
+    }
+    destroy() {
+        this._reset();
+        this.emit('close');
+    }
+    toString() {
+        return '[object FormData]';
+    }
+}
+FormData.LINE_BREAK = '\r\n';
+FormData.CONTENT_TYPE = 'application/octet-stream';
+export default FormData;

package/dist-es/utils/helpers.js

@@ -0,0 +1,7 @@
+export function isHttps(url) {
+    if (url === undefined) {
+        return false;
+    }
+    const parsedUrl = url instanceof URL ? url : new URL(url);
+    return parsedUrl.protocol === 'https:';
+}

package/dist-es/utils/interfaces.js

@@ -0,0 +1 @@
+export {};

package/dist-es/utils/request-agent.js

@@ -0,0 +1,19 @@
+import { CONSTANTS } from '@zcatalyst/utils';
+import { Agent as httpAgent } from 'http';
+import { Agent as httpsAgent } from 'https';
+const agentMap = {};
+export default class RequestAgent {
+    constructor(isHttps, host, replaceAgent) {
+        const protocol = isHttps ? CONSTANTS.PROTOCOL.HTTPS : CONSTANTS.PROTOCOL.HTTP;
+        if (agentMap[protocol] === undefined) {
+            agentMap[protocol] = {};
+        }
+        const protocolMap = agentMap[protocol];
+        if (protocolMap[host] === undefined || replaceAgent) {
+            protocolMap[host] = isHttps
+                ? new httpsAgent({ keepAlive: true })
+                : new httpAgent({ keepAlive: true });
+        }
+        this.agent = protocolMap[host];
+    }
+}

package/dist-es/utils/request-timeout.js

@@ -0,0 +1,11 @@
+export function requestTimeout(timeoutInMs = 0) {
+    return new Promise((resolve, reject) => {
+        if (timeoutInMs) {
+            setTimeout(() => {
+                const timeoutError = new Error(`Request did not complete within ${timeoutInMs} ms`);
+                timeoutError.name = 'TimeoutError';
+                reject(timeoutError);
+            }, timeoutInMs);
+        }
+    });
+}

package/dist-types/fetch-handler.d.ts

@@ -0,0 +1,149 @@
+import { CoreType, IRequestConfig, jwtAccessTokenResponse, RequestHandlerOptions } from './utils/interfaces';
+type ICatalystDataRes = Record<string, string> | string | Blob | ArrayBuffer | ReadableStreamDefaultReader<Uint8Array> | FormData;
+export interface ICatalystClientRes {
+    request: RequestInit;
+    statusCode?: number;
+    headers: HeadersInit;
+    data?: ICatalystDataRes;
+    buffer?: Buffer;
+    blob?: Blob;
+    config: RequestHandlerOptions;
+    stream?: ArrayBuffer;
+}
+export declare class DefaultHttpResponse {
+    statusCode: number;
+    headers: HeadersInit;
+    config: RequestHandlerOptions;
+    resp: ICatalystClientRes;
+    /**
+     * Creates a DefaultHttpResponse instance.
+     * @param resp - The resp value.
+     */
+    constructor(resp: ICatalystClientRes);
+    /**
+     * Returns the data value for this DefaultHttpResponse instance.
+     *
+     * @returns The response payload.
+     * @throws {CatalystAPIError} when the request or response cannot be processed.
+     *
+     * @example
+     * ```ts
+     * import { Handler } from '@zcatalyst/transport';
+     * const result = undefined;
+     * ```
+     */
+    get data(): ICatalystDataRes;
+}
+export declare class ResponseHandler {
+    #private;
+    static apiDomain: string;
+    /**
+     * Creates a ResponseHandler instance.
+     */
+    constructor();
+    /**
+     * Sends a browser fetch request with SDK authentication, timeout and response handling.
+     *
+     * @param options - The initialization or request options.
+     * @param options.requestCore - The Fetch API request configuration.
+     * @param options.url - The URL to update or request.
+     * @param requestOptions - The request handling options.
+     * @returns The fire general request result.
+     * @throws {CatalystAPIError} when the request or response cannot be processed.
+     *
+     * @example
+     * ```ts
+     * import { Handler } from '@zcatalyst/transport';
+     * const response = await ResponseHandler.fireGeneralRequest({ url: '/baas/v1/project/123', method: 'GET', headers: {} });
+     * ```
+     */
+    static fireGeneralRequest({ requestCore, url }: {
+        requestCore: RequestInit;
+        url: string;
+    }, requestOptions?: RequestHandlerOptions): Promise<DefaultHttpResponse | void>;
+    /**
+     * Wraps a Fetch API response in the SDK response object.
+     *
+     * @param response - The response to wrap.
+     * @param options - The initialization or request options.
+     * @returns The wrap response result.
+     * @throws {CatalystAPIError} when the request or response cannot be processed.
+     *
+     * @example
+     * ```ts
+     * import { Handler } from '@zcatalyst/transport';
+     * const response = await ResponseHandler.wrapResponse({ url: '/baas/v1/project/123', method: 'GET', headers: {} });
+     * ```
+     */
+    static wrapResponse(response: Response, options?: RequestHandlerOptions): Promise<DefaultHttpResponse>;
+    /**
+     * Sends a browser fetch request without retry handling.
+     *
+     * @param requestCore - The Fetch API request configuration.
+     * @param reqOptions - The raw request handling options.
+     * @returns The fire raw request result.
+     *
+     * @example
+     * ```ts
+     * import { Handler } from '@zcatalyst/transport';
+     * const response = await ResponseHandler.fireRawRequest({ url: '/baas/v1/project/123', method: 'GET', headers: {} });
+     * ```
+     */
+    static fireRawRequest(requestCore: CoreType, reqOptions: RequestHandlerOptions): Promise<DefaultHttpResponse>;
+    /**
+     * Attaches browser authentication headers according to the configured auth protocol.
+     *
+     * @param headers - The headers object to mutate or extend.
+     * @returns The attach zcauth headers result.
+     *
+     * @example
+     * ```ts
+     * import { Handler } from '@zcatalyst/transport';
+     * const response = await ResponseHandler.attachZCAuthHeaders({ url: '/baas/v1/project/123', method: 'GET', headers: {} });
+     * ```
+     */
+    static attachZCAuthHeaders(headers: HeadersInit): Promise<HeadersInit>;
+    /**
+     * Builds the browser JWT authorization token from the configured cookie.
+     *
+     * @returns The get jwtzcauth token result.
+     *
+     * @example
+     * ```ts
+     * import { Handler } from '@zcatalyst/transport';
+     * const response = await ResponseHandler.getJWTZCAuthToken({ url: '/baas/v1/project/123', method: 'GET', headers: {} });
+     * ```
+     */
+    static getJWTZCAuthToken(): Promise<jwtAccessTokenResponse>;
+    /**
+     * Appends query parameters to a URL.
+     *
+     * @param url - The URL to update or request.
+     * @param qs - The query string values to append.
+     * @returns The URL with encoded query parameters.
+     *
+     * @example
+     * ```ts
+     * import { Handler } from '@zcatalyst/transport';
+     * const response = await ResponseHandler.appendQueryString({ url: '/baas/v1/project/123', method: 'GET', headers: {} });
+     * ```
+     */
+    static appendQueryString(url: string, qs?: Record<string, string | number | boolean | undefined>): string;
+    /**
+     * Sends a Catalyst HTTP request and returns the wrapped response.
+     *
+     * @param options - The initialization or request options.
+     * @param componentName - The component name for user-agent metadata.
+     * @param componentVersion - The component version for user-agent metadata.
+     * @returns The send result.
+     * @throws {CatalystAPIError} when the request or response cannot be processed.
+     *
+     * @example
+     * ```ts
+     * import { Handler } from '@zcatalyst/transport';
+     * const response = await ResponseHandler.send({ url: '/baas/v1/project/123', method: 'GET', headers: {} });
+     * ```
+     */
+    static send(options: IRequestConfig, componentName?: string, componentVersion?: string): Promise<DefaultHttpResponse | void>;
+}
+export {};

package/dist-types/http-handler.d.ts

@@ -0,0 +1,79 @@
+import { CatalystApp } from '@zcatalyst/auth-admin';
+import { ClientRequest, IncomingHttpHeaders, IncomingMessage } from 'http';
+import { Component, IRequestConfig } from './utils/interfaces';
+export interface IAPIResponse {
+    request: ClientRequest;
+    statusCode?: number;
+    headers: IncomingHttpHeaders;
+    data?: string;
+    buffer?: Buffer;
+    config: IRequestConfig;
+    stream?: IncomingMessage;
+}
+export declare class DefaultHttpResponse {
+    statusCode: number;
+    headers: IncomingHttpHeaders;
+    config: IRequestConfig;
+    resp: IAPIResponse;
+    /**
+     * Creates a DefaultHttpResponse instance.
+     * @param resp - The resp value.
+     */
+    constructor(resp: IAPIResponse);
+    /**
+     * Returns the parsed response payload.
+     *
+     * @returns The data result.
+     * @throws {CatalystAPIError} when the operation cannot be completed.
+     *
+     * @example
+     * ```ts
+     * import { Handler } from '@zcatalyst/transport';
+     * // Use DefaultHttpResponse.data while preparing or sending an SDK request.
+     * ```
+     */
+    get data(): any;
+}
+export declare class HttpClient {
+    app?: CatalystApp;
+    /** * @param app - The app used to fetch access tokens to sign API requests. */
+    constructor(app?: CatalystApp);
+    /**
+     * Sends a Catalyst HTTP request and returns the wrapped response.
+     *
+     * @param req - The req value.
+     * @param apmTrackerName - The apmTrackerName value.
+     * @param componentVersion - The componentVersion value.
+     * @returns The send result.
+     * @throws {CatalystAPIError} when the operation cannot be completed.
+     *
+     * @example
+     * ```ts
+     * import { Handler } from '@zcatalyst/transport';
+     * // Use HttpClient.send while preparing or sending an SDK request.
+     * ```
+     */
+    send(req: IRequestConfig, apmTrackerName?: string, componentVersion?: string): Promise<DefaultHttpResponse>;
+}
+export declare class AuthorizedHttpClient extends HttpClient {
+    readonly componentName?: string;
+    readonly componentVersion?: string;
+    /**
+     * @param app - The app used to fetch access tokens to sign API requests.
+     * @param component - Optional component metadata used to attach version headers.
+     */
+    constructor(app?: CatalystApp, component?: Component);
+    /**
+     * Sends a Catalyst HTTP request and returns the wrapped response.
+     *
+     * @param request - The request value.
+     * @returns The send result.
+     *
+     * @example
+     * ```ts
+     * import { Handler } from '@zcatalyst/transport';
+     * // Use AuthorizedHttpClient.send while preparing or sending an SDK request.
+     * ```
+     */
+    send(request: IRequestConfig): Promise<DefaultHttpResponse>;
+}

package/dist-types/index.browser.d.ts

@@ -0,0 +1,29 @@
+import { ICatalystClientRes } from './fetch-handler';
+import { Component, IRequestConfig } from './utils/interfaces';
+export { CatalystService, Component, CONSTANTS } from '@zcatalyst/utils';
+export { PrefixedCatalystError } from '@zcatalyst/utils';
+export declare class Handler {
+    component?: Component;
+    /**
+     * Creates a Handler instance.
+     * @param app - The app value.
+     * @param component - The component value.
+     */
+    constructor(app?: unknown, component?: Component);
+    /**
+     * Sends a Catalyst HTTP request and returns the wrapped response.
+     *
+     * @param options - The initialization or request options.
+     * @returns The send result.
+     *
+     * @example
+     * ```ts
+     * import { Handler } from '@zcatalyst/transport';
+     * const result = undefined;
+     * ```
+     */
+    send(options: IRequestConfig): Promise<ICatalystClientRes>;
+}
+export { RequestType, ResponseType } from './utils/enums';
+export { CatalystAPIError } from './utils/errors';
+export { IRequestConfig };

package/dist-types/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Internal HTTP / fetch transport layer used by every Catalyst component package.
+ *
+ * @packageDocumentation
+ */
+import { DefaultHttpResponse } from './http-handler';
+import FormData from './utils/form-data';
+import { Component, IRequestConfig } from './utils/interfaces';
+export { CatalystService, Component, CONSTANTS } from '@zcatalyst/utils';
+export { PrefixedCatalystError } from '@zcatalyst/utils';
+export declare class Handler {
+    component?: Component;
+    app?: any;
+    /**
+     * Creates a Handler instance.
+     * @param app - The app value.
+     * @param component - The component value.
+     */
+    constructor(app?: unknown, component?: Component);
+    /**
+     * Sends a Catalyst HTTP request through the Node transport handler.
+     *
+     * @param options - The request configuration to send.
+     * @returns The wrapped HTTP response.
+     *
+     * @example
+     * ```ts
+     * import { Handler } from '@zcatalyst/transport';
+     * const response = await new Handler(app).send({ method: 'GET', url: 'https://example.com' });
+     * ```
+     */
+    send(options: IRequestConfig): Promise<DefaultHttpResponse>;
+}
+export { RequestType, ResponseType } from './utils/enums';
+export { CatalystAPIError } from './utils/errors';
+export { FormData, IRequestConfig };