@globus/sdk 4.4.0 → 5.0.0-rc.1

package/dist/cjs/apps/web.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Utilities and methods related to the Globus Web App.
+ * @see https://app.globus.org/
+ */
+import { type Environment } from '../core/global.js';
+import type { SDKOptions } from '../services/types';
+/**
+ * The hostnames for the Globus Web App in each environment.
+ */
+export declare const HOSTS: Record<Environment, string>;
+/**
+ * Return the hostname for the Globus Web App in the given environment.
+ */
+export declare function host(env?: Environment): string;
+/**
+ * Return a URL for the Globus Web App.
+ */
+export declare function url(path?: string, sdkOptions?: SDKOptions): URL;
+type WebAppURLIdentifier = 'TASK' | 'COLLECTION' | 'ENDPOINT';
+/**
+ * Obtain a URL for a specific page in the Globus Web App.
+ * @example
+ * ```typescript
+ * const url = urlFor('TASK', ['example-uuid']);
+ * ```
+ */
+export declare function urlFor(identifier: WebAppURLIdentifier, segments?: string[], sdkOptions?: SDKOptions): URL;
+export {};
+//# sourceMappingURL=web.d.ts.map

package/dist/cjs/apps/web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../../src/apps/web.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;GAEG;AACH,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAO7C,CAAC;AAEF;;GAEG;AACH,wBAAgB,IAAI,CAAC,GAAG,GAAE,WAA8B,UAEvD;AAED;;GAEG;AACH,wBAAgB,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,OAEzD;AAED,KAAK,mBAAmB,GAAG,MAAM,GAAG,YAAY,GAAG,UAAU,CAAC;AAQ9D;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,UAAU,EAAE,mBAAmB,EAC/B,QAAQ,CAAC,EAAE,MAAM,EAAE,EACnB,UAAU,CAAC,EAAE,UAAU,OAIxB"}

package/dist/cjs/apps/web.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Utilities and methods related to the Globus Web App.
+ * @see https://app.globus.org/
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOSTS = void 0;
+exports.host = host;
+exports.url = url;
+exports.urlFor = urlFor;
+const global_js_1 = require("../core/global.js");
+/**
+ * The hostnames for the Globus Web App in each environment.
+ */
+exports.HOSTS = {
+    integration: 'app.integration.globuscs.info',
+    sandbox: 'app.sandbox.globuscs.info',
+    test: 'app.test.globuscs.info',
+    staging: 'app.staging.globuscs.info',
+    preview: 'app.preview.globus.org',
+    production: 'app.globus.org',
+};
+/**
+ * Return the hostname for the Globus Web App in the given environment.
+ */
+function host(env = (0, global_js_1.getEnvironment)()) {
+    return exports.HOSTS[env];
+}
+/**
+ * Return a URL for the Globus Web App.
+ */
+function url(path, sdkOptions) {
+    return new URL(path || '', `https://${host(sdkOptions === null || sdkOptions === void 0 ? void 0 : sdkOptions.environment)}`);
+}
+const WEBAPP_URLS = {
+    TASK: '/activity/%s/overview',
+    COLLECTION: '/file-manager/collections/%s/overview',
+    ENDPOINT: '/file-manager/collections/%s/overview',
+};
+/**
+ * Obtain a URL for a specific page in the Globus Web App.
+ * @example
+ * ```typescript
+ * const url = urlFor('TASK', ['example-uuid']);
+ * ```
+ */
+function urlFor(identifier, segments, sdkOptions) {
+    const path = WEBAPP_URLS[identifier].replace(/%s/g, (segments === null || segments === void 0 ? void 0 : segments.join('/')) || '');
+    return url(path, sdkOptions);
+}
+//# sourceMappingURL=web.js.map

package/dist/cjs/apps/web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.js","sourceRoot":"","sources":["../../../src/apps/web.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAoBH,oBAEC;AAKD,kBAEC;AAiBD,wBAOC;AAnDD,iDAAqE;AAGrE;;GAEG;AACU,QAAA,KAAK,GAAgC;IAChD,WAAW,EAAE,+BAA+B;IAC5C,OAAO,EAAE,2BAA2B;IACpC,IAAI,EAAE,wBAAwB;IAC9B,OAAO,EAAE,2BAA2B;IACpC,OAAO,EAAE,wBAAwB;IACjC,UAAU,EAAE,gBAAgB;CAC7B,CAAC;AAEF;;GAEG;AACH,SAAgB,IAAI,CAAC,MAAmB,IAAA,0BAAc,GAAE;IACtD,OAAO,aAAK,CAAC,GAAG,CAAC,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,SAAgB,GAAG,CAAC,IAAa,EAAE,UAAuB;IACxD,OAAO,IAAI,GAAG,CAAC,IAAI,IAAI,EAAE,EAAE,WAAW,IAAI,CAAC,UAAU,aAAV,UAAU,uBAAV,UAAU,CAAE,WAAW,CAAC,EAAE,CAAC,CAAC;AACzE,CAAC;AAID,MAAM,WAAW,GAAwC;IACvD,IAAI,EAAE,uBAAuB;IAC7B,UAAU,EAAE,uCAAuC;IACnD,QAAQ,EAAE,uCAAuC;CAClD,CAAC;AAEF;;;;;;GAMG;AACH,SAAgB,MAAM,CACpB,UAA+B,EAC/B,QAAmB,EACnB,UAAuB;IAEvB,MAAM,IAAI,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAE,IAAI,CAAC,GAAG,CAAC,KAAI,EAAE,CAAC,CAAC;IAC/E,OAAO,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AAC/B,CAAC"}

package/dist/cjs/constants.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @module Constants
+ * @description Constants provided by the SDK.
+ *
+ * @example
+ * // Using the global exported constants.
+ * import { GCS } from "@globus/sdk/constants";
+ * console.log(GCS.CONNECTORS.POSIX);
+ *
+ * @example
+ * // Using the service-specific exported constants.
+ * import GCS from "@globus/sdk/service/globus-connect-server/constants";
+ * console.log(GCS.CONNECTORS.POSIX);
+ */
+export * as GCS from './services/globus-connect-server/constants.js';
+//# sourceMappingURL=constants.d.ts.map

package/dist/cjs/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,GAAG,MAAM,+CAA+C,CAAC"}

package/dist/cjs/core/authorization/AuthorizationManager.d.ts

@@ -0,0 +1,189 @@
+import type IConfig from 'js-pkce/dist/IConfig';
+import { Event } from './Event.js';
+import { RedirectTransportOptions, GetTokenOptions } from './RedirectTransport.js';
+import { TokenLookup } from './TokenLookup.js';
+import { AuthorizationRequirementsError, ConsentRequiredError } from '../errors.js';
+import type { JwtUserInfo, Token, TokenResponse, TokenWithRefresh } from '../../services/auth/types.js';
+export type AuthorizationManagerConfiguration = {
+    client: IConfig['client_id'];
+    scopes?: IConfig['requested_scopes'];
+    redirect: IConfig['redirect_uri'];
+    /**
+     * @private
+     * @default DEFAULT_CONFIGURATION.useRefreshTokens
+     */
+    useRefreshTokens?: boolean;
+    /**
+     * @private
+     * @default DEFAULT_CONFIGURATION.defaultScopes
+     */
+    defaultScopes?: string | false;
+    /**
+     * Provide an object with event listeners to attach to the instance.
+     * This is useful if you need to listen to events that might dispatch immediately
+     * after the creation of the instance (constructor), e.g., the `authenticated`.
+     */
+    events?: Partial<{
+        [Event in keyof AuthorizationManager['events']]: Parameters<AuthorizationManager['events'][Event]['addListener']>[0];
+    }>;
+};
+/**
+ * Provides management of Globus authorization context for your application.
+ * - Handles the OAuth protcol flow (via PKCE)
+ * - Token lifecycle management
+ * - Common errors (e.g., `ConsentRequired`, `authorization_requirements`)
+ *
+ * Once you configure your instance, you can determine the authenticated state using `manager.authenticated`.
+ *
+ * To prompt a user to authenticate, call `manager.login()` on user interaction – this will initiate the OAuth protocol flow with your configured client and scopes, resulting in an initial redirect to Globus Auth.
+ *
+ * Once the user authenticates with Globus Auth, they will be redirected to your application using the configured `redirect` URL. On this URL, you will need to call `manager.handleCodeRedirect` (using a manager instance configured in the same manner that initiated the `manager.login()` call) to complete the PKCE flow, exchanging the provided code for a valid token, or tokens.
+ *
+ * All tokens managed by the `AuthorizationManager` instance can be found on `manager.token`.
+ *
+ * ### Registering your Globus Application
+ *
+ * The `AuthorizationManager` expects your Globus Application to be registered as an OAuth public client.
+ * In this Globus Web Application, this option is referenced as "_Register a thick client or script that will be installed and run by users on their devices_".
+ *
+ * @example <caption>Creating an AuthorizationManager instance.</caption>
+ * import { authorization } from "globus/sdk";
+ *
+ * const manager = authorization.create({
+ *  // Your registered Globus Application client ID.
+ *  client: '...',
+ *  // The redirect URL for your application; Where you will call `manager.handleCodeRedirect()`
+ *  redirect: 'https://example.com/callback',
+ *  // Known scopes required by your application.
+ *  scopes: 'urn:globus:auth:scope:transfer.api.globus.org:all',
+ * });
+ */
+export declare class AuthorizationManager {
+    #private;
+    configuration: AuthorizationManagerConfiguration;
+    /**
+     * The `AuthorizationManager` is considered `authenticated` if it has a valid Globus Auth token.
+     * It does not necessarily mean that it has a valid token for a specific resource server.
+     */
+    get authenticated(): boolean;
+    /**
+     * Set the authenticated state and emit the `authenticated` event.
+     */
+    set authenticated(value: boolean);
+    tokens: TokenLookup;
+    events: {
+        /**
+         * Emitted when the authenticated state changes.
+         * @event AuthorizationManager.events#authenticated
+         * @type {object}
+         * @property {boolean} isAuthenticated - Whether the `AuthorizationManager` is authenticated.
+         * @property {TokenResponse} [token] - The token response if the `AuthorizationManager` is authenticated.
+         */
+        authenticated: Event<"authenticated", {
+            /**
+             * Whether the `AuthorizationManager` is authenticated.
+             * @see {@link AuthorizationManager.authenticated}
+             */
+            isAuthenticated: boolean;
+            token?: TokenResponse;
+        }>;
+        /**
+         * Emitted when the user revokes their authentication.
+         * @event AuthorizationManager.events#revoke
+         */
+        revoke: Event<"revoke", unknown>;
+    };
+    constructor(configuration: AuthorizationManagerConfiguration);
+    get storageKeyPrefix(): string;
+    /**
+     * The user information decoded from the `id_token` (JWT) of the current Globus Auth token.
+     * This method can be used instead of `auth.oauth2.userinfo` to get the user information without an additional request.
+     *
+     * **IMPORTANT**: The `id_token` can only be processed if the `openid` scope is requested during the authorization process.
+     *
+     * Additionally, the `profile` and `email` scopes are required to get the full user information.
+     *
+     * @see {@link https://docs.globus.org/api/auth/reference/#oidc_userinfo_endpoint}
+     */
+    get user(): JwtUserInfo | null;
+    /**
+     * Attempt to refresh all of the tokens managed by the instance.
+     * This method will only attempt to refresh tokens that have a `refresh_token` attribute.
+     */
+    refreshTokens(): Promise<PromiseSettledResult<TokenResponse | null>[]>;
+    /**
+     * Use the `refresh_token` attribute of a token to obtain a new access token.
+     * @param token The well-formed token with a `refresh_token` attribute.
+     */
+    refreshToken(token: TokenWithRefresh): Promise<TokenResponse | null>;
+    /**
+     * Whether or not the instance has a reference to a Globus Auth token.
+     */
+    hasGlobusAuthToken(): boolean;
+    /**
+     * Retrieve the Globus Auth token managed by the instance.
+     */
+    getGlobusAuthToken(): any;
+    /**
+     * Reset the authenticated state and clear all tokens from storage.
+     * This method **does not** emit the `revoke` event. If you need to emit the `revoke` event, use the `AuthorizationManager.revoke` method.
+     */
+    reset(): void;
+    /**
+     * Initiate the login process by redirecting to the Globus Auth login page.
+     */
+    login(options?: {
+        additionalParams: {};
+    }): void;
+    /**
+     * This method will attempt to complete the PKCE protocol flow.
+     */
+    handleCodeRedirect(options?: {
+        shouldReplace: GetTokenOptions['shouldReplace'];
+        additionalParams?: RedirectTransportOptions['params'];
+    }): Promise<void>;
+    /**
+     * Handle an error response from a Globus service in the context of this `AuthorizationManager`.
+     * This method will introspect the response and attempt to handle any errors that should result
+     * in some additional Globus Auth interaction.
+     * @param response The error response from a Globus service.
+     * @param {object|boolean} options Options for handling the error response. If a boolean is provided, this will be treated as the `options.execute` value.
+     * @param options.execute Whether to execute the handler immediately.
+     * @param options.additionalParms Additional query parameters to be included with the transport generated URL.
+     */
+    handleErrorResponse(response: Record<string, unknown>, options?: {
+        execute?: true;
+        additionalParams?: RedirectTransportOptions['params'];
+    } | true): void;
+    handleErrorResponse(response: Record<string, unknown>, options?: {
+        execute?: false;
+        additionalParams?: RedirectTransportOptions['params'];
+    } | false): () => void;
+    /**
+     * Process a well-formed Authorization Requirements error response from a Globus service
+     * and redirect the user to the Globus Auth login page with the necessary parameters.
+     */
+    handleAuthorizationRequirementsError(response: AuthorizationRequirementsError, options?: {
+        additionalParams?: RedirectTransportOptions['params'];
+    }): void;
+    /**
+     * Process a well-formed `ConsentRequired` error response from a Globus service
+     * and redirect the user to the Globus Auth login page with the necessary parameters.
+     */
+    handleConsentRequiredError(response: ConsentRequiredError, options?: {
+        additionalParams?: RedirectTransportOptions['params'];
+    }): void;
+    /**
+     * Add a Globus Auth token response to storage, if `other_tokens` are present they are also added.
+     * This method is mostly used internally by the `AuthorizationManager`, but can be used by downstream
+     * consumers to add tokens to storage if necessary.
+     */
+    addTokenResponse: (token: Token | TokenResponse) => void;
+    /**
+     * Call `AuthroizationManager.reset`, revoke all of the available tokns, and emit the `revoke` event.
+     * @emits AuthorizationManager.events#revoke
+     * @see AuthorizationManager.reset
+     */
+    revoke(): Promise<void>;
+}
+//# sourceMappingURL=AuthorizationManager.d.ts.map

package/dist/cjs/core/authorization/AuthorizationManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthorizationManager.d.ts","sourceRoot":"","sources":["../../../../src/core/authorization/AuthorizationManager.ts"],"names":[],"mappings":"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"}