Straight-Through Contract Execution via API: Zero-Touch Agreements (2026)

import crypto from "crypto";
import { z } from "zod";

// ---------------------------------------------------------------------------
// 1. SCHEMAS & INTERFACES
// ---------------------------------------------------------------------------
export const ContractInputSchema = z.object({
  dealId: z.string().uuid(),
  vendorCompanyName: z.string().min(2),
  signatoryName: z.string().min(2),
  signatoryEmail: z.string().email(),
  governingLawState: z.string().default("Delaware"),
  termMonths: z.number().int().positive().default(24),
  customConfidentialityCarveouts: z.array(z.string()).optional(),
});

export type ContractInput = z.infer<typeof ContractInputSchema>;

export interface SignbeeSendPayload {
  content: string;
  senderName: string;
  senderEmail: string;
  recipientName: string;
  recipientEmail: string;
  metadata?: Record<string, unknown>;
  callbackUrl?: string;
  expiresInDays?: number;
}

export interface SignbeeSendResponse {
  id: string;
  status: "pending" | "signed" | "completed";
  signing_url?: string;
  created_at: string;
}

// ---------------------------------------------------------------------------
// 2. DYNAMIC MARKDOWN HYDRATION ENGINE
// ---------------------------------------------------------------------------
export class ContractHydrationEngine {
  /**
   * Compiles strict, parameterized Markdown legal templates deterministically.
   */
  public static hydrateMutualNDA(input: ContractInput): string {
    const formattedDate = new Date().toLocaleDateString("en-US", {
      year: "numeric",
      month: "long",
      day: "numeric",
    });

    const carveouts = input.customConfidentialityCarveouts?.length
      ? input.customConfidentialityCarveouts.map((item) => `- ${item}`).join("\n")
      : "- Standard industry residual knowledge exclusions apply.";

    return `# MUTUAL NONDISCLOSURE AGREEMENT

This Mutual Nondisclosure Agreement ("Agreement") is executed and entered into as of **${formattedDate}** (the "Effective Date") by and between:

- **Host Corporation Inc.**, a Delaware corporation ("Disclosing Party" / "Host")
- **${input.vendorCompanyName}**, a duly registered entity ("Receiving Party" / "Vendor")

---

### 1. Purpose & Scope of Confidentiality
The parties wish to explore a potential technology integration, software evaluation, or business partnership (the "Authorized Purpose"). In connection with the Authorized Purpose, each party may disclose technical specifications, API schemas, financial projections, and proprietary algorithms ("Confidential Information").

### 2. Standard of Care & Nondisclosure
The Receiving Party agrees to protect the Disclosing Party's Confidential Information with the same degree of care it uses for its own confidential information, but in no event less than reasonable care.

### 3. Term & Survival
The obligations of confidentiality under this Agreement shall remain in effect for a period of **${input.termMonths} months** from the Effective Date.

### 4. Custom Carveouts & Clarifications
${carveouts}

### 5. Governing Law
This Agreement shall be governed by and construed under the laws of the State of **${input.governingLawState}**, without regard to conflict of law principles.

---

### EXECUTION & ATTESTATION
By applying an electronic signature below, both parties confirm their intention to enter into this legally binding agreement pursuant to the ESIGN Act and eIDAS Regulation.
`;
  }
}

// ---------------------------------------------------------------------------
// 3. RESILIENT STRAIGHT-THROUGH DISPATCHER (With Exponential Backoff & Jitter)
// ---------------------------------------------------------------------------
export class StraightThroughContractDispatcher {
  private readonly apiKey: string;
  private readonly apiBaseUrl: string;
  private readonly maxRetries: number;

  constructor(
    apiKey = process.env.SIGNBEE_API_KEY!,
    apiBaseUrl = "https://signb.ee/api",
    maxRetries = 5
  ) {
    if (!apiKey) throw new Error("SIGNBEE_API_KEY environment variable is required.");
    this.apiKey = apiKey;
    this.apiBaseUrl = apiBaseUrl;
    this.maxRetries = maxRetries;
  }

  /**
   * Generates a deterministic idempotency key based on transaction state.
   */
  private generateIdempotencyKey(input: ContractInput): string {
    const raw = `${input.dealId}:${input.vendorCompanyName}:${input.signatoryEmail}`;
    return crypto.createHash("sha256").update(raw).digest("hex");
  }

  /**
   * Dispatches the contract with exponential backoff, jitter, and idempotency protection.
   */
  public async dispatchContract(input: ContractInput): Promise<SignbeeSendResponse> {
    const validatedInput = ContractInputSchema.parse(input);
    const markdownContent = ContractHydrationEngine.hydrateMutualNDA(validatedInput);
    const idempotencyKey = this.generateIdempotencyKey(validatedInput);

    const payload: SignbeeSendPayload = {
      content: markdownContent,
      senderName: "Host Corporation Automated Signer",
      senderEmail: "legal-bot@hostcorp.com",
      recipientName: validatedInput.signatoryName,
      recipientEmail: validatedInput.signatoryEmail,
      metadata: {
        dealId: validatedInput.dealId,
        vendorName: validatedInput.vendorCompanyName,
        idempotencyKey,
        pipeline: "straight-through-v1",
      },
      expiresInDays: 7,
    };

    let attempt = 0;
    while (attempt < this.maxRetries) {
      try {
        attempt++;
        const response = await fetch(`${this.apiBaseUrl}/send`, {
          method: "POST",
          headers: {
            "Authorization": `Bearer ${this.apiKey}`,
            "Content-Type": "application/json",
            "X-Idempotency-Key": idempotencyKey,
          },
          body: JSON.stringify(payload),
        });

        if (!response.ok) {
          const errorBody = await response.text();
          // Permanent client error: Do not retry, route to DLQ
          if (response.status >= 400 && response.status < 500 && response.status !== 429) {
            throw new Error(`Unrecoverable Signbee Client Error (${response.status}): ${errorBody}`);
          }
          throw new Error(`Transient Signbee Server Error (${response.status}): ${errorBody}`);
        }

        const data: SignbeeSendResponse = await response.json();
        return data;
      } catch (err: any) {
        if (attempt >= this.maxRetries || err.message.includes("Unrecoverable")) {
          await this.routeToDeadLetterQueue(input, err.message);
          throw err;
        }

        // Full jitter calculation: sleep = random_between(0, min(cap, base * 2 ^ attempt))
        const baseDelayMs = 200;
        const maxDelayMs = 4000;
        const exponentialDelay = Math.min(maxDelayMs, baseDelayMs * Math.pow(2, attempt));
        const jitteredDelay = Math.floor(Math.random() * exponentialDelay);

        console.warn(`[STP-Dispatcher] Attempt ${attempt} failed. Retrying in ${jitteredDelay}ms...`);
        await new Promise((resolve) => setTimeout(resolve, jitteredDelay));
      }
    }

    throw new Error("Maximum retry attempts exceeded.");
  }

  private async routeToDeadLetterQueue(input: ContractInput, reason: string): Promise<void> {
    console.error("[DLQ ALERT] Contract dispatch failed permanently. Routing to DLQ table.", {
      dealId: input.dealId,
      reason,
      timestamp: new Date().toISOString(),
    });
    // In production: Persist to Postgres DLQ table, emit AWS SQS message, or page on-call engineer.
  }
}

// ---------------------------------------------------------------------------
// 4. WEBHOOK RECEIVER & AUTOMATED COUNTER-SIGNING ENGINE
// ---------------------------------------------------------------------------
export class StraightThroughWebhookHandler {
  private readonly webhookSecret: string;
  private readonly corporateSigningKey: string;

  constructor(
    webhookSecret = process.env.SIGNBEE_WEBHOOK_SECRET!,
    corporateSigningKey = process.env.SIGNBEE_API_KEY!
  ) {
    if (!webhookSecret) throw new Error("SIGNBEE_WEBHOOK_SECRET is required.");
    this.webhookSecret = webhookSecret;
    this.corporateSigningKey = corporateSigningKey;
  }

  /**
   * Verifies the HMAC-SHA256 webhook signature using constant-time comparison.
   */
  public verifySignature(rawBody: string, incomingSignature: string): boolean {
    if (!incomingSignature) return false;
    const computed = crypto
      .createHmac("sha256", this.webhookSecret)
      .update(rawBody)
      .digest("hex");

    const expectedBuffer = Buffer.from(computed, "utf-8");
    const incomingBuffer = Buffer.from(incomingSignature, "utf-8");

    if (expectedBuffer.length !== incomingBuffer.length) return false;
    return crypto.timingSafeEqual(expectedBuffer, incomingBuffer);
  }

  /**
   * Processes incoming webhook events and triggers the automated corporate counter-sign.
   */
  public async handleWebhookEvent(eventPayload: any): Promise<{ status: string; executed: boolean }> {
    const { event, document_id, data } = eventPayload;

    switch (event) {
      case "document.signed": {
        console.log(`[STP-Webhook] Counterparty signed document ${document_id}. Triggering corporate auto-sign.`);
        await this.executeProgrammaticCounterSignature(document_id, data);
        return { status: "counter_signed", executed: true };
      }

      case "document.completed": {
        console.log(`[STP-Webhook] Document ${document_id} completed. Archiving to S3.`);
        await this.archiveExecutedContractToS3(document_id, data);
        await this.updateDatabaseDealStatus(data.dealId, "COMPLETED", data.download_url);
        return { status: "archived", executed: true };
      }

      case "document.rejected":
      case "document.expired": {
        console.warn(`[STP-Webhook] Document ${document_id} ended with status: ${event}`);
        await this.updateDatabaseDealStatus(data.dealId, "ABANDONED", undefined);
        return { status: event, executed: false };
      }

      default:
        return { status: "ignored", executed: false };
    }
  }

  /**
   * Executes the programmatic corporate counter-signature via internal API.
   */
  private async executeProgrammaticCounterSignature(
    documentId: string,
    metadata: Record<string, unknown>
  ): Promise<void> {
    const counterSignUrl = `https://signb.ee/api/v1/documents/${documentId}/countersign`;

    const response = await fetch(counterSignUrl, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${this.corporateSigningKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        signatoryTitle: "Authorized Electronic Agent / Corporate Counsel",
        attestationReason: "Straight-Through Processing Pipeline Execution",
        timestamp: new Date().toISOString(),
      }),
    });

    if (!response.ok) {
      throw new Error(`Failed to execute corporate counter-sign for ${documentId}: ${await response.text()}`);
    }
  }

  /**
   * Archives final executed PDF to an encrypted AWS S3 bucket.
   */
  private async archiveExecutedContractToS3(documentId: string, data: any): Promise<void> {
    // In production: Stream the download_url buffer directly to your S3 bucket with AES-256 encryption.
    console.log(`[S3-Archive] Uploaded executed contract ${documentId} to S3 bucket: contracts/${data.dealId}.pdf`);
  }

  private async updateDatabaseDealStatus(
    dealId: string,
    status: "COMPLETED" | "ABANDONED",
    contractUrl?: string
  ): Promise<void> {
    console.log(`[DB-Sync] Deal ${dealId} state updated to ${status}. S3 URI: ${contractUrl ?? "N/A"}`);
  }
}