npm package: @spearmint-finance/sdk
Description: # Financial Analysis API  A comprehensive REST API for financial transaction analysis and management.  ## Features  ### Transaction Management - Import transactions from CSV files - CRUD operations for transactions and categories - Advanced filtering and 
Latest version: 0.0.120

# SpearmintApi TypeScript SDK 1.0.0

Welcome to the SpearmintApi SDK documentation. This guide will help you get started with integrating and using the SpearmintApi SDK in your project.

[![This SDK was generated by liblab](https://raw.githubusercontent.com/liblaber/liblab-assets/main/assets/built-by-liblab-icon.svg)](https://liblab.com/?utm_source=readme)

## Versions

- API version: `0.1.0`
- SDK version: `1.0.0`

## About the API

# Financial Analysis API

A comprehensive REST API for financial transaction analysis and management.

## Features

### Transaction Management

- Import transactions from CSV files
- CRUD operations for transactions and categories
- Advanced filtering and search capabilities

### Analysis & Insights

- Income and expense analysis with category breakdowns
- Cash flow analysis and trends
- Financial health indicators
- Time-series analysis (daily, weekly, monthly, quarterly, yearly)

### Relationship Detection

- Automatic transfer pair detection
- Credit card payment/receipt matching
- Reimbursement pair detection
- Manual relationship management

### Projections & Forecasting

- Income and expense projections
- Cash flow forecasting
- Multiple projection algorithms (linear regression, moving average, exponential smoothing, weighted average)
- Scenario analysis (best case, worst case, expected)
- Accuracy metrics (MAPE, RMSE, MAE, R-squared)

### Reporting & Export

- Summary reports with key metrics
- Detailed income/expense reports
- Reconciliation reports
- Export to JSON and CSV formats

### Classification System

- 10 system classifications for transaction types
- Custom user-defined classifications
- Pattern-based classification rules
- Bulk and automatic classification
- Classification-aware calculations

### Error Handling & Logging

- Standardized error responses with detailed error codes
- Comprehensive request/response logging
- Performance monitoring
- Audit trail for data modifications

## Analysis Modes

The API supports two analysis modes:

- **ANALYSIS** (default) - Excludes transfers, reimbursements, and other non-income/expense transactions for accurate financial analysis
- **COMPLETE** - Includes all transactions for reconciliation and complete transaction history

## Authentication

Currently, the API does not require authentication. Authentication will be added in a future release.

## Rate Limiting

Currently, there are no rate limits. Rate limiting will be added in a future release.

## Support

For issues, questions, or feature requests, please contact the development team.

## Table of Contents

- [Setup & Configuration](#setup--configuration)
  - [Supported Language Versions](#supported-language-versions)
  - [Installation](#installation)
- [Authentication](#authentication)
  - [Access Token Authentication](#access-token-authentication)
- [Setting a Custom Timeout](#setting-a-custom-timeout)
- [Sample Usage](#sample-usage)
- [Services](#services)
- [Models](#models)
- [License](#license)

# Setup & Configuration

## Supported Language Versions

This SDK is compatible with the following versions: `TypeScript >= 4.8.4`

## Installation

To get started with the SDK, we recommend installing using `npm` or `yarn`:

```bash
npm install @spearmint-finance/sdk
```

or

```bash
yarn add @spearmint-finance/sdk
```

## Authentication

### Access Token Authentication

The SpearmintApi API uses an Access Token for authentication.

This token must be provided to authenticate your requests to the API.

#### Setting the Access Token

When you initialize the SDK, you can set the access token as follows:

```ts
const sdk = new SpearmintApi({ token: 'YOUR_TOKEN' });
```

If you need to set or update the access token after initializing the SDK, you can use:

```ts
const sdk = new SpearmintApi();
sdk.token = 'YOUR_TOKEN';
```

## Setting a Custom Timeout

You can set a custom timeout for the SDK's HTTP requests as follows:

```ts
const spearmintApi = new SpearmintApi({ timeout: 10000 });
```

# Sample Usage

Below is a comprehensive example demonstrating how to authenticate and call a simple endpoint:

```ts
import { SpearmintApi } from '@spearmint-finance/sdk';

(async () => {
  const spearmintApi = new SpearmintApi({
    token: 'YOUR_TOKEN',
  });

  const { data } = await spearmintApi.system.healthCheck();

  console.log(data);
})();
```

## Services

The SDK provides various services to interact with the API.

<details>
<summary>Below is a list of all available services with links to their detailed documentation:</summary>

| Name                                                                   |
| :--------------------------------------------------------------------- |
| SystemService               |
| TransactionsService   |
| SplitsService               |
| CategoriesService       |
| Import_Service             |
| AnalysisService           |
| RelationshipsService |
| ProjectionsService     |
| ReportsService             |
| PersonsService             |
| ScenariosService         |
| AccountsService           |
| EntitiesService           |
| MaintenanceService     |
| AuthService                   |
| AssistantService         |
| LinkService                   |
| A2aAgentsService         |

</details>

## Models

The SDK includes several models that represent the data structures used in API requests and responses. These models help in organizing and managing the data efficiently.

<details>
<summary>Below is a list of all available models with links to their detailed documentation:</summary>

| Name                                                                                                                                   | Description                                                             |
| :------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |
| TransactionListResponse                                                             | Schema for transaction list response.                                   |
| TransactionResponse                                                                     | Schema for transaction response.                                        |
| CategoryInfo                                                                                   | Category information for transaction response.                          |
| TagInfo                                                                                             | Tag information for transaction response.                               |
| TransactionSplitResponse                                                           | Read model for a transaction split.                                     |
| HttpValidationError                                                                     |                                                                         |
| ValidationError                                                                             |                                                                         |
| TransactionCreate                                                                         | Schema for creating a transaction.                                      |
| TransactionSplitCreate                                                               | Create a category-based split for a transaction.                        |
| TransactionUpdate                                                                         | Schema for updating a transaction.                                      |
| SuccessResponse                                                                             | Success response schema.                                                |
| TransactionSplitResponse                                                           | Read model for a transaction split.                                     |
| HttpValidationError                                                                     |                                                                         |
| TransactionSplitCreate                                                               | Create a category-based split for a transaction.                        |
| CategoryListResponse                                                                   | Schema for category list response.                                      |
| CategoryResponse                                                                           | Schema for category response.                                           |
| HttpValidationError                                                                     |                                                                         |
| CategoryCreate                                                                               | Schema for creating a category.                                         |
| CategoryUpdate                                                                               | Schema for updating a category.                                         |
| SuccessResponse                                                                             | Success response schema.                                                |
| CategoryRuleListResponse                                                           | Schema for category rule list response.                                 |
| CategoryRuleResponse                                                                   | Schema for category rule response.                                      |
| CategoryRuleCreate                                                                       | Schema for creating a category rule.                                    |
| CategoryRuleUpdate                                                                       | Schema for updating a category rule.                                    |
| TestCategoryRuleResponse                                                           | Schema for test category rule response.                                 |
| TestCategoryRuleRequest                                                             | Schema for testing a category rule.                                     |
| ApplyCategoryRulesResponse                                                       | Schema for apply category rules response.                               |
| ApplyCategoryRulesRequest                                                         | Schema for applying category rules.                                     |
| ImportResponse                                                                               | Schema for import response.                                             |
| ImportErrorDetail                                                                         | Schema for import error detail.                                         |
| BodyImportTransactionsApiImportPost                                     |                                                                         |
| HttpValidationError                                                                     |                                                                         |
| ImportRequest                                                                                 | Schema for import request.                                              |
| ImportHistoryResponse                                                                 | Schema for import history list response.                                |
| ImportHistoryItem                                                                         | Schema for a single import history item.                                |
| ImportHistoryDetailResponse                                                     | Schema for detailed import history response.                            |
| ImportStatusResponse                                                                   | Schema for import status response.                                      |
| ImportProfileListResponse                                                         | Schema for list of import profiles.                                     |
| ImportProfileResponse                                                                 | Schema for import profile response.                                     |
| ImportProfileCreate                                                                     | Schema for creating an import profile.                                  |
| ImportProfileUpdate                                                                     | Schema for updating an import profile.                                  |
| ImportProfileSuggestion                                                             | Schema for suggested import profile match.                              |
| BodySuggestImportProfilesApiImportProfilesSuggestPost |                                                                         |
| IncomeAnalysisResponse                                                               | Response for income analysis.                                           |
| CategoryBreakdown                                                                         | Category breakdown data.                                                |
| AnalysisModeEnum                                                                           | Analysis mode.                                                          |
| HttpValidationError                                                                     |                                                                         |
| TrendsResponse                                                                               | Response for trend analysis.                                            |
| TrendDataPoint                                                                               | Single data point in a trend.                                           |
| TimePeriodEnum                                                                               | Time period granularity.                                                |
| ExpenseAnalysisResponse                                                             | Response for expense analysis.                                          |
| TopCategory                                                                                     | Top category data.                                                      |
| GetCashFlowAnalysisOkResponse                                                 | Response for cash flow analysis.                                        |
| CashFlowTrendsResponse                                                               | Response for cash flow trends.                                          |
| CashFlowTrendPoint                                                                       | Cash flow trend data point.                                             |
| FinancialHealthResponse                                                             | Response for financial health indicators.                               |
| FinancialSummaryResponse                                                           | Response for comprehensive financial summary.                           |
| RecentTransaction                                                                         | Recent transaction summary.                                             |
| IncomeExpenseComparisonResponse                                             | Response for income vs expense comparison.                              |
| CategoryBreakdownResponse1                                                       | Response for category breakdown analysis.                               |
| CategoryBreakdownItem                                                                 | Category breakdown item with details.                                   |
| TransferPairsResponse                                                                 | Response with detected transfer pairs.                                  |
| TransferPairDetection                                                                 | Detected transfer pair.                                                 |
| TransactionSummary                                                                       | Summary of a transaction for relationship display.                      |
| HttpValidationError                                                                     |                                                                         |
| CreditCardPairsResponse                                                             | Response with detected credit card pairs.                               |
| CreditCardPairDetection                                                             | Detected credit card payment/receipt pair.                              |
| ReimbursementPairsResponse                                                       | Response with detected reimbursement pairs.                             |
| ReimbursementPairDetection                                                       | Detected reimbursement pair.                                            |
| DividendReinvestmentPairsResponse                                         | Response with detected dividend reinvestment pairs.                     |
| DividendReinvestmentPairDetection                                         | Detected dividend reinvestment pair.                                    |
| DetectAllRelationshipsResponse                                               | Response with all detected relationships.                               |
| RelationshipResponse                                                                   | Response model for a transaction relationship.                          |
| RelationshipCreateRequest                                                         | Request to create a relationship between transactions.                  |
| RelatedTransactionsResponse                                                     | Response with related transactions.                                     |
| RelatedTransactionInfo                                                               | Information about a related transaction.                                |
| SuccessResponse                                                                             | Success response schema.                                                |
| IncomeProjectionResponse                                                           | Response for income projections.                                        |
| HistoricalPeriod                                                                           | Historical period information.                                          |
| ProjectionPeriod                                                                           | Projection period information.                                          |
| ConfidenceInterval                                                                       | Confidence interval for projections.                                    |
| DailyProjection                                                                             | Daily projection data point.                                            |
| ModelMetrics                                                                                   | Model performance metrics.                                              |
| ProjectionMethodEnum                                                                   | Projection algorithm methods.                                           |
| HttpValidationError                                                                     |                                                                         |
| ExpenseProjectionResponse                                                         | Response for expense projections.                                       |
| CashflowProjectionResponse                                                       | Response for cash flow projections.                                     |
| CashflowDailyProjection                                                             | Daily cash flow projection data point.                                  |
| Scenarios                                                                                         | Scenario analysis results.                                              |
| ScenarioData                                                                                   | Scenario analysis data.                                                 |
| ScenarioRange                                                                                 | Range across scenarios.                                                 |
| AccuracyMetrics                                                                             | Projection accuracy metrics.                                            |
| ValidationRequest                                                                         | Request for projection validation.                                      |
| BalanceReportResponse                                                                 | Response for balance report.                                            |
| BalanceSummary                                                                               | High-level balance summary.                                             |
| AccountBalanceDetail                                                                   | Detail for a single account balance.                                    |
| SummaryReportResponse                                                                 | Response for summary report.                                            |
| ReportPeriod                                                                                   | Report period information.                                              |
| IncomeSummary                                                                                 | Income summary in a report.                                             |
| CategorySummary                                                                             | Category summary in a report.                                           |
| ExpenseSummary                                                                               | Expense summary in a report.                                            |
| CashflowSummary                                                                             | Cash flow summary in a report.                                          |
| HealthIndicators                                                                           | Financial health indicators.                                            |
| ReportModeEnum                                                                               | Analysis mode for reports.                                              |
| ReportFormatEnum                                                                           | Report export formats.                                                  |
| HttpValidationError                                                                     |                                                                         |
| IncomeDetailReportResponse                                                       | Response for detailed income report.                                    |
| CategoryDetail                                                                               | Detailed category information.                                          |
| ExpenseDetailReportResponse                                                     | Response for detailed expense report.                                   |
| ReconciliationReportResponse                                                   | Response for reconciliation report.                                     |
| ReconciliationSummary                                                                 | Summary for reconciliation report.                                      |
| TransactionDetail                                                                         | Transaction detail for reconciliation report.                           |
| CapExReportResponse                                                                     | Response for capital expense report.                                    |
| CapExSummary                                                                                   | Summary statistics for CapEx report.                                    |
| CapExCategorySummary                                                                   | CapEx totals grouped by category.                                       |
| CapExTransaction                                                                           | Individual capital expense transaction.                                 |
| ReceivablesReportResponse                                                         | Response for receivables (reimbursement tracking) report.               |
| ReceivablesSummary                                                                       | Summary statistics for Receivables report.                              |
| ReceivablesCategorySummary                                                       | Receivables totals grouped by category.                                 |
| ReceivableTransaction                                                                 | Individual receivable transaction (expense awaiting reimbursement).     |
| PersonRead                                                                                       | Schema returned for a person.                                           |
| PersonCreate                                                                                   | Schema to create a person.                                              |
| HttpValidationError                                                                     |                                                                         |
| ScenarioTemplateListResponse                                                   | Paginated list of scenario templates.                                   |
| ScenarioTemplate                                                                           | A scenario template with pre-configured adjusters.                      |
| TemplateAdjuster                                                                           | A single adjuster within a scenario template.                           |
| HttpValidationError                                                                     |                                                                         |
| ScenarioPreviewResponse                                                             |                                                                         |
| SeriesPoint                                                                                     |                                                                         |
| ScenarioKpIs                                                                                   |                                                                         |
| ScenarioPreviewRequest                                                               | Scenario preview request body.                                          |
| ScenarioAdjusterIn                                                                       | Inline adjuster for preview/simulate.                                   |
| NetWorthResponse                                                                           | Schema for net worth response.                                          |
| HttpValidationError                                                                     |                                                                         |
| AccountSummary                                                                               | Schema for account summary with balance.                                |
| AccountResponse                                                                             | Schema for account responses.                                           |
| AccountCreate                                                                                 | Schema for creating a new account.                                      |
| AccountUpdate                                                                                 | Schema for updating an account.                                         |
| BalanceHistory                                                                               | Schema for balance history response.                                    |
| BalanceResponse                                                                             | Schema for balance responses.                                           |
| BalanceCreate                                                                                 | Schema for creating a balance snapshot.                                 |
| CalculatedBalance                                                                         | Schema for calculated balance response.                                 |
| HoldingResponse                                                                             | Schema for holding responses.                                           |
| HoldingCreate                                                                                 | Schema for creating/updating a holding.                                 |
| HoldingUpdate                                                                                 | Schema for updating a holding. All fields optional.                     |
| PortfolioSummary                                                                           | Schema for portfolio summary.                                           |
| ReconciliationResponse                                                               | Schema for reconciliation responses.                                    |
| ReconciliationCreate                                                                   | Schema for creating a reconciliation.                                   |
| ReconciliationComplete                                                               | Schema for completing a reconciliation.                                 |
| TransactionClearRequest                                                             | Schema for clearing transactions.                                       |
| EntityResponse                                                                               | Schema for entity responses.                                            |
| EntityCreate                                                                                   | Schema for creating an entity.                                          |
| HttpValidationError                                                                     |                                                                         |
| EntityUpdate                                                                                   | Schema for updating an entity.                                          |
| PnlResponse                                                                                     | Profit & Loss statement response.                                       |
| GetEntityCashflowOkResponse                                                     | Cash flow statement response.                                           |
| FixResult                                                                                         |                                                                         |
| ApiKeyListResponse                                                                       | Schema for list of API keys.                                            |
| ApiKeyResponse                                                                               | Schema for API key responses (masked key).                              |
| HttpValidationError                                                                     |                                                                         |
| ApiKeyCreatedResponse                                                                 | Schema for newly created API key (includes full key - shown only once). |
| ApiKeyCreate                                                                                   | Schema for creating a new API key.                                      |
| ApiKeyValidateResponse                                                               | Schema for API key validation response.                                 |
| ApiKeyValidateRequest                                                                 | Schema for validating an API key.                                       |
| ChatRequest                                                                                     | Request body for chat endpoint.                                         |
| ChatContext                                                                                     | Context for the chat message.                                           |
| HttpValidationError                                                                     |                                                                         |
| ConversationResponse                                                                   | Response for conversation listing.                                      |
| ActionConfirmRequest                                                                   | Request body for action confirmation.                                   |
| InsightResponse                                                                             | Response for insights.                                                  |
| LinkTokenResponse                                                                         | Response from creating a Plaid Link token.                              |
| LinkedProviderResponse                                                               | Response with linked provider details.                                  |
| PublicTokenExchange                                                                     | Request to exchange a Plaid public token.                               |
| HttpValidationError                                                                     |                                                                         |
| AkoyaAuthUrlResponse                                                                   | Response with Akoya OAuth authorization URL.                            |
| AkoyaCallbackRequest                                                                   | Request to exchange an Akoya authorization code.                        |
| SyncResultResponse                                                                       | Response from a sync operation.                                         |
| HttpValidationError                                                                     |                                                                         |
| A2ARequest                                                                                       | Generic A2A invocation envelope.                                        |
| NegotiationChoice                                                                         |                                                                         |

</details>

## License

This SDK is licensed under the MIT License.

See the [LICENSE](LICENSE) file for more details.

<!-- This file was generated by liblab | https://liblab.com/ -->