@josephomills/esign 0.2.2

package/dist/ports-DtICqgEf.d.ts

@@ -0,0 +1,553 @@
+import { z } from 'zod';
+
+/**
+ * Lifecycle of a single signing request. PENDING/VIEWED are the only active
+ * states; SIGNED/DECLINED/EXPIRED/REVOKED are terminal. The submit handler is
+ * idempotent, so a no-op transition to the same state is always allowed.
+ */
+type EsignStatus = "PENDING" | "VIEWED" | "SIGNED" | "DECLINED" | "EXPIRED" | "REVOKED";
+declare const ESIGN_STATUSES: readonly EsignStatus[];
+/** Active (still-actionable) states — eligible for view/sign/decline. */
+declare const ACTIVE_STATUSES: readonly EsignStatus[];
+/** Terminal states — no further transitions. */
+declare const TERMINAL_STATUSES: readonly EsignStatus[];
+declare function isActive(status: EsignStatus): boolean;
+declare function isTerminal(status: EsignStatus): boolean;
+/** Whether `from → to` is a legal move (a same-state no-op counts as legal). */
+declare function canTransition(from: EsignStatus, to: EsignStatus): boolean;
+/** Throw `EsignError('CONFLICT')` on an illegal transition. */
+declare function assertTransition(from: EsignStatus, to: EsignStatus): void;
+
+type EsignChannel = "EMAIL" | "TELEGRAM" | "SMS" | "WHATSAPP";
+declare const ESIGN_CHANNELS: readonly EsignChannel[];
+declare const esignChannelSchema: z.ZodEnum<["EMAIL", "TELEGRAM", "SMS", "WHATSAPP"]>;
+interface Placement {
+    page: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+declare const placementSchema: z.ZodObject<{
+    page: z.ZodNumber;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    w: z.ZodNumber;
+    h: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    page: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, {
+    page: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}>;
+/** A resolved recipient — the only thing the fan-out needs. subjectId = the host's profileId. */
+interface Recipient {
+    name: string;
+    email?: string | null;
+    /** Phone for SMS (and WhatsApp when `whatsapp` is absent). */
+    phone?: string | null;
+    whatsapp?: string | null;
+    subjectType: string;
+    subjectId: string;
+    /** Snapshot of the targeted classification, persisted as SigningRequest.subjectGroup. */
+    group?: string | null;
+}
+/** A subject row rendered by the targeting picker. */
+interface SubjectSummary {
+    subjectType: string;
+    subjectId: string;
+    label: string;
+    sublabel?: string;
+    group?: string | null;
+    groupLabel?: string | null;
+    eligible: boolean;
+    ineligibleReason?: string;
+}
+/** A subject that could not be sent to at resolve time. */
+interface SkippedSubject {
+    subjectType: string;
+    subjectId: string;
+    label: string;
+    reason: string;
+}
+/** A declarative filter facet the picker renders as a control. */
+interface SubjectFilterField {
+    key: string;
+    label: string;
+    kind: "enum" | "boolean" | "text" | "scope";
+    options?: {
+        value: string;
+        label: string;
+    }[];
+}
+type SubjectFilter = Record<string, string | boolean | string[] | undefined>;
+/**
+ * How a target is expressed. "all" sends to the whole group (optionally a
+ * classification + filters); "ids" sends to an explicit subset.
+ */
+type SubjectSelection = {
+    mode: "all";
+    type: string;
+    group?: string;
+    filter?: SubjectFilter;
+} | {
+    mode: "ids";
+    type: string;
+    subjectIds: string[];
+};
+declare const subjectSelectionSchema: z.ZodType<SubjectSelection>;
+/** Restrict a resend to a subset of the live group, diffed against existing requests. */
+type ResendPolicy = "all" | "outstanding" | "olderVersion" | "uncovered";
+/** Whether a green-check requires the current version or any version. */
+type VersionPolicy = "current" | "any";
+interface SigningDocumentDTO {
+    id: string;
+    scopeId: string | null;
+    documentType: string | null;
+    title: string;
+    audience: SubjectSelection | null;
+    currentVersionId: string | null;
+    createdById: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface SigningDocumentVersionDTO {
+    id: string;
+    documentId: string;
+    version: number;
+    sourceObjectKey: string;
+    sourceSha256: string;
+    placement: Placement;
+    changeNote: string | null;
+    createdById: string | null;
+    createdAt: string;
+}
+interface SigningCampaignDTO {
+    id: string;
+    documentId: string;
+    documentVersionId: string;
+    scopeId: string | null;
+    note: string | null;
+    emailReceipt: boolean;
+    targeting: SubjectSelection;
+    expiresAt: string;
+    createdById: string | null;
+    createdAt: string;
+}
+interface SigningRequestDTO {
+    id: string;
+    campaignId: string;
+    documentId: string;
+    documentVersionId: string;
+    scopeId: string | null;
+    subjectType: string;
+    subjectId: string;
+    subjectGroup: string | null;
+    recipientName: string;
+    recipientEmail: string | null;
+    recipientWhatsapp: string | null;
+    channels: EsignChannel[];
+    status: EsignStatus;
+    viewedAt: string | null;
+    signedAt: string | null;
+    declinedAt: string | null;
+    expiresAt: string;
+    revokedAt: string | null;
+    sealedObjectKey: string | null;
+    sealedSha256: string | null;
+    createdAt: string;
+}
+interface SigningAuditEventDTO {
+    id: string;
+    requestId: string;
+    seq: number;
+    type: string;
+    payload: unknown;
+    prevHash: string | null;
+    hash: string;
+    occurredAt: string;
+}
+type SubjectSigningState = "NONE" | "PENDING" | "VIEWED" | "SIGNED" | "DECLINED" | "NEEDS_RESIGN";
+interface SubjectSigningStatus {
+    state: SubjectSigningState;
+    signedAt: string | null;
+    signedVersion: number | null;
+    requestId: string | null;
+    sealedObjectKey: string | null;
+}
+type StatusCountMap = Record<EsignStatus, number>;
+interface OutstandingRequest {
+    id: string;
+    campaignId: string;
+    documentId: string;
+    subjectType: string;
+    subjectId: string;
+    recipientName: string;
+    channels: EsignChannel[];
+    status: Extract<EsignStatus, "PENDING" | "VIEWED">;
+    viewedAt: string | null;
+    createdAt: string;
+    expiresAt: string;
+}
+interface GroupBreakdown {
+    group: string | null;
+    counts: StatusCountMap;
+    total: number;
+}
+interface CampaignStatsRow {
+    campaignId: string;
+    counts: StatusCountMap;
+    total: number;
+    viewedNotSigned: number;
+    completionRate: number;
+    avgTimeToSignMs: number | null;
+    byGroup: GroupBreakdown[];
+    outstanding: OutstandingRequest[];
+}
+interface DocumentStatsRow {
+    documentId: string;
+    counts: StatusCountMap;
+    total: number;
+    completionRate: number;
+    byGroup: GroupBreakdown[];
+    bySubjectType: {
+        subjectType: string;
+        counts: StatusCountMap;
+        total: number;
+    }[];
+}
+interface ScopeStatsRow {
+    campaignsSent: number;
+    requestsSent: number;
+    counts: StatusCountMap;
+    completionRate: number;
+    bySubjectType: {
+        subjectType: string;
+        counts: StatusCountMap;
+        total: number;
+    }[];
+    oldestOutstanding: OutstandingRequest[];
+}
+interface StatsRange {
+    from?: Date;
+    to?: Date;
+}
+/** documentCoverage() result — re-derived from the live group every call. */
+interface CoverageReport {
+    documentId: string;
+    totalNow: number;
+    signed: number;
+    outstanding: number;
+    needsResign: number;
+    uncovered: SubjectSummary[];
+    departed: {
+        subjectType: string;
+        subjectId: string;
+    }[];
+}
+/** A drawn or typed signature, as a PNG data URL produced by the signer UI. */
+declare const submitSignatureSchema: z.ZodObject<{
+    signaturePng: z.ZodString;
+    signerName: z.ZodString;
+    consent: z.ZodLiteral<true>;
+}, "strict", z.ZodTypeAny, {
+    signaturePng: string;
+    signerName: string;
+    consent: true;
+}, {
+    signaturePng: string;
+    signerName: string;
+    consent: true;
+}>;
+type SubmitSignatureInput = z.infer<typeof submitSignatureSchema>;
+declare const declineSchema: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    reason?: string | undefined;
+}, {
+    reason?: string | undefined;
+}>;
+type DeclineInput = z.infer<typeof declineSchema>;
+
+interface AuthPort<S> {
+    /** Resolve the request's principal, or throw EsignError('UNAUTHENTICATED'). */
+    requireAuth(req: Request): Promise<S>;
+    /** True when the scope may manage documents / send campaigns. */
+    isAdmin(scope: S): boolean;
+    /** Opaque user id used to attribute documents, versions, campaigns. */
+    userId(scope: S): string;
+    /** Optional opaque scope key (estate id / country id) for row scoping. */
+    scopeId?(scope: S): string | null;
+}
+interface StoragePort {
+    /** Short-lived signed PUT URL for the browser to upload a source PDF. */
+    presignPut(input: {
+        objectKey: string;
+        contentType: string;
+        ttlS: number;
+    }): Promise<{
+        uploadUrl: string;
+    }>;
+    /** Read an object's bytes (source PDF for sealing / serving). null = 404. */
+    get(objectKey: string): Promise<{
+        bytes: Uint8Array;
+        contentType?: string;
+    } | null>;
+    /** Write bytes server-side (the sealed PDF). */
+    put(input: {
+        objectKey: string;
+        bytes: Uint8Array;
+        contentType: string;
+    }): Promise<void>;
+    /** Best-effort delete. */
+    delete(objectKey: string): Promise<void>;
+    /** HMAC-stamp a fresh source-upload key so a presigned key can't be reused elsewhere. */
+    stampKey(parts: {
+        scopeId?: string | null;
+        documentId: string;
+        contentType: string;
+    }): string;
+    /** Verify a stamped key matches the expected document. */
+    verifyKey(stampedKey: string, parts: {
+        documentId: string;
+    }): boolean;
+    /** Deterministic key for a sealed request PDF. */
+    sealedKey(parts: {
+        scopeId?: string | null;
+        campaignId: string;
+        requestId: string;
+    }): string;
+    /** Optional upper bound for an uploaded source PDF (bytes). */
+    maxBytes?(): number;
+}
+interface NotifierAttachment {
+    filename: string;
+    content: Uint8Array;
+    contentType: string;
+}
+interface NotifierPort {
+    send(input: {
+        channel: EsignChannel;
+        recipient: string;
+        subject: string;
+        body: string;
+        actionUrl?: string;
+        idempotencyKey: string;
+        attachments?: NotifierAttachment[];
+    }): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Channels with live credentials — the targeting UI offers only these. */
+    configuredChannels(): EsignChannel[];
+}
+interface SubjectTypeDescriptor {
+    type: string;
+    label: string;
+    pluralLabel?: string;
+    /** The primary classification facet (e.g. missionary support tier, employment type). */
+    groupField?: SubjectFilterField;
+    /** Secondary facets rendered as filter controls. */
+    filterFields?: SubjectFilterField[];
+    /** Paginated, channel-aware enumeration for the picker. */
+    listSubjects(args: {
+        scopeId?: string | null;
+        group?: string;
+        filter?: SubjectFilter;
+        channels?: EsignChannel[];
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        subjects: SubjectSummary[];
+        nextCursor?: string;
+        total?: number;
+    }>;
+    /** Lean id-only enumeration for coverage diffs. */
+    listSubjectIds(args: {
+        scopeId?: string | null;
+        selection: SubjectSelection;
+    }): Promise<string[]>;
+    /** Counts for the review step without materializing recipients. */
+    countSubjects(args: {
+        scopeId?: string | null;
+        selection: SubjectSelection;
+        channels?: EsignChannel[];
+    }): Promise<{
+        total: number;
+        eligible: number;
+        ineligible: number;
+    }>;
+    /** Authoritative send-time resolution: who to send to, and who was skipped. */
+    resolveRecipients(args: {
+        scopeId?: string | null;
+        selection: SubjectSelection;
+        channels?: EsignChannel[];
+    }): Promise<{
+        recipients: Recipient[];
+        skipped: SkippedSubject[];
+    }>;
+}
+interface SubjectsPort {
+    types: SubjectTypeDescriptor[];
+    get(type: string): SubjectTypeDescriptor | undefined;
+}
+interface NewRequestRow {
+    /** Minted by the engine (createRequests returns void), so the fan-out knows it. */
+    id: string;
+    campaignId: string;
+    documentId: string;
+    documentVersionId: string;
+    scopeId: string | null;
+    subjectType: string;
+    subjectId: string;
+    subjectGroup: string | null;
+    recipientName: string;
+    recipientEmail: string | null;
+    recipientWhatsapp: string | null;
+    channels: EsignChannel[];
+    tokenHash: string;
+    expiresAt: Date;
+}
+interface NewAuditEventRow {
+    requestId: string;
+    seq: number;
+    type: string;
+    payload: unknown;
+    prevHash: string | null;
+    hash: string;
+}
+interface RequestSummary {
+    subjectId: string;
+    status: EsignStatus;
+    version: number;
+    signedAt: string | null;
+}
+interface PersistencePort {
+    createDocument(input: {
+        scopeId: string | null;
+        documentType: string | null;
+        title: string;
+        audience: SubjectSelection | null;
+        createdById: string | null;
+    }): Promise<SigningDocumentDTO>;
+    getDocument(id: string): Promise<SigningDocumentDTO | null>;
+    updateDocument(id: string, patch: Partial<Pick<SigningDocumentDTO, "title" | "audience" | "currentVersionId">>): Promise<SigningDocumentDTO>;
+    listDocuments(opts: {
+        scopeId?: string | null;
+        documentType?: string;
+    }): Promise<SigningDocumentDTO[]>;
+    createVersion(input: {
+        documentId: string;
+        version: number;
+        sourceObjectKey: string;
+        sourceSha256: string;
+        placement: Placement;
+        changeNote: string | null;
+        createdById: string | null;
+    }): Promise<SigningDocumentVersionDTO>;
+    getVersion(id: string): Promise<SigningDocumentVersionDTO | null>;
+    listVersions(documentId: string): Promise<SigningDocumentVersionDTO[]>;
+    latestVersion(documentId: string): Promise<SigningDocumentVersionDTO | null>;
+    createCampaign(input: {
+        documentId: string;
+        documentVersionId: string;
+        scopeId: string | null;
+        note: string | null;
+        emailReceipt: boolean;
+        targeting: SubjectSelection;
+        expiresAt: Date;
+        createdById: string | null;
+    }): Promise<SigningCampaignDTO>;
+    getCampaign(id: string): Promise<SigningCampaignDTO | null>;
+    listCampaigns(documentId: string): Promise<SigningCampaignDTO[]>;
+    createRequests(rows: NewRequestRow[]): Promise<void>;
+    getRequest(id: string): Promise<SigningRequestDTO | null>;
+    findRequestByTokenHash(tokenHash: string): Promise<SigningRequestDTO | null>;
+    updateRequest(id: string, patch: Partial<{
+        status: EsignStatus;
+        viewedAt: Date;
+        signedAt: Date;
+        declinedAt: Date;
+        declineReason: string;
+        revokedAt: Date;
+        signerName: string;
+        signerIp: string;
+        signerUserAgent: string;
+        sealedObjectKey: string;
+        sealedSha256: string;
+        finalAuditHash: string;
+    }>): Promise<SigningRequestDTO>;
+    listRequests(opts: {
+        campaignId?: string;
+        documentId?: string;
+        subjectType?: string;
+        subjectId?: string;
+    }): Promise<SigningRequestDTO[]>;
+    /** Latest request per subject for a document — powers coverage + version-aware status. */
+    requestSummaryBySubject(documentId: string): Promise<RequestSummary[]>;
+    appendAuditEvent(row: NewAuditEventRow): Promise<SigningAuditEventDTO>;
+    listAuditEvents(requestId: string): Promise<SigningAuditEventDTO[]>;
+    lastAuditHash(requestId: string): Promise<{
+        seq: number;
+        hash: string;
+    } | null>;
+    subjectSigningStatus(args: {
+        subjectType: string;
+        subjectId: string;
+        documentId?: string;
+        documentType?: string;
+        versionPolicy: VersionPolicy;
+    }): Promise<SubjectSigningStatus>;
+    campaignStats(campaignId: string): Promise<CampaignStatsRow>;
+    documentStats(documentId: string): Promise<DocumentStatsRow>;
+    scopeStats(scopeId: string | null, range?: StatsRange): Promise<ScopeStatsRow>;
+    outstandingRequests(filter: {
+        scopeId?: string | null;
+        documentId?: string;
+        campaignId?: string;
+        now: Date;
+        limit?: number;
+    }): Promise<OutstandingRequest[]>;
+}
+interface HooksPort {
+    onRequestViewed?(req: SigningRequestDTO): Promise<void> | void;
+    onRequestSigned?(event: {
+        subjectType: string;
+        subjectId: string;
+        documentId: string;
+        documentType: string | null;
+        requestId: string;
+        sealedObjectKey: string;
+        signedAt: string;
+    }): Promise<void> | void;
+    onRequestDeclined?(req: SigningRequestDTO): Promise<void> | void;
+}
+interface Clock {
+    now(): Date;
+}
+interface EsignConfig<S> {
+    persistence: PersistencePort;
+    storage: StoragePort;
+    notifier: NotifierPort;
+    auth: AuthPort<S>;
+    subjects: SubjectsPort;
+    hooks?: HooksPort;
+    clock?: Clock;
+    /** Absolute origin used to build the `/sign/<token>` link, e.g. https://estates.app. */
+    baseUrl: string;
+    /** Base path the host mounts the package routes under. Default `/api/esign`. */
+    routeBasePath?: string;
+    /** TTL (seconds) for presigned source-PDF uploads. Default 900. */
+    presignTtlS?: number;
+    /** Default signing-link lifetime in days. Default 30. */
+    defaultExpiryDays?: number;
+}
+
+export { submitSignatureSchema as $, ACTIVE_STATUSES as A, type StatusCountMap as B, type Clock as C, type DocumentStatsRow as D, type EsignChannel as E, type SubjectFilter as F, type GroupBreakdown as G, type HooksPort as H, type SubjectFilterField as I, type SubjectSigningState as J, type SubjectSummary as K, type SubmitSignatureInput as L, assertTransition as M, type NotifierPort as N, type OutstandingRequest as O, type PersistencePort as P, canTransition as Q, type ResendPolicy as R, type SubjectSelection as S, TERMINAL_STATUSES as T, declineSchema as U, type VersionPolicy as V, esignChannelSchema as W, isActive as X, isTerminal as Y, placementSchema as Z, subjectSelectionSchema as _, type SubjectsPort as a, type SkippedSubject as b, type Placement as c, type StoragePort as d, type SigningDocumentVersionDTO as e, type SigningDocumentDTO as f, type SigningRequestDTO as g, type EsignConfig as h, type SubjectSigningStatus as i, type CoverageReport as j, type CampaignStatsRow as k, type StatsRange as l, type ScopeStatsRow as m, type SubjectTypeDescriptor as n, type AuthPort as o, type DeclineInput as p, ESIGN_CHANNELS as q, ESIGN_STATUSES as r, type EsignStatus as s, type NewAuditEventRow as t, type NewRequestRow as u, type NotifierAttachment as v, type Recipient as w, type RequestSummary as x, type SigningAuditEventDTO as y, type SigningCampaignDTO as z };