@splitin/verification-adapter-sdk 0.1.0-beta.0

package/dist/contracts-5VqcOmjU.d.ts

@@ -0,0 +1,388 @@
+/** Public adapter contract version. Npm package versions remain 0.1.x-beta until sandbox certification. */
+declare const VERIFICATION_ADAPTER_CONTRACT_VERSION: "1.0.0";
+declare const ENGINE_CONTRACT_VERSION: "1.0.0";
+declare const PROVIDER_MANIFEST_SCHEMA_URN = "urn:splitin:verification:provider-manifest:v1";
+declare const STANDARD_PACKAGE_CODES: readonly ["human_idv", "business_kyb", "associated_person_idv", "ownership_review"];
+type StandardPackageCode = (typeof STANDARD_PACKAGE_CODES)[number];
+declare const STANDARD_WEBHOOK_PROTOCOLS: readonly ["none", "stripe_v1_hmac", "persona_hmac_sha256", "plaid_es256_jwk"];
+type StandardWebhookProtocol = (typeof STANDARD_WEBHOOK_PROTOCOLS)[number];
+declare const CANONICAL_STATUSES: readonly ["created", "pending_user_input", "paused", "processing", "manual_review_required", "verified", "declined", "failed", "expired", "canceled", "provider_unavailable", "redacted"];
+type VerificationCanonicalStatus = (typeof CANONICAL_STATUSES)[number];
+declare const TERMINAL_STATUSES: readonly ["verified", "declined", "failed", "expired", "canceled", "redacted"];
+type TerminalVerificationStatus = (typeof TERMINAL_STATUSES)[number];
+declare const LAUNCH_PRESENTATIONS: readonly ["embedded", "hosted", "qr", "none"];
+type VerificationLaunchPresentation = (typeof LAUNCH_PRESENTATIONS)[number];
+declare const PROVIDER_ENVIRONMENTS: readonly ["sandbox", "production"];
+type VerificationProviderEnvironment = (typeof PROVIDER_ENVIRONMENTS)[number];
+declare const PROVIDER_OPERATIONS: readonly ["create", "resume", "retrieve", "retry", "cancel", "redact", "webhook_verify", "webhook_normalize", "health"];
+type ProviderOperation = (typeof PROVIDER_OPERATIONS)[number];
+declare const STANDARD_RELATIONSHIP_KINDS: readonly ["ubo", "director", "officer", "authorized_representative", "associated_person"];
+type StandardRelationshipKind = (typeof STANDARD_RELATIONSHIP_KINDS)[number];
+/** Standard codes or namespaced custom codes such as `com.example.employee_check`. */
+type VerificationPackageCode = StandardPackageCode | (string & {});
+type WebhookProtocolId = StandardWebhookProtocol | (string & {});
+type ProviderResourceType = string;
+type VerificationProviderCode = string;
+type VerificationLauncherKey = string;
+declare function isProviderCode(value: string): boolean;
+declare function isLauncherKey(value: string): boolean;
+declare function isStandardPackageCode(value: string): value is StandardPackageCode;
+declare function isCustomPackageCode(value: string): boolean;
+declare function isPackageCode(value: string): value is VerificationPackageCode;
+declare function assertPackageCode(value: string): VerificationPackageCode;
+declare function isWebhookProtocol(value: string): value is WebhookProtocolId;
+declare function isResourceType(value: string): value is ProviderResourceType;
+declare function isCountryCode(value: string): boolean;
+declare function isSemver(value: string): boolean;
+declare function isCanonicalStatus(value: string): value is VerificationCanonicalStatus;
+declare function isTerminalStatus(value: string): value is TerminalVerificationStatus;
+declare function isOpaqueSubjectReference(value: string): boolean;
+declare function metadataContainsForbiddenIdentifier(value: unknown): boolean;
+declare function compareSemver(left: string, right: string): number;
+declare function majorsCompatible(left: string, right: string): boolean;
+
+type ProviderErrorCode = 'INVALID_CONFIGURATION' | 'UNSUPPORTED_CAPABILITY' | 'AUTHENTICATION_FAILED' | 'SIGNATURE_INVALID' | 'RATE_LIMITED' | 'TIMEOUT' | 'RETRYABLE_PROVIDER_FAILURE' | 'TERMINAL_INPUT_FAILURE' | 'UNKNOWN_PROVIDER_STATE' | 'PROVIDER_UNAVAILABLE';
+interface ProviderErrorOptions {
+    retryable?: boolean;
+    safeCode?: string;
+    retryAfterSeconds?: number;
+    cause?: unknown;
+}
+/** Provider-safe error. Message and fields must never contain PII or secrets. */
+declare class ProviderError extends Error {
+    readonly code: ProviderErrorCode;
+    readonly retryable: boolean;
+    readonly safeCode: string;
+    readonly retryAfterSeconds?: number;
+    constructor(code: ProviderErrorCode, message: string, options?: ProviderErrorOptions);
+}
+declare class ProviderUnavailableError extends ProviderError {
+    constructor(message?: string, options?: ProviderErrorOptions);
+}
+declare class ProviderOperationPendingError extends ProviderError {
+    constructor(message?: string);
+}
+declare class VerificationAttemptLimitError extends ProviderError {
+    constructor(retryAfterSeconds: number);
+}
+declare class ProviderRequiredInformationError extends ProviderError {
+    constructor(message?: string);
+}
+interface SafeProviderFailure {
+    code: ProviderErrorCode;
+    safeCode: string;
+    retryable: boolean;
+    retryAfterSeconds?: number;
+}
+declare function toSafeProviderFailure(error: unknown): SafeProviderFailure;
+
+interface ProviderCapabilities {
+    presentations: VerificationLaunchPresentation[];
+    canResume: boolean;
+    canRetry: boolean;
+    canCancel: boolean;
+    canRedact: boolean;
+}
+interface JsonSchema2020 {
+    $schema?: string;
+    $id?: string;
+    type?: string | string[];
+    title?: string;
+    description?: string;
+    const?: unknown;
+    enum?: unknown[];
+    required?: string[];
+    additionalProperties?: boolean | JsonSchema2020;
+    properties?: Record<string, JsonSchema2020>;
+    items?: JsonSchema2020 | JsonSchema2020[];
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    uniqueItems?: boolean;
+    pattern?: string;
+    format?: string;
+    'x-secret'?: boolean;
+    [key: string]: unknown;
+}
+interface ProviderConfigurationSchemaV1 extends JsonSchema2020 {
+    $schema: 'https://json-schema.org/draft/2020-12/schema';
+    type: 'object';
+    additionalProperties: false;
+    required: string[];
+    properties: Record<string, JsonSchema2020>;
+}
+interface ProviderManifestV1 {
+    contractVersion: typeof VERIFICATION_ADAPTER_CONTRACT_VERSION;
+    adapterVersion: string;
+    engineCompatibility: string;
+    provider: VerificationProviderCode;
+    displayName: string;
+    description?: string;
+    supportedPackages: VerificationPackageCode[];
+    supportedCountries: string[];
+    environments: VerificationProviderEnvironment[];
+    capabilities: ProviderCapabilities;
+    launcherKeys: string[];
+    launchPresentations: VerificationLaunchPresentation[];
+    configurationSchemaVersion: string;
+    configurationSchema: ProviderConfigurationSchemaV1;
+    webhook: {
+        protocol: WebhookProtocolId;
+        eventFamilies: string[];
+        toleranceSeconds?: number;
+    };
+    dataPolicy: {
+        classifications: string[];
+        prohibitedPersistence: string[];
+        rawPayloadPersistence: false;
+        browserSecretPersistence: false;
+        governmentIdentifierPersistence: false;
+    };
+    retry: {
+        sameResourceWhenResumable: boolean;
+        newAttemptAfterTerminal: boolean;
+    };
+    cancellation: {
+        supported: boolean;
+        terminal: boolean;
+    };
+    redaction: {
+        supported: boolean;
+        asynchronous: boolean;
+        notApplicable?: boolean;
+    };
+    apiHosts: string[];
+    testedApiVersions: string[];
+}
+interface ProviderSafeLogger {
+    info(event: string, metadata?: Record<string, string | number | boolean | null>): void;
+    warn(event: string, metadata?: Record<string, string | number | boolean | null>): void;
+    error(event: string, metadata?: Record<string, string | number | boolean | null>): void;
+}
+interface ProviderHealthObservation {
+    operation: ProviderOperation;
+    outcome: 'success' | 'retryable_failure' | 'terminal_failure' | 'unknown_status';
+    safeCode: string;
+    observedAt: string;
+    latencyMs?: number;
+}
+interface TraceSpan {
+    name: string;
+    attributes?: Record<string, string | number | boolean>;
+}
+interface OpenTelemetryHooks {
+    counter?(name: string, value: number, attributes?: Record<string, string>): void;
+    histogram?(name: string, value: number, attributes?: Record<string, string>): void;
+    startSpan?(span: TraceSpan): {
+        end(): void;
+    };
+}
+interface ProviderRateBudget {
+    acquire(operation: ProviderOperation): Promise<{
+        allowed: boolean;
+        retryAfterSeconds?: number;
+    }>;
+}
+interface ProviderHttpClient {
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+interface ProviderRuntimeContext<TConfiguration extends object = Record<string, unknown>> {
+    environment: VerificationProviderEnvironment;
+    configuration: Readonly<TConfiguration>;
+    http: ProviderHttpClient;
+    now: () => Date;
+    crypto: Crypto;
+    idempotency: {
+        keyFor(operation: ProviderOperation, attemptId: string, suppliedKey?: string): string;
+    };
+    logger: ProviderSafeLogger;
+    telemetry?: OpenTelemetryHooks;
+    recordHealth: (observation: ProviderHealthObservation) => Promise<void>;
+    rateBudget?: ProviderRateBudget;
+}
+interface ProviderAddressInput {
+    street1: string;
+    street2?: string | null;
+    city: string;
+    subdivision?: string | null;
+    postalCode: string;
+    countryCode: string;
+}
+interface ProviderAssociatedPersonInput {
+    subjectReference: string;
+    legalFirstName: string;
+    legalLastName: string;
+    email?: string | null;
+    relationshipKind: string;
+    claimedOwnershipPercentage?: number | null;
+}
+interface ProviderOrganizationInput {
+    legalName: string;
+    jurisdictionCountryCode: string;
+    entityType?: string | null;
+    registeredAddress?: ProviderAddressInput | null;
+    physicalAddress?: ProviderAddressInput | null;
+    associatedPeople?: ProviderAssociatedPersonInput[];
+    evidenceReferences?: string[];
+}
+interface ProviderRelationshipInput {
+    relationshipReference: string;
+    kind: string;
+    claimedOwnershipPercentage?: number | null;
+    subjectReference?: string | null;
+}
+interface ProviderAttemptCommand {
+    attemptId: string;
+    subjectReference: string;
+    organizationReference?: string | null;
+    packageCode: VerificationPackageCode;
+    countryCode: string;
+    idempotencyKey: string;
+    configurationRevision: string;
+    legalFirstName?: string | null;
+    legalLastName?: string | null;
+    email?: string | null;
+    organization?: ProviderOrganizationInput | null;
+    relationship?: ProviderRelationshipInput | null;
+    associatedPerson?: ProviderAssociatedPersonInput | null;
+    evidenceReferences?: string[];
+    requestOrigin?: string | null;
+    metadata?: Record<string, string | number | boolean | null>;
+}
+interface ProviderResumeCommand {
+    attemptId: string;
+    providerResourceId: string;
+    configurationRevision: string;
+    requestOrigin?: string | null;
+}
+interface ProviderRetryCommand extends ProviderAttemptCommand {
+    previousProviderResourceId?: string | null;
+}
+interface ProviderResourceCommand {
+    attemptId: string;
+    providerResourceId: string;
+    configurationRevision: string;
+    requestOrigin?: string | null;
+}
+interface ProviderRedactionCommand {
+    subjectReference: string;
+    providerResourceId?: string | null;
+    providerResourceType?: string;
+    requestReference: string;
+}
+interface ProviderLaunchEnvelope {
+    attemptId: string;
+    canonicalStatus: VerificationCanonicalStatus;
+    launcherKey: string;
+    presentation: VerificationLaunchPresentation;
+    providerDisclosure?: string;
+    transientSecret?: string;
+    transientSecretExpiresAt?: string;
+    hostedUrl?: string;
+    hostedFallbackExpiresAt?: string;
+    safeErrorCode?: string | null;
+    retryAfter?: string | null;
+    supportPath?: string | null;
+    continuationReference?: string;
+}
+interface ProviderAttemptResult {
+    attemptId: string;
+    providerResourceId: string;
+    providerStatus: string;
+    canonicalStatus: VerificationCanonicalStatus;
+    launch: ProviderLaunchEnvelope;
+    linkedResources?: Array<{
+        resourceType: string;
+        resourceId: string;
+        relationshipCode: string;
+        providerStatus: string;
+        occurredAt: string;
+    }>;
+}
+interface NormalizedProviderSnapshot {
+    providerResourceId: string;
+    providerStatus: string;
+    canonicalStatus: VerificationCanonicalStatus;
+    occurredAt: string;
+    providerCreatedAt?: string;
+    normalizedReasonCodes: string[];
+    safeMetadata: Record<string, string | boolean | number | null>;
+}
+interface ProviderOperationResult {
+    accepted: boolean;
+    providerStatus?: string;
+    canonicalStatus?: VerificationCanonicalStatus;
+}
+interface ProviderRedactionResult {
+    completed: boolean;
+    retryable: boolean;
+    disposition?: 'scheduled' | 'processing' | 'retryable' | 'redacted' | 'not_applicable' | 'dead_letter' | 'failed';
+}
+interface VerifiedWebhookEnvelope {
+    providerEventKey: string;
+    receivedAt: string;
+    bodySha256: string;
+    signatureIssuedAt?: string;
+    opaquePayload: Uint8Array;
+}
+interface NormalizedProviderEvent {
+    providerEventKey: string;
+    providerResourceId: string;
+    eventType: string;
+    providerEventType: string;
+    canonicalStatus?: VerificationCanonicalStatus;
+    occurredAt: string;
+    normalizedReasonCodes: string[];
+    safeMetadata: Record<string, string | boolean | number | null>;
+}
+/**
+ * Provider-neutral verification adapter. The engine owns reconciliation,
+ * queues, routing, attempts, decisions and protected-action enforcement.
+ */
+interface VerificationAdapterV1<TConfig extends object = Record<string, unknown>> {
+    readonly contractVersion: typeof VERIFICATION_ADAPTER_CONTRACT_VERSION;
+    readonly manifest: ProviderManifestV1;
+    readonly provider: VerificationProviderCode;
+    readonly environment: VerificationProviderEnvironment;
+    readonly runtime: ProviderRuntimeContext<TConfig>;
+    validateConfiguration(): void;
+    createAttempt(command: ProviderAttemptCommand): Promise<ProviderAttemptResult>;
+    resumeAttempt(command: ProviderResumeCommand): Promise<ProviderLaunchEnvelope>;
+    retrieveAttempt(command: ProviderResourceCommand): Promise<NormalizedProviderSnapshot>;
+    retryAttempt(command: ProviderRetryCommand): Promise<ProviderAttemptResult>;
+    cancelAttempt(command: ProviderResourceCommand): Promise<ProviderOperationResult>;
+    redactSubject(command: ProviderRedactionCommand): Promise<ProviderRedactionResult>;
+    verifyWebhook(input: Request): Promise<VerifiedWebhookEnvelope>;
+    normalizeWebhook(input: VerifiedWebhookEnvelope): Promise<NormalizedProviderEvent>;
+}
+interface ActorContext {
+    tenantKey: string;
+    actorId: string;
+    actorType: 'user' | 'operator' | 'system';
+    roles: string[];
+    authorizedSubjectScope: string[];
+}
+interface ProtectedActionDenial {
+    code: 'VERIFICATION_REQUIRED';
+    action: string;
+    resourceHash: string;
+    requiredPackages: VerificationPackageCode[];
+    continuation: {
+        key: string;
+        token: string;
+        expiresAt: string;
+    };
+    retryAfter: string | null;
+    supportPath: string | null;
+}
+interface SafeProviderFailureEnvelope {
+    code: ProviderErrorCode;
+    safeCode: string;
+    retryable: boolean;
+    retryAfterSeconds?: number;
+    supportPath?: string | null;
+}
+
+export { VERIFICATION_ADAPTER_CONTRACT_VERSION as $, type ActorContext as A, ProviderRequiredInformationError as B, CANONICAL_STATUSES as C, type ProviderResourceCommand as D, ENGINE_CONTRACT_VERSION as E, type ProviderResourceType as F, type ProviderResumeCommand as G, type ProviderRetryCommand as H, type ProviderSafeLogger as I, type JsonSchema2020 as J, ProviderUnavailableError as K, LAUNCH_PRESENTATIONS as L, STANDARD_RELATIONSHIP_KINDS as M, type NormalizedProviderEvent as N, type OpenTelemetryHooks as O, type ProviderConfigurationSchemaV1 as P, STANDARD_WEBHOOK_PROTOCOLS as Q, type SafeProviderFailure as R, STANDARD_PACKAGE_CODES as S, type SafeProviderFailureEnvelope as T, type StandardPackageCode as U, type VerificationAdapterV1 as V, type StandardRelationshipKind as W, type StandardWebhookProtocol as X, TERMINAL_STATUSES as Y, type TerminalVerificationStatus as Z, type TraceSpan as _, type ProviderManifestV1 as a, VerificationAttemptLimitError as a0, type VerificationCanonicalStatus as a1, type VerificationLaunchPresentation as a2, type VerificationLauncherKey as a3, type VerificationPackageCode as a4, type VerificationProviderCode as a5, type VerificationProviderEnvironment as a6, type VerifiedWebhookEnvelope as a7, type WebhookProtocolId as a8, assertPackageCode as a9, compareSemver as aa, isCanonicalStatus as ab, isCountryCode as ac, isCustomPackageCode as ad, isLauncherKey as ae, isOpaqueSubjectReference as af, isPackageCode as ag, isProviderCode as ah, isResourceType as ai, isSemver as aj, isStandardPackageCode as ak, isTerminalStatus as al, isWebhookProtocol as am, majorsCompatible as an, metadataContainsForbiddenIdentifier as ao, toSafeProviderFailure as ap, type ProviderRuntimeContext as b, type NormalizedProviderSnapshot as c, PROVIDER_ENVIRONMENTS as d, PROVIDER_MANIFEST_SCHEMA_URN as e, PROVIDER_OPERATIONS as f, type ProtectedActionDenial as g, type ProviderAddressInput as h, type ProviderAssociatedPersonInput as i, type ProviderAttemptCommand as j, type ProviderAttemptResult as k, type ProviderCapabilities as l, ProviderError as m, type ProviderErrorCode as n, type ProviderErrorOptions as o, type ProviderHealthObservation as p, type ProviderHttpClient as q, type ProviderLaunchEnvelope as r, type ProviderOperation as s, ProviderOperationPendingError as t, type ProviderOperationResult as u, type ProviderOrganizationInput as v, type ProviderRateBudget as w, type ProviderRedactionCommand as x, type ProviderRedactionResult as y, type ProviderRelationshipInput as z };

package/dist/contracts-5VqcOmjU.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts-5VqcOmjU.d.ts","sources":["contracts-5VqcOmjU.d.ts"],"names":[],"mappings":"AAAA"}