mollie-api-typescript 1.4.1 → 1.5.0

package/src/models/listsettlementpaymentresponse.ts

@@ -1027,12 +1027,12 @@ export type ListSettlementPaymentResponse = {
    */
   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/mandateresponse.ts

@@ -59,6 +59,24 @@ export type MandateResponseDetails = {
   cardFingerprint?: string | null | undefined;
 };
 
+/**
+ * An array defining the eligible use cases for the mandate. For creditcard mandates, this field will always be
+ *
+ * @remarks
+ * present and can contain one or both of the following values:
+ */
+export const MandateResponseScope = {
+  CustomerPresent: "customer-present",
+  CustomerNotPresent: "customer-not-present",
+} as const;
+/**
+ * An array defining the eligible use cases for the mandate. For creditcard mandates, this field will always be
+ *
+ * @remarks
+ * present and can contain one or both of the following values:
+ */
+export type MandateResponseScope = OpenEnum<typeof MandateResponseScope>;
+
 /**
  * The status of the mandate. A status can be `pending` for mandates when the first payment is not yet finalized, or
  *
@@ -129,6 +147,13 @@ export type MandateResponse = {
    * decline Direct Debit payments if the mandate reference is not unique.
    */
   mandateReference: string | null;
+  /**
+   * An array defining the eligible use cases for the mandate. This field will always be
+   *
+   * @remarks
+   * present and can contain one or both of the following values:
+   */
+  scopes?: Array<MandateResponseScope> | null | undefined;
   status: MandateResponseStatus;
   /**
    * The identifier referring to the [customer](get-customer) this mandate was linked to.
@@ -171,6 +196,13 @@ export function mandateResponseDetailsFromJSON(
   );
 }
 
+/** @internal */
+export const MandateResponseScope$inboundSchema: z.ZodType<
+  MandateResponseScope,
+  z.ZodTypeDef,
+  unknown
+> = openEnums.inboundSchema(MandateResponseScope);
+
 /** @internal */
 export const MandateResponseStatus$inboundSchema: z.ZodType<
   MandateResponseStatus,
@@ -212,6 +244,7 @@ export const MandateResponse$inboundSchema: z.ZodType<
   details: z.lazy(() => MandateResponseDetails$inboundSchema),
   signatureDate: z.nullable(z.string()),
   mandateReference: z.nullable(z.string()),
+  scopes: z.nullable(z.array(MandateResponseScope$inboundSchema)).optional(),
   status: MandateResponseStatus$inboundSchema,
   customerId: z.string(),
   createdAt: z.string(),

package/src/models/mandatescopes.ts

@@ -0,0 +1,30 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 578dd7beb9f7
+ */
+
+import * as z from "zod/v3";
+import { ClosedEnum } from "../types/enums.js";
+
+/**
+ * An array defining the eligible use cases for the mandate. For creditcard mandates, this field will always be
+ *
+ * @remarks
+ * present and can contain one or both of the following values:
+ */
+export const MandateScopes = {
+  CustomerPresent: "customer-present",
+  CustomerNotPresent: "customer-not-present",
+} as const;
+/**
+ * An array defining the eligible use cases for the mandate. For creditcard mandates, this field will always be
+ *
+ * @remarks
+ * present and can contain one or both of the following values:
+ */
+export type MandateScopes = ClosedEnum<typeof MandateScopes>;
+
+/** @internal */
+export const MandateScopes$outboundSchema: z.ZodNativeEnum<
+  typeof MandateScopes
+> = z.nativeEnum(MandateScopes);

package/src/models/operations/listmandates.ts

@@ -46,6 +46,10 @@ export type ListMandatesRequest = {
    * newest to oldest.
    */
   sort?: models.Sorting | undefined;
+  /**
+   * Returns only mandates that include the specified scopes.
+   */
+  scopes?: Array<models.MandateScopes> | undefined;
   /**
    * Most API credentials are specifically created for either live mode or test mode. In those cases the `testmode` query
    *
@@ -100,6 +104,7 @@ export type ListMandatesRequest$Outbound = {
   from?: string | undefined;
   limit?: number | null | undefined;
   sort?: string | undefined;
+  scopes?: Array<string> | undefined;
   testmode?: boolean | undefined;
   "idempotency-key"?: string | undefined;
 };
@@ -114,6 +119,7 @@ export const ListMandatesRequest$outboundSchema: z.ZodType<
   from: z.string().optional(),
   limit: z.nullable(z.number().int()).optional(),
   sort: models.Sorting$outboundSchema.optional(),
+  scopes: z.array(models.MandateScopes$outboundSchema).optional(),
   testmode: z.boolean().optional(),
   idempotencyKey: z.string().optional(),
 }).transform((v) => {

package/src/models/paymentrequest.ts

@@ -445,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;
@@ -468,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.
    *
@@ -740,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;
@@ -791,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

@@ -1044,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/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("");
+}