rafay-test-ts-gm 1.22.5

package/src/core/auth/schemes.ts

@@ -0,0 +1,127 @@
+import type { AuthParams, AuthScheme } from "../api-request.js";
+import type { BasicAuthCredentials, TokenProvider } from "./credentials.js";
+import { SdkError } from "../errors.js";
+import * as s from "../validation/index.js";
+
+export const NO_PARAMS: AuthParams = {};
+
+export const noneAuth: AuthScheme = {
+  resolve: () => NO_PARAMS,
+  hasCredentials: () => false,
+};
+
+export function bearerAuth(token: TokenProvider | undefined): AuthScheme {
+  return {
+    async resolve() {
+      const value = await resolveToken(token);
+      return value === undefined ? NO_PARAMS : header("Authorization", `Bearer ${value}`);
+    },
+    hasCredentials: () => hasToken(token),
+  };
+}
+
+export function basicAuth(credentials: BasicAuthCredentials | undefined): AuthScheme {
+  if (credentials !== undefined && credentials.username.includes(":")) {
+    throw new SdkError({
+      message: "A basic-auth username cannot contain a colon (RFC 7617 section 2).",
+    });
+  }
+  return {
+    resolve() {
+      if (credentials === undefined) return NO_PARAMS;
+      return header("Authorization", basicCredential(credentials.username, credentials.password));
+    },
+    hasCredentials: () => credentials !== undefined,
+  };
+}
+
+export function apiKeyHeaderAuth(config: { name: string; token: TokenProvider | undefined }): AuthScheme {
+  return {
+    async resolve() {
+      const value = await resolveToken(config.token);
+      return value === undefined ? NO_PARAMS : header(config.name, value);
+    },
+    hasCredentials: () => hasToken(config.token),
+  };
+}
+
+export function apiKeyQueryAuth(config: { name: string; token: TokenProvider | undefined }): AuthScheme {
+  return {
+    async resolve() {
+      const value = await resolveToken(config.token);
+      if (value === undefined) return NO_PARAMS;
+      return { query: [{ name: config.name, value, schema: s.string() }] };
+    },
+    hasCredentials: () => hasToken(config.token),
+  };
+}
+
+export function apiKeyCookieAuth(config: { name: string; token: TokenProvider | undefined }): AuthScheme {
+  return {
+    async resolve() {
+      const value = await resolveToken(config.token);
+      if (value === undefined) return NO_PARAMS;
+      return { cookies: [{ name: config.name, value, schema: s.string() }] };
+    },
+    hasCredentials: () => hasToken(config.token),
+  };
+}
+
+export function allAuth(...schemes: readonly AuthScheme[]): AuthScheme {
+  return {
+    async resolve(signal) {
+      const parts: AuthParams[] = [];
+      for (const scheme of schemes) parts.push(await scheme.resolve(signal));
+      return {
+        headers: parts.flatMap((part) => part.headers ?? []),
+        query: parts.flatMap((part) => part.query ?? []),
+        cookies: parts.flatMap((part) => part.cookies ?? []),
+      };
+    },
+    hasCredentials: () => schemes.length > 0 && schemes.every((scheme) => scheme.hasCredentials()),
+    invalidate() {
+      for (const scheme of schemes) scheme.invalidate?.();
+    },
+  };
+}
+
+export function anyAuth(...schemes: readonly AuthScheme[]): AuthScheme {
+  return {
+    resolve(signal) {
+      for (const scheme of schemes) {
+        if (scheme.hasCredentials()) return scheme.resolve(signal);
+      }
+      return NO_PARAMS;
+    },
+    hasCredentials: () => schemes.some((scheme) => scheme.hasCredentials()),
+    invalidate() {
+      for (const scheme of schemes) scheme.invalidate?.();
+    },
+  };
+}
+
+export function header(name: string, value: string): AuthParams {
+  return { headers: [{ name, value, schema: s.string() }] };
+}
+
+export function basicCredential(username: string, password: string): string {
+  return `Basic ${base64(new TextEncoder().encode(`${username}:${password}`))}`;
+}
+
+export function base64(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+async function resolveToken(token: TokenProvider | undefined): Promise<string | undefined> {
+  return present(typeof token === "function" ? await token() : token);
+}
+
+function hasToken(token: TokenProvider | undefined): boolean {
+  return typeof token === "function" || present(token) !== undefined;
+}
+
+function present(value: string | undefined): string | undefined {
+  return value !== undefined && value !== "" ? value : undefined;
+}

package/src/core/errors.ts

@@ -0,0 +1,48 @@
+export type ErrorKind = "connection" | "timeout" | "abort" | "sdk" | "schema" | "auth";
+
+export abstract class CoreError extends Error {
+  abstract readonly kind: ErrorKind;
+
+  protected constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+    this.name = new.target.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export type TransportErrorInit = { message: string; cause?: unknown };
+
+export class ConnectionError extends CoreError {
+  readonly kind = "connection" as const;
+  constructor(init: TransportErrorInit) {
+    super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+  }
+}
+
+export class TimeoutError extends CoreError {
+  readonly kind = "timeout" as const;
+  constructor(init: TransportErrorInit) {
+    super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+  }
+}
+
+export class AbortError extends CoreError {
+  readonly kind = "abort" as const;
+  constructor(init: TransportErrorInit) {
+    super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+  }
+}
+
+export class SdkError extends CoreError {
+  readonly kind = "sdk" as const;
+  constructor(init: TransportErrorInit) {
+    super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+  }
+}
+
+export class AuthError extends CoreError {
+  readonly kind = "auth" as const;
+  constructor(init: TransportErrorInit) {
+    super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+  }
+}

package/src/core/headers.ts

@@ -0,0 +1,54 @@
+import type { Param } from "./param-value.js";
+import { encodedParam, flattenValue } from "./param-value.js";
+import { percentEncode } from "./params.js";
+import type { ContentType } from "./request-body.js";
+
+export function buildHeaders(
+  contentType: ContentType | undefined,
+  layers: ReadonlyArray<readonly Param[] | undefined>,
+  cookies?: readonly Param[],
+): Headers {
+  const merged = new Map<string, string | null>();
+  if (contentType !== undefined) merged.set("content-type", contentType);
+  for (const layer of layers) {
+    for (const source of layer ?? []) {
+      const value = encodedParam(source);
+      if (value === undefined) continue;
+      const parts = flattenValue(value);
+      merged.set(source.name.toLowerCase(), parts.length === 0 ? null : parts.join(","));
+    }
+  }
+
+  const cookie = mergeCookies(merged.get("cookie") ?? undefined, cookies);
+  if (cookie !== undefined) merged.set("cookie", cookie);
+
+  const headers = new Headers();
+  for (const [name, value] of merged) {
+    if (value === null) continue;
+    headers.set(name, value);
+  }
+  return headers;
+}
+
+function mergeCookies(
+  existing: string | undefined,
+  cookies: readonly Param[] | undefined,
+): string | undefined {
+  if (cookies === undefined || cookies.length === 0) return existing;
+
+  const pairs = new Map<string, string>();
+  for (const part of (existing ?? "").split(";")) {
+    const trimmed = part.trim();
+    const separator = trimmed.indexOf("=");
+    if (separator <= 0) continue;
+    pairs.set(trimmed.slice(0, separator), trimmed.slice(separator + 1));
+  }
+  for (const source of cookies) {
+    const value = encodedParam(source);
+    if (value === undefined) continue;
+    pairs.set(source.name, flattenValue(value).map(percentEncode).join(","));
+  }
+
+  const merged = [...pairs].map(([name, value]) => `${name}=${value}`).join("; ");
+  return merged === "" ? undefined : merged;
+}

package/src/core/param-value.ts

@@ -0,0 +1,105 @@
+import { SdkError } from "./errors.js";
+import type { Entry } from "./validation/schema.js";
+import { encodeEntry } from "./validation/schema-error.js";
+
+export type ParamStyle = "plain" | "indexed" | "unindexed" | "csv" | "tsv" | "psv";
+
+export type ParamValue =
+  | string
+  | number
+  | boolean
+  | bigint
+  | null
+  | undefined
+  | readonly ParamValue[]
+  | { readonly [key: string]: ParamValue };
+
+export type Param = {
+  readonly name: string;
+  readonly value: unknown;
+  readonly schema: Entry<unknown>;
+};
+
+export type StyledParam = Param & { readonly style?: ParamStyle | undefined };
+
+export type ParamPair = readonly [string, string];
+
+const MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
+
+export function flattenValue(value: ParamValue): string[] {
+  if (value === undefined || value === null) return [];
+  if (isScalar(value)) return [scalar(value)];
+  if (!Array.isArray(value)) return [jsonValue(value)];
+
+  const folded: string[] = [];
+  for (const element of value) {
+    if (element === undefined || element === null) folded.push("");
+    else if (isScalar(element)) folded.push(scalar(element));
+    else return [jsonValue(value)];
+  }
+  return folded;
+}
+
+export function encodedParam(source: Param): ParamValue {
+  return encodeEntry(source.schema, source.value) as ParamValue;
+}
+
+export function flattenParams(sources?: ReadonlyArray<StyledParam>): ParamPair[] {
+  return (sources ?? []).flatMap((source) =>
+    flattenParam(source.name, encodedParam(source), source.style ?? "plain"),
+  );
+}
+
+function flattenParam(key: string, value: ParamValue, style: ParamStyle): ParamPair[] {
+  if (value === undefined || value === null) return [];
+  if (isScalar(value)) return [[key, scalar(value)]];
+  if (Array.isArray(value)) return flattenArray(key, value, style);
+  return Object.entries(value).flatMap(([sub, subValue]) => flattenParam(`${key}[${sub}]`, subValue, style));
+}
+
+function flattenArray(key: string, values: readonly ParamValue[], style: ParamStyle): ParamPair[] {
+  const present = values.filter((value) => value !== undefined && value !== null);
+  switch (style) {
+    case "plain":
+      return present.flatMap((value) => flattenParam(key, value, style));
+    case "indexed":
+      return values.flatMap((value, index) => flattenParam(`${key}[${index}]`, value, style));
+    case "unindexed":
+      return present.flatMap((value) => flattenParam(`${key}[]`, value, style));
+    case "csv":
+      return [joined(key, values, ",")];
+    case "tsv":
+      return [joined(key, values, "\t")];
+    case "psv":
+      return [joined(key, values, "|")];
+    default:
+      return unknownStyle(style);
+  }
+}
+
+function joined(key: string, values: readonly ParamValue[], separator: string): ParamPair {
+  return [key, flattenValue(values).join(separator)];
+}
+
+function unknownStyle(style: never): never {
+  throw new SdkError({ message: `Unknown parameter style: ${String(style)}.` });
+}
+
+export function isScalar(value: ParamValue): value is string | number | boolean | bigint {
+  if (value === undefined || value === null) return false;
+  return typeof value !== "object";
+}
+
+export function scalar(value: string | number | boolean | bigint): string {
+  return String(value);
+}
+
+export function jsonValue(value: ParamValue): string {
+  return JSON.stringify(value, bigintReplacer);
+}
+
+function bigintReplacer(_key: string, value: unknown): unknown {
+  if (typeof value !== "bigint") return value;
+  if (value <= MAX_SAFE_BIGINT && value >= -MAX_SAFE_BIGINT) return Number(value);
+  return String(value);
+}

package/src/core/params.ts

@@ -0,0 +1,28 @@
+import type { ParamPair, StyledParam } from "./param-value.js";
+import { flattenParams } from "./param-value.js";
+
+export function percentEncode(value: string): string {
+  return encodeURIComponent(value).replace(
+    /[!'()*]/g,
+    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+export function formEncode(value: string): string {
+  return percentEncode(value).replace(/%20/g, "+");
+}
+
+export function queryString(
+  layers: ReadonlyArray<readonly StyledParam[] | undefined>,
+  seed: ReadonlyArray<ParamPair> = [],
+): string {
+  return serializePairs([...seed, ...layers.flatMap(flattenParams)], percentEncode);
+}
+
+export function formString(fields?: ReadonlyArray<StyledParam>): string {
+  return serializePairs(flattenParams(fields), formEncode);
+}
+
+function serializePairs(pairs: ReadonlyArray<ParamPair>, encode: (value: string) => string): string {
+  return pairs.map(([key, value]) => `${encode(key)}=${encode(value)}`).join("&");
+}

package/src/core/raw-client.ts

@@ -0,0 +1,128 @@
+import type { ApiRequest, RequestOptions, RawClientOptions, FetchLike } from "./api-request.js";
+import { CoreError, ConnectionError, TimeoutError, AbortError, SdkError } from "./errors.js";
+import { decodeErrorPayload, type AnyResponseError, type ResponseHandler } from "./response-error.js";
+import { decodeResponse } from "./response-decoder.js";
+import { ApiPromise, type RequestOutcome } from "./api-promise.js";
+import { buildBody } from "./request-body.js";
+import { buildUrl } from "./url.js";
+import { buildHeaders } from "./headers.js";
+
+const DEFAULT_TIMEOUT_MS = 100_000;
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
+export class RawClient {
+  readonly #config: RawClientOptions;
+  readonly #fetch: FetchLike;
+
+  constructor(config: RawClientOptions) {
+    const fetchImpl = config.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+      throw new SdkError({ message: "No fetch implementation available; pass ClientOptions.fetch." });
+    }
+    this.#config = config;
+    this.#fetch = fetchImpl;
+  }
+
+  execute<T, E extends AnyResponseError>(
+    apiRequest: ApiRequest,
+    responseHandler: ResponseHandler<T, E>,
+    options?: RequestOptions,
+  ): ApiPromise<T, E> {
+    return new ApiPromise<T, E>(this.#dispatch<T, E>(apiRequest, responseHandler, options?.signal));
+  }
+
+  async #dispatch<T, E extends AnyResponseError>(
+    apiRequest: ApiRequest,
+    responseHandler: ResponseHandler<T, E>,
+    callerSignal: AbortSignal | undefined,
+  ): Promise<RequestOutcome<T, E>> {
+    const timeoutMs = resolveTimeout(this.#config.timeout);
+
+    const controller = new AbortController();
+    const onCallerAbort = (): void =>
+      controller.abort(
+        new AbortError({ message: "Request was aborted by the caller.", cause: callerSignal?.reason }),
+      );
+    callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+    if (callerSignal?.aborted) onCallerAbort();
+    const timer = setTimeout(
+      () => controller.abort(new TimeoutError({ message: `Request timed out after ${timeoutMs}ms.` })),
+      timeoutMs,
+    );
+
+    let response: Response;
+    try {
+      const auth = await apiRequest.auth.resolve(controller.signal);
+
+      const url = buildUrl(
+        apiRequest.url,
+        apiRequest.pathParams,
+        apiRequest.query,
+        this.#config.defaultQuery,
+        this.#config.defaultPathParams,
+        auth.query,
+      );
+      const body = buildBody(apiRequest.body);
+      const headers = buildHeaders(
+        body.contentType,
+        [this.#config.defaultHeaders, apiRequest.headers, auth.headers],
+        auth.cookies,
+      );
+      const init: RequestInit = { method: apiRequest.method, headers, body: body.body };
+
+      response = await this.#fetch.call(undefined, url, {
+        ...init,
+        signal: controller.signal,
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+      if (err instanceof CoreError) throw err;
+      if (controller.signal.aborted) throw controller.signal.reason;
+      throw new ConnectionError({ message: errorMessage(err, "Connection error."), cause: err });
+    }
+
+    if (response.status === 401) apiRequest.auth.invalidate?.();
+
+    const { status, headers: responseHeaders, statusText } = response;
+    try {
+      if (isSuccess(status)) {
+        const data = await decodeResponse(responseHandler.success, response);
+        return { ok: true, status, headers: responseHeaders, data };
+      }
+
+      const payload = await decodeErrorPayload(response, responseHandler.errorFactory.errors, status);
+      const error = new responseHandler.errorFactory({
+        status,
+        headers: responseHeaders,
+        message: statusMessage(status, statusText),
+        payload,
+      });
+
+      return { ok: false, status, headers: responseHeaders, error };
+    } catch (err) {
+      if (err instanceof CoreError) throw err;
+      throw new SdkError({ message: errorMessage(err, "Response handling failed."), cause: err });
+    } finally {
+      clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+    }
+  }
+}
+
+function resolveTimeout(configured: number): number {
+  if (!Number.isFinite(configured) || configured <= 0) return DEFAULT_TIMEOUT_MS;
+  return Math.min(configured, MAX_TIMEOUT_MS);
+}
+
+function isSuccess(status: number): boolean {
+  return status >= 200 && status <= 299;
+}
+
+function statusMessage(status: number, statusText: string): string {
+  return `${status} ${statusText || "HTTP error"}`;
+}
+
+function errorMessage(err: unknown, fallback: string): string {
+  return err instanceof Error && err.message ? err.message : fallback;
+}

package/src/core/request-body.ts

@@ -0,0 +1,82 @@
+import { SdkError } from "./errors.js";
+import type { ParamValue, StyledParam } from "./param-value.js";
+import { isScalar, jsonValue, scalar } from "./param-value.js";
+import { formString } from "./params.js";
+import type { Entry } from "./validation/schema.js";
+import { encodeEntry } from "./validation/schema-error.js";
+
+export type Json = string | number | boolean | null | readonly Json[] | JsonObject;
+
+export type JsonObject = { readonly [key: string]: Json | undefined };
+
+export type ContentType =
+  | "application/x-www-form-urlencoded;charset=UTF-8"
+  | "application/json"
+  | "text/plain;charset=utf-8";
+
+export type BodyContent = {
+  body: string | null;
+  contentType?: ContentType;
+};
+
+export type EmptyBody = {
+  readonly kind: "empty";
+};
+
+export type JsonBody = {
+  readonly kind: "json";
+  readonly value: unknown;
+  readonly schema: Entry<unknown>;
+};
+
+export type FormUrlEncodedBody = {
+  readonly kind: "formUrlEncoded";
+  readonly value: readonly StyledParam[];
+};
+
+export type TextBody = {
+  readonly kind: "text";
+  readonly value: unknown;
+  readonly schema: Entry<unknown>;
+};
+
+export type RequestBody = EmptyBody | JsonBody | FormUrlEncodedBody | TextBody;
+
+export function buildBody(body: RequestBody): BodyContent {
+  switch (body.kind) {
+    case "empty":
+      return { body: null };
+    case "json":
+      return buildJson(body);
+    case "formUrlEncoded":
+      return buildFormUrlEncoded(body);
+    case "text":
+      return buildText(body);
+    default:
+      return unknownBodyKind(body);
+  }
+}
+
+function unknownBodyKind(body: never): never {
+  const kind = (body as { kind?: unknown }).kind;
+  throw new SdkError({ message: `Unsupported request body kind: ${String(kind)}` });
+}
+
+function buildFormUrlEncoded(body: FormUrlEncodedBody): BodyContent {
+  return { body: formString(body.value), contentType: "application/x-www-form-urlencoded;charset=UTF-8" };
+}
+
+function buildJson(body: JsonBody): BodyContent {
+  const text = JSON.stringify(encodeEntry(body.schema, body.value));
+  if (text === undefined) return { body: null };
+  return { body: text, contentType: "application/json" };
+}
+
+function buildText(body: TextBody): BodyContent {
+  const encoded = encodeEntry(body.schema, body.value) as ParamValue;
+  if (encoded === undefined) return { body: null };
+  return {
+    body: isScalar(encoded) ? scalar(encoded) : jsonValue(encoded),
+    contentType: "text/plain;charset=utf-8",
+  };
+}

package/src/core/response-decoder.ts

@@ -0,0 +1,97 @@
+import type { Entry } from "./validation/schema.js";
+import { CoreError, ConnectionError, SdkError } from "./errors.js";
+import { SchemaError, decodeEntry } from "./validation/schema-error.js";
+
+export type JsonResponseDecoder<T> = {
+  readonly kind: "json";
+  readonly schema: Entry<T>;
+};
+
+export type TextResponseDecoder<T> = {
+  readonly kind: "text";
+  readonly schema: Entry<T>;
+};
+
+export type EmptyResponseDecoder = {
+  readonly kind: "empty";
+};
+
+export type ResponseDecoder<T> =
+  | JsonResponseDecoder<T>
+  | TextResponseDecoder<T>
+  | ([T] extends [undefined] ? EmptyResponseDecoder : never);
+
+export type AnyResponseDecoder =
+  | JsonResponseDecoder<unknown>
+  | TextResponseDecoder<unknown>
+  | EmptyResponseDecoder;
+
+export function decodeResponse<T>(decoder: ResponseDecoder<T>, response: Response): Promise<T>;
+export function decodeResponse(decoder: AnyResponseDecoder, response: Response): Promise<unknown>;
+export async function decodeResponse(decoder: AnyResponseDecoder, response: Response): Promise<unknown> {
+  switch (decoder.kind) {
+    case "json":
+      return decodeJson(decoder, response);
+    case "text":
+      return decodeText(decoder, response);
+    case "empty":
+      return decodeEmpty(response);
+    default: {
+      await response.body?.cancel().catch(() => {});
+      return unknownDecoderKind(decoder);
+    }
+  }
+}
+
+async function decodeJson<T>(decoder: JsonResponseDecoder<T>, response: Response): Promise<T> {
+  let text: string;
+  try {
+    text = await response.text();
+  } catch (err) {
+    if (err instanceof CoreError) throw err;
+    throw new ConnectionError({ message: "Response body could not be read.", cause: err });
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new SchemaError({
+      message: "Response body could not be parsed.",
+      rawBody: text,
+      cause: err,
+    });
+  }
+  return decodeEntry(decoder.schema, parsed);
+}
+
+async function decodeText<T>(decoder: TextResponseDecoder<T>, response: Response): Promise<T> {
+  let text: string;
+  try {
+    text = await response.text();
+  } catch (err) {
+    if (err instanceof CoreError) throw err;
+    throw new ConnectionError({ message: "Response body could not be read.", cause: err });
+  }
+  return decodeEntry(decoder.schema, text);
+}
+
+async function decodeEmpty(response: Response): Promise<undefined> {
+  let bytes: ArrayBuffer;
+  try {
+    bytes = await response.arrayBuffer();
+  } catch (err) {
+    if (err instanceof CoreError) throw err;
+    throw new ConnectionError({ message: "Response body could not be read.", cause: err });
+  }
+  if (bytes.byteLength > 0)
+    throw new SchemaError({
+      message: "Expected an empty response body.",
+      rawBody: bytes,
+    });
+  return undefined;
+}
+
+function unknownDecoderKind(decoder: never): never {
+  const kind = (decoder as { kind?: unknown }).kind;
+  throw new SdkError({ message: `Unsupported response decoder kind: ${String(kind)}` });
+}