# LibertyTools LibertyTools is an independent ER:LC integration. ER:LC sends server events to a LibertyTools connection; a connection can run hosted commands, expose events to a private Poll client, and forward events to a user-owned HTTP endpoint. ## Human-readable guides - https://libertytools.dev/docs/examples — downloadable staff-help Discord bot, LibertyJS custom commands, and plain HTTP Poll reader, each with README and .env.example. - https://libertytools.dev/docs — choose a no-code command, Poll bot, or forwarding setup. - https://libertytools.dev/docs/hosted-commands — create and test a command without coding. - https://libertytools.dev/docs/poll — set up a v2 Poll client and LibertyJS bot. - https://libertytools.dev/docs/forwarding — choose Signed Proxy or Raw Mirror. - https://libertytools.dev/docs/events — event shape, credentials, and retention limits. - https://libertytools.dev/docs/api-reference — public v2 Poll read and acknowledge routes. - https://libertytools.dev/docs/troubleshooting — diagnose common failures. - https://libertytools.dev/docs/ai — brief and verification checklist for coding assistants. - https://github.com/Liberty-Tools/LibertyJS — JavaScript/TypeScript SDK README and runnable examples. ## Integration facts - The Poll HTTP API reference includes exact parameters, response fields, acknowledgement arrays, pagination, and error handling: https://libertytools.dev/docs/api-reference. - HTTP Poll reads require only the subscription ID and Poll token. LibertyJS construction currently requires SERVER_KEY too; the Poll bot example uses it to send replies. - Normalized events include id, connectionId, type, occurredAt, receivedAt, data, and synthetic. serverId, originalType, and data.username are optional. There is no per-event pollState property. Unknown source types become Unknown with originalType when available. - Poll reads are oldest first. Follow nextCursor only while hasMore is true, then begin the next scan without a cursor so failed earlier events are retried. Reading does not acknowledge. Acknowledge at most 100 IDs after successful handling; inspect acknowledged, alreadyAcknowledged, and unknown arrays. - Hosted commands not yet sent can wait automatically for capacity and expire after five minutes. Rejected or uncertain sends are not automatically replayed. - New connections use a public ER:LC ingest URL configured in ER:LC server settings. This URL cannot read stored Poll events. - A v2 Poll client needs both POLL_SUBSCRIPTION_ID and private POLL_TOKEN from the dashboard Outputs tab. Send the token only as a Bearer credential from server-side code. - LibertyJS is a Node.js SDK, not a browser SDK. Install with `npm install @libertytools/libertyjs` and use Node.js 18 or newer. - A hosted command runs in LibertyTools without a user bot process. It needs an ER:LC server key and server-owner authorization. A LibertyJS Poll handler needs the user's bot process to remain running. - Forward destinations can use Signed Proxy (normalized event and LibertyTools signature) or Raw Mirror (original ER:LC request). Verify the relevant signature before trusting a forwarded event. - Exact ER:LC copy is the Raw Mirror format. `filter.includeWebhookProbes` optionally includes/excludes genuine WebhookProbe checks independently of other event filters; omission preserves existing filter behavior. The dashboard exposes this option for Raw Mirror destinations. - Raw Mirror's test action prepares the destination for a real signed ER:LC probe and returns `awaitingErlcProbe: true`; it does not fabricate an unsigned probe. Save the ingest URL again in ER:LC to generate a real check. Queued forwarding does not relay the downstream response to ER:LC. - The step-by-step Poll and receiver examples use Node.js 22+ and `node --env-file=.env .mjs`. Node does not load `.env` automatically. Keep `.env` out of Git. - Downloadable examples: https://libertytools.dev/examples/poll-bot.mjs, https://libertytools.dev/examples/signed-proxy-receiver.mjs, and https://libertytools.dev/examples/send-signed-proxy-test.mjs. - Signed Proxy uses HMAC-SHA256(secret, timestamp + "." + exact raw body), a `v1=` signature, constant-time comparison and a five-minute clock tolerance. The receiver starter logs events; persist accepted work and event IDs before acknowledging if you need durable/deduplicated actions. - Never put ER:LC keys, Poll tokens, or forwarding secrets in browser code, public repositories, logs, or AI chat. Do not assume old WEBHOOK_ID-only Poll examples work for new connections. Consult the current SDK README and dashboard for exact credentials and API behavior.