pluggy-sdk
Version:
Official Node.js/TypeScript SDK for the Pluggy API.
373 lines (372 loc) • 13.2 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", { value: true });
exports.PluggyClient = void 0;
const baseApi_1 = require("./baseApi");
const paymentsClient_1 = require("./paymentsClient");
/**
* Creates a new client instance for interacting with Pluggy API
* @constructor
* @param API_KEY for authenticating to the API
* @returns {PluggyClient} a client for making requests
*/
class PluggyClient extends baseApi_1.BaseApi {
constructor(params) {
super(params);
this.payments = new paymentsClient_1.PluggyPaymentsClient(params);
}
/**
* Fetch all available connectors
* @returns {PageResponse<Connector>} paged response of connectors
*/
async fetchConnectors(options = {}) {
return await this.createGetRequest('connectors', options);
}
/**
* Fetch a single Connector
* @param id The Connector ID
* @returns {Connector} a connector object
*/
async fetchConnector(id) {
return await this.createGetRequest(`connectors/${id}`);
}
/**
* Fetch a single item
* @param id The Item ID
* @returns {Item} a item object
*/
async fetchItem(id) {
return await this.createGetRequest(`items/${id}`);
}
/**
* Check that connector parameters are valid
* @param id The Connector ID
* @param parameters A map of name and value for the credentials to be validated
* @returns {ValidationResult} an object with the info of which parameters are wrong
*/
async validateParameters(id, parameters) {
return await this.createPostRequest(`connectors/${id}/validate`, null, parameters);
}
/**
* Creates an item
* @param connectorId The Connector's id
* @param parameters A map of name and value for the needed credentials
* @param options Options available to set to the item
* @returns {Item} a item object
*/
async createItem(connectorId, parameters, options) {
return await this.createPostRequest(`items`, null, {
connectorId,
parameters,
...(options || {}),
});
}
/**
* Updates an item
* @param id The Item ID
* @param parameters A map of name and value for the credentials to be updated.
* Optional; if none submitted, an Item update will be attempted with the latest used credentials.
* @returns {Item} a item object
*/
async updateItem(id, parameters, options) {
return await this.createPatchRequest(`items/${id}`, null, {
id,
parameters,
...(options || {}),
});
}
/**
* Send MFA for item execution
* @param id The Item ID
* @param parameters A map of name and value for the mfa requested
* @returns {Item} a item object
*/
async updateItemMFA(id, parameters = undefined) {
return await this.createPostRequest(`items/${id}/mfa`, null, parameters);
}
/**
* Deletes an item
*/
async deleteItem(id) {
await this.createDeleteRequest(`items/${id}`);
}
/**
* Fetch accounts from an Item
* @param itemId The Item id
* @returns {PageResponse<Account>} paged response of accounts
*/
async fetchAccounts(itemId, type) {
return await this.createGetRequest('accounts', { itemId, type });
}
/**
* Fetch a single account
* @returns {Account} an account object
*/
async fetchAccount(id) {
return await this.createGetRequest(`accounts/${id}`);
}
/**
* Fetch transactions from an account using page-based pagination.
*
* @deprecated Use {@link fetchTransactionsCursor} (single page) or
* {@link fetchAllTransactions} (full sweep) instead. Both rely on the
* `GET /v2/transactions` endpoint with cursor-based pagination, which
* is more stable for long lists and supports the full filter set
* (`dateTo`, `ids`, etc.). This page-based method is kept for
* backward compatibility and will be removed in a future major
* release.
*
* @param accountId The account id
* @param {TransactionFilters} options Transaction options to filter
* @returns {PageResponse<Transaction[]>} object which contains the transactions list and related paging data
*/
async fetchTransactions(accountId, options = {}) {
return await this.createGetRequest('transactions', { ...options, accountId });
}
/**
* Fetch transactions from an account using cursor-based pagination
* @param accountId The account id
* @param {TransactionCursorFilters} options Optional filters (dateFrom, createdAtFrom, after cursor)
* @returns {CursorPageResponse<Transaction>} object with results and next cursor link
*/
async fetchTransactionsCursor(accountId, options = {}) {
return await this.createGetRequest('v2/transactions', { ...options, accountId });
}
/**
* Fetch all transactions from an account using cursor-based pagination
* @param accountId The account id
* @param {TransactionCursorFilters} options Optional filters (dateFrom, createdAtFrom)
* @returns {Transaction[]} an array of all transactions
*/
async fetchAllTransactions(accountId, options = {}) {
const firstPage = await this.fetchTransactionsCursor(accountId, options);
const transactions = [...firstPage.results];
let next = firstPage.next;
while (next !== null) {
const afterParam = new URL(next, this.baseUrl).searchParams.get('after');
if (!afterParam) {
break;
}
const page = await this.fetchTransactionsCursor(accountId, { ...options, after: afterParam });
transactions.push(...page.results);
next = page.next;
}
return transactions;
}
/**
* Fetch account statements from an account
* @param accountId The account id
* @returns {PageResponse<AccountStatement[]>} object which contains the Account statements list and related paging data
*/
async fetchAccountStatements(accountId) {
return await this.createGetRequest(`accounts/${accountId}/statements`);
}
/**
* Post transaction user category for transactin
* @param id The Transaction id
*
* @returns {Transaction} updated transaction object
*/
async updateTransactionCategory(id, categoryId) {
return await this.createPatchRequest(`transactions/${id}`, null, {
categoryId,
});
}
/**
* Fetch a single transaction
*
* @returns {Transaction} an transaction object
*/
async fetchTransaction(id) {
return await this.createGetRequest(`transactions/${id}`);
}
/**
* Fetch investments from an Item
*
* @param itemId The Item id
* @returns {PageResponse<Investment>} paged response of investments
*/
async fetchInvestments(itemId, type, options = {}) {
return await this.createGetRequest('investments', {
...options,
itemId,
type,
});
}
/**
* Fetch a single investment
*
* @returns {Investment} an investment object
*/
async fetchInvestment(id) {
return await this.createGetRequest(`investments/${id}`);
}
/**
* Fetch transactions from an investment
*
* @param investmentId The investment id
* @param {TransactionFilters} options Transaction options to filter
* @returns {PageResponse<InvestmentTransaction[]>} object which contains the transactions list and related paging data
*/
async fetchInvestmentTransactions(investmentId, options = {}) {
return await this.createGetRequest(`investments/${investmentId}/transactions`, {
...options,
investmentId,
});
}
/**
* Fetch all investment transactions from an investment
* @param investmentId The investment id
* @returns {InvestmentTransaction[]} an array of investment transactions
*/
async fetchAllInvestmentTransactions(investmentId) {
const MAX_PAGE_SIZE = 500;
const { totalPages, results: firstPageResults, } = await this.fetchInvestmentTransactions(investmentId, { pageSize: MAX_PAGE_SIZE });
if (totalPages === 1) {
return firstPageResults;
}
const transactions = [...firstPageResults];
let page = 1;
while (page < totalPages) {
page++;
const paginatedTransactions = await this.fetchInvestmentTransactions(investmentId, {
page,
pageSize: MAX_PAGE_SIZE,
});
transactions.push(...paginatedTransactions.results);
}
return transactions;
}
/**
* Fetch loans from an Item
*
* @param {string} itemId
* @param {PageFilters} options - request search filters
* @returns {Promise<PageResponse<Loan>>} - paged response of loans
*/
async fetchLoans(itemId, options = {}) {
return await this.createGetRequest('loans', { ...options, itemId });
}
/**
* Fetch loan by id
*
* @param {string} id - the loan id
* @returns {Promise<Loan>} - loan object, if found
*/
async fetchLoan(id) {
return await this.createGetRequest(`loans/${id}`);
}
/**
* Fetch consents from an Item
*
* @param {string} itemId - the item id
* @param {ConsentFilters} options - request search filters
* @returns {Promise<PageResponse<Consent>>} - paged response of consents
*/
async fetchConsents(itemId, options = {}) {
return await this.createGetRequest('consents', { ...options, itemId });
}
/**
* Fetch consent by id
*
* @param {string} id - the consent id
* @returns {Promise<Consent>} - consent object, if found
*/
async fetchConsent(id) {
return await this.createGetRequest(`consents/${id}`);
}
/**
* Fetch the identity resource
* @returns {IdentityResponse} an identity object
*/
async fetchIdentity(id) {
return await this.createGetRequest(`identity/${id}`);
}
/**
* Fetch the identity resource by it's Item ID
* @returns {IdentityResponse} an identity object
*/
async fetchIdentityByItemId(itemId) {
return await this.createGetRequest(`identity?itemId=${itemId}`);
}
/**
* Fetch credit card bills from an accountId
* @returns {PageResponse<CreditCardBills>} an credit card bills object
*/
async fetchCreditCardBills(accountId, options = {}) {
return await this.createGetRequest('bills', { ...options, accountId });
}
/**
* Fetch a single credit card bill by its id
* @param {string} id - the credit card bill id
* @returns {Promise<CreditCardBills>} - credit card bill object, if found
*/
async fetchCreditCardBill(id) {
return await this.createGetRequest(`bills/${id}`);
}
/**
* Fetch all available categories
* @returns {Categories[]} an paging response of categories
*/
async fetchCategories() {
return await this.createGetRequest('categories');
}
/**
* Fetch a single category
* @returns {Category} a category object
*/
async fetchCategory(id) {
return await this.createGetRequest(`categories/${id}`);
}
/**
* Fetch a single webhook
* @returns {Webhook} a webhook object
*/
async fetchWebhook(id) {
return await this.createGetRequest(`webhooks/${id}`);
}
/**
* Fetch all available webhooks
* @returns {Webhook[]} a paging response of webhooks
*/
async fetchWebhooks() {
return await this.createGetRequest('webhooks');
}
/**
* Creates a Webhook
* @param webhookParams - The webhook params to create, this includes:
* - url: The url where will receive notifications
* - event: The event to listen for
* - headers (optional): The headers to send with the webhook
* @returns {Webhook} the created webhook object
*/
async createWebhook(event, url, headers) {
return await this.createPostRequest(`webhooks`, null, {
event,
url,
headers,
});
}
/**
* Updates a Webhook
* @param id - The Webhook ID
* @param updatedWebhookParams - The webhook params to update
* @returns {Webhook} The webhook updated
*/
async updateWebhook(id, updatedWebhookParams) {
return await this.createPatchRequest(`webhooks/${id}`, null, updatedWebhookParams);
}
/**
* Deletes a Webhook
*/
async deleteWebhook(id) {
return await this.createDeleteRequest(`webhooks/${id}`);
}
/**
* Creates a connect token that can be used as API KEY to connect items from the Frontend
* @returns {string} Access token to connect items with restrict access
*/
async createConnectToken(itemId, options) {
return await this.createPostRequest(`connect_token`, null, { itemId, options });
}
}
exports.PluggyClient = PluggyClient;