Deprecate predictable helper methods

src/createMollieClient.ts

@@ -158,3 +158,5 @@ export { OrderLineType } from './data/orders/orderlines/OrderLine';
 export { PaymentEmbed, PaymentStatus } from './data/payments/data';
 export { RefundEmbed, RefundStatus } from './data/refunds/data';
 export { SubscriptionStatus } from './data/subscription/data';
+export { ProfileStatus } from './data/profiles/data';
+export { OnboardingStatus } from './data/onboarding/data';

src/data/customers/mandates/MandateHelper.ts

@@ -13,6 +13,8 @@ export default class MandateHelper extends Helper<MandateData, Mandate> {
 
   /**
    * Returns whether the mandate is valid.
+   *
+   * @deprecated Use `mandate.status == MandateStatus.valid` instead.
    */
   public isValid(this: MandateData): boolean {
     return this.status === MandateStatus.valid;

src/data/list/List.ts

@@ -4,6 +4,9 @@ import { Links, Url } from '../global';
 
 export default interface List<T> extends Array<T> {
   links: ListLinks;
+  /**
+   * @deprecated Use `list.length` instead.
+   */
   count: number;
   nextPageCursor: Maybe<string>;
   previousPageCursor: Maybe<string>;

src/data/onboarding/OnboardingHelper.ts

@@ -3,24 +3,33 @@ import TransformingNetworkClient from '../../TransformingNetworkClient';
 import Callback from '../../types/Callback';
 import Helper from '../Helper';
 import Organization, { OrganizationData } from '../organizations/Organizations';
-import { OnboardingData } from './data';
+import { OnboardingData, OnboardingStatus } from './data';
 import Onboarding from './Onboarding';
 
 export default class OnboardingHelper extends Helper<OnboardingData, Onboarding> {
   constructor(networkClient: TransformingNetworkClient, protected readonly links: OnboardingData['_links']) {
     super(networkClient, links);
   }
 
+  /**
+   * @deprecated Use `onboarding.status == OnboardingStatus.needsData` instead.
+   */
   public needsData(this: OnboardingData) {
-    return this.status == 'needs-data';
+    return this.status == OnboardingStatus.needsData;
   }
 
+  /**
+   * @deprecated Use `onboarding.status == OnboardingStatus.inReview` instead.
+   */
   public isInReview(this: OnboardingData) {
-    return this.status == 'in-review';
+    return this.status == OnboardingStatus.inReview;
   }
 
+  /**
+   * @deprecated Use `onboarding.status == OnboardingStatus.completed` instead.
+   */
   public isCompleted(this: OnboardingData) {
-    return this.status == 'completed';
+    return this.status == OnboardingStatus.completed;
   }
 
   /**

src/data/onboarding/data.ts

@@ -28,7 +28,7 @@ export interface OnboardingData extends Model<'onboarding', undefined> {
    *
    * @see https://docs.mollie.com/reference/v2/onboarding-api/get-onboarding-status?path=status#response
    */
-  status: 'needs-data' | 'in-review' | 'completed';
+  status: OnboardingStatus;
   /**
    * Whether or not the organization can receive payments.
    *
@@ -63,3 +63,9 @@ export interface OnboardingLinks extends Links {
    */
   organization: Url;
 }
+
+export enum OnboardingStatus {
+  needsData = 'needs-data',
+  inReview = 'in-review',
+  completed = 'completed',
+}

src/data/payments/PaymentHelper.ts

@@ -25,13 +25,17 @@ export default class PaymentHelper extends Helper<PaymentData, Payment> {
 
   /**
    * Returns whether the payment has been created, but nothing else has happened with it yet.
+   *
+   * @deprecated Use `payment.status == PaymentStatus.open` instead.
    */
   public isOpen(this: PaymentData): boolean {
     return this.status === PaymentStatus.open;
   }
 
   /**
    * Returns whether new captures can be created for this payment.
+   *
+   * @deprecated Use `payment.status == PaymentStatus.authorized` instead.
    */
   public isAuthorized(this: PaymentData): boolean {
     return this.status === PaymentStatus.authorized;
@@ -46,13 +50,17 @@ export default class PaymentHelper extends Helper<PaymentData, Payment> {
 
   /**
    * Returns whether the payment has been canceled by the customer.
+   *
+   * @deprecated Use `payment.status == PaymentStatus.canceled` instead.
    */
   public isCanceled(this: PaymentData): boolean {
     return this.status == PaymentStatus.canceled;
   }
 
   /**
    * Returns whether the payment has expired, e.g. the customer has abandoned the payment.
+   *
+   * @deprecated Use `payment.status == PaymentStatus.expired` instead.
    */
   public isExpired(this: PaymentData): boolean {
     return this.status == PaymentStatus.expired;
@@ -70,12 +78,14 @@ export default class PaymentHelper extends Helper<PaymentData, Payment> {
   /**
    * Returns the URL the customer should visit to make the payment. This is to where you should redirect the consumer.
    */
-  public getPaymentUrl(): string {
+  public getPaymentUrl(): Nullable<string> {
     return get(this.links, 'checkout.href', null);
   }
 
   /**
    * Returns whether the payment has failed and cannot be completed with a different payment method.
+   *
+   * @deprecated Use `payment.status == PaymentStatus.failed` instead.
    */
   public isFailed(this: PaymentData): boolean {
     return this.status == PaymentStatus.failed;
@@ -84,6 +94,8 @@ export default class PaymentHelper extends Helper<PaymentData, Payment> {
   /**
    * Returns whether the payment is in this temporary status that can occur when the actual payment process has been
    * started, but has not completed yet.
+   *
+   * @deprecated Use `payment.status == PaymentStatus.pending` instead.
    */
   public isPending(this: PaymentData): boolean {
     return this.status == PaymentStatus.pending;
@@ -106,6 +118,8 @@ export default class PaymentHelper extends Helper<PaymentData, Payment> {
   /**
    * Returns whether `sequenceType` is set to `'first'`. If a `'first'` payment has been completed successfully, the
    * consumer's account may be charged automatically using recurring payments.
+   *
+   * @deprecated Use `payment.sequenceType == SequenceType.first` instead.
    */
   public hasSequenceTypeFirst(this: PaymentData): boolean {
     return this.sequenceType == SequenceType.first;
@@ -114,6 +128,8 @@ export default class PaymentHelper extends Helper<PaymentData, Payment> {
   /**
    * Returns whether `sequenceType` is set to `'recurring'`. This type of payment is processed without involving the
    * consumer.
+   *
+   * @deprecated Use `payment.sequenceType == SequenceType.recurring` instead.
    */
   public hasSequenceTypeRecurring(this: PaymentData): boolean {
     return this.sequenceType == SequenceType.recurring;
@@ -144,6 +160,8 @@ export default class PaymentHelper extends Helper<PaymentData, Payment> {
   /**
    * Returns the total amount that is already refunded. For some payment methods, this amount may be higher than the
    * payment amount, for example to allow reimbursement of the costs for a return shipment to the customer.
+   *
+   * @deprecated Use `payment.amountRefunded` instead. To obtain the value, use `payment.amountRefunded?.value`.
    */
   public getAmountRefunded(this: PaymentData): Amount {
     if (this.amountRefunded == undefined) {
@@ -159,6 +177,8 @@ export default class PaymentHelper extends Helper<PaymentData, Payment> {
 
   /**
    * Returns the remaining amount that can be refunded.
+   *
+   * @deprecated Use `payment.amountRemaining` instead. To obtain the value, use `payment.amountRemaining?.value`.
    */
   public getAmountRemaining(this: PaymentData): Amount {
     if (this.amountRemaining == undefined) {

src/data/profiles/ProfileHelper.ts

@@ -9,24 +9,33 @@ import { PaymentData } from '../payments/data';
 import Payment from '../payments/Payment';
 import { RefundData } from '../refunds/data';
 import Refund from '../refunds/Refund';
-import { ProfileData } from './data';
+import { ProfileData, ProfileStatus } from './data';
 import Profile from './Profile';
 
 export default class ProfileHelper extends Helper<ProfileData, Profile> {
   constructor(networkClient: TransformingNetworkClient, protected readonly links: ProfileData['_links']) {
     super(networkClient, links);
   }
 
+  /**
+   * @deprecated Use `profile.status == ProfileStatus.unverified` instead.
+   */
   public isUnverified(this: ProfileData) {
-    return this.status == 'unverified';
+    return this.status == ProfileStatus.unverified;
   }
 
+  /**
+   * @deprecated Use `profile.status == ProfileStatus.verified` instead.
+   */
   public isVerified(this: ProfileData) {
-    return this.status == 'verified';
+    return this.status == ProfileStatus.verified;
   }
 
+  /**
+   * @deprecated Use `profile.status == ProfileStatus.blocked` instead.
+   */
   public isBlocked(this: ProfileData) {
-    return this.status == 'blocked';
+    return this.status == ProfileStatus.blocked;
   }
 
   /**

src/data/profiles/data.ts

@@ -86,7 +86,7 @@ export interface ProfileData extends Model<'profile', string> {
    *
    * @see https://docs.mollie.com/reference/v2/profiles-api/get-profile?path=status#response
    */
-  status: 'unverified' | 'verified' | 'blocked';
+  status: ProfileStatus;
   /**
    * The presence of a review object indicates changes have been made that have not yet been approved by Mollie. Changes to test profiles are approved automatically, unless a switch to a live profile
    * has been requested. The review object will therefore usually be `null` in test mode.
@@ -152,3 +152,9 @@ export interface ProfileLinks extends Links {
    */
   checkoutPreviewUrl: Url;
 }
+
+export enum ProfileStatus {
+  unverified = 'unverified',
+  verified = 'verified',
+  blocked = 'blocked',
+}

src/data/refunds/RefundHelper.ts

@@ -18,34 +18,44 @@ export default class RefundHelper extends Helper<RefundData, Refund> {
 
   /**
    * Returns whether the refund is queued due to a lack of balance. A queued refund can be canceled.
+   *
+   * @deprecated Use `refund.status == RefundStatus.queued` instead.
    */
   public isQueued(this: RefundData): boolean {
     return this.status === RefundStatus.queued;
   }
 
   /**
    * Returns whether the refund is ready to be sent to the bank. You can still cancel the refund if you like.
+   *
+   * @deprecated Use `refund.status == RefundStatus.pending` instead.
    */
   public isPending(this: RefundData): boolean {
     return this.status === RefundStatus.pending;
   }
 
   /**
    * Returns whether the refund is being processed. Cancellation is no longer possible if so.
+   *
+   * @deprecated Use `refund.status == RefundStatus.processing` instead.
    */
   public isProcessing(this: RefundData): boolean {
     return this.status === RefundStatus.processing;
   }
 
   /**
    * Returns whether the refund has been settled to your customer.
+   *
+   * @deprecated Use `refund.status == RefundStatus.refunded` instead.
    */
   public isRefunded(this: RefundData): boolean {
     return this.status === RefundStatus.refunded;
   }
 
   /**
    * Returns whether the refund has failed after processing.
+   *
+   * @deprecated Use `refund.status == RefundStatus.failed` instead.
    */
   public isFailed(this: RefundData): boolean {
     return this.status === RefundStatus.failed;

src/data/subscription/SubscriptionHelper.ts

@@ -24,22 +24,37 @@ export default class SubscriptionHelper extends Helper<SubscriptionData, Subscri
     return this.webhookUrl;
   }
 
+  /**
+   * @deprecated Use `subscription.status == SubscriptionStatus.active` instead.
+   */
   public isActive(this: SubscriptionData): boolean {
     return this.status === SubscriptionStatus.active;
   }
 
+  /**
+   * @deprecated Use `subscription.status == SubscriptionStatus.pending` instead.
+   */
   public isPending(this: SubscriptionData): boolean {
     return this.status === SubscriptionStatus.pending;
   }
 
+  /**
+   * @deprecated Use `subscription.status == SubscriptionStatus.completed` instead.
+   */
   public isCompleted(this: SubscriptionData): boolean {
     return this.status === SubscriptionStatus.completed;
   }
 
+  /**
+   * @deprecated Use `subscription.status == SubscriptionStatus.suspended` instead.
+   */
   public isSuspended(this: SubscriptionData): boolean {
     return this.status === SubscriptionStatus.suspended;
   }
 
+  /**
+   * @deprecated Use `subscription.status == SubscriptionStatus.canceled` instead.
+   */
   public isCanceled(this: SubscriptionData): boolean {
     return SubscriptionStatus.canceled == this.status;
   }

src/errors/ApiError.ts

@@ -5,7 +5,7 @@ import { MollieApiErrorLinks, Url } from '../data/global';
 import Maybe from '../types/Maybe';
 
 export default class ApiError extends Error {
-  public constructor(message: string, protected title?: string, protected status?: number, protected field?: string, protected links?: MollieApiErrorLinks) {
+  public constructor(message: string, protected title?: string, public readonly statusCode?: number, public readonly field?: string, protected links?: MollieApiErrorLinks) {
     super(message);
     // Set the name to ApiError.
     this.name = 'ApiError';
@@ -17,6 +17,7 @@ export default class ApiError extends Error {
    * Get the error message
    *
    * @since 3.0.0
+   * @deprecated Use `error.message` instead.
    */
   public getMessage(): string {
     return this.message;
@@ -26,6 +27,7 @@ export default class ApiError extends Error {
    * Get the field name that contains an error
    *
    * @since 3.0.0
+   * @deprecated Use `error.field` instead.
    */
   public getField(): Maybe<string> {
     return this.field;
@@ -35,9 +37,10 @@ export default class ApiError extends Error {
    * Get the API status code
    *
    * @since 3.0.0
+   * @deprecated Use `error.statusCode` instead.
    */
   public getStatusCode(): Maybe<number> {
-    return this.status;
+    return this.statusCode;
   }
 
   /**
@@ -96,7 +99,7 @@ export default class ApiError extends Error {
     return new ApiError(
       get(response, 'data.detail', 'Received an error without a message'),
       get(response, 'data.title'),
-      get(response, 'data.status'),
+      get(response, 'data.statusCode'),
       get(response, 'data.field'),
       cloneDeep(get(response, 'data._links')),
     );