routex-client 0.4.2 → 0.4.3

package/README.md

@@ -4,6 +4,12 @@ A client for [YAXI](https://yaxi.tech/)'s Open Banking services.
 
 ## Changelog
 
+### [0.4.3] - 2025-11-06
+
+#### Fixed
+
+- `yaxi-ticket-id` header value in requests
+
 ### [0.4.2] - 2025-09-23
 
 #### Fixed

package/client.d.ts

@@ -0,0 +1,703 @@
+export declare enum AccountField {
+    Iban = "IBAN",
+    Number = "NUMBER",
+    Bic = "BIC",
+    BankCode = "BANKCODE",
+    Currency = "CURRENCY",
+    Name = "NAME",
+    DisplayName = "DISPLAYNAME",
+    OwnerName = "OWNERNAME",
+    ProductName = "PRODUCTNAME",
+    Status = "STATUS",
+    Type = "TYPE"
+}
+export declare enum AccountStatus {
+    Available = "AVAILABLE",
+    Terminated = "TERMINATED",
+    Blocked = "BLOCKED"
+}
+export declare enum AccountType {
+    /**
+     * Account used to post debits and credits.
+     * ISO 20022 ExternalCashAccountType1Code CACC.
+     */
+    Current = "CURRENT",
+    /**
+     * Account used for credit card payments.
+     * ISO 20022 ExternalCashAccountType1Code CARD.
+     */
+    Card = "CARD",
+    /**
+     * Account used for savings.
+     * ISO 20022 ExternalCashAccountType1Code SVGS.
+     */
+    Savings = "SAVINGS",
+    /**
+     * Account used for call money.
+     * No dedicated ISO 20022 code (falls into SVGS).
+     */
+    CallMoney = "CALL_MONEY",
+    /**
+     * Account used for time deposits.
+     * No dedicated ISO 20022 code (falls into SVGS).
+     */
+    TimeDeposit = "TIME_DEPOSIT",
+    /**
+     * Account used for loans.
+     * ISO 20022 ExternalCashAccountType1Code LOAN.
+     */
+    Loan = "LOAN",
+    Securities = "SECURITIES",
+    Insurance = "INSURANCE",
+    Commerce = "COMMERCE",
+    Rewards = "REWARDS"
+}
+/**
+ * Requirements for user identifier and password.
+ */
+export interface CredentialsModel {
+    /**
+     * A full set of credentials may be provided to support fully embedded authentication (including scraped redirects).
+     */
+    full: boolean;
+    /**
+     * Only a user identifier without a password may be provided.
+     * This is typically the case for decoupled authentication where the user e.g. authorizes access in a mobile application.
+     * Note that if password-less authentication fails (e.g. as no device for decoupled authentication is set up for the user and
+     * a redirect is not supported), an error is returned and the transaction has to get restarted with a full set of credentials.
+     */
+    userId: boolean;
+    /**
+     * Credentials are not required. The user will provide them to the service provider during a redirect.
+     */
+    none: boolean;
+}
+/**
+ * Connection meta data
+ */
+export interface ConnectionInfo {
+    /**
+     * Unique identifier.
+     */
+    id: string;
+    /**
+     * ISO 3166-1 ALPHA-2 country codes.
+     */
+    countries: string[];
+    /**
+     * Display name.
+     */
+    displayName: string;
+    /**
+     * Credentials model.
+     */
+    credentials: CredentialsModel;
+    /**
+     * Human-friendly label for the user identifier if relevant.
+     */
+    userId?: string;
+    /**
+     * Advice for the credentials to be displayed.
+     */
+    advice?: string;
+    /**
+     * Logo identifier.
+     */
+    logoId?: string;
+}
+export interface ConfirmationOptions {
+    ticket: string;
+    context: Uint8Array;
+}
+export interface ResponseOptions {
+    ticket: string;
+    context: Uint8Array;
+    response: string;
+}
+interface ServiceOptions {
+    credentials: Credentials;
+    session?: Uint8Array;
+    recurringConsents?: boolean;
+    ticket: string;
+}
+export interface AccountsOptions extends ServiceOptions {
+    fields: AccountField[];
+    filter?: AccountFilter;
+}
+export interface BalancesOptions extends ServiceOptions {
+    accounts: AccountReference[];
+}
+export type TransactionsOptions = ServiceOptions;
+export interface CollectPaymentOptions extends ServiceOptions {
+    account?: AccountReference;
+}
+interface AccountReference {
+    iban: string;
+    currency?: string;
+}
+export interface Credentials {
+    connectionId: string;
+    userId?: string;
+    password?: string;
+    connectionData?: Uint8Array;
+}
+/**
+ * Filters for the connection lookup
+ *
+ * String filters look for the given value anywhere in the related field, case-insensitive.
+ */
+export type SearchFilter = 
+/**
+ * List of ISO 3166-1 alpha-2 country codes to consider.
+ */
+{
+    countries: string[];
+}
+/**
+ * String filter for the provider / product name or any alias.
+ */
+ | {
+    name: string;
+}
+/**
+ * String filter for the BIC.
+ */
+ | {
+    bic: string;
+}
+/**
+ * String filter for the (national) bank code.
+ */
+ | {
+    bankCode: string;
+}
+/**
+ * String filter for any of those fields.
+ */
+ | {
+    term: string;
+};
+/**
+ * Response from YAXI Open Banking services.
+ *
+ * The response either carries an authenticated Result
+ * or an interrupt (i.e. a dialog or redirect for the user).
+ */
+export declare class OBResponse {
+    private _json;
+    static fromJSON(json: ResultJSON | DialogJSON | RedirectJSON | RedirectHandleJSON): OBResponse;
+    protected constructor(json: ResultJSON | DialogJSON | RedirectJSON | RedirectHandleJSON);
+    toJSON(): ResultJSON | DialogJSON | RedirectJSON | RedirectHandleJSON;
+}
+type ResultJSON = {
+    Result: [string, string?, string?];
+};
+/**
+ * Data returned by YAXI Open Banking services, authenticated with an HMAC
+ *
+ * jwt can be used for transfer to a remote system as JSON Web Token {@link https://jwt.io/}.
+ * The remote system can verify and read the data from the "data" claim.
+ * To read the data locally, the frontend can decode the JWT without verification.
+ *
+ * Besides the value itself, it contains a timestamp and a ticket identifier
+ * (bound to known input parameters and service type).
+ */
+export declare class Result extends OBResponse {
+    readonly jwt: string;
+    readonly session?: Uint8Array;
+    readonly connectionData?: Uint8Array;
+    static fromJSON(json: ResultJSON): Result;
+    private constructor();
+}
+/**
+ * Context of a user dialog.
+ */
+export declare enum DialogContext {
+    /**
+     * SCA or TAN process.
+     *
+     * There are multiple cases, distinguishable by the input:
+     * - {@link Confirmation}: Decoupled process (e.g. confirmation in a SCA app).
+     * - {@link Selection}: TAN method selection.
+     * - {@link Field}: TAN entry.
+     */
+    Sca = "SCA",
+    /**
+     * Account selection.
+     *
+     * A {@link Selection} gets returned with this context when an account has to be selected.
+     * Note that there might be just a single option that may be chosen automatically without user interaction.
+     */
+    Accounts = "ACCOUNTS",
+    /**
+     * Pending redirect confirmation.
+     *
+     * A {@link Confirmation} gets returned with this context when a redirect got confirmed but no result is known yet.
+     */
+    Redirect = "REDIRECT",
+    /**
+     * Pending SCT Inst payment.
+     *
+     * A {@link Confirmation} gets returned with this context when an SCT Inst payment has been initialized and not reached the final status yet.
+     */
+    PaymentStatus = "PAYMENT_STATUS",
+    /**
+     * Verification of Payee confirmation.
+     *
+     * A {@link Confirmation} gets returned with this context when an explicit confirmation of the creditor is required due to a name mismatch.
+     * Note that this confirmation has legal implications, releasing the bank from liabilities in case of the transfer to an unintended receiver due to incorrect creditor data.
+     */
+    VopConfirmation = "VOP_CONFIRMATION",
+    /**
+     * Pending Verification of Payee check.
+     * A {@link Confirmation} gets returned with this context when a Verification of Payee check for a bulk payment is still pending.
+     */
+    VopCheck = "VOP_CHECK"
+}
+/**
+ * Image data for a dialog.
+ */
+export interface Image {
+    mimeType: string;
+    /**
+     * Binary data in the format defined by mimeType.
+     */
+    data: Uint8Array;
+    /**
+     * HHD_UC data block
+     *
+     * In cases where the ASPSP provides HHD_UC data for optical coupling with a HandHeld-Device
+     * for the generation of an OTP, especially for an HHD_OPT animated graphic, the raw HHD_UC
+     * data stream is provided here.
+     *
+     * The publicly available document "HandHeld-Device (HHD) for the generation of an OTP HHD
+     * enhancement for optical interfaces" describes how to implement the animated graphic for
+     * HHD_OPT in section C. data provides a pre-rendered animated GIF
+     * to be presented with a width of 62.5 mm.
+     */
+    hhdUcData?: Uint8Array;
+}
+/**
+ * Just a primary action to confirm the dialog.
+ */
+export declare class Confirmation {
+    /**
+     * Context object that can be used to confirm the dialog.
+     */
+    context: Uint8Array;
+    /**
+     * If polling is acceptable, a delay in seconds is specified for which the client has to wait before automatically confirming.
+     */
+    pollingDelaySecs?: number;
+}
+/**
+ * A selection of options the user can choose from.
+ */
+export declare class Selection {
+    /**
+     * Options are meant to be rendered e.g. as radio buttons where the user must select exactly
+     * one to for a confirmation button to get enabled. Another example for an implementation is
+     * one button per option that immediately confirms the selection.
+     */
+    options: Array<{
+        key: string;
+        label: string;
+        explanation?: string;
+    }>;
+    /**
+     * Context object that can be used to respond to the dialog.
+     */
+    context: Uint8Array;
+}
+/**
+ * An input field.
+ */
+export declare class Field {
+    /**
+     * Type that may be used for showing hints or dedicated keyboard layouts and for applying input restrictions or validation.
+     */
+    type: InputType;
+    /**
+     * Indicates if the input should be masked.
+     */
+    secrecyLevel: SecrecyLevel;
+    /**
+     * Minimal length to allow.
+     */
+    minLength?: number;
+    /**
+     * Maximum length to allow.
+     */
+    maxLength?: number;
+    /**
+     * Context object that can be used to respond to the dialog.
+     */
+    context: Uint8Array;
+}
+/**
+ * Type of an input field.
+ */
+export declare enum InputType {
+    Date = "DATE",
+    Email = "EMAIL",
+    Number = "NUMBER",
+    Phone = "PHONE",
+    Text = "TEXT"
+}
+/**
+ * Level of secrecy for an input field.
+ */
+export declare enum SecrecyLevel {
+    /**
+     * The data is not a secret.
+     */
+    Plain = "PLAIN",
+    /**
+     * The data is a one-time password. This can usually be treated as
+     * no secret but the implementer might still choose to mask the input.
+     */
+    Otp = "OTP",
+    /**
+     * The data is a secret password. Input must be masked.
+     */
+    Password = "PASSWORD"
+}
+type DialogJSON = {
+    Dialog: {
+        context?: string;
+        message?: string;
+        image: {
+            mimeType: string;
+            data: string;
+            hhdUcData?: string;
+        };
+        input: {
+            Confirmation: {
+                context: string;
+                pollingDelaySecs?: number;
+            };
+        } | {
+            Selection: {
+                options: [{
+                    key: string;
+                    label: string;
+                    explanation?: string;
+                }];
+                context: string;
+            };
+        } | {
+            Field: {
+                type: string;
+                secrecyLevel: string;
+                minLength?: number;
+                maxLength?: number;
+                context: string;
+            };
+        };
+    };
+};
+/**
+ * User dialog.
+ *
+ * This is meant to be displayed as a dialog in some User Interface and consists of:
+ *
+ * - A way to cancel the dialog (typically an X symbol and / or a "Cancel" button).
+ * - The display part:
+ *   - The message.
+ *   - An optional image.
+ * - The interactive part defined by the input.
+ *
+ * The input contains a context for continuing the
+ * process at the service that issued the dialog object.
+ */
+export declare class Dialog extends OBResponse {
+    readonly context?: DialogContext;
+    readonly message?: string;
+    readonly image?: Image;
+    /**
+     * Data defining the interactive part of a user dialog.
+     */
+    readonly input: Confirmation | Selection | Field;
+    static fromJSON(json: DialogJSON): Dialog;
+    private constructor();
+}
+type RedirectJSON = {
+    Redirect: {
+        url: string;
+        context: string;
+    };
+};
+/**
+ * User redirect.
+ *
+ * The user is meant to get sent to the url and the context can
+ * be used for continuing the process at the service that issued the redirect object afterward.
+ *
+ * A web application needs to direct the user agent to the returned URL.
+ * A desktop or mobile application could either open it in a browser or inside an element like a WebView.
+ */
+export declare class Redirect extends OBResponse {
+    readonly url: URL;
+    readonly context: Uint8Array;
+    static fromJSON(json: RedirectJSON): Redirect;
+    private constructor();
+}
+type RedirectHandleJSON = {
+    RedirectHandle: {
+        handle: string;
+        context: string;
+    };
+};
+/**
+ * Incomplete user redirect.
+ *
+ * A final redirect URI needs to get registered, using the handle, to receive the URL to send the user to.
+ */
+export declare class RedirectHandle extends OBResponse {
+    readonly handle: string;
+    readonly context: Uint8Array;
+    static fromJSON(json: RedirectHandleJSON): RedirectHandle;
+    private constructor();
+}
+export type AccountFilter = {
+    eq: [AccountField, string | null];
+} | {
+    notEq: [AccountField, string | null];
+} | {
+    all: AccountFilter[];
+} | {
+    any: AccountFilter[];
+} | {
+    supports: SupportedService;
+};
+export declare enum SupportedService {
+    CollectPayment = "COLLECT_PAYMENT"
+}
+export type RoutexClientOptions = URL | {
+    url?: URL;
+    retryPolicyFactory?: () => RetryPolicy;
+};
+export declare class RoutexClient {
+    private _url;
+    private _settlement;
+    private _traceId?;
+    private _redirectUri?;
+    private _retryPolicyFactory;
+    constructor(options?: RoutexClientOptions);
+    private _unsealBody;
+    private _request;
+    /**
+     * Search for service connections (banks and other providers)
+     *
+     * The result is a list of connections that match all the {@link SearchFilter}s.
+     * If IBAN detection is enabled and the first value of a term filter is detected
+     * to be a possible prefix of an IBAN that contains a national bank code,
+     * the result might contain additional connections that match that bank code.
+     */
+    search({ ticket, filters, ibanDetection, limit, }: {
+        ticket: string;
+        filters?: SearchFilter[];
+        ibanDetection: boolean;
+        limit?: number;
+    }): Promise<ConnectionInfo[]>;
+    /**
+     * Get information for a service connection
+     */
+    info(ticket: string, connectionId: string): Promise<ConnectionInfo>;
+    /**
+     * Trace identifier returned with the last request
+     */
+    traceId(): Uint8Array | undefined;
+    /**
+     * Retrieve trace data
+     */
+    trace(ticket: string, traceId: Uint8Array): Promise<string>;
+    /**
+     * Set a redirect URI for subsequent service requests.
+     *
+     * Redirects will eventually forward to that URI.
+     * It can be used to redirect back to a web application or to jump
+     * back into the context of a desktop or mobile application.
+     * If no redirect URI is set, {@link RedirectHandle}s will get returned instead of {@link Redirect}s.
+     */
+    setRedirectUri(redirectUri: string): void;
+    /**
+     * Register a redirect URI for a given redirect handle.
+     *
+     * Returns the URL that the user is meant to get sent to.
+     */
+    registerRedirectUri({ ticket, handle, redirectUri, }: {
+        ticket: string;
+        handle: string;
+        redirectUri: string;
+    }): Promise<URL>;
+    private _respond;
+    private _confirm;
+    /**
+     * Fetch a list of accounts
+     */
+    accounts({ credentials, session, recurringConsents, ticket, fields, filter, }: AccountsOptions): Promise<OBResponse>;
+    /**
+     * Respond to {@link Dialog} returned while fetching accounts
+     */
+    respondAccounts(options: ResponseOptions): Promise<OBResponse>;
+    /**
+     * Confirm {@link Dialog} or {@link Redirect} returned while fetching accounts
+     */
+    confirmAccounts(options: ConfirmationOptions): Promise<OBResponse>;
+    /**
+     * Fetch a list of balances
+     */
+    balances({ credentials, session, recurringConsents, ticket, accounts, }: BalancesOptions): Promise<OBResponse>;
+    /**
+     * Respond to {@link Dialog} returned while fetching balances
+     */
+    respondBalances(options: ResponseOptions): Promise<OBResponse>;
+    /**
+     * Confirm {@link Dialog} or {@link Redirect} returned while fetching balances
+     */
+    confirmBalances(options: ConfirmationOptions): Promise<OBResponse>;
+    /**
+     * Fetch a list of transactions
+     */
+    transactions({ credentials, session, recurringConsents, ticket, }: TransactionsOptions): Promise<OBResponse>;
+    /**
+     * Respond to {@link Dialog} returned while fetching transactions
+     */
+    respondTransactions(options: ResponseOptions): Promise<OBResponse>;
+    /**
+     * Confirm {@link Dialog} or {@link Redirect} returned while fetching transactions
+     */
+    confirmTransactions(options: ConfirmationOptions): Promise<OBResponse>;
+    /**
+     * Collect a predefined payment
+     */
+    collectPayment({ credentials, session, recurringConsents, ticket, account, }: CollectPaymentOptions): Promise<OBResponse>;
+    /**
+     * Respond to {@link Dialog} returned while initiating the payment
+     */
+    respondCollectPayment(options: ResponseOptions): Promise<OBResponse>;
+    /**
+     * Confirm {@link Dialog} or {@link Redirect} returned initiating the payment
+     */
+    confirmCollectPayment(options: ConfirmationOptions): Promise<OBResponse>;
+}
+export declare class RequestException extends Error {
+    constructor(error: string, options?: ErrorOptions);
+}
+export declare class UnexpectedErrorException extends Error {
+    constructor(userMessage?: string, options?: ErrorOptions);
+    userMessage?: string;
+}
+export declare class CanceledException extends Error {
+    constructor(options?: ErrorOptions);
+}
+export declare class InvalidCredentialsException extends Error {
+    constructor(userMessage?: string, options?: ErrorOptions);
+    userMessage?: string;
+}
+export declare class ServiceBlockedException extends Error {
+    constructor(code?: string, userMessage?: string, options?: ErrorOptions);
+    code?: ServiceBlockedCode;
+    userMessage?: string;
+}
+export declare enum ServiceBlockedCode {
+    /**
+     * Something is not set up for the user, e.g., there are no TAN methods.
+     */
+    MissingSetup = "MISSING_SETUP",
+    /**
+     * User attention is required via another channel. Typically the user needs to log into the Online Banking.
+     */
+    ActionRequired = "ACTION_REQUIRED"
+}
+export declare class UnauthorizedException extends Error {
+    constructor(userMessage?: string, options?: ErrorOptions);
+    userMessage?: string;
+}
+export declare class ConsentExpiredException extends Error {
+    constructor(userMessage?: string, options?: ErrorOptions);
+    userMessage?: string;
+}
+export declare class AccessExceededException extends Error {
+    constructor(userMessage?: string, options?: ErrorOptions);
+    userMessage?: string;
+}
+export declare class PeriodOutOfBoundsException extends Error {
+    constructor(userMessage?: string, options?: ErrorOptions);
+    userMessage?: string;
+}
+export declare class UnsupportedProductException extends Error {
+    constructor(reason?: string, userMessage?: string, options?: ErrorOptions);
+    reason?: UnsupportedProductReason;
+    userMessage?: string;
+}
+export declare enum UnsupportedProductReason {
+    /**
+     * The amount is not allowed for the payment product.
+     */
+    Limit = "LIMIT",
+    /**
+     * The recipient is not capable to receive the payment product.
+     */
+    Recipient = "RECIPIENT"
+}
+export declare class PaymentFailedException extends Error {
+    constructor(code?: string, userMessage?: string, options?: ErrorOptions);
+    code?: PaymentFailedCode;
+    userMessage?: string;
+}
+export declare enum PaymentFailedCode {
+    LimitExceeded = "LIMIT_EXCEEDED",
+    InsufficientFunds = "INSUFFICIENT_FUNDS"
+}
+export declare class UnexpectedValueException extends Error {
+    constructor(error: string, options?: ErrorOptions);
+}
+export declare class TicketException extends Error {
+    constructor(error: string, code: string, options?: ErrorOptions);
+    code: TicketExceptionCode;
+}
+export declare enum TicketExceptionCode {
+    Missing = "MISSING",
+    Invalid = "INVALID",
+    MissingKey = "MISSING_KEY",
+    UnknownKey = "UNKNOWN_KEY",
+    Mismatch = "MISMATCH",
+    Expired = "EXPIRED",
+    InvalidLifetime = "INVALID_LIFETIME",
+    ExpiredKey = "EXPIRED_KEY",
+    KeyEnvironmentMismatch = "KEY_ENVIRONMENT_MISMATCH"
+}
+export declare class ProviderErrorException extends Error {
+    constructor(code?: string, userMessage?: string, options?: ErrorOptions);
+    code?: ProviderErrorCode;
+    userMessage?: string;
+}
+export declare enum ProviderErrorCode {
+    Maintenance = "MAINTENANCE"
+}
+export declare class ResponseException extends Error {
+    constructor(text: string, response: Response, options?: ErrorOptions);
+    response: Response;
+}
+export declare class NotFoundException extends Error {
+    constructor(options?: ErrorOptions);
+}
+/**
+ * A policy to determine whether a failed operation should be retried. Gets
+ * passed the error which caused the operation to fail and should return a
+ * `Promise` that resolves to `true` if the request should be retried.
+ * Implementations can wait for some time before resolving the `Promise` to add
+ * a wait time between retries.
+ */
+export type RetryPolicy = (error: unknown) => Promise<boolean>;
+/**
+ * A `RetryPolicy` that allows `maxTimes` retries if a `RequestException`
+ * occurred. Doesn't wait any time, but instantly returns.
+ */
+export declare function retryRequestExceptionNTimesPolicy(maxTimes: number): RetryPolicy;
+export declare const _testing: {
+    [Key: string]: unknown;
+};
+export {};