@xenterprises/fastify-xplaid 1.0.0

package/src/xPlaid.js

@@ -0,0 +1,764 @@
+/**
+ * xPlaid - Plaid Financial Data Integration
+ *
+ * A Fastify plugin for integrating with Plaid's banking API.
+ * Provides Link token management, account access, transactions, balances, and identity verification.
+ *
+ * @see https://plaid.com/docs/
+ */
+
+import fp from "fastify-plugin";
+import { Configuration, PlaidApi, PlaidEnvironments, Products, CountryCode } from "plaid";
+
+/**
+ * Plaid environments
+ */
+const ENVIRONMENTS = {
+  SANDBOX: "sandbox",
+  DEVELOPMENT: "development",
+  PRODUCTION: "production",
+};
+
+/**
+ * Plaid products
+ */
+const PRODUCTS = {
+  AUTH: "auth",
+  TRANSACTIONS: "transactions",
+  IDENTITY: "identity",
+  ASSETS: "assets",
+  INVESTMENTS: "investments",
+  LIABILITIES: "liabilities",
+  BALANCE: "balance",
+  INCOME: "income",
+  TRANSFER: "transfer",
+  SIGNAL: "signal",
+  STATEMENTS: "statements",
+};
+
+/**
+ * Country codes
+ */
+const COUNTRY_CODES = {
+  US: "US",
+  CA: "CA",
+  GB: "GB",
+  ES: "ES",
+  FR: "FR",
+  IE: "IE",
+  NL: "NL",
+  DE: "DE",
+};
+
+/**
+ * xPlaid Plugin
+ *
+ * @param {import('fastify').FastifyInstance} fastify - Fastify instance
+ * @param {Object} options - Plugin options
+ * @param {string} options.clientId - Plaid client ID (required)
+ * @param {string} options.secret - Plaid secret (required)
+ * @param {string} [options.environment] - Plaid environment (sandbox, development, production)
+ * @param {string} [options.version] - Plaid API version (default: 2020-09-14)
+ * @param {boolean} [options.active] - Enable/disable the plugin (default: true)
+ */
+async function xPlaid(fastify, options) {
+  // Check if plugin is disabled
+  if (options.active === false) {
+    fastify.log.info("#   ⏸️  xPlaid Disabled");
+    return;
+  }
+
+  // Validate required configuration
+  if (!options.clientId) {
+    throw new Error("xPlaid: clientId is required");
+  }
+  if (!options.secret) {
+    throw new Error("xPlaid: secret is required");
+  }
+
+  const version = options.version || "2020-09-14";
+
+  // Determine Plaid environment and base path
+  let environment;
+  let basePath;
+  switch (options.environment) {
+    case ENVIRONMENTS.PRODUCTION:
+      environment = ENVIRONMENTS.PRODUCTION;
+      basePath = PlaidEnvironments.production;
+      break;
+    case ENVIRONMENTS.DEVELOPMENT:
+      environment = ENVIRONMENTS.DEVELOPMENT;
+      basePath = PlaidEnvironments.development;
+      break;
+    default:
+      environment = ENVIRONMENTS.SANDBOX;
+      basePath = PlaidEnvironments.sandbox;
+  }
+
+  // Configure Plaid client
+  const configuration = new Configuration({
+    basePath,
+    baseOptions: {
+      headers: {
+        "PLAID-CLIENT-ID": options.clientId,
+        "PLAID-SECRET": options.secret,
+        "Plaid-Version": version,
+      },
+    },
+  });
+
+  const plaidClient = new PlaidApi(configuration);
+
+  // ============================================================================
+  // Link Token Service
+  // ============================================================================
+
+  /**
+   * Create a Link token for initializing Plaid Link
+   * @param {Object} params - Link token parameters
+   * @param {string} params.userId - Unique client user ID
+   * @param {string} [params.clientName] - Application name (max 30 chars)
+   * @param {string[]} [params.products] - Products to enable
+   * @param {string[]} [params.countryCodes] - Country codes
+   * @param {string} [params.language] - Display language
+   * @param {string} [params.webhook] - Webhook URL
+   * @param {string} [params.redirectUri] - OAuth redirect URI
+   * @param {string} [params.accessToken] - For update mode
+   * @returns {Promise<Object>} Link token response
+   */
+  async function createLinkToken(params) {
+    const {
+      userId,
+      clientName = "App",
+      products = [Products.Transactions],
+      countryCodes = [CountryCode.Us],
+      language = "en",
+      webhook,
+      redirectUri,
+      accessToken,
+    } = params;
+
+    const request = {
+      user: {
+        client_user_id: userId,
+      },
+      client_name: clientName.slice(0, 30),
+      products: accessToken ? undefined : products,
+      country_codes: countryCodes,
+      language,
+    };
+
+    if (webhook) request.webhook = webhook;
+    if (redirectUri) request.redirect_uri = redirectUri;
+    if (accessToken) request.access_token = accessToken;
+
+    try {
+      const response = await plaidClient.linkTokenCreate(request);
+      return {
+        linkToken: response.data.link_token,
+        expiration: response.data.expiration,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid linkTokenCreate failed");
+      throw new Error(error.response?.data?.error_message || "Failed to create link token");
+    }
+  }
+
+  /**
+   * Get information about a Link token
+   * @param {string} linkToken - Link token
+   * @returns {Promise<Object>} Link token info
+   */
+  async function getLinkToken(linkToken) {
+    try {
+      const response = await plaidClient.linkTokenGet({ link_token: linkToken });
+      return response.data;
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid linkTokenGet failed");
+      throw new Error(error.response?.data?.error_message || "Failed to get link token");
+    }
+  }
+
+  /**
+   * Exchange a public token for an access token
+   * @param {string} publicToken - Public token from Link
+   * @returns {Promise<Object>} Access token and item ID
+   */
+  async function exchangePublicToken(publicToken) {
+    try {
+      const response = await plaidClient.itemPublicTokenExchange({
+        public_token: publicToken,
+      });
+      return {
+        accessToken: response.data.access_token,
+        itemId: response.data.item_id,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid exchangePublicToken failed");
+      throw new Error(error.response?.data?.error_message || "Failed to exchange public token");
+    }
+  }
+
+  // ============================================================================
+  // Accounts Service
+  // ============================================================================
+
+  /**
+   * Get accounts for an Item
+   * @param {string} accessToken - Access token
+   * @param {Object} [options] - Options
+   * @param {string[]} [options.accountIds] - Filter by account IDs
+   * @returns {Promise<Object>} Accounts response
+   */
+  async function getAccounts(accessToken, options = {}) {
+    const request = { access_token: accessToken };
+
+    if (options.accountIds) {
+      request.options = { account_ids: options.accountIds };
+    }
+
+    try {
+      const response = await plaidClient.accountsGet(request);
+      return {
+        accounts: response.data.accounts,
+        item: response.data.item,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid accountsGet failed");
+      throw new Error(error.response?.data?.error_message || "Failed to get accounts");
+    }
+  }
+
+  /**
+   * Get real-time balance for accounts
+   * @param {string} accessToken - Access token
+   * @param {Object} [options] - Options
+   * @param {string[]} [options.accountIds] - Filter by account IDs
+   * @returns {Promise<Object>} Balance response
+   */
+  async function getBalance(accessToken, options = {}) {
+    const request = { access_token: accessToken };
+
+    if (options.accountIds) {
+      request.options = { account_ids: options.accountIds };
+    }
+
+    try {
+      const response = await plaidClient.accountsBalanceGet(request);
+      return {
+        accounts: response.data.accounts,
+        item: response.data.item,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid accountsBalanceGet failed");
+      throw new Error(error.response?.data?.error_message || "Failed to get balance");
+    }
+  }
+
+  // ============================================================================
+  // Transactions Service
+  // ============================================================================
+
+  /**
+   * Sync transactions (recommended approach)
+   * @param {string} accessToken - Access token
+   * @param {Object} [options] - Options
+   * @param {string} [options.cursor] - Cursor for pagination
+   * @param {number} [options.count] - Number of transactions (max 500)
+   * @param {string[]} [options.accountIds] - Filter by account IDs
+   * @returns {Promise<Object>} Transaction sync response
+   */
+  async function syncTransactions(accessToken, options = {}) {
+    const request = { access_token: accessToken };
+
+    if (options.cursor) request.cursor = options.cursor;
+    if (options.count) request.count = Math.min(options.count, 500);
+    if (options.accountIds) {
+      request.options = { account_ids: options.accountIds };
+    }
+
+    try {
+      const response = await plaidClient.transactionsSync(request);
+      return {
+        added: response.data.added,
+        modified: response.data.modified,
+        removed: response.data.removed,
+        nextCursor: response.data.next_cursor,
+        hasMore: response.data.has_more,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid transactionsSync failed");
+      throw new Error(error.response?.data?.error_message || "Failed to sync transactions");
+    }
+  }
+
+  /**
+   * Get transactions within a date range (legacy approach)
+   * @param {string} accessToken - Access token
+   * @param {string} startDate - Start date (YYYY-MM-DD)
+   * @param {string} endDate - End date (YYYY-MM-DD)
+   * @param {Object} [options] - Options
+   * @param {number} [options.count] - Number of transactions (max 500)
+   * @param {number} [options.offset] - Pagination offset
+   * @param {string[]} [options.accountIds] - Filter by account IDs
+   * @returns {Promise<Object>} Transactions response
+   */
+  async function getTransactions(accessToken, startDate, endDate, options = {}) {
+    const request = {
+      access_token: accessToken,
+      start_date: startDate,
+      end_date: endDate,
+    };
+
+    const requestOptions = {};
+    if (options.count) requestOptions.count = Math.min(options.count, 500);
+    if (options.offset) requestOptions.offset = options.offset;
+    if (options.accountIds) requestOptions.account_ids = options.accountIds;
+
+    if (Object.keys(requestOptions).length > 0) {
+      request.options = requestOptions;
+    }
+
+    try {
+      const response = await plaidClient.transactionsGet(request);
+      return {
+        accounts: response.data.accounts,
+        transactions: response.data.transactions,
+        totalTransactions: response.data.total_transactions,
+        item: response.data.item,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid transactionsGet failed");
+      throw new Error(error.response?.data?.error_message || "Failed to get transactions");
+    }
+  }
+
+  /**
+   * Refresh transactions
+   * @param {string} accessToken - Access token
+   * @returns {Promise<Object>} Refresh response
+   */
+  async function refreshTransactions(accessToken) {
+    try {
+      const response = await plaidClient.transactionsRefresh({
+        access_token: accessToken,
+      });
+      return {
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid transactionsRefresh failed");
+      throw new Error(error.response?.data?.error_message || "Failed to refresh transactions");
+    }
+  }
+
+  // ============================================================================
+  // Identity Service
+  // ============================================================================
+
+  /**
+   * Get identity information for accounts
+   * @param {string} accessToken - Access token
+   * @param {Object} [options] - Options
+   * @param {string[]} [options.accountIds] - Filter by account IDs
+   * @returns {Promise<Object>} Identity response
+   */
+  async function getIdentity(accessToken, options = {}) {
+    const request = { access_token: accessToken };
+
+    if (options.accountIds) {
+      request.options = { account_ids: options.accountIds };
+    }
+
+    try {
+      const response = await plaidClient.identityGet(request);
+      return {
+        accounts: response.data.accounts,
+        item: response.data.item,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid identityGet failed");
+      throw new Error(error.response?.data?.error_message || "Failed to get identity");
+    }
+  }
+
+  // ============================================================================
+  // Auth Service
+  // ============================================================================
+
+  /**
+   * Get account and routing numbers for ACH
+   * @param {string} accessToken - Access token
+   * @param {Object} [options] - Options
+   * @param {string[]} [options.accountIds] - Filter by account IDs
+   * @returns {Promise<Object>} Auth response
+   */
+  async function getAuth(accessToken, options = {}) {
+    const request = { access_token: accessToken };
+
+    if (options.accountIds) {
+      request.options = { account_ids: options.accountIds };
+    }
+
+    try {
+      const response = await plaidClient.authGet(request);
+      return {
+        accounts: response.data.accounts,
+        numbers: response.data.numbers,
+        item: response.data.item,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid authGet failed");
+      throw new Error(error.response?.data?.error_message || "Failed to get auth");
+    }
+  }
+
+  // ============================================================================
+  // Investments Service
+  // ============================================================================
+
+  /**
+   * Get investment holdings
+   * @param {string} accessToken - Access token
+   * @param {Object} [options] - Options
+   * @param {string[]} [options.accountIds] - Filter by account IDs
+   * @returns {Promise<Object>} Holdings response
+   */
+  async function getHoldings(accessToken, options = {}) {
+    const request = { access_token: accessToken };
+
+    if (options.accountIds) {
+      request.options = { account_ids: options.accountIds };
+    }
+
+    try {
+      const response = await plaidClient.investmentsHoldingsGet(request);
+      return {
+        accounts: response.data.accounts,
+        holdings: response.data.holdings,
+        securities: response.data.securities,
+        item: response.data.item,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid investmentsHoldingsGet failed");
+      throw new Error(error.response?.data?.error_message || "Failed to get holdings");
+    }
+  }
+
+  /**
+   * Get investment transactions
+   * @param {string} accessToken - Access token
+   * @param {string} startDate - Start date (YYYY-MM-DD)
+   * @param {string} endDate - End date (YYYY-MM-DD)
+   * @param {Object} [options] - Options
+   * @param {number} [options.count] - Number of transactions (max 500)
+   * @param {number} [options.offset] - Pagination offset
+   * @param {string[]} [options.accountIds] - Filter by account IDs
+   * @returns {Promise<Object>} Investment transactions response
+   */
+  async function getInvestmentTransactions(accessToken, startDate, endDate, options = {}) {
+    const request = {
+      access_token: accessToken,
+      start_date: startDate,
+      end_date: endDate,
+    };
+
+    const requestOptions = {};
+    if (options.count) requestOptions.count = Math.min(options.count, 500);
+    if (options.offset) requestOptions.offset = options.offset;
+    if (options.accountIds) requestOptions.account_ids = options.accountIds;
+
+    if (Object.keys(requestOptions).length > 0) {
+      request.options = requestOptions;
+    }
+
+    try {
+      const response = await plaidClient.investmentsTransactionsGet(request);
+      return {
+        accounts: response.data.accounts,
+        investmentTransactions: response.data.investment_transactions,
+        securities: response.data.securities,
+        totalInvestmentTransactions: response.data.total_investment_transactions,
+        item: response.data.item,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid investmentsTransactionsGet failed");
+      throw new Error(
+        error.response?.data?.error_message || "Failed to get investment transactions"
+      );
+    }
+  }
+
+  // ============================================================================
+  // Liabilities Service
+  // ============================================================================
+
+  /**
+   * Get liabilities information
+   * @param {string} accessToken - Access token
+   * @param {Object} [options] - Options
+   * @param {string[]} [options.accountIds] - Filter by account IDs
+   * @returns {Promise<Object>} Liabilities response
+   */
+  async function getLiabilities(accessToken, options = {}) {
+    const request = { access_token: accessToken };
+
+    if (options.accountIds) {
+      request.options = { account_ids: options.accountIds };
+    }
+
+    try {
+      const response = await plaidClient.liabilitiesGet(request);
+      return {
+        accounts: response.data.accounts,
+        liabilities: response.data.liabilities,
+        item: response.data.item,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid liabilitiesGet failed");
+      throw new Error(error.response?.data?.error_message || "Failed to get liabilities");
+    }
+  }
+
+  // ============================================================================
+  // Item Management
+  // ============================================================================
+
+  /**
+   * Get Item information
+   * @param {string} accessToken - Access token
+   * @returns {Promise<Object>} Item response
+   */
+  async function getItem(accessToken) {
+    try {
+      const response = await plaidClient.itemGet({
+        access_token: accessToken,
+      });
+      return {
+        item: response.data.item,
+        status: response.data.status,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid itemGet failed");
+      throw new Error(error.response?.data?.error_message || "Failed to get item");
+    }
+  }
+
+  /**
+   * Remove an Item
+   * @param {string} accessToken - Access token
+   * @returns {Promise<Object>} Remove response
+   */
+  async function removeItem(accessToken) {
+    try {
+      const response = await plaidClient.itemRemove({
+        access_token: accessToken,
+      });
+      return {
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid itemRemove failed");
+      throw new Error(error.response?.data?.error_message || "Failed to remove item");
+    }
+  }
+
+  /**
+   * Get institution by ID
+   * @param {string} institutionId - Institution ID
+   * @param {string[]} [countryCodes] - Country codes
+   * @returns {Promise<Object>} Institution response
+   */
+  async function getInstitution(institutionId, countryCodes = [CountryCode.Us]) {
+    try {
+      const response = await plaidClient.institutionsGetById({
+        institution_id: institutionId,
+        country_codes: countryCodes,
+      });
+      return {
+        institution: response.data.institution,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid institutionsGetById failed");
+      throw new Error(error.response?.data?.error_message || "Failed to get institution");
+    }
+  }
+
+  /**
+   * Search institutions
+   * @param {string} query - Search query
+   * @param {Object} [options] - Options
+   * @param {string[]} [options.countryCodes] - Country codes
+   * @param {string[]} [options.products] - Filter by products
+   * @param {number} [options.count] - Number of results
+   * @param {number} [options.offset] - Pagination offset
+   * @returns {Promise<Object>} Institutions search response
+   */
+  async function searchInstitutions(query, options = {}) {
+    const request = {
+      query,
+      country_codes: options.countryCodes || [CountryCode.Us],
+    };
+
+    if (options.products) request.products = options.products;
+    if (options.count) request.options = { ...request.options, count: options.count };
+    if (options.offset) request.options = { ...request.options, offset: options.offset };
+
+    try {
+      const response = await plaidClient.institutionsSearch(request);
+      return {
+        institutions: response.data.institutions,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid institutionsSearch failed");
+      throw new Error(error.response?.data?.error_message || "Failed to search institutions");
+    }
+  }
+
+  // ============================================================================
+  // Webhooks
+  // ============================================================================
+
+  /**
+   * Update webhook URL for an Item
+   * @param {string} accessToken - Access token
+   * @param {string} webhook - New webhook URL
+   * @returns {Promise<Object>} Update response
+   */
+  async function updateWebhook(accessToken, webhook) {
+    try {
+      const response = await plaidClient.itemWebhookUpdate({
+        access_token: accessToken,
+        webhook,
+      });
+      return {
+        item: response.data.item,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid itemWebhookUpdate failed");
+      throw new Error(error.response?.data?.error_message || "Failed to update webhook");
+    }
+  }
+
+  /**
+   * Get webhook verification key
+   * @param {string} keyId - Key ID from webhook header
+   * @returns {Promise<Object>} Key response
+   */
+  async function getWebhookVerificationKey(keyId) {
+    try {
+      const response = await plaidClient.webhookVerificationKeyGet({
+        key_id: keyId,
+      });
+      return {
+        key: response.data.key,
+        requestId: response.data.request_id,
+      };
+    } catch (error) {
+      fastify.log.error({ error: error.response?.data }, "Plaid webhookVerificationKeyGet failed");
+      throw new Error(error.response?.data?.error_message || "Failed to get verification key");
+    }
+  }
+
+  // Store configuration on fastify instance
+  fastify.decorate("xplaid", {
+    // Configuration
+    config: {
+      environment,
+      clientId: `***${options.clientId.slice(-4)}`,
+    },
+
+    // Constants
+    constants: {
+      ENVIRONMENTS,
+      PRODUCTS,
+      COUNTRY_CODES,
+    },
+
+    // Link token service
+    link: {
+      createToken: createLinkToken,
+      getToken: getLinkToken,
+      exchangePublicToken,
+    },
+
+    // Accounts service
+    accounts: {
+      get: getAccounts,
+      getBalance,
+    },
+
+    // Transactions service
+    transactions: {
+      sync: syncTransactions,
+      get: getTransactions,
+      refresh: refreshTransactions,
+    },
+
+    // Identity service
+    identity: {
+      get: getIdentity,
+    },
+
+    // Auth service (ACH)
+    auth: {
+      get: getAuth,
+    },
+
+    // Investments service
+    investments: {
+      getHoldings,
+      getTransactions: getInvestmentTransactions,
+    },
+
+    // Liabilities service
+    liabilities: {
+      get: getLiabilities,
+    },
+
+    // Item management service
+    items: {
+      get: getItem,
+      remove: removeItem,
+      getInstitution,
+      searchInstitutions,
+    },
+
+    // Webhooks service
+    webhooks: {
+      update: updateWebhook,
+      getVerificationKey: getWebhookVerificationKey,
+    },
+
+    // Raw client access
+    raw: plaidClient,
+  });
+
+  fastify.log.info(`#   ✅ xPlaid Enabled (${environment})`);
+  fastify.log.info("#      • Link Token Management");
+  fastify.log.info("#      • Accounts & Balance");
+  fastify.log.info("#      • Transactions");
+  fastify.log.info("#      • Identity & Auth");
+  fastify.log.info("#      • Investments & Liabilities");
+}
+
+export default fp(xPlaid, {
+  name: "xPlaid",
+});
+
+export { ENVIRONMENTS, PRODUCTS, COUNTRY_CODES };