TaxApex Node.js SDK

Official Node.js/TypeScript client library for the TaxApex Tax Notice Management API.

Installation

npm install @taxapex/sdk
# or
yarn add @taxapex/sdk
# or
pnpm add @taxapex/sdk

Quick Start

import { TaxApexClient } from '@taxapex/sdk';

// Initialize the client
const client = new TaxApexClient({ apiKey: 'your-api-key' });

// Extract data from a tax notice
const result = await client.extract.fromFile('notice.pdf');
console.log(`Notice Type: ${result.noticeType}`);
console.log(`Amount Due: $${result.amountDue}`);
console.log(`Due Date: ${result.dueDate}`);

Features

Document Extraction

Extract structured data from IRS and state tax notices:

// From a local file
const result = await client.extract.fromFile('cp2000_notice.pdf');

// From a buffer
import * as fs from 'fs';
const buffer = fs.readFileSync('notice.pdf');
const result = await client.extract.fromBuffer(buffer, 'notice.pdf');

// From a URL
const result = await client.extract.fromUrl({
  url: 'https://example.com/notice.pdf',
  documentType: 'CP2000',
});

// Access extracted data
console.log(`Notice Type: ${result.noticeType}`);
console.log(`Issuing Agency: ${result.issuingAgency}`);
console.log(`Amount Due: $${result.amountDue}`);
console.log(`Due Date: ${result.dueDate?.toLocaleDateString()}`);
console.log(`Taxpayer: ${result.taxpayerName}`);
console.log(`Tax Year: ${result.taxYear}`);
console.log(`Confidence: ${(result.confidenceScore * 100).toFixed(1)}%`);

Audit Risk Analysis

Analyze audit risk for clients:

// Analyze audit risk
const risk = await client.auditRisk.analyze({
  clientId: 'client-12345',
  taxYear: 2023,
  incomeData: {
    wages: 150000,
    selfEmployment: 50000,
    investments: 25000,
    rental: 12000,
  },
  deductionData: {
    mortgageInterest: 18000,
    stateTaxes: 10000,
    charitable: 15000,
    homeOffice: 5000,
  },
  industry: 'technology',
});

// Review results
console.log(`Overall Risk Score: ${risk.overallScore}/100`);
console.log(`Risk Level: ${risk.riskLevel}`);
console.log('\nCategory Scores:');
console.log(`  Income: ${risk.incomeScore}/100`);
console.log(`  Deductions: ${risk.deductionsScore}/100`);
console.log(`  Credits: ${risk.creditsScore}/100`);
console.log(`  Compliance: ${risk.complianceScore}/100`);

console.log('\nRisk Factors:');
for (const factor of risk.riskFactors) {
  console.log(`  - ${factor.description} (${factor.severity})`);
}

console.log('\nRecommendations:');
for (const rec of risk.recommendations) {
  console.log(`  - ${rec}`);
}

Semantic Search

Search across your document repository:

// Search documents
const results = await client.search.query({
  query: 'IRS penalty abatement procedures',
  documentType: 'IRS_NOTICE',
  limit: 5,
  minSimilarity: 0.7,
});

console.log(`Found ${results.totalResults} results:`);
for (const item of results.results) {
  console.log(`\n${item.title}`);
  console.log(`  Similarity: ${(item.similarityScore * 100).toFixed(1)}%`);
  console.log(`  Snippet: ${item.contentSnippet.slice(0, 100)}...`);
}

// Index a new document
await client.search.indexDocument({
  documentId: 'doc-123',
  content: 'Full text content of the document...',
  title: 'CP2000 Response Letter',
  documentType: 'RESPONSE_LETTER',
  taxYear: 2023,
});

Tax Research

Get AI-powered answers to tax questions:

// Research a tax question
const result = await client.research.query({
  question: 'What are the requirements for claiming the home office deduction?',
  includeCitations: true,
  maxSources: 5,
});

console.log(`Answer:\n${result.answer}`);
console.log(`\nConfidence: ${(result.confidence * 100).toFixed(1)}%`);
console.log('\nSources:');
for (const source of result.sources) {
  console.log(`  - ${source.title}`);
  console.log(`    ${source.url}`);
}

Usage Statistics

Monitor your API usage:

const usage = await client.getUsage();

console.log(`Billing Period: ${usage.periodStart.toLocaleDateString()} to ${usage.periodEnd.toLocaleDateString()}`);
console.log(`Document Extractions: ${usage.documentExtractions}`);
console.log(`AI Analysis Calls: ${usage.aiAnalysisCalls}`);
console.log(`Search Queries: ${usage.searchQueries}`);
console.log(`Audit Risk Assessments: ${usage.auditRiskAssessments}`);
console.log(`Total API Calls: ${usage.totalApiCalls}`);

Configuration

Environment Variables

export TAXAPEX_API_KEY="your-api-key"
export TAXAPEX_BASE_URL="https://api.taxapex.com/v1"  # Optional

Client Options

const client = new TaxApexClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.taxapex.com/v1',  // Custom API URL
  timeout: 120000,  // Request timeout in milliseconds
  maxRetries: 5,    // Retry attempts for failed requests
  retryDelay: 2000, // Base delay between retries in ms
});

Error Handling

import {
  TaxApexClient,
  TaxApexError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  NotFoundError,
} from '@taxapex/sdk';

try {
  const result = await client.extract.fromFile('notice.pdf');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof ValidationError) {
    console.error(`Invalid request: ${error.message}`);
  } else if (error instanceof NotFoundError) {
    console.error('Resource not found');
  } else if (error instanceof TaxApexError) {
    console.error(`API error: ${error.message} (status: ${error.statusCode})`);
  }
}

TypeScript Support

This SDK is written in TypeScript and provides full type definitions:

import type {
  ExtractionResult,
  AuditRiskAssessment,
  SearchResult,
  ResearchResult,
  UsageStats,
} from '@taxapex/sdk';

import { NoticeType, RiskLevel } from '@taxapex/sdk';

// Types are fully available
const handleResult = (result: ExtractionResult) => {
  if (result.noticeType === NoticeType.CP2000) {
    // Handle CP2000 notice
  }
};

const handleRisk = (assessment: AuditRiskAssessment) => {
  if (assessment.riskLevel === RiskLevel.HIGH) {
    // Handle high risk
  }
};

Data Models

ExtractionResult

| Field | Type | Description | |-------|------|-------------| | id | string | Unique extraction ID | | noticeType | NoticeType | Type of notice (CP2000, CP501, etc.) | | issuingAgency | string | IRS or state agency | | noticeDate | Date | Date on the notice | | dueDate | Date | Response due date | | amountDue | number | Amount owed | | taxpayerName | string | Taxpayer name | | taxpayerId | string | SSN/EIN (masked) | | taxYear | number | Tax year | | fields | ExtractedField[] | All extracted fields | | confidenceScore | number | Extraction confidence (0-1) |

AuditRiskAssessment

| Field | Type | Description | |-------|------|-------------| | id | string | Assessment ID | | clientId | string | Client identifier | | taxYear | number | Tax year analyzed | | overallScore | number | Overall risk score (0-100) | | riskLevel | RiskLevel | low, medium, high, critical | | incomeScore | number | Income risk score | | deductionsScore | number | Deductions risk score | | creditsScore | number | Credits risk score | | complianceScore | number | Compliance risk score | | riskFactors | RiskFactor[] | Identified risk factors | | recommendations | string[] | Mitigation recommendations |

Support

• Documentation: https://docs.taxapex.com
• Email: [email protected]
• GitHub Issues: https://github.com/innorve/taxapex-node/issues

License

MIT License - see LICENSE file for details.