@globus/sdk 1.0.0-alpha → 1.2.0-alpha

package/src/lib/core/__tests__/url.spec.ts

@@ -1,105 +0,0 @@
-import { EnvironmentConfigurationError } from "../errors";
-import { ENVIRONMENTS } from "../global";
-import { build, getServiceURL, stringifyParameters } from "../url";
-
-describe.each(Object.values(ENVIRONMENTS))(
-  "getServiceUrl succeeds",
-  (environment) => {
-    it("should produce a valid Globus Auth service URL", () => {
-      expect(() => {
-        getServiceURL("AUTH", environment);
-      }).not.toThrow();
-    });
-
-    it("should produce a valid Globus Transfer service URL", () => {
-      expect(() => {
-        getServiceURL("TRANSFER", environment);
-      }).not.toThrow();
-    });
-  }
-);
-
-describe("getServiceUrl failure", () => {
-  it("should throw an error when passed an invalid value", () => {
-    expect(() => {
-      getServiceURL("TRANSFER", "///%%%###");
-    }).toThrow();
-  });
-});
-
-describe.each(Object.values(ENVIRONMENTS))(
-  "build succeeds for all environments",
-  (environment) => {
-    const ORIGINAL_ENV_VARS = process.env;
-
-    beforeEach(() => {
-      process.env = {
-        ...ORIGINAL_ENV_VARS,
-        GLOBUS_SDK_ENVIRONMENT: environment,
-      };
-    });
-
-    afterAll(() => {
-      process.env = ORIGINAL_ENV_VARS;
-    });
-
-    it("should not throw errors for all environments", () => {
-      expect(() => {
-        build("AUTH", "test-path");
-      }).not.toThrow();
-    });
-  }
-);
-
-describe("build fails when invalid GLOBUS_SDK_ENVIRONMENT is set", () => {
-  const ORIGINAL_ENV_VARS = process.env;
-
-  afterAll(() => {
-    process.env = ORIGINAL_ENV_VARS;
-  });
-
-  it("should throw an error", () => {
-    process.env["GLOBUS_SDK_ENVIRONMENT"] = "sindbox"; // <- intentional misspelling
-
-    expect(() => {
-      build("AUTH", "test-path");
-    }).toThrow(EnvironmentConfigurationError);
-  });
-});
-
-describe("stringifyParameters", () => {
-  it("should serialize a simple object", () => {
-    expect(
-      stringifyParameters({ storage_gateway: "my-storage-gateway" })
-    ).toEqual("storage_gateway=my-storage-gateway");
-  });
-
-  it("should serialize an object with an array (single value)", () => {
-    /**
-     * Example from the GCS Manager API
-     * @see https://docs.globus.org/globus-connect-server/v5.4/api/openapi_Roles/#listRoles
-     */
-    expect(stringifyParameters({ include: ["all_roles"] })).toEqual(
-      "include=all_roles"
-    );
-  });
-
-  it("should serialize an object with an array (many values)", () => {
-    /**
-     * Example from the Groups V2 API
-     * @see https://groups.api.globus.org/redoc?_gl=1*16m8wdi*_ga*MTI3NTI4MzEzMi4xNjc1MTk1MTMw*_ga_7ZB89HGG0P*MTY5MDU3OTExNS4xNjUuMS4xNjkwNTc5MTk2LjAuMC4w#tag/groups/operation/get_statuses_v2_groups_statuses_get
-     */
-    expect(
-      stringifyParameters({
-        include: [
-          "memberships",
-          "my_memberships",
-          "policies",
-          "allowed_actions",
-        ],
-      })
-    ).toEqual(
-      "include=memberships%2Cmy_memberships%2Cpolicies%2Callowed_actions"
-    );
-  });
-});

package/src/lib/core/authorization.ts

@@ -1,113 +0,0 @@
-/**
- * @description Session and authorization management via PKCE.
- * @group Core
- * @module
- * @experimental
- */
-import PKCE from "js-pkce";
-
-import type IConfig from "js-pkce/dist/IConfig";
-import type ITokenResponse from "js-pkce/dist/ITokenResponse";
-import { getAuthorizationEndpoint, getTokenEndpoint } from "../services/auth";
-import {
-  addTokenResponse,
-  getTokenForScope,
-  reset as resetTokens,
-} from "./consent";
-
-import { createStorage, StorageSystem } from "./storage";
-
-let storage: StorageSystem;
-
-type PKCEConfiguration = {
-  client_id?: IConfig["client_id"];
-  requested_scopes: IConfig["requested_scopes"];
-  redirect_uri: IConfig["redirect_uri"];
-};
-
-/**
- * @experimental
- */
-export class PKCEAuthorization {
-  #pkce: PKCE;
-  #configuration: IConfig;
-  #response: ITokenResponse | undefined;
-
-  constructor(configuration: PKCEConfiguration) {
-    storage = createStorage("localStorage");
-    if (!configuration.client_id) {
-      throw new Error("You must provide a `client_id`.");
-    }
-    this.#configuration = {
-      client_id: configuration.client_id,
-      authorization_endpoint: getAuthorizationEndpoint(),
-      token_endpoint: getTokenEndpoint(),
-      ...configuration,
-    };
-    this.#pkce = this.#createPKCEInstance();
-  }
-
-  #createPKCEInstance() {
-    return new PKCE(this.#configuration);
-  }
-
-  #resetPKCE() {
-    /**
-     * Resets js-pkce state
-     * @see https://github.com/bpedroza/js-pkce/blob/master/src/PKCE.ts
-     */
-    sessionStorage.removeItem("pkce_state");
-    sessionStorage.removeItem("pkce_code_verifier");
-  }
-
-  reset() {
-    this.#resetPKCE();
-    resetTokens();
-  }
-
-  redirect() {
-    this.reset();
-    window.location.replace(this.#pkce.authorizeUrl());
-  }
-
-  async handleCodeRedirect(options = { removeStateAndReplaceLocation: true }) {
-    const url = new URL(window.location.href);
-    const params = new URLSearchParams(url.search);
-
-    if (!params.get("code")) return;
-    const response = await this.#pkce.exchangeForAccessToken(url.toString());
-    this.#response = response;
-    addTokenResponse(this.#response);
-    // Remove PKCE-state from the URL since we have a token.
-    if (options.removeStateAndReplaceLocation) {
-      params.delete("code");
-      params.delete("state");
-      url.search = params.toString();
-      window.location.replace(url);
-    }
-  }
-
-  hasToken(): boolean {
-    return this.#configuration.requested_scopes
-      .split(" ")
-      .every((scope) => Boolean(getTokenForScope(scope)));
-  }
-
-  revoke() {
-    this.reset();
-  }
-}
-
-/**
- * @experimental
- */
-export function pkce(configuration: PKCEConfiguration) {
-  return new PKCEAuthorization(configuration);
-}
-
-/**
- * @experimental
- */
-export function incremental(configuration: PKCEConfiguration) {
-  return new PKCEAuthorization(configuration);
-}

package/src/lib/core/consent.ts

@@ -1,34 +0,0 @@
-import { getStorage } from "./storage";
-import type { Token, TokenResponse } from "../services/auth";
-
-import ITokenResponse from "js-pkce/dist/ITokenResponse";
-
-function isValidToken(check: unknown): check is Token {
-  const maybe = check as Token;
-  return Boolean(maybe.token_type && maybe.access_token);
-}
-
-function store(token: ITokenResponse) {
-  token.scope.split(" ").forEach((scope) => {
-    getStorage().set(scope, token);
-  });
-}
-
-export function addTokenResponse(token: ITokenResponse | TokenResponse) {
-  store(token);
-  if ("other_tokens" in token) {
-    token.other_tokens.forEach(store);
-  }
-}
-
-export function getTokenForScope(scope: string) {
-  const token = getStorage().get(scope);
-  if (!token || !isValidToken(token)) {
-    return null;
-  }
-  return `${token.token_type} ${token.access_token}`;
-}
-
-export function reset() {
-  getStorage().clear();
-}

package/src/lib/core/errors.ts

@@ -1,8 +0,0 @@
-export class EnvironmentConfigurationError extends Error {
-  override name = "EnvironmentConfigurationError";
-  constructor(variable: string, value: unknown) {
-    super();
-    // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
-    this.message = `Invalid configuration value provided for ${variable} (${value}).`;
-  }
-}

package/src/lib/core/fetch.ts

@@ -1,38 +0,0 @@
-import { fetch } from "./internals/fetch";
-import { getTokenForScope } from "./consent";
-
-type GlobusScope = string;
-
-export type FetchOverrides =
-  | (Omit<RequestInit, "headers"> & {
-      headers?: Record<string, string>;
-    })
-  | undefined;
-
-export function fetchWithScope(
-  scope: GlobusScope,
-  input: RequestInfo | URL,
-  fetchOverrides: FetchOverrides = {}
-) {
-  const headers = fetchOverrides.headers || {};
-  /**
-   * If an `Authorization` override header was provided, we skip any
-   * sort of lookup and use the provided value.
-   */
-  if (!headers?.["Authorization"]) {
-    const token = getTokenForScope(scope);
-    if (token) {
-      headers["Authorization"] = token;
-    }
-  }
-  /**
-   * If `Content-Type` header was not provided, and there is a body, we assume it is JSON.
-   */
-  if (!headers?.["Content-Type"] && fetchOverrides?.body) {
-    headers["Content-Type"] = "application/json";
-  }
-  return fetch(input, {
-    ...fetchOverrides,
-    headers,
-  });
-}

package/src/lib/core/global.ts

@@ -1,128 +0,0 @@
-import * as AUTH from "../services/auth/config";
-import * as TRANSFER from "../services/transfer/config";
-import * as FLOWS from "../services/flows/config";
-import * as GROUPS from "../services/groups/config";
-import * as SEARCH from "../services/search/config";
-
-import { EnvironmentConfigurationError } from "./errors";
-
-function getRuntime() {
-  return typeof window !== "undefined" ? window : process;
-}
-
-function isBrowser(runtime: Window | NodeJS.Process): runtime is Window {
-  return typeof window === typeof runtime;
-}
-
-function env<T extends string>(
-  key: string,
-  fallback: T | undefined = undefined
-): T | undefined {
-  const runtime = getRuntime();
-  let envConfiguration;
-  if (isBrowser(runtime)) {
-    envConfiguration = runtime;
-  } else {
-    envConfiguration = runtime.env;
-  }
-  if (key in envConfiguration) {
-    return (envConfiguration as Record<typeof key, T>)[key];
-  }
-  return fallback;
-}
-
-/**
- * Handlers for: GLOBUS_SDK_ENVIRONMENT
- */
-export const ENVIRONMENTS = {
-  PRODUCTION: "production",
-  PREVIEW: "preview",
-  STAGING: "staging",
-  SANDBOX: "sandbox",
-  INTEGRATION: "integration",
-  TEST: "test",
-} as const;
-
-export type Environment = (typeof ENVIRONMENTS)[keyof typeof ENVIRONMENTS];
-
-export function getEnvironment(): Environment {
-  const environment = env<Environment>(
-    "GLOBUS_SDK_ENVIRONMENT",
-    ENVIRONMENTS.PRODUCTION
-  );
-  if (!environment || !Object.values(ENVIRONMENTS).includes(environment)) {
-    throw new EnvironmentConfigurationError(
-      "GLOBUS_SDK_ENVIRONMENT",
-      environment
-    );
-  }
-  return environment;
-}
-
-export const SERVICES = {
-  [AUTH.ID]: AUTH.ID,
-  [TRANSFER.ID]: TRANSFER.ID,
-  [FLOWS.ID]: FLOWS.ID,
-  [GROUPS.ID]: GROUPS.ID,
-  [SEARCH.ID]: SEARCH.ID,
-};
-
-export type Service = keyof typeof SERVICES;
-
-export const SERVICE_HOSTS: Record<
-  Service,
-  Partial<Record<Environment, string>>
-> = {
-  [AUTH.ID]: AUTH.HOSTS,
-  [TRANSFER.ID]: TRANSFER.HOSTS,
-  [FLOWS.ID]: FLOWS.HOSTS,
-  [GROUPS.ID]: GROUPS.HOSTS,
-  [SEARCH.ID]: SEARCH.HOSTS,
-};
-
-/**
- * Handlers for: GLOBUS_SDK_VERIFY_SSL
- * Since disabling SSL is at least not-recommended, we consider
- * this value to always be true, but provide a warning when it set
- * to one of the falsey values for informational purposes.
- *
- * Taking direction from `globus-sdk-python` for possible false values
- * @see https://github.com/globus/globus-sdk-python/blob/18eced9c12e2ec41745d1be183148845198b999c/src/globus_sdk/config/env_vars.py#L20
- */
-export function getVerifySSL(): boolean {
-  const verifySSLTemp = (
-    env("GLOBUS_SDK_VERIFY_SSL", "true") as string
-  ).toLowerCase();
-  if (["n", "no", "f", "false", "off", "0"].includes(verifySSLTemp)) {
-    console.warn(
-      "Setting GLOBUS_SDK_VERIFY_SSL to false is disallowed in the Globus Javascript SDK. It will always true in this context"
-    );
-  }
-  return true;
-}
-
-/**
- * Handlers for: GLOBUS_SDK_HTTP_TIMEOUT
- */
-export function getHttpTimeout() {
-  const timeout = Number(env("GLOBUS_SDK_HTTP_TIMEOUT", "60"));
-  if (timeout === -1) {
-    return null;
-  }
-  return timeout;
-}
-
-function getServiceHost(service: Service, environment: Environment) {
-  return SERVICE_HOSTS[service][environment];
-}
-
-export function getServiceBaseUrl(
-  service: Service,
-  environment: Environment = getEnvironment()
-) {
-  const host = getServiceHost(service, environment);
-  return env(
-    `GLOBUS_SDK_SERVICE_URL_${service}`,
-    host ? `https://${host}` : undefined
-  );
-}

package/src/lib/core/internals/__mocks__/fetch.ts

@@ -1,7 +0,0 @@
-const actual: typeof import("../fetch") =
-  jest.requireActual("../fetch");
-
-module.exports = {
-  ...actual,
-  fetch: jest.fn().mockResolvedValue({}),
-};

package/src/lib/core/storage/index.ts

@@ -1,57 +0,0 @@
-import { MemoryStorage } from "./memory";
-import { LocalStorage } from "./local-storage";
-/**
- * Acts as a basic wrapper for storage layers to make their surface APIs consistent.
- */
-export interface StorageSystem {
-  get(key: string): unknown | undefined;
-  set(key: string, value: unknown): void;
-  remove(key: string): void;
-  clear(): void;
-}
-
-let storage: undefined | StorageSystem;
-type StorageOptions =
-  | "localStorage"
-  | "memory"
-  | {
-      new (): StorageSystem;
-    };
-
-/**
- * Returns the active storage system or creates an instance for the running process.
- */
-export function createStorage(
-  storageType: StorageOptions = "memory"
-): StorageSystem {
-  if (!storage) {
-    let Factory;
-    if (storageType === "localStorage") {
-      Factory = LocalStorage;
-    } else if (storageType === "memory") {
-      Factory = MemoryStorage;
-    } else {
-      Factory = storageType;
-    }
-    storage = new Factory();
-  }
-  return storage;
-}
-
-export default createStorage;
-
-export function getStorage() {
-  if (!storage) {
-    throw Error("You must create a storage system.");
-  }
-  return storage;
-}
-
-/**
- * A private method for resetting the storage system. This is primarily used to reset
- * the storage system during testing.
- * @private
- */
-export function __reset() {
-  storage = undefined;
-}

package/src/lib/core/storage/local-storage.ts

@@ -1,20 +0,0 @@
-import { StorageSystem } from "./index";
-
-export class LocalStorage implements StorageSystem {
-  get<T>(key: string): T | null | unknown {
-    const value = localStorage.getItem(key);
-    return value !== null ? JSON.parse(value) : null;
-  }
-
-  set(key: string, value: unknown) {
-    localStorage.setItem(key, JSON.stringify(value));
-  }
-
-  remove(key: string) {
-    localStorage.removeItem(key);
-  }
-
-  clear() {
-    localStorage.clear();
-  }
-}

package/src/lib/core/storage/memory.ts

@@ -1,21 +0,0 @@
-import type { StorageSystem } from "./index";
-
-export class MemoryStorage implements StorageSystem {
-  #cache: Record<string, unknown> = {};
-
-  get(key: string) {
-    return this.#cache[key];
-  }
-
-  set(key: string, value: unknown) {
-    this.#cache[key] = value;
-  }
-
-  remove(key: string) {
-    delete this.#cache[key];
-  }
-
-  clear() {
-    this.#cache = {};
-  }
-}

package/src/lib/core/storage/storage.spec.ts

@@ -1,30 +0,0 @@
-import type { StorageSystem } from "./index";
-
-import storage, { __reset } from "./index";
-import { MemoryStorage } from "./memory";
-import { LocalStorage } from "./local-storage";
-
-describe("storage", () => {
-  afterEach(() => {
-    __reset();
-  });
-
-  it("default storage interface (memory)", () => {
-    expect(storage()).toBeInstanceOf(MemoryStorage);
-  });
-
-  it("can be configured using known interface", () => {
-    expect(storage("localStorage")).toBeInstanceOf(LocalStorage);
-  });
-
-  it("can be provided a custom storage interface", () => {
-    expect(storage(CustomStorage)).toBeInstanceOf(CustomStorage);
-  });
-});
-
-class CustomStorage implements StorageSystem {
-  get(key: string) {}
-  set(key: string, value: any): void {}
-  remove(key: string): void {}
-  clear(): void {}
-}

package/src/lib/core/url.ts

@@ -1,73 +0,0 @@
-import { getServiceBaseUrl, getEnvironment, Environment } from "./global";
-import type { Service } from "./global";
-import type { GCSConfiguration } from "../services/globus-connect-server";
-
-/**
- * Return the base URL for a service (based on the environment).
- * @param service The service to build the URL for.
- * @param path The path to the resource.
- * @param environment The environment to use.
- */
-export function getServiceURL(
-  service: Service,
-  path = "",
-  environment: Environment = getEnvironment()
-): URL {
-  const base = getServiceBaseUrl(service, environment);
-  return new URL(path, base);
-}
-
-/**
- * Build a URL for a service or GCSConfiguration.
- *
- * @param service The service identifier or GCSConfiguration object to build the URL for.
- * @param path The path to the resource.
- * @param options Additional options for the URL.
- */
-export function build(
-  serviceOrConfiguration: Service | GCSConfiguration,
-  path: string,
-  options?: {
-    search?: Parameters<typeof stringifyParameters>[0];
-  }
-) {
-  let url;
-  if (typeof serviceOrConfiguration === "object") {
-    url = new URL(path, serviceOrConfiguration.host);
-  } else {
-    url = getServiceURL(serviceOrConfiguration, path);
-  }
-  if (options && options.search) {
-    url.search = stringifyParameters(options.search);
-  }
-  return url.toString();
-}
-
-/**
- * An extremely simplified parameter serializer based on our current needs.
- *
- * **This is intended for internal @globus/sdk use only.**
- *
- * @private
- */
-export function stringifyParameters(parameters: {
-  [key: string]:
-    | string
-    | number
-    | Array<string | number | null | undefined>
-    | null
-    | undefined;
-}) {
-  const search = new URLSearchParams();
-  for (const [key, value] of Object.entries(parameters)) {
-    if (Array.isArray(value)) {
-      /**
-       * Arrays are converted to comma-separated strings.
-       */
-      search.set(key, value.join(","));
-    } else if (value !== undefined) {
-      search.set(key, String(value));
-    }
-  }
-  return search.toString();
-}

package/src/lib/services/auth/config.ts

@@ -1,11 +0,0 @@
-import type { Environment } from "../../core/global";
-
-export const ID = "AUTH";
-export const HOSTS: Partial<Record<Environment, string>> = {
-  integration: "auth.integration.globuscs.info",
-  sandbox: "auth.sandbox.globuscs.info",
-  production: "auth.globus.org",
-  test: "auth.test.globuscs.info",
-  staging: "auth.staging.globuscs.info",
-  preview: "auth.preview.globus.org",
-};

package/src/lib/services/auth/index.ts

@@ -1,37 +0,0 @@
-/**
- * @description A wrapper around the Globus Auth service.
- * @group Service
- * @see [Globus Auth API Documentation](https://docs.globus.org/api/auth/)
- * @module
- */
-import { build } from "../../core/url";
-
-import * as AUTH from "./config";
-
-/**
- * @private
- * @internal
- */
-export const CONFIG = AUTH;
-
-import type ITokenResponse from "js-pkce/dist/ITokenResponse";
-
-export function getAuthorizationEndpoint() {
-  return build(AUTH.ID, "/v2/oauth2/authorize");
-}
-
-export function getTokenEndpoint() {
-  return build(AUTH.ID, "/v2/oauth2/token");
-}
-
-export type Token = ITokenResponse & {
-  resource_server: string;
-  id_token?: string;
-};
-/**
- * @see https://docs.globus.org/api/auth/reference/#authorization_code_grant_preferred
- */
-export type TokenResponse = Token & {
-  state: string;
-  other_tokens: Token[];
-};