SDKs and External Integration Surface - Node SDK Client, Shared Types, and Resource Wrappers
Overview
The Node SDK is the official programmatic entry point for the Lita API. It gives application code a single Lita client that fans out into region-aware resource wrappers for consent management, feature computation, evidence retrieval, and async job status polling, while preserving the same JSON shapes exposed by the REST API.
The package is API-first and thin by design: the resource classes delegate directly to a shared HttpClient, the transport injects the required auth and request-tracing headers, and the public type surface mirrors the wire format used by the regional endpoints. Webhook verification is handled separately through constructEvent, which validates the X-Lita-Signature header before parsing webhook payloads into the shared WebhookEvent type.
Package Surface
index.ts package entry
sdks/node/src/index.ts
The entry point exposes the public client, error classes, webhook helper, and the shared type contracts used across the SDK.
| Export | Kind | Responsibility |
|---|---|---|
Lita |
default class | Constructs the shared transport and resource wrappers |
constructEvent |
function | Verifies and parses webhook payloads |
LitaError |
error class | Base API error type |
LitaAuthError |
error class | Authentication and authorization failures |
LitaNotFoundError |
error class | Missing resource failures |
LitaRateLimitError |
error class | Rate limit failures with retry hints |
LitaWebhookSignatureError |
error class | Invalid webhook signature failures |
| type exports | type aliases and interfaces | Shared request, response, and event contracts |
The intended usage pattern is the default export plus resource accessors:
import Lita from '@lita/node';
const lita = new Lita({ apiKey: process.env.LITA_API_KEY!, region: 'us' });
const consent = await lita.consents.create({
applicant_id: 'app_demo_001',
purpose: 'LENDING_UNDERWRITING',
data_categories: ['transactions', 'income', 'payment_behavior'],
expires_in_days: 30,
});
const score = await lita.consents.getScore(consent.consent_id);
Architecture Overview
flowchart TB
subgraph NodeSDK [Node SDK]
Entry[Lita client]
Consents[ConsentsResource]
Features[FeaturesResource]
Evidence[EvidenceResource]
Status[StatusResource]
Http[HttpClient]
Webhooks[constructEvent]
Types[Shared types]
Entry --> Consents
Entry --> Features
Entry --> Evidence
Entry --> Status
Consents --> Http
Features --> Http
Evidence --> Http
Status --> Http
Entry --> Types
Consents --> Types
Features --> Types
Evidence --> Types
Status --> Types
Webhooks --> Types
end
subgraph LitaAPI [Lita regional REST API]
API[Regional REST resources]
end
Http --> API
Client Construction and Request Lifecycle
The public client is a composition root:
new Lita(options)creates a singleHttpClient.- The same
HttpClientinstance is injected intoConsentsResource,FeaturesResource,EvidenceResource, andStatusResource. - Each resource method forwards directly to the transport with a relative path and typed request or response contract.
HttpClientbuilds the final URL from the configured base URL, region, and optional sandbox prefix.- The transport attaches
AuthorizationandX-Request-Idon every request, addsContent-Type: application/jsonfor bodies, and maps non-2xx responses into typed SDK errors.
sequenceDiagram
participant C as Consumer
participant L as Lita
participant R as ConsentsResource
participant H as HttpClient
participant A as Lita API
C->>L: new Lita(options)
L->>H: new HttpClient(options)
L->>R: new ConsentsResource(http)
C->>R: create(params)
R->>H: post(consents, params)
H->>A: POST /{region}/consents
A-->>H: Consent JSON
H-->>R: Consent
R-->>C: Consent
Shared Type Surface
Client Configuration Types
sdks/node/src/types.ts
Region
us, jp
LitaClientOptions
| Property | Type | Description |
|---|---|---|
apiKey |
string |
Required API key used as the Bearer token |
region |
Region |
Required target region for all requests |
sandbox? |
boolean |
Adds /sandbox to the region prefix when true |
baseUrl? |
string |
Overrides the default API base URL |
timeout? |
number |
Request timeout in milliseconds |
The transport resolves the region prefix as:
us→usjp→jpsandbox: true→us/sandboxorjp/sandbox
The default base URL is https://api.joinlita.com/api/v1, and trailing slashes are removed before request URLs are assembled.
Common Error Payload
sdks/node/src/types.ts
LitaErrorResponse
| Property | Type | Description |
|---|---|---|
error |
{ code: string; message: string; request_id: string; retryable: boolean; } |
Error envelope returned by the API |
Nested error fields:
| Property | Type | Description |
|---|---|---|
code |
string |
Machine-readable error code |
message |
string |
Human-readable error message |
request_id |
string |
Request identifier propagated from the server payload |
retryable |
boolean |
Indicates whether the same request may succeed when retried |
Consent Types
sdks/node/src/types.ts
ConsentPurpose
RENTAL_SCREENING, LENDING_UNDERWRITING, EMPLOYMENT_SCREENING, ACCOUNT_OPENING
DataCategory
transactions, income, payment_behavior, obligations, employment
ConsentStatus
PENDING, ACTIVE, REVOKED, EXPIRED
Connection
| Property | Type | Description |
|---|---|---|
connection_id |
string |
Connection identifier |
provider |
string |
External data provider name |
status |
ACTIVE or INACTIVE |
Connection state |
Consent
| Property | Type | Description |
|---|---|---|
consent_id |
string |
Consent identifier |
status |
ConsentStatus |
Consent lifecycle state |
applicant_id |
string |
Applicant identifier |
purpose |
ConsentPurpose |
Consent purpose |
redirect_url? |
string |
Redirect URL returned by create |
created_at? |
string |
Creation timestamp |
activated_at? |
string |
Activation timestamp |
expires_at |
string |
Expiration timestamp |
revoked_at? |
string |
Revocation timestamp |
connections? |
Connection[] |
Linked provider connections |
ConsentCreateParams
| Property | Type | Description |
|---|---|---|
applicant_id |
string |
Applicant identifier |
purpose |
ConsentPurpose |
Purpose requested by the applicant |
data_categories |
DataCategory[] |
Categories requested for access |
expires_in_days |
number |
Number of days the consent stays active after completion; max 365 |
Feature Computation Types
sdks/node/src/types.ts
JobStatus
PROCESSING, COMPLETE, FAILED
ComputeFeaturesParams
| Property | Type | Description |
|---|---|---|
consent_id |
string |
Active consent used to start computation |
ComputeFeaturesResponse
| Property | Type | Description |
|---|---|---|
job_id |
string |
Async job identifier |
status |
JobStatus |
Current job state |
consent_id |
string |
Consent linked to the job |
estimated_completion_ms |
number |
Estimated completion time in milliseconds |
ScoreDecision
APPROVE, REVIEW, DECLINE, INSUFFICIENT_DATA
Score
| Property | Type | Description |
|---|---|---|
consent_id |
string |
Consent used for scoring |
applicant_id |
string |
Applicant identifier |
score |
number |
Numeric score value |
score_range |
{ min: number; max: number; } |
Score bounds |
decision |
ScoreDecision |
Decision derived from the score |
score_factors |
string[] |
Reasons that influenced the score |
evidence_ref |
string |
Evidence snapshot reference |
scored_at |
string |
Score timestamp |
model_version |
string |
Scoring model version |
Nested score_range fields:
| Property | Type | Description |
|---|---|---|
min |
number |
Minimum possible score |
max |
number |
Maximum possible score |
Evidence Types
sdks/node/src/types.ts
DelinquencyBucket
CURRENT, 30_DPD, 60_DPD, 90_PLUS_DPD, CHARGE_OFF, WRITE_OFF
KycStatus
PASSED, REVIEW, FAILED, PENDING
KycCheckDetail
| Property | Type | Description |
|---|---|---|
status |
KycStatus |
Result for a single KYC check |
method? |
string |
Check method |
lists_screened? |
string[] |
Lists screened during the check |
risk_level? |
string |
Risk level returned by the check |
KycResult
| Property | Type | Description |
|---|---|---|
consent_id |
string |
Consent linked to the KYC result |
status |
KycStatus |
Overall KYC status |
checks |
{ identity?: KycCheckDetail; sanctions?: KycCheckDetail; pep?: KycCheckDetail; aml?: KycCheckDetail; } |
KYC check breakdown |
completed_at |
string |
Completion timestamp |
Nested checks fields:
| Property | Type | Description |
|---|---|---|
identity? |
KycCheckDetail |
Identity verification result |
sanctions? |
KycCheckDetail |
Sanctions screening result |
pep? |
KycCheckDetail |
Politically exposed person screening result |
aml? |
KycCheckDetail |
AML screening result |
EvidenceSnapshot
| Property | Type | Description |
|---|---|---|
evidence_ref |
string |
Evidence snapshot identifier |
consent_id |
string |
Consent linked to the snapshot |
applicant_id |
string |
Applicant identifier |
snapshot_version |
string |
Snapshot version string |
created_at |
string |
Creation timestamp |
score_inputs |
{ payment_behavior?: { payments_observed: number; avg_payment_delay_days: number; late_payment_count_30d_plus: number; }; income?: { monthly_net_income: number; income_stability_score: number; }; obligations?: { total_monthly_obligations: number; obligation_to_income_ratio: number; }; } |
Inputs captured for scoring |
kyc_result |
{ status: KycStatus; checks: string[]; } |
KYC summary embedded in the snapshot |
delinquency_bucket |
DelinquencyBucket |
Delinquency classification |
Nested score_inputs fields:
| Property | Type | Description |
|---|---|---|
payment_behavior? |
{ payments_observed: number; avg_payment_delay_days: number; late_payment_count_30d_plus: number; } |
Payment behavior signals |
income? |
{ monthly_net_income: number; income_stability_score: number; } |
Income signals |
obligations? |
{ total_monthly_obligations: number; obligation_to_income_ratio: number; } |
Obligation signals |
Nested payment_behavior fields:
| Property | Type | Description |
|---|---|---|
payments_observed |
number |
Number of observed payments |
avg_payment_delay_days |
number |
Average delay in days |
late_payment_count_30d_plus |
number |
Count of payments late by 30 days or more |
Nested income fields:
| Property | Type | Description |
|---|---|---|
monthly_net_income |
number |
Monthly net income |
income_stability_score |
number |
Income stability score |
Nested obligations fields:
| Property | Type | Description |
|---|---|---|
total_monthly_obligations |
number |
Total monthly obligations |
obligation_to_income_ratio |
number |
Ratio of obligations to income |
Transaction Types
sdks/node/src/types.ts
TransactionType
DEBIT, CREDIT
Transaction
| Property | Type | Description |
|---|---|---|
transaction_id |
string |
Transaction identifier |
date |
string |
Transaction date |
amount |
number |
Transaction amount |
currency |
string |
ISO currency code |
description |
string |
Transaction description |
category |
string |
Categorization label |
type |
TransactionType |
Debit or credit |
TransactionListParams
| Property | Type | Description |
|---|---|---|
limit? |
number |
Maximum number of records to return |
cursor? |
string |
Pagination cursor |
from_date? |
string |
Lower bound date filter |
to_date? |
string |
Upper bound date filter |
TransactionListResponse
| Property | Type | Description |
|---|---|---|
data |
Transaction[] |
Returned transaction rows |
next_cursor |
`string \ | null` |
total_count |
number |
Total matched transaction count |
Job Status and Webhook Types
sdks/node/src/types.ts
JobStatusResponse
| Property | Type | Description |
|---|---|---|
job_id |
string |
Async job identifier |
status |
JobStatus |
Current job state |
consent_id |
string |
Linked consent identifier |
completed_at? |
string |
Completion timestamp |
error? |
{ code: string; message: string; } |
Job failure details |
Nested error fields:
| Property | Type | Description |
|---|---|---|
code |
string |
Failure code |
message |
string |
Failure message |
WebhookEventType
consent.activated, consent.expired, consent.revoked, data.updated, features.computed, score.completed, kyc.updated
WebhookEvent
| Property | Type | Description |
|---|---|---|
event_id |
string |
Unique webhook event identifier |
event_type |
WebhookEventType |
Event kind |
created_at |
string |
Event creation timestamp |
region |
Region |
Region attached to the event |
data |
Record<string, unknown> |
Event payload |
HTTP Transport
HttpClient
sdks/node/src/client.ts
HttpClient is the shared transport used by every resource wrapper. It centralizes URL construction, header injection, JSON serialization, timeout handling, and SDK error mapping.
| Property | Type | Description |
|---|---|---|
apiKey |
string |
Bearer token attached to every request |
regionPrefix |
string |
Region path segment, optionally suffixed with /sandbox |
baseUrl |
string |
Normalized API base URL |
timeout |
number |
Abort timeout in milliseconds |
Constructor dependencies
| Type | Description |
|---|---|
LitaClientOptions |
Supplies API key, region, sandbox flag, base URL, and timeout |
Public methods
| Method | Description |
|---|---|
get |
Builds a GET request, serializes query parameters, and parses the JSON response |
post |
Builds a POST request with a JSON body and parses the JSON response |
delete |
Builds a DELETE request and parses the JSON response |
Request lifecycle details:
getappends query parameters only when a key has a defined and non-null value.- Query values are stringified with
String(value). requestgenerates a freshX-Request-IdwithrandomUUID()for every outbound call.- Requests with a body include
Content-Type: application/json. - On
response.ok === false, the client parses the error payload asLitaErrorResponseand throws a typed SDK error. 401and403map toLitaAuthError.404maps toLitaNotFoundError.429maps toLitaRateLimitErrorand includes theRetry-Afterheader value when present.- All other non-2xx responses map to
LitaError. - Successful responses are returned as
response.json() as Promise<T>, so the resource layer supplies the compile-time response type.
Error Taxonomy
LitaError
sdks/node/src/errors.ts
Base API failure type used for non-specialized non-2xx responses.
| Property | Type | Description |
|---|---|---|
status |
number |
HTTP status code |
code |
string |
Machine-readable error code |
requestId |
string |
Request identifier from the error payload |
retryable |
boolean |
Retryability flag from the error payload |
LitaAuthError
sdks/node/src/errors.ts
Specialization of LitaError used for 401 and 403 responses. It does not add new fields beyond the base error properties.
LitaNotFoundError
sdks/node/src/errors.ts
Specialization of LitaError used for 404 responses. It does not add new fields beyond the base error properties.
LitaRateLimitError
sdks/node/src/errors.ts
Specialization of LitaError used for 429 responses.
| Property | Type | Description |
|---|---|---|
retryAfter? |
number |
Parsed Retry-After header value when present |
LitaWebhookSignatureError
sdks/node/src/errors.ts
Thrown when webhook signature verification fails. It is raised by constructEvent before any payload parsing is accepted as valid.
Webhook Helpers
constructEvent
sdks/node/src/webhooks.ts
constructEvent(rawBody, signature, secret): WebhookEvent verifies the signature attached to an incoming webhook request and returns the parsed event payload.
| Parameter | Type | Description |
|---|---|---|
rawBody |
`Buffer \ | string` |
signature |
string |
Incoming X-Lita-Signature header value |
secret |
string |
Webhook signing secret from the Lita dashboard |
Public methods
| Method | Description |
|---|---|
constructEvent |
Computes the expected HMAC signature, compares it in constant time, and parses the webhook event |
Verification flow:
- Convert a string body to a UTF-8
Buffer. - Compute
HMAC-SHA256over the raw bytes with the provided secret. - Prefix the hex digest with
sha256=. - Compare the expected signature against the provided header with
timingSafeEqual. - Throw
LitaWebhookSignatureErrorif the comparison fails. - Parse the body as JSON and cast it to
WebhookEvent.
sequenceDiagram
participant S as Webhook Sender
participant A as App
participant H as constructEvent
S->>A: POST webhook body and X Lita Signature
A->>H: rawBody, signature, secret
H->>H: compute HMAC SHA 256
H->>H: compare signatures in constant time
alt signature matches
H-->>A: WebhookEvent
else signature mismatch
H-->>A: LitaWebhookSignatureError
end
Resource Wrappers
ConsentsResource
sdks/node/src/resources/consents.ts
The consent resource maps directly onto the consent lifecycle endpoints and returns strongly typed models for consent state, score data, transaction history, and KYC results.
Constructor dependencies
| Type | Description |
|---|---|
HttpClient |
Shared transport used for all consent-related API calls |
Public methods
| Method | Description |
|---|---|
create |
Creates a consent |
get |
Reads the current consent state |
revoke |
Revokes an active consent |
getScore |
Retrieves the computed score |
listTransactions |
Lists paginated transactions for a consent |
getKyc |
Retrieves KYC and AML results |
Create Consent
{
"title": "Create Consent",
"description": "Creates a consent and returns the redirect URL. When sandbox is enabled, the runtime path becomes /{region}/sandbox/consents.",
"method": "POST",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/consents",
"headers": [
{
"key": "Authorization",
"value": "Bearer <api_key>",
"required": true
},
{
"key": "X-Request-Id",
"value": "req-<uuid>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"applicant_id\": \"app_demo_001\",\n \"purpose\": \"LENDING_UNDERWRITING\",\n \"data_categories\": [\n \"transactions\",\n \"income\",\n \"payment_behavior\"\n ],\n \"expires_in_days\": 30\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_id\": \"con_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"status\": \"PENDING\",\n \"applicant_id\": \"app_demo_001\",\n \"purpose\": \"LENDING_UNDERWRITING\",\n \"redirect_url\": \"https://auth.joinlita.com/consents/con_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"created_at\": \"2026-03-31T10:15:00Z\",\n \"expires_at\": \"2026-04-30T10:15:00Z\",\n \"connections\": [\n {\n \"connection_id\": \"conn_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"provider\": \"bank_rails\",\n \"status\": \"ACTIVE\"\n }\n ]\n}"
},
"401": {
"description": "Unauthorized",
"body": "{\n \"error\": {\n \"code\": \"unauthorized\",\n \"message\": \"Invalid API key\",\n \"request_id\": \"req-0f3b6b6e-1d0f-4d1c-8cbe-9e6a9d0f7a12\",\n \"retryable\": false\n }\n}"
},
"429": {
"description": "Rate limited",
"body": "{\n \"error\": {\n \"code\": \"rate_limited\",\n \"message\": \"Too many requests\",\n \"request_id\": \"req-0f3b6b6e-1d0f-4d1c-8cbe-9e6a9d0f7a12\",\n \"retryable\": true\n }\n}"
}
}
}
Get Consent
{
"title": "Get Consent",
"description": "Gets the current state of a consent. When sandbox is enabled, the runtime path becomes /{region}/sandbox/consents/{id}.",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/consents/{consentId}",
"headers": [
{
"key": "Authorization",
"value": "Bearer <api_key>",
"required": true
},
{
"key": "X-Request-Id",
"value": "req-<uuid>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "<consent_id>",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_id\": \"con_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"status\": \"ACTIVE\",\n \"applicant_id\": \"app_demo_001\",\n \"purpose\": \"LENDING_UNDERWRITING\",\n \"redirect_url\": \"https://auth.joinlita.com/consents/con_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"created_at\": \"2026-03-31T10:15:00Z\",\n \"activated_at\": \"2026-03-31T10:16:00Z\",\n \"expires_at\": \"2026-04-30T10:15:00Z\",\n \"connections\": [\n {\n \"connection_id\": \"conn_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"provider\": \"bank_rails\",\n \"status\": \"ACTIVE\"\n }\n ]\n}"
},
"404": {
"description": "Not found",
"body": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req-0f3b6b6e-1d0f-4d1c-8cbe-9e6a9d0f7a12\",\n \"retryable\": false\n }\n}"
},
"429": {
"description": "Rate limited",
"body": "{\n \"error\": {\n \"code\": \"rate_limited\",\n \"message\": \"Too many requests\",\n \"request_id\": \"req-0f3b6b6e-1d0f-4d1c-8cbe-9e6a9d0f7a12\",\n \"retryable\": true\n }\n}"
}
}
}
Revoke Consent
{
"title": "Revoke Consent",
"description": "Revokes an active consent and returns the consent identifier, status, and revocation timestamp. When sandbox is enabled, the runtime path becomes /{region}/sandbox/consents/{id}.",
"method": "DELETE",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/consents/{consentId}",
"headers": [
{
"key": "Authorization",
"value": "Bearer <api_key>",
"required": true
},
{
"key": "X-Request-Id",
"value": "req-<uuid>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "<consent_id>",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_id\": \"con_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"status\": \"REVOKED\",\n \"revoked_at\": \"2026-03-31T11:00:00Z\"\n}"
},
"404": {
"description": "Not found",
"body": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req-0f3b6b6e-1d0f-4d1c-8cbe-9e6a9d0f7a12\",\n \"retryable\": false\n }\n}"
}
}
}
Get Consent Score
{
"title": "Get Consent Score",
"description": "Retrieves the computed credit score for a consent. When sandbox is enabled, the runtime path becomes /{region}/sandbox/consents/{id}/score.",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/consents/{consentId}/score",
"headers": [
{
"key": "Authorization",
"value": "Bearer <api_key>",
"required": true
},
{
"key": "X-Request-Id",
"value": "req-<uuid>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "<consent_id>",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_id\": \"con_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"applicant_id\": \"app_demo_001\",\n \"score\": 742,\n \"score_range\": {\n \"min\": 300,\n \"max\": 850\n },\n \"decision\": \"APPROVE\",\n \"score_factors\": [\n \"consistent income\",\n \"low utilization\"\n ],\n \"evidence_ref\": \"evi_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"scored_at\": \"2026-03-31T10:20:00Z\",\n \"model_version\": \"score-v2026.03\"\n}"
},
"404": {
"description": "Not found",
"body": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req-0f3b6b6e-1d0f-4d1c-8cbe-9e6a9d0f7a12\",\n \"retryable\": false\n }\n}"
},
"429": {
"description": "Rate limited",
"body": "{\n \"error\": {\n \"code\": \"rate_limited\",\n \"message\": \"Too many requests\",\n \"request_id\": \"req-0f3b6b6e-1d0f-4d1c-8cbe-9e6a9d0f7a12\",\n \"retryable\": true\n }\n}"
}
}
}
List Transactions
{
"title": "List Transactions",
"description": "Lists paginated transactions for a consent, optionally filtered by cursor and date range. When sandbox is enabled, the runtime path becomes /{region}/sandbox/consents/{id}/data/transactions.",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/consents/{consentId}/data/transactions",
"headers": [
{
"key": "Authorization",
"value": "Bearer <api_key>",
"required": true
},
{
"key": "X-Request-Id",
"value": "req-<uuid>",
"required": true
}
],
"queryParams": [
{
"key": "limit",
"value": "50",
"required": false
},
{
"key": "cursor",
"value": "txn_cursor_001",
"required": false
},
{
"key": "from_date",
"value": "2025-01-01",
"required": false
},
{
"key": "to_date",
"value": "2025-01-31",
"required": false
}
],
"pathParams": [
{
"key": "consentId",
"value": "<consent_id>",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"data\": [\n {\n \"transaction_id\": \"txn_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"date\": \"2026-03-30\",\n \"amount\": -125.45,\n \"currency\": \"USD\",\n \"description\": \"Rent payment\",\n \"category\": \"housing\",\n \"type\": \"DEBIT\"\n }\n ],\n \"next_cursor\": \"txn_cursor_002\",\n \"total_count\": 1\n}"
},
"404": {
"description": "Not found",
"body": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req-0f3b6b6e-1d0f-4d1c-8cbe-9e6a9d0f7a12\",\n \"retryable\": false\n }\n}"
},
"429": {
"description": "Rate limited",
"body": "{\n \"error\": {\n \"code\": \"rate_limited\",\n \"message\": \"Too many requests\",\n \"request_id\": \"req-0f3b6b6e-1d0f-4d1c-8cbe-9e6a9d0f7a12\",\n \"retryable\": true\n }\n}"
}
}
}
Get KYC Result
{
"title": "Get KYC Result",
"description": "Returns KYC and AML check results for a consent. When sandbox is enabled, the runtime path becomes /{region}/sandbox/consents/{id}/kyc.",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/consents/{consentId}/kyc",
"headers": [
{
"key": "Authorization",
"value": "Bearer <api_key>",
"required": true
},
{
"key": "X-Request-Id",
"value": "req-<uuid>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consentId",
"value": "<consent_id>",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_id\": \"con_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"status\": \"PASSED\",\n \"checks\": {\n \"identity\": {\n \"status\": \"PASSED\",\n \"method\": \"document_verification\",\n \"lists_screened\": [\n \"internal_watchlist\"\n ],\n \"risk_level\": \"LOW\"\n },\n \"sanctions\": {\n \"status\": \"PASSED\",\n \"method\": \"sanctions_screening\",\n \"lists_screened\": [\n \"ofac\",\n \"eu\"\n ],\n \"risk_level\": \"LOW\"\n },\n \"pep\": {\n \"status\": \"REVIEW\",\n \"method\": \"pep_screening\",\n \"lists_screened\": [\n \"pep_global\"\n ],\n \"risk_level\": \"MEDIUM\"\n },\n \"aml\": {\n \"status\": \"PASSED\",\n \"method\": \"rules_engine\",\n \"lists_screened\": [\n \"internal_aml\"\n ],\n \"risk_level\": \"LOW\"\n }\n },\n \"completed_at\": \"2026-03-31T10:22:00Z\"\n}"
},
"404": {
"description": "Not found",
"body": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"Consent not found\",\n \"request_id\": \"req-0f3b6b6e-1d0f-4d1c-8cbe-9e6a9d0f7a12\",\n \"retryable\": false\n }\n}"
}
}
}
FeaturesResource
sdks/node/src/resources/features.ts
This wrapper starts the asynchronous feature computation pipeline for a consent.
Constructor dependencies
| Type | Description |
|---|---|
HttpClient |
Shared transport used for the feature computation request |
Public methods
| Method | Description |
|---|---|
compute |
Starts feature computation for a consent |
Compute Features
{
"title": "Compute Features",
"description": "Triggers the feature computation pipeline for an active consent. When sandbox is enabled, the runtime path becomes /{region}/sandbox/features/compute.",
"method": "POST",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/features/compute",
"headers": [
{
"key": "Authorization",
"value": "Bearer <api_key>",
"required": true
},
{
"key": "X-Request-Id",
"value": "req-<uuid>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"consent_id\": \"con_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"job_id\": \"job_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"status\": \"PROCESSING\",\n \"consent_id\": \"con_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"estimated_completion_ms\": 1500\n}"
},
"429": {
"description": "Rate limited",
"body": "{\n \"error\": {\n \"code\": \"rate_limited\",\n \"message\": \"Too many requests\",\n \"request_id\": \"req-0f3b6b6e-1d0f-4d1c-8cbe-9e6a9d0f7a12\",\n \"retryable\": true\n }\n}"
}
}
}
EvidenceResource
sdks/node/src/resources/evidence.ts
The evidence wrapper returns immutable evidence snapshots for audit and regulatory use cases.
Constructor dependencies
| Type | Description |
|---|---|
HttpClient |
Shared transport used for evidence retrieval |
Public methods
| Method | Description |
|---|---|
get |
Retrieves an evidence snapshot by evidence reference |
Get Evidence Snapshot
{
"title": "Get Evidence Snapshot",
"description": "Retrieves an immutable evidence snapshot. When sandbox is enabled, the runtime path becomes /{region}/sandbox/evidence/{evidence_ref}.",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/evidence/{evidenceRef}",
"headers": [
{
"key": "Authorization",
"value": "Bearer <api_key>",
"required": true
},
{
"key": "X-Request-Id",
"value": "req-<uuid>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "evidenceRef",
"value": "<evidence_ref>",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"evidence_ref\": \"evi_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"consent_id\": \"con_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"applicant_id\": \"app_demo_001\",\n \"snapshot_version\": \"v3\",\n \"created_at\": \"2026-03-31T10:20:00Z\",\n \"score_inputs\": {\n \"payment_behavior\": {\n \"payments_observed\": 24,\n \"avg_payment_delay_days\": 1.4,\n \"late_payment_count_30d_plus\": 0\n },\n \"income\": {\n \"monthly_net_income\": 5400,\n \"income_stability_score\": 92\n },\n \"obligations\": {\n \"total_monthly_obligations\": 1800,\n \"obligation_to_income_ratio\": 0.33\n }\n },\n \"kyc_result\": {\n \"status\": \"PASSED\",\n \"checks\": [\n \"identity\",\n \"sanctions\"\n ]\n },\n \"delinquency_bucket\": \"CURRENT\"\n}"
},
"404": {
"description": "Not found",
"body": "{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"Evidence snapshot not found\",\n \"request_id\": \"req-0f3b6b6e-1d0f-4d1c-8cbe-9e6a9d0f7a12\",\n \"retryable\": false\n }\n}"
}
}
}
StatusResource
sdks/node/src/resources/status.ts
The status wrapper polls the state of an asynchronous processing job.
Constructor dependencies
| Type | Description |
|---|---|
HttpClient |
Shared transport used for job polling |
Public methods
| Method | Description |
|---|---|
get |
Retrieves the current job status by job identifier |
Get Job Status
{
"title": "Get Job Status",
"description": "Polls the status of an async processing job. When sandbox is enabled, the runtime path becomes /{region}/sandbox/status/{job_id}.",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/status/{jobId}",
"headers": [
{
"key": "Authorization",
"value": "Bearer <api_key>",
"required": true
},
{
"key": "X-Request-Id",
"value": "req-<uuid>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "jobId",
"value": "<job_id>",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"job_id\": \"job_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"status\": \"COMPLETE\",\n \"consent_id\": \"con_01J9Q8V2E3R8P7X1Y2Z3A4B5C6\",\n \"completed_at\": \"2026-03-31T10:15:01Z\"\n}"
},
"429": {
"description": "Rate limited",
"body": "{\n \"error\": {\n \"code\": \"rate_limited\",\n \"message\": \"Too many requests\",\n \"request_id\": \"req-0f3b6b6e-1d0f-4d1c-8cbe-9e6a9d0f7a12\",\n \"retryable\": true\n }\n}"
}
}
}
Error Handling
The SDK surfaces server failures through a small, typed hierarchy:
LitaErrorcarries the HTTP status, machine-readable code, request ID, and retryability flag.LitaAuthErroris thrown for401and403.LitaNotFoundErroris thrown for404.LitaRateLimitErroris thrown for429and exposesretryAfterwhen the response includesRetry-After.LitaWebhookSignatureErroris thrown before webhook payload parsing succeeds when the signature comparison fails.
A typical handling pattern is:
try {
const consent = await lita.consents.get('con_123');
return consent;
} catch (error) {
if (error instanceof LitaRateLimitError) {
console.log(error.retryAfter);
}
throw error;
}
The transport preserves the request identifier from the response payload as requestId, which is the field surfaced by LitaError.
Testing Considerations
The SDK surface supports focused tests around the transport and wrapper behavior:
- verify that
Litawires oneHttpClientinto all four resource wrappers - verify
HttpClientbuilds URLs withbaseUrl, region, and optional sandbox prefix - verify
getomitsundefinedandnullquery parameters - verify
postsetsContent-Type: application/json - verify non-2xx responses map to the correct error subclass
- verify
constructEventaccepts raw bytes or strings and rejects invalid signatures - verify resource methods pass the correct relative path and typed payload to
HttpClient
Key Classes Reference
| Class | Location | Responsibility |
|---|---|---|
Lita |
index.ts |
Public SDK client that composes the resource wrappers |
HttpClient |
client.ts |
Shared HTTP transport, URL building, headers, timeout, and error mapping |
LitaError |
errors.ts |
Base API error type |
LitaAuthError |
errors.ts |
Auth failure specialization |
LitaNotFoundError |
errors.ts |
Missing resource specialization |
LitaRateLimitError |
errors.ts |
Rate limit specialization with retry-after support |
LitaWebhookSignatureError |
errors.ts |
Webhook signature verification failure |
constructEvent |
webhooks.ts |
Webhook signature verification helper |
ConsentsResource |
resources/consents.ts |
Consent, score, transaction, and KYC operations |
FeaturesResource |
resources/features.ts |
Feature computation trigger |
EvidenceResource |
resources/evidence.ts |
Evidence snapshot retrieval |
StatusResource |
resources/status.ts |
Async job status polling |