@alertnew/recipes

Open-source extraction recipes for alert.new - the easiest way to monitor any website for changes.

What is alert.new?

alert.new is a free website monitoring service that lets you:

• Track price drops on Amazon, eBay, and any e-commerce site
• Get notified when products come back in stock
• Monitor GitHub repos for new releases
• Follow social media metrics (YouTube views, Reddit upvotes, etc.)
• Watch any webpage for changes

No coding required. Just paste a URL and set your alert conditions.

Try it free at alert.new

What is a Recipe?

Recipes are the extraction logic that powers alert.new. They define:

• URL matching - Which websites this recipe handles
• Fields - What data to extract (price, stock, views, etc.)
• Default alerts - Pre-configured conditions users can enable
• Extraction logic - How to parse HTML/JSON into structured data

Available Recipes

| Recipe | Website | Fields Extracted | |--------|---------|-----------------| | amazon | Amazon (all regions) | Price, stock, rating, reviews, deals, coupons, BSR | | ebay | eBay | Price, bids, seller rating, shipping, time left | | github | GitHub | Stars, forks, releases, issues, license, topics | | youtube | YouTube | Views, likes, comments, subscribers, duration | | reddit | Reddit | Score, comments, awards, upvote ratio | | hackernews | Hacker News | Points, comments, author, rank | | npm | npm Registry | Version, downloads, dependencies, license | | twitter | X/Twitter | Author, verified status | | producthunt | Product Hunt | Upvotes, comments, rank | | generic | Any website | Title, description, meta tags, JSON-LD |

Installation

npm install @alertnew/recipes

Usage

import { getRecipeForUrl, getRecipeBySlug } from '@alertnew/recipes'

// Get the right recipe for any URL
const recipe = getRecipeForUrl('https://www.amazon.com/dp/B0D1XD1ZV3')
console.log(recipe.meta.name) // "Amazon Product"

// Extract data from HTML
const html = await fetch(url).then(r => r.text())
const data = await recipe.extract(html, url)
console.log(data) // { title: "...", price: 29.99, inStock: true, ... }

// Or get a recipe by slug
const github = getRecipeBySlug('github')

Contributing a Recipe

We welcome contributions! Help us support more websites.

1. Fork & Clone

git clone https://github.com/alert-new/recipes.git
cd recipes
npm install

2. Create Your Recipe

Create a new file in src/recipes/:

import { defineRecipe } from '../types'

export const myRecipe = defineRecipe({
  meta: {
    slug: 'my-site',
    name: 'My Site',
    description: 'Track prices on My Site',
    icon: 'https://example.com/favicon.ico',
    category: 'ecommerce',
    tags: ['shopping', 'deals'],
    maintainers: ['your-github-username'],
    examples: ['https://example.com/product/123'],
  },

  match: /^https?:\/\/(www\.)?example\.com\/product\//i,

  fields: {
    title: { type: 'string', label: 'Title', primary: true },
    price: { type: 'currency', label: 'Price', primary: true },
    inStock: { type: 'boolean', label: 'In Stock' },
  },

  defaultAlerts: [
    {
      id: 'price-drop',
      label: 'Price Drop',
      description: 'Notify when price decreases',
      when: 'price < previous.price',
      icon: '💰',
    },
  ],

  async extract(html, url) {
    const data = {}
    // Your extraction logic here
    return data
  },
})

3. Test Your Recipe

npm test                    # Run unit tests
npm run validate            # Validate all recipes
npm run test:live           # Test against live URLs

4. Submit a PR

We'll review and merge quality contributions!

Helper Functions

Import from @alertnew/recipes:

| Function | Description | |----------|-------------| | extractFirst(html, regex) | Extract first regex match | | extractAll(html, regex) | Extract all matches | | extractMetaTags(html) | Get all meta tags as object | | extractJsonLd(html) | Parse JSON-LD structured data | | parsePrice(str) | Parse "$1,234.56" to number | | parseAbbreviatedNumber(str) | Parse "1.2K", "5M" to number | | decodeHtmlEntities(str) | Decode & etc. |

Field Types

| Type | Description | Condition Support | |------|-------------|-------------------| | string | Text content | =, !=, contains | | number | Numeric value | <, >, <=, >=, =, != | | boolean | True/false | == true, == false | | currency | Money value | Same as number | | url | URL string | =, != | | date | ISO date string | =, != |

Alert Conditions

The when expression supports:

// Comparisons
price < 100
price < previous.price
inStock == true && previous.inStock == false

// Math
price < previous.price * 0.9     // 10% price drop

// Functions
floor(stars / 1000) > floor(previous.stars / 1000)  // Star milestone

API Reference

// Get all recipes
import { recipes, allRecipes } from '@alertnew/recipes'

// Find recipe for URL
import { getRecipeForUrl } from '@alertnew/recipes'
const recipe = getRecipeForUrl(url)

// Get recipe by slug
import { getRecipeBySlug } from '@alertnew/recipes'
const amazon = getRecipeBySlug('amazon')

// Types
import type { Recipe, RecipeField, ExtractedData } from '@alertnew/recipes'

Fair Use & Legal

This repository is for educational and personal use. By using these recipes:

1. Respect robots.txt - Don't scrape disallowed pages
2. Rate limit - Don't overload target websites
3. Public data only - Only extract publicly available information
4. Comply with ToS - Follow each website's Terms of Service

alert.new is designed for personal monitoring at reasonable intervals, not bulk data collection.

Links

• Website: alert.new
• Documentation: alert.new/docs
• Issues: GitHub Issues

License

MIT - see LICENSE

Start monitoring any website for free at alert.new