autnam 1.0.0

package/packages/arcgis-rest-portal/src/items/update.ts

@@ -0,0 +1,188 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, IRequestOptions } from "@esri/arcgis-rest-request";
+import { IItemUpdate } from "../helpers.js";
+
+import { getPortalUrl } from "../util/get-portal-url.js";
+import {
+  ICreateUpdateItemOptions,
+  IMoveItemResponse,
+  IItemInfoOptions,
+  IItemResourceOptions,
+  IItemInfoResponse,
+  IItemResourceResponse,
+  IUpdateItemResponse,
+  determineOwner
+} from "./helpers.js";
+
+export interface IUpdateItemOptions extends ICreateUpdateItemOptions {
+  item: IItemUpdate;
+}
+
+export interface IMoveItemOptions extends ICreateUpdateItemOptions {
+  /**
+   * Alphanumeric id of item to be moved.
+   */
+  itemId: string;
+  /**
+   * Alphanumeric id of folder to house moved item. If null, empty, or "/", the destination is the
+   * root folder.
+   */
+  folderId?: string;
+}
+
+/**
+ * ```js
+ * import { updateItem } from "@esri/arcgis-rest-portal";
+ * //
+ * updateItem({
+ *   item: {
+ *     id: "3ef",
+ *     description: "A three hour tour"
+ *   },
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Update an Item. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/update-item.htm) for more information.
+ *
+ * @param requestOptions - Options for the request.
+ * @returns A Promise that updates an item.
+ */
+export function updateItem(
+  requestOptions: IUpdateItemOptions
+): Promise<IUpdateItemResponse> {
+  return determineOwner(requestOptions).then((owner) => {
+    const url = requestOptions.folderId
+      ? `${getPortalUrl(requestOptions)}/content/users/${owner}/${
+          requestOptions.folderId
+        }/items/${requestOptions.item.id}/update`
+      : `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+          requestOptions.item.id
+        }/update`;
+
+    // serialize the item into something Portal will accept
+    requestOptions.params = {
+      ...requestOptions.params,
+      ...requestOptions.item
+    };
+
+    return request(url, requestOptions);
+  });
+}
+
+/**
+ * ```js
+ * import { updateItemInfo } from "@esri/arcgis-rest-portal";
+ * //
+ * updateItemInfo({
+ *   id: '3ef',
+ *   file: file,
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Update an info file associated with an item. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/update-info.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that updates an item info file.
+ */
+export function updateItemInfo(
+  requestOptions: IItemInfoOptions
+): Promise<IItemInfoResponse> {
+  return determineOwner(requestOptions).then((owner) => {
+    const url = `${getPortalUrl(
+      requestOptions as IRequestOptions
+    )}/content/users/${owner}/items/${requestOptions.id}/updateinfo`;
+
+    // mix in user supplied params
+    requestOptions.params = {
+      folderName: requestOptions.folderName,
+      file: requestOptions.file,
+      ...requestOptions.params
+    };
+
+    return request(url, requestOptions);
+  });
+}
+
+/**
+ * ```js
+ * import { updateItemResource } from "@esri/arcgis-rest-portal";
+ * //
+ * updateItemResource({
+ *   id: '3ef',
+ *   resource: file,
+ *   name: 'bigkahuna.jpg',
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Update a resource associated with an item. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/update-resources.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that updates an item resource.
+ */
+export function updateItemResource(
+  requestOptions: IItemResourceOptions
+): Promise<IItemResourceResponse> {
+  return determineOwner(requestOptions).then((owner) => {
+    const url = `${getPortalUrl(
+      requestOptions as IRequestOptions
+    )}/content/users/${owner}/items/${requestOptions.id}/updateResources`;
+
+    // mix in user supplied params
+    requestOptions.params = {
+      file: requestOptions.resource,
+      fileName: requestOptions.name,
+      resourcesPrefix: requestOptions.prefix,
+      text: requestOptions.content,
+      ...requestOptions.params
+    };
+
+    // only override the access specified previously if 'private' is passed explicitly
+    if (typeof requestOptions.private !== "undefined") {
+      requestOptions.params.access = requestOptions.private
+        ? "private"
+        : "inherit";
+    }
+    return request(url, requestOptions);
+  });
+}
+
+/**
+ * ```js
+ * import { moveItem } from "@esri/arcgis-rest-portal";
+ * //
+ * moveItem({
+ *   itemId: "3ef",
+ *   folderId: "7c5",
+ *   authentication: ArcGISIdentityManager
+ * })
+ * ```
+ * Move an item to a folder. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/move-item.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that resolves with owner and folder details once the move has been completed
+ */
+export function moveItem(
+  requestOptions: IMoveItemOptions
+): Promise<IMoveItemResponse> {
+  return determineOwner(requestOptions).then((owner) => {
+    const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+      requestOptions.itemId
+    }/move`;
+
+    let folderId = requestOptions.folderId;
+    if (!folderId) {
+      folderId = "/";
+    }
+    requestOptions.params = {
+      folder: folderId,
+      ...requestOptions.params
+    };
+
+    return request(url, requestOptions);
+  });
+}

package/packages/arcgis-rest-portal/src/items/upload.ts

@@ -0,0 +1,124 @@
+/* Copyright (c) 2017-2019 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, appendCustomParams } from "@esri/arcgis-rest-request";
+import { IItemAdd } from "../helpers.js";
+
+import { getPortalUrl } from "../util/get-portal-url.js";
+import {
+  IUserItemOptions,
+  IUpdateItemResponse,
+  determineOwner,
+  IItemPartOptions
+} from "./helpers.js";
+
+export interface ICommitItemOptions extends IUserItemOptions {
+  item: IItemAdd;
+}
+
+/**
+ * ```js
+ * import { addItemPart } from "@esri/arcgis-rest-portal";
+ * //
+ * addItemPart({
+ *   id: "30e5fe3149c34df1ba922e6f5bbf808f",
+ *   file: data,
+ *   partNum: 1,
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Add Item Part allows the caller to upload a file part when doing an add or update item operation in multipart mode. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/add-item-part.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise to add the item part status.
+ */
+export function addItemPart(
+  requestOptions?: IItemPartOptions
+): Promise<IUpdateItemResponse> {
+  const partNum = requestOptions.partNum;
+
+  if (!Number.isInteger(partNum) || partNum < 1 || partNum > 10000) {
+    return Promise.reject(
+      new Error(
+        "The part number must be an integer between 1 to 10000, inclusive."
+      )
+    );
+  }
+
+  return determineOwner(requestOptions).then((owner) => {
+    // AGO adds the "partNum" parameter in the query string, not in the body
+    const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+      requestOptions.id
+    }/addPart?partNum=${partNum}`;
+
+    const options = appendCustomParams<IItemPartOptions>(
+      requestOptions,
+      ["file"],
+      { params: { ...requestOptions.params } }
+    );
+
+    return request(url, options);
+  });
+}
+
+/**
+ * ```js
+ * import { commitItemUpload } from "@esri/arcgis-rest-portal";
+ * //
+ * commitItemUpload({
+ *   id: "30e5fe3149c34df1ba922e6f5bbf808f",
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Commit is called once all parts are uploaded during a multipart Add Item or Update Item operation. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/commit.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise to get the commit result.
+ */
+export function commitItemUpload(
+  requestOptions?: ICommitItemOptions
+): Promise<IUpdateItemResponse> {
+  return determineOwner(requestOptions).then((owner) => {
+    const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+      requestOptions.id
+    }/commit`;
+
+    const options = appendCustomParams<ICommitItemOptions>(requestOptions, [], {
+      params: {
+        ...requestOptions.params,
+        ...requestOptions.item
+      }
+    });
+
+    return request(url, options);
+  });
+}
+
+/**
+ * ```js
+ * import { cancelItemUpload } from "@esri/arcgis-rest-portal";
+ * //
+ * cancelItemUpload({
+ *   id: "30e5fe3149c34df1ba922e6f5bbf808f",
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Cancels a multipart upload on an item. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/cancel.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise to get the commit result.
+ */
+export function cancelItemUpload(
+  requestOptions?: IUserItemOptions
+): Promise<IUpdateItemResponse> {
+  return determineOwner(requestOptions).then((owner) => {
+    const url = `${getPortalUrl(requestOptions)}/content/users/${owner}/items/${
+      requestOptions.id
+    }/cancel`;
+
+    return request(url, requestOptions);
+  });
+}

package/packages/arcgis-rest-portal/src/orgs/notification.ts

@@ -0,0 +1,148 @@
+import {
+  request,
+  IRequestOptions,
+  ArcGISRequestError
+} from "@esri/arcgis-rest-request";
+import { getPortalUrl } from "../util/get-portal-url.js";
+import { chunk } from "../util/array.js";
+
+export interface ICreateOrgNotificationOptions extends IRequestOptions {
+  /**
+   * Subject of the notification. This only applies to email and builtin notifications. For push notifications, subject/title is provided as a part of the message payload.
+   */
+  subject?: string;
+  /**
+   * Message to be sent. For builtin and email notifications this is a string. For push notifications, this will be JSON.
+   */
+  message: string | object;
+  /**
+   * Array of usernames of the users in the group to whom the message should be sent. If not provided, the message will be sent to all users in the group if the user is an admin. Only group admins will be able to send notifications to a list of users. Group users will be able to send notifications to only one user at a time.
+   */
+  users?: string[];
+  /**
+   * The channel through which the notification is to be delivered. Supported values are email or builtin. Email will be sent when the email option is chosen. If the builtin option is chosen, a notification will be added to the notifications list that the user can see when logged into the home app.
+   */
+  notificationChannelType?: string;
+
+  /**
+   * How many emails should be sent at a time. Defaults to the max possible (25)
+   */
+  batchSize?: number;
+}
+
+export interface ICreateOrgNotificationResult {
+  /**
+   * Whether the operation was successful
+   */
+  success: boolean;
+  /**
+   * An array of request errors
+   */
+  errors?: ArcGISRequestError[];
+}
+
+/**
+ * Send a notification to members of the requesting user's org.
+ * Operation success will be indicated by a flag on the return
+ * object. If there are any errors, they will be placed in an
+ * errors array on the return object
+ *
+ * ```js
+ * const authentication: IAuthenticationManager; // Typically passed into to the function
+ * //
+ * const options: IInviteGroupUsersOptions = {
+ *  id: 'group_id',
+ *  users: ['larry', 'curly', 'moe'],
+ *  notificationChannelType: 'email',
+ *  expiration: 20160,
+ *  authentication
+ * }
+ * //
+ * const result = await createOrgNotification(options);
+ * //
+ * const if_success_result_looks_like = {
+ *  success: true
+ * }
+ * //
+ * const if_failure_result_looks_like = {
+ *  success: false,
+ *  errors: [ArcGISRequestError]
+ * }
+ * ```
+ * @param {ICreateOrgNotificationOptions} options
+ *
+ * @returns {ICreateOrgNotificationResult}
+ */
+export function createOrgNotification(options: ICreateOrgNotificationOptions) {
+  const url = `${getPortalUrl(options)}/portals/self/createNotification`;
+  const batches = _generateBatchRequests(options);
+  const promises = batches.map((batch) => _sendSafeRequest(url, batch));
+
+  return Promise.all(promises).then(_combineResults);
+}
+
+/**
+ * @private
+ */
+function _generateBatchRequests(
+  options: ICreateOrgNotificationOptions
+): IRequestOptions[] {
+  const userBatches: string[][] = chunk<string>(
+    options.users,
+    options.batchSize || 25
+  );
+  return userBatches.map((users) => _generateRequestOptions(users, options));
+}
+
+/**
+ * @private
+ */
+function _generateRequestOptions(
+  users: string[],
+  baseOptions: ICreateOrgNotificationOptions
+): IRequestOptions {
+  const requestOptions: ICreateOrgNotificationOptions = Object.assign(
+    {},
+    baseOptions
+  );
+
+  requestOptions.params = {
+    ...requestOptions.params,
+    users,
+    subject: baseOptions.subject,
+    message: baseOptions.message,
+    notificationChannelType: requestOptions.notificationChannelType
+  };
+
+  return requestOptions;
+}
+
+/**
+ * @private
+ */
+function _sendSafeRequest(
+  url: string,
+  requestOptions: IRequestOptions
+): Promise<ICreateOrgNotificationResult> {
+  return request(url, requestOptions).catch((error) => ({ errors: [error] }));
+}
+
+/**
+ * @private
+ */
+function _combineResults(
+  responses: ICreateOrgNotificationResult[]
+): ICreateOrgNotificationResult {
+  const success = responses.every((res) => res.success);
+  const errors: ArcGISRequestError[] = responses.reduce(
+    (collection, res) => collection.concat(res.errors || []),
+    []
+  );
+  const combined: ICreateOrgNotificationResult = { success };
+
+  if (errors.length > 0) {
+    combined.errors = errors;
+  }
+
+  return combined;
+}

package/packages/arcgis-rest-portal/src/services/get-unique-service-name.ts

@@ -0,0 +1,35 @@
+/* Copyright (c) 2018-2020 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { ArcGISIdentityManager } from "@esri/arcgis-rest-request";
+import { isServiceNameAvailable } from "./is-service-name-available.js";
+
+/**
+ * Given a starting name, return a service name that is unique within
+ * the current users organization
+ *
+ * @export
+ * @param {string} name
+ * @param {ArcGISIdentityManager} session
+ * @param {number} step
+ * @return {*}  {Promise<string>}
+ */
+export function getUniqueServiceName(
+  name: string,
+  type: string,
+  session: ArcGISIdentityManager,
+  step: number
+): Promise<string> {
+  let nameToCheck = name;
+  if (step) {
+    nameToCheck = `${name}_${step}`;
+  }
+  return isServiceNameAvailable(nameToCheck, type, session).then((response) => {
+    if (response.available) {
+      return nameToCheck;
+    } else {
+      step = step + 1;
+      return getUniqueServiceName(name, type, session, step);
+    }
+  });
+}

package/packages/arcgis-rest-portal/src/services/is-service-name-available.ts

@@ -0,0 +1,29 @@
+/* Copyright (c) 2018-2020 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, ArcGISIdentityManager } from "@esri/arcgis-rest-request";
+import { IServiceNameAvailable } from "../helpers.js";
+
+/**
+ * Determine if a specific service name is available in the current user's organization
+ *
+ * @export
+ * @param {string} name
+ * @param {ArcGISIdentityManager} session
+ * @return {*}  {Promise<IServiceNameAvailable>}
+ */
+export function isServiceNameAvailable(
+  name: string,
+  type: string,
+  session: ArcGISIdentityManager
+): Promise<IServiceNameAvailable> {
+  const url = `${session.portal}/portals/self/isServiceNameAvailable`;
+  return request(url, {
+    params: {
+      name,
+      type
+    },
+    httpMethod: "GET",
+    authentication: session
+  });
+}

package/packages/arcgis-rest-portal/src/sharing/access.ts

@@ -0,0 +1,84 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+
+import {
+  ISharingOptions,
+  ISharingResponse,
+  isItemOwner,
+  getSharingUrl,
+  isOrgAdmin
+} from "./helpers.js";
+
+export interface ISetAccessOptions extends ISharingOptions {
+  /**
+   * "private" indicates that the item can only be accessed by the user. "public" means accessible to anyone. An item shared to the organization has an access level of "org".
+   */
+  access: "private" | "org" | "public";
+}
+
+/**
+ * ```js
+ * import { setItemAccess } from "@esri/arcgis-rest-portal";
+ * //
+ * setItemAccess({
+ *   id: "abc123",
+ *   access: "public", // 'org' || 'private'
+ *   authentication: session
+ * })
+ * ```
+ * Change who is able to access an item.
+ *
+ * @param requestOptions - Options for the request.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function setItemAccess(
+  requestOptions: ISetAccessOptions
+): Promise<ISharingResponse> {
+  const url = getSharingUrl(requestOptions);
+
+  if (isItemOwner(requestOptions)) {
+    // if the user owns the item, proceed
+    return updateItemAccess(url, requestOptions);
+  } else {
+    // otherwise we need to check to see if they are an organization admin
+    return isOrgAdmin(requestOptions).then((admin) => {
+      if (admin) {
+        return updateItemAccess(url, requestOptions);
+      } else {
+        // if neither, updating the sharing isnt possible
+        throw Error(
+          `This item can not be shared by ${requestOptions.authentication.username}. They are neither the item owner nor an organization admin.`
+        );
+      }
+    });
+  }
+}
+
+function updateItemAccess(
+  url: string,
+  requestOptions: ISetAccessOptions
+): Promise<any> {
+  requestOptions.params = {
+    org: false,
+    everyone: false,
+    ...requestOptions.params
+  };
+
+  // if the user wants to make the item private, it needs to be unshared from any/all groups as well
+  if (requestOptions.access === "private") {
+    requestOptions.params.groups = " ";
+  }
+  if (requestOptions.access === "org") {
+    requestOptions.params.org = true;
+  }
+  // if sharing with everyone, share with the entire organization as well.
+  if (requestOptions.access === "public") {
+    // this is how the ArcGIS Online Home app sets public access
+    // setting org = true instead of account = true will cancel out all sharing
+    requestOptions.params.account = true;
+    requestOptions.params.everyone = true;
+  }
+  return request(url, requestOptions);
+}

package/packages/arcgis-rest-portal/src/sharing/helpers.ts

@@ -0,0 +1,80 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IUserRequestOptions, IGroup, IUser, GroupMembership } from "@esri/arcgis-rest-request";
+import { getPortalUrl } from "../util/get-portal-url.js";
+import { getGroup } from "../groups/get.js";
+
+export interface ISharingOptions extends IUserRequestOptions {
+  /**
+   * Unique identifier for the item.
+   */
+  id: string;
+  /**
+   * Item owner, if different from the authenticated user.
+   */
+  owner?: string;
+}
+
+export interface ISharingResponse {
+  notSharedWith?: string[];
+  notUnsharedFrom?: string[];
+  itemId: string;
+}
+
+export function getSharingUrl(requestOptions: ISharingOptions): string {
+  const username = requestOptions.authentication.username;
+  const owner = requestOptions.owner || username;
+  return `${getPortalUrl(requestOptions)}/content/users/${encodeURIComponent(
+    owner
+  )}/items/${requestOptions.id}/share`;
+}
+
+export function isItemOwner(requestOptions: ISharingOptions): boolean {
+  const username = requestOptions.authentication.username;
+  const owner = requestOptions.owner || username;
+  return owner === username;
+}
+
+/**
+ * Check it the user is a full org_admin
+ * @param requestOptions
+ * @returns Promise resolving in a boolean indicating if the user is an ArcGIS Organization administrator
+ */
+export function isOrgAdmin(
+  requestOptions: IUserRequestOptions
+): Promise<boolean> {
+  const session = requestOptions.authentication;
+
+  return session.getUser(requestOptions).then((user: IUser) => {
+    return user && user.role === "org_admin" && !user.roleId;
+  });
+}
+
+/**
+ * Get the User Membership for a particular group. Use this if all you have is the groupId.
+ * If you have the group object, check the `userMembership.memberType` property instead of calling this method.
+ *
+ * @param requestOptions
+ * @returns A Promise that resolves with "owner" | "admin" | "member" | "nonmember"
+ */
+export function getUserMembership(
+  requestOptions: IGroupSharingOptions
+): Promise<GroupMembership> {
+  // fetch the group...
+  return getGroup(requestOptions.groupId, requestOptions)
+    .then((group: IGroup) => {
+      return group.userMembership.memberType;
+    })
+    .catch(() => {
+      return "none" as GroupMembership;
+    });
+}
+
+export interface IGroupSharingOptions extends ISharingOptions {
+  /**
+   * Group identifier
+   */
+  groupId: string;
+  confirmItemControl?: boolean;
+}