Merge pull request #82 from GW2Treasures/feature/commerce-delivery

Add types for `/v2/commerce/delivery` and `/v2/commerce/exchange`

.changeset/five-ways-teach.md

@@ -0,0 +1,5 @@
+---
+"@gw2api/types": patch
+---
+
+Add types for `/v2/commerce/delivery`

.changeset/popular-wombats-return.md

@@ -0,0 +1,5 @@
+---
+"@gw2api/types": patch
+---
+
+Add types for `/v2/commerce/exchange`

.changeset/proud-files-help.md

@@ -0,0 +1,5 @@
+---
+"@gw2api/types": patch
+---
+
+Improve commerce types

packages/types/data/commerce.ts

@@ -1,33 +1,118 @@
-type PriceDetail = {
+/**
+ * Delivery as returned from /v2/commerce/delivery
+ * @see https://wiki.guildwars2.com/wiki/API:2/commerce/delivery
+ */
+export interface Delivery {
+  /** The amount of coins ready for pickup */
+  coins: number,
+
+  /** Items waiting for pickup */
+  items: Delivery.Item[]
+}
+
+export namespace Delivery {
+  export interface Item {
+    /** The id of the item, resolvable against /v2/items */
+    id: number,
+
+    /** The amount of items */
+    count: number
+  }
+}
+
+
+/**
+ * Listing as returned from /v2/commerce/exchange/{coins,gems}
+ * @see https://wiki.guildwars2.com/wiki/API:2/commerce/exchange
+ */
+export interface Exchange {
+  /** The amount of coins per single gem */
+  coins_per_gem: number,
+
+  /** The amount exchanged for the specified quantity */
   quantity: number,
-  unit_price: number,
 }
 
-type ListingDetail = PriceDetail & {
-  listings: number,
+
+/**
+ * Listing as returned from /v2/commerce/listings
+ * @see https://wiki.guildwars2.com/wiki/API:2/commerce/listings
+ */
+export interface Listing {
+  /** The id of the item, resolvable against /v2/items */
+  id: number,
+
+  /** Current buy listings */
+  buys: Listing.Detail[],
+
+  /** Current sell listings */
+  sells: Listing.Detail[],
+}
+
+export namespace Listing {
+  export interface Detail extends Price.Detail {
+    /** Amount of listings */
+    listings: number,
+  }
 }
 
-export type Price = {
+
+/**
+ * Price as returned from /v2/commerce/prices
+ * @see https://wiki.guildwars2.com/wiki/API:2/commerce/prices
+ */
+export interface Price {
+  /** The id of the item, resolvable against /v2/items */
   id: number,
+
+  /** Flag if the item is available for Free to Play accounts */
   whitelisted: boolean,
-  buys: PriceDetail,
-  sells: PriceDetail,
+
+  /** Buy price details */
+  buys: Price.Detail,
+
+  /** Sell price details */
+  sells: Price.Detail,
 }
 
-export type Listing = {
-  id: number,
-  buys: ListingDetail[],
-  sells: ListingDetail[],
+export namespace Price {
+  export interface Detail {
+    /** Amount of items listed at this price */
+    quantity: number,
+
+    /** Price per item */
+    unit_price: number,
+  }
 }
 
-export type TransactionCurrent = {
+
+/**
+ * Transactions as returned from /v2/commerce/transactions/current
+ * @see https://wiki.guildwars2.com/wiki/API:2/commerce/transactions
+ */
+export interface TransactionCurrent {
+  /** Transaction id */
   id: number,
+
+  /** The id of the item, resolvable against /v2/items */
   item_id: number,
+
+  /** The price of the transaction */
   price: number,
+
+  /** The amount of items in this transaction */
   quantity: number,
+
+  /** The transaction creation date as ISO-8601 timestamp */
   created: string
 }
 
-export type TransactionHistoric = TransactionCurrent & {
+
+/**
+ * Transactions as returned from /v2/commerce/transactions/history
+ * @see https://wiki.guildwars2.com/wiki/API:2/commerce/transactions
+ */
+export interface TransactionHistoric extends TransactionCurrent {
+  /** The date of purchase as ISO-8601 timestamp */
   purchased: string
 }

packages/types/endpoints.ts

@@ -13,7 +13,7 @@ import type { AchievementCategory } from './data/achievement-category';
 import type { AchievementGroup } from './data/achievement-group';
 import type { Character, CharacterBackstory, CharacterBuildTab, CharacterCore, CharacterCrafting, CharacterEquipment, CharacterEquipmentTab, CharacterInventory, CharacterRecipes, CharacterSkills, CharacterSpecializations, CharacterTraining } from './data/character';
 import type { Color } from './data/color';
-import type { Listing, Price, TransactionCurrent, TransactionHistoric } from './data/commerce';
+import type { Delivery, Exchange, Listing, Price, TransactionCurrent, TransactionHistoric } from './data/commerce';
 import type { Createsubtoken } from './data/createsubtoken';
 import type { Currency } from './data/currency';
 import type { GuildUpgrade } from './data/guild';
@@ -128,7 +128,8 @@ export type KnownUnauthorizedEndpoint =
   | '/v2/backstory/questions'
   | '/v2/build'
   | '/v2/colors'
-  | '/v2/commerce/exchange'
+  | '/v2/commerce/exchange/coins'
+  | '/v2/commerce/exchange/gems'
   | '/v2/commerce/listings'
   | '/v2/commerce/prices'
   | '/v2/continents'
@@ -359,7 +360,7 @@ type BulkExpandedResponseType<Endpoint extends KnownBulkExpandedEndpoint, Url ex
   // otherwise this is not a known bulk request
   unknown
 
-// createsubtoken request
+// /v2/createsubtoken request
 type CreateSubtokenUrl<Url extends KnownEndpoint> =
   | WithParameters<Url, CombineParameters<`expire=${string}`, CombineParameters<`permissions=${string}`, `urls=${string}`>>>
   | WithParameters<Url, CombineParameters<`expire=${string}`, `permissions=${string}`>>
@@ -370,6 +371,10 @@ type CreateSubtokenUrl<Url extends KnownEndpoint> =
   | WithParameters<Url, `urls=${string}`>
   | Url
 
+// /v2/commerce/exchange request
+type CommerceExchangeUrl<Url extends KnownEndpoint> =
+  | WithParameters<Url, `quantity=${number}`>
+
 // options
 type Options = {}
 
@@ -461,6 +466,8 @@ export type EndpointType<Url extends KnownEndpoint | (string & {}), Schema exten
   Url extends BulkExpandedEndpointUrl<'/v2/skills', number> ? BulkExpandedResponseType<'/v2/skills', Url, number, Skill> :
   Url extends BulkExpandedEndpointUrl<'/v2/skins', number> ? BulkExpandedResponseType<'/v2/skins', Url, number, Skin> :
   Url extends BulkExpandedEndpointUrl<'/v2/titles', number> ? BulkExpandedResponseType<'/v2/titles', Url, number, Title> :
+  Url extends '/v2/commerce/delivery' ? Delivery :
+  Url extends CommerceExchangeUrl<'/v2/commerce/exchange/coins' | '/v2/commerce/exchange/gems'> ? Exchange :
   Url extends BulkExpandedEndpointUrl<'/v2/commerce/listings', number> ? BulkExpandedResponseType<'/v2/commerce/listings', Url, number, Listing> :
   Url extends BulkExpandedEndpointUrl<'/v2/commerce/prices', number> ? BulkExpandedResponseType<'/v2/commerce/prices', Url, number, Price> :
   Url extends PaginatedEndpointUrl<'/v2/commerce/transactions/current/buys'> ? TransactionCurrent[] :