diff --git a/src/server/types/AppearanceLayer.js b/src/server/types/AppearanceLayer.js index f003242..0591ebb 100644 --- a/src/server/types/AppearanceLayer.js +++ b/src/server/types/AppearanceLayer.js @@ -17,12 +17,14 @@ const typeDefs = gql` # Cache for 1 week (unlikely to change) type AppearanceLayer @cacheControl(maxAge: 604800) { - # The DTI ID. Guaranteed unique across all layers of all types. + "The DTI ID. Guaranteed unique across all layers of all types." id: ID! - # The Neopets ID. Guaranteed unique across layers of the _same_ type, but - # not of different types. That is, it's allowed and common for an item - # layer and a pet layer to have the same remoteId. + """ + The Neopets ID. Guaranteed unique across layers of the _same_ type, but + not of different types. That is, it's allowed and common for an item + layer and a pet layer to have the same remoteId. + """ remoteId: ID! zone: Zone! diff --git a/src/server/types/ClosetList.js b/src/server/types/ClosetList.js index 81447f9..f3926ba 100644 --- a/src/server/types/ClosetList.js +++ b/src/server/types/ClosetList.js @@ -12,10 +12,15 @@ const typeDefs = gql` id: ID! name: String - # A user-customized description. May contain Markdown and limited HTML. + """ + A user-customized description. May contain Markdown and limited HTML. + WARNING: If you're using this in an application, you MUST ensure that the + content is rendered safely! Do not render this as HTML unless you + are confident that you've sanitized it appropriately. + """ description: String - # Whether this is a list of items they own, or items they want. + "Whether this is a list of items they own, or items they want." ownsOrWantsItems: OwnsOrWants! # Each user has a "default list" of items they own/want. When users click @@ -30,8 +35,10 @@ const typeDefs = gql` } extend type Mutation { - # Edit the metadata of a closet list. Requires the current user to own the - # list, or for the correct supportSecret to be provided. + """ + Edit the metadata of a closet list. Requires the current user to own the + list, or for the correct supportSecret to be provided. + """ editClosetList( closetListId: ID! name: String! diff --git a/src/server/types/Item.js b/src/server/types/Item.js index 218e961..6d6d3ae 100644 --- a/src/server/types/Item.js +++ b/src/server/types/Item.js @@ -15,101 +15,129 @@ const typeDefs = gql` thumbnailUrl: String! rarityIndex: Int! - # Whether this item comes from the NC Mall. + "Whether this item comes from the NC Mall." isNc: Boolean! - # Whether this item comes from a paintbrush. + "Whether this item comes from a paintbrush." isPb: Boolean! - # When this item was first added to DTI. ISO 8601 string, or null if the - # item was added so long ago that we don't have this field! + """ + When this item was first added to DTI. ISO 8601 string, or null if the + item was added so long ago that we don't have this field! + """ createdAt: String - # This item's capsule trade value as text, according to wakaguide.com, as a - # human-readable string. Will be null if the value is not known, or if - # there's an error connecting to the data source. + """ + This item's capsule trade value as text, according to wakaguide.com, as a + human-readable string. Will be null if the value is not known, or if + there's an error connecting to the data source. + """ wakaValueText: String @cacheControl(maxAge: ${oneHour}) currentUserOwnsThis: Boolean! @cacheControl(scope: PRIVATE) currentUserWantsThis: Boolean! @cacheControl(scope: PRIVATE) - # How many users are offering/seeking this in their public trade lists. - # Excludes users that seem relatively inactive. + """ + How many users are offering/seeking this in their public trade lists. + Excludes users that seem relatively inactive. + """ numUsersOfferingThis: Int! @cacheControl(maxAge: ${oneHour}) numUsersSeekingThis: Int! @cacheControl(maxAge: ${oneHour}) - # The trades available for this item, grouped by offering vs seeking. + "The trades available for this item, grouped by offering vs seeking." tradesOffering: [ItemTrade!]! @cacheControl(maxAge: 0) tradesSeeking: [ItemTrade!]! @cacheControl(maxAge: 0) - # How this item appears on the given species/color combo. If it does not - # fit the pet, we'll return an empty ItemAppearance with no layers. + """ + How this item appears on the given species/color combo. If it does not + fit the pet, we'll return an empty ItemAppearance with no layers. + """ appearanceOn(speciesId: ID!, colorId: ID!): ItemAppearance! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneDay}) - # This is set manually by Support users, when the pet is only for e.g. - # Maraquan pets, and our usual auto-detection isn't working. We provide - # this for the Support UI; it's not very helpful for most users, because it - # can be empty even if the item _has_ an auto-detected special color. + """ + This is set manually by Support users, when the pet is only for e.g. + Maraquan pets, and our usual auto-detection isn't working. We provide + this for the Support UI; it's not very helpful for most users, because it + can be empty even if the item _has_ an auto-detected special color. + """ manualSpecialColor: Color @cacheControl(maxAge: 0) - # This is set manually by Support users, when the item _seems_ to fit all - # pets the same because of its zones, but it actually doesn't - e.g., - # the Dug Up Dirt Foreground actually looks different for each body. We - # provide this for the Support UI; it's not very helpful for most users, - # because it's only used at modeling time. This value does not change how - # layer data from this API should be interpreted! + """ + This is set manually by Support users, when the item _seems_ to fit all + pets the same because of its zones, but it actually doesn't - e.g., + the Dug Up Dirt Foreground actually looks different for each body. We + provide this for the Support UI; it's not very helpful for most users, + because it's only used at modeling time. This value does not change how + layer data from this API should be interpreted! + """ explicitlyBodySpecific: Boolean! @cacheControl(maxAge: 0) - # This is set manually by Support users, when the item is from the NC Mall - # but isn't correctly labeled as r500 on Neopets.com. When this is true, - # it sets isNc to be true as well, regardless of rarityIndex. + """ + This is set manually by Support users, when the item is from the NC Mall + but isn't correctly labeled as r500 on Neopets.com. When this is true, + it sets isNc to be true as well, regardless of rarityIndex. + """ isManuallyNc: Boolean! - # Get the species that we need modeled for this item for the given color. - # - # NOTE: Most color IDs won't be accepted here. Either pass the ID of a - # major special color like Baby (#6), or leave it blank for standard - # bodies like Blue, Green, Red, etc. + """ + Get the species that we need modeled for this item for the given color. + + NOTE: Most color IDs won't be accepted here. Either pass the ID of a + major special color like Baby (#6), or leave it blank for standard + bodies like Blue, Green, Red, etc. + """ speciesThatNeedModels(colorId: ID): [Species!]! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneHour}) - # Return a single ItemAppearance for this item. It'll be for the species - # with the smallest ID for which we have item appearance data, and a basic - # color. We use this on the item page, to initialize the preview section. - # (You can find out which species this is for by going through the body - # field on ItemAppearance!) - # - # There's also optional fields preferredSpeciesId and preferredColorId, to - # request a certain species or color if possible. We'll try to match each, - # with precedence to species first; then fall back to the canonical values. - # - # Note that the exact choice of color doesn't usually affect this field, - # because ItemAppearance is per-body rather than per-color. It's most - # relevant for special colors like Baby or Mutant. But the - # canonicalAppearance on the Body type _does_ use the preferred color more - # precisely! + """ + Return a single ItemAppearance for this item. It'll be for the species + with the smallest ID for which we have item appearance data, and a basic + color. We use this on the item page, to initialize the preview section. + (You can find out which species this is for by going through the body + field on ItemAppearance!) + + There's also optional fields preferredSpeciesId and preferredColorId, to + request a certain species or color if possible. We'll try to match each, + with precedence to species first; then fall back to the canonical values. + + Note that the exact choice of color doesn't usually affect this field, + because ItemAppearance is per-body rather than per-color. It's most + relevant for special colors like Baby or Mutant. But the + canonicalAppearance on the Body type _does_ use the preferred color more + precisely! + """ canonicalAppearance(preferredSpeciesId: ID, preferredColorId: ID): ItemAppearance @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneWeek}) - # All zones that this item occupies, for at least one body. That is, it's - # a union of zones for all of its appearances! We use this for overview - # info about the item. + """ + All zones that this item occupies, for at least one body. That is, it's + a union of zones for all of its appearances! We use this for overview + info about the item. + """ allOccupiedZones: [Zone!]! @cacheControl(maxAge: ${oneHour}) - # The zones this item restricts. Turns out, even though we offer this on - # ItemAppearance for consistency, this is static across all appearances. + """ + The zones this item restricts. Turns out, even though we offer this on + ItemAppearance for consistency, this is static across all appearances. + """ restrictedZones: [Zone!]! @cacheControl(maxAge: ${oneHour}, staleWhileRevalidate: ${oneWeek}) - # All bodies that this item is compatible with. Note that this might return - # the special representsAllPets body, e.g. if this is just a Background! - # Deprecated: Impress 2020 now uses compatibleBodiesAndTheirZones. + """ + All bodies that this item is compatible with. Note that this might return + the special representsAllPets body, e.g. if this is just a Background! + Deprecated: Impress 2020 now uses compatibleBodiesAndTheirZones. + """ compatibleBodies: [Body!]! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneWeek}) - # All bodies that this item is compatible with, and the zones this item - # occupies for that body. Note that this might return the special - # representsAllPets body, e.g. if this is just a Background! + """ + All bodies that this item is compatible with, and the zones this item + occupies for that body. Note that this might return the special + representsAllPets body, e.g. if this is just a Background! + """ compatibleBodiesAndTheirZones: [BodyAndZones!]! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneWeek}) - # All appearances for this item. Used in Support tools, to show and manage - # how this item fits every pet body. + """ + All appearances for this item. Used in Support tools, to show and manage + how this item fits every pet body. + """ allAppearances: [ItemAppearance!]! } diff --git a/src/server/types/Outfit.js b/src/server/types/Outfit.js index fcfda7c..99293c7 100644 --- a/src/server/types/Outfit.js +++ b/src/server/types/Outfit.js @@ -16,14 +16,16 @@ const typeDefs = gql` closetedItems: [Item!]! creator: User - # When this outfit was created. ISO 8601 string. + "When this outfit was created. ISO 8601 string." createdAt: String! - # When this outfit was last updated. ISO 8601 string. + "When this outfit was last updated. ISO 8601 string." updatedAt: String! - # This is a convenience field: you could query this from the combination of - # petAppearance and wornItems, but this gets you it in one shot! + """ + This is a convenience field: you could query this from the combination of + petAppearance and wornItems, but this gets you it in one shot! + """ itemAppearances: [ItemAppearance!]! } @@ -34,8 +36,10 @@ const typeDefs = gql` extend type Mutation { saveOutfit( - id: ID # Optional, is null when saving new outfits. - name: String # Optional, server may fill in a placeholder. + "Optional, is null when saving new outfits." + id: ID + "Optional, server may fill in a placeholder." + name: String speciesId: ID! colorId: ID! pose: Pose! diff --git a/src/server/types/Pet.js b/src/server/types/Pet.js index e588ee3..5c78ae0 100644 --- a/src/server/types/Pet.js +++ b/src/server/types/Pet.js @@ -11,10 +11,14 @@ const typeDefs = gql` petAppearance: PetAppearance! wornItems: [Item!]! - species: Species! # to be deprecated? can use petAppearance? 🤔 - color: Color! # to be deprecated? can use petAppearance? 🤔 - pose: Pose! # to be deprecated? can use petAppearance? 🤔 - items: [Item!]! # deprecated alias for wornItems + "to be deprecated? can use petAppearance? 🤔" + species: Species! + "to be deprecated? can use petAppearance? 🤔" + color: Color! + "to be deprecated? can use petAppearance? 🤔" + pose: Pose! + "deprecated alias for wornItems" + items: [Item!]! } extend type Query { diff --git a/src/server/types/PetAppearance.js b/src/server/types/PetAppearance.js index ac3e6c5..42f7f1e 100644 --- a/src/server/types/PetAppearance.js +++ b/src/server/types/PetAppearance.js @@ -16,7 +16,7 @@ const typeDefs = gql` name: String! isStandard: Boolean! - # All SpeciesColorPairs of this color. + "All SpeciesColorPairs of this color." appliedToAllCompatibleSpecies: [SpeciesColorPair!]! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneDay}) } @@ -24,13 +24,17 @@ const typeDefs = gql` id: ID! name: String! - # A PetAppearance that has this species. Prefers Blue (or the optional - # preferredColorId), and happy poses. + """ + A PetAppearance that has this species. Prefers Blue (or the optional + preferredColorId), and happy poses. + """ canonicalAppearance(preferredColorId: ID): PetAppearance - # The bodyId for PetAppearances that use this species and a standard color. - # We use this to preload the standard body IDs, so that items stay when - # switching between standard colors. + """ + The bodyId for PetAppearances that use this species and a standard color. + We use this to preload the standard body IDs, so that items stay when + switching between standard colors. + """ standardBodyId: ID! } diff --git a/src/server/types/User.js b/src/server/types/User.js index 9d8507a..2fb5f89 100644 --- a/src/server/types/User.js +++ b/src/server/types/User.js @@ -13,20 +13,26 @@ const typeDefs = gql` itemsTheyOwn: [Item!]! itemsTheyWant: [Item!]! - # These items represent potential trade matches. We use this as a preview - # in the trade list table. + """ + These items represent potential trade matches. We use this as a preview + in the trade list table. + """ itemsTheyOwnThatCurrentUserWants: [Item!]! itemsTheyWantThatCurrentUserOwns: [Item!]! - # When this user last updated any of their trade lists, as an ISO 8601 - # timestamp. + """ + When this user last updated any of their trade lists, as an ISO 8601 + timestamp. + """ lastTradeActivity: String! - # This user's outfits. Returns an empty list if the current user is not - # authorized to see them. + """ + This user's outfits. Returns an empty list if the current user is not + authorized to see them. + """ outfits: [Outfit!]! - # This user's email address. Requires the correct supportSecret to view. + "This user's email address. Requires the correct supportSecret to view." emailForSupportUsers(supportSecret: String!): String! }