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:

  1. new Lita(options) creates a single HttpClient.
  2. The same HttpClient instance is injected into ConsentsResource, FeaturesResource, EvidenceResource, and StatusResource.
  3. Each resource method forwards directly to the transport with a relative path and typed request or response contract.
  4. HttpClient builds the final URL from the configured base URL, region, and optional sandbox prefix.
  5. The transport attaches Authorization and X-Request-Id on every request, adds Content-Type: application/json for 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 → us
  • jp → jp
  • sandbox: true → us/sandbox or jp/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

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
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:

  • get appends query parameters only when a key has a defined and non-null value.
  • Query values are stringified with String(value).
  • request generates a fresh X-Request-Id with randomUUID() for every outbound call.
  • Requests with a body include Content-Type: application/json.
  • On response.ok === false, the client parses the error payload as LitaErrorResponse and throws a typed SDK error.
  • 401 and 403 map to LitaAuthError.
  • 404 maps to LitaNotFoundError.
  • 429 maps to LitaRateLimitError and includes the Retry-After header 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:

  1. Convert a string body to a UTF-8 Buffer.
  2. Compute HMAC-SHA256 over the raw bytes with the provided secret.
  3. Prefix the hex digest with sha256=.
  4. Compare the expected signature against the provided header with timingSafeEqual.
  5. Throw LitaWebhookSignatureError if the comparison fails.
  6. 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
{
    "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}"
        }
    }
}
{
    "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}"
        }
    }
}
{
    "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}"
        }
    }
}
{
    "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:

  • LitaError carries the HTTP status, machine-readable code, request ID, and retryability flag.
  • LitaAuthError is thrown for 401 and 403.
  • LitaNotFoundError is thrown for 404.
  • LitaRateLimitError is thrown for 429 and exposes retryAfter when the response includes Retry-After.
  • LitaWebhookSignatureError is 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 Lita wires one HttpClient into all four resource wrappers
  • verify HttpClient builds URLs with baseUrl, region, and optional sandbox prefix
  • verify get omits undefined and null query parameters
  • verify post sets Content-Type: application/json
  • verify non-2xx responses map to the correct error subclass
  • verify constructEvent accepts 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