@noise/url-validator — Paperclip URL Validation Plugin

Ensures agent comments contain ONLY social media links.

When the Social Intelligence Scanner (or any agent) posts a comment with URLs, this plugin:

1. ✅ Keeps direct social media post links (Instagram, TikTok, LinkedIn, Facebook, etc.)
2. ❌ Flags & removes blog/article URLs (later.com, sproutsocial.com, digiday.com, etc.)
3. 📝 Posts a correction comment with the cleaned version

Problem This Solves

The agency's AI agents keep including website article links in outputs that should contain ONLY direct social media post links. This plugin enforces the rule at code level — not through instructions.

How It Works

Three enforcement layers (belt + suspenders + parachute):

| Layer | How | When | |-------|-----|------| | Tool | validate-urls — agent calls before posting | Proactive, best UX | | Event | comment.created handler | Automatic, catches everything | | Job | Periodic scan every 10 min | Safety net for missed events |

Allowed Domains

| Platform | Domains | |----------|---------| | Instagram | instagram.com, www.instagram.com | | TikTok | tiktok.com, www.tiktok.com, vm.tiktok.com | | LinkedIn | linkedin.com, www.linkedin.com | | Facebook | facebook.com, www.facebook.com, m.facebook.com, fb.watch, fb.com | | X/Twitter | x.com, twitter.com | | YouTube | youtube.com, youtu.be | | Threads | threads.net |

Everything else is blocked.

Installation

Option A: Install as Paperclip Plugin (Recommended)

1. Publish to npm (one-time setup):

   cd noise-paperclip-plugin
   npm install
   npm run build
   npm publish --access public

2. Install in Paperclip:

   • Go to Settings → Plugins
   • Click "Install Plugin"
   • Enter: @noise/url-validator
   • Click Install

3. Done! The plugin auto-starts and begins monitoring.

Option B: Standalone Scanner (Works Immediately)

If you can't publish to npm right now, use the standalone script:

# One-shot scan (dry run first!)
PAPERCLIP_URL=https://noise-x-paperclip.onrender.com \
PAPERCLIP_API_KEY=<your-key> \
DRY_RUN=true \
node standalone/url-validator-api.mjs --scan-once

# Live scan (posts corrections)
PAPERCLIP_URL=https://noise-x-paperclip.onrender.com \
PAPERCLIP_API_KEY=<your-key> \
node standalone/url-validator-api.mjs --scan-once

# Continuous monitoring (runs every 10 min)
PAPERCLIP_URL=https://noise-x-paperclip.onrender.com \
PAPERCLIP_API_KEY=<your-key> \
node standalone/url-validator-api.mjs

Getting an API Key

1. In Paperclip, find or create a board operator agent
2. Generate an API key via: POST /api/agents/{agentId}/keys
3. Or use Local Trusted Mode if running on the same machine

Agent Tool Usage

Once installed, agents can use these tools:

validate-urls

Call BEFORE posting a comment to check URLs:

Tool: validate-urls
Input: { "text": "Check out https://instagram.com/p/123 and https://later.com/tips" }
Output: ⚠️ URL VALIDATION FAILED — 1 non-social URL(s) detected

clean-comment

Get a cleaned version of text:

Tool: clean-comment
Input: { "text": "See https://later.com/blog/tips for more" }
Output: "See [REMOVED - not a social media link] for more"

What Happens When a Violation is Found

The plugin posts a correction comment like this:

⚠️ URL VALIDATION ALERT [URL Validator Plugin]

The previous comment contained 2 non-social media URL(s) that have been flagged:

• ❌ https://later.com/blog/instagram-tips/
• ❌ https://sproutsocial.com/insights/report/

Only direct social media post links are permitted: Instagram, TikTok, LinkedIn, Facebook, X/Twitter, YouTube, Threads

---

Cleaned version:

[original text with bad URLs replaced]

Testing

# Run all tests (no dependencies needed)
node --test test/url-validator.test.mjs

All 22 tests cover:

• Individual domain allowlisting
• URL extraction from markdown
• Mixed content cleaning
• Real-world agent output scenarios

Project Structure

noise-paperclip-plugin/
├── src/
│   ├── constants.ts      # Domain allowlist, plugin IDs
│   ├── url-validator.ts   # Core validation logic (pure functions)
│   ├── manifest.ts        # Plugin manifest (capabilities, tools, jobs)
│   └── worker.ts          # Plugin worker (event handlers, tools, jobs)
├── standalone/
│   └── url-validator-api.mjs  # Standalone script (no plugin needed)
├── test/
│   └── url-validator.test.mjs # Tests (node:test, zero deps)
├── scripts/
│   └── build.mjs          # esbuild build script
├── package.json
└── README.md

Customizing

Adding Allowed Domains

Edit src/constants.ts → ALLOWED_DOMAINS array, then rebuild.

Changing Scan Frequency

Edit src/manifest.ts → jobs[0].schedule (cron syntax).

Changing Replacement Text

Edit src/constants.ts → REPLACEMENT_TEXT.

Technical Notes

• Plugin uses Paperclip SDK v1 (apiVersion: 1)
• Worker runs out-of-process (Node.js)
• Events: subscribes to comment.created and issue.updated
• Job: runs every 10 minutes as a safety net
• State: tracks flagged comments to avoid duplicates
• No UI components (automation-only plugin)
• Zero external dependencies beyond the Paperclip SDK