rafay-test-ts-gm 1.22.5

package/src/client.ts

@@ -0,0 +1,80 @@
+import { buildAuthSchemes, type AuthSchemes } from "./auth-schemes.js";
+import { DEFAULT_CLIENT_OPTIONS, type ClientOptions } from "./client-options.js";
+import { RawClient } from "./core/raw-client.js";
+import { DirectionsApi } from "./resources/directions-api.js";
+import { DistanceMatrixApi } from "./resources/distance-matrix-api.js";
+import { ElevationApi } from "./resources/elevation-api.js";
+import { GeocodingApi } from "./resources/geocoding-api.js";
+import { GeolocationApi } from "./resources/geolocation-api.js";
+import { PlacesApi } from "./resources/places-api.js";
+import { RoadsApi } from "./resources/roads-api.js";
+import { StreetViewApi } from "./resources/street-view-api.js";
+import { TimeZoneApi } from "./resources/time-zone-api.js";
+import { buildServers, type Servers } from "./servers.js";
+
+export class GoogleMapsPlatformClient {
+  readonly #rawClient: RawClient;
+  readonly #servers: Servers;
+  readonly #auth: AuthSchemes;
+  #geolocationApi?: GeolocationApi;
+  #directionsApi?: DirectionsApi;
+  #elevationApi?: ElevationApi;
+  #geocodingApi?: GeocodingApi;
+  #timeZoneApi?: TimeZoneApi;
+  #roadsApi?: RoadsApi;
+  #distanceMatrixApi?: DistanceMatrixApi;
+  #placesApi?: PlacesApi;
+  #streetViewApi?: StreetViewApi;
+
+  constructor(clientOptions: Partial<ClientOptions> = {}) {
+    const options = { ...DEFAULT_CLIENT_OPTIONS, ...clientOptions };
+
+    this.#rawClient = new RawClient({
+      timeout: options.timeout,
+      defaultHeaders: [],
+      defaultQuery: [],
+      defaultPathParams: [],
+      fetch: options.fetch,
+    });
+
+    this.#servers = buildServers(options.serverEnvironment, options.serverOptions);
+
+    this.#auth = buildAuthSchemes(options);
+  }
+
+  get geolocationApi(): GeolocationApi {
+    return (this.#geolocationApi ??= new GeolocationApi(this.#rawClient, this.#servers, this.#auth));
+  }
+
+  get directionsApi(): DirectionsApi {
+    return (this.#directionsApi ??= new DirectionsApi(this.#rawClient, this.#servers, this.#auth));
+  }
+
+  get elevationApi(): ElevationApi {
+    return (this.#elevationApi ??= new ElevationApi(this.#rawClient, this.#servers, this.#auth));
+  }
+
+  get geocodingApi(): GeocodingApi {
+    return (this.#geocodingApi ??= new GeocodingApi(this.#rawClient, this.#servers, this.#auth));
+  }
+
+  get timeZoneApi(): TimeZoneApi {
+    return (this.#timeZoneApi ??= new TimeZoneApi(this.#rawClient, this.#servers, this.#auth));
+  }
+
+  get roadsApi(): RoadsApi {
+    return (this.#roadsApi ??= new RoadsApi(this.#rawClient, this.#servers, this.#auth));
+  }
+
+  get distanceMatrixApi(): DistanceMatrixApi {
+    return (this.#distanceMatrixApi ??= new DistanceMatrixApi(this.#rawClient, this.#servers, this.#auth));
+  }
+
+  get placesApi(): PlacesApi {
+    return (this.#placesApi ??= new PlacesApi(this.#rawClient, this.#servers, this.#auth));
+  }
+
+  get streetViewApi(): StreetViewApi {
+    return (this.#streetViewApi ??= new StreetViewApi(this.#rawClient, this.#servers, this.#auth));
+  }
+}

package/src/core/api-promise.ts

@@ -0,0 +1,44 @@
+import type { AnyResponseError, PayloadOf } from "./response-error.js";
+
+export type RequestOutcome<T, E extends AnyResponseError> =
+  | { ok: true; status: number; headers: Headers; data: T }
+  | { ok: false; status: number; headers: Headers; error: E };
+
+export type ApiResult<T, E extends AnyResponseError> =
+  | { ok: true; status: number; headers: Headers; value: T }
+  | { ok: false; status: number; headers: Headers; errorMessage: string; error: PayloadOf<E> };
+
+export class ApiPromise<T, E extends AnyResponseError> extends Promise<T> {
+  readonly #outcome: Promise<RequestOutcome<T, E>>;
+
+  constructor(outcome: Promise<RequestOutcome<T, E>>) {
+    super((resolve, reject) => {
+      outcome.then((o) => (o.ok ? resolve(o.data) : reject(o.error)), reject);
+    });
+    this.#outcome = outcome;
+
+    this.catch(() => {});
+  }
+
+  static override get [Symbol.species](): PromiseConstructor {
+    return Promise;
+  }
+
+  async asApiResult(): Promise<ApiResult<T, E>> {
+    const o = await this.#outcome;
+    return o.ok
+      ? {
+          ok: true,
+          value: o.data,
+          status: o.status,
+          headers: o.headers,
+        }
+      : {
+          ok: false,
+          error: o.error.payload as PayloadOf<E>,
+          errorMessage: o.error.message,
+          status: o.error.status,
+          headers: o.headers,
+        };
+  }
+}

package/src/core/api-request.ts

@@ -0,0 +1,46 @@
+import type { RequestBody } from "./request-body.js";
+import type { StyledParam, Param } from "./param-value.js";
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+
+export type FetchLike = typeof fetch;
+
+export type RequestOptions = {
+  signal?: AbortSignal;
+};
+
+export type RawClientOptions = {
+  readonly timeout: number;
+  readonly defaultHeaders: readonly Param[];
+  readonly defaultQuery: readonly StyledParam[];
+  readonly defaultPathParams: readonly Param[];
+  readonly fetch?: FetchLike | undefined;
+};
+
+export type UrlTemplate = {
+  baseUrl: string;
+  subPath: string;
+  variables?: Record<string, string> | undefined;
+};
+
+export type AuthParams = {
+  readonly headers?: readonly Param[];
+  readonly query?: readonly StyledParam[];
+  readonly cookies?: readonly Param[];
+};
+
+export type AuthScheme = {
+  resolve(signal: AbortSignal): Promise<AuthParams> | AuthParams;
+  hasCredentials(): boolean;
+  invalidate?(): void;
+};
+
+export type ApiRequest = {
+  method: HttpMethod;
+  url: UrlTemplate;
+  auth: AuthScheme;
+  pathParams?: Param[] | undefined;
+  query?: StyledParam[] | undefined;
+  headers?: Param[] | undefined;
+  body: RequestBody;
+};

package/src/core/auth/credentials.ts

@@ -0,0 +1,38 @@
+export type TokenProvider = string | (() => string | Promise<string>);
+
+export type BasicAuthCredentials = {
+  readonly username: string;
+  readonly password: string;
+};
+
+export type OAuth2ClientCredentials = {
+  readonly clientId: string;
+  readonly clientSecret: string;
+  readonly scope?: string | undefined;
+};
+
+export type OAuth2PasswordCredentials = {
+  readonly clientId: string;
+  readonly clientSecret?: string | undefined;
+  readonly username: string;
+  readonly password: string;
+  readonly scope?: string | undefined;
+};
+
+export const PkceMethod = {
+  S256: "S256",
+  Plain: "plain",
+} as const;
+export type PkceMethod = (typeof PkceMethod)[keyof typeof PkceMethod];
+
+export type AuthorizationCodePrompt = (authorizationUrl: string, signal: AbortSignal) => Promise<string>;
+
+export type OAuth2AuthorizationCodeCredentials = {
+  readonly clientId: string;
+  readonly clientSecret?: string | undefined;
+  readonly redirectUri: string;
+  readonly scope?: string | undefined;
+  readonly state?: string | undefined;
+  readonly pkce?: PkceMethod | null | undefined;
+  readonly promptForAuthorizationCode: AuthorizationCodePrompt;
+};

package/src/core/auth/oauth2-schemes.ts

@@ -0,0 +1,114 @@
+import type { AuthScheme } from "../api-request.js";
+import type {
+  OAuth2RefreshableTokenStrategy,
+  OAuth2TokenStrategy,
+  OAuthToken,
+  OAuthTokenRefreshable,
+} from "./oauth2-strategies.js";
+import { NO_PARAMS, header } from "./schemes.js";
+
+const EXPIRY_BUFFER_MS = 30_000;
+
+export function oauth2Scheme<TCredentials>(
+  credentials: TCredentials | undefined,
+  strategy: OAuth2TokenStrategy<TCredentials>,
+): AuthScheme {
+  let cached: { token: string; expiresAt: number } | undefined;
+  let inflight: Promise<string> | undefined;
+
+  const acquire = (present: TCredentials, signal: AbortSignal): Promise<string> => {
+    if (inflight !== undefined) return inflight;
+
+    const run = strategy
+      .getToken(present, signal)
+      .then((token) => {
+        cached = { token: token.accessToken, expiresAt: expiryOf(token) };
+        return cached.token;
+      })
+      .finally(() => {
+        inflight = undefined;
+      });
+    inflight = run;
+    return run;
+  };
+
+  return {
+    async resolve(signal) {
+      if (credentials === undefined) return NO_PARAMS;
+
+      const current = cached;
+      if (current !== undefined && Date.now() < current.expiresAt) {
+        return header("Authorization", `Bearer ${current.token}`);
+      }
+
+      const token = await acquire(credentials, signal);
+      return header("Authorization", `Bearer ${token}`);
+    },
+    hasCredentials: () => credentials !== undefined,
+    invalidate: () => {
+      cached = undefined;
+    },
+  };
+}
+
+export function oauth2RefreshableScheme<TCredentials>(
+  credentials: TCredentials | undefined,
+  strategy: OAuth2RefreshableTokenStrategy<TCredentials>,
+): AuthScheme {
+  let cached: { token: OAuthTokenRefreshable; expiresAt: number } | undefined;
+  let inflight: Promise<OAuthTokenRefreshable> | undefined;
+
+  const acquire = (present: TCredentials, signal: AbortSignal): Promise<OAuthTokenRefreshable> => {
+    if (inflight !== undefined) return inflight;
+
+    const stale = cached?.token.refreshToken;
+    const run = renew(strategy, present, stale, signal)
+      .then((token) => {
+        cached = { token, expiresAt: expiryOf(token) };
+        return token;
+      })
+      .finally(() => {
+        inflight = undefined;
+      });
+    inflight = run;
+    return run;
+  };
+
+  return {
+    async resolve(signal) {
+      if (credentials === undefined) return NO_PARAMS;
+
+      const current = cached;
+      if (current !== undefined && Date.now() < current.expiresAt) {
+        return header("Authorization", `Bearer ${current.token.accessToken}`);
+      }
+
+      const token = await acquire(credentials, signal);
+      return header("Authorization", `Bearer ${token.accessToken}`);
+    },
+    hasCredentials: () => credentials !== undefined,
+    invalidate: () => {
+      cached = undefined;
+    },
+  };
+}
+
+function expiryOf(token: OAuthToken): number {
+  if (token.expiresIn === undefined || token.expiresIn <= 0) return Number.POSITIVE_INFINITY;
+  return Date.now() + token.expiresIn * 1000 - EXPIRY_BUFFER_MS;
+}
+
+async function renew<TCredentials>(
+  strategy: OAuth2RefreshableTokenStrategy<TCredentials>,
+  credentials: TCredentials,
+  refreshToken: string | undefined,
+  signal: AbortSignal,
+): Promise<OAuthTokenRefreshable> {
+  if (refreshToken !== undefined) {
+    const refreshed = await strategy.tryRefreshToken(credentials, refreshToken, signal);
+    if (refreshed !== null) {
+      return refreshed.refreshToken === undefined ? { ...refreshed, refreshToken } : refreshed;
+    }
+  }
+  return strategy.getToken(credentials, signal);
+}

package/src/core/auth/oauth2-strategies.ts

@@ -0,0 +1,298 @@
+import type { UrlTemplate } from "../api-request.js";
+import type { Param, StyledParam } from "../param-value.js";
+import type { RawClient } from "../raw-client.js";
+import type { Entry, Schema } from "../validation/schema.js";
+import type {
+  OAuth2AuthorizationCodeCredentials,
+  OAuth2ClientCredentials,
+  OAuth2PasswordCredentials,
+} from "./credentials.js";
+import { PkceMethod } from "./credentials.js";
+import { base64, basicCredential, noneAuth } from "./schemes.js";
+import { AuthError, CoreError } from "../errors.js";
+import { ResponseError } from "../response-error.js";
+import { buildUrl } from "../url.js";
+import * as s from "../validation/index.js";
+
+export type OAuthToken = {
+  accessToken: string;
+  tokenType: string;
+  expiresIn?: number;
+  scope?: string;
+};
+
+export const oauthTokenSchema: Schema<OAuthToken> = s.object<OAuthToken>({
+  accessToken: s.string(),
+  tokenType: s.string(),
+  expiresIn: s.optional(s.number()),
+  scope: s.optional(s.string()),
+  _keysMap: {
+    accessToken: "access_token",
+    tokenType: "token_type",
+    expiresIn: "expires_in",
+  },
+});
+
+export type OAuthTokenRefreshable = OAuthToken & {
+  refreshToken?: string;
+};
+
+export const oauthTokenRefreshableSchema: Schema<OAuthTokenRefreshable> = s.object<OAuthTokenRefreshable>({
+  accessToken: s.string(),
+  tokenType: s.string(),
+  expiresIn: s.optional(s.number()),
+  scope: s.optional(s.string()),
+  refreshToken: s.optional(s.string()),
+  _keysMap: {
+    accessToken: "access_token",
+    tokenType: "token_type",
+    expiresIn: "expires_in",
+    refreshToken: "refresh_token",
+  },
+});
+
+export type OAuth2TokenStrategy<TCredentials> = {
+  getToken(credentials: TCredentials, signal: AbortSignal): Promise<OAuthToken>;
+};
+
+export type OAuth2RefreshableTokenStrategy<TCredentials> = {
+  getToken(credentials: TCredentials, signal: AbortSignal): Promise<OAuthTokenRefreshable>;
+  tryRefreshToken(
+    credentials: TCredentials,
+    refreshToken: string,
+    signal: AbortSignal,
+  ): Promise<OAuthTokenRefreshable | null>;
+};
+
+export type OAuth2CredentialPlacement = "header" | "body";
+
+export function oauth2ClientCredentialsStrategy(config: {
+  tokenUrl: UrlTemplate;
+  rawClient: RawClient;
+  placement?: OAuth2CredentialPlacement;
+}): OAuth2TokenStrategy<OAuth2ClientCredentials> {
+  return {
+    getToken(credentials, signal) {
+      const placed = placeCredentials(
+        config.placement ?? "header",
+        credentials.clientId,
+        credentials.clientSecret,
+      );
+      return requestToken(
+        config,
+        oauthTokenSchema,
+        placed.headers,
+        [
+          { name: "grant_type", value: "client_credentials", schema: s.string() },
+          ...scopeField(credentials.scope),
+          ...placed.fields,
+        ],
+        signal,
+      );
+    },
+  };
+}
+
+export function oauth2PasswordStrategy(config: {
+  tokenUrl: UrlTemplate;
+  rawClient: RawClient;
+  placement?: OAuth2CredentialPlacement;
+}): OAuth2TokenStrategy<OAuth2PasswordCredentials> {
+  return {
+    getToken(credentials, signal) {
+      const placed = placeCredentials(
+        config.placement ?? "header",
+        credentials.clientId,
+        credentials.clientSecret,
+      );
+      return requestToken(
+        config,
+        oauthTokenSchema,
+        placed.headers,
+        [
+          { name: "grant_type", value: "password", schema: s.string() },
+          { name: "username", value: credentials.username, schema: s.string() },
+          { name: "password", value: credentials.password, schema: s.string() },
+          ...scopeField(credentials.scope),
+          ...placed.fields,
+        ],
+        signal,
+      );
+    },
+  };
+}
+
+export function oauth2AuthorizationCodeStrategy(config: {
+  authorizationUrl: UrlTemplate;
+  tokenUrl: UrlTemplate;
+  rawClient: RawClient;
+  placement?: OAuth2CredentialPlacement;
+}): OAuth2RefreshableTokenStrategy<OAuth2AuthorizationCodeCredentials> {
+  const placementOf = (
+    credentials: OAuth2AuthorizationCodeCredentials,
+  ): { headers: Param[]; fields: StyledParam[] } =>
+    placeCredentials(config.placement ?? "header", credentials.clientId, credentials.clientSecret);
+
+  return {
+    async getToken(credentials, signal) {
+      const method = credentials.pkce === undefined ? PkceMethod.S256 : credentials.pkce;
+      if (method === null && (credentials.clientSecret === undefined || credentials.clientSecret === "")) {
+        throw new AuthError({
+          message:
+            "A client secret is required when PKCE is disabled. Set pkce to PkceMethod.S256 for a public client.",
+        });
+      }
+
+      const pkce = method === null ? undefined : await generatePkce(method);
+      const authorizationUrl = buildUrl(
+        config.authorizationUrl,
+        undefined,
+        authorizationFields(credentials, pkce),
+        [],
+      ).href;
+      const code = await credentials.promptForAuthorizationCode(authorizationUrl, signal);
+      const placed = placementOf(credentials);
+
+      return requestToken(
+        config,
+        oauthTokenRefreshableSchema,
+        placed.headers,
+        [
+          { name: "grant_type", value: "authorization_code", schema: s.string() },
+          { name: "code", value: code, schema: s.string() },
+          { name: "redirect_uri", value: credentials.redirectUri, schema: s.string() },
+          ...(pkce === undefined
+            ? []
+            : [{ name: "code_verifier", value: pkce.verifier, schema: s.string() }]),
+          ...placed.fields,
+        ],
+        signal,
+      );
+    },
+
+    async tryRefreshToken(credentials, refreshToken, signal) {
+      const placed = placementOf(credentials);
+      const outcome = await config.rawClient
+        .execute<OAuthTokenRefreshable, ResponseError>(
+          {
+            method: "POST",
+            url: config.tokenUrl,
+            auth: noneAuth,
+            headers: placed.headers,
+            body: {
+              kind: "formUrlEncoded",
+              value: [
+                { name: "grant_type", value: "refresh_token", schema: s.string() },
+                { name: "refresh_token", value: refreshToken, schema: s.string() },
+                ...placed.fields,
+              ],
+            },
+          },
+          {
+            success: { kind: "json", schema: oauthTokenRefreshableSchema },
+            errorFactory: ResponseError,
+          },
+          { signal },
+        )
+        .asApiResult();
+
+      return outcome.ok ? outcome.value : null;
+    },
+  };
+}
+
+function scopeField(scope: string | undefined): StyledParam[] {
+  if (scope === undefined || scope === "") return [];
+  return [{ name: "scope", value: scope, schema: s.string() }];
+}
+
+function placeCredentials(
+  placement: OAuth2CredentialPlacement,
+  clientId: string,
+  clientSecret: string | undefined,
+): { headers: Param[]; fields: StyledParam[] } {
+  if (placement === "header") {
+    return {
+      headers: [
+        {
+          name: "Authorization",
+          value: basicCredential(clientId, clientSecret ?? ""),
+          schema: s.string(),
+        },
+      ],
+      fields: [],
+    };
+  }
+
+  const fields: StyledParam[] = [{ name: "client_id", value: clientId, schema: s.string() }];
+  if (clientSecret !== undefined) {
+    fields.push({ name: "client_secret", value: clientSecret, schema: s.string() });
+  }
+  return { headers: [], fields };
+}
+
+async function requestToken<T>(
+  config: { tokenUrl: UrlTemplate; rawClient: RawClient },
+  schema: Entry<T>,
+  headers: readonly Param[],
+  fields: readonly StyledParam[],
+  signal: AbortSignal,
+): Promise<T> {
+  try {
+    return await config.rawClient.execute<T, ResponseError>(
+      {
+        method: "POST",
+        url: config.tokenUrl,
+        auth: noneAuth,
+        headers: [...headers],
+        body: { kind: "formUrlEncoded", value: [...fields] },
+      },
+      {
+        success: { kind: "json", schema },
+        errorFactory: ResponseError,
+      },
+      { signal },
+    );
+  } catch (err) {
+    if (err instanceof CoreError) throw err;
+    throw new AuthError({ message: "The OAuth2 token request failed.", cause: err });
+  }
+}
+
+function authorizationFields(
+  credentials: OAuth2AuthorizationCodeCredentials,
+  pkce: PkceValues | undefined,
+): StyledParam[] {
+  const fields: StyledParam[] = [
+    { name: "response_type", value: "code", schema: s.string() },
+    { name: "client_id", value: credentials.clientId, schema: s.string() },
+    { name: "redirect_uri", value: credentials.redirectUri, schema: s.string() },
+    ...scopeField(credentials.scope),
+  ];
+  if (credentials.state !== undefined && credentials.state !== "") {
+    fields.push({ name: "state", value: credentials.state, schema: s.string() });
+  }
+  if (pkce !== undefined) {
+    fields.push(
+      { name: "code_challenge", value: pkce.challenge, schema: s.string() },
+      { name: "code_challenge_method", value: pkce.method, schema: s.string() },
+    );
+  }
+  return fields;
+}
+
+type PkceValues = { verifier: string; challenge: string; method: PkceMethod };
+
+async function generatePkce(method: PkceMethod): Promise<PkceValues> {
+  const entropy = new Uint8Array(32);
+  crypto.getRandomValues(entropy);
+  const verifier = base64Url(entropy);
+  if (method === PkceMethod.Plain) return { verifier, challenge: verifier, method };
+
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return { verifier, challenge: base64Url(new Uint8Array(digest)), method };
+}
+
+function base64Url(bytes: Uint8Array): string {
+  return base64(bytes).replace(/=+$/, "").replaceAll("+", "-").replaceAll("/", "_");
+}