@esri/hub-common 9.13.1 → 9.15.0

package/dist/types/ArcGISContext.d.ts

@@ -1,98 +1,320 @@
-import { UserSession } from "@esri/arcgis-rest-auth";
-import { IArcGISContextState } from "./ArcGISContextState";
+import { IUser, IUserRequestOptions, UserSession } from "@esri/arcgis-rest-auth";
+import { IPortal } from "@esri/arcgis-rest-portal";
+import { IRequestOptions } from "@esri/arcgis-rest-request";
+import { IHubRequestOptions } from ".";
 /**
- * Options that can be passed into `ArcGISContext.create`
+ * Defines the properties of the ArcGISContext.
+ * Typically components or functions will get an instance
+ * of `ArcGISContext` from `ArcGISContetManager`.
+ *
+ * `ArcGISContext` implements this interface, and uses
+ * getters to simplify the derivation of various complex properties.
+ *
+ */
+export interface IArcGISContext {
+    /**
+     * Unique id from the ArcGISContextManager that created
+     * this instance. Primarily useful for debugging possible
+     * race-conditions that can result in multiple ArcGISContextManager
+     * instances being created.
+     */
+    id: number;
+    /**
+     * Return the UserSession if authenticated
+     */
+    session: UserSession;
+    /**
+     * Return boolean indicating if authenticatio is present
+     */
+    isAuthenticated: boolean;
+    /**
+     * Return `IUserRequestOptions`, which is used for REST-JS
+     * functions which require authentication information.
+     *
+     * If context is not authenticated, this function will return `undefined`
+     */
+    userRequestOptions: IUserRequestOptions;
+    /**
+     * Return `IRequestOptions`, which is used by REST-JS functions
+     * which *may* use authentication information if provided.
+     *
+     * If context is not authenticated, this function just returns
+     * the `portal` property, which informs REST-JS what Sharing API
+     * instance to use (i.e. AGO, Enterprise etc)
+     */
+    requestOptions: IRequestOptions;
+    /**
+     * Return a `IHubRequestOptions` object
+     *
+     * If context is not authenticated, this function will return `undefined`
+     */
+    hubRequestOptions: IHubRequestOptions;
+    /**
+     * Return the portal url.
+     *
+     * If authenticated @ ArcGIS Online, it will return
+     * the https://org.env.arcgis.com
+     *
+     * If authenticated @ ArcGIS Enterprise, it will return
+     * https://{portalHostname}/{webadaptor}
+     */
+    portalUrl: string;
+    /**
+     * Returns the url to the sharing api composed from portalUrl
+     * i.e. https://myorg.maps.arcgis.com/sharing/rest
+     */
+    sharingApiUrl: string;
+    /**
+     * Returns the Hub url, based on the portalUrl
+     *
+     * For ArcGIS Enterprise this will return `undefined`
+     */
+    hubUrl: string;
+    /**
+     * Returns boolean indicating if the backing system
+     * is ArcGIS Enterprise (formerly ArcGIS Portal) or not
+     */
+    isPortal: boolean;
+    /**
+     * Returns the discussions API URL
+     */
+    discussionsServiceUrl: string;
+    /**
+     * Returns the Hub Search API URL
+     */
+    hubSearchServiceUrl: string;
+    /**
+     * Returns Hub Domain Service URL
+     */
+    domainServiceUrl: string;
+    /**
+     * Returns the Events configuration object from portal/self
+     *
+     * `{serviceId: '3ef..', publicViewId: 'bc3...'}`
+     */
+    eventsConfig: any;
+    /**
+     * Returns boolean indicating if the current user
+     * belongs to an organization that has licensed
+     * ArcGIS Hub
+     */
+    hubEnabled: boolean;
+    /**
+     * Return Hub Community Org Id, if defined
+     */
+    communityOrgId: string;
+    /**
+     * Returns the Community Org Hostname, if defined
+     */
+    communityOrgHostname: string;
+    /**
+     * Returns the Hub Community Org url
+     *
+     * i.e. https://c-org.maps.arcgis.com
+     */
+    communityOrgUrl: string;
+    /**
+     * Returns the hash of helper services from portal self
+     */
+    helperServices: any;
+    /**
+     * Returns the current user
+     */
+    currentUser: IUser;
+    /**
+     * Returns the portal object
+     */
+    portal: IPortal;
+    /**
+     * Additional app-specific context
+     */
+    properties: Record<string, any>;
+}
+/**
+ * Options for the ArcGISContext constructor
  */
 export interface IArcGISContextOptions {
     /**
-     * Existing user session, which may be created from Identity Manager
-     * `const session = UserSession.fromCredential(idMgr.getCredential());`
+     * Unique id from the ArcGISContextManager that created
+     * this instance. Primarily useful for debugging possible
+     * race-conditions that can result in multiple ArcGISContextManager
+     * instances being created.
+     */
+    id: number;
+    /**
+     * Portal base url
+     * For ArcGIS Online - https://org.env.arcgis.com
+     * For ArcGIS Enterprise - https://{portalHostname}/{webadaptor}
+     */
+    portalUrl: string;
+    /**
+     * Hub Url that corresponds to the portal url is appropritate
+     */
+    hubUrl?: string;
+    /**
+     * The current UserSession
      */
     authentication?: UserSession;
     /**
-     * ArcGIS Online or ArcGIS Enterprise portal url.
-     * Do not include  `/sharing/rest`
-     * Defaults to `https://www.arcgis.com`
-     * For ArcGIS Enterprise, you must include the webadaptor name.
-     * i.e. https://gis.mytown.gov/portal
+     * If the user is authenticated, the portal should be passed in
+     * so various getters can work as expected.
      *
-     * When Authentication is present, the UserSession.portal value is
-     * used instead of this property.
+     * ArcGISContextManager handles this internally
      */
-    portalUrl?: string;
+    portalSelf?: IPortal;
     /**
-     * If set to `true` additional logging will be sent to the console
-     * Defaults to false.
+     * If the user is authenticated, the user should be passed in
+     * so various getters can work as expected.
+     *
+     * ArcGISContextManager handles this internally
      */
-    debug?: boolean;
+    currentUser?: IUser;
+    /**
+     * Optional hash of additional context
+     */
+    properties?: Record<string, any>;
 }
 /**
- * Application Context Object
- *
- * Abstraction that combines a `UserSession` with
- * the `portal/self` and `user/self` responses to
- * provide a central lookup of platform information.
+ * Abstraction that holds a `UserSession`, along with
+ * getters to streamline access to various platform
+ * urls, and common constructs like `IRequestOptions`,
+ * `IUserRequestOptions` etc.
  *
- * This is a work-in-progress, and will likely expand over time.
+ * Instances are intended to be immutable, but this is not directly enforced.
  *
- * `ArcGISContext` is used in conjuction with the `arcgis-app-identity`
- * component to orchestrate oAuth.
+ * In most circumstances, this class should be created by
+ * the ArcGISContextManager class.
  */
-export declare class ArcGISContext {
+export declare class ArcGISContext implements IArcGISContext {
     /**
-     * Random identifier useful for debugging issues
-     * where race-conditions can result in multiple
-     * contexts getting created
+     * Unique id from the ArcGISContextManager that created
+     * this instance. Primarily useful for debugging possible
+     * race-conditions that can result in multiple ArcGISContextManager
+     * instances being created.
      */
     id: number;
-    private _state;
     private _authentication;
     private _portalUrl;
     private _hubUrl;
     private _portalSelf;
     private _currentUser;
-    private _debug;
+    private _properties;
     /**
-     * Private constructor. Use `ArcGISContext.create(...)` to
-     * instantiate an instance
+     * Create a new instance of `ArcGISContext`.
+     *
      * @param opts
      */
-    private constructor();
+    constructor(opts: IArcGISContextOptions);
     /**
-     * Static async Factory
-     * @param opts
-     * @returns
+     * Return the UserSession if authenticated
+     */
+    get session(): UserSession;
+    /**
+     * Return boolean indicating if authenticatio is present
+     */
+    get isAuthenticated(): boolean;
+    /**
+     * Return `IUserRequestOptions`, which is used for REST-JS
+     * functions which require authentication information.
+     *
+     * If context is not authenticated, this function will throw
+     */
+    get userRequestOptions(): IUserRequestOptions;
+    /**
+     * Return `IRequestOptions`, which is used by REST-JS functions
+     * which *may* use authentication information if provided.
+     *
+     * If context is not authenticated, this function just returns
+     * the `portal` property, which informs REST-JS what Sharing API
+     * instance to use (i.e. AGO, Enterprise etc)
+     */
+    get requestOptions(): IRequestOptions;
+    /**
+     * Return a `IHubRequestOptions` object
+     */
+    get hubRequestOptions(): IHubRequestOptions;
+    /**
+     * Return the portal url i.e. https://www.arcgis.com
+     *
+     * If authenticated @ ArcGIS Online, it will return
+     * the https://org.env.arcgis.com
+     *
+     * If authenticated @ ArcGIS Enterprise, it will return
+     * https://{portalHostname}/{webadaptor}
+     */
+    get portalUrl(): string;
+    /**
+     * Returns the url to the sharing api composed from portalUrl
+     * i.e. https://myorg.maps.arcgis.com/sharing/rest
+     */
+    get sharingApiUrl(): string;
+    /**
+     * Returns the Hub url, based on the portalUrl
+     *
+     * For ArcGIS Enterprise this will return `undefined`
+     */
+    get hubUrl(): string;
+    /**
+     * Returns boolean indicating if the backing system
+     * is ArcGIS Enterprise (formerly ArcGIS Portal) or not
+     */
+    get isPortal(): boolean;
+    /**
+     * Returns the discussions API URL
+     */
+    get discussionsServiceUrl(): string;
+    /**
+     * Returns the Hub Search API URL
      */
-    static create(opts?: IArcGISContextOptions): Promise<ArcGISContext>;
+    get hubSearchServiceUrl(): string;
     /**
-     * If we have a UserSession, fetch portal/self and
-     * store that along with current user
+     * Returns Hub Domain Service URL
+     */
+    get domainServiceUrl(): string;
+    /**
+     * Returns the Events configuration object from portal/self
+     *
+     * `{serviceId: '3ef..', publicViewId: 'bc3...'}`
+     */
+    get eventsConfig(): any;
+    /**
+     * Returns boolean indicating if the current user
+     * belongs to an organization that has licensed
+     * ArcGIS Hub
+     */
+    get hubEnabled(): boolean;
+    /**
+     * Return the Hub Community Org Id, if defined
+     */
+    get communityOrgId(): string;
+    /**
+     * Returns the Hub Community Org Hostname, if defined
+     *
+     * i.e. c-org.maps.arcgis.com
+     */
+    get communityOrgHostname(): string;
+    /**
+     * Returns the Hub Community Org url
+     *
+     * i.e. https://c-org.maps.arcgis.com
      */
-    initialize(): Promise<void>;
+    get communityOrgUrl(): string;
     /**
-     * Set the Authentication (UserSession) for the context.
-     * This should be called when a user signs into a running
-     * application.
-     * @param auth
+     * Returns the hash of helper services from portal self
      */
-    setAuthentication(auth: UserSession): Promise<void>;
+    get helperServices(): any;
     /**
-     * Clear the Authentication (UserSession). This should be
-     * called when a user signs out of an application, but
-     * the application continues running
+     * Returns the current user as IUser
      */
-    clearAuthentication(): void;
+    get currentUser(): IUser;
     /**
-     * Return a reference to the current state.
-     * When `.setAuthentication()` or `.clearAuthenentication()` are
-     * called, the state will be re-created. This is done so frameworks
-     * like React or Ember can detect changes.
+     * Returns the portal object as IPortal
      */
-    get state(): IArcGISContextState;
+    get portal(): IPortal;
     /**
-     * @internal
-     * Log debugging messages to the console
-     * @param message
+     * Return the properties hash that was passed in.
+     * Useful for app-specific context such as the active
+     * Site for ArcGIS Hub
      */
-    private log;
+    get properties(): Record<string, any>;
 }

package/dist/types/ArcGISContextManager.d.ts

@@ -0,0 +1,130 @@
+import { IPortal } from "@esri/arcgis-rest-portal";
+import { IUser, UserSession } from "@esri/arcgis-rest-auth";
+import { IArcGISContext } from "./ArcGISContext";
+import { Level } from ".";
+/**
+ * Options that can be passed into `ArcGISContextManager.create`
+ */
+export interface IArcGISContextManagerOptions {
+    /**
+     * Existing user session, which may be created from Identity Manager
+     * `const session = UserSession.fromCredential(idMgr.getCredential());`
+     */
+    authentication?: UserSession;
+    /**
+     * ArcGIS Online or ArcGIS Enterprise portal url.
+     * Do not include  `/sharing/rest`
+     * Defaults to `https://www.arcgis.com`
+     * For ArcGIS Enterprise, you must include the webadaptor name.
+     * i.e. https://gis.mytown.gov/portal
+     *
+     * When Authentication is present, the UserSession.portal value is
+     * used instead of this property.
+     */
+    portalUrl?: string;
+    /**
+     * Portal self for the authenticated user. If not passed into `.create`
+     * with the UserSession, it will be fetched
+     */
+    portal?: IPortal;
+    /**
+     * Current user as `IUser`. If not passed into `.create` with the UserSession
+     * it will be fetched.
+     */
+    currentUser?: IUser;
+    /**
+     * Any additional properties to expose on the context. This allows
+     * an application to send additional context into the system.
+     * For example, in ArcGIS Hub, many times we want to pass in the
+     * active "Hub Site" as additional context, so we will send that in
+     * as a node on a properties object.
+     */
+    properties?: Record<string, any>;
+    /**
+     * Logging level
+     * off > error > warn > info > debug > all
+     * defaults to 'error'
+     */
+    logLevel?: Level;
+}
+/**
+ * The manager exposes context (`IArcGISContext`), which combines a `UserSession` with
+ * the `portal/self` and `user/self` responses to provide a central lookup for platform
+ * information, api urls, and other useful properties for developers such as IRequestOptions
+ * IUserRequestOptions, IHubRequestOptions etc.
+ *
+ * The context is exposed on gthe `.context` property, and as the authentication changes
+ * the `.context` is re-created. This is done to allow web frameworks to watch for
+ * changes on that single property, instead of having to leverage observers or events
+ * for change detection.
+ *
+ * Please see the [ArcGISContext Guide](/hub.js/guides/context) for additional information.
+ *
+ */
+export declare class ArcGISContextManager {
+    /**
+     * Random identifier useful for debugging issues
+     * where race-conditions can result in multiple
+     * contexts getting created
+     */
+    id: number;
+    private _context;
+    private _authentication;
+    private _portalUrl;
+    private _properties;
+    private _hubUrl;
+    private _portalSelf;
+    private _currentUser;
+    private _logLevel;
+    /**
+     * Private constructor. Use `ArcGISContextManager.create(...)` to
+     * instantiate an instance
+     * @param opts
+     */
+    private constructor();
+    /**
+     * Used to create a new instance of the ArcGISContext class.
+     *
+     * ```js
+     * const ctxMgr = await ArcGISContextManager.create();
+     * ```
+     *
+     * @param opts
+     * @returns
+     */
+    static create(opts?: IArcGISContextManagerOptions): Promise<ArcGISContextManager>;
+    /**
+     * Set the Authentication (UserSession) for the context.
+     * This should be called when a user signs into a running
+     * application.
+     * @param auth
+     */
+    setAuthentication(auth: UserSession): Promise<void>;
+    /**
+     * Set the properties hash and re-create the context
+     * @param properties
+     */
+    setProperties(properties: Record<string, any>): void;
+    /**
+     * Clear the Authentication (UserSession). This should be
+     * called when a user signs out of an application, but
+     * the application continues running
+     */
+    clearAuthentication(): void;
+    /**
+     * Return a reference to the current state.
+     * When `.setAuthentication()` or `.clearAuthenentication()` are
+     * called, the state will be re-created. This is done so frameworks
+     * like React or Ember can detect changes.
+     */
+    get context(): IArcGISContext;
+    /**
+     * If we have a UserSession, fetch portal/self and
+     * store that along with current user
+     */
+    private initialize;
+    /**
+     * Getter to streamline the creation of updated Context instances
+     */
+    private get contextOpts();
+}

package/dist/types/Hub.d.ts

@@ -0,0 +1,72 @@
+import { ArcGISContextManager, IArcGISContextManagerOptions } from "./ArcGISContextManager";
+import { HubProjectManager } from "./projects/HubProjectManager";
+/**
+ * Options for instantiating a Hub instance
+ */
+export interface IHubOptions {
+    contextManager?: ArcGISContextManager;
+    managerOptions?: IArcGISContextManagerOptions;
+    authOptions?: {
+        usename: string;
+        password: string;
+        portalUrl?: string;
+    };
+}
+/**
+ * Hub class can be used as an entry point to managing
+ * content, teams, sites, projects etc, in an organization's Hub.
+ *
+ * ```js
+ * import {Hub} from '@esri/hub-common';
+ * // create a Hub instance, authenticating as a specific user
+ * // working against arcgis online
+ * const myHub = await Hub.create({authOptions: {username: "casey", password: "jones"}});
+ *
+ * myHub.context.currentUser //=> {username: "casey", ...} as IUser
+ *
+ * const projectStore = await myHub.getProjectStore();
+ *
+ * const pavingProject = await projectStore.create({name: "12th Street Paving"});
+ * pavingProject.summary = "This is the 2024 planned paving of 12th Street, between 8th and 11th Ave";
+ * await projectStore.update(pavingProject);
+ * ```
+ *
+ * This is a convenience class. Hub Stores can be created
+ * directly, or the underlying functions can be imported an used
+ * as need for scenarios where these class structures introduce
+ * unwanted complexity
+ */
+export declare class Hub {
+    /**
+     * Hold a context manager, which should be a single instance for
+     * an application. When authentication changes, the .context
+     * property on the context manager will be replaced. As long as
+     * all the fns in this class leverage properties on .context
+     * everything be kept in sync.
+     */
+    private _contextManager;
+    private _projectManager;
+    /**
+     * Private so we can employ a factory function should we need
+     * async work during creation
+     * @param contextManager
+     */
+    private constructor();
+    /**
+     * Factory function to construct a new HubProjectStore instance.
+     *
+     * Note: Used so that we could do async actions in the ctor.
+     * @param contextManager
+     * @returns
+     */
+    static create(options: IHubOptions): Promise<Hub>;
+    /**
+     * Getter to abstract the context manager
+     */
+    get context(): import("./ArcGISContext").IArcGISContext;
+    /**
+     * Create a Project Store connected to the current Hub
+     * @returns
+     */
+    get projects(): HubProjectManager;
+}

package/dist/types/HubError.d.ts

@@ -0,0 +1,17 @@
+import { OperationError } from ".";
+/**
+ * Generic Hub Error with an Error stack as well
+ * as an optional serialized OperationStack.
+ *
+ * Also accepts a `rootCause` Error object
+ */
+export default class HubError extends OperationError {
+    /**
+     * Creates an instance of HubError.
+     * @param {string} operation
+     * @param {string} [message]
+     * @param {Error} [rootCause]
+     * @memberof HubError
+     */
+    constructor(operation: string, message?: string, rootCause?: Error);
+}

package/dist/types/collections.d.ts

@@ -1,3 +1,15 @@
+/**
+ * ```js
+ * import { getCollection } from "@esri/hub-common";
+ * //
+ * getCollection('Feature Layer')
+ * > 'dataset'
+ * ```
+ * Get the Hub collection for a given item type
+ * @param itemType The ArcGIS [item type](https://developers.arcgis.com/rest/users-groups-and-items/items-and-item-types.htm).
+ * @returns the Hub collection of a given item type.
+ */
+export declare const getCollection: (type?: string) => string;
 export declare const collections: {
     [key: string]: string[];
 };