impeditmaiores 1.0.0

package/packages/arcgis-rest-portal/src/users/get-user-url.ts

@@ -0,0 +1,18 @@
+/* Copyright (c) 2019 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { UserSession } from "@esri/arcgis-rest-auth";
+
+import { getPortalUrl } from "../util/get-portal-url";
+
+/**
+ * Helper that returns the [user](https://developers.arcgis.com/rest/users-groups-and-items/user.htm) for a given portal.
+ *
+ * @param session
+ * @returns User url to be used in API requests.
+ */
+export function getUserUrl(session: UserSession): string {
+  return `${getPortalUrl(session)}/community/users/${encodeURIComponent(
+    session.username
+  )}`;
+}

package/packages/arcgis-rest-portal/src/users/get-user.ts

@@ -0,0 +1,58 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, IRequestOptions } from "@esri/arcgis-rest-request";
+import { IUser } from "@esri/arcgis-rest-types";
+
+import { UserSession } from "@esri/arcgis-rest-auth";
+
+import { getPortalUrl } from "../util/get-portal-url";
+
+export interface IGetUserOptions extends IRequestOptions {
+  /**
+   * A session representing a logged in user.
+   */
+  authentication?: UserSession;
+  /**
+   * Supply a username if you'd like to fetch information about a different user than is being used to authenticate the request.
+   */
+  username?: string;
+}
+
+/**
+ * ```js
+ * import { getUser } from '@esri/arcgis-rest-portal';
+ * //
+ * getUser("jsmith")
+ *   .then(response)
+ * // => { firstName: "John", lastName: "Smith",tags: ["GIS Analyst", "City of Redlands"] }
+ * ```
+ * Get information about a user. This method has proven so generically useful that you can also call [`UserSession.getUser()`](/arcgis-rest-js/api/auth/UserSession#getUser-summary).
+ *
+ * @param requestOptions - options to pass through in the request
+ * @returns A Promise that will resolve with metadata about the user
+ */
+export function getUser(
+  requestOptions?: string | IGetUserOptions
+): Promise<IUser> {
+  let url;
+  let options = { httpMethod: "GET" } as IGetUserOptions;
+
+  // if a username is passed, assume ArcGIS Online
+  if (typeof requestOptions === "string") {
+    url = `https://www.arcgis.com/sharing/rest/community/users/${requestOptions}`;
+  } else {
+    // if an authenticated session is passed, default to that user/portal unless another username is provided manually
+    const username =
+      requestOptions.username || requestOptions.authentication.username;
+    url = `${getPortalUrl(requestOptions)}/community/users/${encodeURIComponent(
+      username
+    )}`;
+    options = {
+      ...requestOptions,
+      ...options
+    };
+  }
+  // send the request
+  return request(url, options);
+}

package/packages/arcgis-rest-portal/src/users/invitation.ts

@@ -0,0 +1,156 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+import { IGroup } from "@esri/arcgis-rest-types";
+
+import { IUserRequestOptions } from "@esri/arcgis-rest-auth";
+
+import { getPortalUrl } from "../util/get-portal-url";
+
+export interface IInvitation {
+  id: string;
+  targetType: string;
+  targetId: string;
+  received: number;
+  accepted: boolean;
+  mustApprove: boolean;
+  email: string;
+  role: string;
+  type: string;
+  dateAccepted: number;
+  expiration: number;
+  created: number;
+  username: string;
+  fromUsername: {
+    username: string;
+    fullname?: string;
+  };
+  group?: IGroup;
+  groupId?: string;
+}
+
+export interface IInvitationResult {
+  userInvitations: IInvitation[];
+}
+
+/**
+ * ```js
+ * import { getUserInvitations } from '@esri/arcgis-rest-portal';
+ * // username is inferred from UserSession
+ * getUserInvitations({ authentication })
+ *   .then(response) // response.userInvitations.length => 3
+ * ```
+ * Get all invitations for a user. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/user-invitations.htm) for more information.
+ *
+ * @param requestOptions - options to pass through in the request
+ * @returns A Promise that will resolve with the user's invitations
+ */
+export function getUserInvitations(
+  requestOptions: IUserRequestOptions
+): Promise<IInvitationResult> {
+  let options = { httpMethod: "GET" } as IUserRequestOptions;
+
+  const username = encodeURIComponent(requestOptions.authentication.username);
+  const portalUrl = getPortalUrl(requestOptions);
+  const url = `${portalUrl}/community/users/${username}/invitations`;
+  options = { ...requestOptions, ...options };
+
+  // send the request
+  return request(url, options);
+}
+
+export interface IGetUserInvitationOptions extends IUserRequestOptions {
+  invitationId: string;
+}
+
+/**
+ * ```js
+ * import { getUserInvitation } from '@esri/arcgis-rest-portal';
+ * // username is inferred from UserSession
+ * getUserInvitation({
+ *   invitationId: "3ef",
+ *   authentication
+ * })
+ *   .then(response) // => response.accepted => true
+ * ```
+ * Get an invitation for a user by id. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/user-invitation.htm) for more information.
+ *
+ * @param requestOptions - options to pass through in the request
+ * @returns A Promise that will resolve with the invitation
+ */
+export function getUserInvitation(
+  requestOptions: IGetUserInvitationOptions
+): Promise<IInvitation> {
+  const username = encodeURIComponent(requestOptions.authentication.username);
+  const portalUrl = getPortalUrl(requestOptions);
+  const url = `${portalUrl}/community/users/${username}/invitations/${requestOptions.invitationId}`;
+
+  let options = { httpMethod: "GET" } as IGetUserInvitationOptions;
+  options = { ...requestOptions, ...options };
+
+  // send the request
+  return request(url, options);
+}
+
+/**
+ * ```js
+ * import { acceptInvitation } from '@esri/arcgis-rest-portal';
+ * // username is inferred from UserSession
+ * acceptInvitation({
+ *   invitationId: "3ef",
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Accept an invitation. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/accept-invitation.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function acceptInvitation(
+  requestOptions: IGetUserInvitationOptions
+): Promise<{
+  success: boolean;
+  username: string;
+  groupId: string;
+  id: string;
+}> {
+  const username = encodeURIComponent(requestOptions.authentication.username);
+  const portalUrl = getPortalUrl(requestOptions);
+  const url = `${portalUrl}/community/users/${username}/invitations/${requestOptions.invitationId}/accept`;
+
+  const options: IGetUserInvitationOptions = { ...requestOptions };
+  return request(url, options);
+}
+
+/**
+ * ```js
+ * import { declineInvitation } from '@esri/arcgis-rest-portal';
+ * // username is inferred from UserSession
+ * declineInvitation({
+ *   invitationId: "3ef",
+ *   authentication
+ * })
+ *   .then(response)
+ * ```
+ * Decline an invitation. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/decline-invitation.htm) for more information.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function declineInvitation(
+  requestOptions: IGetUserInvitationOptions
+): Promise<{
+  success: boolean;
+  username: string;
+  groupId: string;
+  id: string;
+}> {
+  const username = encodeURIComponent(requestOptions.authentication.username);
+  const portalUrl = getPortalUrl(requestOptions);
+  const url = `${portalUrl}/community/users/${username}/invitations/${requestOptions.invitationId}/decline`;
+
+  const options: IGetUserInvitationOptions = { ...requestOptions };
+  return request(url, options);
+}

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

@@ -0,0 +1,68 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+import { IUserRequestOptions } from "@esri/arcgis-rest-auth";
+
+import { getPortalUrl } from "../util/get-portal-url";
+
+export interface INotification {
+  id: string;
+  type: string;
+  target: string;
+  targetType: string;
+  received: number;
+  data: { [key: string]: any };
+}
+
+export interface IRemoveNotificationOptions extends IUserRequestOptions {
+  /**
+   * Unique identifier of the item.
+   */
+  id: string;
+}
+export interface INotificationResult {
+  notifications: INotification[];
+}
+
+/**
+ * ```js
+ * import { getUserNotifications } from '@esri/arcgis-rest-portal';
+ * // username is inferred from UserSession
+ * getUserNotifications({ authentication })
+ *   .then(results) // results.notifications.length) => 3
+ * ```
+ * Get notifications for a user.
+ *
+ * @param requestOptions - options to pass through in the request
+ * @returns A Promise that will resolve with the user's notifications
+ */
+export function getUserNotifications(
+  requestOptions: IUserRequestOptions
+): Promise<INotificationResult> {
+  let options = { httpMethod: "GET" } as IUserRequestOptions;
+
+  const username = encodeURIComponent(requestOptions.authentication.username);
+  const portalUrl = getPortalUrl(requestOptions);
+  const url = `${portalUrl}/community/users/${username}/notifications`;
+  options = { ...requestOptions, ...options };
+
+  // send the request
+  return request(url, options);
+}
+
+/**
+ * Delete a notification.
+ *
+ * @param requestOptions - Options for the request
+ * @returns A Promise that will resolve with the success/failure status of the request
+ */
+export function removeNotification(
+  requestOptions: IRemoveNotificationOptions
+): Promise<{ success: boolean; notificationId: string }> {
+  const username = encodeURIComponent(requestOptions.authentication.username);
+  const portalUrl = getPortalUrl(requestOptions);
+  const url = `${portalUrl}/community/users/${username}/notifications/${requestOptions.id}/delete`;
+
+  return request(url, requestOptions);
+}

package/packages/arcgis-rest-portal/src/users/search-users.ts

@@ -0,0 +1,37 @@
+/* Copyright (c) 2018-2019 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+import { IAuthenticatedRequestOptions } from "@esri/arcgis-rest-auth";
+import { IAuthenticationManager } from "@esri/arcgis-rest-request";
+import { IPagingParams, IUser } from "@esri/arcgis-rest-types";
+import { SearchQueryBuilder } from "../util/SearchQueryBuilder";
+import { ISearchOptions, ISearchResult } from "../util/search";
+import { genericSearch } from "../util/generic-search";
+
+// export interface IUserSearchOptions extends IAuthenticatedRequestOptions, IPagingParams {
+//   q: string | SearchQueryBuilder;
+//   sortField?: string;
+//   sortOrder?: string;
+//   [key: string]: any;
+// }
+
+export interface IUserSearchOptions extends ISearchOptions {
+  authentication: IAuthenticationManager;
+}
+
+/**
+ * ```js
+ * import { searchItems } from "@esri/arcgis-rest-portal";
+ * //
+ * searchUsers({ q: 'tommy', authentication })
+ *   .then(response) // response.total => 355
+ * ```
+ * Search a portal for users.
+ *
+ * @param search - A RequestOptions object to pass through to the endpoint.
+ * @returns A Promise that will resolve with the data from the response.
+ */
+export function searchUsers(
+  search: IUserSearchOptions | SearchQueryBuilder
+): Promise<ISearchResult<IUser>> {
+  return genericSearch<IUser>(search, "user");
+}

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

@@ -0,0 +1,66 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request } from "@esri/arcgis-rest-request";
+import { IUser } from "@esri/arcgis-rest-types";
+
+import { IUserRequestOptions } from "@esri/arcgis-rest-auth";
+
+import { getPortalUrl } from "../util/get-portal-url";
+
+export interface IUpdateUserOptions extends IUserRequestOptions {
+  /**
+   * The user properties to be updated.
+   */
+  user: IUser;
+}
+
+export interface IUpdateUserResponse {
+  success: boolean;
+  username: string;
+}
+
+/**
+ * ```js
+ * import { updateUser } from '@esri/arcgis-rest-portal';
+ * // any user can update their own profile
+ * updateUser({
+ *   authentication,
+ *   user: { description: "better than the last one" }
+ * })
+ *   .then(response)
+ * // org administrators must declare the username that will be updated explicitly
+ * updateUser({
+ *   authentication,
+ *   user: { username: "c@sey", description: "" }
+ * })
+ *   .then(response)
+ * // => { "success": true, "username": "c@sey" }
+ * ```
+ * Update a user profile. The username will be extracted from the authentication session unless it is provided explicitly. See the [REST Documentation](https://developers.arcgis.com/rest/users-groups-and-items/update-user.htm) for more information.
+ *
+ * @param requestOptions - options to pass through in the request
+ * @returns A Promise that will resolve with metadata about the user
+ */
+export function updateUser(
+  requestOptions?: IUpdateUserOptions
+): Promise<IUpdateUserResponse> {
+  // default to the authenticated username unless another username is provided manually
+  const username =
+    requestOptions.user.username || requestOptions.authentication.username;
+
+  const updateUrl = `${getPortalUrl(
+    requestOptions
+  )}/community/users/${encodeURIComponent(username)}/update`;
+
+  // mixin custom params and the user information, then drop the user info
+  requestOptions.params = {
+    ...requestOptions.user,
+    ...requestOptions.params
+  };
+
+  delete requestOptions.user;
+
+  // send the request
+  return request(updateUrl, requestOptions);
+}