Merge pull request #195 from mollie/pimm/documentation-copy

Add documentation from docs.mollie.com.

src/data/chargebacks/Chargeback.ts

@@ -5,35 +5,49 @@ import Payment, { injectPrototypes as injectPaymentPrototypes } from '../payment
 import Seal from '../../types/Seal';
 import commonHelpers from '../commonHelpers';
 
-/**
- * Chargeback Response object.
- *
- * @param resource - Indicates the response contains a Chargeback object.
- *                   Will always contain `chargeback` for this endpoint.
- * @param id - The chargeback’s unique identifier, for example `chb_n9z0tp`.
- * @param amount - The amount charged back by the consumer.
- * @param settlementAmount - This optional field will contain the amount that will be deducted from your account,
- *                           converted to the currency your account is settled in. It follows the same syntax as
- *                           the `amount` property. Note that for chargebacks, the `value` key of `settlementAmount`
- *                           will be negative. Any amounts not settled by Mollie will not be reflected in this amount,
- *                           e.g. PayPal chargebacks.
- * @param createdAt - The date and time the chargeback was issued, in ISO 8601 format.
- * @param reversedAt - The date and time the chargeback was reversed if applicable, in ISO 8601 format.
- * @param paymentId - The unique identifier of the payment this chargeback was issued for. For example: `tr_7UhSN1zuXS`.
- *                    The full payment object can be retrieved via the `payment` URL in the `_links` object.
- * @param _links - An object with several URL objects relevant to the chargeback.
- *
- * @see https://docs.mollie.com/reference/v2/chargebacks-api/get-chargeback
- */
 export interface ChargebackData extends Model<'chargeback'> {
+  /**
+   * The amount charged back by the consumer.
+   *
+   * @see https://docs.mollie.com/reference/v2/chargebacks-api/get-chargeback?path=amount#response
+   */
   amount: Amount;
+  /**
+   * This optional field will contain the amount that will be deducted from your account, converted to the currency your account is settled in. It follows the same syntax as the `amount` property.
+   *
+   * Note that for chargebacks, the `value` key of `settlementAmount` will be negative.
+   *
+   * Any amounts not settled by Mollie will not be reflected in this amount, e.g. PayPal chargebacks.
+   *
+   * @see https://docs.mollie.com/reference/v2/chargebacks-api/get-chargeback?path=settlementAmount#response
+   */
   settlementAmount: Amount;
+  /**
+   * The date and time the chargeback was issued, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
+   *
+   * @see https://docs.mollie.com/reference/v2/chargebacks-api/get-chargeback?path=createdAt#response
+   */
   createdAt: string;
+  /**
+   * The date and time the chargeback was reversed if applicable, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
+   *
+   * @see https://docs.mollie.com/reference/v2/chargebacks-api/get-chargeback?path=reversedAt#response
+   */
   reversedAt: string;
+  /**
+   * The unique identifier of the payment this chargeback was issued for. For example: `tr_7UhSN1zuXS`. The full payment object can be retrieved via the `payment` URL in the `_links` object.
+   *
+   * @see https://docs.mollie.com/reference/v2/chargebacks-api/get-chargeback?path=paymentId#response
+   */
   paymentId: string;
   _embedded?: {
     payments?: Omit<PaymentData, '_embedded'>[];
   };
+  /**
+   * An object with several URL objects relevant to the chargeback. Every URL object will contain an `href` and a `type` field.
+   *
+   * @see https://docs.mollie.com/reference/v2/chargebacks-api/get-chargeback?path=_links#response
+   */
   _links: ChargebackLinks;
 }
 
@@ -48,15 +62,18 @@ type Chargeback = Seal<
 
 export default Chargeback;
 
-/**
- * Chargebacks _links object
- *
- * @param payment - The API resource URL of the payment this chargeback belongs to.
- * @param settlement - The API resource URL of the settlement this payment has been settled with. Not present if not
- *                     yet settled.
- */
 export interface ChargebackLinks extends Links {
+  /**
+   * The API resource URL of the payment this chargeback belongs to.
+   *
+   * @see https://docs.mollie.com/reference/v2/chargebacks-api/get-chargeback?path=_links/payment#response
+   */
   payment: Url;
+  /**
+   * The API resource URL of the settlement this payment has been settled with. Not present if not yet settled.
+   *
+   * @see https://docs.mollie.com/reference/v2/chargebacks-api/get-chargeback?path=_links/settlement#response
+   */
   settlement?: Url;
 }
 

src/data/customers/Customer.ts

@@ -3,36 +3,79 @@ import Model from '../Model';
 import Seal from '../../types/Seal';
 import commonHelpers from '../commonHelpers';
 
-/**
- * Customer Response object.
- *
- * @see https://docs.mollie.com/reference/v2/customers-api/get-customer
- */
 export interface CustomerData extends Model<'customer'> {
+  /**
+   * The mode used to create this customer.
+   *
+   * Possible values: `live` `test`
+   *
+   * @see https://docs.mollie.com/reference/v2/customers-api/get-customer?path=mode#response
+   */
   mode: ApiMode;
+  /**
+   * The full name of the customer as provided when the customer was created.
+   *
+   * @see https://docs.mollie.com/reference/v2/customers-api/get-customer?path=name#response
+   */
   name: string;
+  /**
+   * The email address of the customer as provided when the customer was created.
+   *
+   * @see https://docs.mollie.com/reference/v2/customers-api/get-customer?path=email#response
+   */
   email: string;
+  /**
+   * Allows you to preset the language to be used in the hosted payment pages shown to the consumer. If this parameter was not provided when the customer was created, the browser language will be used
+   * instead in the payment flow (which is usually more accurate).
+   *
+   * Possible values: `en_US` `nl_NL` `nl_BE` `fr_FR` `fr_BE` `de_DE` `de_AT` `de_CH` `es_ES` `ca_ES` `pt_PT` `it_IT` `nb_NO` `sv_SE` `fi_FI` `da_DK` `is_IS` `hu_HU` `pl_PL` `lv_LV` `lt_LT`
+   *
+   * @see https://docs.mollie.com/reference/v2/customers-api/get-customer?path=locale#response
+   */
   locale: Locale;
   recentlyUsedMethods: PaymentMethod[];
+  /**
+   * Data provided during the customer creation.
+   *
+   * @see https://docs.mollie.com/reference/v2/customers-api/get-customer?path=metadata#response
+   */
   metadata: Record<string, string>;
+  /**
+   * The customer's date and time of creation, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
+   *
+   * @see https://docs.mollie.com/reference/v2/customers-api/get-customer?path=createdAt#response
+   */
   createdAt: string;
+  /**
+   * An object with several URL objects relevant to the customer. Every URL object will contain an `href` and a `type` field.
+   *
+   * @see https://docs.mollie.com/reference/v2/customers-api/get-customer?path=_links#response
+   */
   _links: CustomerLinks;
 }
 
 type Customer = Seal<CustomerData, typeof commonHelpers>;
 
 export default Customer;
 
-/**
- * Customer _links object
- *
- * @param mandates - Mandates list
- * @param subscriptions - Subscriptions list
- * @param payments - Payments list
- */
 export interface CustomerLinks extends Links {
+  /**
+   * The API resource URL of the mandates belonging to the Customer, if there are no mandates this parameter is omitted.
+   *
+   * @see https://docs.mollie.com/reference/v2/customers-api/get-customer?path=_links/mandates#response
+   */
   mandates: Url;
+  /**
+   * The API resource URL of the subscriptions belonging to the Customer, if there are no subscriptions this parameter is omitted.
+   *
+   * @see https://docs.mollie.com/reference/v2/customers-api/get-customer?path=_links/subscriptions#response
+   */
   subscriptions: Url;
+  /**
+   * The API resource URL of the payments belonging to the Customer, if there are no payments this parameter is omitted.
+   *
+   * @see https://docs.mollie.com/reference/v2/customers-api/get-customer?path=_links/payments#response
+   */
   payments: Url;
 }
 

src/data/customers/mandates/data.ts

@@ -2,23 +2,67 @@ import { ApiMode, CardLabel, Links, Url } from '../../global';
 import Model from '../../Model';
 import Nullable from '../../../types/Nullable';
 
-/**
- * Mandate Response object
- *
- * @see https://docs.mollie.com/reference/v2/mandates-api/get-mandate
- */
 export interface MandateData extends Model<'mandate'> {
+  /**
+   * The mode used to create this mandate.
+   *
+   * @see https://docs.mollie.com/reference/v2/mandates-api/get-mandate?path=mode#response
+   */
   mode: ApiMode;
+  /**
+   * The status of the mandate. Please note that a status can be `pending` for mandates when the first payment is not yet finalized or when we did not received the IBAN yet.
+   *
+   * Possible values: `valid` `pending` `invalid`
+   *
+   * @see https://docs.mollie.com/reference/v2/mandates-api/get-mandate?path=status#response
+   */
   status: MandateStatus;
+  /**
+   * Payment method of the mandate.
+   *
+   * Possible values: `directdebit` `creditcard` `paypal`
+   *
+   * @see https://docs.mollie.com/reference/v2/mandates-api/get-mandate?path=method#response
+   */
   method: MandateMethod;
+  /**
+   * The mandate detail object contains different fields per payment method. See the list below.
+   *
+   * @see https://docs.mollie.com/reference/v2/mandates-api/get-mandate?path=details#response
+   */
   details: MandateDetails;
+  /**
+   * The mandate's custom reference, if this was provided when creating the mandate.
+   *
+   * @see https://docs.mollie.com/reference/v2/mandates-api/get-mandate?path=mandateReference#response
+   */
   mandateReference: string;
+  /**
+   * The signature date of the mandate in `YYYY-MM-DD` format.
+   *
+   * @see https://docs.mollie.com/reference/v2/mandates-api/get-mandate?path=signatureDate#response
+   */
   signatureDate: string;
+  /**
+   * The mandate's date and time of creation, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
+   *
+   * @see https://docs.mollie.com/reference/v2/mandates-api/get-mandate?path=createdAt#response
+   */
   createdAt: string;
+  /**
+   * An object with several URL objects relevant to the mandate. Every URL object will contain an `href` and a `type` field.
+   *
+   * @see https://docs.mollie.com/reference/v2/mandates-api/get-mandate?path=_links#response
+   */
   _links: MandateLinks;
 }
 
 export interface MandateLinks extends Links {
+  /**
+   * The API resource URL of the customer the mandate is for.
+   *
+   * @see https://docs.mollie.com/reference/v2/mandates-api/get-mandate?path=_links/customer#response
+   */
   customer: Url;
 }
 

src/data/customers/mandates/helpers.ts

@@ -4,7 +4,7 @@ import commonHelpers from '../../commonHelpers';
 export default {
   ...commonHelpers,
   /**
-   * If the mandate is valid
+   * Returns whether the mandate is valid.
    */
   isValid: function isValid(this: MandateData): boolean {
     return this.status === MandateStatus.valid;

src/data/global.ts

@@ -54,12 +54,6 @@ export enum ApiMode {
   live = 'live',
 }
 
-export interface Image {
-  size1x: string;
-  size2x: string;
-  svg: string;
-}
-
 export interface Url {
   href: string;
   type: string;

src/data/methods/data.ts

@@ -1,37 +1,67 @@
-import { Amount, FeeRegion, Image, Links, PaymentMethod as PaymentMethodEnum } from '../global';
+import { Amount, FeeRegion, Links, PaymentMethod as PaymentMethodEnum } from '../global';
 import Model from '../Model';
 import Nullable from '../../types/Nullable';
 
-/**
- * Method Response object.
- *
- * @param resource - Indicates the response contains a method object. Will always contain `method` for this endpoint.
- * @param id - The unique identifier of the payment method. When used during payment creation, the payment method
- *             selection screen will be skipped.
- * @param description - The full name of the payment method, translated in the optional locale passed.
- * @param image - The URLs of images representing the payment method.
- * @param pricing - See {@link IMethodPricing}
- * @param _links - An object with several URL objects relevant to the payment method.
- *
- * @see https://docs.mollie.com/reference/v2/methods-api/get-method
- */
 export interface MethodData extends Model<'method', PaymentMethodEnum> {
+  /**
+   * The full name of the payment method, translated in the optional locale passed.
+   *
+   * @see https://docs.mollie.com/reference/v2/methods-api/get-method?path=description#response
+   */
   description: string;
   /**
-   * An object containing `value` and `currency`. It represents the minimum payment amount required to use this payment
-   * method.
+   * An object containing `value` and `currency`. It represents the minimum payment amount required to use this payment method.
+   *
+   * @see https://docs.mollie.com/reference/v2/methods-api/get-method?path=minimumAmount#response
    */
   minimumAmount: Amount;
   /**
-   * An object containing `value` and `currency`. It represents the maximum payment amount allowed when using this
-   * payment method.
+   * An object containing `value` and `currency`. It represents the maximum payment amount allowed when using this payment method.
+   *
+   * @see https://docs.mollie.com/reference/v2/methods-api/get-method?path=maximumAmount#response
    */
   maximumAmount: Nullable<Amount>;
+  /**
+   * The URLs of images representing the payment method.
+   *
+   * @see https://docs.mollie.com/reference/v2/methods-api/get-method?path=image#response
+   */
   image: Image;
+  /**
+   * Pricing set of the payment method what will be include if you add the parameter.
+   *
+   * @see https://docs.mollie.com/reference/v2/methods-api/get-method?path=pricing#response
+   */
   pricing: MethodPricing;
+  /**
+   * An object with several URL objects relevant to the payment method. Every URL object will contain an `href` and a `type` field.
+   *
+   * @see https://docs.mollie.com/reference/v2/methods-api/get-method?path=_links#response
+   */
   _links: Links;
 }
 
+export interface Image {
+  /**
+   * The URL for a payment method icon of 32x24 pixels.
+   *
+   * @see https://docs.mollie.com/reference/v2/methods-api/get-method?path=image/size1x#response
+   */
+  size1x: string;
+  /**
+   * The URL for a payment method icon of 64x48 pixels.
+   *
+   * @see https://docs.mollie.com/reference/v2/methods-api/get-method?path=image/size2x#response
+   */
+  size2x: string;
+  /**
+   * The URL for a payment method icon in vector format. Usage of this format is preferred since it can scale to any desired size.
+   *
+   * @see https://docs.mollie.com/reference/v2/methods-api/get-method?path=image/svg#response
+   */
+  svg: string;
+}
+
 export enum MethodImageSize {
   size1x = 'size1x',
   size2x = 'size2x',
@@ -43,19 +73,9 @@ export enum MethodInclude {
   pricing = 'pricing',
 }
 
-/**
- * Pricing set of the payment method what will be include if you add the parameter.
- *
- * @param description - The area or product-type where the pricing is applied for, translated in the optional locale passed.
- * @param fixed - The fixed price per transaction
- * @param variable - A string containing the percentage what will be charged over the payment amount besides the fixed price.
- */
 export interface MethodPricing {
   description: string;
   fixed: Amount;
   variable: string;
-  /**
-   * This value is only available for credit card rates.
-   */
   feeRegion: FeeRegion;
 }