@beyondwork/docx-react-component 1.0.41 → 1.0.43

package/src/io/ooxml/comment-negotiation-payload.ts

@@ -0,0 +1,288 @@
+import type {
+  CommentNegotiationActionType,
+  CommentNegotiationEntry,
+  CommentNegotiationSnapshot,
+  CommentNegotiationState,
+  NegotiationCounterProposal,
+  NegotiationHistoryRow,
+  NegotiationVote,
+} from "../../api/comment-negotiation-types.ts";
+import {
+  attrNumber,
+  childrenOf,
+  firstChild,
+  parseBwXml,
+  renderElement,
+  renderText,
+  stripNs,
+  textOf,
+} from "./bw-xml.ts";
+
+const NS_URI = "urn:beyondwork:workflow-payload:1";
+
+const STATE_VOCAB = new Set<CommentNegotiationState>([
+  "proposed",
+  "negotiating",
+  "accepted",
+  "rejected",
+  "resolved",
+]);
+const VERDICT_VOCAB = new Set<NegotiationVote["verdict"]>([
+  "approve",
+  "reject",
+  "abstain",
+]);
+const ACTION_VOCAB = new Set<CommentNegotiationActionType>([
+  "propose-change",
+  "counter-propose",
+  "vote",
+  "accept",
+  "reject",
+  "lock",
+  "reopen",
+]);
+const EDIT_KIND_VOCAB = new Set<"replace" | "insert" | "delete">([
+  "replace",
+  "insert",
+  "delete",
+]);
+
+export function buildCommentNegotiationXml(
+  snap: CommentNegotiationSnapshot,
+): string {
+  const threads = snap.entries.map(buildThread).join("");
+  return renderElement(
+    "bw:commentNegotiation",
+    {
+      "xmlns:bw": NS_URI,
+      schemaVersion: String(snap.schemaVersion),
+    },
+    [threads],
+  );
+}
+
+function buildThread(entry: CommentNegotiationEntry): string {
+  const approvers = entry.requiredApprovers.length
+    ? renderElement("bw:requiredApprovers", {}, [
+        entry.requiredApprovers
+          .map((id) => renderElement("bw:userRef", { id }))
+          .join(""),
+      ])
+    : "";
+
+  const votes = entry.votes.length
+    ? renderElement("bw:votes", {}, [
+        entry.votes
+          .map((v) =>
+            renderElement("bw:vote", {
+              authorId: v.authorId,
+              verdict: v.verdict,
+              castAt: v.castAt,
+            }),
+          )
+          .join(""),
+      ])
+    : "";
+
+  const proposals = entry.counterProposals.length
+    ? renderElement("bw:counterProposals", {}, [
+        entry.counterProposals.map(buildCounterProposal).join(""),
+      ])
+    : "";
+
+  const history = entry.history.length
+    ? renderElement("bw:history", {}, [
+        entry.history
+          .map((h) =>
+            renderElement("bw:transition", {
+              from: h.from,
+              to: h.to,
+              actorId: h.actorId,
+              at: h.at,
+              action: h.action,
+              reasonCode: h.reasonCode,
+            }),
+          )
+          .join(""),
+      ])
+    : "";
+
+  return renderElement(
+    "bw:thread",
+    {
+      commentId: entry.commentId,
+      state: entry.state,
+      lockedAt: entry.lockedAt,
+      lockedBy: entry.lockedBy,
+      acceptedProposalId: entry.acceptedProposalId,
+    },
+    [approvers, votes, proposals, history],
+  );
+}
+
+function buildCounterProposal(p: NegotiationCounterProposal): string {
+  const bodyEl = renderElement("bw:body", {}, [renderText(p.body)]);
+  const edit = p.proposedRangeEdit
+    ? renderElement(
+        "bw:proposedRangeEdit",
+        {
+          kind: p.proposedRangeEdit.kind,
+          start: String(p.proposedRangeEdit.start),
+          end: String(p.proposedRangeEdit.end),
+        },
+        [p.proposedRangeEdit.text ? renderText(p.proposedRangeEdit.text) : ""],
+      )
+    : "";
+  return renderElement(
+    "bw:counterProposal",
+    {
+      id: p.id,
+      authorId: p.authorId,
+      createdAt: p.createdAt,
+      supersededBy: p.supersededBy,
+    },
+    [bodyEl, edit],
+  );
+}
+
+export function parseCommentNegotiationXml(
+  xml: string,
+): CommentNegotiationSnapshot {
+  const root = parseBwXml(xml);
+  if (stripNs(root.name) !== "commentNegotiation") {
+    throw new Error(
+      `parseCommentNegotiationXml: expected <bw:commentNegotiation>, got <${root.name}>`,
+    );
+  }
+  const schemaVersion =
+    attrNumber(root.attributes["schemaVersion"]) ?? 1;
+  if (schemaVersion !== 1) {
+    // Unknown major — preserve-only; return an empty snapshot so the runtime
+    // still works. The full tree is preserved by the workflow-payload emitter.
+    return { schemaVersion: 1, entries: [] };
+  }
+
+  const entries: CommentNegotiationEntry[] = [];
+  for (const thread of childrenOf(root, "thread")) {
+    const state = thread.attributes["state"] as CommentNegotiationState;
+    if (!STATE_VOCAB.has(state)) continue;
+
+    const entry: CommentNegotiationEntry = {
+      commentId: thread.attributes["commentId"] ?? "",
+      state,
+      requiredApprovers: parseApprovers(thread),
+      votes: parseVotes(thread),
+      counterProposals: parseProposals(thread),
+      history: parseHistory(thread),
+    };
+    if (thread.attributes["lockedAt"] !== undefined) {
+      entry.lockedAt = thread.attributes["lockedAt"];
+    }
+    if (thread.attributes["lockedBy"] !== undefined) {
+      entry.lockedBy = thread.attributes["lockedBy"];
+    }
+    if (thread.attributes["acceptedProposalId"] !== undefined) {
+      entry.acceptedProposalId = thread.attributes["acceptedProposalId"];
+    }
+    entries.push(entry);
+  }
+
+  return { schemaVersion: 1, entries };
+}
+
+function parseApprovers(
+  thread: ReturnType<typeof parseBwXml>,
+): string[] {
+  const container = firstChild(thread, "requiredApprovers");
+  if (!container) return [];
+  return childrenOf(container, "userRef")
+    .map((el) => el.attributes["id"])
+    .filter((id): id is string => id !== undefined && id !== "");
+}
+
+function parseVotes(thread: ReturnType<typeof parseBwXml>): NegotiationVote[] {
+  const container = firstChild(thread, "votes");
+  if (!container) return [];
+  const out: NegotiationVote[] = [];
+  for (const el of childrenOf(container, "vote")) {
+    const verdict = el.attributes["verdict"] as NegotiationVote["verdict"];
+    if (!VERDICT_VOCAB.has(verdict)) continue;
+    const authorId = el.attributes["authorId"];
+    const castAt = el.attributes["castAt"];
+    if (!authorId || !castAt) continue;
+    out.push({ authorId, verdict, castAt });
+  }
+  return out;
+}
+
+function parseProposals(
+  thread: ReturnType<typeof parseBwXml>,
+): NegotiationCounterProposal[] {
+  const container = firstChild(thread, "counterProposals");
+  if (!container) return [];
+  const out: NegotiationCounterProposal[] = [];
+  for (const el of childrenOf(container, "counterProposal")) {
+    const id = el.attributes["id"];
+    const authorId = el.attributes["authorId"];
+    const createdAt = el.attributes["createdAt"];
+    if (!id || !authorId || !createdAt) continue;
+    const bodyEl = firstChild(el, "body");
+    const editEl = firstChild(el, "proposedRangeEdit");
+    const proposal: NegotiationCounterProposal = {
+      id,
+      authorId,
+      createdAt,
+      body: bodyEl ? textOf(bodyEl) : "",
+    };
+    if (el.attributes["supersededBy"] !== undefined) {
+      proposal.supersededBy = el.attributes["supersededBy"];
+    }
+    if (editEl) {
+      const kind = editEl.attributes["kind"] as "replace" | "insert" | "delete";
+      const start = attrNumber(editEl.attributes["start"]);
+      const end = attrNumber(editEl.attributes["end"]);
+      if (EDIT_KIND_VOCAB.has(kind) && start !== undefined && end !== undefined) {
+        const edit: NegotiationCounterProposal["proposedRangeEdit"] = {
+          kind,
+          start,
+          end,
+        };
+        const text = textOf(editEl);
+        if (text.length > 0) edit.text = text;
+        proposal.proposedRangeEdit = edit;
+      }
+    }
+    out.push(proposal);
+  }
+  return out;
+}
+
+function parseHistory(
+  thread: ReturnType<typeof parseBwXml>,
+): NegotiationHistoryRow[] {
+  const container = firstChild(thread, "history");
+  if (!container) return [];
+  const out: NegotiationHistoryRow[] = [];
+  for (const el of childrenOf(container, "transition")) {
+    const from = el.attributes["from"] as CommentNegotiationState;
+    const to = el.attributes["to"] as CommentNegotiationState;
+    const action = el.attributes["action"] as CommentNegotiationActionType;
+    const actorId = el.attributes["actorId"];
+    const at = el.attributes["at"];
+    if (
+      !STATE_VOCAB.has(from) ||
+      !STATE_VOCAB.has(to) ||
+      !ACTION_VOCAB.has(action) ||
+      !actorId ||
+      !at
+    ) {
+      continue;
+    }
+    const row: NegotiationHistoryRow = { from, to, actorId, at, action };
+    if (el.attributes["reasonCode"] !== undefined) {
+      row.reasonCode = el.attributes["reasonCode"];
+    }
+    out.push(row);
+  }
+  return out;
+}

package/src/io/ooxml/comment-presentation-payload.ts

@@ -0,0 +1,311 @@
+import type {
+  CommentAttachment,
+  CommentAudience,
+  CommentBody,
+  CommentLabel,
+  CommentMention,
+  CommentPresentation,
+  CommentPresentationReply,
+  CommentPresentationSnapshot,
+  CommentReaction,
+} from "../../api/comment-presentation-types.ts";
+import {
+  attrNumber,
+  childrenOf,
+  firstChild,
+  parseBwXml,
+  renderCdata,
+  renderElement,
+  renderText,
+  stripNs,
+  textOf,
+} from "./bw-xml.ts";
+
+const NS_URI = "urn:beyondwork:workflow-payload:1";
+
+const AUDIENCE_VOCAB = new Set<CommentAudience>([
+  "internal",
+  "external",
+  "shared",
+]);
+const ATTACHMENT_KIND_VOCAB = new Set<CommentAttachment["kind"]>([
+  "image",
+  "file",
+  "link",
+]);
+
+export function buildCommentPresentationXml(
+  snap: CommentPresentationSnapshot,
+): string {
+  const entries = snap.entries.map(buildComment).join("");
+  return renderElement(
+    "bw:commentPresentation",
+    {
+      "xmlns:bw": NS_URI,
+      schemaVersion: String(snap.schemaVersion),
+    },
+    [entries],
+  );
+}
+
+function buildComment(entry: CommentPresentation): string {
+  const body = buildBody("bw:body", entry.body);
+  const replies = entry.replies.length
+    ? renderElement("bw:replies", {}, [
+        entry.replies.map(buildReply).join(""),
+      ])
+    : "";
+  const mentions = entry.mentions.length
+    ? renderElement("bw:mentions", {}, [
+        entry.mentions
+          .map((m) =>
+            renderElement("bw:mention", {
+              userId: m.userId,
+              displayName: m.displayName,
+              offsetInBody: String(m.offsetInBody),
+              entryId: m.entryId,
+            }),
+          )
+          .join(""),
+      ])
+    : "";
+  const attachments = entry.attachments.length
+    ? renderElement("bw:attachments", {}, [
+        entry.attachments.map(buildAttachment).join(""),
+      ])
+    : "";
+  const reactions = entry.reactions.length
+    ? renderElement("bw:reactions", {}, [
+        entry.reactions
+          .map((r) =>
+            renderElement("bw:reaction", {
+              emoji: r.emoji,
+              authorId: r.authorId,
+              reactedAt: r.reactedAt,
+            }),
+          )
+          .join(""),
+      ])
+    : "";
+  const labels = entry.labels.length
+    ? renderElement("bw:labels", {}, [
+        entry.labels
+          .map((l) =>
+            renderElement("bw:label", { key: l.key, color: l.color }, [
+              renderText(l.text),
+            ]),
+          )
+          .join(""),
+      ])
+    : "";
+
+  return renderElement(
+    "bw:comment",
+    {
+      commentId: entry.commentId,
+      audience: entry.audience,
+    },
+    [body, replies, mentions, attachments, reactions, labels],
+  );
+}
+
+function buildReply(reply: CommentPresentationReply): string {
+  return renderElement("bw:reply", { entryId: reply.entryId }, [
+    buildBody("bw:body", reply.body),
+  ]);
+}
+
+function buildBody(elementName: string, body: CommentBody): string {
+  const needsCdata = /[<>&]/.test(body.text);
+  return renderElement(
+    elementName,
+    {
+      format: body.format,
+      digest: body.digest,
+      sanitized: body.sanitized ? "true" : undefined,
+    },
+    [needsCdata ? renderCdata(body.text) : renderText(body.text)],
+  );
+}
+
+function buildAttachment(a: CommentAttachment): string {
+  return renderElement("bw:attachment", {
+    id: a.id,
+    kind: a.kind,
+    displayName: a.displayName,
+    mimeType: a.mimeType,
+    relationshipId: a.relationshipId,
+    href: a.href,
+    byteLength: a.byteLength !== undefined ? String(a.byteLength) : undefined,
+    width: a.width !== undefined ? String(a.width) : undefined,
+    height: a.height !== undefined ? String(a.height) : undefined,
+  });
+}
+
+export function parseCommentPresentationXml(
+  xml: string,
+): CommentPresentationSnapshot {
+  const root = parseBwXml(xml);
+  if (stripNs(root.name) !== "commentPresentation") {
+    throw new Error(
+      `parseCommentPresentationXml: expected <bw:commentPresentation>, got <${root.name}>`,
+    );
+  }
+  const schemaVersion = attrNumber(root.attributes["schemaVersion"]) ?? 1;
+  if (schemaVersion !== 1) {
+    return { schemaVersion: 1, entries: [] };
+  }
+
+  const entries: CommentPresentation[] = [];
+  for (const commentEl of childrenOf(root, "comment")) {
+    const commentId = commentEl.attributes["commentId"] ?? "";
+    if (!commentId) continue;
+    const audienceAttr = commentEl.attributes["audience"] as CommentAudience;
+    const audience: CommentAudience = AUDIENCE_VOCAB.has(audienceAttr)
+      ? audienceAttr
+      : "internal"; // fail-closed per schema
+    const bodyEl = firstChild(commentEl, "body");
+    const body: CommentBody = bodyEl ? parseBody(bodyEl) : emptyBody();
+
+    entries.push({
+      commentId,
+      audience,
+      body,
+      replies: parseReplies(commentEl),
+      mentions: parseMentions(commentEl),
+      attachments: parseAttachments(commentEl),
+      reactions: parseReactions(commentEl),
+      labels: parseLabels(commentEl),
+    });
+  }
+
+  return { schemaVersion: 1, entries };
+}
+
+function parseBody(el: ReturnType<typeof parseBwXml>): CommentBody {
+  const body: CommentBody = {
+    format: "markdown",
+    text: textOf(el),
+    digest: el.attributes["digest"] ?? "",
+  };
+  if (el.attributes["sanitized"] === "true") body.sanitized = true;
+  return body;
+}
+
+function emptyBody(): CommentBody {
+  return {
+    format: "markdown",
+    text: "",
+    digest: "",
+  };
+}
+
+function parseReplies(
+  commentEl: ReturnType<typeof parseBwXml>,
+): CommentPresentationReply[] {
+  const container = firstChild(commentEl, "replies");
+  if (!container) return [];
+  const out: CommentPresentationReply[] = [];
+  for (const el of childrenOf(container, "reply")) {
+    const entryId = el.attributes["entryId"];
+    if (!entryId) continue;
+    const bodyEl = firstChild(el, "body");
+    out.push({
+      entryId,
+      body: bodyEl ? parseBody(bodyEl) : emptyBody(),
+    });
+  }
+  return out;
+}
+
+function parseMentions(
+  commentEl: ReturnType<typeof parseBwXml>,
+): CommentMention[] {
+  const container = firstChild(commentEl, "mentions");
+  if (!container) return [];
+  const out: CommentMention[] = [];
+  for (const el of childrenOf(container, "mention")) {
+    const userId = el.attributes["userId"];
+    const displayName = el.attributes["displayName"];
+    const offsetInBody = attrNumber(el.attributes["offsetInBody"]);
+    if (!userId || !displayName || offsetInBody === undefined) continue;
+    const mention: CommentMention = { userId, displayName, offsetInBody };
+    if (el.attributes["entryId"] !== undefined) {
+      mention.entryId = el.attributes["entryId"];
+    }
+    out.push(mention);
+  }
+  return out;
+}
+
+function parseAttachments(
+  commentEl: ReturnType<typeof parseBwXml>,
+): CommentAttachment[] {
+  const container = firstChild(commentEl, "attachments");
+  if (!container) return [];
+  const out: CommentAttachment[] = [];
+  for (const el of childrenOf(container, "attachment")) {
+    const id = el.attributes["id"];
+    const kind = el.attributes["kind"] as CommentAttachment["kind"];
+    const displayName = el.attributes["displayName"];
+    if (!id || !displayName || !ATTACHMENT_KIND_VOCAB.has(kind)) continue;
+    const a: CommentAttachment = { id, kind, displayName };
+    if (el.attributes["mimeType"] !== undefined) {
+      a.mimeType = el.attributes["mimeType"];
+    }
+    if (el.attributes["relationshipId"] !== undefined) {
+      a.relationshipId = el.attributes["relationshipId"];
+    }
+    if (el.attributes["href"] !== undefined && isAllowedHref(el.attributes["href"])) {
+      a.href = el.attributes["href"];
+    }
+    const byteLength = attrNumber(el.attributes["byteLength"]);
+    if (byteLength !== undefined) a.byteLength = byteLength;
+    const width = attrNumber(el.attributes["width"]);
+    if (width !== undefined) a.width = width;
+    const height = attrNumber(el.attributes["height"]);
+    if (height !== undefined) a.height = height;
+    out.push(a);
+  }
+  return out;
+}
+
+function isAllowedHref(href: string): boolean {
+  return (
+    href.startsWith("http://") ||
+    href.startsWith("https://") ||
+    href.startsWith("mailto:")
+  );
+}
+
+function parseReactions(
+  commentEl: ReturnType<typeof parseBwXml>,
+): CommentReaction[] {
+  const container = firstChild(commentEl, "reactions");
+  if (!container) return [];
+  const out: CommentReaction[] = [];
+  for (const el of childrenOf(container, "reaction")) {
+    const emoji = el.attributes["emoji"];
+    const authorId = el.attributes["authorId"];
+    const reactedAt = el.attributes["reactedAt"];
+    if (!emoji || !authorId || !reactedAt) continue;
+    out.push({ emoji, authorId, reactedAt });
+  }
+  return out;
+}
+
+function parseLabels(
+  commentEl: ReturnType<typeof parseBwXml>,
+): CommentLabel[] {
+  const container = firstChild(commentEl, "labels");
+  if (!container) return [];
+  const out: CommentLabel[] = [];
+  for (const el of childrenOf(container, "label")) {
+    const key = el.attributes["key"];
+    if (!key) continue;
+    const label: CommentLabel = { key, text: textOf(el) };
+    if (el.attributes["color"] !== undefined) label.color = el.attributes["color"];
+    out.push(label);
+  }
+  return out;
+}

package/src/io/ooxml/external-custody-payload.ts

@@ -0,0 +1,102 @@
+import type { ExternalCustody } from "../../api/external-custody-types.ts";
+import {
+  attrNumber,
+  childrenOf,
+  parseBwXml,
+  renderElement,
+  stripNs,
+} from "./bw-xml.ts";
+
+const NS_URI = "urn:beyondwork:workflow-payload:1";
+
+export function buildExternalCustodyXml(custody: ExternalCustody): string {
+  const stripped = renderElement("bw:strippedComments", {}, [
+    custody.strippedCommentIds
+      .map((id) => renderElement("bw:commentRef", { commentId: id }))
+      .join(""),
+  ]);
+  const participants = custody.strippedParticipantIds.length
+    ? renderElement("bw:strippedParticipants", {}, [
+        custody.strippedParticipantIds
+          .map((id) => renderElement("bw:userRef", { id }))
+          .join(""),
+      ])
+    : "";
+  return renderElement(
+    "bw:externalCustody",
+    {
+      "xmlns:bw": NS_URI,
+      schemaVersion: String(custody.schemaVersion),
+      custodyId: custody.custodyId,
+      originDocumentId: custody.originDocumentId,
+      originPayloadId: custody.originPayloadId,
+      originContentHash: custody.originContentHash,
+      sentAt: custody.sentAt,
+      sentBy: custody.sentBy,
+      recipient: custody.recipient,
+      archiveRef: custody.archiveRef,
+    },
+    [stripped, participants],
+  );
+}
+
+export function parseExternalCustodyXml(xml: string): ExternalCustody {
+  const root = parseBwXml(xml);
+  if (stripNs(root.name) !== "externalCustody") {
+    throw new Error(
+      `parseExternalCustodyXml: expected <bw:externalCustody>, got <${root.name}>`,
+    );
+  }
+  const schemaVersion = attrNumber(root.attributes["schemaVersion"]) ?? 1;
+  if (schemaVersion !== 1) {
+    throw new Error(
+      `parseExternalCustodyXml: unsupported schemaVersion=${schemaVersion}`,
+    );
+  }
+
+  const required = [
+    "custodyId",
+    "originDocumentId",
+    "originPayloadId",
+    "originContentHash",
+    "sentAt",
+    "sentBy",
+    "recipient",
+    "archiveRef",
+  ] as const;
+  for (const key of required) {
+    if (!root.attributes[key]) {
+      throw new Error(
+        `parseExternalCustodyXml: missing required attribute ${key}`,
+      );
+    }
+  }
+
+  const strippedContainer = childrenOf(root, "strippedComments")[0];
+  const strippedCommentIds = strippedContainer
+    ? childrenOf(strippedContainer, "commentRef")
+        .map((el) => el.attributes["commentId"])
+        .filter((id): id is string => Boolean(id))
+    : [];
+
+  const participantsContainer = childrenOf(root, "strippedParticipants")[0];
+  const strippedParticipantIds = participantsContainer
+    ? childrenOf(participantsContainer, "userRef")
+        .map((el) => el.attributes["id"])
+        .filter((id): id is string => Boolean(id))
+    : [];
+
+  return {
+    schemaVersion: 1,
+    custodyId: root.attributes["custodyId"]!,
+    originDocumentId: root.attributes["originDocumentId"]!,
+    originPayloadId: root.attributes["originPayloadId"]!,
+    originContentHash: root.attributes["originContentHash"]!,
+    sentAt: root.attributes["sentAt"]!,
+    sentBy: root.attributes["sentBy"]!,
+    recipient: root.attributes["recipient"]!,
+    archiveRef: root.attributes["archiveRef"]!,
+    strippedCommentIds,
+    strippedParticipantIds,
+  };
+}