### Set Up Local Development Environment (Bash)

Source: https://github.com/vas3k/taxhacker/blob/main/README.md

This script guides through cloning the TaxHacker repository, installing dependencies using npm, setting up environment variables by copying an example file, initializing the database with Prisma, and starting the development server.

```bash
# Clone the repository
git clone https://github.com/vas3k/TaxHacker.git
cd TaxHacker

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env

# Edit .env with your configuration
# Make sure to set DATABASE_URL to your PostgreSQL connection string
# Example: postgresql://user@localhost:5432/taxhacker

# Initialize the database
npx prisma generate && npx prisma migrate dev

# Start the development server
npm run dev
```

--------------------------------

### Deploy TaxHacker with Docker Compose

Source: https://github.com/vas3k/taxhacker/blob/main/README.md

This snippet demonstrates the basic steps to download the Docker Compose configuration file and start TaxHacker using Docker. It assumes Docker and Docker Compose are already installed on the system.

```bash
curl -O https://raw.githubusercontent.com/vas3k/TaxHacker/main/docker-compose.yml

docker compose up
```

--------------------------------

### Build and Start Production Server (Bash)

Source: https://github.com/vas3k/taxhacker/blob/main/README.md

These commands are used to build the TaxHacker application for production and then start the production server. This is an alternative to the development server commands.

```bash
# Build the application
npm run build

# Start the production server
npm run start
```

--------------------------------

### Quick Docker Deployment with Bash

Source: https://context7.com/vas3k/taxhacker/llms.txt

This bash script provides a quick start guide for deploying TaxHacker using Docker Compose. It involves downloading the `docker-compose.yml` file, running the services in detached mode, and accessing the application via `http://localhost:7331`.

```bash
# Quick start
curl -O https://raw.githubusercontent.com/vas3k/TaxHacker/main/docker-compose.yml
docker compose up -d

# Access at http://localhost:7331

```

--------------------------------

### Custom Docker Compose Configuration for TaxHacker

Source: https://github.com/vas3k/taxhacker/blob/main/README.md

An example of a custom Docker Compose configuration for TaxHacker. This allows for specific settings such as image repository, port mapping, environment variables for database connection and upload paths, and volume mounts for persistent data.

```yaml
services:
  app:
    image: ghcr.io/vas3k/taxhacker:latest
    ports:
      - "7331:7331"
    environment:
      - SELF_HOSTED_MODE=true
      - UPLOAD_PATH=/app/data/uploads
      - DATABASE_URL=postgresql://postgres:postgres@localhost:5432/taxhacker
    volumes:
      - ./data:/app/data
    restart: unless-stopped
```

--------------------------------

### Docker Compose Deployment Configuration

Source: https://context7.com/vas3k/taxhacker/llms.txt

This YAML configuration defines a Docker Compose setup for deploying TaxHacker. It includes services for the application and a PostgreSQL database, specifying images, ports, environment variables, volumes, and restart policies. The configuration ensures a self-hosted environment with necessary credentials and data persistence.

```yaml
# docker-compose.yml
services:
  app:
    image: ghcr.io/vas3k/taxhacker:latest
    ports:
      - "7331:7331"
    environment:
      - NODE_ENV=production
      - SELF_HOSTED_MODE=true
      - UPLOAD_PATH=/app/data/uploads
      - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/taxhacker
      - BETTER_AUTH_SECRET=your-secure-secret-minimum-16-chars
      - OPENAI_API_KEY=sk-your-openai-key
      - OPENAI_MODEL_NAME=gpt-4o-mini
    volumes:
      - ./data:/app/data
    restart: unless-stopped
    depends_on:
      - postgres

  postgres:
    image: postgres:17-alpine
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=taxhacker
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    restart: unless-stopped

```

--------------------------------

### Fetch Currency Conversion Rates API (Bash)

Source: https://context7.com/vas3k/taxhacker/llms.txt

Retrieves historical exchange rates for currency conversion from XE.com. The API caches results for 24 hours and supports over 170 currencies. It requires 'from', 'to', and 'date' parameters.

```bash
# Get historical exchange rate from EUR to USD for a specific date
curl -X GET "http://localhost:7331/api/currency?from=EUR&to=USD&date=2024-01-15" \
  -H "Cookie: session=your-session-token"

# Response (success)
{
  "rate": 1.0892,
  "cached": false
}

# Response with cached data
{
  "rate": 1.0892,
  "cached": true
}

# Error response for missing parameters
{
  "error": "Missing required parameters: from, to, date"
}
```

--------------------------------

### Configure LLM Providers for Document Analysis with TypeScript

Source: https://context7.com/vas3k/taxhacker/llms.txt

This TypeScript code configures multiple LLM providers (OpenAI, Google, Mistral) for document analysis. It defines settings including API keys and models, and constructs a request object with a prompt, schema, and attachments. The `requestLLM` function handles the request and provides a response with extracted data and provider information.

```typescript
// LLM provider types and configuration
import { requestLLM, type LLMSettings, type LLMRequest } from "@/ai/providers/llmProvider"

const llmSettings: LLMSettings = {
  providers: [
    {
      provider: "openai",
      apiKey: process.env.OPENAI_API_KEY,
      model: "gpt-4o-mini"
    },
    {
      provider: "google",
      apiKey: process.env.GOOGLE_API_KEY,
      model: "gemini-2.5-flash"
    },
    {
      provider: "mistral",
      apiKey: process.env.MISTRAL_API_KEY,
      model: "mistral-medium-latest"
    }
  ]
}

const request: LLMRequest = {
  prompt: "Extract financial data from this receipt…",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" },
      total: { type: "number" },
      merchant: { type: "string" },
      date: { type: "string" }
    }
  },
  attachments: [
    {
      contentType: "image/jpeg",
      base64: "base64-encoded-image-data…"
    }
  ]
}

const response = await requestLLM(llmSettings, request)
// Result: {
//   output: { name: "...", total: 45.99, merchant: "...", date: "2024-03-15" },
//   provider: "openai",
//   tokensUsed: 150
// }

```

--------------------------------

### Manage User Settings using TypeScript

Source: https://context7.com/vas3k/taxhacker/llms.txt

Handles various user settings including general preferences, categories, projects, custom fields, and currencies. Utilizes server actions imported from '@/app/(app)/settings/actions'. Supports adding, editing, and deleting these entities.

```typescript
// Save general settings
import { saveSettingsAction } from "@/app/(app)/settings/actions"

const settingsFormData = new FormData()
settingsFormData.append("prompt_analyse_new_file", "Custom AI prompt for document analysis...")
settingsFormData.append("default_currency", "EUR")

const result = await saveSettingsAction(null, settingsFormData)
// Result: { success: true }

// Category management
import { addCategoryAction, editCategoryAction, deleteCategoryAction } from "@/app/(app)/settings/actions"

const newCategory = await addCategoryAction("user-uuid", {
  name: "Software Subscriptions",
  llm_prompt: "Software licenses and SaaS subscriptions",
  color: "#3B82F6"
})
// Result: { success: true, category: { code: "software-subscriptions", ... } }

await editCategoryAction("user-uuid", "software-subscriptions", {
  name: "Software & SaaS",
  llm_prompt: "Software licenses, SaaS subscriptions, and digital tools"
})

await deleteCategoryAction("user-uuid", "software-subscriptions")

// Project management
import { addProjectAction, editProjectAction } from "@/app/(app)/settings/actions"

const newProject = await addProjectAction("user-uuid", {
  name: "Client ABC",
  llm_prompt: "Expenses for Client ABC project",
  color: "#10B981"
})

// Custom field management
import { addFieldAction, editFieldAction } from "@/app/(app)/settings/actions"

const customField = await addFieldAction("user-uuid", {
  name: "Invoice Number",
  type: "string",
  llm_prompt: "Extract the invoice or receipt number from the document",
  isVisibleInList: true,
  isVisibleInAnalysis: true,
  isRequired: false
})
// Result: { success: true, field: { code: "invoice-number", isExtra: true, ... } }

// Currency management
import { addCurrencyAction } from "@/app/(app)/settings/actions"

await addCurrencyAction("user-uuid", {
  code: "BTC",
  name: "Bitcoin"
})
```

--------------------------------

### Backup and Restore Data with TypeScript

Source: https://context7.com/vas3k/taxhacker/llms.txt

This snippet demonstrates how to restore user data from a ZIP backup file using TypeScript. It utilizes a `restoreBackupAction` function and expects a FormData object containing the backup ZIP. The result indicates success and provides counters for restored data types.

```typescript
// Restore from backup ZIP file
import { restoreBackupAction } from "@/app/(app)/settings/backups/actions"

const formData = new FormData()
formData.append("file", backupZipFile) // ZIP file up to 256MB

const result = await restoreBackupAction(null, formData)
// Result: {
//   success: true,
//   data: {
//     counters: {
//       "categories.json": 5,
//       "projects.json": 3,
//       "transactions.json": 150,
//       "Uploaded attachments": 89
//     }
//   }
// }

// Backup ZIP structure:
// backup.zip
// ├── data/
// │   ├── metadata.json        # { version: "1.0", timestamp: "..." }
// │   ├── categories.json      # User categories
// │   ├── projects.json        # User projects
// │   ├── fields.json          # Custom fields
// │   ├── currencies.json      # User currencies
// │   ├── settings.json        # User settings
// │   ├── transactions.json    # All transactions
// │   ├── files.json           # File records
// │   └── uploads/             # Actual file attachments
// │       ├── 2024/01/...
// │       └── unsorted/...

```

--------------------------------

### Restart TaxHacker with Docker Compose

Source: https://github.com/vas3k/taxhacker/blob/main/docs/migrate-0.3-0.5.md

These shell commands are used to stop the current TaxHacker instance and restart it using Docker Compose, a necessary step before creating a data backup.

```bash
docker compose down
docker compose up -d
```

--------------------------------

### Settings Management API

Source: https://context7.com/vas3k/taxhacker/llms.txt

Provides server actions for managing various user settings including categories, projects, currencies, and custom fields.

```APIDOC
## Settings Management API

### Description
Manages user settings, including categories, projects, currencies, and custom fields via server actions.

### Method
POST (implied by server actions)

### Endpoint
`/settings/actions` (implied by server actions)

### Parameters
#### Request Body (General Settings)
- **prompt_analyse_new_file** (string) - Optional - Custom AI prompt for document analysis.
- **default_currency** (string) - Optional - The default currency code (e.g., "EUR").

### Request Example (General Settings)
```typescript
const settingsFormData = new FormData()
settingsFormData.append("prompt_analyse_new_file", "Custom AI prompt for document analysis...")
settingsFormData.append("default_currency", "EUR")

const result = await saveSettingsAction(null, settingsFormData)
```

### Response (General Settings)
#### Success Response (200)
- **success** (boolean) - Indicates if the settings were saved successfully.

#### Response Example (General Settings)
```json
{
  "success": true
}
```

## Category Management API

### Description
Allows adding, editing, and deleting transaction categories.

### Method
POST (implied by server actions)

### Endpoint
`/settings/actions` (implied by server actions)

### Parameters
#### Add Category
- **userId** (string) - Required - The ID of the user.
- **categoryData** (Object) - Required - Data for the new category.
  - **name** (string) - Required - The name of the category.
  - **llm_prompt** (string) - Optional - A prompt for AI analysis related to this category.
  - **color** (string) - Optional - A hex color code for the category.

### Request Example (Add Category)
```typescript
const newCategory = await addCategoryAction("user-uuid", {
  name: "Software Subscriptions",
  llm_prompt: "Software licenses and SaaS subscriptions",
  color: "#3B82F6"
})
```

#### Edit Category
- **userId** (string) - Required - The ID of the user.
- **categoryCode** (string) - Required - The code of the category to edit.
- **updatedCategoryData** (Object) - Required - The updated data for the category.

### Request Example (Edit Category)
```typescript
await editCategoryAction("user-uuid", "software-subscriptions", {
  name: "Software & SaaS",
  llm_prompt: "Software licenses, SaaS subscriptions, and digital tools"
})
```

#### Delete Category
- **userId** (string) - Required - The ID of the user.
- **categoryCode** (string) - Required - The code of the category to delete.

### Request Example (Delete Category)
```typescript
await deleteCategoryAction("user-uuid", "software-subscriptions")
```

### Response (Category Actions)
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **category** (Object) - The created or updated category object (for add/edit).
  - **code** (string) - The unique code for the category.

#### Response Example (Add Category)
```json
{
  "success": true,
  "category": {
    "code": "software-subscriptions",
    "name": "Software Subscriptions",
    "llm_prompt": "Software licenses and SaaS subscriptions",
    "color": "#3B82F6"
  }
}
```

## Project Management API

### Description
Allows adding and editing projects.

### Method
POST (implied by server actions)

### Endpoint
`/settings/actions` (implied by server actions)

### Parameters
#### Add Project
- **userId** (string) - Required - The ID of the user.
- **projectData** (Object) - Required - Data for the new project.
  - **name** (string) - Required - The name of the project.
  - **llm_prompt** (string) - Optional - A prompt for AI analysis related to this project.
  - **color** (string) - Optional - A hex color code for the project.

### Request Example (Add Project)
```typescript
const newProject = await addProjectAction("user-uuid", {
  name: "Client ABC",
  llm_prompt: "Expenses for Client ABC project",
  color: "#10B981"
})
```

#### Edit Project
- **userId** (string) - Required - The ID of the user.
- **projectCode** (string) - Required - The code of the project to edit.
- **updatedProjectData** (Object) - Required - The updated data for the project.

### Response (Project Actions)
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **project** (Object) - The created or updated project object.
  - **code** (string) - The unique code for the project.

## Custom Field Management API

### Description
Allows adding and editing custom fields for transactions.

### Method
POST (implied by server actions)

### Endpoint
`/settings/actions` (implied by server actions)

### Parameters
#### Add Custom Field
- **userId** (string) - Required - The ID of the user.
- **fieldData** (Object) - Required - Data for the new custom field.
  - **name** (string) - Required - The name of the custom field.
  - **type** (string) - Required - The data type of the field (e.g., "string").
  - **llm_prompt** (string) - Optional - A prompt for AI to extract this field.
  - **isVisibleInList** (boolean) - Optional - Whether the field is visible in the transaction list.
  - **isVisibleInAnalysis** (boolean) - Optional - Whether the field is visible during analysis.
  - **isRequired** (boolean) - Optional - Whether the field is required.

### Request Example (Add Custom Field)
```typescript
const customField = await addFieldAction("user-uuid", {
  name: "Invoice Number",
  type: "string",
  llm_prompt: "Extract the invoice or receipt number from the document",
  isVisibleInList: true,
  isVisibleInAnalysis: true,
  isRequired: false
})
```

#### Edit Custom Field
- **userId** (string) - Required - The ID of the user.
- **fieldCode** (string) - Required - The code of the custom field to edit.
- **updatedFieldData** (Object) - Required - The updated data for the custom field.

### Response (Custom Field Actions)
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **field** (Object) - The created or updated custom field object.
  - **code** (string) - The unique code for the custom field.
  - **isExtra** (boolean) - Indicates if this is an extra field.

#### Response Example (Add Custom Field)
```json
{
  "success": true,
  "field": {
    "code": "invoice-number",
    "name": "Invoice Number",
    "type": "string",
    "llm_prompt": "Extract the invoice or receipt number from the document",
    "isVisibleInList": true,
    "isVisibleInAnalysis": true,
    "isRequired": false,
    "isExtra": true
  }
}
```

## Currency Management API

### Description
Allows adding custom currency types.

### Method
POST (implied by server actions)

### Endpoint
`/settings/actions` (implied by server actions)

### Parameters
#### Add Currency
- **userId** (string) - Required - The ID of the user.
- **currencyData** (Object) - Required - Data for the new currency.
  - **code** (string) - Required - The currency code (e.g., "BTC").
  - **name** (string) - Required - The name of the currency (e.g., "Bitcoin").

### Request Example (Add Currency)
```typescript
await addCurrencyAction("user-uuid", {
  code: "BTC",
  name: "Bitcoin"
})
```

### Response (Currency Actions)
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
```

--------------------------------

### Query, Create, and Update Transactions (TypeScript)

Source: https://context7.com/vas3k/taxhacker/llms.txt

Provides functions for querying transactions with advanced filtering, sorting, and pagination. It also includes methods to programmatically create and update transaction records in the database. Dependencies include transaction models.

```typescript
// Query transactions with filters
import { getTransactions, getTransactionById } from "@/models/transactions"

// Get all transactions for a user with filters
const { transactions, total } = await getTransactions(
  "user-uuid",
  {
    search: "office supplies",
    dateFrom: "2024-01-01",
    dateTo: "2024-12-31",
    categoryCode: "office",
    projectCode: "startup-2024",
    type: "expense",
    ordering: "-issuedAt" // Prefix with - for descending
  },
  {
    limit: 20,
    offset: 0
  }
)
// Result: { transactions: [...], total: 150 }

// Get single transaction by ID
const transaction = await getTransactionById("transaction-uuid", "user-uuid")
// Result: { id: "...", name: "...", category: { ... }, project: { ... } }

// Create transaction programmatically
import { createTransaction, updateTransaction } from "@/models/transactions"

const newTransaction = await createTransaction("user-uuid", {
  name: "Cloud Hosting",
  merchant: "AWS",
  total: 9999,
  currencyCode: "USD",
  type: "expense",
  categoryCode: "infrastructure",
  issuedAt: new Date("2024-03-01"),
  note: "March hosting fees"
})

// Update transaction
const updated = await updateTransaction("transaction-uuid", "user-uuid", {
  note: "Updated: March hosting fees - production servers"
})

```

--------------------------------

### Currency Conversion API

Source: https://context7.com/vas3k/taxhacker/llms.txt

Fetches historical exchange rates for currency conversion using data from XE.com. The API caches results for 24 hours to optimize performance and supports 170+ world currencies plus cryptocurrencies.

```APIDOC
## GET /api/currency

### Description
Fetches historical exchange rates for currency conversion.

### Method
GET

### Endpoint
`/api/currency`

### Parameters
#### Query Parameters
- **from** (string) - Required - The source currency code (e.g., EUR).
- **to** (string) - Required - The target currency code (e.g., USD).
- **date** (string) - Required - The date for the exchange rate in `YYYY-MM-DD` format.

### Request Example
```bash
curl -X GET "http://localhost:7331/api/currency?from=EUR&to=USD&date=2024-01-15" \
  -H "Cookie: session=your-session-token"
```

### Response
#### Success Response (200)
- **rate** (number) - The historical exchange rate.
- **cached** (boolean) - Indicates if the data was served from cache.

#### Response Example
```json
{
  "rate": 1.0892,
  "cached": false
}
```

#### Error Response (400)
- **error** (string) - Description of the error, e.g., "Missing required parameters: from, to, date".

#### Error Response Example
```json
{
  "error": "Missing required parameters: from, to, date"
}
```
```

--------------------------------

### Handle File Uploads (TypeScript)

Source: https://context7.com/vas3k/taxhacker/llms.txt

Enables server actions for uploading receipt images and invoice documents. Files are stored in user-specific directories with automatic storage quota management. Supports uploading to an unsorted folder for AI processing or directly to a transaction.

```typescript
// Upload files to unsorted folder for AI processing
import { uploadFilesAction } from "@/app/(app)/files/actions"

const formData = new FormData()
formData.append("files", receiptFile1) // File object
formData.append("files", invoiceFile2) // Multiple files supported

const result = await uploadFilesAction(formData)
// Result: { success: true, error: null }

// Upload files directly to a transaction
import { uploadTransactionFilesAction } from "@/app/(app)/transactions/actions"

const txFormData = new FormData()
txFormData.append("transactionId", "transaction-uuid")
txFormData.append("files", attachmentFile)

const txResult = await uploadTransactionFilesAction(txFormData)
// Result: { success: true }

// Delete a file from a transaction
import { deleteTransactionFileAction } from "@/app/(app)/transactions/actions"

const deleteResult = await deleteTransactionFileAction(
  "transaction-uuid",
  "file-uuid"
)
// Result: { success: true, data: { ... } }
```

--------------------------------

### Analyze Document with AI and Save as Transaction (TypeScript)

Source: https://context7.com/vas3k/taxhacker/llms.txt

Analyzes an uploaded file using AI to extract financial data based on provided settings and field schemas. It then saves the analyzed data as a new transaction. Dependencies include AI analysis actions and transaction saving actions.

```typescript
// Analyze a file using AI
import { analyzeFileAction } from "@/app/(app)/unsorted/actions"
import type { File, Field, Category, Project } from "@/prisma/client"

const file: File = { /* file record from database */ }
const settings: Record<string, string> = {
  prompt_analyse_new_file: "Extract all financial data from this document..."
}
const fields: Field[] = [
  { code: "name", name: "Name", type: "string", llm_prompt: "Extract item name" },
  { code: "total", name: "Total", type: "number", llm_prompt: "Extract total amount" },
  // ... other fields
]
const categories: Category[] = [
  { code: "office", name: "Office Supplies", llm_prompt: "Office and stationery items" },
  { code: "travel", name: "Travel", llm_prompt: "Transportation and accommodation" }
]
const projects: Project[] = [
  { code: "startup-2024", name: "Startup 2024" }
]

const result = await analyzeFileAction(file, settings, fields, categories, projects)
// Result: {
//   success: true,
//   data: {
//     output: {
//       name: "Office Supplies Purchase",
//       merchant: "Staples",
//       total: "45.99",
//       currencyCode: "USD",
//       categoryCode: "office",
//       issuedAt: "2024-03-15"
//     },
//     tokensUsed: 1
//   }
// }

// Save analyzed file as a transaction
import { saveFileAsTransactionAction } from "@/app/(app)/unsorted/actions"

const saveFormData = new FormData()
saveFormData.append("fileId", "file-uuid")
saveFormData.append("name", "Office Supplies")
saveFormData.append("total", "4599")
saveFormData.append("currencyCode", "USD")
saveFormData.append("type", "expense")
saveFormData.append("categoryCode", "office")

const saveResult = await saveFileAsTransactionAction(null, saveFormData)
// Result: { success: true, data: { id: "new-transaction-uuid", ... } }

```

--------------------------------

### Adjust Body Size Limit in next.config.ts

Source: https://github.com/vas3k/taxhacker/blob/main/docs/migrate-0.3-0.5.md

This TypeScript code snippet shows how to modify the `bodySizeLimit` in the `next.config.ts` file. This is a workaround for potential file size errors when uploading large data archives during the restore process.

```typescript
bodySizeLimit: "256mb"
```

--------------------------------

### Import Transactions from CSV using TypeScript

Source: https://context7.com/vas3k/taxhacker/llms.txt

Parses a CSV file and imports transactions. It involves two main steps: parsing the CSV to preview data and then saving the parsed transactions. Requires `parseCSVAction` and `saveTransactionsAction` from '@/app/(app)/import/csv/actions'.

```typescript
// Parse CSV file
import { parseCSVAction, saveTransactionsAction } from "@/app/(app)/import/csv/actions"

// Step 1: Parse CSV to preview data
const parseFormData = new FormData()
parseFormData.append("file", csvFile) // File object

const parseResult = await parseCSVAction(null, parseFormData)
// Result: {
//   success: true,
//   data: [
//     ["Date", "Description", "Amount", "Category"],
//     ["2024-03-15", "Office Supplies", "45.99", "Office"],
//     ["2024-03-16", "Client Lunch", "89.50", "Meals"]
//   ]
// }

// Step 2: Save parsed transactions
const rows = [
  { name: "Office Supplies", total: 4599, issuedAt: "2024-03-15", categoryCode: "office" },
  { name: "Client Lunch", total: 8950, issuedAt: "2024-03-16", categoryCode: "meals" }
]

const saveFormData = new FormData()
saveFormData.append("rows", JSON.stringify(rows))

const saveResult = await saveTransactionsAction(null, saveFormData)
// Result: { success: true }
```

--------------------------------

### Manage Financial Transactions (TypeScript)

Source: https://context7.com/vas3k/taxhacker/llms.txt

Provides server actions for creating, updating, and deleting financial transactions. Operations are user-scoped and trigger automatic revalidation of the transactions page cache. Amounts should be provided in cents.

```typescript
// Create a new transaction
import { createTransactionAction } from "@/app/(app)/transactions/actions"

const formData = new FormData()
formData.append("name", "Office Supplies")
formData.append("merchant", "Staples")
formData.append("total", "4599") // Amount in cents
formData.append("currencyCode", "USD")
formData.append("type", "expense")
formData.append("categoryCode", "office")
formData.append("projectCode", "startup-2024")
formData.append("issuedAt", "2024-03-15")

const result = await createTransactionAction(null, formData)
// Result: { success: true, data: { id: "uuid", name: "Office Supplies", ... } }

// Update existing transaction
import { saveTransactionAction } from "@/app/(app)/transactions/actions"

formData.append("transactionId", "existing-transaction-uuid")
formData.append("note", "Q1 office supplies purchase")

const updateResult = await saveTransactionAction(null, formData)
// Result: { success: true, data: { id: "uuid", note: "Q1 office supplies purchase", ... } }

// Delete a transaction (also deletes associated files)
import { deleteTransactionAction } from "@/app/(app)/transactions/actions"

const deleteResult = await deleteTransactionAction(null, "transaction-uuid")
// Result: { success: true, data: { id: "transaction-uuid", ... } }

// Bulk delete multiple transactions
import { bulkDeleteTransactionsAction } from "@/app/(app)/transactions/actions"

const bulkResult = await bulkDeleteTransactionsAction([
  "transaction-uuid-1",
  "transaction-uuid-2",
  "transaction-uuid-3"
])
// Result: { success: true }
```

--------------------------------

### File Upload Actions

Source: https://context7.com/vas3k/taxhacker/llms.txt

Server actions for uploading receipt images and invoice documents. Files are stored in user-specific directories with automatic storage quota management.

```APIDOC
## File Upload Server Actions

### Description
Provides server actions for uploading and managing files associated with transactions.

### Actions

#### Upload Files (Unsorted)
Uploads files to an unsorted folder for AI processing.

**Usage:**
```typescript
import { uploadFilesAction } from "@/app/(app)/files/actions"

const formData = new FormData()
formData.append("files", receiptFile1) // File object
formData.append("files", invoiceFile2) // Multiple files supported

const result = await uploadFilesAction(formData)
// Result: { success: true, error: null }
```

#### Upload Files to Transaction
Uploads files directly and associates them with a specific transaction.

**Usage:**
```typescript
import { uploadTransactionFilesAction } from "@/app/(app)/transactions/actions"

const txFormData = new FormData()
txFormData.append("transactionId", "transaction-uuid")
txFormData.append("files", attachmentFile)

const txResult = await uploadTransactionFilesAction(txFormData)
// Result: { success: true }
```

#### Delete Transaction File
Deletes a specific file associated with a transaction.

**Usage:**
```typescript
import { deleteTransactionFileAction } from "@/app/(app)/transactions/actions"

const deleteResult = await deleteTransactionFileAction(
  "transaction-uuid",
  "file-uuid"
)
// Result: { success: true, data: { ... } }
```

### Parameters
- **files** (File object or Array<File>) - Required - The file(s) to upload.
- **transactionId** (string) - Required for `uploadTransactionFilesAction` - The ID of the transaction to associate the files with.
- **transactionId** (string) - Required for `deleteTransactionFileAction` - The ID of the transaction the file belongs to.
- **fileId** (string) - Required for `deleteTransactionFileAction` - The ID of the file to delete.
```

--------------------------------

### CSV Import API

Source: https://context7.com/vas3k/taxhacker/llms.txt

Handles the parsing and importing of transactions from CSV files, including support for field mapping.

```APIDOC
## CSV Import API

### Description
Parses and imports transactions from CSV files with field mapping support.

### Method
POST (implied by server actions)

### Endpoint
`/import/csv` (implied by server actions)

### Parameters
#### Request Body
- **file** (File) - Required - The CSV file to import.

### Request Example
```typescript
const parseFormData = new FormData()
parseFormData.append("file", csvFile) // File object

const parseResult = await parseCSVAction(null, parseFormData)
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (Array<Array<string>>) - The parsed data from the CSV file, including headers.

#### Response Example
```json
{
  "success": true,
  "data": [
    ["Date", "Description", "Amount", "Category"],
    ["2024-03-15", "Office Supplies", "45.99", "Office"],
    ["2024-03-16", "Client Lunch", "89.50", "Meals"]
  ]
}
```

## Save Imported Transactions API

### Description
Saves the transactions that have been parsed from a CSV file.

### Method
POST (implied by server actions)

### Endpoint
`/import/save` (implied by server actions)

### Parameters
#### Request Body
- **rows** (Array<Object>) - Required - An array of transaction objects to save.
  - **name** (string) - The name of the transaction.
  - **total** (number) - The total amount of the transaction.
  - **issuedAt** (string) - The date the transaction was issued.
  - **categoryCode** (string) - The code of the category associated with the transaction.

### Request Example
```typescript
const rows = [
  { name: "Office Supplies", total: 4599, issuedAt: "2024-03-15", categoryCode: "office" },
  { name: "Client Lunch", total: 8950, issuedAt: "2024-03-16", categoryCode: "meals" }
]
const saveFormData = new FormData()
saveFormData.append("rows", JSON.stringify(rows))

const saveResult = await saveTransactionsAction(null, saveFormData)
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the transactions were saved successfully.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Upgrade Docker Compose to Latest TaxHacker Version

Source: https://github.com/vas3k/taxhacker/blob/main/docs/migrate-0.3-0.5.md

This YAML snippet demonstrates how to update the Docker Compose configuration to the latest version of TaxHacker, preparing the instance for data restoration.

```yaml
services:
  app:
    image: ghcr.io/vas3k/taxhacker:latest
    ports:
      - "7331:7331"
      
// everything else stays the same
```

--------------------------------

### Transaction Management Actions

Source: https://context7.com/vas3k/taxhacker/llms.txt

Server actions for creating, updating, and deleting financial transactions. All operations are user-scoped and automatically revalidate the transactions page cache.

```APIDOC
## Transaction Management Server Actions

### Description
Provides server actions for managing financial transactions, including creation, updates, and deletion.

### Actions

#### Create Transaction
Creates a new financial transaction.

**Usage:**
```typescript
import { createTransactionAction } from "@/app/(app)/transactions/actions"

const formData = new FormData()
formData.append("name", "Office Supplies")
formData.append("merchant", "Staples")
formData.append("total", "4599") // Amount in cents
formData.append("currencyCode", "USD")
formData.append("type", "expense")
formData.append("categoryCode", "office")
formData.append("projectCode", "startup-2024")
formData.append("issuedAt", "2024-03-15")

const result = await createTransactionAction(null, formData)
// Result: { success: true, data: { id: "uuid", name: "Office Supplies", ... } }
```

#### Update Transaction
Updates an existing financial transaction.

**Usage:**
```typescript
import { saveTransactionAction } from "@/app/(app)/transactions/actions"

const formData = new FormData()
formData.append("transactionId", "existing-transaction-uuid")
formData.append("note", "Q1 office supplies purchase")

const updateResult = await saveTransactionAction(null, formData)
// Result: { success: true, data: { id: "uuid", note: "Q1 office supplies purchase", ... } }
```

#### Delete Transaction
Deletes a specific transaction and its associated files.

**Usage:**
```typescript
import { deleteTransactionAction } from "@/app/(app)/transactions/actions"

const deleteResult = await deleteTransactionAction(null, "transaction-uuid")
// Result: { success: true, data: { id: "transaction-uuid", ... } }
```

#### Bulk Delete Transactions
Deletes multiple transactions simultaneously.

**Usage:**
```typescript
import { bulkDeleteTransactionsAction } from "@/app/(app)/transactions/actions"

const bulkResult = await bulkDeleteTransactionsAction([
  "transaction-uuid-1",
  "transaction-uuid-2",
  "transaction-uuid-3"
])
// Result: { success: true }
```

### Parameters (for Create/Update)
- **name** (string) - Required - The name of the transaction.
- **merchant** (string) - Required - The merchant where the transaction occurred.
- **total** (string) - Required - The total amount of the transaction in cents.
- **currencyCode** (string) - Required - The currency code (e.g., USD).
- **type** (string) - Required - The type of transaction (e.g., 'expense', 'income').
- **categoryCode** (string) - Required - The code for the transaction category.
- **projectCode** (string) - Optional - The code for the associated project.
- **issuedAt** (string) - Required - The date the transaction was issued in `YYYY-MM-DD` format.
- **transactionId** (string) - Required for update actions - The ID of the transaction to update.
- **note** (string) - Optional - Additional notes for the transaction.
```

--------------------------------

### Export Transactions using cURL

Source: https://context7.com/vas3k/taxhacker/llms.txt

Exports transactions in CSV or ZIP format. Supports filtering by date range, category, project, and type. Can optionally include file attachments. Requires authentication via a session cookie.

```bash
# Export transactions as CSV
curl -X GET "http://localhost:7331/export/transactions?fields=name,total,currencyCode,issuedAt,categoryCode&dateFrom=2024-01-01&dateTo=2024-12-31" \
  -H "Cookie: session=your-session-token" \
  -o transactions.csv

# Export with attachments as ZIP
curl -X GET "http://localhost:7331/export/transactions?fields=name,total,currencyCode,issuedAt&includeAttachments=true&progressId=optional-progress-uuid" \
  -H "Cookie: session=your-session-token" \
  -o transactions.zip

# Filter by category and project
curl -X GET "http://localhost:7331/export/transactions?fields=name,total&categoryCode=office&projectCode=startup-2024&type=expense" \
  -H "Cookie: session=your-session-token" \
  -o filtered_transactions.csv
```

--------------------------------

### Update Docker Compose to TaxHacker v0.3.0

Source: https://github.com/vas3k/taxhacker/blob/main/docs/migrate-0.3-0.5.md

This YAML snippet shows how to update the Docker Compose configuration to use the TaxHacker v0.3.0 image, which is the version required before migrating data to Postgres.

```yaml
services:
  app:
    image: ghcr.io/vas3k/taxhacker:v0.3.0
    ports:
      - "7331:7331"
      
// everything else stays the same
```

--------------------------------

### Split Multi-Item Invoice into Separate Transactions (TypeScript)

Source: https://context7.com/vas3k/taxhacker/llms.txt

Splits a single invoice containing multiple items into separate transactions. Each new transaction will have a copy of the original document and pre-populated item data. This function requires a list of transaction items and the original file ID.

```typescript
// Split a multi-item invoice into separate transactions
import { splitFileIntoItemsAction } from "@/app/(app)/unsorted/actions"
import type { TransactionData } from "@/models/transactions"

const items: TransactionData[] = [
  {
    name: "Laptop Stand",
    merchant: "Amazon",
    total: 4999,
    currencyCode: "USD",
    type: "expense",
    categoryCode: "equipment"
  },
  {
    name: "USB-C Hub",
    merchant: "Amazon",
    total: 2999,
    currencyCode: "USD",
    type: "expense",
    categoryCode: "equipment"
  }
]

const formData = new FormData()
formData.append("fileId", "original-file-uuid")
formData.append("items", JSON.stringify(items))

const result = await splitFileIntoItemsAction(null, formData)
// Result: { success: true }
// Creates two new files in unsorted, each pre-populated with item data

```

--------------------------------

### Transaction Export API

Source: https://context7.com/vas3k/taxhacker/llms.txt

Exports transaction data in CSV or ZIP format, with options for including attachments and filtering by date or category.

```APIDOC
## Transaction Export API

### Description
Exports transactions to CSV or ZIP format with optional file attachments and filtering capabilities.

### Method
GET

### Endpoint
`/export/transactions`

### Parameters
#### Query Parameters
- **fields** (string) - Required - Comma-separated list of fields to include in the export (e.g., `name,total,currencyCode,issuedAt,categoryCode`).
- **dateFrom** (string) - Optional - Start date for filtering transactions (YYYY-MM-DD).
- **dateTo** (string) - Optional - End date for filtering transactions (YYYY-MM-DD).
- **includeAttachments** (boolean) - Optional - If true, includes attachments in the export (results in ZIP format).
- **progressId** (string) - Optional - A UUID for tracking the export progress.
- **categoryCode** (string) - Optional - Filters transactions by a specific category code.
- **projectCode** (string) - Optional - Filters transactions by a specific project code.
- **type** (string) - Optional - Filters transactions by type (e.g., `expense`).

### Request Example
```bash
# Export transactions as CSV
curl -X GET "http://localhost:7331/export/transactions?fields=name,total,currencyCode,issuedAt,categoryCode&dateFrom=2024-01-01&dateTo=2024-12-31" \
  -H "Cookie: session=your-session-token" \
  -o transactions.csv

# Export with attachments as ZIP
curl -X GET "http://localhost:7331/export/transactions?fields=name,total,currencyCode,issuedAt&includeAttachments=true&progressId=optional-progress-uuid" \
  -H "Cookie: session=your-session-token" \
  -o transactions.zip

# Filter by category and project
curl -X GET "http://localhost:7331/export/transactions?fields=name,total&categoryCode=office&projectCode=startup-2024&type=expense" \
  -H "Cookie: session=your-session-token" \
  -o filtered_transactions.csv
```

### Response
#### Success Response (200)
- The response will be a file download (CSV or ZIP) based on the `includeAttachments` parameter and query options.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.