refactor(:family:): reorganize IItem and IGroup interfaces

extending interfaces between categories proved to be more complicated than helpful
there is
already way too much complexity between what items and groups need to look like when they are
created, updated and retrieved.

AFFECTS PACKAGES:
@esri/arcgis-rest-common-types
@esri/arcgis-rest-groups
@esri/arcgis-rest-items
@esri/arcgis-rest-users

packages/arcgis-rest-common-types/src/group.ts

@@ -0,0 +1,51 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+/**
+ * A [Group](https://developers.arcgis.com/rest/users-groups-and-items/common-parameters.htm) that has not been created yet.
+ */
+export interface IGroupAdd {
+  title: string;
+  owner?: string;
+  tags?: string[];
+  description?: string;
+  access?: "private" | "org" | "public";
+  phone?: string;
+  sortField?:
+    | "title"
+    | "owner"
+    | "avgrating"
+    | "numviews"
+    | "created"
+    | "modified";
+  sortOrder?: "asc" | "desc";
+  isViewOnly?: boolean;
+  isInvitationOnly?: boolean;
+  thumbnail?: string;
+  autoJoin?: boolean;
+  snippet?: string;
+  [key: string]: any;
+}
+
+/**
+ * Existing Portal [Group](https://developers.arcgis.com/rest/users-groups-and-items/group.htm).
+ */
+export interface IGroup extends IGroupAdd {
+  id: string;
+  owner: string;
+  tags: string[];
+  created: number;
+  modified: number;
+  protected: boolean;
+  isInvitationOnly: boolean;
+  isViewOnly: boolean;
+  isOpenData: boolean;
+  isFav: boolean;
+  autoJoin: boolean;
+  userMembership?: {
+    username?: string;
+    memberType?: string;
+    applications?: number;
+  };
+  hasCategorySchema?: boolean;
+}

packages/arcgis-rest-common-types/src/index.ts

@@ -1,7 +1,11 @@
-/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
  * Apache-2.0 */
 
+import { IGroup } from "./group";
+
 export * from "./webmap";
+export * from "./item";
+export * from "./group";
 
 /**
  * an arc can be represented as a JSON curve object
@@ -180,28 +184,6 @@ export interface IFont {
   decoration?: "line-through" | "underline" | "none";
 }
 
-/**
- * Portal Item
- */
-export interface IItem {
-  id?: string;
-  owner?: string;
-  title?: string;
-  type?: string;
-  tags?: string[];
-  typeKeywords?: string[];
-  description?: string;
-  snippet?: string;
-  documentation?: string;
-  extent?: number[][];
-  categories?: string[];
-  spatialReference?: any;
-  culture?: string;
-  properties?: any;
-  url?: string;
-  [key: string]: any;
-}
-
 /**
  *
  */
@@ -476,31 +458,6 @@ export interface IUser {
   provider?: "arcgis" | "enterprise" | "facebook" | "google";
 }
 
-export interface IGroup extends IItem {
-  isInvitationOnly?: boolean;
-  phone?: string;
-  sortField?:
-    | "title"
-    | "owner"
-    | "avgrating"
-    | "numviews"
-    | "created"
-    | "modified";
-  isViewOnly?: boolean;
-  isFav?: boolean;
-  access?: "private" | "org" | "public";
-  userMembership?: {
-    username?: string;
-    memberType?: string;
-    applications?: number;
-  };
-  protected?: boolean;
-  autoJoin?: boolean;
-  hasCategorySchema?: boolean;
-  isOpenData?: boolean;
-  [key: string]: any;
-}
-
 export type esriUnits =
   | "esriSRUnit_Meter"
   | "esriSRUnit_StatuteMile"

packages/arcgis-rest-common-types/src/item.ts

@@ -0,0 +1,45 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { ISpatialReference } from "./index";
+
+/**
+ * A Portal [Item](https://developers.arcgis.com/rest/users-groups-and-items/common-parameters.htm) that has not been created yet.
+ */
+export interface IItemAdd {
+  title: string;
+  type: string;
+  owner?: string;
+  typeKeywords?: string[];
+  description?: string;
+  snippet?: string;
+  documentation?: string;
+  extent?: number[][];
+  categories?: string[];
+  spatialReference?: ISpatialReference;
+  culture?: string;
+  properties?: any;
+  url?: string;
+  tags?: string[];
+  [key: string]: any;
+}
+
+/**
+ * A Portal [Item](https://developers.arcgis.com/rest/users-groups-and-items/common-parameters.htm) to be updated.
+ */
+export interface IItemUpdate {
+  id: string;
+  [key: string]: any;
+}
+
+/**
+ * Existing Portal [Item](https://developers.arcgis.com/rest/users-groups-and-items/item.htm).
+ */
+export interface IItem extends IItemAdd {
+  id: string;
+  owner: string;
+  tags: string[];
+  created: number;
+  modified: number;
+  protected: boolean;
+}

packages/arcgis-rest-groups/src/groups.ts

@@ -1,13 +1,20 @@
-/* Copyright (c) 2017 Environmental Systems Research Institute, Inc.
+/* Copyright (c) 2017-2018 Environmental Systems Research Institute, Inc.
  * Apache-2.0 */
+
 import {
   request,
   IRequestOptions,
   // IParams,
   getPortalUrl
 } from "@esri/arcgis-rest-request";
 
-import { IPagingParams, IItem, IGroup } from "@esri/arcgis-rest-common-types";
+import {
+  IPagingParams,
+  IItem,
+  IItemUpdate,
+  IGroupAdd,
+  IGroup
+} from "@esri/arcgis-rest-common-types";
 
 export interface IPagingParamsRequestOptions extends IRequestOptions {
   paging: IPagingParams;
@@ -17,8 +24,12 @@ export interface IGroupIdRequestOptions extends IRequestOptions {
   id: string;
 }
 
-export interface IGroupRequestOptions extends IRequestOptions {
-  group: IGroup;
+export interface IGroupAddRequestOptions extends IRequestOptions {
+  group: IGroupAdd;
+}
+
+export interface IGroupUpdateRequestOptions extends IRequestOptions {
+  group: IItemUpdate;
 }
 
 export interface IGroupSearchRequest extends IPagingParams {
@@ -156,32 +167,17 @@ export function getGroupUsers(
   return request(url, options);
 }
 
-/**
- * Serialize a group into a json format accepted by the Portal API
- * for create and update operations
- *
- * @param group IGroup to be serialized
- * @returns a formatted JSON object to be sent to Portal
- */
-function serializeGroup(group: IGroup): any {
-  // create a clone so we're not messing with the original
-  const clone = JSON.parse(JSON.stringify(group));
-  // join and tags...
-  clone.tags = clone.tags.join(", ");
-  return clone;
-}
-
 /**
  * Create a new Group.
  * Note: The group name must be unique within the user's organization.
  * @param requestOptions  - Options for the request, including a group object
  * @returns A Promise that will resolve with the success/failure status of the request
  */
 export function createGroup(
-  requestOptions: IGroupRequestOptions
+  requestOptions: IGroupAddRequestOptions
 ): Promise<any> {
   const url = `${getPortalUrl(requestOptions)}/community/createGroup`;
-  const options: IGroupRequestOptions = {
+  const options: IGroupAddRequestOptions = {
     ...requestOptions
   };
   // serialize the group into something Portal will accept
@@ -195,13 +191,13 @@ export function createGroup(
  * @returns A Promise that will resolve with the success/failure status of the request
  */
 export function updateGroup(
-  requestOptions: IGroupRequestOptions
+  requestOptions: IGroupUpdateRequestOptions
 ): Promise<any> {
   const url = `${getPortalUrl(requestOptions)}/community/groups/${
     requestOptions.group.id
   }/update`;
 
-  const options: IGroupRequestOptions = {
+  const options: IGroupUpdateRequestOptions = {
     ...requestOptions
   };
   // serialize the group into something Portal will accept
@@ -259,3 +255,18 @@ export function unprotectGroup(
   };
   return request(url, options);
 }
+
+/**
+ * Serialize a group into a json format accepted by the Portal API
+ * for create and update operations
+ *
+ * @param group IGroup to be serialized
+ * @returns a formatted JSON object to be sent to Portal
+ */
+function serializeGroup(group: IGroupAdd | IItemUpdate | IGroup): any {
+  // create a clone so we're not messing with the original
+  const clone = JSON.parse(JSON.stringify(group));
+  // join and tags...
+  clone.tags = clone.tags.join(", ");
+  return clone;
+}

packages/arcgis-rest-groups/test/mocks/responses.ts

@@ -130,7 +130,8 @@ export const GroupContentResponse: IGroupContentResult = {
       avgRating: 0,
       numViews: 1301,
       groupCategories: [],
-      scoreCompleteness: 50
+      scoreCompleteness: 50,
+      protected: false
     }
   ]
 };

packages/arcgis-rest-items/src/items.ts

@@ -7,22 +7,14 @@ import {
   getPortalUrl
 } from "@esri/arcgis-rest-request";
 
-import { IItem, IPagingParams } from "@esri/arcgis-rest-common-types";
+import {
+  IItemAdd,
+  IItemUpdate,
+  IItem,
+  IPagingParams
+} from "@esri/arcgis-rest-common-types";
 import { IUserRequestOptions } from "@esri/arcgis-rest-auth";
 
-export interface IItemAdd extends IItem {
-  title: string;
-  type: string;
-}
-
-export interface IItemUpdate extends IItem {
-  id: string;
-}
-
-export interface IItemRequestOptions extends IRequestOptions {
-  item: IItem;
-}
-
 export interface IItemIdRequestOptions extends IUserRequestOptions {
   /**
    * Unique identifier of the item.
@@ -424,7 +416,7 @@ export function removeItemResource(
  * @param item IItem to be serialized
  * @returns a formatted json object to be sent to Portal
  */
-function serializeItem(item: IItem): any {
+function serializeItem(item: IItemAdd | IItemUpdate | IItem): any {
   // create a clone so we're not messing with the original
   const clone = JSON.parse(JSON.stringify(item));
   // join keywords and tags...

packages/arcgis-rest-items/test/mocks/item.ts

@@ -16,7 +16,10 @@ export const ItemResponse: IItem = {
   typeKeywords: ["Javascript", "hubSiteApplication"],
   properties: {
     parentId: "3eb"
-  }
+  },
+  created: 123,
+  modified: 456,
+  protected: false
 };
 
 export const ItemDataResponse: any = {

packages/arcgis-rest-items/test/mocks/search.ts

@@ -53,7 +53,8 @@ export const SearchResponse: ISearchResult = {
       numComments: 0,
       numRatings: 0,
       avgRating: 0,
-      numViews: 4
+      numViews: 4,
+      protected: false
     }
   ]
 };