@speechall/sdk 0.0.1 → 2.0.4

package/src/core/headers.ts

@@ -0,0 +1,35 @@
+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))) {
+        const insensitiveKey = key.toLowerCase();
+        if (value != null) {
+            result[insensitiveKey] = value;
+        } else if (insensitiveKey in result) {
+            delete result[insensitiveKey];
+        }
+    }
+
+    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))) {
+        const insensitiveKey = key.toLowerCase();
+        if (value != null) {
+            result[insensitiveKey] = value;
+        }
+    }
+
+    return result;
+}

package/src/core/index.ts

@@ -0,0 +1,7 @@
+export * from "./auth/index.js";
+export * from "./base64.js";
+export * from "./fetcher/index.js";
+export * as file from "./file/index.js";
+export * as logging from "./logging/index.js";
+export * from "./runtime/index.js";
+export * as url from "./url/index.js";

package/src/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/src/core/logging/exports.ts

@@ -0,0 +1,19 @@
+import * as logger from "./logger.js";
+
+export namespace logging {
+    /**
+     * Configuration for logger instances.
+     */
+    export type LogConfig = logger.LogConfig;
+    export type LogLevel = logger.LogLevel;
+    export const LogLevel: typeof logger.LogLevel = logger.LogLevel;
+    export type ILogger = logger.ILogger;
+    /**
+     * Console logger implementation that outputs to the console.
+     */
+    export type ConsoleLogger = logger.ConsoleLogger;
+    /**
+     * Console logger implementation that outputs to the console.
+     */
+    export const ConsoleLogger: typeof logger.ConsoleLogger = logger.ConsoleLogger;
+}

package/src/core/logging/index.ts

@@ -0,0 +1 @@
+export * from "./logger.js";

package/src/core/logging/logger.ts

@@ -0,0 +1,203 @@
+export const LogLevel = {
+    Debug: "debug",
+    Info: "info",
+    Warn: "warn",
+    Error: "error",
+} as const;
+export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+const logLevelMap: Record<LogLevel, number> = {
+    [LogLevel.Debug]: 1,
+    [LogLevel.Info]: 2,
+    [LogLevel.Warn]: 3,
+    [LogLevel.Error]: 4,
+};
+
+export interface ILogger {
+    /**
+     * Logs a debug message.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Logs an info message.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Logs a warning message.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Logs an error message.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    error(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * Configuration for logger initialization.
+ */
+export interface LogConfig {
+    /**
+     * Minimum log level to output.
+     * @default LogLevel.Info
+     */
+    level?: LogLevel;
+    /**
+     * Logger implementation to use.
+     * @default new ConsoleLogger()
+     */
+    logger?: ILogger;
+    /**
+     * Whether logging should be silenced.
+     * @default true
+     */
+    silent?: boolean;
+}
+
+/**
+ * Default console-based logger implementation.
+ */
+export class ConsoleLogger implements ILogger {
+    debug(message: string, ...args: unknown[]): void {
+        console.debug(message, ...args);
+    }
+    info(message: string, ...args: unknown[]): void {
+        console.info(message, ...args);
+    }
+    warn(message: string, ...args: unknown[]): void {
+        console.warn(message, ...args);
+    }
+    error(message: string, ...args: unknown[]): void {
+        console.error(message, ...args);
+    }
+}
+
+/**
+ * Logger class that provides level-based logging functionality.
+ */
+export class Logger {
+    private readonly level: number;
+    private readonly logger: ILogger;
+    private readonly silent: boolean;
+
+    /**
+     * Creates a new logger instance.
+     * @param config - Logger configuration
+     */
+    constructor(config: Required<LogConfig>) {
+        this.level = logLevelMap[config.level];
+        this.logger = config.logger;
+        this.silent = config.silent;
+    }
+
+    /**
+     * Checks if a log level should be output based on configuration.
+     * @param level - The log level to check
+     * @returns True if the level should be logged
+     */
+    public shouldLog(level: LogLevel): boolean {
+        return !this.silent && this.level <= logLevelMap[level];
+    }
+
+    /**
+     * Checks if debug logging is enabled.
+     * @returns True if debug logs should be output
+     */
+    public isDebug(): boolean {
+        return this.shouldLog(LogLevel.Debug);
+    }
+
+    /**
+     * Logs a debug message if debug logging is enabled.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    public debug(message: string, ...args: unknown[]): void {
+        if (this.isDebug()) {
+            this.logger.debug(message, ...args);
+        }
+    }
+
+    /**
+     * Checks if info logging is enabled.
+     * @returns True if info logs should be output
+     */
+    public isInfo(): boolean {
+        return this.shouldLog(LogLevel.Info);
+    }
+
+    /**
+     * Logs an info message if info logging is enabled.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    public info(message: string, ...args: unknown[]): void {
+        if (this.isInfo()) {
+            this.logger.info(message, ...args);
+        }
+    }
+
+    /**
+     * Checks if warning logging is enabled.
+     * @returns True if warning logs should be output
+     */
+    public isWarn(): boolean {
+        return this.shouldLog(LogLevel.Warn);
+    }
+
+    /**
+     * Logs a warning message if warning logging is enabled.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    public warn(message: string, ...args: unknown[]): void {
+        if (this.isWarn()) {
+            this.logger.warn(message, ...args);
+        }
+    }
+
+    /**
+     * Checks if error logging is enabled.
+     * @returns True if error logs should be output
+     */
+    public isError(): boolean {
+        return this.shouldLog(LogLevel.Error);
+    }
+
+    /**
+     * Logs an error message if error logging is enabled.
+     * @param message - The message to log
+     * @param args - Additional arguments to log
+     */
+    public error(message: string, ...args: unknown[]): void {
+        if (this.isError()) {
+            this.logger.error(message, ...args);
+        }
+    }
+}
+
+export function createLogger(config?: LogConfig | Logger): Logger {
+    if (config == null) {
+        return defaultLogger;
+    }
+    if (config instanceof Logger) {
+        return config;
+    }
+    config = config ?? {};
+    config.level ??= LogLevel.Info;
+    config.logger ??= new ConsoleLogger();
+    config.silent ??= true;
+    return new Logger(config as Required<LogConfig>);
+}
+
+const defaultLogger: Logger = new Logger({
+    level: LogLevel.Info,
+    logger: new ConsoleLogger(),
+    silent: true,
+});

package/src/core/runtime/index.ts

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

package/src/core/runtime/runtime.ts

@@ -0,0 +1,134 @@
+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 in React-Native.
+     * This check should come before Node.js detection since React Native may have a process polyfill.
+     * 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",
+        };
+    }
+
+    /**
+     * 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]),
+        };
+    }
+
+    return {
+        type: "unknown",
+    };
+}

package/src/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/src/core/url/index.ts

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

package/src/core/url/join.ts

@@ -0,0 +1,79 @@
+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 {
+            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/src/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/src/environments.ts

@@ -0,0 +1,7 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export const SpeechallEnvironment = {
+    Default: "https://api.speechall.com/v1",
+} as const;
+
+export type SpeechallEnvironment = typeof SpeechallEnvironment.Default;

package/src/errors/SpeechallError.ts

@@ -0,0 +1,58 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as core from "../core/index.js";
+import { toJson } from "../core/json.js";
+
+export class SpeechallError extends Error {
+    public readonly statusCode?: number;
+    public readonly body?: unknown;
+    public readonly rawResponse?: core.RawResponse;
+
+    constructor({
+        message,
+        statusCode,
+        body,
+        rawResponse,
+    }: {
+        message?: string;
+        statusCode?: number;
+        body?: unknown;
+        rawResponse?: core.RawResponse;
+    }) {
+        super(buildMessage({ message, statusCode, body }));
+        Object.setPrototypeOf(this, new.target.prototype);
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+
+        this.name = this.constructor.name;
+        this.statusCode = statusCode;
+        this.body = body;
+        this.rawResponse = rawResponse;
+    }
+}
+
+function buildMessage({
+    message,
+    statusCode,
+    body,
+}: {
+    message: string | undefined;
+    statusCode: number | undefined;
+    body: unknown | undefined;
+}): string {
+    const lines: string[] = [];
+    if (message != null) {
+        lines.push(message);
+    }
+
+    if (statusCode != null) {
+        lines.push(`Status code: ${statusCode.toString()}`);
+    }
+
+    if (body != null) {
+        lines.push(`Body: ${toJson(body, undefined, 2)}`);
+    }
+
+    return lines.join("\n");
+}

package/src/errors/SpeechallTimeoutError.ts

@@ -0,0 +1,13 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export class SpeechallTimeoutError extends Error {
+    constructor(message: string) {
+        super(message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+
+        this.name = this.constructor.name;
+    }
+}