📚 API Reference

sanitize(str) → string

Escape a string for safe insertion into innerHTML. Uses DOM-based escaping in browsers, regex-based escaping in Node.js.

gifCaptcha.sanitize('<script>alert(1)</script>');
// → "&lt;script&gt;alert(1)&lt;/script&gt;"

gifCaptcha.sanitize('Hello "world" & friends');
// → 'Hello &quot;world&quot; &amp; friends'

createSanitizer() → { sanitize }

Create a standalone sanitizer instance. Useful when you need isolated sanitizers or want to avoid the global default.

const mySanitizer = gifCaptcha.createSanitizer();
mySanitizer.sanitize('<b>bold</b>');
// → "&lt;b&gt;bold&lt;/b&gt;"

loadGifWithRetry(container, challenge, attempt) → void

Load a GIF image into a DOM container with automatic retry on failure. On final failure, shows a fallback with a link to the source or a title hint. Browser-only.

const container = document.getElementById('captcha-gif');
gifCaptcha.loadGifWithRetry(container, {
  title: "Surprise Ending",
  gifUrl: "https://example.com/twist.gif",
  sourceUrl: "https://example.com/source"
});

textSimilarity(a, b) → number

Calculate word-level Jaccard similarity between two strings. Returns a score between 0 (no overlap) and 1 (identical words). Case-insensitive.

gifCaptcha.textSimilarity("the cat sat on the mat", "the cat sat");
// → 0.833 (5/6 unique words overlap)

gifCaptcha.textSimilarity("hello world", "goodbye moon");
// → 0 (no shared words)

validateAnswer(userAnswer, expectedAnswer, options?) → { passed, score, hasKeywords }

Validate a user's CAPTCHA response against the expected answer using fuzzy text matching and optional keyword checks.

Returns

gifCaptcha.validateAnswer(
  "the cat fell off the table",
  "the cat fell off the table unexpectedly"
);
// → { passed: true, score: 0.857, hasKeywords: true }

gifCaptcha.validateAnswer(
  "I cannot view animated images",
  "the cat fell off the table",
  { requiredKeywords: ["cat", "fell"] }
);
// → { passed: false, score: 0, hasKeywords: false }

createChallenge(opts) → Challenge throws Error

Create a structured CAPTCHA challenge object with validation.

const challenge = gifCaptcha.createChallenge({
  id: 1,
  title: "Plot Twist",
  gifUrl: "https://media.tenor.com/twist.gif",
  humanAnswer: "Both fired trick guns with flags",
  aiAnswer: "I cannot view animated GIFs",
  keywords: ["trick", "guns", "flags"]
});

pickChallenges(pool, count?) → Challenge[]

Pick N random challenges from a pool without replacement, using Fisher-Yates shuffle. Does not modify the original array.

const selected = gifCaptcha.pickChallenges(allChallenges, 5);
// → 5 random challenges from the pool

installRoundRectPolyfill() → void

Install the roundRect polyfill on CanvasRenderingContext2D. No-op if already available or outside a browser. Used by analysis and simulator chart renderers.

gifCaptcha.installRoundRectPolyfill();
// Canvas roundRect() is now available in older browsers

Constants