Follow a Linear issue as one conversation

import { createHmac, timingSafeEqual } from "node:crypto"

const SHA256_HEX_LENGTH = 64
const HEX_64 = /^[0-9a-f]{64}$/u
const DELIVERY_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u
export const DEFAULT_TIMESTAMP_TOLERANCE_MS = 60 * 1_000

const safeEqualHex = (provided, expected) => {
	if (provided.length !== expected.length) return false
	try {
		return timingSafeEqual(Buffer.from(provided, "utf8"), Buffer.from(expected, "utf8"))
	} catch {
		return false
	}
}

export const verifyLinearDelivery = ({
	rawBody,
	signatureHeader,
	deliveryIdHeader,
	signingSecret,
	nowMs = Date.now(),
	toleranceMs = DEFAULT_TIMESTAMP_TOLERANCE_MS,
}) => {
	if (!Buffer.isBuffer(rawBody) || rawBody.length === 0) {
		return { ok: false, reason: "empty_body" }
	}
	if (typeof signingSecret !== "string" || signingSecret === "") {
		return { ok: false, reason: "missing_secret" }
	}
	if (typeof signatureHeader !== "string" || signatureHeader === "") {
		return { ok: false, reason: "missing_signature" }
	}
	const provided = signatureHeader.trim().toLowerCase()
	if (provided.length !== SHA256_HEX_LENGTH || !HEX_64.test(provided)) {
		return { ok: false, reason: "malformed_signature" }
	}
	if (typeof deliveryIdHeader !== "string" || !DELIVERY_ID.test(deliveryIdHeader)) {
		return { ok: false, reason: "malformed_delivery_id" }
	}
	const expected = createHmac("sha256", signingSecret).update(rawBody).digest("hex")
	if (!safeEqualHex(provided, expected)) {
		return { ok: false, reason: "signature_mismatch" }
	}
	if (!Number.isSafeInteger(nowMs) || nowMs <= 0 || !Number.isSafeInteger(toleranceMs) || toleranceMs < 0) {
		return { ok: false, reason: "invalid_timestamp_window" }
	}
	let envelope
	try {
		envelope = JSON.parse(rawBody.toString("utf8"))
	} catch {
		return { ok: false, reason: "malformed_timestamp" }
	}
	const sentAt = envelope !== null && typeof envelope === "object" && !Array.isArray(envelope)
		? envelope.webhookTimestamp
		: undefined
	if (!Number.isSafeInteger(sentAt) || sentAt <= 0) {
		return { ok: false, reason: "malformed_timestamp" }
	}
	if (Math.abs(nowMs - sentAt) > toleranceMs) {
		return { ok: false, reason: "stale_timestamp" }
	}
	return { ok: true, deliveryId: deliveryIdHeader }
}

const conversationForIssue = (issueId) => ({
	kind: "thread",
	root_external_id: `linear:issue:${issueId}`,
	thread_external_id: `linear:issue:${issueId}`,
})

const externalEventId = (event) =>
	event.type === "Comment" ? `linear:comment:${event.resourceId}` : `linear:${event.type.toLowerCase()}:${event.resourceId}`

const events = await checkfu.sessions.events.list(sessionId, {
	after: ingestReceipt.event_sequence,
})
for await (const agentMessage of events) {
	if (
		agentMessage.type !== "agent.message" ||
		agentMessage.seq <= ingestReceipt.event_sequence ||
		typeof agentMessage.payload.content !== "string"
	) continue
	// Claim and post this message using the presentation fence below.
}

const key = {
	conversation_binding_id: binding.id,
	session_id: ingestReceipt.session_id,
	interaction_id: ingestReceipt.event_id,
	kind: "final",
	revision: String(agentMessage.seq),
	delivery_role: "reply",
}

const claimed = await checkfu.collaboration.conversationPresentations.claim({
	external_installation_id: installation.id,
	key,
	through_sequence: agentMessage.seq,
})
if (!claimed.won) return // another replica owns this presentation

const dispatch = {
	external_installation_id: installation.id,
	key,
	generation: claimed.attempt.generation,
	owner: claimed.attempt.owner,
	// The public contract shape: cpd_ + 40 hex, minted once per dispatch.
	dispatch_token: `cpd_${crypto.randomBytes(20).toString("hex")}`,
}

await checkfu.collaboration.conversationPresentations.beginDispatch(dispatch)
const posted = await yourLinearClient.createComment(issueId, agentMessage.payload.content)
await checkfu.collaboration.conversationPresentations.settle({
	...dispatch,
	outcome: posted.unknownOutcome
		? { state: "indeterminate" }
		: posted.commentId
			? { state: "posted", provider_message_id: posted.commentId }
			: { state: "known_failed" },
})

node --test test/*.test.mjs