@firedrill-tools/linkedin 0.1.1

package/firedrill/tools/linkedin/app/site/ui.js

@@ -0,0 +1,142 @@
+// DOM, Tool-call, time and toast helpers for the LinkedIn Tool app. Record text only ever reaches the DOM via textContent.
+import { invoke } from "/_firedrill/client.js";
+import { icon } from "./icons.js";
+
+export const $ = (selector, root = document) => root.querySelector(selector);
+export const $$ = (selector, root = document) => [...root.querySelectorAll(selector)];
+
+/** Create an element. options: { class, text, title, attrs, on: {event: handler} }. */
+export function el(tag, options = {}, children = []) {
+  const node = document.createElement(tag);
+  if (options.class) node.className = options.class;
+  if (options.text !== undefined && options.text !== null) node.textContent = String(options.text);
+  if (options.title) node.title = options.title;
+  if (options.attrs) for (const [name, value] of Object.entries(options.attrs)) if (value !== undefined && value !== null && value !== false) node.setAttribute(name, value === true ? "" : String(value));
+  if (options.on) for (const [name, handler] of Object.entries(options.on)) node.addEventListener(name, handler);
+  for (const child of Array.isArray(children) ? children : [children]) if (child !== undefined && child !== null && child !== false) node.append(child);
+  return node;
+}
+
+export function iconButton(name, label, onClick, className = "") {
+  return el("button", { class: `icon-btn ${className}`.trim(), title: label, attrs: { type: "button", "aria-label": label }, on: onClick ? { click: onClick } : undefined }, icon(name));
+}
+
+// ---- Tool calls ------------------------------------------------------------------------------
+
+export class ToolError extends Error {
+  constructor(status, code, message, retryable) {
+    super(message);
+    this.status = status;
+    this.code = String(code ?? status).replace(/^tool\./, "");
+    this.retryable = Boolean(retryable);
+  }
+  get denied() { return this.status === "denied" || this.code === "ACCESS_DENIED"; }
+}
+
+let writeListener = () => {};
+export const onWrite = (listener) => { writeListener = listener; };
+
+/** Invoke one operation; resolves the value or throws ToolError. Mutations pass an idempotency key. */
+export async function call(operationId, args = {}, idempotencyKey) {
+  let result;
+  try {
+    result = await invoke(operationId, args, idempotencyKey ? { idempotencyKey } : {});
+  } catch (error) {
+    throw new ToolError("transport", "NETWORK", "Couldn't reach the service. Check that the environment is still running.");
+  }
+  const outcome = result?.outcome ?? {};
+  if (idempotencyKey) writeListener();
+  if (outcome.status !== "ok") {
+    const error = outcome.error ?? {};
+    throw new ToolError(outcome.status, error.code, error.message ?? `The request was ${outcome.status}.`, error.retryable);
+  }
+  return outcome.value;
+}
+
+export const newKey = () => crypto.randomUUID();
+
+/** LinkedIn-style wording for an operation failure. */
+export function describe(error) {
+  if (!(error instanceof ToolError)) return "Something went wrong. Please try again.";
+  if (error.status === "denied") return "You don't have access to do that with this account.";
+  switch (error.code) {
+    case "INVALID_ACCESS_TOKEN": return "Your session has expired. Sign in again to continue.";
+    case "ACCESS_DENIED": return "You don't have permission to do that.";
+    case "TOO_MANY_REQUESTS": return "You're commenting too fast. Please wait a moment and try again.";
+    case "SERVICE_UNAVAILABLE": return "Reactions are temporarily unavailable. Please try again later.";
+    case "NOT_FOUND": return "This content isn't available.";
+    case "INTERNAL_SERVER_ERROR": return "Something went wrong on our end. Please try again.";
+    default: return error.message || "Something went wrong. Please try again.";
+  }
+}
+
+// ---- Time (world virtual time only, UTC) -----------------------------------------------------
+
+let serverNowMs = 0;
+export const setServerNow = (ms) => { if (Number.isFinite(ms)) serverNowMs = ms; };
+export const serverNow = () => serverNowMs;
+
+/** "now", "5m", "2h", "3d", "1w", "4mo", "1yr" as the feed renders them. */
+export function relativeTime(ms) {
+  const diff = Math.max(0, serverNowMs - ms);
+  const min = Math.floor(diff / 60000);
+  if (min < 1) return "now";
+  if (min < 60) return `${min}m`;
+  const h = Math.floor(min / 60);
+  if (h < 24) return `${h}h`;
+  const d = Math.floor(h / 24);
+  if (d < 7) return `${d}d`;
+  if (d < 30) return `${Math.floor(d / 7)}w`;
+  if (d < 365) return `${Math.floor(d / 30)}mo`;
+  return `${Math.floor(d / 365)}yr`;
+}
+
+const MONTHS = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+export function longDate(ms) {
+  const date = new Date(ms);
+  return `${MONTHS[date.getUTCMonth()]} ${date.getUTCDate()}, ${date.getUTCFullYear()}`;
+}
+
+// ---- Avatars ---------------------------------------------------------------------------------
+
+const AVATAR_COLOURS = ["#0a66c2", "#057642", "#915907", "#8f5849", "#5f4b8b", "#b24020", "#0e7470", "#56687a"];
+export function avatar(name, seed, size = 48, organization = false) {
+  const text = String(name ?? "?").trim();
+  const initials = organization
+    ? text.slice(0, 1).toUpperCase()
+    : text.split(/\s+/).filter(Boolean).slice(0, 2).map((part) => [...part][0]?.toUpperCase() ?? "").join("");
+  let hash = 0;
+  for (const char of String(seed ?? text)) hash = (hash * 31 + char.codePointAt(0)) >>> 0;
+  const node = el("span", { class: `avatar avatar--${size}${organization ? " avatar--org" : ""}`, text: initials || "?", attrs: { "aria-hidden": "true" } });
+  node.style.setProperty("--avatar-bg", AVATAR_COLOURS[hash % AVATAR_COLOURS.length]);
+  return node;
+}
+
+// ---- Toast -----------------------------------------------------------------------------------
+
+let toastTimer;
+export function toast(text, { error = false, actionLabel, onAction, timeout = 6000 } = {}) {
+  const host = $("#toast");
+  $("#toast-text").textContent = text;
+  const iconHost = $("#toast-icon");
+  iconHost.replaceChildren(icon(error ? "alert" : "check"));
+  host.dataset.error = String(error);
+  const button = $("#toast-action");
+  button.hidden = !actionLabel;
+  button.textContent = actionLabel ?? "";
+  button.onclick = () => { host.hidden = true; if (onAction) onAction(); };
+  host.hidden = false;
+  clearTimeout(toastTimer);
+  toastTimer = setTimeout(() => { host.hidden = true; }, timeout);
+}
+export function initToast() {
+  $("#toast-close").addEventListener("click", () => { $("#toast").hidden = true; });
+}
+
+/** Button spinner/disabled state around an async task; ignores re-entry. */
+export async function busy(button, task) {
+  if (button?.dataset.busy === "true") return undefined;
+  if (button) { button.dataset.busy = "true"; button.disabled = true; }
+  try { return await task(); }
+  finally { if (button) { button.dataset.busy = "false"; button.disabled = false; } }
+}

package/firedrill/tools/linkedin/behavior.mjs

@@ -0,0 +1,66 @@
+// Synthetic LinkedIn member network for Firedrill: the versioned Community Management REST API subset under /rest plus
+// the /v2 consumer endpoints. Every operation computes from `context.state`; nothing is sent to LinkedIn.
+import * as R from "./lib/routes.mjs";
+import { encoder } from "./lib/wire.mjs";
+import { createComment, deleteComment, updateComment } from "./ops/comments-write.mjs";
+import { getComment, listComments } from "./ops/comments-read.mjs";
+import { listFeed } from "./ops/feed.mjs";
+import { getNetworkSize, listConnections } from "./ops/network.mjs";
+import { findByVanityName, getOrganization, listAcls } from "./ops/orgs.mjs";
+import { deletePost, updatePost } from "./ops/posts-edit.mjs";
+import { getPost, listByAuthor } from "./ops/posts-read.mjs";
+import { createPost } from "./ops/posts-write.mjs";
+import { getPerson, me, userinfo } from "./ops/profile.mjs";
+import { createReaction, deleteReaction, listReactions } from "./ops/reactions.mjs";
+import { getSocialMetadata, setCommentsState } from "./ops/social.mjs";
+
+const body = (value) => ({ body: value });
+const empty = () => ({});
+const json = encoder(body);
+const v2json = encoder(body, true);
+// A compound-key GET answers the bare reaction; the entity finder answers the collection.
+const reactionsEncoder = (result) =>
+  encoder((page) => ({ body: result.invocation?.arguments?.single === true ? page.elements[0] : page }))(result);
+
+// [operation id, handler, [route id, decoder, encoder]...]
+const TABLE = [
+  ["profile.userinfo", userinfo, ["userinfo", R.plain, v2json]],
+  ["profile.me", me, ["me", R.plain, v2json]],
+  ["people.get", getPerson, ["get-person", R.getPerson, v2json]],
+  ["posts.create", createPost,
+    ["create-post", R.createPost, encoder((post) => ({ headers: { "x-restli-id": post.id, "x-linkedin-id": post.id } }))],
+    ["create-ugc-post", R.createUgcPost, encoder((post) => ({ headers: { "x-restli-id": post.id }, body: { id: post.id } }), true)]],
+  ["posts.get", getPost, ["get-post", R.getPost, json]],
+  ["posts.list_by_author", listByAuthor, ["find-posts", R.findPosts, json]],
+  ["posts.update", updatePost, ["update-post", R.updatePost, encoder(empty)]],
+  ["posts.delete", deletePost, ["delete-post", R.deletePost("postUrn", true), encoder(empty)],
+    ["delete-ugc-post", R.deletePost("ugcPostUrn", false), encoder(empty, true)]],
+  ["feed.list", listFeed],
+  ["comments.create", createComment, ["create-comment", R.createComment, encoder((c) => ({ headers: { "x-restli-id": c.id }, body: c }))]],
+  ["comments.list", listComments, ["list-comments", R.listComments, json]],
+  ["comments.get", getComment, ["get-comment", R.getComment, json]],
+  ["comments.update", updateComment,
+    ["update-comment", R.updateComment, encoder((c) => ({ headers: { "x-resourceidentity-urn": c.commentUrn }, body: c }))]],
+  ["comments.delete", deleteComment, ["delete-comment", R.deleteComment, encoder(empty)]],
+  ["reactions.create", createReaction, ["create-reaction", R.createReaction, json]],
+  ["reactions.list", listReactions,
+    ["get-reactions", R.getReactions, reactionsEncoder]],
+  ["reactions.delete", deleteReaction, ["delete-reaction", R.deleteReaction, encoder(empty)]],
+  ["social_metadata.get", getSocialMetadata, ["get-social-metadata", R.getSocialMetadata, json]],
+  ["social_metadata.set_comments_state", setCommentsState, ["update-social-metadata", R.updateSocialMetadata, encoder(empty)]],
+  ["organizations.get", getOrganization, ["get-organization", R.getOrganization, json]],
+  ["organizations.find_by_vanity_name", findByVanityName, ["find-organizations", R.findOrganizations, json]],
+  ["organization_acls.list", listAcls, ["find-organization-acls", R.findAcls, json]],
+  ["network_sizes.get", getNetworkSize, ["get-network-size", R.getNetworkSize, json],
+    ["get-connection-size", R.getConnectionSize, encoder(body, true)]],
+  ["connections.list", listConnections],
+];
+
+const operations = {};
+const http = {};
+for (const [operationId, handler, ...routes] of TABLE) {
+  operations[operationId] = handler;
+  for (const [routeId, decode, encode] of routes) http[routeId] = { decode, encode };
+}
+
+export default { operations, http };

package/firedrill/tools/linkedin/lib/access.mjs

@@ -0,0 +1,69 @@
+// Post and thread resolution with LinkedIn visibility rules (drafts, CONNECTIONS posts, tombstones).
+import { connected, managesAuthor, requireScope, urnField } from "./auth.mjs";
+import { fail, notFound } from "./errors.mjs";
+import { parseUrn } from "./urn.mjs";
+
+const COMMENT_ID = /^[0-9]{1,19}$/;
+
+/** Post row for a share, ugcPost or activity URN (already parsed), or null. */
+export function findPost(context, parsed) {
+  if (parsed.type === "activity") {
+    const activity = context.state.get("activities", parsed.id);
+    return activity === null ? null : context.state.get("posts", activity.postId);
+  }
+  const post = context.state.get("posts", parsed.id);
+  return post !== null && post.kind === parsed.type ? post : null;
+}
+
+/** Read scope for a thread: member-authored threads need r_member_social, organization threads r_organization_social. */
+export function requireReadScope(context, who, authorUrn, resource) {
+  const organization = parseUrn(authorUrn)?.type === "organization";
+  requireScope(context, who, [organization ? "r_organization_social" : "r_member_social"], resource);
+}
+
+/** "ok", "missing" (deleted, or a draft outside the author view) or "hidden" (a CONNECTIONS post of a non-connection). */
+export function visibility(context, who, post, viewContext = "READER") {
+  if (post.deletedAtMs !== null) return "missing";
+  if (post.lifecycleState === "DRAFT" && (viewContext !== "AUTHOR" || !managesAuthor(context, who, post.author))) return "missing";
+  if (post.visibility === "CONNECTIONS" && post.author !== who.urn) {
+    const author = parseUrn(post.author);
+    if (author === null || author.type !== "person" || !connected(context, who.personId, author.id)) return "hidden";
+  }
+  return "ok";
+}
+
+/** Loads a post the caller may read, failing NOT_FOUND / ACCESS_DENIED as LinkedIn does. */
+export function loadVisiblePost(context, who, parsed, resource, viewContext = "READER", write = false) {
+  const post = findPost(context, parsed);
+  if (post === null) notFound(context, `Post ${parsed.urn} not found`);
+  if (!write) requireReadScope(context, who, post.author, resource);
+  const seen = visibility(context, who, post, viewContext);
+  if (seen === "missing") notFound(context, `Post ${parsed.urn} not found`);
+  if (seen === "hidden") fail(context, "ACCESS_DENIED", `Not enough permissions to access: ${parsed.urn}`);
+  return post;
+}
+
+/**
+ * Resolves a social-action target (share, ugcPost, activity or comment URN) to `{ post, comment }`; `comment` is the
+ * stored comment row when the target is a comment URN. Drafts resolve for their author so writes can refuse them.
+ */
+export function loadThread(context, who, field, value, resource, { inPath = false, types, write = false } = {}) {
+  const parsed = urnField(context, field, value, types ?? ["share", "ugcPost", "activity", "comment"], { inPath });
+  if (parsed.type === "comment") {
+    const activity = context.state.get("activities", parsed.activityId);
+    if (activity === null) notFound(context, `Comment ${parsed.urn} not found`);
+    const post = loadVisiblePost(context, who, { type: "activity", id: parsed.activityId, urn: `urn:li:activity:${parsed.activityId}` },
+      resource, "AUTHOR", write);
+    const comment = context.state.get("comments", `${parsed.activityId}|${parsed.commentId}`);
+    if (comment === null) notFound(context, `Comment ${parsed.urn} not found`);
+    return { post, comment, parsed };
+  }
+  return { post: loadVisiblePost(context, who, parsed, resource, "AUTHOR", write), comment: null, parsed };
+}
+
+/** Validates a comment id path key (digits only). */
+export function commentIdArg(context, value, inPath) {
+  if (typeof value === "string" && COMMENT_ID.test(value)) return value;
+  if (inPath) return fail(context, "BAD_REQUEST", "Syntax exception in path variables");
+  return fail(context, "INVALID_URN_ID", "The URN ID provided is invalid");
+}

package/firedrill/tools/linkedin/lib/auth.mjs

@@ -0,0 +1,115 @@
+// Caller identity (token), OAuth scopes, Rest.li wire checks and organization roles.
+import { badRequest, fail, missing, shortValue } from "./errors.mjs";
+import { organizationUrn, parseUrn, personUrn, urnType } from "./urn.mjs";
+
+export const DEFAULT_SCOPES = ["openid", "profile", "email", "w_member_social", "r_member_social", "rw_organization_admin",
+  "r_organization_social", "w_organization_social", "r_1st_connections_size"];
+const ACTIVE_VERSIONS = new Set(["202509", "202510", "202511", "202512", "202601", "202602", "202603", "202604", "202605", "202606",
+  "202607", "202608"]);
+export const POSTER_ROLES = new Set(["ADMINISTRATOR", "CONTENT_ADMINISTRATOR", "DIRECT_SPONSORED_CONTENT_POSTER"]);
+export const READER_ROLES = new Set([...POSTER_ROLES, "ANALYST", "CURATOR"]);
+const PERSON_ID = /^[A-Za-z0-9_-]{10}$/;
+
+/** Resolves the member the token belongs to: `linkedinPersonId`, else the network's default member. */
+export function caller(context) {
+  const attributes = context.actor.attributes ?? {};
+  let personId = Object.hasOwn(attributes, "linkedinPersonId") ? attributes.linkedinPersonId : undefined;
+  if (personId === undefined || personId === null) personId = context.state.get("meta", "network")?.defaultPersonId;
+  const person = typeof personId === "string" && PERSON_ID.test(personId) ? context.state.get("people", personId) : null;
+  if (person === null) fail(context, "INVALID_ACCESS_TOKEN", "Invalid access token");
+  const raw = Object.hasOwn(attributes, "linkedinScopes") ? attributes.linkedinScopes : undefined;
+  const scopes = new Set(Array.isArray(raw) ? raw.filter((scope) => typeof scope === "string") : DEFAULT_SCOPES);
+  return { personId, person, urn: personUrn(personId), scopes };
+}
+
+/**
+ * Header and syntax checks for requests that arrived through an HTTP route (`input.wire`). Canonical, MCP and app callers
+ * send no `wire` and skip them. `expected` is the Rest.li method the route implements.
+ */
+export function checkWire(context, input, expected, restAllowed = true) {
+  const wire = input.wire;
+  if (wire === undefined) return;
+  if (wire.rest === true && restAllowed) {
+    const version = wire.linkedinVersion;
+    if (typeof version !== "string" || version.trim() === "") {
+      fail(context, "VERSION_MISSING", "A version must be present. Please specify a version by adding the Linkedin-Version header.");
+    }
+    if (!ACTIVE_VERSIONS.has(version.trim())) fail(context, "NONEXISTENT_VERSION", `Requested version ${shortValue(version)} is not active`);
+    const method = wire.restliMethod;
+    if (method === null || method === undefined) {
+      if (wire.requireMethod === true) badRequest(context, "Invalid X-RestLi-Method header");
+    } else if (method.trim().toUpperCase() !== expected) badRequest(context, "Invalid X-RestLi-Method header");
+  }
+  if (typeof wire.error === "string") badRequest(context, wire.error);
+}
+
+/** Fails ACCESS_DENIED unless the token holds at least one of the scopes. */
+export function requireScope(context, who, anyOf, resource) {
+  if (!anyOf.some((scope) => who.scopes.has(scope))) fail(context, "ACCESS_DENIED", `Not enough permissions to access: ${resource}`);
+}
+
+const ALL_ROLES = ["ADMINISTRATOR", "DIRECT_SPONSORED_CONTENT_POSTER", "RECRUITING_POSTER", "LEAD_CAPTURE_ADMINISTRATOR",
+  "LEAD_GEN_FORMS_MANAGER", "ANALYST", "CURATOR", "CONTENT_ADMINISTRATOR"];
+
+/** Approved roles of a member on an organization (one direct read per role; no scan). */
+export function rolesOn(context, organizationId, personId) {
+  const roles = new Set();
+  for (const role of ALL_ROLES) {
+    if (context.state.get("organization-acls", `${organizationId}|${personId}|${role}`)?.state === "APPROVED") roles.add(role);
+  }
+  return roles;
+}
+
+export const holdsAny = (roles, wanted) => [...roles].some((role) => wanted.has(role));
+
+/**
+ * Validates a URN-valued field. `types` lists accepted URN types; `inPath` makes syntax problems Rest.li path errors.
+ * Returns the parsed URN, or null when the value is absent and `required` is false.
+ */
+export function urnField(context, field, value, types, { required = true, inPath = false } = {}) {
+  if (value === undefined || value === null) {
+    if (!required) return null;
+    return missing(context, field);
+  }
+  const parsed = parseUrn(value);
+  if (inPath && (parsed === null || !types.includes(parsed.type))) return badRequest(context, "Syntax exception in path variables");
+  if (parsed === null) {
+    const type = urnType(value);
+    if (type !== null && !types.includes(type)) {
+      return fail(context, "INVALID_URN_TYPE", `${field} value ${shortValue(value)} must be a ${types.join(" or ")} URN`);
+    }
+    return fail(context, "INVALID_URN_ID", "The URN ID provided is invalid");
+  }
+  if (!types.includes(parsed.type)) {
+    return fail(context, "INVALID_URN_TYPE", `${field} value ${shortValue(value)} must be a ${types.join(" or ")} URN`);
+  }
+  return parsed;
+}
+
+/**
+ * Checks that the caller may act as `actorValue` (its own person URN, or an organization it holds a poster role on) and
+ * that the token carries the matching write scope. Returns `{ urn, kind, id, agent }`.
+ */
+export function actingAs(context, who, field, actorValue, resource) {
+  const parsed = urnField(context, field, actorValue, ["person", "organization"]);
+  if (parsed.type === "person") {
+    requireScope(context, who, ["w_member_social"], resource);
+    if (parsed.id !== who.personId) fail(context, "ACCESS_DENIED", `Not enough permissions to act as ${parsed.urn}`);
+    return { urn: parsed.urn, kind: "person", id: parsed.id, agent: null };
+  }
+  requireScope(context, who, ["w_organization_social"], resource);
+  const organization = context.state.get("organizations", parsed.id);
+  if (organization === null || !holdsAny(rolesOn(context, parsed.id, who.personId), POSTER_ROLES)) {
+    fail(context, "ACCESS_DENIED", `Not enough permissions to act as ${parsed.urn}`);
+  }
+  return { urn: organizationUrn(parsed.id), kind: "organization", id: parsed.id, agent: who.personId };
+}
+
+/** Whether the caller may manage content authored by `authorUrn` (the author itself, or a poster of that page). */
+export function managesAuthor(context, who, authorUrn) {
+  if (authorUrn === who.urn) return true;
+  const parsed = parseUrn(authorUrn);
+  return parsed !== null && parsed.type === "organization" && holdsAny(rolesOn(context, parsed.id, who.personId), POSTER_ROLES);
+}
+
+export const connected = (context, a, b) => context.state.get("connections", `${a}|${b}`) !== null;

package/firedrill/tools/linkedin/lib/cascade.mjs

@@ -0,0 +1,28 @@
+// Cascading deletes: comments of a thread and the reactions on posts and comments.
+import { scanPrefix, scanValues } from "./store.mjs";
+import { activityUrn, commentUrn } from "./urn.mjs";
+
+export const reactionsOn = (context, entityUrn) => scanValues(context, "reactions", `${entityUrn}|`);
+export const threadComments = (context, activityId) => scanValues(context, "comments", `${activityId}|`);
+
+export function deleteReactionsOn(context, entityUrn) {
+  const rows = scanPrefix(context, "reactions", `${entityUrn}|`);
+  for (const row of rows) context.state.delete("reactions", row.rowId);
+  return rows.length;
+}
+
+/** Deletes comment rows and the reactions on each; returns the number of comments deleted. */
+export function deleteComments(context, comments) {
+  for (const comment of comments) {
+    deleteReactionsOn(context, commentUrn(comment.activityId, comment.id));
+    context.state.delete("comments", `${comment.activityId}|${comment.id}`);
+  }
+  return comments.length;
+}
+
+/** Deletes every comment of a thread, their reactions and the reactions on the post itself. */
+export function deleteThread(context, activityId) {
+  const deleted = deleteComments(context, threadComments(context, activityId));
+  deleteReactionsOn(context, activityUrn(activityId));
+  return deleted;
+}

package/firedrill/tools/linkedin/lib/errors.mjs

@@ -0,0 +1,50 @@
+// Declared Tool error codes, their HTTP status and LinkedIn `serviceErrorCode`, plus failure helpers.
+
+export const ERRORS = new Map([
+  ["INVALID_ACCESS_TOKEN", [401, 65600]],
+  ["VERSION_MISSING", [400, 0]],
+  ["NONEXISTENT_VERSION", [426, 0]],
+  ["BAD_REQUEST", [400, 0]],
+  ["ACCESS_DENIED", [403, 100]],
+  ["NOT_FOUND", [404, 0]],
+  ["MISSING_FIELD", [400, 0]],
+  ["INVALID_VALUE_FOR_FIELD", [400, 0]],
+  ["INVALID_VALUE_BLANK_FIELD", [400, 0]],
+  ["FIELD_LENGTH_TOO_LONG", [400, 0]],
+  ["INVALID_URN_TYPE", [400, 0]],
+  ["INVALID_URN_ID", [400, 0]],
+  ["UNPROCESSABLE_ENTITY", [422, 0]],
+  ["TOO_MANY_REQUESTS", [429, 0]],
+  ["INTERNAL_SERVER_ERROR", [500, 0]],
+  ["SERVICE_UNAVAILABLE", [503, 0]],
+]);
+
+/** Fails the current operation with a declared code. Messages never name objects created in the same call. */
+export function fail(context, code, message) {
+  context.fail({ code, message });
+}
+
+export const missing = (context, field) => fail(context, "MISSING_FIELD", `${field} is required but missing`);
+export const invalidValue = (context, field, value) =>
+  fail(context, "INVALID_VALUE_FOR_FIELD", `${field} can't be set to ${shortValue(value)}`);
+export const blank = (context, field) => fail(context, "INVALID_VALUE_BLANK_FIELD", `${field} can't be blank`);
+export const tooLong = (context, field, length, max) =>
+  fail(context, "FIELD_LENGTH_TOO_LONG", `${field} length ${length} can't exceeded maximum ${max} length`);
+export const notFound = (context, message = "Not Found") => fail(context, "NOT_FOUND", message);
+export const unprocessable = (context, message) => fail(context, "UNPROCESSABLE_ENTITY", message);
+export const badRequest = (context, message) => fail(context, "BAD_REQUEST", message);
+
+/** Renders a caller value inside an error message without echoing unbounded text. */
+export function shortValue(value) {
+  let text;
+  if (typeof value === "string") text = value;
+  else if (value === undefined) text = "undefined";
+  else {
+    try {
+      text = JSON.stringify(value) ?? String(value);
+    } catch {
+      text = "an unsupported value";
+    }
+  }
+  return text.length > 80 ? `${text.slice(0, 77)}...` : text;
+}

package/firedrill/tools/linkedin/lib/message.mjs

@@ -0,0 +1,43 @@
+// Comment message validation: text (≤ 1250 characters) and mention attributes.
+import { blank, invalidValue, missing, tooLong } from "./errors.mjs";
+import { parseUrn } from "./urn.mjs";
+
+export const MAX_COMMENT = 1250;
+const MAX_ATTRIBUTES = 50;
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** Returns `{ text, attributes }` in stored form (`{ start, length, person, organization }`). */
+export function messageArg(context, message, field = "message") {
+  if (message === undefined || message === null) return missing(context, field);
+  if (!isObject(message)) return invalidValue(context, field, message);
+  const text = message.text;
+  if (text === undefined || text === null || (typeof text === "string" && text.trim() === "")) return blank(context, `${field}/text`);
+  if (typeof text !== "string") return invalidValue(context, `${field}/text`, text);
+  if (text.length > MAX_COMMENT) return tooLong(context, `${field}/text`, text.length, MAX_COMMENT);
+  const raw = message.attributes ?? [];
+  if (!Array.isArray(raw) || raw.length > MAX_ATTRIBUTES) return invalidValue(context, `${field}/attributes`, "more than 50 attributes");
+  const attributes = [];
+  for (let i = 0; i < raw.length; i += 1) {
+    const where = `${field}/attributes/${i}`;
+    const attribute = raw[i];
+    if (!isObject(attribute)) return invalidValue(context, where, attribute);
+    const { start, length, value } = attribute;
+    if (!Number.isInteger(start) || start < 0 || !Number.isInteger(length) || length < 1 || start + length > text.length) {
+      return invalidValue(context, `${where}/start`, `${start}+${length} outside the text`);
+    }
+    if (!isObject(value)) return invalidValue(context, `${where}/value`, value);
+    const personUrn = isObject(value.person) ? value.person.person : undefined;
+    const organizationUrn = isObject(value.organization) ? value.organization.organization : undefined;
+    const person = parseUrn(personUrn);
+    const organization = parseUrn(organizationUrn);
+    if (person !== null && person.type === "person" && organizationUrn === undefined && context.state.get("people", person.id) !== null) {
+      attributes.push({ start, length, person: person.id, organization: null });
+    } else if (organization !== null && organization.type === "organization" && personUrn === undefined
+      && context.state.get("organizations", organization.id) !== null) {
+      attributes.push({ start, length, person: null, organization: Number(organization.id) });
+    } else {
+      return invalidValue(context, `${where}/value`, value);
+    }
+  }
+  return { text, attributes };
+}

package/firedrill/tools/linkedin/lib/paging.mjs

@@ -0,0 +1,54 @@
+// Offset paging (`start`/`count`) with Rest.li links and a UTF-8 byte budget per page.
+import { fail, invalidValue } from "./errors.mjs";
+import { jsonBytes } from "./text.mjs";
+
+export const PAGE_BYTE_BUDGET = 900000;
+
+export function pageArgs(context, input, { defaultCount = 10, maxCount = 100 } = {}) {
+  const start = input.start ?? 0;
+  const count = input.count ?? defaultCount;
+  if (!Number.isInteger(start) || start < 0 || start > 1000000) invalidValue(context, "start", start);
+  if (!Number.isInteger(count) || count < 1 || count > maxCount) invalidValue(context, "count", count);
+  return { start, count };
+}
+
+function encode(value) {
+  try {
+    return encodeURIComponent(value);
+  } catch {
+    return "";
+  }
+}
+
+/** Query string from ordered [name, value] pairs (values null/undefined skipped). */
+export function queryString(pairs) {
+  return pairs.filter(([, value]) => value !== null && value !== undefined).map(([name, value]) => `${name}=${encode(String(value))}`).join("&");
+}
+
+/**
+ * Builds `{ paging, elements }` from the full ordered `items`, rendering with `render` from `start` while the page has room
+ * in `count` and in the byte budget. A byte-limited page ends early with a `next` link at the first omitted item.
+ */
+export function buildPage(context, items, render, { start, count, path, query = [], withTotal = true }) {
+  const elements = [];
+  let bytes = 200;
+  for (let i = start; i < items.length && elements.length < count; i += 1) {
+    const element = render(items[i]);
+    const size = jsonBytes(element) + 1;
+    if (bytes + size > PAGE_BYTE_BUDGET) {
+      if (elements.length === 0) fail(context, "INTERNAL_SERVER_ERROR", "a single element exceeds the response size budget");
+      break;
+    }
+    bytes += size;
+    elements.push(element);
+  }
+  const links = [];
+  const next = start + elements.length;
+  if (start > 0) {
+    links.push({ rel: "prev", href: `${path}?${queryString([...query, ["start", Math.max(0, start - count)], ["count", count]])}`, type: "application/json" });
+  }
+  if (next < items.length) {
+    links.push({ rel: "next", href: `${path}?${queryString([...query, ["start", next], ["count", count]])}`, type: "application/json" });
+  }
+  return { paging: { start, count, links, ...(withTotal ? { total: items.length } : {}) }, elements };
+}

package/firedrill/tools/linkedin/lib/postinput.mjs

@@ -0,0 +1,47 @@
+// Validation of post fields shared by create and partial update.
+import { blank, invalidValue, tooLong } from "./errors.mjs";
+import { templateHashtags } from "./text.mjs";
+
+export const MAX_COMMENTARY = 3000;
+export const VISIBILITIES = new Set(["PUBLIC", "CONNECTIONS", "LOGGED_IN"]);
+export const FEED_DISTRIBUTIONS = new Set(["MAIN_FEED", "NONE"]);
+
+/** Returns templated commentary ("" when absent). Blank checks are the caller's (they depend on article/reshare). */
+export function commentaryArg(context, value) {
+  if (value === undefined || value === null) return "";
+  if (typeof value !== "string") return invalidValue(context, "commentary", value);
+  if (value.length > MAX_COMMENTARY) return tooLong(context, "commentary", value.length, MAX_COMMENTARY);
+  const templated = templateHashtags(value);
+  if (templated.length > MAX_COMMENTARY) return tooLong(context, "commentary", templated.length, MAX_COMMENTARY);
+  return value.trim() === "" ? "" : templated;
+}
+
+/** Validates `content`; only `content.article` is simulated. Returns the stored article or null. */
+export function contentArg(context, content) {
+  if (content === undefined || content === null) return null;
+  if (typeof content !== "object" || Array.isArray(content)) return invalidValue(context, "content", content);
+  for (const key of Object.keys(content)) {
+    if (key !== "article") return invalidValue(context, `content/${key}`, "an unsupported content type");
+  }
+  const article = content.article;
+  if (article === undefined) return invalidValue(context, "content", content);
+  if (article === null || typeof article !== "object" || Array.isArray(article)) return invalidValue(context, "content/article", article);
+  const { source, title, description } = article;
+  if (typeof source !== "string" || !/^https:\/\/[^\s/]+/.test(source)) return invalidValue(context, "content/article/source", source);
+  if (source.length > 2000) return tooLong(context, "content/article/source", source.length, 2000);
+  if (typeof title !== "string" || title.trim() === "") return blank(context, "content/article/title");
+  if (title.length > 400) return tooLong(context, "content/article/title", title.length, 400);
+  if (description !== undefined && description !== null && typeof description !== "string") {
+    return invalidValue(context, "content/article/description", description);
+  }
+  if (typeof description === "string" && description.length > 4000) {
+    return tooLong(context, "content/article/description", description.length, 4000);
+  }
+  return { source, title, description: typeof description === "string" && description !== "" ? description : null };
+}
+
+/** Compares two 1–19 digit decimal id strings numerically. */
+export function compareIds(a, b) {
+  if (a.length !== b.length) return a.length - b.length;
+  return a < b ? -1 : a > b ? 1 : 0;
+}