plato-sandbox-sdk 1.1.1

package/core/fetcher/requestWithRetries.ts

@@ -0,0 +1,73 @@
+const INITIAL_RETRY_DELAY = 1000; // in milliseconds
+const MAX_RETRY_DELAY = 60000; // in milliseconds
+const DEFAULT_MAX_RETRIES = 2;
+const JITTER_FACTOR = 0.2; // 20% random jitter
+
+function addPositiveJitter(delay: number): number {
+    // Generate a random value between 0 and +JITTER_FACTOR
+    const jitterMultiplier = 1 + Math.random() * JITTER_FACTOR;
+    return delay * jitterMultiplier;
+}
+
+function addSymmetricJitter(delay: number): number {
+    // Generate a random value in a JITTER_FACTOR-sized percentage range around delay
+    const jitterMultiplier = 1 + (Math.random() - 0.5) * JITTER_FACTOR;
+    return delay * jitterMultiplier;
+}
+
+function getRetryDelayFromHeaders(response: Response, retryAttempt: number): number {
+    // Check for Retry-After header first (RFC 7231), with no jitter
+    const retryAfter = response.headers.get("Retry-After");
+    if (retryAfter) {
+        // Parse as number of seconds...
+        const retryAfterSeconds = parseInt(retryAfter, 10);
+        if (!Number.isNaN(retryAfterSeconds) && retryAfterSeconds > 0) {
+            return Math.min(retryAfterSeconds * 1000, MAX_RETRY_DELAY);
+        }
+
+        // ...or as an HTTP date; both are valid
+        const retryAfterDate = new Date(retryAfter);
+        if (!Number.isNaN(retryAfterDate.getTime())) {
+            const delay = retryAfterDate.getTime() - Date.now();
+            if (delay > 0) {
+                return Math.min(Math.max(delay, 0), MAX_RETRY_DELAY);
+            }
+        }
+    }
+
+    // Then check for industry-standard X-RateLimit-Reset header, with positive jitter
+    const rateLimitReset = response.headers.get("X-RateLimit-Reset");
+    if (rateLimitReset) {
+        const resetTime = parseInt(rateLimitReset, 10);
+        if (!Number.isNaN(resetTime)) {
+            // Assume Unix timestamp in epoch seconds
+            const delay = resetTime * 1000 - Date.now();
+            if (delay > 0) {
+                return addPositiveJitter(Math.min(delay, MAX_RETRY_DELAY));
+            }
+        }
+    }
+
+    // Fall back to exponential backoff, with symmetric jitter
+    return addSymmetricJitter(Math.min(INITIAL_RETRY_DELAY * 2 ** retryAttempt, MAX_RETRY_DELAY));
+}
+
+export async function requestWithRetries(
+    requestFn: () => Promise<Response>,
+    maxRetries: number = DEFAULT_MAX_RETRIES,
+): Promise<Response> {
+    let response: Response = await requestFn();
+
+    for (let i = 0; i < maxRetries; ++i) {
+        if ([408, 429].includes(response.status) || response.status >= 500) {
+            // Get delay with appropriate jitter applied
+            const delay = getRetryDelayFromHeaders(response, i);
+
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            response = await requestFn();
+        } else {
+            break;
+        }
+    }
+    return response!;
+}

package/core/fetcher/signals.ts

@@ -0,0 +1,38 @@
+const TIMEOUT = "timeout";
+
+export function getTimeoutSignal(timeoutMs: number): { signal: AbortSignal; abortId: NodeJS.Timeout } {
+    const controller = new AbortController();
+    const abortId = setTimeout(() => controller.abort(TIMEOUT), timeoutMs);
+    return { signal: controller.signal, abortId };
+}
+
+/**
+ * Returns an abort signal that is getting aborted when
+ * at least one of the specified abort signals is aborted.
+ *
+ * Requires at least node.js 18.
+ */
+export function anySignal(...args: AbortSignal[] | [AbortSignal[]]): AbortSignal {
+    // Allowing signals to be passed either as array
+    // of signals or as multiple arguments.
+    const signals = (args.length === 1 && Array.isArray(args[0]) ? args[0] : args) as AbortSignal[];
+
+    const controller = new AbortController();
+
+    for (const signal of signals) {
+        if (signal.aborted) {
+            // Exiting early if one of the signals
+            // is already aborted.
+            controller.abort((signal as any)?.reason);
+            break;
+        }
+
+        // Listening for signals and removing the listeners
+        // when at least one symbol is aborted.
+        signal.addEventListener("abort", () => controller.abort((signal as any)?.reason), {
+            signal: controller.signal,
+        });
+    }
+
+    return controller.signal;
+}

package/core/headers.ts

@@ -0,0 +1,33 @@
+export function mergeHeaders<THeaderValue>(
+    ...headersArray: (Record<string, THeaderValue> | null | undefined)[]
+): Record<string, string | THeaderValue> {
+    const result: Record<string, THeaderValue> = {};
+
+    for (const [key, value] of headersArray
+        .filter((headers) => headers != null)
+        .flatMap((headers) => Object.entries(headers))) {
+        if (value != null) {
+            result[key] = value;
+        } else if (key in result) {
+            delete result[key];
+        }
+    }
+
+    return result;
+}
+
+export function mergeOnlyDefinedHeaders<THeaderValue>(
+    ...headersArray: (Record<string, THeaderValue> | null | undefined)[]
+): Record<string, THeaderValue> {
+    const result: Record<string, THeaderValue> = {};
+
+    for (const [key, value] of headersArray
+        .filter((headers) => headers != null)
+        .flatMap((headers) => Object.entries(headers))) {
+        if (value != null) {
+            result[key] = value;
+        }
+    }
+
+    return result;
+}

package/core/index.ts

@@ -0,0 +1,4 @@
+export * from "./fetcher/index.js";
+export * from "./runtime/index.js";
+export * from "./stream/index.js";
+export * as url from "./url/index.js";

package/core/json.ts

@@ -0,0 +1,27 @@
+/**
+ * Serialize a value to JSON
+ * @param value A JavaScript value, usually an object or array, to be converted.
+ * @param replacer A function that transforms the results.
+ * @param space Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read.
+ * @returns JSON string
+ */
+export const toJson = (
+    value: unknown,
+    replacer?: (this: unknown, key: string, value: unknown) => unknown,
+    space?: string | number,
+): string => {
+    return JSON.stringify(value, replacer, space);
+};
+
+/**
+ * Parse JSON string to object, array, or other type
+ * @param text A valid JSON string.
+ * @param reviver A function that transforms the results. This function is called for each member of the object. If a member contains nested objects, the nested objects are transformed before the parent object is.
+ * @returns Parsed object, array, or other type
+ */
+export function fromJson<T = unknown>(
+    text: string,
+    reviver?: (this: unknown, key: string, value: unknown) => unknown,
+): T {
+    return JSON.parse(text, reviver);
+}

package/core/runtime/index.ts

@@ -0,0 +1 @@
+export { RUNTIME } from "./runtime.js";

package/core/runtime/runtime.ts

@@ -0,0 +1,133 @@
+interface DenoGlobal {
+    version: {
+        deno: string;
+    };
+}
+
+interface BunGlobal {
+    version: string;
+}
+
+declare const Deno: DenoGlobal | undefined;
+declare const Bun: BunGlobal | undefined;
+declare const EdgeRuntime: string | undefined;
+declare const self: typeof globalThis.self & {
+    importScripts?: unknown;
+};
+
+/**
+ * A constant that indicates which environment and version the SDK is running in.
+ */
+export const RUNTIME: Runtime = evaluateRuntime();
+
+export interface Runtime {
+    type: "browser" | "web-worker" | "deno" | "bun" | "node" | "react-native" | "unknown" | "workerd" | "edge-runtime";
+    version?: string;
+    parsedVersion?: number;
+}
+
+function evaluateRuntime(): Runtime {
+    /**
+     * A constant that indicates whether the environment the code is running is a Web Browser.
+     */
+    const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
+    if (isBrowser) {
+        return {
+            type: "browser",
+            version: window.navigator.userAgent,
+        };
+    }
+
+    /**
+     * A constant that indicates whether the environment the code is running is Cloudflare.
+     * https://developers.cloudflare.com/workers/runtime-apis/web-standards/#navigatoruseragent
+     */
+    const isCloudflare = typeof globalThis !== "undefined" && globalThis?.navigator?.userAgent === "Cloudflare-Workers";
+    if (isCloudflare) {
+        return {
+            type: "workerd",
+        };
+    }
+
+    /**
+     * A constant that indicates whether the environment the code is running is Edge Runtime.
+     * https://vercel.com/docs/functions/runtimes/edge-runtime#check-if-you're-running-on-the-edge-runtime
+     */
+    const isEdgeRuntime = typeof EdgeRuntime === "string";
+    if (isEdgeRuntime) {
+        return {
+            type: "edge-runtime",
+        };
+    }
+
+    /**
+     * A constant that indicates whether the environment the code is running is a Web Worker.
+     */
+    const isWebWorker =
+        typeof self === "object" &&
+        typeof self?.importScripts === "function" &&
+        (self.constructor?.name === "DedicatedWorkerGlobalScope" ||
+            self.constructor?.name === "ServiceWorkerGlobalScope" ||
+            self.constructor?.name === "SharedWorkerGlobalScope");
+    if (isWebWorker) {
+        return {
+            type: "web-worker",
+        };
+    }
+
+    /**
+     * A constant that indicates whether the environment the code is running is Deno.
+     * FYI Deno spoofs process.versions.node, see https://deno.land/std@0.177.0/node/process.ts?s=versions
+     */
+    const isDeno =
+        typeof Deno !== "undefined" && typeof Deno.version !== "undefined" && typeof Deno.version.deno !== "undefined";
+    if (isDeno) {
+        return {
+            type: "deno",
+            version: Deno.version.deno,
+        };
+    }
+
+    /**
+     * A constant that indicates whether the environment the code is running is Bun.sh.
+     */
+    const isBun = typeof Bun !== "undefined" && typeof Bun.version !== "undefined";
+    if (isBun) {
+        return {
+            type: "bun",
+            version: Bun.version,
+        };
+    }
+
+    /**
+     * A constant that indicates whether the environment the code is running is Node.JS.
+     */
+    const isNode =
+        typeof process !== "undefined" &&
+        "version" in process &&
+        !!process.version &&
+        "versions" in process &&
+        !!process.versions?.node;
+    if (isNode) {
+        return {
+            type: "node",
+            version: process.versions.node,
+            parsedVersion: Number(process.versions.node.split(".")[0]),
+        };
+    }
+
+    /**
+     * A constant that indicates whether the environment the code is running is in React-Native.
+     * https://github.com/facebook/react-native/blob/main/packages/react-native/Libraries/Core/setUpNavigator.js
+     */
+    const isReactNative = typeof navigator !== "undefined" && navigator?.product === "ReactNative";
+    if (isReactNative) {
+        return {
+            type: "react-native",
+        };
+    }
+
+    return {
+        type: "unknown",
+    };
+}

package/core/stream/Stream.ts

@@ -0,0 +1,155 @@
+import { RUNTIME } from "../runtime/index.js";
+
+export declare namespace Stream {
+    interface Args {
+        /**
+         * The HTTP response stream to read from.
+         */
+
+        stream: ReadableStream;
+
+        /**
+         * The event shape to use for parsing the stream data.
+         */
+        eventShape: JsonEvent | SseEvent;
+        /**
+         * An abort signal to stop the stream.
+         */
+        signal?: AbortSignal;
+    }
+
+    interface JsonEvent {
+        type: "json";
+        messageTerminator: string;
+    }
+
+    interface SseEvent {
+        type: "sse";
+        streamTerminator?: string;
+    }
+}
+
+const DATA_PREFIX = "data:";
+
+export class Stream<T> implements AsyncIterable<T> {
+    private stream: ReadableStream;
+
+    private parse: (val: unknown) => Promise<T>;
+    /**
+     * The prefix to use for each message. For example,
+     * for SSE, the prefix is "data: ".
+     */
+    private prefix: string | undefined;
+    private messageTerminator: string;
+    private streamTerminator: string | undefined;
+    private controller: AbortController = new AbortController();
+    private decoder: TextDecoder | undefined;
+
+    constructor({ stream, parse, eventShape, signal }: Stream.Args & { parse: (val: unknown) => Promise<T> }) {
+        this.stream = stream;
+        this.parse = parse;
+        if (eventShape.type === "sse") {
+            this.prefix = DATA_PREFIX;
+            this.messageTerminator = "\n";
+            this.streamTerminator = eventShape.streamTerminator;
+        } else {
+            this.messageTerminator = eventShape.messageTerminator;
+        }
+        signal?.addEventListener("abort", () => this.controller.abort());
+
+        // Initialize shared TextDecoder
+        if (typeof TextDecoder !== "undefined") {
+            this.decoder = new TextDecoder("utf-8");
+        }
+    }
+
+    private async *iterMessages(): AsyncGenerator<T, void> {
+        this.controller.signal;
+        const stream = readableStreamAsyncIterable<any>(this.stream);
+        let buf = "";
+        let prefixSeen = false;
+        for await (const chunk of stream) {
+            buf += this.decodeChunk(chunk);
+
+            let terminatorIndex: number;
+            while ((terminatorIndex = buf.indexOf(this.messageTerminator)) >= 0) {
+                let line = buf.slice(0, terminatorIndex);
+                buf = buf.slice(terminatorIndex + this.messageTerminator.length);
+
+                if (!line.trim()) {
+                    continue;
+                }
+
+                if (!prefixSeen && this.prefix != null) {
+                    const prefixIndex = line.indexOf(this.prefix);
+                    if (prefixIndex === -1) {
+                        continue;
+                    }
+                    prefixSeen = true;
+                    line = line.slice(prefixIndex + this.prefix.length);
+                }
+
+                if (this.streamTerminator != null && line.includes(this.streamTerminator)) {
+                    return;
+                }
+                const message = await this.parse(JSON.parse(line));
+                yield message;
+                prefixSeen = false;
+            }
+        }
+    }
+
+    async *[Symbol.asyncIterator](): AsyncIterator<T, void, unknown> {
+        for await (const message of this.iterMessages()) {
+            yield message;
+        }
+    }
+
+    private decodeChunk(chunk: any): string {
+        let decoded = "";
+        // If TextDecoder is available, use the streaming decoder instance
+        if (this.decoder != null) {
+            decoded += this.decoder.decode(chunk, { stream: true });
+        }
+        // Buffer is present in Node.js environment
+        else if (RUNTIME.type === "node" && typeof chunk !== "undefined") {
+            decoded += Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        }
+        return decoded;
+    }
+}
+
+/**
+ * Browser polyfill for ReadableStream
+ */
+// biome-ignore lint/suspicious/noExplicitAny: allow explicit any
+export function readableStreamAsyncIterable<T>(stream: any): AsyncIterableIterator<T> {
+    if (stream[Symbol.asyncIterator]) {
+        return stream;
+    }
+
+    const reader = stream.getReader();
+    return {
+        async next() {
+            try {
+                const result = await reader.read();
+                if (result?.done) {
+                    reader.releaseLock();
+                } // release lock when stream becomes closed
+                return result;
+            } catch (e) {
+                reader.releaseLock(); // release lock when stream becomes errored
+                throw e;
+            }
+        },
+        async return() {
+            const cancelPromise = reader.cancel();
+            reader.releaseLock();
+            await cancelPromise;
+            return { done: true, value: undefined };
+        },
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+    };
+}

package/core/stream/index.ts

@@ -0,0 +1 @@
+export { Stream } from "./Stream.js";

package/core/url/encodePathParam.ts

@@ -0,0 +1,18 @@
+export function encodePathParam(param: unknown): string {
+    if (param === null) {
+        return "null";
+    }
+    const typeofParam = typeof param;
+    switch (typeofParam) {
+        case "undefined":
+            return "undefined";
+        case "string":
+        case "number":
+        case "boolean":
+            break;
+        default:
+            param = String(param);
+            break;
+    }
+    return encodeURIComponent(param as string | number | boolean);
+}

package/core/url/index.ts

@@ -0,0 +1,3 @@
+export { encodePathParam } from "./encodePathParam.js";
+export { join } from "./join.js";
+export { toQueryString } from "./qs.js";

package/core/url/join.ts

@@ -0,0 +1,80 @@
+export function join(base: string, ...segments: string[]): string {
+    if (!base) {
+        return "";
+    }
+
+    if (segments.length === 0) {
+        return base;
+    }
+
+    if (base.includes("://")) {
+        let url: URL;
+        try {
+            url = new URL(base);
+        } catch {
+            // Fallback to path joining if URL is malformed
+            return joinPath(base, ...segments);
+        }
+
+        const lastSegment = segments[segments.length - 1];
+        const shouldPreserveTrailingSlash = lastSegment?.endsWith("/");
+
+        for (const segment of segments) {
+            const cleanSegment = trimSlashes(segment);
+            if (cleanSegment) {
+                url.pathname = joinPathSegments(url.pathname, cleanSegment);
+            }
+        }
+
+        if (shouldPreserveTrailingSlash && !url.pathname.endsWith("/")) {
+            url.pathname += "/";
+        }
+
+        return url.toString();
+    }
+
+    return joinPath(base, ...segments);
+}
+
+function joinPath(base: string, ...segments: string[]): string {
+    if (segments.length === 0) {
+        return base;
+    }
+
+    let result = base;
+
+    const lastSegment = segments[segments.length - 1];
+    const shouldPreserveTrailingSlash = lastSegment?.endsWith("/");
+
+    for (const segment of segments) {
+        const cleanSegment = trimSlashes(segment);
+        if (cleanSegment) {
+            result = joinPathSegments(result, cleanSegment);
+        }
+    }
+
+    if (shouldPreserveTrailingSlash && !result.endsWith("/")) {
+        result += "/";
+    }
+
+    return result;
+}
+
+function joinPathSegments(left: string, right: string): string {
+    if (left.endsWith("/")) {
+        return left + right;
+    }
+    return `${left}/${right}`;
+}
+
+function trimSlashes(str: string): string {
+    if (!str) return str;
+
+    let start = 0;
+    let end = str.length;
+
+    if (str.startsWith("/")) start = 1;
+    if (str.endsWith("/")) end = str.length - 1;
+
+    return start === 0 && end === str.length ? str : str.slice(start, end);
+}

package/core/url/qs.ts

@@ -0,0 +1,74 @@
+interface QueryStringOptions {
+    arrayFormat?: "indices" | "repeat";
+    encode?: boolean;
+}
+
+const defaultQsOptions: Required<QueryStringOptions> = {
+    arrayFormat: "indices",
+    encode: true,
+} as const;
+
+function encodeValue(value: unknown, shouldEncode: boolean): string {
+    if (value === undefined) {
+        return "";
+    }
+    if (value === null) {
+        return "";
+    }
+    const stringValue = String(value);
+    return shouldEncode ? encodeURIComponent(stringValue) : stringValue;
+}
+
+function stringifyObject(obj: Record<string, unknown>, prefix = "", options: Required<QueryStringOptions>): string[] {
+    const parts: string[] = [];
+
+    for (const [key, value] of Object.entries(obj)) {
+        const fullKey = prefix ? `${prefix}[${key}]` : key;
+
+        if (value === undefined) {
+            continue;
+        }
+
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                continue;
+            }
+            for (let i = 0; i < value.length; i++) {
+                const item = value[i];
+                if (item === undefined) {
+                    continue;
+                }
+                if (typeof item === "object" && !Array.isArray(item) && item !== null) {
+                    const arrayKey = options.arrayFormat === "indices" ? `${fullKey}[${i}]` : fullKey;
+                    parts.push(...stringifyObject(item as Record<string, unknown>, arrayKey, options));
+                } else {
+                    const arrayKey = options.arrayFormat === "indices" ? `${fullKey}[${i}]` : fullKey;
+                    const encodedKey = options.encode ? encodeURIComponent(arrayKey) : arrayKey;
+                    parts.push(`${encodedKey}=${encodeValue(item, options.encode)}`);
+                }
+            }
+        } else if (typeof value === "object" && value !== null) {
+            if (Object.keys(value as Record<string, unknown>).length === 0) {
+                continue;
+            }
+            parts.push(...stringifyObject(value as Record<string, unknown>, fullKey, options));
+        } else {
+            const encodedKey = options.encode ? encodeURIComponent(fullKey) : fullKey;
+            parts.push(`${encodedKey}=${encodeValue(value, options.encode)}`);
+        }
+    }
+
+    return parts;
+}
+
+export function toQueryString(obj: unknown, options?: QueryStringOptions): string {
+    if (obj == null || typeof obj !== "object") {
+        return "";
+    }
+
+    const parts = stringifyObject(obj as Record<string, unknown>, "", {
+        ...defaultQsOptions,
+        ...options,
+    });
+    return parts.join("&");
+}

package/dist/BaseClient.d.ts

@@ -0,0 +1,25 @@
+import type * as core from "./core/index.js";
+export interface BaseClientOptions {
+    environment: core.Supplier<string>;
+    /** Specify a custom URL to connect the client to. */
+    baseUrl?: core.Supplier<string>;
+    /** Additional headers to include in requests. */
+    headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
+    /** The default maximum time to wait for a response in seconds. */
+    timeoutInSeconds?: number;
+    /** The default number of times to retry the request. Defaults to 2. */
+    maxRetries?: number;
+}
+export interface BaseRequestOptions {
+    /** The maximum time to wait for a response in seconds. */
+    timeoutInSeconds?: number;
+    /** The number of times to retry the request. Defaults to 2. */
+    maxRetries?: number;
+    /** A hook to abort the request. */
+    abortSignal?: AbortSignal;
+    /** Additional query string parameters to include in the request. */
+    queryParams?: Record<string, unknown>;
+    /** Additional headers to include in the request. */
+    headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
+}
+//# sourceMappingURL=BaseClient.d.ts.map