Round 3

api/shapes/wishlist.ts

@@ -2,47 +2,87 @@
 
 import { DestinyItemSubType } from 'bungie-api-ts/destiny2';
 
-interface WishList {
-  /** Indicates that this JSON file is in the format described by this file. */
-  format: 'DIMv1';
+export type ItemHash = number;
+
+export interface WishList {
+  /**
+   * Indicates that this JSON file is in the format described by this schema. If
+   * the format is changed in a non-backwards-compatible way this string will be
+   * changed. It otherwise has no semantic meaning.
+   */
+  format: 'wishlist.v1';
+
+  /**
+   * The name of the wish list itself, as a plain string. e.g. "Voltron".
+   */
   name: string;
+  /** The description of the wish list itself, as a plain string. */
   description: string;
-  /** URLs of other wish lists that are transitively included into this wishlist. */
-  includes: string[];
-  /** UNIX timestamp (milliseconds) representing when this wish list was created. */
-  date?: number;
+
+  /** Information about the author(s) of this wish list. */
+  authors?: Author[];
+
+  /**
+   * URLs of other wish lists that are transitively included into this wishlist.
+   * This allows wish lists to be composed of other wish lists, which are then
+   * fetched individually. A wish list may specify multiple includes, and no
+   * rolls of its own.
+   */
+  include?: string[];
+
+  /**
+   * UNIX timestamp (milliseconds) representing when this wish list was first
+   * created, for display to humans.
+   */
+  createdTime?: number;
+  /**
+   * UNIX timestamp (milliseconds) representing when this wish list was last
+   * updated, for display to humans. This shouldn't be used to manage cache
+   * freshness - use HTTP headers for that.
+   */
+  updatedTime?: number;
+
+  /*
+  * Rolls - these are the various rules that match weapons and perks in order to
+    make recommendations. Multiple rolls may apply to a single weapon, and all
+    of them will be shown. The order of rolls is not significant.
+  */
+
   /**
    * Per-item-hash rolls - each one specifies one or more rolls that are
-   * specific to a particular DestinyInventoryItem.
-   * E.g. "These are the god rolls for The Messenger"
+   * specific to a particular DestinyInventoryItem. E.g. "These are the god
+   * rolls for The Messenger"
    */
-  itemRolls: ItemRoll[];
+  itemRolls?: ItemRoll[];
   /**
-   * Perk rolls match specific plug combinations, but without specifying an item.
-   * E.g. "Outlaw + Kill Clip is always good"
+   * Perk rolls match specific plug combinations, but without specifying an
+   * item. E.g. "Outlaw + Kill Clip is always good"
    */
-  perkRolls: Roll[];
+  perkRolls?: Roll[];
   /**
-   * Rolls that apply to any weapons in a specific category.
-   * E.g. "Shotguns with Shot Package + Slideshot are always good".
+   * Rolls that apply to any weapons in a specific category. E.g. "Shotguns with
+   * Shot Package + Slideshot are always good".
    *
    * If you specify the intrinsic perk hash, you can also specify things like
    * "Adaptive Frame Scout Rifles with Surplus + Demolitionist are good"
    */
-  categoryRolls: CategoryRoll[];
+  categoryRolls?: CategoryRoll[];
 }
 
 /** These tags are meant to match the Little Light JSON wishlist tags. */
 type Tag =
   /** This roll is intended for use in PVE */
-  | 'PVE'
+  | 'PvE'
   /** This roll is intended for use in PVP */
-  | 'PVP'
+  | 'PvP'
   /** This roll is specifically good for mouse+keyboard users */
-  | 'Mouse'
+  | 'MnK'
   /** This roll is specifically good for controller users */
-  | 'Controller'
-  /** God Roll - "don't you dare throw this away" - not all guns need to have one of these! */
+  | 'Ctrl'
+  /**
+   * God Roll - "don't you dare throw this away" - not all guns need to have one
+   * of these!
+   */
   | 'Godroll'
   /**
    * Good Roll - "this is worth keeping/trying" - for guns you would tell
@@ -57,34 +97,82 @@ type Tag =
    */
   | 'Recommended'
   /**
-   * Trash - this sucks, these perks clash - controversial. makes people very
-   * sad when they see it, but like the roll
+   * Trash - this sucks, these perks clash - controversial. Makes people very
+   * sad when they see it, but like the roll. Allowing users to uncheck tags
+   * when importing wish lists may make using this viable.
    */
   | 'Trash'
   // Users are free to specify any other tag
   | string;
 
-// TODO: should we try to reduce the size of this?
 interface Roll {
-  name?: string; // Not used in DIM
+  /**
+   * An explanation about this roll. Usually contains a general explanation of
+   * the good and bad parts of this weapon.
+   */
   description?: string; // e.g. notes
-  plugs: number[][];
-  // Can be used to filter which rolls to show!
-  tags?: Tag[];
   /**
-   * UNIX timestamp (milliseconds) representing when this roll was created or
-   * updated. If not specified, uses the date from the wishlist it's in.
+   * Describe a combination of perks, which are really plugs for sockets.
+   *
+   * ItemHash is the `DestinyInventoryItem` hash for a socket plug.
+   *
+   * Each element in the top-level array represents a "group" of perks, which
+   * means they belong to the same socket (column) in the perk selection UI.
+   *
+   * Masterworks, Weapon Mod, Shader, and other non-Perk plugs *should not* be
+   * included.
+   *
+   * The order of perks group is not specified. Do not include empty groups.
+   *
+   * For hash in the same group, their relation is OR. For different groups,
+   * their relation is AND. (e.g. `[[1, 2], [3, 4]]` means `(1 OR 2) AND (3 OR
+   * 4)`)
+   *
+   * e.g. For `"Randy's Throwing Knife" <3292795429>`,
+   * - `[[247725512, 2387244414]]` is a valid value meaning "the weapon must
+   *   have plug 247725512 or 2387244414 available on it".
+   *   - Implementers should iterate the groups in `socketEntries`'s `plugSet`
+   *     info to determine the actual socket. (Recommended)
+   * - `[[247725512], [2387244414]]` is a valid value meaning "the weapon must
+   *   have plug 247725512 and 2387244414 available on it on different sockets".
+   *
+   * Implementers must ignore any invalid combination they can't match.
+   */
+  plugs: ItemHash[][];
+
+  /**
+   * Tag for the current combination. This can be used to show special flair on
+   * the item, as a search filter, or to allow users to select which types of
+   * tags they want to import from a wishlist.
+   *
+   * All tags that are not ReservedTags should be treated as user-defined tags.
    */
-  date?: number;
+  tags?: Tag[];
 }
 
 interface ItemRoll extends Roll {
-  /** Inventory item hash */
-  hash: number;
+  /** Inventory item hash this roll applies to. */
+  hash: ItemHash;
 }
 
 interface CategoryRoll extends Roll {
+  /**
+   * The subtypes of items this roll applies to. This allows targeting rolls to
+   * "Shotguns" for example.
+   */
   categories: DestinyItemSubType[];
-  /** Optional intrinsic perk hash, used to narrow this to a specific archetype. */
-  intrinsic?: number;
+  /**
+   * Optional intrinsic perk hash, used to narrow this to a specific archetype.
+   *
+   * If you specify the intrinsic perk hash, you can also specify things like
+   * "Adaptive Frame Scout Rifles with Surplus + Demolitionist are good".
+   */
+  intrinsic?: ItemHash;
+}
+
+interface Author {
+  /** The name of one of the authors of this wish list. */
+  name: string;
+  /** An optional URL to a public profile or home page for the author. */
+  url?: string;
 }