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.

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
  • Supported Language Versions
  • Installation
• Authentication
  • Access Token Authentication
• Setting a Custom Timeout
• Sample Usage
• Services
• Models
• 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:

npm install @spearmint-finance/sdk

or

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:

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

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

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:

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

Sample Usage

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

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

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

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

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

Services

The SDK provides various services to interact with the API.

| Name | | :------------------------------------------------------------------------- | | SystemService | | TransactionsService | | CategoriesService | | Import_Service | | AnalysisService | | RelationshipsService | | ProjectionsService | | ReportsService | | ClassificationsService | | PersonsService | | SplitsService | | ScenariosService | | AccountsService | | MaintenanceService |

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.

| Name | Description | | :------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------- | | TransactionListResponse | Schema for transaction list response. | | TransactionResponse | Schema for transaction response. | | CategoryInfo | Category information for transaction response. | | ClassificationInfo | Classification information for transaction response. | | TagInfo | Tag information for transaction response. | | HttpValidationError | | | ValidationError | | | TransactionCreate | Schema for creating a transaction. | | TransactionUpdate | Schema for updating a transaction. | | SuccessResponse | Success response schema. | | 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. | | TestCategoryRuleRequest | Schema for testing a category rule. | | TestCategoryRuleResponse | Schema for test category rule response. | | ApplyCategoryRulesRequest | Schema for applying category rules. | | ApplyCategoryRulesResponse | Schema for apply category rules response. | | BodyImportTransactionsApiImportPost | | | ImportResponse | Schema for import response. | | ImportErrorDetail | Schema for import error detail. | | 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. | | GetIncomeAnalysisApiAnalysisIncomeGetMode | Analysis mode. | | IncomeAnalysisResponse | Response for income analysis. | | CategoryBreakdown | Category breakdown data. | | IncomeAnalysisResponseMode | Analysis mode. | | HttpValidationError | | | TimePeriodEnum | Time period granularity. | | TrendsResponse | Response for trend analysis. | | TrendDataPoint | Single data point in a trend. | | ExpenseAnalysisResponse | Response for expense analysis. | | TopCategory | Top category data. | | CashFlowResponse | 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. | | RelationshipCreateRequest | Request to create a relationship between transactions. | | RelationshipResponse | Response model for a transaction relationship. | | RelatedTransactionsResponse | Response with related transactions. | | RelatedTransactionInfo | Information about a related transaction. | | SuccessResponse | Success response schema. | | ProjectionMethodEnum | Projection algorithm methods. | | 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. | | 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. | | ValidationRequest | Request for projection validation. | | AccuracyMetrics | Projection accuracy metrics. | | BalanceReportResponse | Response for balance report. | | BalanceSummary | High-level balance summary. | | AccountBalanceDetail | Detail for a single account balance. | | GetSummaryReportApiReportsSummaryGetMode | Analysis mode for reports. | | ReportFormatEnum | Report export formats. | | 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. | | 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. | | ClassificationListResponse | Schema for list of classifications. | | ClassificationResponse | Schema for classification response. | | HttpValidationError | | | ClassificationCreate | Schema for creating a new classification. | | ClassificationUpdate | Schema for updating a classification. | | ClassifyTransactionRequest | Schema for classifying a transaction. | | BulkClassifyRequest | Schema for bulk classification. | | BulkClassifyResponse | Schema for bulk classification response. | | AutoClassifyRequest | Schema for auto-classification request. | | AutoClassifyResponse | Schema for auto-classification response. | | ClassificationRuleListResponse | Schema for list of classification rules. | | ClassificationRuleResponse | Schema for classification rule response. | | ClassificationRuleCreate | Schema for creating a classification rule. | | ClassificationRuleUpdate | Schema for updating a classification rule. | | TestRuleRequest | Schema for testing a classification rule. | | TestRuleResponse | Schema for rule test response. | | ApplyRulesRequest | Schema for applying classification rules. | | ApplyRulesResponse | Schema for apply rules response. | | PersonRead | Schema returned for a person. | | PersonCreate | Schema to create a person. | | HttpValidationError | | | TransactionSplitRead | Read model for a transaction split. | | HttpValidationError | | | TransactionSplitCreate | Create a split for a transaction. | | ScenarioPreviewRequest | Scenario preview request body. | | ScenarioAdjusterIn | Inline adjuster for preview/simulate. | | ScenarioPreviewResponse | | | SeriesPoint | | | ScenarioKpIs | | | HttpValidationError | | | 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. | | PortfolioSummary | Schema for portfolio summary. | | ReconciliationCreate | Schema for creating a reconciliation. | | ReconciliationResponse | Schema for reconciliation responses. | | ReconciliationComplete | Schema for completing a reconciliation. | | TransactionClearRequest | Schema for clearing transactions. | | FixResult | |

License

This SDK is licensed under the MIT License.

See the LICENSE file for more details.