curl -X POST https://api.superdocs.app/v1/chat/async \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Update section 3 to include GDPR compliance language",
    "session_id": "contract-review",
    "document_html": "...",
    "approval_mode": "ask_every_time"
  }'

curl https://api.superdocs.app/v1/jobs/JOB_ID \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

{
  "status": "awaiting_approval",
  "metadata": {
    "pending_changes": [
      {
        "change_id": "ch_1",
        "operation": "edit",
        "chunk_id": "550e8400-e29b-41d4-a716-446655440000",
        "old_html": "<p>Original section 3 content...</p>",
        "new_html": "<p>Updated content with GDPR compliance...</p>",
        "ai_explanation": "Added GDPR data processing requirements"
      }
    ]
  }
}

curl -X POST https://api.superdocs.app/v1/chat/contract-review/approve \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "JOB_ID",
    "change_id": "ch_1",
    "approved": true
  }'

curl -X POST https://api.superdocs.app/v1/chat/contract-review/approve \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "JOB_ID",
    "approved": true,
    "changes": [
      {"change_id": "ch_1", "approved": true},
      {"change_id": "ch_2", "approved": false}
    ]
  }'

curl -X POST https://api.superdocs.app/v1/chat/contract-review/approve \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "JOB_ID",
    "change_id": "ch_1",
    "approved": false,
    "feedback": "Keep the original language but add a GDPR reference link"
  }'

// proposed-change-decoration.ts
import { Plugin, PluginKey, Transaction } from "prosemirror-state";
import { Decoration, DecorationSet, EditorView } from "prosemirror-view";
import type { Node as ProseMirrorNode } from "prosemirror-model";

export type ProposedChange = {
  change_id: string;
  operation: "edit" | "create" | "delete";
  chunk_id: string | null;
  old_html: string | null;
  new_html: string | null;
  ai_explanation: string;
  insert_after_chunk_id: string | null;
};

const META_ADD = "proposedChangeAdd";
const META_REMOVE = "proposedChangeRemove";
const META_CLEAR = "proposedChangeClear";

export const proposedChangeKey = new PluginKey("proposedChangeOverlay");

type State = {
  decorations: DecorationSet;
  pending: Map<string, ProposedChange>;
};

function findChunkRange(doc: ProseMirrorNode, chunkId: string) {
  let hit: { from: number; to: number } | null = null;
  doc.descendants((node, pos) => {
    if (hit) return false;
    if (node.attrs?.["data-chunk-id"] === chunkId) {
      hit = { from: pos, to: pos + node.nodeSize };
      return false;
    }
    return true;
  });
  return hit;
}

function stripHtml(html: string) {
  const withSpaces = html.replace(/<\/(p|div|li|h[1-6]|tr|td|th)>/gi, " ");
  const tmp = document.createElement("div");
  tmp.innerHTML = withSpaces;
  return (tmp.textContent ?? "").replace(/\s+/g, " ").trim();
}

function escapeHtml(s: string) {
  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
}

// Word-level LCS diff → red/green HTML.
function wordDiff(oldText: string, newText: string) {
  const A = oldText.split(/(\s+)/);
  const B = newText.split(/(\s+)/);
  const m = A.length, n = B.length;
  const dp: number[][] = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
  for (let i = 1; i <= m; i++)
    for (let j = 1; j <= n; j++)
      dp[i][j] = A[i - 1] === B[j - 1] ? dp[i - 1][j - 1] + 1 : Math.max(dp[i - 1][j], dp[i][j - 1]);
  const parts: { t: "same" | "del" | "add"; s: string }[] = [];
  let i = m, j = n;
  while (i > 0 || j > 0) {
    if (i > 0 && j > 0 && A[i - 1] === B[j - 1]) { parts.unshift({ t: "same", s: A[i - 1] }); i--; j--; }
    else if (j > 0 && (i === 0 || dp[i][j - 1] >= dp[i - 1][j])) { parts.unshift({ t: "add", s: B[j - 1] }); j--; }
    else { parts.unshift({ t: "del", s: A[i - 1] }); i--; }
  }
  return parts.map(p => {
    const e = escapeHtml(p.s);
    if (p.t === "del") return `<span class="diff-word-deleted">${e}</span>`;
    if (p.t === "add") return `<span class="diff-word-added">${e}</span>`;
    return e;
  }).join("");
}

function controls(change: ProposedChange): HTMLDivElement {
  const wrap = document.createElement("div");
  wrap.className = "inline-diff-controls";
  wrap.contentEditable = "false";
  for (const action of ["accept", "deny"] as const) {
    const btn = document.createElement("button");
    btn.className = `inline-diff-btn inline-diff-btn--${action}`;
    btn.textContent = action === "accept" ? "\u2713" : "\u2717";
    btn.addEventListener("mousedown", e => { e.preventDefault(); e.stopPropagation(); });
    btn.addEventListener("click", e => {
      e.preventDefault(); e.stopPropagation();
      window.dispatchEvent(new CustomEvent("diff-action", {
        detail: { action, change_id: change.change_id },
      }));
    });
    wrap.appendChild(btn);
  }
  return wrap;
}

function editWidget(pos: number, change: ProposedChange): Decoration {
  return Decoration.widget(pos, () => {
    const wrap = document.createElement("div");
    wrap.className = "diff-edit-wrapper";
    wrap.contentEditable = "false";
    wrap.setAttribute("data-diff-widget", "true");
    wrap.appendChild(controls(change));
    const preview = document.createElement("div");
    preview.className = "diff-preview-content";
    preview.innerHTML = wordDiff(stripHtml(change.old_html ?? ""), stripHtml(change.new_html ?? ""));
    wrap.appendChild(preview);
    return wrap;
  }, { side: -1, key: `diff-edit-${change.change_id}` });
}

function ghostCreateWidget(pos: number, change: ProposedChange): Decoration {
  return Decoration.widget(pos, () => {
    const ghost = document.createElement("div");
    ghost.className = "diff-ghost-create";
    ghost.contentEditable = "false";
    ghost.appendChild(controls(change));
    const body = document.createElement("div");
    body.className = "diff-ghost-content";
    body.innerHTML = change.new_html ?? "<p><em>New section</em></p>";
    ghost.appendChild(body);
    return ghost;
  }, { side: 1, key: `diff-ghost-${change.change_id}` });
}

function build(doc: ProseMirrorNode, pending: Map<string, ProposedChange>): DecorationSet {
  const out: Decoration[] = [];
  for (const change of pending.values()) {
    if (change.operation === "create") {
      if (!change.insert_after_chunk_id) continue;
      const after = findChunkRange(doc, change.insert_after_chunk_id);
      if (after) out.push(ghostCreateWidget(after.to, change));
      continue;
    }
    if (!change.chunk_id) continue;
    const range = findChunkRange(doc, change.chunk_id);
    if (!range) continue;
    if (change.operation === "edit") {
      const hasPreview = !!(change.old_html && change.new_html);
      out.push(Decoration.node(range.from, range.to, {
        class: hasPreview ? "diff-chunk-edit diff-chunk-has-preview" : "diff-chunk-edit",
      }));
      if (hasPreview) out.push(editWidget(range.from + 1, change));
    } else if (change.operation === "delete") {
      out.push(Decoration.node(range.from, range.to, { class: "diff-chunk-delete" }));
    }
  }
  return DecorationSet.create(doc, out);
}

export function proposedChangeDecoration(): Plugin<State> {
  return new Plugin<State>({
    key: proposedChangeKey,
    state: {
      init() { return { decorations: DecorationSet.empty, pending: new Map() }; },
      apply(tr: Transaction, value: State): State {
        let pending = value.pending;
        const add = tr.getMeta(META_ADD) as ProposedChange | undefined;
        const remove = tr.getMeta(META_REMOVE) as string | undefined;
        const clear = tr.getMeta(META_CLEAR) as boolean | undefined;
        if (clear) return { decorations: DecorationSet.empty, pending: new Map() };
        if (add) { pending = new Map(pending); pending.set(add.change_id, add); }
        if (remove) { pending = new Map(pending); pending.delete(remove); }
        if (add || remove) return { decorations: build(tr.doc, pending), pending };
        if (tr.docChanged) return { decorations: value.decorations.map(tr.mapping, tr.doc), pending };
        return value;
      },
    },
    props: { decorations(state) { return proposedChangeKey.getState(state)?.decorations ?? DecorationSet.empty; } },
  });
}

export const addProposedChange = (view: EditorView, change: ProposedChange) =>
  view.dispatch(view.state.tr.setMeta(META_ADD, change));
export const removeProposedChange = (view: EditorView, change_id: string) =>
  view.dispatch(view.state.tr.setMeta(META_REMOVE, change_id));
export const clearProposedChanges = (view: EditorView) =>
  view.dispatch(view.state.tr.setMeta(META_CLEAR, true));

.diff-chunk-edit {
  outline: 2px solid #4285f4; outline-offset: -1px;
  background: rgba(66, 133, 244, 0.06); border-radius: 4px; position: relative;
}
.diff-chunk-has-preview > *:not([data-diff-widget]) { display: none !important; }
.diff-chunk-delete {
  outline: 2px solid #dc3545; outline-offset: -1px;
  background: rgba(220, 53, 69, 0.06); border-radius: 4px; position: relative;
}
.diff-chunk-delete > *:not([data-diff-widget]) {
  text-decoration: line-through; text-decoration-color: rgba(220, 53, 69, 0.5); opacity: 0.65;
}
.inline-diff-controls {
  position: absolute; top: 4px; right: 4px; display: flex; gap: 4px;
  background: white; border: 1px solid #e0e0e0; border-radius: 6px;
  padding: 3px 4px; box-shadow: 0 2px 8px rgba(0,0,0,0.12); z-index: 50; user-select: none;
}
.inline-diff-btn {
  width: 32px; height: 32px; border: none; border-radius: 4px;
  font-size: 18px; font-weight: 700; cursor: pointer;
  display: flex; align-items: center; justify-content: center; line-height: 1; padding: 0;
}
.inline-diff-btn--accept { background: #e6ffed; color: #28a745; }
.inline-diff-btn--accept:hover { background: #28a745; color: white; }
.inline-diff-btn--deny { background: #ffeef0; color: #dc3545; }
.inline-diff-btn--deny:hover { background: #dc3545; color: white; }
.diff-edit-wrapper { position: relative; padding: 44px 8px 8px 8px; }
.diff-preview-content { line-height: 1.6; white-space: pre-wrap; word-wrap: break-word; }
.diff-word-deleted {
  background: rgba(220, 53, 69, 0.15); color: #b71c1c;
  text-decoration: line-through; text-decoration-color: #dc3545;
  padding: 1px 2px; border-radius: 2px;
}
.diff-word-added {
  background: rgba(40, 167, 69, 0.15); color: #1b5e20;
  text-decoration: underline; text-decoration-color: #28a745;
  padding: 1px 2px; border-radius: 2px;
}
.diff-ghost-create {
  position: relative; border: 2px dashed #28a745; background: rgba(40, 167, 69, 0.04);
  border-radius: 6px; padding: 44px 8px 8px 8px; margin: 8px 0;
}
.diff-ghost-content { opacity: 0.75; line-height: 1.6; }

// 1. Start async request with approval mode
const response = await fetch("https://api.superdocs.app/v1/chat/async", {
  method: "POST",
  headers: { "Authorization": "Bearer sk_YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    message: "Rewrite the liability section",
    session_id: "contract-review",
    document_html: "...",
    approval_mode: "ask_every_time"
  })
});
const { job_id } = await response.json();

// 2. Open SSE connection
const es = new EventSource(
  `https://api.superdocs.app/v1/chat/contract-review/stream?job_id=${job_id}&api_key=sk_YOUR_API_KEY`
);

// 3. Collect proposed changes. Every HITL turn — one change or hundreds —
//    arrives as a single `proposed_change_batch` event carrying a
//    `changes` array (a one-change turn has type "single_approval").
let pendingChanges = [];

const showReviewUi = (changes) => {
  // Render approve/deny UI here with the full batch.
  // When the user decides, call POST /v1/chat/{session_id}/approve
  // with the change_id list and the decision.
  console.log(`Reviewing ${changes.length} change(s)`);
  for (const change of changes) {
    console.log(`  ${change.change_id}: ${change.operation} — ${change.ai_explanation}`);
  }
};

es.addEventListener("proposed_change_batch", (event) => {
  const data = JSON.parse(event.data);
  const batch = JSON.parse(data.content);   // { type, batch_id, batch_total, changes }
  pendingChanges = batch.changes;
  showReviewUi(pendingChanges);
});

// Optional safety net for older clients: a standalone `proposed_change`
// listener is harmless but never fires — single changes come through
// `proposed_change_batch` too. You don't need this if starting fresh.

es.addEventListener("final", (event) => {
  const data = JSON.parse(event.data);
  console.log("Done:", data.result.response);
  // Apply data.result.document_changes.updated_html to your editor
  es.close();
});

es.addEventListener("error", (event) => {
  if (event.data) {
    const data = JSON.parse(event.data);
    console.error("Error:", data.error);
  }
  es.close();
});

import time
import requests

API_KEY = "sk_YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
BASE = "https://api.superdocs.app"

# 1. Start with approval mode
response = requests.post(f"{BASE}/v1/chat/async", headers=HEADERS, json={
    "message": "Rewrite the liability section",
    "session_id": "contract-review",
    "document_html": "...",
    "approval_mode": "ask_every_time"
})
job_id = response.json()["job_id"]

# 2. Poll and handle approvals
while True:
    job = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS).json()

    if job["status"] == "completed":
        print("Done:", job["result"]["response"])
        break

    elif job["status"] == "failed":
        print("Error:", job["error"])
        break

    elif job["status"] == "awaiting_approval":
        changes = job["metadata"]["pending_changes"]
        for change in changes:
            print(f"\nChange {change['change_id']}:")
            print(f"  Operation: {change['operation']}")
            print(f"  Explanation: {change.get('ai_explanation', 'N/A')}")
            print(f"  Old: {change.get('old_html', 'N/A')[:100]}")
            print(f"  New: {change.get('new_html', 'N/A')[:100]}")

        # Approve all changes
        requests.post(f"{BASE}/v1/chat/contract-review/approve", headers=HEADERS, json={
            "job_id": job_id,
            "approved": True,
            "changes": [{"change_id": c["change_id"], "approved": True} for c in changes]
        })
        print("\nApproved all changes, continuing...")

    time.sleep(2)