@arkyc/types 1.0.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toneflix Technologies Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -6,11 +6,11 @@ import { CaptureModel, DEFAULT_GLOBAL_SETTINGS, GlobalSetting, GlobalSettings, R
 import { DecisionReason, LivenessChallenge, LivenessMode, VerificationDecision, VerificationSession, VerificationStatus } from "./verification.mjs";
 import { REALTIME_EVENT, RealtimeEventName, ReviewActionEvent, SessionTransitionEvent, parseRealtimeChannel, realtimeChannels } from "./realtime.mjs";
 import { ApiKey, ApiKeyWithSecret, Project, ProjectBranding, ProjectContext, ProjectEnvironment, ProjectHandoffSettings, ProjectMember, ProjectSettings, ProjectStatus, VerificationThresholds } from "./project.mjs";
-import { DocumentCapture, DocumentPortrait, DocumentType, FaceMatchCheck, FaceMatchResultData, LivenessCheck, LivenessResultData, OcrAuthenticity, OcrFields, OcrResult, OcrResultData, SpoofSignals } from "./providers.mjs";
-import { DEFAULT_WORKFLOW_CONFIG, WORKFLOW_STEP_KEYS, Workflow, WorkflowConfig, WorkflowOptions, WorkflowStep, WorkflowStepKey, workflowEnabledSteps, workflowEnables, workflowRunsOcr } from "./workflow.mjs";
+import { ADDRESS_METHODS, AVAILABLE_WORKFLOW_STEP_KEYS, AddressMethod, AddressOnFail, AddressStepConfig, DEFAULT_ADDRESS_CONFIG, DEFAULT_WORKFLOW_CONFIG, WORKFLOW_STEP_KEYS, Workflow, WorkflowConfig, WorkflowOptions, WorkflowStep, WorkflowStepKey, workflowAddressConfig, workflowEnabledSteps, workflowEnables, workflowRunsOcr } from "./workflow.mjs";
+import { AddressMethodResult, AddressResultData, AddressVerification, DocumentCapture, DocumentPortrait, DocumentType, FaceMatchCheck, FaceMatchResultData, LivenessCheck, LivenessResultData, OcrAuthenticity, OcrFields, OcrResult, OcrResultData, PostalAddress, SpoofSignals } from "./providers.mjs";
 import { Review, ReviewAction, ReviewNote } from "./review.mjs";
 import { WebhookChecks, WebhookDelivery, WebhookDeliveryStatus, WebhookEndpoint, WebhookEndpointStatus, WebhookEvent, WebhookEventName } from "./webhook.mjs";
 import { ActorType, AuditLog } from "./audit.mjs";
 import { CreateSessionParams, SdkOptions, SessionResource } from "./sdk.mjs";
 import { WidgetMode, WidgetOptions, WidgetResult, WidgetStep } from "./widget.mjs";
-export { ActorType, AdminPermission, AdminPermissionGroup, AdminPermissionKey, AdminRoleSlug, AnyPermissionGroup, AnyPermissionKey, ApiKey, ApiKeyWithSecret, AuditLog, CaptureModel, CreateSessionParams, DEFAULT_GLOBAL_SETTINGS, DEFAULT_WORKFLOW_CONFIG, DecisionReason, DocumentCapture, DocumentPortrait, DocumentType, Entity, FaceMatchCheck, FaceMatchResultData, GlobalSetting, GlobalSettings, Id, InvitationStatus, IsoDate, IsoDateTime, LivenessChallenge, LivenessCheck, LivenessMode, LivenessResultData, MembershipStatus, Metadata, OcrAuthenticity, OcrFields, OcrResult, OcrResultData, Organization, OrganizationInvitation, OrganizationMember, OrganizationScoped, OrganizationSettings, Permission, PermissionGroup, PermissionKey, Project, ProjectBranding, ProjectContext, ProjectEnvironment, ProjectHandoffSettings, ProjectMember, ProjectScoped, ProjectSettings, ProjectStatus, PublicUser, REALTIME_EVENT, RealtimeEventName, RealtimeTransport, Review, ReviewAction, ReviewActionEvent, ReviewNote, Role, RolePermission, SdkOptions, SessionResource, SessionTransitionEvent, SpoofSignals, SystemRoleSlug, Timestamps, User, UserPermission, VerificationDecision, VerificationSession, VerificationStatus, VerificationThresholds, WORKFLOW_STEP_KEYS, WebhookChecks, WebhookDelivery, WebhookDeliveryStatus, WebhookEndpoint, WebhookEndpointStatus, WebhookEvent, WebhookEventName, WidgetMode, WidgetOptions, WidgetResult, WidgetStep, Workflow, WorkflowConfig, WorkflowOptions, WorkflowStep, WorkflowStepKey, parseRealtimeChannel, realtimeChannels, workflowEnabledSteps, workflowEnables, workflowRunsOcr };
+export { ADDRESS_METHODS, AVAILABLE_WORKFLOW_STEP_KEYS, ActorType, AddressMethod, AddressMethodResult, AddressOnFail, AddressResultData, AddressStepConfig, AddressVerification, AdminPermission, AdminPermissionGroup, AdminPermissionKey, AdminRoleSlug, AnyPermissionGroup, AnyPermissionKey, ApiKey, ApiKeyWithSecret, AuditLog, CaptureModel, CreateSessionParams, DEFAULT_ADDRESS_CONFIG, DEFAULT_GLOBAL_SETTINGS, DEFAULT_WORKFLOW_CONFIG, DecisionReason, DocumentCapture, DocumentPortrait, DocumentType, Entity, FaceMatchCheck, FaceMatchResultData, GlobalSetting, GlobalSettings, Id, InvitationStatus, IsoDate, IsoDateTime, LivenessChallenge, LivenessCheck, LivenessMode, LivenessResultData, MembershipStatus, Metadata, OcrAuthenticity, OcrFields, OcrResult, OcrResultData, Organization, OrganizationInvitation, OrganizationMember, OrganizationScoped, OrganizationSettings, Permission, PermissionGroup, PermissionKey, PostalAddress, Project, ProjectBranding, ProjectContext, ProjectEnvironment, ProjectHandoffSettings, ProjectMember, ProjectScoped, ProjectSettings, ProjectStatus, PublicUser, REALTIME_EVENT, RealtimeEventName, RealtimeTransport, Review, ReviewAction, ReviewActionEvent, ReviewNote, Role, RolePermission, SdkOptions, SessionResource, SessionTransitionEvent, SpoofSignals, SystemRoleSlug, Timestamps, User, UserPermission, VerificationDecision, VerificationSession, VerificationStatus, VerificationThresholds, WORKFLOW_STEP_KEYS, WebhookChecks, WebhookDelivery, WebhookDeliveryStatus, WebhookEndpoint, WebhookEndpointStatus, WebhookEvent, WebhookEventName, WidgetMode, WidgetOptions, WidgetResult, WidgetStep, Workflow, WorkflowConfig, WorkflowOptions, WorkflowStep, WorkflowStepKey, parseRealtimeChannel, realtimeChannels, workflowAddressConfig, workflowEnabledSteps, workflowEnables, workflowRunsOcr };

package/dist/index.mjs

@@ -1,4 +1,4 @@
 import { DEFAULT_GLOBAL_SETTINGS } from "./settings.mjs";
 import { REALTIME_EVENT, parseRealtimeChannel, realtimeChannels } from "./realtime.mjs";
-import { DEFAULT_WORKFLOW_CONFIG, WORKFLOW_STEP_KEYS, workflowEnabledSteps, workflowEnables, workflowRunsOcr } from "./workflow.mjs";
-export { DEFAULT_GLOBAL_SETTINGS, DEFAULT_WORKFLOW_CONFIG, REALTIME_EVENT, WORKFLOW_STEP_KEYS, parseRealtimeChannel, realtimeChannels, workflowEnabledSteps, workflowEnables, workflowRunsOcr };
+import { ADDRESS_METHODS, AVAILABLE_WORKFLOW_STEP_KEYS, DEFAULT_ADDRESS_CONFIG, DEFAULT_WORKFLOW_CONFIG, WORKFLOW_STEP_KEYS, workflowAddressConfig, workflowEnabledSteps, workflowEnables, workflowRunsOcr } from "./workflow.mjs";
+export { ADDRESS_METHODS, AVAILABLE_WORKFLOW_STEP_KEYS, DEFAULT_ADDRESS_CONFIG, DEFAULT_GLOBAL_SETTINGS, DEFAULT_WORKFLOW_CONFIG, REALTIME_EVENT, WORKFLOW_STEP_KEYS, parseRealtimeChannel, realtimeChannels, workflowAddressConfig, workflowEnabledSteps, workflowEnables, workflowRunsOcr };

package/dist/project.d.mts

@@ -16,6 +16,8 @@ interface VerificationThresholds {
   ocrConfidenceThreshold: number;
   livenessThreshold: number;
   faceMatchThreshold: number;
+  /** Minimum address-verification confidence before flagging for review. */
+  addressThreshold: number;
 }
 /** Visual branding applied to the widget for a project. */
 interface ProjectBranding {

package/dist/project.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.mts","names":[],"sources":["../src/project.ts"],"mappings":";;;;;;KAMY,kBAAA;AAAZ;AAAA,KAGY,aAAA;;;AAHkB;AAG9B;UAMiB,sBAAA;EACf,wBAAA;EACA,sBAAA;EACA,iBAAA;EACA,kBAAA;AAAA;;UAIe,eAAA;EACf,QAAA;EACA,aAAA;EACA,aAAA;EACA,KAAA;EARkB;EAUlB,IAAA;EANe;;;;EAWf,aAAA;AAAA;;;;;;UAQe,sBAAA;EAAA;EAEf,OAAA;;;AAKa;AAIf;EAJE,aAAa;AAAA;;UAIE,eAAA,SAAwB,QAAA;EACvC,UAAA,GAAa,OAAA,CAAQ,sBAAA;EACrB,eAAA;EAFuC;EAIvC,WAAA;EAJ+C;EAM/C,aAAA,GAAgB,YAAA;EALhB;EAOA,OAAA,GAAU,sBAAA;AAAA;;;;;UAOK,OAAA,SAAgB,MAAA,EAAQ,kBAAA;EACvC,IAAA;EACA,IAAA;EACA,WAAA,EAAa,kBAAA;EACb,QAAA,EAAU,eAAA;EACV,QAAA,EAAU,eAAA;EACV,MAAA,EAAQ,aAAA;EACR,YAAA;AAAA;;UAIe,aAAA,SAAsB,MAAA,EAAQ,aAAA;EAC7C,OAAA,EAAS,EAAA;EACT,OAAA,EAAS,EAAA;EACT,MAAA,EAAQ,gBAAA;AAAA;;;;;UAOO,MAAA,SAAe,MAAA,EAAQ,aAAA;EACtC,IAAA;EACA,UAAA;EACA,QAAA;EACA,YAAA,EAAc,WAAA;EACd,UAAA,EAAY,WAAA;EACZ,UAAA,EAAY,WAAA;AAAA;;UAIG,gBAAA;EACf,OAAA,EAAS,MAAM;EArBA;EAuBf,MAAA;AAAA;;UAIe,cAAA;EACf,eAAA,EAAiB,EAAA;EACjB,UAAA,EAAY,EAAA;EACZ,UAAA,GAAa,EAAA;AAAA"}
+{"version":3,"file":"project.d.mts","names":[],"sources":["../src/project.ts"],"mappings":";;;;;;KAMY,kBAAA;AAAZ;AAAA,KAGY,aAAA;;;AAHkB;AAG9B;UAMiB,sBAAA;EACf,wBAAA;EACA,sBAAA;EACA,iBAAA;EACA,kBAAA;EAJqC;EAMrC,gBAAA;AAAA;;UAIe,eAAA;EACf,QAAA;EACA,aAAA;EACA,aAAA;EACA,KAAA;EARgB;EAUhB,IAAA;EAN8B;;;;EAW9B,aAAA;AAAA;;;;;AAAa;UAQE,sBAAA;EAAsB;EAErC,OAAA;EAAA;AAKa;AAIf;;EAJE,aAAa;AAAA;;UAIE,eAAA,SAAwB,QAAA;EACvC,UAAA,GAAa,OAAA,CAAQ,sBAAA;EACrB,eAAA;EAF+C;EAI/C,WAAA;EAJuC;EAMvC,aAAA,GAAgB,YAAA;EALH;EAOb,OAAA,GAAU,sBAAA;AAAA;;;;;UAOK,OAAA,SAAgB,MAAA,EAAQ,kBAAA;EACvC,IAAA;EACA,IAAA;EACA,WAAA,EAAa,kBAAA;EACb,QAAA,EAAU,eAAA;EACV,QAAA,EAAU,eAAA;EACV,MAAA,EAAQ,aAAA;EACR,YAAA;AAAA;;UAIe,aAAA,SAAsB,MAAA,EAAQ,aAAA;EAC7C,OAAA,EAAS,EAAA;EACT,OAAA,EAAS,EAAA;EACT,MAAA,EAAQ,gBAAA;AAAA;;;;;UAOO,MAAA,SAAe,MAAA,EAAQ,aAAA;EACtC,IAAA;EACA,UAAA;EACA,QAAA;EACA,YAAA,EAAc,WAAA;EACd,UAAA,EAAY,WAAA;EACZ,UAAA,EAAY,WAAA;AAAA;;UAIG,gBAAA;EACf,OAAA,EAAS,MAAM;EArBc;EAuB7B,MAAA;AAAA;;UAIe,cAAA;EACf,eAAA,EAAiB,EAAA;EACjB,UAAA,EAAY,EAAA;EACZ,UAAA,GAAa,EAAA;AAAA"}

package/dist/providers.d.mts

@@ -1,4 +1,5 @@
 import { Entity, Id, IsoDate, ProjectScoped } from "./common.mjs";
+import { AddressMethod } from "./workflow.mjs";
 
 //#region src/providers.d.ts
 /** Supported identity document categories. */
@@ -70,6 +71,50 @@ interface FaceMatchResultData {
   confidence: number;
   raw?: unknown;
 }
+/** A normalized postal address. Any field may be absent depending on the source. */
+interface PostalAddress {
+  line1?: string;
+  line2?: string;
+  city?: string;
+  /** State / province / region. */
+  region?: string;
+  postalCode?: string;
+  /** Country as resolved (ISO code or name). */
+  country?: string;
+  /** Geocoordinates, when a method resolves them. */
+  latitude?: number;
+  longitude?: number;
+}
+/** One method's contribution to address verification. */
+interface AddressMethodResult {
+  method: AddressMethod;
+  /** Whether this method produced a usable, valid result. */
+  passed: boolean;
+  /** Method confidence in [0, 1]. */
+  confidence: number;
+  /** The address this method resolved/extracted, when any. */
+  resolved?: PostalAddress;
+  /**
+   * The provider's full, human-readable address string for the resolved hit —
+   * e.g. Nominatim's `display_name` or openrouteservice's `label`. Shown to
+   * reviewers so they see the exact place the provider detected.
+   */
+  resolvedLabel?: string;
+  /** Human-readable note (e.g. why it failed). */
+  note?: string;
+  raw?: unknown;
+}
+/** The shape returned by an address verifier — the aggregate of its methods. */
+interface AddressResultData {
+  passed: boolean;
+  /** Overall confidence in [0, 1]. */
+  score: number;
+  /** Per-method breakdown. */
+  methods: AddressMethodResult[];
+  /** Whether the methods agree (country/locality) when two or more ran. */
+  consistent: boolean;
+  raw?: unknown;
+}
 /** A captured identity document (front and optional back) for a session. */
 interface DocumentCapture extends Entity, ProjectScoped {
   session_id: Id;
@@ -116,6 +161,24 @@ interface FaceMatchCheck extends Entity, ProjectScoped {
   provider: string;
   raw_response: unknown;
 }
+/** Persisted address-verification result for a session. */
+interface AddressVerification extends Entity, ProjectScoped {
+  session_id: Id;
+  /** The address the user claimed (typed in the widget), when provided. */
+  claimed_address: PostalAddress | null;
+  /** Proof-of-address document image, when the `poa_document` method ran. */
+  document_image_path: string | null;
+  /** Captured device coordinates, when the `device_location` method ran. */
+  latitude: number | null;
+  longitude: number | null;
+  passed: boolean;
+  /** Overall confidence in [0, 1]. */
+  score: number;
+  /** Per-method breakdown. */
+  methods: AddressMethodResult[];
+  provider: string;
+  raw_response: unknown;
+}
 //#endregion
-export { DocumentCapture, DocumentPortrait, DocumentType, FaceMatchCheck, FaceMatchResultData, LivenessCheck, LivenessResultData, OcrAuthenticity, OcrFields, OcrResult, OcrResultData, SpoofSignals };
+export { AddressMethodResult, AddressResultData, AddressVerification, DocumentCapture, DocumentPortrait, DocumentType, FaceMatchCheck, FaceMatchResultData, LivenessCheck, LivenessResultData, OcrAuthenticity, OcrFields, OcrResult, OcrResultData, PostalAddress, SpoofSignals };
 //# sourceMappingURL=providers.d.mts.map

package/dist/providers.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"providers.d.mts","names":[],"sources":["../src/providers.ts"],"mappings":";;;;KAGY,YAAA;AAAZ;AAAA,UAGiB,SAAA;EACf,SAAA;EACA,QAAA;EACA,QAAA;EACA,WAAA,GAAc,OAAA;EACd,cAAA;EACA,UAAA,GAAa,OAAO;EACpB,WAAA;AAAA;;;;;;UAQe,eAAA;EATF;EAWb,OAAA;EAVW;EAYX,UAAA;EAJe;EAMf,YAAA;;EAEA,SAAA;EANA;EAQA,gBAAA;EAJA;EAMA,iBAAA;EAFA;EAIA,YAAA;AAAA;;UAIe,aAAA;EACf,MAAA,EAAQ,SAAA;EADoB;EAG5B,UAAA;EAE8B;EAA9B,YAAA,GAAe,eAAe;EAJtB;EAMR,GAAA;AAAA;;UAIe,YAAA;EACf,YAAA;EACA,YAAA;EACA,YAAA;EACA,aAAA;EACA,eAAA;EACA,YAAA;AAAA;;UAIe,kBAAA;EACf,MAAA;EANA;EAQA,KAAA;EACA,YAAA,EAAc,YAAY;EAC1B,GAAA;AAAA;;UAIe,mBAAA;EACf,MAAA;EATA;EAWA,eAAA;EARA;EAUA,UAAA;EACA,GAAA;AAAA;AAVG;AAAA,UAcY,eAAA,SAAwB,MAAA,EAAQ,aAAA;EAC/C,UAAA,EAAY,EAAA;EACZ,OAAA;EACA,aAAA,EAAe,YAAA;EACf,gBAAA;EACA,eAAA;EACA,aAAA;AAAA;;UAIe,SAAA,SAAkB,MAAA,EAAQ,aAAA;EACzC,UAAA,EAAY,EAAA;EACZ,mBAAA,EAAqB,EAAA;EACrB,MAAA,EAAQ,SAAA;EACR,UAAA;EACA,YAAA;AAAA;;UAIe,gBAAA,SAAyB,MAAA,EAAQ,aAAA;EAChD,UAAA,EAAY,EAAA;EACZ,mBAAA,EAAqB,EAAA;EACrB,mBAAA;EACA,oBAAA;AAAA;;UAIe,aAAA,SAAsB,MAAA,EAAQ,aAAA;EAC7C,UAAA,EAAY,EAAA;EACZ,iBAAA;EACA,UAAA;EACA,KAAA;EACA,MAAA;EACA,aAAA,EAAe,YAAA;EACf,QAAA;EACA,YAAA;AAAA;;UAIe,cAAA,SAAuB,MAAA,EAAQ,aAAA;EAC9C,UAAA,EAAY,EAAA;EACZ,sBAAA;EACA,iBAAA;EACA,gBAAA;EACA,UAAA;EACA,MAAA;EACA,QAAA;EACA,YAAA;AAAA"}
+{"version":3,"file":"providers.d.mts","names":[],"sources":["../src/providers.ts"],"mappings":";;;;;KAIY,YAAA;AAAZ;AAAA,UAGiB,SAAA;EACf,SAAA;EACA,QAAA;EACA,QAAA;EACA,WAAA,GAAc,OAAA;EACd,cAAA;EACA,UAAA,GAAa,OAAO;EACpB,WAAA;AAAA;;;;;;UAQe,eAAA;EATF;EAWb,OAAA;EAVW;EAYX,UAAA;EAJe;EAMf,YAAA;;EAEA,SAAA;EANA;EAQA,gBAAA;EAJA;EAMA,iBAAA;EAFA;EAIA,YAAA;AAAA;;UAIe,aAAA;EACf,MAAA,EAAQ,SAAA;EADoB;EAG5B,UAAA;EAE8B;EAA9B,YAAA,GAAe,eAAe;EAJtB;EAMR,GAAA;AAAA;;UAIe,YAAA;EACf,YAAA;EACA,YAAA;EACA,YAAA;EACA,aAAA;EACA,eAAA;EACA,YAAA;AAAA;;UAIe,kBAAA;EACf,MAAA;EANA;EAQA,KAAA;EACA,YAAA,EAAc,YAAY;EAC1B,GAAA;AAAA;;UAIe,mBAAA;EACf,MAAA;EATA;EAWA,eAAA;EARA;EAUA,UAAA;EACA,GAAA;AAAA;AAVG;AAAA,UAcY,aAAA;EACf,KAAA;EACA,KAAA;EACA,IAAA;EAZA;EAcA,MAAA;EACA,UAAA;EAVA;EAYA,OAAA;EAZG;EAcH,QAAA;EACA,SAAA;AAAA;;UAIe,mBAAA;EACf,MAAA,EAAQ,aAAA;EAbR;EAeA,MAAA;EAZA;EAcA,UAAA;EAVA;EAYA,QAAA,GAAW,aAAa;EAXf;AAAA;AAIX;;;EAaE,aAAA;EAZA;EAcA,IAAA;EACA,GAAA;AAAA;;UAIe,iBAAA;EACf,MAAA;EANA;EAQA,KAAA;EAPG;EASH,OAAA,EAAS,mBAAmB;EALb;EAOf,UAAA;EACA,GAAA;AAAA;;UAIe,eAAA,SAAwB,MAAA,EAAQ,aAAA;EAC/C,UAAA,EAAY,EAAA;EACZ,OAAA;EACA,aAAA,EAAe,YAAA;EACf,gBAAA;EACA,eAAA;EACA,aAAA;AAAA;;UAIe,SAAA,SAAkB,MAAA,EAAQ,aAAA;EACzC,UAAA,EAAY,EAAA;EACZ,mBAAA,EAAqB,EAAA;EACrB,MAAA,EAAQ,SAAA;EACR,UAAA;EACA,YAAA;AAAA;;UAIe,gBAAA,SAAyB,MAAA,EAAQ,aAAA;EAChD,UAAA,EAAY,EAAA;EACZ,mBAAA,EAAqB,EAAA;EACrB,mBAAA;EACA,oBAAA;AAAA;;UAIe,aAAA,SAAsB,MAAA,EAAQ,aAAA;EAC7C,UAAA,EAAY,EAAA;EACZ,iBAAA;EACA,UAAA;EACA,KAAA;EACA,MAAA;EACA,aAAA,EAAe,YAAA;EACf,QAAA;EACA,YAAA;AAAA;;UAIe,cAAA,SAAuB,MAAA,EAAQ,aAAA;EAC9C,UAAA,EAAY,EAAA;EACZ,sBAAA;EACA,iBAAA;EACA,gBAAA;EACA,UAAA;EACA,MAAA;EACA,QAAA;EACA,YAAA;AAAA;;UAIe,mBAAA,SAA4B,MAAA,EAAQ,aAAA;EACnD,UAAA,EAAY,EAAA;EArCA;EAuCZ,eAAA,EAAiB,aAAA;EAnCF;EAqCf,mBAAA;;EAEA,QAAA;EACA,SAAA;EACA,MAAA;EAzCgD;EA2ChD,KAAA;EA3C6D;EA6C7D,OAAA,EAAS,mBAAA;EACT,QAAA;EACA,YAAA;AAAA"}

package/dist/verification.d.mts

@@ -2,7 +2,7 @@ import { Entity, Id, IsoDateTime, Metadata, ProjectScoped } from "./common.mjs";
 
 //#region src/verification.d.ts
 /** The lifecycle state of a verification session. */
-type VerificationStatus = 'pending' | 'started' | 'document_submitted' | 'liveness_submitted' | 'processing' | 'requires_review' | 'approved' | 'rejected' | 'expired' | 'cancelled';
+type VerificationStatus = 'pending' | 'started' | 'document_submitted' | 'address_submitted' | 'liveness_submitted' | 'processing' | 'requires_review' | 'approved' | 'rejected' | 'expired' | 'cancelled';
 /** The outcome of the decision engine (or a manual review). */
 type VerificationDecision = 'approved' | 'requires_review' | 'rejected';
 /** Whether liveness is checked passively (a selfie) or actively (a challenge video). */
@@ -14,7 +14,7 @@ type LivenessMode = 'passive' | 'active';
  */
 type LivenessChallenge = 'turn_left' | 'turn_right' | 'blink' | 'smile' | 'nod' | 'move_closer';
 /** Why a session reached its decision. */
-type DecisionReason = 'AUTO_APPROVED' | 'LOW_DOCUMENT_QUALITY' | 'OCR_LOW_CONFIDENCE' | 'DOCUMENT_EXPIRED' | 'LIVENESS_FAILED' | 'LIVENESS_LOW_CONFIDENCE' | 'FACE_MATCH_FAILED' | 'FACE_MATCH_LOW_CONFIDENCE' | 'MULTIPLE_FACES_DETECTED' | 'MANUAL_APPROVAL' | 'MANUAL_REJECTION' | 'RETRY_REQUESTED';
+type DecisionReason = 'AUTO_APPROVED' | 'LOW_DOCUMENT_QUALITY' | 'OCR_LOW_CONFIDENCE' | 'DOCUMENT_EXPIRED' | 'LIVENESS_FAILED' | 'LIVENESS_LOW_CONFIDENCE' | 'FACE_MATCH_FAILED' | 'FACE_MATCH_LOW_CONFIDENCE' | 'MULTIPLE_FACES_DETECTED' | 'ADDRESS_VERIFICATION_FAILED' | 'ADDRESS_LOW_CONFIDENCE' | 'MANUAL_APPROVAL' | 'MANUAL_REJECTION' | 'RETRY_REQUESTED';
 /**
  * A verification session: the full lifecycle of one verification flow, owned by
  * a project (and organization). Created from an integrator's backend, driven by the

package/dist/verification.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"verification.d.mts","names":[],"sources":["../src/verification.ts"],"mappings":";;;;KAGY,kBAAA;AAAZ;AAAA,KAaY,oBAAA;;KAGA,YAAA;AAhBkB;AAa9B;;;;AAb8B,KAuBlB,iBAAA;AAPZ;AAAA,KAUY,cAAA;;;AAVY;AAOxB;;UAsBiB,mBAAA,SAA4B,MAAA,EAAQ,aAAA;EAtBxB;EAwB3B,cAAA;EArBU;EAuBV,IAAA;EACA,MAAA,EAAQ,kBAAA;EACR,aAAA,EAAe,oBAAA;EACf,cAAA,EAAgB,oBAAA;EAChB,eAAA,EAAiB,cAAA;EARkB;EAUnC,UAAA;EALQ;EAOR,iBAAA;EACA,UAAA,EAAY,WAAA;EACZ,YAAA,EAAc,WAAA;EACd,WAAA,EAAa,WAAA;EACb,WAAA,EAAa,EAAA;EACb,QAAA,EAAU,QAAA;AAAA"}
+{"version":3,"file":"verification.d.mts","names":[],"sources":["../src/verification.ts"],"mappings":";;;;KAGY,kBAAA;AAAZ;AAAA,KAcY,oBAAA;;KAGA,YAAA;AAjBkB;AAc9B;;;;AAd8B,KAwBlB,iBAAA;AAPZ;AAAA,KAUY,cAAA;;;AAVY;AAOxB;;UAwBiB,mBAAA,SAA4B,MAAA,EAAQ,aAAA;EAxBxB;EA0B3B,cAAA;EAvBU;EAyBV,IAAA;EACA,MAAA,EAAQ,kBAAA;EACR,aAAA,EAAe,oBAAA;EACf,cAAA,EAAgB,oBAAA;EAChB,eAAA,EAAiB,cAAA;EARkB;EAUnC,UAAA;EALQ;EAOR,iBAAA;EACA,UAAA,EAAY,WAAA;EACZ,YAAA,EAAc,WAAA;EACd,WAAA,EAAa,WAAA;EACb,WAAA,EAAa,EAAA;EACb,QAAA,EAAU,QAAA;AAAA"}

package/dist/webhook.d.mts

@@ -3,7 +3,7 @@ import { DecisionReason, VerificationStatus } from "./verification.mjs";
 
 //#region src/webhook.d.ts
 /** The set of webhook event names Arkyc can deliver. */
-type WebhookEventName = 'verification.started' | 'verification.document_submitted' | 'verification.processing' | 'verification.requires_review' | 'verification.approved' | 'verification.rejected' | 'verification.completed' | 'verification.expired' | 'verification.cancelled';
+type WebhookEventName = 'verification.started' | 'verification.document_submitted' | 'verification.address_submitted' | 'verification.processing' | 'verification.requires_review' | 'verification.approved' | 'verification.rejected' | 'verification.completed' | 'verification.expired' | 'verification.cancelled';
 /** Per-check summary included in a webhook payload. */
 interface WebhookChecks {
   document?: {
@@ -20,6 +20,11 @@ interface WebhookChecks {
     passed: boolean;
     similarity_score: number;
   };
+  address?: {
+    passed: boolean;
+    score: number; /** Which corroboration methods ran. */
+    methods: string[];
+  };
 }
 /** The JSON body delivered to a webhook endpoint. */
 interface WebhookEvent {

package/dist/webhook.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"webhook.d.mts","names":[],"sources":["../src/webhook.ts"],"mappings":";;;;;KAIY,gBAAA;AAAZ;AAAA,UAYiB,aAAA;EACf,QAAA;IACE,aAAA;IACA,cAAA;IACA,OAAA,WAJ0B;IAM1B,eAAA;EAAA;EAEF,QAAA;IACE,MAAA;IACA,KAAA;EAAA;EAEF,UAAA;IACE,MAAA;IACA,gBAAA;EAAA;AAAA;;UAKa,YAAA;EACf,KAAA,EAAO,gBAAA;EACP,UAAA,EAAY,EAAA;EACZ,eAAA,EAAiB,EAAA;EACjB,UAAA,EAAY,EAAA;EACZ,cAAA;EACA,MAAA,EAAQ,kBAAA;EACR,MAAA,EAAQ,aAAA;EACR,eAAA,EAAiB,cAAA;EAJL;EAMZ,MAAA,EAAQ,MAAA;EACR,UAAA,EAAY,WAAA;AAAA;;KAIF,qBAAA;;UAGK,eAAA,SAAwB,MAAA,EAAQ,aAAA;EAC/C,GAAA;EAlBO;EAoBP,WAAA;EACA,MAAA,EAAQ,gBAAA;EACR,MAAA,EAAQ,qBAAA;AAAA;;KAIE,qBAAA;;UAGK,eAAA,SAAwB,MAAA,EAAQ,aAAA;EAC/C,mBAAA,EAAqB,EAAA;EACrB,KAAA,EAAO,gBAAA;EACP,OAAA,EAAS,YAAA;EACT,MAAA,EAAQ,qBAAA;EACR,eAAA;EACA,aAAA;EACA,QAAA;EACA,aAAA,EAAe,WAAA;AAAA"}
+{"version":3,"file":"webhook.d.mts","names":[],"sources":["../src/webhook.ts"],"mappings":";;;;;KAIY,gBAAA;AAAZ;AAAA,UAaiB,aAAA;EACf,QAAA;IACE,aAAA;IACA,cAAA;IACA,OAAA,WAJ0B;IAM1B,eAAA;EAAA;EAEF,QAAA;IACE,MAAA;IACA,KAAA;EAAA;EAEF,UAAA;IACE,MAAA;IACA,gBAAA;EAAA;EAEF,OAAA;IACE,MAAA;IACA,KAAA,UAFF;IAIE,OAAA;EAAA;AAAA;;UAKa,YAAA;EACf,KAAA,EAAO,gBAAA;EACP,UAAA,EAAY,EAAA;EACZ,eAAA,EAAiB,EAAA;EACjB,UAAA,EAAY,EAAA;EACZ,cAAA;EACA,MAAA,EAAQ,kBAAA;EACR,MAAA,EAAQ,aAAA;EACR,eAAA,EAAiB,cAAA;EADT;EAGR,MAAA,EAAQ,MAAA;EACR,UAAA,EAAY,WAAA;AAAA;;KAIF,qBAAA;;UAGK,eAAA,SAAwB,MAAA,EAAQ,aAAA;EAC/C,GAAA;EAjBY;EAmBZ,WAAA;EACA,MAAA,EAAQ,gBAAA;EACR,MAAA,EAAQ,qBAAA;AAAA;;KAIE,qBAAA;;UAGK,eAAA,SAAwB,MAAA,EAAQ,aAAA;EAC/C,mBAAA,EAAqB,EAAA;EACrB,KAAA,EAAO,gBAAA;EACP,OAAA,EAAS,YAAA;EACT,MAAA,EAAQ,qBAAA;EACR,eAAA;EACA,aAAA;EACA,QAAA;EACA,aAAA,EAAe,WAAA;AAAA"}

package/dist/widget.d.mts

@@ -5,7 +5,7 @@ import { ProjectBranding } from "./project.mjs";
 /** How the widget mounts into the host page. */
 type WidgetMode = 'overlay' | 'inline' | 'hosted';
 /** The screens of the widget verification flow, in order. */
-type WidgetStep = 'welcome' | 'document_selection' | 'front_capture' | 'back_capture' | 'ocr_processing' | 'active_liveness' | 'selfie_capture' | 'passive_liveness' | 'face_match' | 'processing' | 'result';
+type WidgetStep = 'welcome' | 'document_selection' | 'front_capture' | 'back_capture' | 'ocr_processing' | 'address_entry' | 'address_processing' | 'active_liveness' | 'selfie_capture' | 'passive_liveness' | 'face_match' | 'processing' | 'result';
 /** The result handed to the widget's `onComplete` callback. */
 interface WidgetResult {
   status: VerificationStatus;

package/dist/widget.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"widget.d.mts","names":[],"sources":["../src/widget.ts"],"mappings":";;;;;KAIY,UAAA;AAAZ;AAAA,KAGY,UAAA;;UAcK,YAAA;EACf,MAAA,EAAQ,kBAAA;EACR,QAAA,EAAU,oBAAoB;AAAA;;UAIf,aAAA;EApBK;EAsBpB,KAAA;EACA,IAAA,GAAO,UAAA;;EAEP,SAAA,YAAqB,WAAA;EACrB,QAAA,GAAW,eAAA;EACX,OAAA;EACA,UAAA,IAAc,MAAA,EAAQ,YAAA;EACtB,OAAA,IAAW,KAAA,EAAO,KAAA;EAClB,OAAA;AAAA"}
+{"version":3,"file":"widget.d.mts","names":[],"sources":["../src/widget.ts"],"mappings":";;;;;KAIY,UAAA;AAAZ;AAAA,KAGY,UAAA;;UAgBK,YAAA;EACf,MAAA,EAAQ,kBAAA;EACR,QAAA,EAAU,oBAAoB;AAAA;;UAIf,aAAA;EAtBK;EAwBpB,KAAA;EACA,IAAA,GAAO,UAAA;;EAEP,SAAA,YAAqB,WAAA;EACrB,QAAA,GAAW,eAAA;EACX,OAAA;EACA,UAAA,IAAc,MAAA,EAAQ,YAAA;EACtB,OAAA,IAAW,KAAA,EAAO,KAAA;EAClB,OAAA;AAAA"}

package/dist/workflow.d.mts

@@ -12,13 +12,49 @@ import { Id, IsoDateTime } from "./common.mjs";
  * disturbs sessions already in flight.
  */
 /** A coarse verification stage a workflow can order and toggle. */
-type WorkflowStepKey = 'document' | 'liveness' | 'face_match';
-/** The canonical stage order used as the default and to normalise stored steps. */
+type WorkflowStepKey = 'document' | 'address' | 'liveness' | 'face_match';
+/**
+ * The default pipeline's stages, in canonical order — what runs when a session
+ * has no workflow. `address` is deliberately NOT here: it's an opt-in stage,
+ * available only on custom workflows.
+ */
 declare const WORKFLOW_STEP_KEYS: readonly WorkflowStepKey[];
+/**
+ * Every stage a custom workflow may include, in canonical order. Used by the
+ * workflow editor and to validate/normalise stored steps — a superset of
+ * {@link WORKFLOW_STEP_KEYS} that adds the opt-in `address` stage.
+ */
+declare const AVAILABLE_WORKFLOW_STEP_KEYS: readonly WorkflowStepKey[];
+/** A method the address stage uses to corroborate the user's address. */
+type AddressMethod = 'poa_document' | 'device_location' | 'geocode_lookup';
+/** Every selectable address-verification method, in display order. */
+declare const ADDRESS_METHODS: readonly AddressMethod[];
+/** What a failed/low-confidence address result does to the session. */
+type AddressOnFail = 'review' | 'reject';
+/** Configuration for the `address` stage, carried on its {@link WorkflowStep}. */
+interface AddressStepConfig {
+  /** Methods to run; at least one when the stage is enabled. */
+  methods: AddressMethod[];
+  /**
+   * What a failed or low-confidence result does. `review` (default) flags the
+   * session for a human; `reject` fails it outright.
+   */
+  on_fail: AddressOnFail;
+  /**
+   * Minimum address-verification confidence in [0, 1] to auto-verify the address.
+   * A passed address scoring below this is routed to manual review (the gate is
+   * never a rejection). Omitted falls back to the project `addressThreshold`.
+   */
+  auto_approve_threshold?: number;
+}
+/** The default address config applied when the stage is enabled without one. */
+declare const DEFAULT_ADDRESS_CONFIG: AddressStepConfig;
 /** One stage within a workflow, in pipeline order, on or off. */
 interface WorkflowStep {
   key: WorkflowStepKey;
   enabled: boolean;
+  /** Stage-specific configuration. Only the `address` stage uses this today. */
+  config?: AddressStepConfig;
 }
 /** Workflow-wide toggles. */
 interface WorkflowOptions {
@@ -50,10 +86,15 @@ declare const DEFAULT_WORKFLOW_CONFIG: WorkflowConfig;
  * absent or `enabled: false` does not run.
  */
 declare function workflowEnables(config: WorkflowConfig | null | undefined, key: WorkflowStepKey): boolean;
+/**
+ * The resolved address config for a session's workflow, or `null` when the
+ * address stage isn't enabled. Missing fields fall back to {@link DEFAULT_ADDRESS_CONFIG}.
+ */
+declare function workflowAddressConfig(config: WorkflowConfig | null | undefined): AddressStepConfig | null;
 /** Whether OCR parsing should run: the document stage is on and `skip_ocr` is off. */
 declare function workflowRunsOcr(config: WorkflowConfig | null | undefined): boolean;
 /** The enabled stages in pipeline order (used by the widget to sequence its steps). */
 declare function workflowEnabledSteps(config: WorkflowConfig | null | undefined): WorkflowStepKey[];
 //#endregion
-export { DEFAULT_WORKFLOW_CONFIG, WORKFLOW_STEP_KEYS, Workflow, WorkflowConfig, WorkflowOptions, WorkflowStep, WorkflowStepKey, workflowEnabledSteps, workflowEnables, workflowRunsOcr };
+export { ADDRESS_METHODS, AVAILABLE_WORKFLOW_STEP_KEYS, AddressMethod, AddressOnFail, AddressStepConfig, DEFAULT_ADDRESS_CONFIG, DEFAULT_WORKFLOW_CONFIG, WORKFLOW_STEP_KEYS, Workflow, WorkflowConfig, WorkflowOptions, WorkflowStep, WorkflowStepKey, workflowAddressConfig, workflowEnabledSteps, workflowEnables, workflowRunsOcr };
 //# sourceMappingURL=workflow.d.mts.map

package/dist/workflow.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.d.mts","names":[],"sources":["../src/workflow.ts"],"mappings":";;;;;AAcA;;;;AAA2B;AAG3B;;;;KAHY,eAAA;AAMZ;AAAA,cAHa,kBAAA,WAA6B,eAAe;;UAGxC,YAAA;EACf,GAAA,EAAK,eAAe;EACpB,OAAA;AAAA;;UAIe,eAAA;EAAA;;;;AAMP;EAAR,QAAQ;AAAA;;UAIO,cAAA;EACf,KAAA,EAAO,YAAA;EACP,OAAA,EAAS,eAAe;AAAA;;UAIT,QAAA,SAAiB,cAAA;EAChC,EAAA,EAAI,EAAA;EACJ,eAAA,EAAiB,EAAA;EACjB,IAAA;EACA,UAAA,EAAY,WAAA;EACZ,UAAA,EAAY,WAAA;AAAA;;cAID,uBAAA,EAAyB,cAOrC;;;;;;iBAOe,eAAA,CAAgB,MAAA,EAAQ,cAAA,qBAAmC,GAAA,EAAK,eAAe;;iBAO/E,eAAA,CAAgB,MAAyC,EAAjC,cAAc;;iBAOtC,oBAAA,CAAqB,MAAA,EAAQ,cAAA,sBAAoC,eAAe"}
+{"version":3,"file":"workflow.d.mts","names":[],"sources":["../src/workflow.ts"],"mappings":";;;;;AAcA;;;;AAA2B;AAO3B;;;;KAPY,eAAA;AAcZ;;;;AAAmE;AAAnE,cAPa,kBAAA,WAA6B,eAAe;;;;AAehC;AAGzB;cAXa,4BAAA,WAAuC,eAAe;;KAQvD,aAAA;AAGwC;AAAA,cAAvC,eAAA,WAA0B,aAAa;;KAGxC,aAAA;;UAGK,iBAAA;EAAA;EAEf,OAAA,EAAS,aAAA;;;;;EAKT,OAAA,EAAS,aAAa;EAAb;;;AAMa;AAIxB;EAJE,sBAAA;AAAA;;cAIW,sBAAA,EAAwB,iBAGpC;AAGD;AAAA,UAAiB,YAAA;EACf,GAAA,EAAK,eAAA;EACL,OAAA;EADA;EAGA,MAAA,GAAS,iBAAiB;AAAA;;UAIX,eAAA;EAJW;AAAA;AAI5B;;;EAME,QAAQ;AAAA;AAIV;AAAA,UAAiB,cAAA;EACf,KAAA,EAAO,YAAA;EACP,OAAA,EAAS,eAAe;AAAA;;UAIT,QAAA,SAAiB,cAAA;EAChC,EAAA,EAAI,EAAA;EACJ,eAAA,EAAiB,EAAA;EACjB,IAAA;EACA,UAAA,EAAY,WAAA;EACZ,UAAA,EAAY,WAAA;AAAA;;cAID,uBAAA,EAAyB,cAOrC;;;;;;iBAOe,eAAA,CAAgB,MAAA,EAAQ,cAAA,qBAAmC,GAAA,EAAK,eAAe;;;;;iBAY/E,qBAAA,CAAsB,MAAA,EAAQ,cAAA,sBAAoC,iBAAiB;;iBASnF,eAAA,CAAgB,MAAyC,EAAjC,cAAc;;iBAOtC,oBAAA,CAAqB,MAAA,EAAQ,cAAA,sBAAoC,eAAe"}

package/dist/workflow.mjs

@@ -1,10 +1,36 @@
 //#region src/workflow.ts
-/** The canonical stage order used as the default and to normalise stored steps. */
+/**
+* The default pipeline's stages, in canonical order — what runs when a session
+* has no workflow. `address` is deliberately NOT here: it's an opt-in stage,
+* available only on custom workflows.
+*/
 const WORKFLOW_STEP_KEYS = [
 	"document",
 	"liveness",
 	"face_match"
 ];
+/**
+* Every stage a custom workflow may include, in canonical order. Used by the
+* workflow editor and to validate/normalise stored steps — a superset of
+* {@link WORKFLOW_STEP_KEYS} that adds the opt-in `address` stage.
+*/
+const AVAILABLE_WORKFLOW_STEP_KEYS = [
+	"document",
+	"address",
+	"liveness",
+	"face_match"
+];
+/** Every selectable address-verification method, in display order. */
+const ADDRESS_METHODS = [
+	"poa_document",
+	"device_location",
+	"geocode_lookup"
+];
+/** The default address config applied when the stage is enabled without one. */
+const DEFAULT_ADDRESS_CONFIG = {
+	methods: ["geocode_lookup"],
+	on_fail: "review"
+};
 /** The default pipeline applied when a session has no workflow. */
 const DEFAULT_WORKFLOW_CONFIG = {
 	steps: [
@@ -29,9 +55,22 @@ const DEFAULT_WORKFLOW_CONFIG = {
 * absent or `enabled: false` does not run.
 */
 function workflowEnables(config, key) {
-	if (!config) return true;
+	if (!config) return WORKFLOW_STEP_KEYS.includes(key);
 	return config.steps.some((step) => step.key === key && step.enabled);
 }
+/**
+* The resolved address config for a session's workflow, or `null` when the
+* address stage isn't enabled. Missing fields fall back to {@link DEFAULT_ADDRESS_CONFIG}.
+*/
+function workflowAddressConfig(config) {
+	if (!config) return null;
+	const step = config.steps.find((s) => s.key === "address" && s.enabled);
+	if (!step) return null;
+	return {
+		...DEFAULT_ADDRESS_CONFIG,
+		...step.config ?? {}
+	};
+}
 /** Whether OCR parsing should run: the document stage is on and `skip_ocr` is off. */
 function workflowRunsOcr(config) {
 	if (!config) return true;
@@ -43,6 +82,6 @@ function workflowEnabledSteps(config) {
 	return config.steps.filter((step) => step.enabled).map((step) => step.key);
 }
 //#endregion
-export { DEFAULT_WORKFLOW_CONFIG, WORKFLOW_STEP_KEYS, workflowEnabledSteps, workflowEnables, workflowRunsOcr };
+export { ADDRESS_METHODS, AVAILABLE_WORKFLOW_STEP_KEYS, DEFAULT_ADDRESS_CONFIG, DEFAULT_WORKFLOW_CONFIG, WORKFLOW_STEP_KEYS, workflowAddressConfig, workflowEnabledSteps, workflowEnables, workflowRunsOcr };
 
 //# sourceMappingURL=workflow.mjs.map

package/dist/workflow.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.mjs","names":[],"sources":["../src/workflow.ts"],"sourcesContent":["import type { Id, IsoDateTime } from './common'\n\n/**\n * Workflows (Phase 19).\n *\n * An organization-scoped, reusable recipe that determines the order of the\n * coarse verification stages, lets each be turned off, and can skip OCR parsing\n * (capture-only). Workflows are optional: a session created without one runs the\n * default pipeline (document → liveness → face match, OCR on). A workflow's\n * config is snapshotted onto each session at creation, so editing it never\n * disturbs sessions already in flight.\n */\n\n/** A coarse verification stage a workflow can order and toggle. */\nexport type WorkflowStepKey = 'document' | 'liveness' | 'face_match'\n\n/** The canonical stage order used as the default and to normalise stored steps. */\nexport const WORKFLOW_STEP_KEYS: readonly WorkflowStepKey[] = ['document', 'liveness', 'face_match']\n\n/** One stage within a workflow, in pipeline order, on or off. */\nexport interface WorkflowStep {\n  key: WorkflowStepKey\n  enabled: boolean\n}\n\n/** Workflow-wide toggles. */\nexport interface WorkflowOptions {\n  /**\n   * Skip OCR parsing — capture the document image but don't extract fields.\n   * Useful when Arkyc is only used for data capture and the assets are handed\n   * to a third party. Disables the document portrait too, so face match can't run.\n   */\n  skip_ocr: boolean\n}\n\n/** The portable config of a workflow: ordered stages + options. */\nexport interface WorkflowConfig {\n  steps: WorkflowStep[]\n  options: WorkflowOptions\n}\n\n/** A saved, organization-scoped workflow. */\nexport interface Workflow extends WorkflowConfig {\n  id: Id\n  organization_id: Id\n  name: string\n  created_at: IsoDateTime\n  updated_at: IsoDateTime\n}\n\n/** The default pipeline applied when a session has no workflow. */\nexport const DEFAULT_WORKFLOW_CONFIG: WorkflowConfig = {\n  steps: [\n    { key: 'document', enabled: true },\n    { key: 'liveness', enabled: true },\n    { key: 'face_match', enabled: true },\n  ],\n  options: { skip_ocr: false },\n}\n\n/**\n * Whether a stage runs under a config. A `null` config means \"no workflow\" — the\n * default pipeline, where every stage runs. Within a real config, a stage that is\n * absent or `enabled: false` does not run.\n */\nexport function workflowEnables(config: WorkflowConfig | null | undefined, key: WorkflowStepKey): boolean {\n  if (!config) return true\n\n  return config.steps.some((step) => step.key === key && step.enabled)\n}\n\n/** Whether OCR parsing should run: the document stage is on and `skip_ocr` is off. */\nexport function workflowRunsOcr(config: WorkflowConfig | null | undefined): boolean {\n  if (!config) return true\n\n  return workflowEnables(config, 'document') && !config.options.skip_ocr\n}\n\n/** The enabled stages in pipeline order (used by the widget to sequence its steps). */\nexport function workflowEnabledSteps(config: WorkflowConfig | null | undefined): WorkflowStepKey[] {\n  if (!config) return [...WORKFLOW_STEP_KEYS]\n\n  return config.steps.filter((step) => step.enabled).map((step) => step.key)\n}\n"],"mappings":";;AAiBA,MAAa,qBAAiD;CAAC;CAAY;CAAY;AAAY;;AAkCnG,MAAa,0BAA0C;CACrD,OAAO;EACL;GAAE,KAAK;GAAY,SAAS;EAAK;EACjC;GAAE,KAAK;GAAY,SAAS;EAAK;EACjC;GAAE,KAAK;GAAc,SAAS;EAAK;CACrC;CACA,SAAS,EAAE,UAAU,MAAM;AAC7B;;;;;;AAOA,SAAgB,gBAAgB,QAA2C,KAA+B;CACxG,IAAI,CAAC,QAAQ,OAAO;CAEpB,OAAO,OAAO,MAAM,MAAM,SAAS,KAAK,QAAQ,OAAO,KAAK,OAAO;AACrE;;AAGA,SAAgB,gBAAgB,QAAoD;CAClF,IAAI,CAAC,QAAQ,OAAO;CAEpB,OAAO,gBAAgB,QAAQ,UAAU,KAAK,CAAC,OAAO,QAAQ;AAChE;;AAGA,SAAgB,qBAAqB,QAA8D;CACjG,IAAI,CAAC,QAAQ,OAAO,CAAC,GAAG,kBAAkB;CAE1C,OAAO,OAAO,MAAM,QAAQ,SAAS,KAAK,OAAO,CAAC,CAAC,KAAK,SAAS,KAAK,GAAG;AAC3E"}
+{"version":3,"file":"workflow.mjs","names":[],"sources":["../src/workflow.ts"],"sourcesContent":["import type { Id, IsoDateTime } from './common'\n\n/**\n * Workflows (Phase 19).\n *\n * An organization-scoped, reusable recipe that determines the order of the\n * coarse verification stages, lets each be turned off, and can skip OCR parsing\n * (capture-only). Workflows are optional: a session created without one runs the\n * default pipeline (document → liveness → face match, OCR on). A workflow's\n * config is snapshotted onto each session at creation, so editing it never\n * disturbs sessions already in flight.\n */\n\n/** A coarse verification stage a workflow can order and toggle. */\nexport type WorkflowStepKey = 'document' | 'address' | 'liveness' | 'face_match'\n\n/**\n * The default pipeline's stages, in canonical order — what runs when a session\n * has no workflow. `address` is deliberately NOT here: it's an opt-in stage,\n * available only on custom workflows.\n */\nexport const WORKFLOW_STEP_KEYS: readonly WorkflowStepKey[] = ['document', 'liveness', 'face_match']\n\n/**\n * Every stage a custom workflow may include, in canonical order. Used by the\n * workflow editor and to validate/normalise stored steps — a superset of\n * {@link WORKFLOW_STEP_KEYS} that adds the opt-in `address` stage.\n */\nexport const AVAILABLE_WORKFLOW_STEP_KEYS: readonly WorkflowStepKey[] = [\n  'document',\n  'address',\n  'liveness',\n  'face_match',\n]\n\n/** A method the address stage uses to corroborate the user's address. */\nexport type AddressMethod = 'poa_document' | 'device_location' | 'geocode_lookup'\n\n/** Every selectable address-verification method, in display order. */\nexport const ADDRESS_METHODS: readonly AddressMethod[] = ['poa_document', 'device_location', 'geocode_lookup']\n\n/** What a failed/low-confidence address result does to the session. */\nexport type AddressOnFail = 'review' | 'reject'\n\n/** Configuration for the `address` stage, carried on its {@link WorkflowStep}. */\nexport interface AddressStepConfig {\n  /** Methods to run; at least one when the stage is enabled. */\n  methods: AddressMethod[]\n  /**\n   * What a failed or low-confidence result does. `review` (default) flags the\n   * session for a human; `reject` fails it outright.\n   */\n  on_fail: AddressOnFail\n  /**\n   * Minimum address-verification confidence in [0, 1] to auto-verify the address.\n   * A passed address scoring below this is routed to manual review (the gate is\n   * never a rejection). Omitted falls back to the project `addressThreshold`.\n   */\n  auto_approve_threshold?: number\n}\n\n/** The default address config applied when the stage is enabled without one. */\nexport const DEFAULT_ADDRESS_CONFIG: AddressStepConfig = {\n  methods: ['geocode_lookup'],\n  on_fail: 'review',\n}\n\n/** One stage within a workflow, in pipeline order, on or off. */\nexport interface WorkflowStep {\n  key: WorkflowStepKey\n  enabled: boolean\n  /** Stage-specific configuration. Only the `address` stage uses this today. */\n  config?: AddressStepConfig\n}\n\n/** Workflow-wide toggles. */\nexport interface WorkflowOptions {\n  /**\n   * Skip OCR parsing — capture the document image but don't extract fields.\n   * Useful when Arkyc is only used for data capture and the assets are handed\n   * to a third party. Disables the document portrait too, so face match can't run.\n   */\n  skip_ocr: boolean\n}\n\n/** The portable config of a workflow: ordered stages + options. */\nexport interface WorkflowConfig {\n  steps: WorkflowStep[]\n  options: WorkflowOptions\n}\n\n/** A saved, organization-scoped workflow. */\nexport interface Workflow extends WorkflowConfig {\n  id: Id\n  organization_id: Id\n  name: string\n  created_at: IsoDateTime\n  updated_at: IsoDateTime\n}\n\n/** The default pipeline applied when a session has no workflow. */\nexport const DEFAULT_WORKFLOW_CONFIG: WorkflowConfig = {\n  steps: [\n    { key: 'document', enabled: true },\n    { key: 'liveness', enabled: true },\n    { key: 'face_match', enabled: true },\n  ],\n  options: { skip_ocr: false },\n}\n\n/**\n * Whether a stage runs under a config. A `null` config means \"no workflow\" — the\n * default pipeline, where every stage runs. Within a real config, a stage that is\n * absent or `enabled: false` does not run.\n */\nexport function workflowEnables(config: WorkflowConfig | null | undefined, key: WorkflowStepKey): boolean {\n  // No workflow runs the default pipeline only — opt-in stages (`address`) are\n  // off unless a custom workflow turns them on.\n  if (!config) return WORKFLOW_STEP_KEYS.includes(key)\n\n  return config.steps.some((step) => step.key === key && step.enabled)\n}\n\n/**\n * The resolved address config for a session's workflow, or `null` when the\n * address stage isn't enabled. Missing fields fall back to {@link DEFAULT_ADDRESS_CONFIG}.\n */\nexport function workflowAddressConfig(config: WorkflowConfig | null | undefined): AddressStepConfig | null {\n  if (!config) return null\n  const step = config.steps.find((s) => s.key === 'address' && s.enabled)\n  if (!step) return null\n\n  return { ...DEFAULT_ADDRESS_CONFIG, ...(step.config ?? {}) }\n}\n\n/** Whether OCR parsing should run: the document stage is on and `skip_ocr` is off. */\nexport function workflowRunsOcr(config: WorkflowConfig | null | undefined): boolean {\n  if (!config) return true\n\n  return workflowEnables(config, 'document') && !config.options.skip_ocr\n}\n\n/** The enabled stages in pipeline order (used by the widget to sequence its steps). */\nexport function workflowEnabledSteps(config: WorkflowConfig | null | undefined): WorkflowStepKey[] {\n  if (!config) return [...WORKFLOW_STEP_KEYS]\n\n  return config.steps.filter((step) => step.enabled).map((step) => step.key)\n}\n"],"mappings":";;;;;;AAqBA,MAAa,qBAAiD;CAAC;CAAY;CAAY;AAAY;;;;;;AAOnG,MAAa,+BAA2D;CACtE;CACA;CACA;CACA;AACF;;AAMA,MAAa,kBAA4C;CAAC;CAAgB;CAAmB;AAAgB;;AAuB7G,MAAa,yBAA4C;CACvD,SAAS,CAAC,gBAAgB;CAC1B,SAAS;AACX;;AAoCA,MAAa,0BAA0C;CACrD,OAAO;EACL;GAAE,KAAK;GAAY,SAAS;EAAK;EACjC;GAAE,KAAK;GAAY,SAAS;EAAK;EACjC;GAAE,KAAK;GAAc,SAAS;EAAK;CACrC;CACA,SAAS,EAAE,UAAU,MAAM;AAC7B;;;;;;AAOA,SAAgB,gBAAgB,QAA2C,KAA+B;CAGxG,IAAI,CAAC,QAAQ,OAAO,mBAAmB,SAAS,GAAG;CAEnD,OAAO,OAAO,MAAM,MAAM,SAAS,KAAK,QAAQ,OAAO,KAAK,OAAO;AACrE;;;;;AAMA,SAAgB,sBAAsB,QAAqE;CACzG,IAAI,CAAC,QAAQ,OAAO;CACpB,MAAM,OAAO,OAAO,MAAM,MAAM,MAAM,EAAE,QAAQ,aAAa,EAAE,OAAO;CACtE,IAAI,CAAC,MAAM,OAAO;CAElB,OAAO;EAAE,GAAG;EAAwB,GAAI,KAAK,UAAU,CAAC;CAAG;AAC7D;;AAGA,SAAgB,gBAAgB,QAAoD;CAClF,IAAI,CAAC,QAAQ,OAAO;CAEpB,OAAO,gBAAgB,QAAQ,UAAU,KAAK,CAAC,OAAO,QAAQ;AAChE;;AAGA,SAAgB,qBAAqB,QAA8D;CACjG,IAAI,CAAC,QAAQ,OAAO,CAAC,GAAG,kBAAkB;CAE1C,OAAO,OAAO,MAAM,QAAQ,SAAS,KAAK,OAAO,CAAC,CAAC,KAAK,SAAS,KAAK,GAAG;AAC3E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkyc/types",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Shared domain types and contracts for Arkyc",
   "license": "MIT",
   "type": "module",