Drive Signing Desk from your own code

// make-body.js - build the run body with the SAME engine the web page uses.
// Save signkit.js from https://signing-desk.skillsafe.ai/signkit.js next to this file.
// Usage: node make-body.js agreement.txt
const fs = require("fs");
const K = require("./signkit.js");

const A = K.analyze({
  title: "Harborline x Northwind master services agreement",
  ours: "Harborline Analytics, Inc.",
  routing: "counterparty_first",   // counterparty_first, we_first or parallel
  prepared: "2026-09-26",          // YYYY-MM-DD
  doc: fs.readFileSync(process.argv[2] || "agreement.txt", "utf8"),
  signers: [                        // name, email, title, party
    "Dana Whitfield, dana.whitfield@harborline.example, Chief Financial Officer, Harborline Analytics, Inc.",
    "Marcus Oyelaran, m.oyelaran@northwindfreight.example, VP Operations, Northwind Freight Systems LLC"
  ].join("\n"),
  approvers: "Priya Raman, priya.raman@harborline.example",
  cc: "Contracts Desk, contracts@harborline.example\nLegal Notices, legal@northwindfreight.example",
  attest_final: true,
  attest_counsel: true
});
const body = K.buildInput(A, { question: "" });   // a non-empty question is answered in summary
if (!body) throw new Error("the agreement text is empty");
fs.writeFileSync("body.json", JSON.stringify(K.mustBeObject(body)));
console.log(A.flags.length, "flags; browser status", A.hint);
console.log("Idempotency-Key: signing-desk:prepare:" + K.hashInput(body) + ":a1");

{"ok": true, "data": {"job_id": "job_...", "status": "queued"}}
{"ok": false, "error": {"code": "payment_required", "message": "..."}}

# The token page is the shortest path. It shows the token this browser holds and
# hands you a ready-made shell export:
#
#   https://signing-desk.skillsafe.ai/tokens.html
#   export SKILLSAFE_TOKEN="..."
#
# To mint a guest token from the command line instead. A guest token is enough
# for /me and /estimate; a run needs a personal token from signing in.
curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/guest" \
  -H "Content-Type: application/json" -d '{"slug":"signing-desk"}'
# {"ok":true,"data":{"token":"…","subject_type":"guest"}}

# Every call is the same three things: the base URL, your bearer token,
# and a JSON body. Keep the token in a shell variable.
BASE="https://api.skillsafe.ai/v1/app-api"
SLUG="signing-desk"
TOKEN="$SKILLSAFE_TOKEN"   # from https://signing-desk.skillsafe.ai/tokens.html

call() {                  # call <path> [json-body]
  if [ -n "$2" ]; then
    curl -sS -X POST "$BASE/$1" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d "$2"
  else
    curl -sS "$BASE/$1" -H "Authorization: Bearer $TOKEN"
  fi
}

call me
# {"ok":true,"data":{"subject_type":"user","username":"you","credits":51234}}

# body.json is the input object itself - no {"input": ...} wrapper. Build it with
# make-body.js above. estimate does not validate it, so check the shape first:
python3 -c 'import json;b=json.load(open("body.json"));assert isinstance(b,dict) and b.get("task")=="prepare" and all(isinstance(v,str) for v in b.values()) and all(b.get(k,"").strip() for k in ("document_title","document","facts")) and isinstance(json.loads(b["facts"]),dict)'
INPUT=$(cat body.json)

call estimate "$INPUT"
# {"ok":true,"data":{"model":"...","model_alias":"gpt-terra",
#   "markup_bps":1000,"hold_credits":...,"min_credits":...,"sponsor_enabled":false,
#   "warnings":[]}}
#
# estimate creates no job and charges nothing. hold_credits is RESERVED, not the
# price; charged_credits after the run is usually far lower.

# Always send an Idempotency-Key derived from the input. A retried request with
# the same key returns the SAME job instead of billing a second run.
KEY="signing-desk:prepare:$(printf '%s' "$INPUT" | shasum -a 256 | cut -c1-16):a1"

JOB=$(curl -sS -X POST "$BASE/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d "$INPUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["job_id"])')

while :; do
  OUT=$(call "jobs/$JOB")
  STATUS=$(printf '%s' "$OUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["status"])')
  [ "$STATUS" = "succeeded" ] && break
  [ "$STATUS" = "failed" ] && echo "$OUT" && exit 1
  sleep 2
done

# {"ok":true,"data":{"job_id":"job_...","status":"succeeded",
#   "output":{"output":"{\"lane\":\"prepare\",\"document\":{...},\"status\":\"resolve_first\", ...}"},
#   "charged_credits":...,"truncated":false}}
printf '%s' "$OUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["output"]["output"])' > reply.json

# Server-sent events. `delta` events carry chunks of the reply; `done` carries the
# status, charged_credits and the truncated flag. Ignore `tick` heartbeats.
curl -N -X POST "$BASE/run-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -H "Accept: text/event-stream" \
  -d "$INPUT"

# event: job    {"job_id":"job_..."}
# event: delta  {"text":"{\"lane\":\"prepare\",\"document\":{\"title\":\"Harborline x Northwind"}
# event: done   {"status":"succeeded","charged_credits":...,"truncated":false}

# reply.json holds data.output.output from step 5. Strip any fence, keep the object:
python3 - <<'EOF'
import json, re
t = open("reply.json").read().strip()
t = re.sub(r"^```(?:json)?\s*", "", t, flags=re.I)
t = re.sub(r"\s*```\s*$", "", t)
r = json.loads(t[t.index("{"):t.rindex("}") + 1])
print(r["status"], "-", r["headline"])
for c in r["checklist"]:
    print(c["id"], c["status"], "|", c["note"])
for i in r["issues"]:
    print(i["ref"], i["severity"], "|", i["issue"], "->", i["fix"])
for s in sorted(r["signing"], key=lambda s: s["order"]):
    print(s["order"], s["action"], s["name"], s["email"], "|", s["role"])
print(r["envelope"]["subject"])
EOF

# assert-reply.py - the core checks, for body.json and reply.json from the steps above.
import json, re
body = json.load(open("body.json")); facts = json.loads(body["facts"])
t = open("reply.json").read(); r = json.loads(t[t.index("{"):t.rindex("}") + 1])
flags = {f["id"]: f for f in facts["flags"]}
ids = [p["id"] for p in r["prescan_responses"]]
assert sorted(ids) == sorted(flags), "every flag answered exactly once"
dismissed = {p["id"] for p in r["prescan_responses"] if p["status"] == "dismissed"}
standing = [f for i, f in flags.items() if i not in dismissed]
rank = ["ready_to_send", "confirm_then_send", "resolve_first"]
floor = 2 if any(f["severity"] == "high" for f in standing) else 1 if any(f["severity"] == "medium" for f in standing) else 0
assert rank.index(r["status"]) >= floor, "status looser than the flags left standing"
covered = {x for i in r["issues"] for x in re.findall(r"[FSACP]\d+", i["ref"])}
assert all(f["id"] in covered for f in standing if f["severity"] != "low")
assert {c["id"] for c in r["checklist"]} == {"final_form", "exhibits", "entity_names", "dates",
                                           "signature_blocks", "internal_approvals", "counsel_review"}
people = {p["id"]: p for p in facts["signers"] + facts["approvers"]}
assert sorted(s["ref"] for s in r["signing"]) == sorted(people), "each signer and approver exactly once"
for s in r["signing"]:
    assert s["email"].lower() == people[s["ref"]]["email"].lower()
    assert s["action"] == ("approve" if s["ref"].startswith("A") else "sign")
signers = [s for s in r["signing"] if s["ref"].startswith("S")]
approvers = [s for s in r["signing"] if s["ref"].startswith("A")]
if approvers and signers:
    assert max(a["order"] for a in approvers) < min(s["order"] for s in signers)
side = {s["id"]: s["side"] for s in facts["signers"]}
mode = facts["routing_mode"]
if mode == "parallel":
    assert len({s["order"] for s in signers}) <= 1 and r["routing"] == "parallel"
else:
    first, second = ("ours", "theirs") if mode == "we_first" else ("theirs", "ours")
    a = [s["order"] for s in signers if side[s["ref"]] == first]
    b = [s["order"] for s in signers if side[s["ref"]] == second]
    if a and b:
        assert max(a) < min(b), "signing order does not follow routing_mode"
known = {p["email"].lower() for p in facts["signers"] + facts["approvers"] + facts["cc"]}
known |= {e.lower() for e in re.findall(r"[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}", body["document"])}
blob = json.dumps([r["signing"], r["cc"], r["envelope"], r["next_steps"], r["issues"], r["summary"]])
assert all(e.lower() in known for e in re.findall(r"[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}", blob)), "invented email"
assert all(p.lower() in body["document"].lower() for p in r["document"]["parties"])

{"lane":"prepare",
 "document":{"title":"...","type":"MSA|NDA|SOW|Amendment|Order Form|Lease|...","parties":["exact party name"],"pages":3},
 "status":"ready_to_send|confirm_then_send|resolve_first",
 "headline":"...","summary":"...",
 "checklist":[{"id":"final_form","status":"pass|issue|confirm","note":"...","refs":"F1,F4"}],
 "issues":[{"ref":"F2","severity":"high|medium|low","issue":"...","fix":"..."}],
 "routing":"sequential|parallel","routing_reason":"...",
 "signing":[{"order":1,"ref":"A1","name":"...","email":"...","role":"Internal approver","action":"approve|sign"}],
 "cc":[{"ref":"C1","name":"...","email":"..."}],
 "fields":[{"ref":"S1","field":"signature|date|name|title|initials","where":"..."}],
 "envelope":{"subject":"...","message":"..."},
 "next_steps":["..."],
 "prescan_responses":[{"id":"F1","status":"confirmed|dismissed","reason":"..."}]}

{
 "task": "prepare",
 "document_title": "Harborline x Northwind master services agreement",
 "document": "MASTER SERVICES AGREEMENT\n\nThis Master Services Agreement (the \"Agreement\") is entered into as of the date of the last signature below (the \"Effective Date\") by and between Harborline Analytics, Inc., a Delaware corporation with offices at 400 Pier Street, Suite 12, Portland, Oregon (\"Harborline\"), and Northwind Freight Systems LLC, an Ohio limited liability company with offices at 88 Canal Road, Toledo, Ohio (\"Customer\").\n\n1. SERVICES\n…\n\nIN WITNESS WHEREOF, the parties have executed this Agreement by their authorized representatives.\n\nHARBORLINE ANALYTICS, INC.\nBy: ______________________\nName: Dana Whitfield\nTitle: Chief Financial Officer\nDate: ____________________\n\nNORTHWIND FREIGHT SYSTEM, LLC\nBy: ______________________\nName: ____________________\nTitle: ___________________\nDate: ____________________\n\nEXHIBIT A\n…\n\nEXHIBIT C\n…",
 "facts": "{\"document_type_guess\":\"MSA\",\"pages\":1,…,\"routing_mode\":\"counterparty_first\",…,\"browser_status\":\"resolve_first\",…}"
}

{
 "parties": [
  {
   "id": "P1",
   "name": "Harborline Analytics, Inc.",
   "signature_block_name": "HARBORLINE ANALYTICS, INC.",
   "ours": true
  },
  {
   "id": "P2",
   "name": "Northwind Freight Systems LLC",
   "signature_block_name": "NORTHWIND FREIGHT SYSTEM, LLC",
   "ours": false
  }
 ],
 "your_company": "Harborline Analytics, Inc.",
 "exhibits": {
  "referenced": [
   "Exhibit A",
   "Exhibit B",
   "Exhibit C"
  ],
  "attached": [
   "Exhibit A",
   "Exhibit C"
  ]
 },
 "attested": {
  "final_agreed_version": true,
  "counsel_reviewed": true
 },
 "signers": [
  {
   "id": "S1",
   "name": "Dana Whitfield",
   "email": "dana.whitfield@harborline.example",
   "title": "Chief Financial Officer",
   "party": "Harborline Analytics, Inc.",
   "side": "ours"
  },
  {
   "id": "S2",
   "name": "Marcus Oyelaran",
   "email": "m.oyelaran@northwindfreight.example",
   "title": "VP Operations",
   "party": "Northwind Freight Systems LLC",
   "side": "theirs"
  }
 ],
 "approvers": [
  {
   "id": "A1",
   "name": "Priya Raman",
   "email": "priya.raman@harborline.example"
  }
 ],
 "cc": [
  {
   "id": "C1",
   "name": "Contracts Desk",
   "email": "contracts@harborline.example"
  },
  {
   "id": "C2",
   "name": "Legal Notices",
   "email": "legal@northwindfreight.example"
  }
 ],
 "routing_mode": "counterparty_first",
 "browser_status": "resolve_first",
 "flags": [
  {
   "id": "F1",
   "severity": "high",
   "category": "parties",
   "checklist_item": "entity_names",
   "message": "The preamble names \"Northwind Freight Systems LLC\" (line 3) but the signature block says \"NORTHWIND FREIG…"
  },
  {
   "id": "F2",
   "severity": "high",
   "category": "exhibits",
   "checklist_item": "exhibits",
   "message": "Exhibit B is referenced (first at line 10, 1 mention) but no Exhibit B is attached after the signature se…"
  },
  {
   "id": "F3",
   "severity": "high",
   "category": "blanks",
   "checklist_item": "final_form",
   "message": "Unfilled bracketed blank \"[●]\" at line 10: …tform subscription fee is USD [●] per month, invoiced monthly i…"
  },
  {
   "id": "F4",
   "severity": "high",
   "category": "draft",
   "checklist_item": "final_form",
   "message": "Drafting mark \"[Note to Draft\" at line 21: …(12) months before the claim. [Note to Draft: Finance to conf…"
  }
 ],
 "flags_not_listed": 0,
 "prepared_on": "2026-09-26"
}

{
 "lane": "prepare",
 "document": {
  "title": "Harborline x Northwind master services agreement",
  "type": "MSA",
  "parties": [
   "Harborline Analytics, Inc.",
   "Northwind Freight Systems LLC"
  ],
  "pages": 1
 },
 "status": "resolve_first",
 "headline": "The Master Services Agreement between Harborline Analytics, Inc. and Northwind Freight Systems LLC cannot go out yet: it has an unfilled fee blank, an open drafting note, a missing Exhibit B and a misnamed Northwind signature block.",
 "summary": "Before sending, fill the monthly subscription fee in Section 2.1, resolve and delete the Note to Draft in Section 5, attach Exhibit B, and correct the Northwind signature block to read NORTHWIND …",
 "checklist": [
  {
   "id": "final_form",
   "status": "issue",
   "note": "Section 2.1 still has the blank USD [●] for the monthly fee and Section 5 still contains …",
   "refs": "F3,F4"
  },
  {
   "id": "exhibits",
   "status": "issue",
   "note": "Exhibits A and C are attached, but Exhibit B (fees) is referenced in Section 2.1 and not …",
   "refs": "F2"
  },
  {
   "id": "entity_names",
   "status": "issue",
   "note": "The preamble names Northwind Freight Systems LLC but its signature block reads NORTHWIND …",
   "refs": "F1"
  },
  {
   "id": "internal_approvals",
   "status": "pass",
   "note": "Priya Raman is listed as an internal approver and approves inside the envelope before …",
   "refs": ""
  },
  {
   "id": "counsel_review",
   "status": "pass",
   "note": "The user confirmed counsel reviewed the agreement and that this is the final agreed …",
   "refs": ""
  }
 ],
 "issues": [
  {
   "ref": "F1",
   "severity": "high",
   "issue": "The Northwind signature block reads NORTHWIND FREIGHT SYSTEM, LLC, which does not match the party named in the preamble, Northwind Freight Systems LLC.",
   "fix": "Change the block heading to NORTHWIND FREIGHT SYSTEMS LLC so it matches the preamble exactly."
  },
  {
   "ref": "F2",
   "severity": "high",
   "issue": "Section 2.1 says Customer pays the fees set out in Exhibit B, but no Exhibit B is attached.",
   "fix": "Attach the agreed Exhibit B fee schedule after the signature blocks before sending."
  }
 ],
 "routing": "sequential",
 "routing_reason": "Routing is counterparty first, so Northwind Freight Systems LLC signs before Harborline Analytics, Inc. countersigns and the fully signed copy returns to Harborline.",
 "signing": [
  {
   "order": 1,
   "ref": "A1",
   "name": "Priya Raman",
   "email": "priya.raman@harborline.example",
   "role": "Internal approver",
   "action": "approve"
  },
  {
   "order": 2,
   "ref": "S2",
   "name": "Marcus Oyelaran",
   "email": "m.oyelaran@northwindfreight.example",
   "role": "Northwind Freight Systems LLC authorized signatory (VP Operations)",
   "action": "sign"
  },
  {
   "order": 3,
   "ref": "S1",
   "name": "Dana Whitfield",
   "email": "dana.whitfield@harborline.example",
   "role": "Harborline Analytics, Inc. authorized signatory (Chief Financial Officer)",
   "action": "sign"
  }
 ],
 "cc": [
  {
   "ref": "C1",
   "name": "Contracts Desk",
   "email": "contracts@harborline.example"
  },
  {
   "ref": "C2",
   "name": "Legal Notices",
   "email": "legal@northwindfreight.example"
  }
 ],
 "fields": [
  {
   "ref": "S2",
   "field": "signature",
   "where": "NORTHWIND FREIGHT SYSTEMS LLC block, By line"
  },
  {
   "ref": "S2",
   "field": "name",
   "where": "NORTHWIND FREIGHT SYSTEMS LLC block, Name line"
  },
  {
   "ref": "S2",
   "field": "title",
   "where": "NORTHWIND FREIGHT SYSTEMS LLC block, Title line"
  },
  {
   "ref": "S2",
   "field": "date",
   "where": "NORTHWIND FREIGHT SYSTEMS LLC block, Date line"
  }
 ],
 "envelope": {
  "subject": "Master Services Agreement for signature: Harborline Analytics, Inc. and Northwind Freight Systems LLC",
  "message": "Hello, attached is the Master Services Agreement between Harborline Analytics, Inc. and Northwind Freight Systems LLC for route-analytics services. Priya Raman will first review and approve it internally. Marcus …"
 },
 "next_steps": [
  "Fix the four blockers first: fill the fee in Section 2.1, resolve and remove the Note to Draft in Section 5, attach Exhibit B, and correct …",
  "Load the corrected document into your e-signature tool with Priya Raman approving first, then Marcus Oyelaran, then Dana Whitfield, copying …"
 ],
 "prescan_responses": [
  {
   "id": "F1",
   "status": "confirmed",
   "reason": "The preamble names Northwind Freight Systems LLC while the signature block reads NORTHWIND FREIGHT SYSTEM, LLC, dropping the s in Systems and adding a comma."
  },
  {
   "id": "F2",
   "status": "confirmed",
   "reason": "Section 2.1 relies on Exhibit B for the fees, but only Exhibits A and C follow the signature blocks."
  }
 ]
}