@kypacs/sdk

TypeScript SDK for the PaciKYC API — typed methods for KYC/KYB verification, AML screening, and compliance management.

Installation

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

Quick Start

import { PaciKycClient } from '@kypacs/sdk';

const client = new PaciKycClient({
  apiKey: 'pk_live_xxx',
  baseUrl: 'https://api.pacikyc.com', // Optional, this is the default
});

// Create a verification
const verification = await client.verifications.create({
  type: 'INDIVIDUAL',
  applicantData: {
    firstName: 'Jane',
    lastName: 'Doe',
    dateOfBirth: '1990-01-01',
  },
});

// Run a sanctions screening
const screening = await client.screenings.create({
  queryData: { name: 'Jane Doe', dateOfBirth: '1990-01-01' },
});

// List open cases
const cases = await client.cases.list({ status: 'OPEN' });

Authentication

All API requests require an API key. You can create API keys in the PaciKYC dashboard under Settings → API Keys.

const client = new PaciKycClient({
  apiKey: 'pk_live_xxx', // Your API key
});

API keys prefixed with pk_test_ are for the sandbox environment. Keys prefixed with pk_live_ are for production.

Configuration

import { PaciKycClient } from '@kypacs/sdk';
import type { PaciKycClientConfig } from '@kypacs/sdk';

const config: PaciKycClientConfig = {
  apiKey: 'pk_live_xxx',       // Required
  baseUrl: 'https://api.pacikyc.com', // Default
  timeout: 30000,              // Request timeout (ms), default: 30000
  retries: 2,                  // Auto-retry on 5xx/network errors, default: 2
  retryDelay: 1000,            // Base delay between retries (ms), default: 1000
  onError: (error) => {        // Global error handler
    console.error(`PaciKYC error: ${error.code}`, error.message);
  },
};

const client = new PaciKycClient(config);

Error Handling

The SDK maps API errors to typed error classes:

import {
  PaciKycError,
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  PlanLimitError,
  ServerError,
} from '@kypacs/sdk';

try {
  await client.verifications.get('non-existent-id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Verification not found');
  } else if (error instanceof ValidationError) {
    console.log('Validation errors:', error.fieldErrors);
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited, retry after ${error.retryAfter}s`);
  } else if (error instanceof PaciKycError) {
    console.log(`Error ${error.statusCode}: ${error.message}`);
    console.log(`Request ID: ${error.requestId}`); // For support queries
  }
}

| Error Class | HTTP Status | Description | |---|---|---| | AuthenticationError | 401 | Invalid or missing API key | | PlanLimitError | 402 | Plan limit exceeded | | AuthorizationError | 403 | Insufficient permissions | | NotFoundError | 404 | Resource not found | | ValidationError | 400/422 | Invalid request data | | RateLimitError | 429 | Too many requests | | ServerError | 5xx | Server error (auto-retried) |

Webhook Signature Verification

Verify incoming webhook payloads without instantiating a client:

import { verifyWebhookSignature } from '@kypacs/sdk';

// In your webhook handler:
const isValid = verifyWebhookSignature({
  payload: rawRequestBody,
  signature: req.headers['x-pacikyc-signature'],
  timestamp: req.headers['x-pacikyc-timestamp'],
  secret: 'whsec_xxx',     // Your webhook signing secret
  tolerance: 300,            // Max age in seconds (default: 5 minutes)
});

if (!isValid) {
  return res.status(401).json({ error: 'Invalid signature' });
}

Pagination

Manual Pagination

const page1 = await client.verifications.list({ page: 1, limit: 20 });
console.log(page1.data);       // Verification[]
console.log(page1.meta.total); // Total count
console.log(page1.meta.totalPages);

Auto-Pagination

Iterate through all pages automatically using async iterators:

for await (const verification of client.verifications.listAll({ status: 'APPROVED' })) {
  console.log(verification.id);
}

// Also available on screenings, cases, businesses, transactions, transactionMonitoring,
// sar, and monitoring.listAllAlerts / monitoring.listAllExpiringDocuments:
for await (const screening of client.screenings.listAll()) {
  console.log(screening.id);
}

API Reference

Verifications

client.verifications.create(data)              // Create a new verification
client.verifications.get(id)                   // Get verification details
client.verifications.list(params?)             // List verifications (paginated)
client.verifications.update(id, data)          // Update a verification
client.verifications.submit(id)                // Submit for review
client.verifications.decide(id, data)          // Approve or reject
client.verifications.createInviteLink(id)      // Generate an invite link
client.verifications.listAll(params?)          // Auto-paginate all results

Documents

client.documents.requestUploadUrl(data)        // Get a pre-signed upload URL
client.documents.confirmUpload(id)             // Confirm upload completed
client.documents.getDownloadUrl(id)            // Get a pre-signed download URL
client.documents.get(id)                       // Get document metadata
client.documents.list({ verificationId })      // List documents for a verification
client.documents.delete(id)                    // Delete a document

Screenings

client.screenings.create(data)                 // Create a screening
client.screenings.createBatch(data)            // Batch screening
client.screenings.get(id)                      // Get screening details
client.screenings.list(params?)                // List screenings (paginated)
client.screenings.review(id, data)             // Review a match
client.screenings.getMatchDetails(id, entityId) // Get entity match details
client.screenings.listAll(params?)             // Auto-paginate all results

Cases

client.cases.get(id)                           // Get case details
client.cases.list(params?)                     // List cases (paginated)
client.cases.assign(id, data)                  // Assign a case
client.cases.addNote(id, data)                 // Add a note
client.cases.escalate(id, data)                // Escalate a case
client.cases.resolve(id, data)                 // Resolve a case
client.cases.getStats()                        // Get case statistics
client.cases.listAll(params?)                  // Auto-paginate all results

Businesses

client.businesses.search(data)                 // Search business registries
client.businesses.create(data)                 // Create a business entity
client.businesses.get(id)                      // Get business details
client.businesses.list(params?)                // List businesses (paginated)
client.businesses.addUbo(id, data)             // Add a beneficial owner
client.businesses.verifyUbo(id, uboId)         // Verify a beneficial owner
client.businesses.listAll(params?)             // Auto-paginate all results

Webhooks

client.webhooks.create(data)                   // Create a webhook endpoint
client.webhooks.list()                         // List all webhook endpoints
client.webhooks.update(id, data)               // Update a webhook endpoint
client.webhooks.delete(id)                     // Delete a webhook endpoint
client.webhooks.test(id)                       // Send a test event

Tenants

client.tenants.create(data)                    // Create a tenant (super admin)
client.tenants.get(id)                         // Get tenant details
client.tenants.list(params?)                   // List tenants
client.tenants.update(id, data)                // Update tenant settings

Users

client.users.create(data)                      // Invite a user
client.users.get(id)                           // Get user details
client.users.list(params?)                     // List users
client.users.update(id, data)                  // Update user role/status
client.users.delete(id)                        // Remove a user

Reports

client.reports.getVerificationReport(params?)         // Verification statistics
client.reports.getScreeningReport(params?)             // Screening match statistics
client.reports.getComplianceReport(params?)            // Case management statistics
client.reports.getUsageMetrics(params?)                // Phase 2 usage metrics
client.reports.getFullReport(params?)                  // Combined compliance report

Report parameters accept optional dateFrom and dateTo (ISO 8601 strings) for filtering by date range.

Billing

client.billing.getSubscription()               // Get current subscription
client.billing.getUsage()                      // Get usage summary
client.billing.getInvoices()                   // List invoices
client.billing.createCheckoutSession(data)     // Start a checkout flow
client.billing.createPortalSession()           // Open the billing portal

Transactions (AML transaction monitoring)

client.transactions.ingestBatch(data)          // Submit a batch of transactions for monitoring
client.transactions.getBatchStatus(batchId)    // Poll batch processing status
client.transactions.list(params?)              // List transactions (paginated)
client.transactions.get(id)                    // Get a transaction with its alerts
client.transactions.listAll(params?)           // Auto-paginate all results

Transaction-Monitoring Alerts

client.transactionMonitoring.list(params?)             // List alerts (paginated)
client.transactionMonitoring.get(id)                   // Get alert detail
client.transactionMonitoring.updateStatus(id, data)    // Transition (INVESTIGATING / CLOSED_FALSE_POSITIVE / ESCALATED_TO_SAR)
client.transactionMonitoring.listAll(params?)          // Auto-paginate all results

Ongoing Monitoring (re-screening & document expiry)

client.monitoring.getStatus()                          // Re-screening config + aggregate counts
client.monitoring.triggerRescreening()                 // Manually enqueue a re-screening run
client.monitoring.listExpiringDocuments(params?)       // Documents approaching expiry (paginated)
client.monitoring.listAlerts(params?)                  // Monitoring alerts (paginated)
client.monitoring.acknowledgeAlert(id)                 // Acknowledge a monitoring alert
client.monitoring.listAllAlerts(params?)               // Auto-paginate alerts
client.monitoring.listAllExpiringDocuments(params?)    // Auto-paginate expiring documents

SAR (Suspicious Activity Reports)

client.sar.create(data)                        // Create a draft SAR from a case
client.sar.list(params?)                       // List SARs (paginated)
client.sar.get(id)                             // Get a SAR
client.sar.updateNarrative(id, data)           // Update narrative (DRAFT / REJECTED only)
client.sar.submit(id)                          // Finalise — generates goAML XML + PDF exports
client.sar.getDownload(id, 'xml' | 'pdf')      // Pre-signed download URL for the submitted export
client.sar.preview(id, 'xml' | 'pdf')          // Pre-signed preview URL (no state change)
client.sar.updateSubmissionRef(id, data)       // Record/amend the FIU submission reference
client.sar.acknowledge(id, data?)              // Mark as ACKNOWLEDGED by the FIU
client.sar.reject(id, data?)                   // Record an FIU rejection (re-editable)
client.sar.listAll(params?)                    // Auto-paginate all results

Compliance Rules & Verification Sequences

client.rules.get(jurisdiction?)                // Effective rules (defaults + overrides)
client.rules.update(data)                      // Patch the tenant compliance-rules config
client.rules.listJurisdictions()               // Supported jurisdictions + EDD triggers
client.rules.getCountryRisk()                  // Country risk-rating table
client.rules.listDefaultSequences()            // Built-in default verification sequences
client.rules.getSequenceConfig()               // Tenant verification-sequence config
client.rules.updateSequenceConfig(data)        // Patch the tenant verification-sequence config
client.rules.resolveSequence({ jurisdiction, type? }) // Resolve the effective sequence
client.rules.getExecutionSummary(verificationId)      // Sequence execution trail for a verification

TypeScript Types

All request/response types are exported:

import type {
  Verification,
  VerificationDetail,
  CreateVerificationInput,
  Screening,
  Case,
  BusinessEntity,
  Transaction,
  TmAlert,
  MonitoringStatus,
  Sar,
  ComplianceRules,
  PaginatedList,
} from '@kypacs/sdk';

SDK Generation

Types are generated from the running API's OpenAPI specification:

# Requires the API server to be running with Swagger enabled
bash infrastructure/scripts/generate-sdk.sh

# Or via Turborepo
turbo generate-sdk --filter=@kypacs/sdk