Package Exports

@alertnew/recipes

Readme

@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:

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

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

License

MIT - see LICENSE

Start monitoring any website for free at alert.new

JSPM