Construction E-Signature API: Automate Lien Waivers & Change Orders (2026)

export interface ProgressWaiverInput {
  payAppId: string;
  projectName: string;
  jobLocationAddress: string;
  ownerName: string;
  generalContractorName: string;
  subcontractorCompany: string;
  subcontractorSignerName: string;
  subcontractorEmail: string;
  throughDate: string; // e.g., "2026-10-31"
  netProgressPaymentUsd: number;
  unpaidRetainageUsd: number;
  checkOrAchReference: string;
}

export async function sendCaliforniaConditionalProgressWaiver(input: ProgressWaiverInput) {
  const statutoryMarkdown = `# CONDITIONAL WAIVER AND RELEASE ON PROGRESS PAYMENT
*(Pursuant to California Civil Code Section 8132)*

**NOTICE:** THIS DOCUMENT WAIVES THE CLAIMANT'S LIEN, STOP PAYMENT NOTICE, AND PAYMENT BOND RIGHTS EFFECTIVE ON RECEIPT OF PAYMENT. A PERSON SHOULD NOT RELY ON THIS DOCUMENT UNLESS SATISFIED THAT THE CLAIMANT HAS RECEIVED PAYMENT.

### Identifying Information
| Field | Statutory Record |
|---|---|
| **Name of Claimant (Subcontractor)** | ${input.subcontractorCompany} |
| **Name of Customer (Direct Contractor)** | ${input.generalContractorName} |
| **Job Location / Project Site** | ${input.projectName} — ${input.jobLocationAddress} |
| **Property Owner** | ${input.ownerName} |
| **Through Date** | ${input.throughDate} |

### Conditional Waiver and Release
This document waives and releases lien, stop payment notice, and payment bond rights the claimant has for labor and service provided, and equipment and material delivered, to the customer on this job through the **Through Date** of this document. Rights based upon labor or service provided, or equipment or material delivered, pursuant to a written change order that has been fully executed by the parties prior to the date that this document is signed by the claimant, are waived and released by this document, unless listed as an Exception below.

This document is effective only on the claimant's receipt of payment from the financial institution on which the following check or ACH electronic transfer is drawn:

- **Maker of Check / ACH Originator:** ${input.generalContractorName}
- **Amount of Progress Payment:** $${input.netProgressPaymentUsd.toLocaleString("en-US", { minimumFractionDigits: 2 })} USD
- **Check / ACH Trace Reference:** ${input.checkOrAchReference}

### Exceptions
This document does not affect any of the following:
1. Retentions held to date in the amount of **$${input.unpaidRetainageUsd.toLocaleString("en-US", { minimumFractionDigits: 2 })} USD**.
2. Extras for which the claimant has not received payment.
3. The following progress payments for which the claimant has previously given a conditional waiver and release but has not received payment: **$0.00**.`;

  const response = await fetch("https://signb.ee/api/v1/send", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SIGNBEE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: `CA Conditional Progress Waiver — ${input.subcontractorCompany} (Pay App ${input.payAppId})`,
      markdown: statutoryMarkdown,
      sender_name: `${input.generalContractorName} Project Accounting`,
      sender_email: "payapps@pacificbuilders.com",
      recipient_name: input.subcontractorSignerName,
      recipient_email: input.subcontractorEmail,
      expires_in_days: 14,
      webhook_url: `https://erp.pacificbuilders.com/api/webhooks/signbee?payAppId=${encodeURIComponent(input.payAppId)}&waiverType=CONDITIONAL_PROGRESS`,
    }),
  });

  if (!response.ok) {
    throw new Error(`Signbee dispatch failed: ${await response.text()}`);
  }

  return response.json();
}

export async function dispatchFieldChangeOrder(co: {
  changeOrderNumber: string;
  projectCode: string;
  subcontractorName: string;
  signerName: string;
  signerEmail: string;
  csiCostCode: string;
  scopeDescription: string;
  originalContractSum: number;
  previousChangeOrdersSum: number;
  thisChangeOrderDelta: number;
  scheduleImpactDays: number;
}) {
  const newContractTotal =
    co.originalContractSum + co.previousChangeOrdersSum + co.thisChangeOrderDelta;

  const markdown = `# SUBCONTRACT CHANGE ORDER #${co.changeOrderNumber}

**Project Reference:** ${co.projectCode}
**Subcontractor:** ${co.subcontractorName}
**CSI Division / Cost Code:** ${co.csiCostCode}

### 1. Description of Directed Scope Modification
${co.scopeDescription}

### 2. Contract Sum & Schedule Adjustment Summary
| Contract Ledger Item | Amount (USD) |
|---|---|
| Original Executed Subcontract Sum | $${co.originalContractSum.toLocaleString("en-US", { minimumFractionDigits: 2 })} |
| Net Change by Previously Authorized Change Orders | $${co.previousChangeOrdersSum.toLocaleString("en-US", { minimumFractionDigits: 2 })} |
| **Net Addition / (Deduction) This Change Order #${co.changeOrderNumber}** | **$${co.thisChangeOrderDelta.toLocaleString("en-US", { minimumFractionDigits: 2 })}** |
| **New Adjusted Subcontract Total** | **$${newContractTotal.toLocaleString("en-US", { minimumFractionDigits: 2 })}** |

- **Approved Project Schedule Extension:** ${co.scheduleImpactDays} calendar days.

By signing below electronically, Subcontractor agrees that the adjustment in Contract Sum and Contract Time above constitutes full and complete equitable adjustment for all direct, indirect, and cumulative impact costs arising out of this Change Order.`;

  const res = await fetch("https://signb.ee/api/v1/send", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SIGNBEE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: `Change Order #${co.changeOrderNumber} — ${co.subcontractorName} (${co.projectCode})`,
      markdown,
      sender_name: "Field Operations — Pacific Builders",
      sender_email: "field-ops@pacificbuilders.com",
      recipient_name: co.signerName,
      recipient_email: co.signerEmail,
      expires_in_days: 7,
      webhook_url: `https://erp.pacificbuilders.com/api/webhooks/signbee?coNumber=${encodeURIComponent(co.changeOrderNumber)}`,
    }),
  });

  return res.json();
}

import { NextRequest, NextResponse } from "next/server";
import { db } from "@/lib/db";
import { releaseSubcontractorAchTransfer } from "@/lib/treasury";

export async function POST(req: NextRequest) {
  const payAppId = req.nextUrl.searchParams.get("payAppId");
  const waiverType = req.nextUrl.searchParams.get("waiverType");
  const payload = await req.json();

  if (payload.event !== "document.signed" || !payAppId) {
    return NextResponse.json({ received: true });
  }

  // Record immutable SHA-256 certificate metadata in Construction ERP audit log
  await db.lienWaiverAudit.update({
    where: { payAppId_waiverType: { payAppId, waiverType: waiverType ?? "CONDITIONAL_PROGRESS" } },
    data: {
      status: "SIGNED",
      signbeeDocumentId: payload.document_id,
      sha256Checksum: payload.sha256_hash,
      signedAtUtc: new Date(payload.signed_at ?? Date.now()),
      verificationUrl: `https://signb.ee/verify/${payload.document_id}`,
    },
  });

  // If this was the Conditional Progress Waiver, automatically release the held ACH disbursement
  if (waiverType === "CONDITIONAL_PROGRESS") {
    await releaseSubcontractorAchTransfer(payAppId, {
      complianceProofHash: payload.sha256_hash,
    });
  }

  return NextResponse.json({
    received: true,
    achReleased: waiverType === "CONDITIONAL_PROGRESS",
  });
}