Agentic Text

npm version Downloads/month License: MIT

agentic-text is an open-source TypeScript SMS wrapper for Twilio, Telnyx, and Plivo, with contact opt-in records and manual STOP controls.

Install

npm install agentic-text

Requires Node.js 18 or later. Includes TypeScript declarations and three runtime dependencies.

Preview your first text

Save this as preview.mjs, then run node preview.mjs:

import { dispatchText, DryRunSmsAdapter, getCostReport } from "agentic-text";
const preview = await dispatchText("Preview only", {
  adapter: new DryRunSmsAdapter(), dryRun: true
});
console.log(preview);
console.log(getCostReport());

Expect a result with dryRun: true and zero recorded dispatches. This example needs no credentials or contact data. It sends no SMS. Direct library calls require callers to apply contact checks and guards explicitly.

Features and coverage

• Store contacts with an opt-in source and timestamp in a local JSON file.
• Record STOP entries; ensureWarm blocks stopped or unlisted numbers.
• Apply UTC quiet hours and optional dispatch caps in the CLI; MCP supports injected guards.
• Add a brand prefix and STOP footer with CLI --brand or the withOptOutFooter helper.
• Classify inbound keywords and validate application-to-person ten-digit long code (A2P 10DLC) campaign fields with library helpers.

Three vendor adapters and one dry-run adapter exist. Export credentials before live calls; the package does not load .env files. CLI vendor selection follows Twilio, Telnyx, then Plivo environment keys; --vendor overrides it. MCP defaults to Twilio.

Runtime surfaces

CLI commands: send, warmbase add|list, stops add|list, a2p, costs, and mcp; flags include --help and --version. Use warmbase add --to <real-opted-in-number> --source <opt-in-source> before sending. send requires --to, --from, and --text or --file. Preview first; add --live for a vendor call. Optional send flags include --vendor, --brand, --warmbase, --cap, --quiet-start, --quiet-end, --dry-run, and --prospect-file. --prospect-file points at a growth-prospect-list CSV with phone, basis, evidence_url, no_solicitation_flag, and do_not_contact columns; the row for --to must exist and pass all four checks before the send. warmbase add accepts --name; stops add accepts --keyword. The default contact file is ~/.agentic-text/warmbase.json; override it with AGENTIC_TEXT_WARMBASE or CLI --warmbase. Record each received STOP with stops add --to <number>. The number leaves the contact list and remains blocked.

Start the Model Context Protocol (MCP) server with npx agentic-text mcp or npx agentic-text-mcp. Its seven tools are send_text, warmbase_add, warmbase_list, record_stop, list_stops, a2p_checklist, and get_cost_report. send_text previews by default; dryRun: false requests a live send after contact and guard checks. send_text accepts an optional prospect object with the growth-prospect-list compliance columns; flagged or unevidenced prospects refuse with a tool error. The self-hosted Worker source exposes GET /health and POST /preview; it never sends SMS or reads the contact file.

Edge runtimes (Cloudflare Workers)

agentic-text/adapters is a fetch-only entry point for hosts with no filesystem and no process.env. Every credential arrives as an argument; nothing is read from the environment. It carries the Twilio, Telnyx, and Plivo send adapters plus the callback helpers.

import { TelnyxSmsAdapter, verifyTelnyxSignature, telnyxEventPrice } from 'agentic-text/adapters';

const sms = new TelnyxSmsAdapter({
  to: '+15551234567', from: '+15557654321',   // E.164 only
  apiKey: env.TELNYX_API_KEY,                 // key passed in, never read from env
  messagingProfileId: env.TELNYX_MESSAGING_PROFILE_ID,
  webhookUrl: 'https://crm.example/hooks/telnyx',
});
const receipt = await sms.dispatch('hi');     // receipt.id is the provider message id

// In the webhook route:
const ok = await verifyTelnyxSignature({
  publicKey: env.TELNYX_PUBLIC_KEY,
  timestamp: req.headers.get('telnyx-timestamp'),
  signature: req.headers.get('telnyx-signature-ed25519'),
  payload: rawBody,
});
const price = telnyxEventPrice(JSON.parse(rawBody));   // cost.amount -> integer cents

Twilio mirrors it: statusCallback on TwilioSmsAdapter, verifyTwilioSignature (HMAC-SHA1 over URL + sorted params), twilioCallbackPrice (Price/PriceUnit params) and adapter.charge(sid) for the final price on the Message resource. verifyTelnyxSignature refuses a telnyx-timestamp older than five minutes (toleranceSeconds overrides it) and returns false on malformed key or signature material. The /adapters entry imports nothing from agentic-core — failures throw the local AdapterError (code: "VENDOR_FAILED") — so the bundle needs no nodejs_compat flag at all. See e2e/worker.ts and e2e/e2e.ts for a bundled proof and a dry-run E2E against local fakes.

Behavior limits

CLI and MCP quiet hours default to 01:00–13:00 UTC. These checks can also block previews. The package records supplied opt-in evidence; it cannot verify consent or guarantee regulatory compliance. Direct adapters bypass contact checks, quiet hours, and footer helpers. Library callers must use ensureWarm and configured guards. STOP recording is manual; there is no inbound webhook receiver. Adding a contact again does not clear its STOP entry. A successful HTTP response produces a receipt, not proof of handset delivery; missing vendor IDs receive generated IDs. Requests default to a ten-second timeout, with no automatic retry, failover, or delivery-status polling. Contact storage uses synchronous JSON writes without file locking. Cost reports are process-local usage, not vendor invoices. a2p prints guidance and key-presence flags; it does not register campaigns. There is no managed SMS service. Version 0.1.x interfaces can change. No public case studies are published in this repository.

Links and license

Package · Twilio · Telnyx · Plivo

MIT license.