mollie-api-typescript 1.4.0 → 1.5.0

package/src/models/operations/updateprofile.ts

@@ -23,6 +23,10 @@ export type UpdateProfileRequestBody = {
   website?: string | null | undefined;
   /**
    * The email address associated with the profile's trade name or brand.
+   *
+   * @remarks
+   *
+   * If the domain contains non-ASCII characters, encode it as Punycode per [RFC 3492](https://www.rfc-editor.org/rfc/rfc3492).
    */
   email?: string | null | undefined;
   /**

package/src/models/paymentaddress.ts

@@ -64,6 +64,8 @@ export type PaymentAddress = {
    * email upon payment creation. The language of the email will follow the locale parameter of the payment.
    *
    * Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
+   *
+   * If the domain contains non-ASCII characters, encode it as Punycode per [RFC 3492](https://www.rfc-editor.org/rfc/rfc3492).
    */
   email?: string | undefined;
   /**

package/src/models/paymentrequest.ts

@@ -176,6 +176,8 @@ export type PaymentRequestBillingAddress = {
    * email upon payment creation. The language of the email will follow the locale parameter of the payment.
    *
    * Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
+   *
+   * If the domain contains non-ASCII characters, encode it as Punycode per [RFC 3492](https://www.rfc-editor.org/rfc/rfc3492).
    */
   email?: string | undefined;
   /**
@@ -443,12 +445,12 @@ export type PaymentRequest = {
   routing?: Array<EntityPaymentRoute> | null | undefined;
   sequenceType?: SequenceType | undefined;
   /**
-   * **Only relevant for recurring payments.**
+   * **Only relevant for recurring payments and stored cards.**
    *
    * @remarks
    *
-   * When creating recurring payments, the ID of a specific [mandate](get-mandate) can be supplied to indicate which of
-   * the customer's accounts should be credited.
+   * When creating recurring or stored cards payments, the ID of a specific [mandate](get-mandate) can be supplied to indicate which of
+   * the customer's accounts should be debited.
    */
   mandateId?: string | null | undefined;
   customerId?: string | undefined;
@@ -466,6 +468,13 @@ export type PaymentRequest = {
    * The date by which the payment should be completed in `YYYY-MM-DD` format
    */
   dueDate?: string | undefined;
+  /**
+   * Whether the card details should be stored for the customer after a successful payment. This will create a mandate for the customer,
+   *
+   * @remarks
+   * allowing for future customer present saved-card CIT payments. Requires customerId, cardToken, and the creditcard method to be specified.
+   */
+  storeCredentials?: boolean | undefined;
   /**
    * Whether to create the entity in test mode or live mode.
    *
@@ -738,6 +747,7 @@ export type PaymentRequest$Outbound = {
   customerId?: string | undefined;
   profileId?: string | undefined;
   dueDate?: string | undefined;
+  storeCredentials?: boolean | undefined;
   testmode?: boolean | null | undefined;
   applePayPaymentToken?: string | undefined;
   company?: Company$Outbound | undefined;
@@ -789,6 +799,7 @@ export const PaymentRequest$outboundSchema: z.ZodType<
   customerId: z.string().optional(),
   profileId: z.string().optional(),
   dueDate: z.string().optional(),
+  storeCredentials: z.boolean().optional(),
   testmode: z.nullable(z.boolean()).optional(),
   applePayPaymentToken: z.string().optional(),
   company: z.lazy(() => Company$outboundSchema).optional(),

package/src/models/paymentresponse.ts

@@ -321,6 +321,8 @@ export type PaymentResponseBillingAddress = {
    * email upon payment creation. The language of the email will follow the locale parameter of the payment.
    *
    * Required for payment methods `billie`, `in3`, `klarna` and `riverty`.
+   *
+   * If the domain contains non-ASCII characters, encode it as Punycode per [RFC 3492](https://www.rfc-editor.org/rfc/rfc3492).
    */
   email?: string | undefined;
   /**
@@ -1042,12 +1044,12 @@ export type PaymentResponse = {
    */
   subscriptionId?: string | null | undefined;
   /**
-   * **Only relevant for recurring payments.**
+   * **Only relevant for recurring payments and stored cards.**
    *
    * @remarks
    *
-   * When creating recurring payments, the ID of a specific [mandate](get-mandate) can be supplied to indicate which of
-   * the customer's accounts should be credited.
+   * When creating recurring or stored cards payments, the ID of a specific [mandate](get-mandate) can be supplied to indicate which of
+   * the customer's accounts should be debited.
    */
   mandateId?: string | null | undefined;
   customerId?: string | undefined;

package/src/models/profilerequest.ts

@@ -22,6 +22,10 @@ export type ProfileRequest = {
   website: string;
   /**
    * The email address associated with the profile's trade name or brand.
+   *
+   * @remarks
+   *
+   * If the domain contains non-ASCII characters, encode it as Punycode per [RFC 3492](https://www.rfc-editor.org/rfc/rfc3492).
    */
   email: string;
   /**

package/src/models/profileresponse.ts

@@ -123,6 +123,10 @@ export type ProfileResponse = {
   website: string;
   /**
    * The email address associated with the profile's trade name or brand.
+   *
+   * @remarks
+   *
+   * If the domain contains non-ASCII characters, encode it as Punycode per [RFC 3492](https://www.rfc-editor.org/rfc/rfc3492).
    */
   email: string;
   /**

package/src/models/salesinvoicerecipient.ts

@@ -59,6 +59,10 @@ export type SalesInvoiceRecipient = {
   vatNumber?: string | null | undefined;
   /**
    * The email address of the recipient.
+   *
+   * @remarks
+   *
+   * If the domain contains non-ASCII characters, encode it as Punycode per [RFC 3492](https://www.rfc-editor.org/rfc/rfc3492).
    */
   email: string;
   /**

package/src/models/salesinvoicerecipientresponse.ts

@@ -62,6 +62,10 @@ export type SalesInvoiceRecipientResponse = {
   vatNumber?: string | null | undefined;
   /**
    * The email address of the recipient.
+   *
+   * @remarks
+   *
+   * If the domain contains non-ASCII characters, encode it as Punycode per [RFC 3492](https://www.rfc-editor.org/rfc/rfc3492).
    */
   email: string;
   /**

package/src/utils/webhooks/index.ts

@@ -0,0 +1,4 @@
+export {
+  InvalidSignatureException,
+  SignatureValidator,
+} from "./signature_validator.js";

package/src/utils/webhooks/signature_validator.ts

@@ -0,0 +1,136 @@
+export class InvalidSignatureException extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidSignatureException";
+
+    Object.setPrototypeOf(this, InvalidSignatureException.prototype);
+  }
+}
+
+export class SignatureValidator {
+  static readonly SIGNATURE_HEADER = "X-Mollie-Signature";
+  private static readonly SIGNATURE_PREFIX = "sha256=";
+
+  private readonly signingSecrets: string[];
+
+  constructor(signingSecrets: string | string[]) {
+    this.signingSecrets = Array.isArray(signingSecrets)
+      ? [...signingSecrets]
+      : [signingSecrets];
+  }
+
+  static async validate(
+    payload: string,
+    signingSecrets: string | string[],
+    signatures?: string | string[] | null,
+  ): Promise<boolean> {
+    return new SignatureValidator(signingSecrets).validatePayload(
+      payload,
+      signatures,
+    );
+  }
+
+  async validatePayload(
+    payload: string,
+    signatures?: string | string[] | null,
+  ): Promise<boolean> {
+    const signatureList = this.normalizeSignatures(signatures);
+
+    if (signatureList.length === 0) {
+      return false;
+    }
+
+    return this.validateSignatures(payload, signatureList);
+  }
+
+  private normalizeSignatures(
+    signatures?: string | string[] | null,
+  ): string[] {
+    if (typeof signatures === "string") {
+      return signatures ? [signatures] : [];
+    }
+
+    if (!signatures) {
+      return [];
+    }
+
+    return signatures.filter((signature): signature is string => !!signature);
+  }
+
+  private async validateSignatures(
+    payload: string,
+    signatures: string[],
+  ): Promise<boolean> {
+    for (const signature of signatures) {
+      const extractedSignature = this.extractSignature(signature);
+
+      if (await this.isValidSignature(extractedSignature, payload)) {
+        return true;
+      }
+    }
+
+    throw new InvalidSignatureException("Invalid webhook signature");
+  }
+
+  private extractSignature(signatureHeader: string): string {
+    if (signatureHeader.startsWith(SignatureValidator.SIGNATURE_PREFIX)) {
+      return signatureHeader.slice(SignatureValidator.SIGNATURE_PREFIX.length);
+    }
+
+    return signatureHeader;
+  }
+
+  private async isValidSignature(
+    providedSignature: string,
+    payload: string,
+  ): Promise<boolean> {
+    for (const secret of this.signingSecrets) {
+      const expectedSignature = await SignatureValidator.createSignature(
+        payload,
+        secret,
+      );
+
+      if (constantTimeEquals(expectedSignature, providedSignature)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  static async createSignature(payload: string, secret: string): Promise<string> {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+      throw new Error("Web Crypto API is not available in this runtime");
+    }
+
+    const encoder = new TextEncoder();
+    const key = await subtle.importKey(
+      "raw",
+      encoder.encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"],
+    );
+    const signature = await subtle.sign("HMAC", key, encoder.encode(payload));
+
+    return toHex(signature);
+  }
+}
+
+function constantTimeEquals(left: string, right: string): boolean {
+  const maxLength = Math.max(left.length, right.length);
+  let mismatch = left.length ^ right.length;
+
+  for (let index = 0; index < maxLength; index++) {
+    mismatch |= (left.charCodeAt(index) || 0) ^ (right.charCodeAt(index) || 0);
+  }
+
+  return mismatch === 0;
+}
+
+function toHex(buffer: ArrayBuffer): string {
+  return Array.from(new Uint8Array(buffer))
+    .map((value) => value.toString(16).padStart(2, "0"))
+    .join("");
+}