@esri/hub-common 9.10.1 → 9.10.2

package/dist/types/OperationStack.d.ts

@@ -0,0 +1,201 @@
+import { IOperation, ISerializedOperationStack } from "./types";
+/**
+ * Allows an application to track a series of operations, storing information
+ * about the arguments passes in and the results returned
+ *
+ * ```js
+ * import { OperationStack } from '@esri/solution-common';
+ *
+ * const stack = new OperationStack();
+ *
+ * // start an operation by type
+ * const id = stack.start('getItem');
+ * //.. work happens...
+ * stack.finish(id);
+ *
+ * // start an operation with an Operation object
+ * stack.start({
+ *   id: 'createItem_1',
+ *   type: 'createItem',
+ *   inputs: {
+ *    item: {...truncated...},
+ *    portal: 'https://www.arcgis.com',
+ *    username: 'jsmith'
+ *   },
+ * });
+ * // make the call
+ * stack.finish('createItem_1', {newItemId: '00cf213'});
+ *
+ * // later you can get that information back out of the stack
+ * const prevOp = stack.getOperation('createItem_1);
+ *
+ * // and if you need to roll back you can use the
+ * // .cleanup and .output properties to help orchestrate
+ *
+ * ```
+ *
+ *
+ * Can be used to implement "atomic" operations in an environment that does not
+ * have this as a core feature
+ */
+export default class OperationStack {
+    /**
+     * Internal array of Operations
+     *
+     * @private
+     * @type {IOperation[]}
+     * @memberof OperationStack
+     */
+    private operations;
+    /**
+     * Creates an instance of OperationStack.
+     * @memberof OperationStack
+     */
+    constructor();
+    /**
+     * Start an Operation
+     *
+     * ```js
+     * const stack = new OperationStack();
+     * stack.startOperation({
+     *  id: 'get-bc3',
+     *  type: 'getItem',
+     *  cleanup: 'n/a',
+     *  inputs: {
+     *    id: 'bc3',
+     *    owner: 'vader'
+     *  }
+     * });
+     * // do work
+     * stack.finish('get-bc3');
+     * ```
+     *
+     *
+     * @param {IOperation} operation
+     * @memberof OperationStack
+     */
+    startOperation(operation: IOperation): void;
+    /**
+     * Start an operation without requiring a full operation
+     *
+     * ```js
+     * const opId = stack.start('getItems');
+     * //...work happens
+     * stack.finish(opId);
+     * ```
+     *
+     * @param {string} type Type of the operation. i.e. getItem
+     * @param {Record<string, unknown>} [params] optionally pass in id, inputs, cleanup
+     * @returns {string} Identifier of the new stack entry
+     * @memberof OperationStack
+     */
+    start(type: string, params?: Record<string, unknown>): string;
+    /**
+     * Returns a reference to an Operation
+     *
+     * @param {string} id Unique Identifier
+     * @returns {Operation}
+     * @memberof OperationStack
+     */
+    getOperation(id: string): IOperation;
+    /**
+     * Returns reference to the operations array
+     *
+     * @returns {Operation[]}
+     * @memberof OperationStack
+     */
+    getOperations(): IOperation[];
+    /**
+     * Inform the stack that an operation has finished.
+     *
+     * This will append in a duration property, and mark
+     * the state as 'completed'.
+     *
+     * @param {string} id Unique identifier of the Operation
+     * @param {Record<string, unknown>} [options] outputs
+     * @memberof OperationStack
+     */
+    finish(id: string, options?: Record<string, unknown>): void;
+    /**
+     * Merge a serialized operation stack into
+     * a stack instance
+     *
+     * ```js
+     *    import { OperationStack } from '@esri/solution-common';
+     *    function someFunction() {
+     *      const stack = new OperationStack();
+     *      stack.start('getItem', {id: 'get-bc3'});
+     *      // do some work...
+     *      stack.finish('get-bc3');
+     *
+     *      const itm = {title: 'Fake Item', type: 'Web Map'};
+     *      // create an entry for the function we are about to call...
+     *      stack.start('createItem', {id: 'createItem_01', inputs: {item: itm}});
+     *      // call a function that does work, and has it's own stack
+     *      // and returns a serialized version as part of it's results
+     *      return createItem(itm)
+     *      .then((result) => {
+     *        // tell the stack the last operation finished...
+     *        stack.finish('createItem_01');
+     *        // merge in the stack from the function we called
+     *        stack.merge(result.stack);
+     *        // > stack.getCompleted().length === 3
+     *      });
+     *    }
+     *
+     *    function createItem (itm) {
+     *      const otherStack = new OperationStack();
+     *      const id = otherStack.start('createItem');
+     *      // make calls to create item etc
+     *      otherStack.finish(id, {itemId: newItem.id});
+     *      otherStack.start('protectItem', {id: 'protect-00c'});
+     *      // make call to protect item...
+     *      otherStack.finish('protect-00c');
+     *      // all done... return a result with a stack
+     *      return Promise.resolve({
+     *        success:true,
+     *        stack: otherStack.serialize()
+     *      });
+     *    }
+     * ```
+     *
+     *  Typically used to create a comprehensive list of operations
+     *  when a function returns a `SerializedOperationStack` as part of
+     *  it's response
+     *
+     *
+     * @param {ISerializedOperationStack} stack
+     * @memberof OperationStack
+     */
+    merge(stack: ISerializedOperationStack): void;
+    /**
+     * Get a list of the completed operations
+     *
+     * @returns {IOperation[]}
+     * @memberof OperationStack
+     */
+    getCompleted(): IOperation[];
+    /**
+     *  Return an array of working operations
+     *
+     * @returns {IOperation[]}
+     * @memberof OperationStack
+     */
+    getWorking(): IOperation[];
+    /**
+     * Serialize the completed operations into a set of
+     * human readable messages, sorted by the startedAt timestamp
+     *
+     *
+     * @returns {string}
+     * @memberof IOperationStack
+     */
+    toString(): string;
+    /**
+     * Serialize the stack into simple objects
+     *
+     * @returns {ISerializedOperationStack}
+     * @memberof OperationStack
+     */
+    serialize(): ISerializedOperationStack;
+}

package/dist/types/access/can-edit-event.d.ts

@@ -0,0 +1,13 @@
+import { IUser } from "@esri/arcgis-rest-types";
+import { IInitiativeModel } from "../types";
+export interface IEventModel {
+    initiative: IInitiativeModel;
+    [propName: string]: any;
+}
+/**
+ * Checks if user has access to edit an event in Hub
+ * @param {IEventModel} model consolidated event model as consumed by Hub, contains the event feature, related initiative model, and attendees group
+ * @param {IUser} user
+ * @returns {boolean}
+ */
+export declare function canEditEvent(model: IEventModel, user: IUser): boolean;

package/dist/types/access/can-edit-item.d.ts

@@ -0,0 +1,8 @@
+import { IItem, IUser } from "@esri/arcgis-rest-types";
+/**
+ * Checks if user has access to edit an item in Hub
+ * @param {IItem} item
+ * @param {IUser} user
+ * @returns {boolean}
+ */
+export declare function canEditItem(item: IItem, user: IUser): boolean;

package/dist/types/access/can-edit-site-content.d.ts

@@ -0,0 +1,11 @@
+import { IItem, IUser } from "@esri/arcgis-rest-types";
+export declare const REQUIRED_PRIVS: string[];
+/**
+ * Checks if user has access to content library in Hub
+ * In Hub Home context, user access requires additional privileges
+ * In initiative context, check is delegated to canEditItem for the initiative site item
+ * @param {IItem} item
+ * @param {IUser} user
+ * @returns {boolean}
+ */
+export declare function canEditSiteContent(item: IItem, user: IUser): boolean;

package/dist/types/access/can-edit-site.d.ts

@@ -0,0 +1,10 @@
+import { IItem, IUser } from "@esri/arcgis-rest-types";
+/**
+ * Checks if user has access to edit site in Hub
+ * Currently, Hub Home sites are not editable
+ * In initiative context, check is delegated to canEditItem for the initiative site item
+ * @param {IItem} model
+ * @param {IUser} user
+ * @returns {boolean}
+ */
+export declare function canEditSite(model: IItem, user: IUser): boolean;

package/dist/types/access/has-base-priv.d.ts

@@ -0,0 +1,7 @@
+import { IUser } from "@esri/arcgis-rest-types";
+/**
+ * Checks for fundamental privilege required by all access checks
+ * @param {IUser} user
+ * @returns {boolean}
+ */
+export declare function hasBasePriv(user: IUser): boolean;

package/dist/types/access/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./can-edit-event";
+export * from "./can-edit-item";
+export * from "./can-edit-site-content";
+export * from "./can-edit-site";
+export * from "./has-base-priv";

package/dist/types/api.d.ts

@@ -0,0 +1,15 @@
+import { IRequestOptions } from "@esri/arcgis-rest-request";
+import { IPortal } from "@esri/arcgis-rest-portal";
+import { IHubRequestOptions } from "./types";
+/**
+ * ```js
+ * import { getHubApiUrl() } from "@esri/hub-common";
+ * //
+ * getHubApiUrl({ portal: "https://custom.maps.arcgis.com/sharing/rest" })
+ * >> "https://hub.arcgis.com"
+ * ```
+ * Retrieves the Hub API Url associated with a specific ArcGIS Online organization.
+ * @param urlOrObject a Portal URL, Portal API URL, request options object, or Portal self object
+ * @returns the associated Hub API Url as a string.
+ */
+export declare function getHubApiUrl(urlOrObject: IPortal | IHubRequestOptions | IRequestOptions | string): string;

package/dist/types/auth.d.ts

@@ -0,0 +1,5 @@
+import { UserSession, IOAuth2Options } from "@esri/arcgis-rest-auth";
+/**
+ * A thin wrapper around [`UserSession.completeOAuth2()`](https://esri.github.io/arcgis-rest-js/api/auth/UserSession/#completeOAuth2) that sets search tags and other relevant metadata for newly created community users.
+ */
+export declare function completeOAuth2(options: IOAuth2Options, win?: any): Promise<UserSession>;

package/dist/types/categories.d.ts

@@ -0,0 +1,9 @@
+import { IItem } from "@esri/arcgis-rest-types";
+export declare const categories: {
+    [key: string]: string[];
+};
+/**
+ * Is the item type downloadable in the Hub app
+ * @param item ArcGIS item with type and type keywords
+ */
+export declare function isDownloadable(item: IItem): boolean;

package/dist/types/collections.d.ts

@@ -0,0 +1,3 @@
+export declare const collections: {
+    [key: string]: string[];
+};

package/dist/types/content/_internal.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Use this module for functions that do not need to be used by consumers (yet),
+ * but may be shared between hub.js modules, and/or need to be tested
+ * to get 100% coverage w/o writing cumbersome tests of higher level functions.
+ *
+ * Consuming will not be able to import these functions.
+ *
+ * It's probably a good pattern to add functions here first and then
+ * move them to index.ts only when they are needed by a consumer.
+ */
+import { BBox, IHubContent, IHubGeography, GeographyProvenance } from "../types";
+/**
+ * Create a new content with updated boundary properties
+ * @param content original content
+ * @param boundary boundary provenance
+ * @returns
+ */
+export declare const setContentBoundary: (content: IHubContent, boundary: GeographyProvenance) => {
+    boundary: IHubGeography;
+    item: any;
+    hubId?: string;
+    permissions: {
+        visibility: "private" | "public" | "org";
+        control?: import("../types").AccessControl;
+        groups?: import("@esri/arcgis-rest-types").IGroup[];
+    };
+    family?: import("../types").HubFamily;
+    itemCategories?: string[];
+    normalizedType?: string;
+    publishedDate: Date;
+    publishedDateSource?: string;
+    updateFrequency?: string;
+    actionLinks?: import("../types").IActionLink[];
+    hubActions?: object;
+    metrics?: {
+        visibility: "private" | "public" | "org" | "updateGroups";
+    };
+    slug?: string;
+    portalDataUrl?: string;
+    groupIds?: string[];
+    errors?: import("../types").IEnrichmentErrorInfo[];
+    data?: {
+        [propName: string]: any;
+    };
+    server?: Partial<import("@esri/arcgis-rest-types").IFeatureServiceDefinition>;
+    layers?: Partial<import("@esri/arcgis-rest-types").ILayerDefinition>[];
+    layer?: Partial<import("@esri/arcgis-rest-types").ILayerDefinition>;
+    recordCount?: number;
+    orgId?: string;
+    org?: Partial<import("@esri/arcgis-rest-portal").IPortal>;
+    isDownloadable: boolean;
+    structuredLicense?: import("..").IStructuredLicense;
+    name: string;
+    summary?: string;
+    hubType: import("../types").HubType;
+    createdDate: Date;
+    createdDateSource?: string;
+    updatedDate: Date;
+    updatedDateSource?: string;
+    portalHomeUrl?: string;
+    portalApiUrl?: string;
+    thumbnailUrl?: string;
+    metadata?: any;
+    id: string;
+    owner: string;
+    tags: string[];
+    created: number;
+    modified: number;
+    numViews: number;
+    size: number;
+    protected?: boolean;
+    title: string;
+    type: string;
+    typeKeywords?: string[];
+    description?: string;
+    snippet?: string;
+    documentation?: string;
+    extent?: number[][];
+    categories?: string[];
+    spatialReference?: import("@esri/arcgis-rest-types").ISpatialReference;
+    culture?: string;
+    properties?: any;
+    url?: string;
+};
+/**
+ * Create a new content with updated extent and derived properties like boundary
+ * @param content original content
+ * @param extent new extent
+ * @returns a new content with the updated extent and boundary
+ */
+export declare const setContentExtent: (content: IHubContent, extent: BBox) => IHubContent;

package/dist/types/content/index.d.ts

@@ -0,0 +1,238 @@
+import { ResourceObject } from "jsonapi-typescript";
+import { IItem } from "@esri/arcgis-rest-portal";
+import { HubType, HubFamily } from "../types";
+import { IHubContent, IModel } from "../types";
+/**
+ * JSONAPI dataset resource returned by the Hub API
+ */
+export declare type DatasetResource = ResourceObject<"dataset", {
+    [k: string]: any;
+}>;
+/**
+ * ```js
+ * import { getCategory } from "@esri/hub-common";
+ * //
+ * getCategory('Feature Layer')
+ * > 'dataset'
+ * ```
+ * **DEPRECATED: Use getCollection() instead**
+ * returns the Hub category 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 category of a given item type.
+ */
+export declare function getCategory(itemType?: string): string;
+/**
+ * ```js
+ * import { getTypes } from "@esri/hub-common";
+ * //
+ * getTypes('site')
+ * > [ 'hub site application' ]
+ * ```
+ * To do.
+ * @param category The ArcGIS Hub category.
+ * @returns all the item types for the given category.
+ *
+ */
+export declare function getTypes(category?: string): string[];
+/**
+ * ```js
+ * import { normalizeItemType } from "@esri/hub-common";
+ * //
+ * normalizeItemType(item)
+ * > [ 'Hub Site Application' ]
+ * ```
+ * @param item Item object.
+ * @returns type of the input item.
+ *
+ */
+export declare function normalizeItemType(item?: any): string;
+/**
+ * ```js
+ * import { getTypeCategories } from "@esri/hub-common";
+ * //
+ * getTypeCategories(item)
+ * > [ 'Hub Site Application' ]
+ * ```
+ * @param item Item object.
+ * @returns typeCategory of the input item.
+ *
+ */
+export declare function getTypeCategories(item?: any): string[];
+/**
+ * ```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 function getCollection(itemType?: string): string;
+/**
+ * Case-insensitive check if the type is "Feature Service"
+ * @param {string} type - item's type
+ * @returns {boolean}
+ */
+export declare const isFeatureService: (type: string) => boolean;
+/**
+ * parse layer id from a service URL
+ * @param {string} url
+ * @returns {string} layer id
+ */
+export declare const getLayerIdFromUrl: (url: string) => string;
+/**
+ * return the layerId if we can tell that item is a single layer service
+ * @param {*} item from AGO
+ * @returns {string} layer id
+ */
+export declare const getItemLayerId: (item: IItem) => string;
+/**
+ * given an item, get the id to use w/ the Hub API
+ * @param item
+ * @returns Hub API id (hubId)
+ */
+export declare const getItemHubId: (item: IItem) => string;
+/**
+ * ```js
+ * import { getContentIdentifier } from "@esri/hub-common";
+ * //
+ * getContentIdentifier(content, site)
+ * > 'f12hhjk32' // id
+ * // OR
+ * > 'content-slug' // human-readable slug
+ * ```
+ * Returns the preferred identifier for a piece of content (determined by content type):
+ * - Content from the 'template' and 'feedback' families return the standard id field
+ * - Pages that are linked to the site parameter will return the slug defined by the site. Otherwise, the page id will be returned
+ * - All other content will return the highest available item in the following hierarchy:
+ *   1. slug - includes org prefix if the site parameter is a portal or has an orgKey different from the slug prefix
+ *   2. hubId
+ *   3. id
+ * @param content The IHubContent item
+ * @param site The site to compare content against
+ * @returns the preferred id for the given content.
+ */
+export declare function getContentIdentifier(content: IHubContent, site?: IModel): string;
+/**
+ * Parse item ID and layer ID (if any) from dataset record ID
+ *
+ * @param datasetId Hub API dataset record id ({itemId}_{layerId} or {itemId})
+ * @returns A hash with the `itemId` and `layerId` (if any)
+ */
+export declare function parseDatasetId(datasetId: string): {
+    itemId: string;
+    layerId?: string;
+};
+/**
+ * Determine if an identifier is a Hub API slug
+ *
+ * @param identifier Hub API slug ({orgKey}::{title-as-slug} or {title-as-slug})
+ * or record id ((itemId}_{layerId} or {itemId})
+ * @returns true if the identifier is valid _and_ is **not** a record id
+ */
+export declare function isSlug(identifier: string): boolean;
+/**
+ * Add a context (prefix) to slug if it doesn't already have one
+ *
+ * @param slug Hub API slug (with or without context)
+ * @param context usually a portal's orgKey
+ * @returns slug with context ({context}::{slug})
+ */
+export declare function addContextToSlug(slug: string, context: string): string;
+/**
+ * Remove context (prefix) from a slug
+ *
+ * @param slug Hub API slug with context
+ * @param context usually a portal's orgKey
+ * @returns slug without context
+ */
+export declare function removeContextFromSlug(slug: string, context: string): string;
+/**
+ * Splits item category strings at slashes and discards the "Categories" keyword
+ *
+ * ```
+ * ["/Categories/Boundaries", "/Categories/Planning and cadastre/Property records", "/Categories/Structure"]
+ * ```
+ * Should end up being
+ * ```
+ * ["Boundaries", "Planning and cadastre", "Property records", "Structure"]
+ * ```
+ *
+ * @param categories - an array of strings
+ * @private
+ */
+export declare function parseItemCategories(categories: string[]): string[];
+/**
+ * return the Hub family given an item's type
+ * @param type item type
+ * @returns Hub family
+ */
+export declare function getFamily(type: string): HubFamily;
+/**
+ * DEPRECATED: Use getFamily() instead.
+ *
+ * get the HubType for a given item or item type
+ *
+ * @param itemOrType an item or item.type
+ */
+export declare function getItemHubType(itemOrType: IItem | string): HubType;
+/**
+ * Convert a Portal item to Hub content
+ *
+ * @param item Portal Item
+ * @returns Hub content
+ * @export
+ */
+export declare function itemToContent(item: IItem): IHubContent;
+/**
+ * Convert a Hub API dataset resource to Hub Content
+ *
+ * @param {DatasetResource} Dataset resource
+ * @returns {IHubContent} Hub content object
+ * @export
+ */
+export declare function datasetToContent(dataset: DatasetResource): IHubContent;
+/**
+ * Convert a Hub API dataset resource to a portal item
+ *
+ * @param {DatasetResource} Dataset resource
+ * @returns {IItem} portal item
+ * @export
+ */
+export declare function datasetToItem(dataset: DatasetResource): IItem;
+/**
+ * returns a new content that has the specified type and
+ * and updated related properties like normalizedType, family, etc
+ * @param content orignal content
+ * @param type new type
+ * @returns new content
+ */
+export declare const setContentType: (content: IHubContent, type: string) => IHubContent;
+/**
+ * returns a new content that has the specified hubId and updated identifier
+ * @param content orignal content
+ * @param hubId new hubId
+ * @returns new content
+ */
+export declare const setContentHubId: (content: IHubContent, hubId: string) => IHubContent;
+/**
+ * Calculates the relative and absolute urls for a given content on a specific site
+ *
+ * @param content
+ * @param siteModel
+ * @returns relative and absolute urls
+ */
+export declare const getContentSiteUrls: (content: IHubContent, siteModel: IModel) => {
+    relative: string;
+    absolute: string;
+};
+/**
+ * append the absolute URL to the content on the site
+ * also updates the relative URL in case the
+ * @param content
+ * @param siteModel
+ * @returns
+ */
+export declare const setContentSiteUrls: (content: IHubContent, siteModel: IModel) => IHubContent;