Skip to content

A local-first personal finance app

8.7 KB
Raw Blame
import createDebug from 'debug';
import { fetch } from 'undici';

import type {
  GoCardlessAccountDetails,
  GoCardlessAccountId,
  GoCardlessAccountMetadata,
  GoCardlessAgreementId,
  GoCardlessInstitutionId,
  GoCardlessRequisitionId,
  Institution,
  Requisition,
} from '#app-gocardless/gocardless-node.types';
import type {
  GetBalances,
  GetTransactionsResponse,
} from '#app-gocardless/gocardless.types';

const debugSensitive = createDebug('actual-sensitive:gocardless');

const BASE_URL = 'https://bankaccountdata.gocardless.com/api/v2';
const ALLOWED_ORIGIN = new URL(BASE_URL).origin;

export type TokenResponse = {
  access: string;
  refresh: string;
  access_expires: number;
  refresh_expires: number;
};

type AgreementResponse = {
  id: GoCardlessAgreementId;
  created: string;
  max_historical_days: number;
  access_valid_for_days: number;
  access_scope: string[];
  accepted: string | null;
  institution_id: GoCardlessInstitutionId;
};

export type AccountDetailsResponse = {
  account: GoCardlessAccountDetails;
};

export class GoCardlessApiError extends Error {
  response: {
    status: number;
    headers: Record<string, string>;
    data?: unknown;
  };

  constructor(
    message: string,
    status: number,
    headers: Record<string, string>,
  ) {
    super(message);
    this.response = { status, headers };
  }
}

function isInvalidTokenResponse(data: unknown): boolean {
  return (
    typeof data === 'object' &&
    data !== null &&
    'summary' in data &&
    data.summary === 'Invalid token'
  );
}

export class GoCardlessApi {
  #secretId: string | null;
  #secretKey: string | null;
  #token: string | null = null;

  constructor({
    secretId,
    secretKey,
  }: {
    secretId: string | null;
    secretKey: string | null;
  }) {
    this.#secretId = secretId;
    this.#secretKey = secretKey;
  }

  get secretId(): string | null {
    return this.#secretId;
  }

  get secretKey(): string | null {
    return this.#secretKey;
  }

  get token(): string | null {
    return this.#token;
  }

  set token(value: string | null) {
    this.#token = value;
  }

  async #request<T>(
    endpoint: string,
    {
      method = 'GET',
      body,
      isRetry = false,
    }: {
      method?: 'GET' | 'POST' | 'DELETE';
      body?: Record<string, unknown>;
      isRetry?: boolean;
    } = {},
  ): Promise<T> {
    const headers: Record<string, string> = {
      accept: 'application/json',
      'Content-Type': 'application/json',
    };

    if (this.#token) {
      headers.Authorization = `Bearer ${this.#token}`;
    }

    const url = new URL(`${BASE_URL}${endpoint}`);
    if (url.origin !== ALLOWED_ORIGIN || !url.pathname.startsWith('/api/v2/')) {
      throw new Error(`Invalid GoCardless API endpoint: ${endpoint}`);
    }

    const response = await fetch(url, {
      method,
      headers,
      signal: AbortSignal.timeout(20000),
      ...(body
        ? {
            body: JSON.stringify(
              Object.fromEntries(
                Object.entries(body).filter(([, v]) => v != null),
              ),
            ),
          }
        : {}),
    });

    if (!response.ok) {
      const error = new GoCardlessApiError(
        `GoCardless API error: ${response.status}`,
        response.status,
        Object.fromEntries(response.headers.entries()),
      );
      try {
        error.response.data = await response.json();
      } catch {}
      console.log(`GoCardless request failed: ${response.status}`);
      debugSensitive(
        `GoCardless ${method} ${endpoint} ${response.status}`,
        error.response.data ? JSON.stringify(error.response.data) : '(no body)',
      );

      if (
        !isRetry &&
        this.#token &&
        response.status === 401 &&
        isInvalidTokenResponse(error.response.data)
      ) {
        this.#token = null;
        await this.generateToken();
        return this.#request<T>(endpoint, { method, body, isRetry: true });
      }

      throw error;
    }

    return response.json() as Promise<T>;
  }

  async generateToken(): Promise<TokenResponse> {
    const data = await this.#request<TokenResponse>('/token/new/', {
      method: 'POST',
      body: {
        secret_id: this.#secretId,
        secret_key: this.#secretKey,
      },
    });
    this.#token = data.access;
    return data;
  }

  async exchangeToken({
    refreshToken,
  }: {
    refreshToken: string;
  }): Promise<TokenResponse> {
    const data = await this.#request<TokenResponse>('/token/refresh/', {
      method: 'POST',
      body: { refresh: refreshToken },
    });
    this.#token = data.access;
    return data;
  }

  async getInstitutions({
    country,
  }: {
    country: string;
  }): Promise<Institution[]> {
    return this.#request<Institution[]>(`/institutions/?country=${country}`);
  }

  async getInstitutionById(id: GoCardlessInstitutionId): Promise<Institution> {
    return this.#request<Institution>(`/institutions/${id}/`);
  }

  async createRequisition({
    redirectUrl,
    institutionId,
    agreement,
    userLanguage,
    reference,
    ssn,
    redirectImmediate,
    accountSelection,
  }: {
    redirectUrl: string;
    institutionId: GoCardlessInstitutionId;
    agreement: GoCardlessAgreementId;
    userLanguage: string;
    reference: string | null;
    ssn: string | null;
    redirectImmediate: boolean;
    accountSelection: boolean;
  }): Promise<Requisition> {
    return this.#request<Requisition>('/requisitions/', {
      method: 'POST',
      body: {
        redirect: redirectUrl,
        institution_id: institutionId,
        agreement,
        user_language: userLanguage,
        reference,
        ssn,
        redirect_immediate: redirectImmediate,
        account_selection: accountSelection,
      },
    });
  }

  async getRequisitionById(
    requisitionId: GoCardlessRequisitionId,
  ): Promise<Requisition> {
    return this.#request<Requisition>(`/requisitions/${requisitionId}/`);
  }

  async deleteRequisition(
    requisitionId: GoCardlessRequisitionId,
  ): Promise<{ summary: string; detail: string }> {
    return this.#request(`/requisitions/${requisitionId}/`, {
      method: 'DELETE',
    });
  }

  async createAgreement({
    institutionId,
    maxHistoricalDays = 90,
    accessValidForDays = 90,
    accessScope = ['balances', 'details', 'transactions'],
  }: {
    institutionId: GoCardlessInstitutionId;
    maxHistoricalDays?: number;
    accessValidForDays?: number;
    accessScope?: string[];
  }): Promise<AgreementResponse> {
    return this.#request<AgreementResponse>('/agreements/enduser/', {
      method: 'POST',
      body: {
        institution_id: institutionId,
        max_historical_days: maxHistoricalDays,
        access_valid_for_days: accessValidForDays,
        access_scope: accessScope,
      },
    });
  }

  async getAccountMetadata(
    accountId: GoCardlessAccountId,
  ): Promise<GoCardlessAccountMetadata> {
    return this.#request<GoCardlessAccountMetadata>(`/accounts/${accountId}/`);
  }

  async getAccountDetails(
    accountId: GoCardlessAccountId,
  ): Promise<AccountDetailsResponse> {
    return this.#request<AccountDetailsResponse>(
      `/accounts/${accountId}/details/`,
    );
  }

  async getAccountBalances(
    accountId: GoCardlessAccountId,
  ): Promise<GetBalances> {
    return this.#request<GetBalances>(`/accounts/${accountId}/balances/`);
  }

  async getAccountTransactions({
    accountId,
    dateFrom,
    dateTo,
  }: {
    accountId: GoCardlessAccountId;
    dateFrom?: string;
    dateTo?: string;
  }): Promise<GetTransactionsResponse> {
    const params = new URLSearchParams();
    if (dateFrom) params.set('date_from', dateFrom);
    if (dateTo) params.set('date_to', dateTo);
    const query = params.toString();
    return this.#request<GetTransactionsResponse>(
      `/accounts/${accountId}/transactions/${query ? `?${query}` : ''}`,
    );
  }

  async initSession({
    redirectUrl,
    institutionId,
    maxHistoricalDays = 90,
    accessValidForDays = 90,
    userLanguage = 'en',
    referenceId = null,
    ssn = null,
    redirectImmediate = false,
    accountSelection = false,
  }: {
    redirectUrl: string;
    institutionId: GoCardlessInstitutionId;
    maxHistoricalDays?: number | string;
    accessValidForDays?: number | string;
    userLanguage?: string;
    referenceId?: string | null;
    ssn?: string | null;
    redirectImmediate?: boolean;
    accountSelection?: boolean;
  }): Promise<Requisition> {
    const agreement = await this.createAgreement({
      institutionId,
      maxHistoricalDays: Number(maxHistoricalDays),
      accessValidForDays: Number(accessValidForDays),
    });

    return this.createRequisition({
      redirectUrl,
      institutionId,
      agreement: agreement.id,
      userLanguage,
      reference: referenceId,
      ssn,
      redirectImmediate,
      accountSelection,
    });
  }
}