@usepylon/sdk 0.0.0-stage → 0.1.0-alpha.2

package/dist/esm/core/auth/AuthProvider.d.ts

@@ -0,0 +1,8 @@
+import type { EndpointMetadata } from "../fetcher/EndpointMetadata.js";
+import type { AuthRequest } from "./AuthRequest.js";
+export interface AuthProvider {
+    getAuthRequest(arg?: {
+        endpointMetadata?: EndpointMetadata;
+    }): Promise<AuthRequest>;
+}
+export declare function isAuthProvider(value: unknown): value is AuthProvider;

package/dist/esm/core/auth/AuthProvider.js

@@ -0,0 +1,6 @@
+export function isAuthProvider(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "getAuthRequest" in value &&
+        typeof value.getAuthRequest === "function");
+}

package/dist/esm/core/auth/AuthRequest.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Request parameters for authentication requests.
+ */
+export interface AuthRequest {
+    /**
+     * The headers to be included in the request.
+     */
+    headers: Record<string, string>;
+}

package/dist/esm/core/auth/AuthRequest.js

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

package/dist/esm/core/auth/BasicAuth.d.ts

@@ -0,0 +1,8 @@
+export interface BasicAuth {
+    username?: string;
+    password?: string;
+}
+export declare const BasicAuth: {
+    toAuthorizationHeader: (basicAuth: BasicAuth | undefined) => string | undefined;
+    fromAuthorizationHeader: (header: string) => BasicAuth;
+};

package/dist/esm/core/auth/BasicAuth.js

@@ -0,0 +1,30 @@
+import { base64Decode, base64Encode } from "../base64.js";
+const BASIC_AUTH_HEADER_PREFIX = /^Basic /i;
+export const BasicAuth = {
+    toAuthorizationHeader: (basicAuth) => {
+        var _a, _b;
+        if (basicAuth == null) {
+            return undefined;
+        }
+        const username = (_a = basicAuth.username) !== null && _a !== void 0 ? _a : "";
+        const password = (_b = basicAuth.password) !== null && _b !== void 0 ? _b : "";
+        if (username === "" && password === "") {
+            return undefined;
+        }
+        const token = base64Encode(`${username}:${password}`);
+        return `Basic ${token}`;
+    },
+    fromAuthorizationHeader: (header) => {
+        const credentials = header.replace(BASIC_AUTH_HEADER_PREFIX, "");
+        const decoded = base64Decode(credentials);
+        const [username, ...passwordParts] = decoded.split(":");
+        const password = passwordParts.length > 0 ? passwordParts.join(":") : undefined;
+        if (username == null || password == null) {
+            throw new Error("Invalid basic auth");
+        }
+        return {
+            username,
+            password,
+        };
+    },
+};

package/dist/esm/core/auth/BearerToken.d.ts

@@ -0,0 +1,7 @@
+export type BearerToken = string;
+declare function toAuthorizationHeader(token: string | undefined): string | undefined;
+export declare const BearerToken: {
+    toAuthorizationHeader: typeof toAuthorizationHeader;
+    fromAuthorizationHeader: (header: string) => BearerToken;
+};
+export {};

package/dist/esm/core/auth/BearerToken.js

@@ -0,0 +1,13 @@
+const BEARER_AUTH_HEADER_PREFIX = /^Bearer /i;
+function toAuthorizationHeader(token) {
+    if (token == null) {
+        return undefined;
+    }
+    return `Bearer ${token}`;
+}
+export const BearerToken = {
+    toAuthorizationHeader: toAuthorizationHeader,
+    fromAuthorizationHeader: (header) => {
+        return header.replace(BEARER_AUTH_HEADER_PREFIX, "").trim();
+    },
+};

package/dist/esm/core/auth/NoOpAuthProvider.d.ts

@@ -0,0 +1,5 @@
+import type { AuthProvider } from "./AuthProvider.js";
+import type { AuthRequest } from "./AuthRequest.js";
+export declare class NoOpAuthProvider implements AuthProvider {
+    getAuthRequest(): Promise<AuthRequest>;
+}

package/dist/esm/core/auth/NoOpAuthProvider.js

@@ -0,0 +1,5 @@
+export class NoOpAuthProvider {
+    getAuthRequest() {
+        return Promise.resolve({ headers: {} });
+    }
+}

package/dist/esm/core/auth/index.d.ts

@@ -0,0 +1,5 @@
+export { type AuthProvider, isAuthProvider } from "./AuthProvider.js";
+export type { AuthRequest } from "./AuthRequest.js";
+export { BasicAuth } from "./BasicAuth.js";
+export { BearerToken } from "./BearerToken.js";
+export { NoOpAuthProvider } from "./NoOpAuthProvider.js";

package/dist/esm/core/auth/index.js

@@ -0,0 +1,4 @@
+export { isAuthProvider } from "./AuthProvider.js";
+export { BasicAuth } from "./BasicAuth.js";
+export { BearerToken } from "./BearerToken.js";
+export { NoOpAuthProvider } from "./NoOpAuthProvider.js";

package/dist/esm/core/base64.d.ts

@@ -0,0 +1,2 @@
+export declare function base64Encode(input: string): string;
+export declare function base64Decode(input: string): string;

package/dist/esm/core/base64.js

@@ -0,0 +1,22 @@
+function base64ToBytes(base64) {
+    const binString = atob(base64);
+    return Uint8Array.from(binString, (m) => m.codePointAt(0));
+}
+function bytesToBase64(bytes) {
+    const binString = String.fromCodePoint(...bytes);
+    return btoa(binString);
+}
+export function base64Encode(input) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(input, "utf8").toString("base64");
+    }
+    const bytes = new TextEncoder().encode(input);
+    return bytesToBase64(bytes);
+}
+export function base64Decode(input) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(input, "base64").toString("utf8");
+    }
+    const bytes = base64ToBytes(input);
+    return new TextDecoder().decode(bytes);
+}

package/dist/esm/core/exports.d.ts

@@ -0,0 +1,3 @@
+export * from "./file/exports.js";
+export * from "./logging/exports.js";
+export * from "./pagination/exports.js";

package/dist/esm/core/exports.js

@@ -0,0 +1,3 @@
+export * from "./file/exports.js";
+export * from "./logging/exports.js";
+export * from "./pagination/exports.js";

package/dist/esm/core/fetcher/APIResponse.d.ts

@@ -0,0 +1,20 @@
+import type { RawResponse } from "./RawResponse.js";
+/**
+ * The response of an API call.
+ * It is a successful response or a failed response.
+ */
+export type APIResponse<Success, Failure> = SuccessfulResponse<Success> | FailedResponse<Failure>;
+export interface SuccessfulResponse<T> {
+    ok: true;
+    body: T;
+    /**
+     * @deprecated Use `rawResponse` instead
+     */
+    headers?: Record<string, any>;
+    rawResponse: RawResponse;
+}
+export interface FailedResponse<T> {
+    ok: false;
+    error: T;
+    rawResponse: RawResponse;
+}

package/dist/esm/core/fetcher/APIResponse.js

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

package/dist/esm/core/fetcher/BinaryResponse.d.ts

@@ -0,0 +1,19 @@
+export type BinaryResponse = {
+    /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bodyUsed) */
+    bodyUsed: Response["bodyUsed"];
+    /**
+     * Returns a ReadableStream of the response body.
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/body)
+     */
+    stream: () => Response["body"];
+    /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/arrayBuffer) */
+    arrayBuffer: () => ReturnType<Response["arrayBuffer"]>;
+    /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/blob) */
+    blob: () => ReturnType<Response["blob"]>;
+    /**
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bytes)
+     * Some versions of the Fetch API may not support this method.
+     */
+    bytes?(): Promise<Uint8Array>;
+};
+export declare function getBinaryResponse(response: Response): BinaryResponse;

package/dist/esm/core/fetcher/BinaryResponse.js

@@ -0,0 +1,14 @@
+export function getBinaryResponse(response) {
+    const binaryResponse = {
+        get bodyUsed() {
+            return response.bodyUsed;
+        },
+        stream: () => response.body,
+        arrayBuffer: response.arrayBuffer.bind(response),
+        blob: response.blob.bind(response),
+    };
+    if ("bytes" in response && typeof response.bytes === "function") {
+        binaryResponse.bytes = response.bytes.bind(response);
+    }
+    return binaryResponse;
+}

package/dist/esm/core/fetcher/EndpointMetadata.d.ts

@@ -0,0 +1,13 @@
+export type SecuritySchemeKey = string;
+/**
+ * A collection of security schemes, where the key is the name of the security scheme and the value is the list of scopes required for that scheme.
+ * All schemes in the collection must be satisfied for authentication to be successful.
+ */
+export type SecuritySchemeCollection = Record<SecuritySchemeKey, AuthScope[]>;
+export type AuthScope = string;
+export type EndpointMetadata = {
+    /**
+     * An array of security scheme collections. Each collection represents an alternative way to authenticate.
+     */
+    security?: SecuritySchemeCollection[];
+};

package/dist/esm/core/fetcher/EndpointMetadata.js

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

package/dist/esm/core/fetcher/EndpointSupplier.d.ts

@@ -0,0 +1,12 @@
+import type { EndpointMetadata } from "./EndpointMetadata.js";
+import type { Supplier } from "./Supplier.js";
+type EndpointSupplierFn<T> = (arg: {
+    endpointMetadata?: EndpointMetadata;
+}) => T | Promise<T>;
+export type EndpointSupplier<T> = Supplier<T> | EndpointSupplierFn<T>;
+export declare const EndpointSupplier: {
+    get: <T>(supplier: EndpointSupplier<T>, arg: {
+        endpointMetadata?: EndpointMetadata;
+    }) => Promise<T>;
+};
+export {};

package/dist/esm/core/fetcher/EndpointSupplier.js

@@ -0,0 +1,19 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+export const EndpointSupplier = {
+    get: (supplier, arg) => __awaiter(void 0, void 0, void 0, function* () {
+        if (typeof supplier === "function") {
+            return supplier(arg);
+        }
+        else {
+            return supplier;
+        }
+    }),
+};

package/dist/esm/core/fetcher/Fetcher.d.ts

@@ -0,0 +1,56 @@
+import { type LogConfig, type Logger } from "../logging/logger.js";
+import type { APIResponse } from "./APIResponse.js";
+import type { EndpointMetadata } from "./EndpointMetadata.js";
+export type FetchFunction = <R = unknown>(args: Fetcher.Args) => Promise<APIResponse<R, Fetcher.Error>>;
+export declare namespace Fetcher {
+    interface Args {
+        url: string;
+        method: string;
+        contentType?: string;
+        headers?: Record<string, unknown>;
+        /**
+         * @deprecated Prefer `queryString` (produced by `core.url.queryBuilder()`).
+         * Retained for backwards compatibility with custom fetchers and callers that
+         * still construct request args with a query-parameter object.
+         */
+        queryParameters?: Record<string, unknown>;
+        queryString?: string;
+        body?: unknown;
+        timeoutMs?: number;
+        maxRetries?: number;
+        withCredentials?: boolean;
+        abortSignal?: AbortSignal;
+        requestType?: "json" | "file" | "bytes" | "form" | "other";
+        responseType?: "json" | "blob" | "sse" | "streaming" | "text" | "arrayBuffer" | "binary-response";
+        duplex?: "half";
+        endpointMetadata?: EndpointMetadata;
+        fetchFn?: typeof fetch;
+        logging?: LogConfig | Logger;
+    }
+    type Error = FailedStatusCodeError | NonJsonError | BodyIsNullError | TimeoutError | UnknownError;
+    interface FailedStatusCodeError {
+        reason: "status-code";
+        statusCode: number;
+        body: unknown;
+    }
+    interface NonJsonError {
+        reason: "non-json";
+        statusCode: number;
+        rawBody: string;
+    }
+    interface BodyIsNullError {
+        reason: "body-is-null";
+        statusCode: number;
+    }
+    interface TimeoutError {
+        reason: "timeout";
+        cause?: unknown;
+    }
+    interface UnknownError {
+        reason: "unknown";
+        errorMessage: string;
+        cause?: unknown;
+    }
+}
+export declare function fetcherImpl<R = unknown>(args: Fetcher.Args): Promise<APIResponse<R, Fetcher.Error>>;
+export declare const fetcher: FetchFunction;

package/dist/esm/core/fetcher/Fetcher.js

@@ -0,0 +1,270 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { toJson } from "../json.js";
+import { createLogger } from "../logging/logger.js";
+import { createRequestUrl } from "./createRequestUrl.js";
+import { EndpointSupplier } from "./EndpointSupplier.js";
+import { getErrorResponseBody } from "./getErrorResponseBody.js";
+import { getFetchFn } from "./getFetchFn.js";
+import { getRequestBody } from "./getRequestBody.js";
+import { getResponseBody, isResponseBodyError } from "./getResponseBody.js";
+import { Headers } from "./Headers.js";
+import { clearResponseTimeout, makeRequest } from "./makeRequest.js";
+import { abortRawResponse, toRawResponse, unknownRawResponse } from "./RawResponse.js";
+import { redactUrl, SENSITIVE_QUERY_PARAMS } from "./redactUrl.js";
+import { requestWithRetries } from "./requestWithRetries.js";
+import { TIMEOUT } from "./signals.js";
+const SENSITIVE_HEADERS = new Set([
+    "authorization",
+    "www-authenticate",
+    "x-api-key",
+    "api-key",
+    "apikey",
+    "x-api-token",
+    "x-auth-token",
+    "auth-token",
+    "cookie",
+    "set-cookie",
+    "proxy-authorization",
+    "proxy-authenticate",
+    "x-csrf-token",
+    "x-xsrf-token",
+    "x-session-token",
+    "x-access-token",
+]);
+function redactHeaders(headers) {
+    const filtered = {};
+    for (const [key, value] of headers instanceof Headers ? headers.entries() : Object.entries(headers)) {
+        if (SENSITIVE_HEADERS.has(key.toLowerCase())) {
+            filtered[key] = "[REDACTED]";
+        }
+        else {
+            filtered[key] = value;
+        }
+    }
+    return filtered;
+}
+function redactQueryParameters(queryParameters) {
+    if (queryParameters == null) {
+        return undefined;
+    }
+    const redacted = {};
+    for (const [key, value] of Object.entries(queryParameters)) {
+        redacted[key] = SENSITIVE_QUERY_PARAMS.has(key.toLowerCase()) ? "[REDACTED]" : value;
+    }
+    return redacted;
+}
+function getHeaders(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const newHeaders = new Headers();
+        newHeaders.set("Accept", args.responseType === "json"
+            ? "application/json"
+            : args.responseType === "text"
+                ? "text/plain"
+                : args.responseType === "sse"
+                    ? "text/event-stream"
+                    : "*/*");
+        if (args.body !== undefined && args.contentType != null) {
+            newHeaders.set("Content-Type", args.contentType);
+        }
+        if (args.headers == null) {
+            return newHeaders;
+        }
+        for (const [key, value] of Object.entries(args.headers)) {
+            const result = yield EndpointSupplier.get(value, { endpointMetadata: (_a = args.endpointMetadata) !== null && _a !== void 0 ? _a : {} });
+            if (typeof result === "string") {
+                newHeaders.set(key, result);
+                continue;
+            }
+            if (result == null) {
+                continue;
+            }
+            newHeaders.set(key, `${result}`);
+        }
+        return newHeaders;
+    });
+}
+function isJsonContentType(contentType) {
+    var _a, _b;
+    const mediaType = (_b = (_a = contentType === null || contentType === void 0 ? void 0 : contentType.split(";")[0]) === null || _a === void 0 ? void 0 : _a.trim().toLowerCase()) !== null && _b !== void 0 ? _b : "";
+    return mediaType === "application/json" || mediaType === "text/json" || mediaType.endsWith("+json");
+}
+export function fetcherImpl(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        let url = args.url;
+        if (args.queryString != null && args.queryString.length > 0) {
+            url = `${url}?${args.queryString}`;
+        }
+        else {
+            url = createRequestUrl(args.url, args.queryParameters);
+        }
+        const requestBody = yield getRequestBody({
+            body: args.body,
+            type: (_a = args.requestType) !== null && _a !== void 0 ? _a : "other",
+        });
+        const fetchFn = (_b = args.fetchFn) !== null && _b !== void 0 ? _b : (yield getFetchFn());
+        const headers = yield getHeaders(args);
+        const logger = createLogger(args.logging);
+        if (logger.isDebug()) {
+            const metadata = {
+                method: args.method,
+                url: redactUrl(url),
+                headers: redactHeaders(headers),
+                queryParameters: redactQueryParameters(args.queryParameters),
+                hasBody: requestBody != null,
+            };
+            logger.debug("Making HTTP request", metadata);
+        }
+        // Bodies that are read in full here stay covered by the timeout; streamed bodies are read by the caller.
+        const keepTimeoutUntilBodyRead = args.responseType !== "streaming" && args.responseType !== "sse" && args.responseType !== "binary-response";
+        const attemptResponses = [];
+        try {
+            const response = yield requestWithRetries(() => __awaiter(this, void 0, void 0, function* () {
+                // A retry means the previous attempt is over; stop its timer now rather than at the end.
+                for (const previousResponse of attemptResponses) {
+                    clearResponseTimeout(previousResponse);
+                }
+                const attemptResponse = yield makeRequest(fetchFn, url, args.method, headers, requestBody, args.timeoutMs, args.abortSignal, args.withCredentials, args.duplex, args.responseType === "streaming" || args.responseType === "sse", keepTimeoutUntilBodyRead);
+                attemptResponses.push(attemptResponse);
+                return attemptResponse;
+            }), args.maxRetries, args.abortSignal);
+            if (response.status >= 200 && response.status < 400) {
+                if (logger.isDebug()) {
+                    const metadata = {
+                        method: args.method,
+                        url: redactUrl(url),
+                        statusCode: response.status,
+                        responseHeaders: redactHeaders(response.headers),
+                    };
+                    logger.debug("HTTP request succeeded", metadata);
+                }
+                const body = yield getResponseBody(response, args.responseType);
+                // Only a body the server labelled as JSON is an error here; void endpoints may return plain text.
+                if (isResponseBodyError(body) &&
+                    body.error.reason === "non-json" &&
+                    isJsonContentType(response.headers.get("Content-Type"))) {
+                    return {
+                        ok: false,
+                        error: body.error,
+                        rawResponse: toRawResponse(response),
+                    };
+                }
+                return {
+                    ok: true,
+                    body: body,
+                    headers: response.headers,
+                    rawResponse: toRawResponse(response),
+                };
+            }
+            else {
+                if (logger.isError()) {
+                    const metadata = {
+                        method: args.method,
+                        url: redactUrl(url),
+                        statusCode: response.status,
+                        responseHeaders: redactHeaders(Object.fromEntries(response.headers.entries())),
+                    };
+                    logger.error("HTTP request failed with error status", metadata);
+                }
+                return {
+                    ok: false,
+                    error: {
+                        reason: "status-code",
+                        statusCode: response.status,
+                        body: yield getErrorResponseBody(response),
+                    },
+                    rawResponse: toRawResponse(response),
+                };
+            }
+        }
+        catch (error) {
+            if ((_c = args.abortSignal) === null || _c === void 0 ? void 0 : _c.aborted) {
+                if (logger.isError()) {
+                    const metadata = {
+                        method: args.method,
+                        url: redactUrl(url),
+                    };
+                    logger.error("HTTP request was aborted", metadata);
+                }
+                return {
+                    ok: false,
+                    error: {
+                        reason: "unknown",
+                        errorMessage: "The user aborted a request",
+                        cause: error,
+                    },
+                    rawResponse: abortRawResponse,
+                };
+            }
+            else if (error === TIMEOUT || (error instanceof Error && error.name === "AbortError")) {
+                if (logger.isError()) {
+                    const metadata = {
+                        method: args.method,
+                        url: redactUrl(url),
+                        timeoutMs: args.timeoutMs,
+                    };
+                    logger.error("HTTP request timed out", metadata);
+                }
+                return {
+                    ok: false,
+                    error: {
+                        reason: "timeout",
+                        cause: error,
+                    },
+                    rawResponse: abortRawResponse,
+                };
+            }
+            else if (error instanceof Error) {
+                if (logger.isError()) {
+                    const metadata = {
+                        method: args.method,
+                        url: redactUrl(url),
+                        errorMessage: error.message,
+                    };
+                    logger.error("HTTP request failed with error", metadata);
+                }
+                return {
+                    ok: false,
+                    error: {
+                        reason: "unknown",
+                        errorMessage: error.message,
+                        cause: error,
+                    },
+                    rawResponse: unknownRawResponse,
+                };
+            }
+            if (logger.isError()) {
+                const metadata = {
+                    method: args.method,
+                    url: redactUrl(url),
+                    error: toJson(error),
+                };
+                logger.error("HTTP request failed with unknown error", metadata);
+            }
+            return {
+                ok: false,
+                error: {
+                    reason: "unknown",
+                    errorMessage: toJson(error),
+                    cause: error,
+                },
+                rawResponse: unknownRawResponse,
+            };
+        }
+        finally {
+            for (const attemptResponse of attemptResponses) {
+                clearResponseTimeout(attemptResponse);
+            }
+        }
+    });
+}
+export const fetcher = fetcherImpl;

package/dist/esm/core/fetcher/Headers.d.ts

@@ -0,0 +1,2 @@
+declare let Headers: typeof globalThis.Headers;
+export { Headers };