@sphereon/oid4vci-common 0.4.1-next.285

package/lib/functions/CredentialOfferUtil.ts

@@ -0,0 +1,338 @@
+import {
+  AssertedUniformCredentialOffer,
+  AuthzFlowType,
+  CredentialOffer,
+  CredentialOfferPayload,
+  CredentialOfferPayloadV1_0_08,
+  CredentialOfferPayloadV1_0_09,
+  CredentialOfferPayloadV1_0_11,
+  DefaultURISchemes,
+  Grant,
+  GrantTypes,
+  OpenId4VCIVersion,
+  OpenIDResponse,
+  UniformCredentialOffer,
+  UniformCredentialOfferPayload,
+  UniformCredentialOfferRequest,
+} from '../types';
+
+import { getJson } from './HttpUtils';
+
+export function determineSpecVersionFromURI(uri: string): OpenId4VCIVersion {
+  let version: OpenId4VCIVersion = OpenId4VCIVersion.VER_UNKNOWN;
+
+  version = determineSpecVersionFromScheme(uri, version);
+  version = getVersionFromURIParam(uri, version, OpenId4VCIVersion.VER_1_0_08, 'initiate_issuance');
+  version = getVersionFromURIParam(uri, version, OpenId4VCIVersion.VER_1_0_08, 'credential_type');
+  version = getVersionFromURIParam(uri, version, OpenId4VCIVersion.VER_1_0_08, 'op_state');
+
+  // version = getVersionFromURIParam(uri, version, OpenId4VCIVersion.VER_1_0_09, 'credentials');
+  // version = getVersionFromURIParam(uri, version, OpenId4VCIVersion.VER_1_0_09, 'initiate_issuance_uri')
+
+  version = getVersionFromURIParam(uri, version, OpenId4VCIVersion.VER_1_0_11, 'credential_offer_uri=');
+  version = getVersionFromURIParam(uri, version, OpenId4VCIVersion.VER_1_0_11, 'credential_issuer');
+  version = getVersionFromURIParam(uri, version, OpenId4VCIVersion.VER_1_0_11, 'grants');
+
+  if (version === OpenId4VCIVersion.VER_UNKNOWN) {
+    version = OpenId4VCIVersion.VER_1_0_11;
+  }
+  return version;
+}
+
+export function determineSpecVersionFromScheme(credentialOfferURI: string, openId4VCIVersion: OpenId4VCIVersion) {
+  const scheme = getScheme(credentialOfferURI);
+  if (credentialOfferURI.includes(DefaultURISchemes.INITIATE_ISSUANCE)) {
+    return recordVersion(openId4VCIVersion, OpenId4VCIVersion.VER_1_0_08, scheme);
+  } else if (credentialOfferURI.includes(DefaultURISchemes.CREDENTIAL_OFFER)) {
+    return recordVersion(openId4VCIVersion, OpenId4VCIVersion.VER_1_0_11, scheme);
+  } else {
+    return recordVersion(openId4VCIVersion, OpenId4VCIVersion.VER_UNKNOWN, scheme);
+  }
+}
+
+export function getScheme(credentialOfferURI: string) {
+  if (!credentialOfferURI || !credentialOfferURI.includes('://')) {
+    throw Error('Invalid credential offer URI');
+  }
+  return credentialOfferURI.split('://')[0];
+}
+
+export function getIssuerFromCredentialOfferPayload(request: CredentialOfferPayload): string | undefined {
+  if (!request || (!('issuer' in request) && !('credential_issuer' in request))) {
+    return undefined;
+  }
+  return 'issuer' in request ? request.issuer : request['credential_issuer'];
+}
+
+export function determineSpecVersionFromOffer(offer: CredentialOfferPayload | CredentialOffer): OpenId4VCIVersion {
+  if (isCredentialOfferV1_0_11(offer)) {
+    return OpenId4VCIVersion.VER_1_0_11;
+  } else if (isCredentialOfferV1_0_09(offer)) {
+    return OpenId4VCIVersion.VER_1_0_09;
+  } else if (isCredentialOfferV1_0_08(offer)) {
+    return OpenId4VCIVersion.VER_1_0_08;
+  }
+  return OpenId4VCIVersion.VER_UNKNOWN;
+}
+
+export function isCredentialOfferVersion(offer: CredentialOfferPayload | CredentialOffer, min: OpenId4VCIVersion, max?: OpenId4VCIVersion) {
+  if (max && max.valueOf() < min.valueOf()) {
+    throw Error(`Cannot have a max ${max.valueOf()} version smaller than the min version ${min.valueOf()}`);
+  }
+  const version = determineSpecVersionFromOffer(offer);
+  if (version.valueOf() < min.valueOf()) {
+    console.log(`Credential offer version (${version.valueOf()}) is lower than minimum required version (${min.valueOf()})`);
+    return false;
+  } else if (max && version.valueOf() > max.valueOf()) {
+    console.log(`Credential offer version (${version.valueOf()}) is higher than maximum required version (${max.valueOf()})`);
+    return false;
+  }
+  return true;
+}
+
+function isCredentialOfferV1_0_08(offer: CredentialOfferPayload | CredentialOffer): boolean {
+  if (!offer) {
+    return false;
+  }
+  if ('issuer' in offer && 'credential_type' in offer) {
+    // payload
+    return true;
+  }
+  if ('credential_offer' in offer && offer['credential_offer']) {
+    // offer, so check payload
+    return isCredentialOfferV1_0_08(offer['credential_offer']);
+  }
+  return false;
+}
+
+function isCredentialOfferV1_0_09(offer: CredentialOfferPayload | CredentialOffer): boolean {
+  if (!offer) {
+    return false;
+  }
+  if ('issuer' in offer && 'credentials' in offer) {
+    // payload
+    return true;
+  }
+  if ('credential_offer' in offer && offer['credential_offer']) {
+    // offer, so check payload
+    return isCredentialOfferV1_0_09(offer['credential_offer']);
+  }
+  return false;
+}
+
+function isCredentialOfferV1_0_11(offer: CredentialOfferPayload | CredentialOffer): boolean {
+  if (!offer) {
+    return false;
+  }
+  if ('credential_issuer' in offer && 'credentials' in offer) {
+    // payload
+    return true;
+  }
+  if ('credential_offer' in offer && offer['credential_offer']) {
+    // offer, so check payload
+    return isCredentialOfferV1_0_11(offer['credential_offer']);
+  }
+  return 'credential_offer_uri' in offer;
+}
+
+export async function toUniformCredentialOfferRequest(
+  offer: CredentialOffer,
+  opts?: {
+    resolve?: boolean;
+    version?: OpenId4VCIVersion;
+  }
+): Promise<UniformCredentialOfferRequest> {
+  const version = opts?.version ?? determineSpecVersionFromOffer(offer);
+  let originalCredentialOffer = offer.credential_offer;
+  let credentialOfferURI: string | undefined;
+  if ('credential_offer_uri' in offer && offer?.credential_offer_uri !== undefined) {
+    credentialOfferURI = offer.credential_offer_uri;
+    if (opts?.resolve || opts?.resolve === undefined) {
+      originalCredentialOffer = (await resolveCredentialOfferURI(credentialOfferURI)) as CredentialOfferPayloadV1_0_11;
+    } else if (!originalCredentialOffer) {
+      throw Error(`Credential offer uri (${credentialOfferURI}) found, but resolution was explicitly disabled and credential_offer was supplied`);
+    }
+  }
+  if (!originalCredentialOffer) {
+    throw Error('No credential offer available');
+  }
+  const payload = toUniformCredentialOfferPayload(originalCredentialOffer, opts);
+  const supportedFlows = determineFlowType(payload, version);
+  return {
+    credential_offer: payload,
+    original_credential_offer: originalCredentialOffer,
+    ...(credentialOfferURI && { credential_offer_uri: credentialOfferURI }),
+    supportedFlows,
+    version,
+  };
+}
+
+export function isPreAuthCode(request: UniformCredentialOfferPayload | UniformCredentialOffer) {
+  const payload = 'credential_offer' in request ? request.credential_offer : (request as UniformCredentialOfferPayload);
+  return payload?.grants?.['urn:ietf:params:oauth:grant-type:pre-authorized_code']?.['pre-authorized_code'] !== undefined;
+}
+
+export async function assertedUniformCredentialOffer(
+  origCredentialOffer: UniformCredentialOffer,
+  opts?: {
+    resolve?: boolean;
+  }
+): Promise<AssertedUniformCredentialOffer> {
+  const credentialOffer = JSON.parse(JSON.stringify(origCredentialOffer));
+  if (credentialOffer.credential_offer_uri && !credentialOffer.credential_offer) {
+    if (opts?.resolve === undefined || opts.resolve) {
+      credentialOffer.credential_offer = await resolveCredentialOfferURI(credentialOffer.credential_offer_uri);
+    } else {
+      throw Error(`No credential_offer present, but we did get a URI, but resolution was explicitly disabled`);
+    }
+  }
+  if (!credentialOffer.credential_offer) {
+    throw Error(`No credential_offer present`);
+  }
+  credentialOffer.credential_offer = await toUniformCredentialOfferPayload(credentialOffer.credential_offer, { version: credentialOffer.version });
+  return credentialOffer as AssertedUniformCredentialOffer;
+}
+
+export async function resolveCredentialOfferURI(uri?: string): Promise<UniformCredentialOfferPayload | undefined> {
+  if (!uri) {
+    return undefined;
+  }
+  const response = (await getJson(uri)) as OpenIDResponse<UniformCredentialOfferPayload>;
+  if (!response || !response.successBody) {
+    throw Error(`Could not get credential offer from uri: ${uri}: ${JSON.stringify(response?.errorBody)}`);
+  }
+  return response.successBody as UniformCredentialOfferPayload;
+}
+
+export function toUniformCredentialOfferPayload(
+  offer: CredentialOfferPayload,
+  opts?: {
+    version?: OpenId4VCIVersion;
+  }
+): UniformCredentialOfferPayload {
+  // todo: create test to check idempotence once a payload is already been made uniform.
+  const version = opts?.version ?? determineSpecVersionFromOffer(offer);
+  if (version >= OpenId4VCIVersion.VER_1_0_11) {
+    const orig = offer as UniformCredentialOfferPayload;
+    return {
+      ...orig,
+    };
+  }
+  const grants: Grant = 'grants' in offer ? (offer.grants as Grant) : {};
+  let offerPayloadAsV8V9 = offer as CredentialOfferPayloadV1_0_08 | CredentialOfferPayloadV1_0_09;
+  if (isCredentialOfferVersion(offer, OpenId4VCIVersion.VER_1_0_08, OpenId4VCIVersion.VER_1_0_09)) {
+    if (offerPayloadAsV8V9.op_state) {
+      grants.authorization_code = {
+        ...grants.authorization_code,
+        issuer_state: offerPayloadAsV8V9.op_state,
+      };
+    }
+    let user_pin_required = false;
+    if (typeof offerPayloadAsV8V9.user_pin_required === 'string') {
+      user_pin_required = offerPayloadAsV8V9.user_pin_required === 'true' || offerPayloadAsV8V9.user_pin_required === 'yes';
+    } else if (offerPayloadAsV8V9.user_pin_required !== undefined) {
+      user_pin_required = offerPayloadAsV8V9.user_pin_required;
+    }
+    if (offerPayloadAsV8V9['pre-authorized_code']) {
+      grants['urn:ietf:params:oauth:grant-type:pre-authorized_code'] = {
+        'pre-authorized_code': offerPayloadAsV8V9['pre-authorized_code'],
+        user_pin_required,
+      };
+    }
+  }
+  const issuer = getIssuerFromCredentialOfferPayload(offer);
+  if (version === OpenId4VCIVersion.VER_1_0_09) {
+    offerPayloadAsV8V9 = offer as CredentialOfferPayloadV1_0_09;
+    return {
+      // credential_definition: getCredentialsSupported(never, offerPayloadAsV8V9.credentials).map(sup => {credentialSubject: sup.credentialSubject})[0],
+      credential_issuer: issuer ?? offerPayloadAsV8V9.issuer,
+      credentials: offerPayloadAsV8V9.credentials,
+      grants,
+    };
+  }
+  if (version === OpenId4VCIVersion.VER_1_0_08) {
+    offerPayloadAsV8V9 = offer as CredentialOfferPayloadV1_0_08;
+    return {
+      credential_issuer: issuer ?? offerPayloadAsV8V9.issuer,
+      credentials: Array.isArray(offerPayloadAsV8V9.credential_type) ? offerPayloadAsV8V9.credential_type : [offerPayloadAsV8V9.credential_type],
+      grants,
+    } as UniformCredentialOfferPayload;
+  }
+  throw Error(`Could not create uniform payload for version ${version}`);
+}
+
+export function determineFlowType(
+  suppliedOffer: AssertedUniformCredentialOffer | UniformCredentialOfferPayload,
+  version: OpenId4VCIVersion
+): AuthzFlowType[] {
+  const payload: UniformCredentialOfferPayload = getCredentialOfferPayload(suppliedOffer);
+  const supportedFlows: AuthzFlowType[] = [];
+  if (payload.grants?.authorization_code) {
+    supportedFlows.push(AuthzFlowType.AUTHORIZATION_CODE_FLOW);
+  }
+  if (payload.grants?.['urn:ietf:params:oauth:grant-type:pre-authorized_code']?.['pre-authorized_code']) {
+    supportedFlows.push(AuthzFlowType.PRE_AUTHORIZED_CODE_FLOW);
+  }
+  if (supportedFlows.length === 0 && version < OpenId4VCIVersion.VER_1_0_09) {
+    // auth flow without op_state was possible in v08. The only way to know is that the detections would result in finding nothing.
+    supportedFlows.push(AuthzFlowType.AUTHORIZATION_CODE_FLOW);
+  }
+  return supportedFlows;
+}
+
+export function getCredentialOfferPayload(offer: AssertedUniformCredentialOffer | UniformCredentialOfferPayload): UniformCredentialOfferPayload {
+  let payload: UniformCredentialOfferPayload;
+  if ('credential_offer' in offer && offer['credential_offer']) {
+    payload = offer.credential_offer;
+  } else {
+    payload = offer as UniformCredentialOfferPayload;
+  }
+  return payload;
+}
+
+export function determineGrantTypes(
+  offer:
+    | AssertedUniformCredentialOffer
+    | UniformCredentialOfferPayload
+    | ({
+        grants: Grant;
+      } & Record<never, never>)
+): GrantTypes[] {
+  let grants: Grant | undefined;
+  if ('grants' in offer && offer.grants) {
+    grants = offer.grants;
+  } else {
+    grants = getCredentialOfferPayload(offer as AssertedUniformCredentialOffer | UniformCredentialOfferPayload).grants;
+  }
+
+  const types: GrantTypes[] = [];
+  if (grants) {
+    if (grants.authorization_code) {
+      types.push(GrantTypes.AUTHORIZATION_CODE);
+    }
+    if (
+      grants['urn:ietf:params:oauth:grant-type:pre-authorized_code'] &&
+      grants['urn:ietf:params:oauth:grant-type:pre-authorized_code']['pre-authorized_code']
+    ) {
+      types.push(GrantTypes.PRE_AUTHORIZED_CODE);
+    }
+  }
+  return types;
+}
+
+function getVersionFromURIParam(credentialOfferURI: string, currentVersion: OpenId4VCIVersion, matchingVersion: OpenId4VCIVersion, param: string) {
+  if (credentialOfferURI.includes(param)) {
+    return recordVersion(currentVersion, matchingVersion, param);
+  }
+  return currentVersion;
+}
+
+function recordVersion(currentVersion: OpenId4VCIVersion, matchingVersion: OpenId4VCIVersion, key: string) {
+  if (currentVersion === OpenId4VCIVersion.VER_UNKNOWN || matchingVersion === currentVersion) {
+    return matchingVersion;
+  }
+
+  throw new Error(
+    `Invalid param. Some keys have been used from version: ${currentVersion} version while '${key}' is used from version: ${matchingVersion}`
+  );
+}

package/lib/functions/CredentialRequestUtil.ts

@@ -0,0 +1,5 @@
+import { CredentialRequestV1_0_11 } from '../types';
+
+export function getIssuerStateAndPreAuthCode(credentialRequest: CredentialRequestV1_0_11) {
+  console.log('nothing yet: ' + credentialRequest);
+}

package/lib/functions/Encoding.ts

@@ -0,0 +1,166 @@
+// import * as u8a from 'uint8arrays'
+
+import { BAD_PARAMS, DecodeURIAsJsonOpts, EncodeJsonAsURIOpts, OpenId4VCIVersion, SearchValue } from '../types';
+
+/**
+ * @function encodeJsonAsURI encodes a Json object into a URI
+ * @param json object
+ * @param opts:
+ *          - urlTypeProperties: a list of properties of which the value is a URL
+ *          - arrayTypeProperties: a list of properties which are an array
+ */
+
+// /* eslint-disable @typescript-eslint/no-explicit-any */
+export function convertJsonToURI(
+  json:
+    | {
+        [s: string]: never;
+      }
+    | ArrayLike<never>
+    | string
+    | object,
+  opts?: EncodeJsonAsURIOpts
+): string {
+  if (typeof json === 'string') {
+    return convertJsonToURI(JSON.parse(json), opts);
+  }
+
+  const results = [];
+
+  function encodeAndStripWhitespace(key: string): string {
+    return encodeURIComponent(key.replace(' ', ''));
+  }
+
+  let components: string;
+  if (opts?.version && opts.version > OpenId4VCIVersion.VER_1_0_08) {
+    // v11 changed from encoding every param to a encoded json object with a credential_offer param key
+    components = encodeAndStripWhitespace(JSON.stringify(json));
+  } else {
+    for (const [key, value] of Object.entries(json)) {
+      if (!value) {
+        continue;
+      }
+      //Skip properties that are not of URL type
+      if (!opts?.uriTypeProperties?.includes(key)) {
+        results.push(`${key}=${value}`);
+        continue;
+      }
+      if (opts?.arrayTypeProperties?.includes(key) && Array.isArray(value)) {
+        results.push(value.map((v) => `${encodeAndStripWhitespace(key)}=${customEncodeURIComponent(v, /\./g)}`).join('&'));
+        continue;
+      }
+      const isBool = typeof value == 'boolean';
+      const isNumber = typeof value == 'number';
+      const isString = typeof value == 'string';
+      let encoded;
+      if (isBool || isNumber) {
+        encoded = `${encodeAndStripWhitespace(key)}=${value}`;
+      } else if (isString) {
+        encoded = `${encodeAndStripWhitespace(key)}=${customEncodeURIComponent(value, /\./g)}`;
+      } else {
+        encoded = `${encodeAndStripWhitespace(key)}=${customEncodeURIComponent(JSON.stringify(value), /\./g)}`;
+      }
+      results.push(encoded);
+    }
+    components = results.join('&');
+  }
+  if (opts?.baseUrl) {
+    if (opts.baseUrl.endsWith('=')) {
+      if (opts.param) {
+        throw Error('Cannot combine param with an url ending in =');
+      }
+      return `${opts.baseUrl}${components}`;
+    } else if (!opts.baseUrl.includes('?')) {
+      return `${opts.baseUrl}?${opts.param ? opts.param + '=' : ''}${components}`;
+    } else if (opts.baseUrl.endsWith('?')) {
+      return `${opts.baseUrl}${opts.param ? opts.param + '=' : ''}${components}`;
+    } else {
+      return `${opts.baseUrl}${opts.param ? '&' + opts.param : ''}=${components}`;
+    }
+  }
+  return components;
+}
+
+/**
+ * @function decodeUriAsJson decodes a URI into a Json object
+ * @param uri string
+ * @param opts:
+ *          - requiredProperties: the required properties
+ *          - arrayTypeProperties: properties that can show up more that once
+ */
+export function convertURIToJsonObject(uri: string, opts?: DecodeURIAsJsonOpts): unknown {
+  if (!uri || !opts?.requiredProperties?.every((p) => uri.includes(p))) {
+    throw new Error(BAD_PARAMS);
+  }
+  const uriComponents = getURIComponentsAsArray(uri, opts?.arrayTypeProperties);
+  return decodeJsonProperties(uriComponents);
+}
+
+function decodeJsonProperties(parts: string[] | string[][]): unknown {
+  const json: { [s: string]: unknown } | ArrayLike<unknown> = {};
+  for (const key in parts) {
+    const value = parts[key];
+    if (!value) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      // if (value.length > 1) {
+      json[decodeURIComponent(key)] = value.map((v) => decodeURIComponent(v));
+      /*} else {
+        json[decodeURIComponent(key)] = decodeURIComponent(value[0]);
+      }*/
+    }
+    const isBool = typeof value == 'boolean';
+    const isNumber = typeof value == 'number';
+    const isString = typeof value == 'string';
+    if (isBool || isNumber) {
+      json[decodeURIComponent(key)] = value;
+    } else if (isString) {
+      const decoded = decodeURIComponent(value);
+      if (decoded.startsWith('{') && decoded.endsWith('}')) {
+        json[decodeURIComponent(key)] = JSON.parse(decoded);
+      } else {
+        json[decodeURIComponent(key)] = decoded;
+      }
+    }
+  }
+  return json;
+}
+
+/**
+ * @function get URI Components as Array
+ * @param uri string
+ * @param arrayTypes array of string containing array like keys
+ */
+function getURIComponentsAsArray(uri: string, arrayTypes?: string[]): string[] | string[][] {
+  const parts = uri.includes('?') ? uri.split('?')[1] : uri.includes('://') ? uri.split('://')[1] : uri;
+  const json: string[] | string[][] = [];
+  const dict: string[] = parts.split('&');
+  for (const entry of dict) {
+    const pair: string[] = entry.split('=');
+    const p0: any = pair[0];
+    const p1: any = pair[1];
+    if (arrayTypes?.includes(p0)) {
+      const key = json[p0];
+      if (Array.isArray(key)) {
+        key.push(p1);
+      } else {
+        json[p0] = [p1];
+      }
+      continue;
+    }
+    json[p0] = p1;
+  }
+  return json;
+}
+
+/**
+ * @function customEncodeURIComponent is used to encode chars that are not encoded by default
+ * @param searchValue The pattern/regexp to find the char(s) to be encoded
+ * @param uriComponent query string
+ */
+function customEncodeURIComponent(uriComponent: string, searchValue: SearchValue): string {
+  // -_.!~*'() are not escaped because they are considered safe.
+  // Add them to the regex as you need
+  return encodeURIComponent(uriComponent).replace(searchValue, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}

package/lib/functions/HttpUtils.ts

@@ -0,0 +1,168 @@
+import { fetch } from 'cross-fetch';
+import Debug from 'debug';
+
+import { Encoding, OpenIDResponse } from '../types';
+
+const debug = Debug('sphereon:openid4vci:http');
+
+export const getJson = async <T>(
+  URL: string,
+  opts?: { bearerToken?: string; contentType?: string; accept?: string; customHeaders?: Record<string, string>; exceptionOnHttpErrorStatus?: boolean }
+): Promise<OpenIDResponse<T>> => {
+  return await openIdFetch(URL, undefined, { method: 'GET', ...opts });
+};
+
+export const formPost = async <T>(
+  url: string,
+  body: BodyInit,
+  opts?: { bearerToken?: string; contentType?: string; accept?: string; customHeaders?: Record<string, string>; exceptionOnHttpErrorStatus?: boolean }
+): Promise<OpenIDResponse<T>> => {
+  return await post(url, body, opts?.contentType ? { ...opts } : { contentType: Encoding.FORM_URL_ENCODED, ...opts });
+};
+
+export const post = async <T>(
+  url: string,
+  body?: BodyInit,
+  opts?: { bearerToken?: string; contentType?: string; accept?: string; customHeaders?: Record<string, string>; exceptionOnHttpErrorStatus?: boolean }
+): Promise<OpenIDResponse<T>> => {
+  return await openIdFetch(url, body, { method: 'POST', ...opts });
+};
+
+const openIdFetch = async <T>(
+  url: string,
+  body?: BodyInit,
+  opts?: {
+    method?: string;
+    bearerToken?: string;
+    contentType?: string;
+    accept?: string;
+    customHeaders?: Record<string, string>;
+    exceptionOnHttpErrorStatus?: boolean;
+  }
+): Promise<OpenIDResponse<T>> => {
+  const headers: Record<string, string> = opts?.customHeaders ?? {};
+  if (opts?.bearerToken) {
+    headers['Authorization'] = `Bearer ${opts.bearerToken}`;
+  }
+  const method = opts?.method ? opts.method : body ? 'POST' : 'GET';
+  const accept = opts?.accept ? opts.accept : 'application/json';
+  headers['Accept'] = accept;
+  if (headers['Content-Type']) {
+    if (opts?.contentType && opts.contentType !== headers['Content-Type']) {
+      throw Error(
+        `Mismatch in content-types from custom headers (${headers['Content-Type']}) and supplied content type option (${opts.contentType})`
+      );
+    }
+  } else {
+    if (opts?.contentType) {
+      headers['Content-Type'] = opts.contentType;
+    } else if (method !== 'GET') {
+      headers['Content-Type'] = 'application/json';
+    }
+  }
+
+  const payload: RequestInit = {
+    method,
+    headers,
+    body,
+  };
+
+  console.log(`START fetching url: ${url}`);
+  if (body) {
+    debug(`Body:\r\n${JSON.stringify(body)}`);
+  }
+  debug(`Headers:\r\n${JSON.stringify(payload.headers)}`);
+  const origResponse = await fetch(url, payload);
+  const isJSONResponse = accept === 'application/json' || origResponse.headers.get('Content-Type') === 'application/json';
+  const success = origResponse && origResponse.status >= 200 && origResponse.status < 400;
+  const responseText = await origResponse.text();
+  const responseBody = isJSONResponse && responseText.includes('{') ? JSON.parse(responseText) : responseText;
+
+  console.log(`${success ? 'success' : 'error'} status: ${origResponse.status}, body:\r\n${JSON.stringify(responseBody)}`);
+  if (!success && opts?.exceptionOnHttpErrorStatus) {
+    const error = JSON.stringify(responseBody);
+    throw new Error(error === '{}' ? '{"error": "not found"}' : error);
+  }
+  debug(`END fetching url: ${url}`);
+
+  return {
+    origResponse,
+    successBody: success ? responseBody : undefined,
+    errorBody: !success ? responseBody : undefined,
+  };
+};
+
+export const isValidURL = (url: string): boolean => {
+  const urlPattern = new RegExp(
+    '^(https?:\\/\\/)' + // validate protocol
+      '((([a-z\\d]([a-z\\d-]*[a-z\\d])*)\\.)+[a-z]{2,}|' + // validate domain name
+      '((localhost))|' + // validate OR localhost
+      '((\\d{1,3}\\.){3}\\d{1,3}))' + // validate OR ip (v4) address
+      '(\\:\\d+)?(\\/[-a-z\\d%_.~+:]*)*' + // validate port and path
+      '(\\?[;&a-z\\d%_.~+=-]*)?' + // validate query string
+      '(\\#[-a-z\\d_]*)?$', // validate fragment locator
+    'i'
+  );
+  return urlPattern.test(url);
+};
+
+export const trimBoth = (value: string, trim: string): string => {
+  return trimEnd(trimStart(value, trim), trim);
+};
+
+export const trimEnd = (value: string, trim: string): string => {
+  return value.endsWith(trim) ? value.substring(0, value.length - trim.length) : value;
+};
+
+export const trimStart = (value: string, trim: string): string => {
+  return value.startsWith(trim) ? value.substring(trim.length) : value;
+};
+
+export const adjustUrl = <T extends string | URL>(
+  urlOrPath: T,
+  opts?: {
+    stripSlashEnd?: boolean;
+    stripSlashStart?: boolean;
+    prepend?: string;
+    append?: string;
+  }
+): T => {
+  let url = typeof urlOrPath === 'object' ? urlOrPath.toString() : (urlOrPath as string);
+  if (opts?.append) {
+    url = trimEnd(url, '/') + '/' + trimStart(opts.append, '/');
+  }
+  if (opts?.prepend) {
+    if (opts.prepend.includes('://')) {
+      // includes domain/hostname
+      if (!url.startsWith(opts.prepend)) {
+        url = trimEnd(opts.prepend, '/') + '/' + trimStart(url, '/');
+      }
+    } else {
+      // path only for prepend
+      let host = '';
+      let path = url;
+      if (url.includes('://')) {
+        // includes domain/hostname
+        host = new URL(url).host;
+        path = new URL(url).pathname;
+      }
+      if (!path.startsWith(opts.prepend)) {
+        if (host && host !== '') {
+          url = trimEnd(host, '/');
+        }
+        url += trimEnd(url, '/') + '/' + trimBoth(opts.prepend, '/') + '/' + trimStart(path, '/');
+      }
+    }
+  }
+  if (opts?.stripSlashStart) {
+    url = trimStart(url, '/');
+  }
+  if (opts?.stripSlashEnd) {
+    url = trimEnd(url, '/');
+  }
+
+  if (typeof urlOrPath === 'string') {
+    return url as T;
+  }
+  return new URL(url) as T;
+};