ExcitingAds! Cold Fusion

Decoding VINs with an API

2026-06-26T18:00:00+00:00

Today's post took a bit of a pivot. I decided to work on a demo idea I had created way back in March. As I worked on it, I ran into multiple roadblocks, and while that original idea for a demo may still see the light of the day, I figured I'd at least share something that did work.

What's a VIN?

A VIN is a vehicle identification number. It's a standard that dates back to 1954 and identifies a particular car by manufacturer, make, model, year, and a heck of a lot more. A VIN is 17 characters avoiding the letters O, I, U, and Q to avoid confusion with some numbers.

You can break down a VIN into various components if you want - but would still need to know various lookup values, for example a manufacturer referred to as 1FT maps to Ford Truck.

Decoding a VIN via API

As part of the demo that didn't quite make it, I needed to decode a VIN value. I had a commercial service in mind but it had a pretty limited free tier (50 calls). Turns out, the National Highway Traffic Safety Administration actually has a bunch of APIs, multiple of which work with VINs.

The Vehicle API is free, with no limits (outside of not being a jerk), and requires no API keys at all.

The one we want is the Decode VIN Extended (flat format) endpoint. Why "flat format"? The initial API returns information that very much looks like XML translated to JSON, which to be fair, it is, and while the data is all there, it's a bit ugly. The flat format makes it look quite a bit nicer.

To use the API, simply include the VIN in the URL and ensure you add ?format=json: https://vpic.nhtsa.dot.gov/api/vehicles/decodevinvalues/3VV3B7AXXNM077525?format=json

This returns:

{
  "Count": 1,
  "Message": "Results returned successfully. NOTE: Any missing decoded values should be interpreted as NHTSA does not have data on the specific variable. Missing value should NOT be interpreted as an indication that a feature or technology is unavailable for a vehicle.",
  "SearchCriteria": "VIN(s): 3VV3B7AXXNM077525",
  "Results": [
    {
      "ABS": "Standard",
      "ActiveSafetySysNote": "",
      "AdaptiveCruiseControl": "Standard",
      "AdaptiveDrivingBeam": "Standard",
      "AdaptiveHeadlights": "",
      "AdditionalErrorText": "",
      "AirBagLocCurtain": "1st Row (Driver and Passenger)",
      "AirBagLocFront": "1st Row (Driver and Passenger)",
      "AirBagLocKnee": "",
      "AirBagLocSeatCushion": "",
      "AirBagLocSide": "1st Row (Driver and Passenger)",
      "AutoReverseSystem": "Standard",
      "AutomaticPedestrianAlertingSound": "",
      "AxleConfiguration": "",
      "Axles": "",
      "BasePrice": "",
      "BatteryA": "",
      "BatteryA_to": "",
      "BatteryCells": "",
      "BatteryInfo": "",
      "BatteryKWh": "",
      "BatteryKWh_to": "",
      "BatteryModules": "",
      "BatteryPacks": "",
      "BatteryType": "",
      "BatteryV": "",
      "BatteryV_to": "",
      "BedLengthIN": "",
      "BedType": "",
      "BlindSpotIntervention": "",
      "BlindSpotMon": "Standard",
      "BodyCabType": "",
      "BodyClass": "Sport Utility Vehicle [SUV]/Multipurpose Vehicle [MPV]",
      "BrakeSystemDesc": "",
      "BrakeSystemType": "",
      "BusFloorConfigType": "Not Applicable",
      "BusLength": "",
      "BusType": "Not Applicable",
      "CAN_AACN": "",
      "CIB": "Standard",
      "CashForClunkers": "",
      "ChargerLevel": "",
      "ChargerPowerKW": "",
      "CombinedBrakingSystem": "",
      "CoolingType": "",
      "CurbWeightLB": "",
      "CustomMotorcycleType": "Not Applicable",
      "DaytimeRunningLight": "Standard",
      "DestinationMarket": "",
      "DisplacementCC": "2000.0",
      "DisplacementCI": "122.04748818946",
      "DisplacementL": "2.0",
      "Doors": "",
      "DriveType": "",
      "DriverAssist": "",
      "DynamicBrakeSupport": "Standard",
      "EDR": "",
      "ESC": "Standard",
      "EVDriveUnit": "",
      "ElectrificationLevel": "",
      "EngineConfiguration": "",
      "EngineCycles": "",
      "EngineCylinders": "4",
      "EngineHP": "184",
      "EngineHP_to": "",
      "EngineKW": "",
      "EngineManufacturer": "Volkswagen",
      "EngineModel": "",
      "EntertainmentSystem": "",
      "ErrorCode": "0",
      "ErrorText": "0 - VIN decoded clean. Check Digit (9th position) is correct",
      "ForwardCollisionWarning": "Standard",
      "FuelInjectionType": "",
      "FuelTankMaterial": "",
      "FuelTankType": "",
      "FuelTypePrimary": "Gasoline",
      "FuelTypeSecondary": "",
      "GCWR": "",
      "GCWR_to": "",
      "GVWR": "Class 1D: 5,001 - 6,000 lb (2,268 - 2,722 kg)",
      "GVWR_to": "",
      "KeylessIgnition": "Standard",
      "LaneCenteringAssistance": "",
      "LaneDepartureWarning": "Standard",
      "LaneKeepSystem": "Standard",
      "LowerBeamHeadlampLightSource": "LED",
      "Make": "VOLKSWAGEN",
      "MakeID": "482",
      "Manufacturer": "VOLKSWAGEN DE MEXICO SA DE CV",
      "ManufacturerId": "16478",
      "Model": "Tiguan",
      "ModelID": "8151",
      "ModelYear": "2022",
      "MotorcycleChassisType": "Not Applicable",
      "MotorcycleSuspensionType": "Not Applicable",
      "NCSABodyType": "",
      "NCSAMake": "",
      "NCSAMapExcApprovedBy": "",
      "NCSAMapExcApprovedOn": "",
      "NCSAMappingException": "",
      "NCSAModel": "",
      "NCSANote": "",
      "NonLandUse": "",
      "Note": "",
      "OtherBusInfo": "",
      "OtherEngineInfo": "Test Group: NVGAJ02.0V3A / Emission Std.: Tier 3 BIN 30 LEV3 SULEV30",
      "OtherMotorcycleInfo": "",
      "OtherRestraintSystemInfo": "Seat Belt: Active-Dr/Pass / Advanced Front Airbags",
      "OtherTrailerInfo": "",
      "ParkAssist": "",
      "PedestrianAutomaticEmergencyBraking": "",
      "PlantCity": "PUEBLA",
      "PlantCompanyName": "",
      "PlantCountry": "MEXICO",
      "PlantState": "",
      "PossibleValues": "",
      "Pretensioner": "",
      "RearAutomaticEmergencyBraking": "Standard",
      "RearCrossTrafficAlert": "Standard",
      "RearVisibilitySystem": "Standard",
      "SAEAutomationLevel": "",
      "SAEAutomationLevel_to": "",
      "SeatBeltsAll": "Manual",
      "SeatRows": "2",
      "Seats": "5",
      "SemiautomaticHeadlampBeamSwitching": "Standard",
      "Series": "",
      "Series2": "",
      "SteeringLocation": "",
      "SuggestedVIN": "",
      "TPMS": "Indirect",
      "TopSpeedMPH": "",
      "TrackWidth": "",
      "TractionControl": "Standard",
      "TrailerBodyType": "Not Applicable",
      "TrailerLength": "",
      "TrailerType": "Not Applicable",
      "TransmissionSpeeds": "8",
      "TransmissionStyle": "Automatic",
      "Trim": "SE",
      "Trim2": "",
      "Turbo": "",
      "VIN": "3VV3B7AXXNM077525",
      "ValveTrainDesign": "",
      "VehicleDescriptor": "3VV3B7AX*NM",
      "VehicleType": "MULTIPURPOSE PASSENGER VEHICLE (MPV)",
      "WheelBaseLong": "",
      "WheelBaseShort": "",
      "WheelBaseType": "",
      "WheelSizeFront": "",
      "WheelSizeRear": "",
      "WheelieMitigation": "",
      "Wheels": "",
      "Windows": ""
    }
  ]
}

This is, indeed, my car and the data is spot on. If you pass an invalid VIN, the values for ErrorCode and ErrorText will include pertinent information. As an example, this URL with a messed up VIN gives:

{ 
// All the usual keys
"ErrorCode": "1,7,400",
"ErrorText": "1 - Check Digit (9th position) does not calculate properly; 7 - Manufacturer is not registered with NHTSA for sale or importation in the U.S. for use on U.S roads; Please contact the manufacturer directly for more information; 400 - Invalid Characters Present",
 // more
}

Note that as I said in the code block, you still get all the other keys as well, so you need to check for ErrorCode being "0" (note that it's a string, not a number) before you can use the data.

But - the API tries its best to decode as much as possible. So for example, if I remove one value from my VIN, I get an error ("6 - Incomplete VIN"), but it still returns the right make and model for my car.

Depending on your particular need, you may not want to treat errors as a boolean state and see what you can get away with.

Putting a Bow on It

Alright, so while this worked, I thought I'd make a quick trip to Val Town to build a slightly nicer API wrapper for this. My code would do two things:

Return an object with two keys, vehicle and error.
vehicle is the vehicle information result, just the first one, but with keys lowercased because there's no need to write more APIs the Microsoft way.
error will check if ErrorCode isn't "0", and if so, will be populated with ErrorText.

In Val Town, I created a new val with a HTTP trigger. I look for the VIN in the URL, and if it's there, pass it to the NHTSA's API and shape the API as I described above. That's literally it.

export default async function (req: Request): Promise<Response> {
  const url = new URL(req.url);
  const vin = url.searchParams.get("vin");

  if (!vin) {
    return new Response(
      JSON.stringify({ error: "Missing 'vin' query parameter" }),
      {
        status: 400,
        headers: { "Content-Type": "application/json" },
      },
    );
  }

  const vinreq = await fetch(
    `https://vpic.nhtsa.dot.gov/api/vehicles/decodevinvalues/${vin}?format=json`,
  );
  const data = await vinreq.json();

  const result = {
    vehicle: lowerCaseKeys(data.Results[0]),
    error: null,
  };

  if (data.Results[0].ErrorCode !== "0") {
    result.error = data.Results[0].ErrorText;
  }

  return new Response(JSON.stringify(result), {
    headers: { "Content-Type": "application/json" },
  });
}

function lowerCaseKeys(obj) {
  const result = {};
  for (const key of Object.keys(obj)) {
    result[key.toLowerCase()] = obj[key];
  }
  return result;
}

This API is up and running at https://raymondcamden--a5e2f648718311f1ace11607ee4eb77e.web.val.run, and you can see the full Val here, https://www.val.town/x/raymondcamden/vin-api.

Quick Demo

I went to another code hosting service, Code Pen, to create a quick and simple demo. If you open your browser to https://new-thunder-treefrog.codepen.app/, you can enter a VIN, hit the button, and see the result dumped on screen. The entire Val Town integration was just a fetch call:

let req = await fetch(`https://raymondcamden--a5e2f648718311f1ace11607ee4eb77e.web.val.run/?vin=${vin}`);
let result = await req.json();

Here's the CodePen itself if you want to fork, or run the demo here.

See the Pen VIN API Tester by Raymond Camden (@cfjedimaster) on CodePen.

Photo by Elisa Schmidt on Unsplash

Parsing Arbitrary Dates in Strings with Chrono and a Web Component

2026-06-24T18:00:00+00:00

Yesterday I had an idea for a possible experiment using Chrome's built-in AI support - looking for "date" references in strings. So for example: "I will have my new job in 12 days". Could the AI model recognize "12 days" as a date and determine what the actual date is, assuming a reference date of now? I was about to start working on a simple POC when I thought... wait... is there already a JavaScript library for this?

Of course there is.

The aptly named Chrono library does just that. It can parse a string with one assumed date and return the date, so for example:

import * as chrono from 'chrono-node';

chrono.parseDate('An appointment on Sep 12-13');

This returns: Sat Sep 12 2026 12:00:00 GMT-0500 (Central Daylight Time). It can also take a string and give you a parsed set of results, so for example:

chrono.parse('An appointment on Sep 12-13');
/* [{ 
    index: 18,
    text: 'Sep 12-13',
    start: ...
}] */

The parse method will return one result per matched item, with the result including the original string, lots of info on how it parsed it, and the ability to get the proper date object from it. It can also handle durations and a reference date too, so if your input was, "I will eat sushi tomorrow" and the reference was January 2nd, 2026, it would recognize that tomorrow is January 3rd, 2026.

So, how about a demo? I created a quick CodePen that has a textarea for arbitrary input. You can type anything, and when it finds stuff, it dumps it out below and then follows up that dump with parsed dates. I'll skip over the HTML (you can see it in the embedded CodePen), but here's the JavaScript:

import * as chrono from 'chrono-node';

const $input = document.querySelector('#input');
const $output = document.querySelector('#output');

$input.addEventListener('input', () => {
	const input = $input.value.trim();
	$output.innerText = '';
	if(input === '') return;
	/*
	temp test to set a reference:
	let yesterday = new Date();
	yesterday.setDate(yesterday.getDate() - 1);
	let parsed = chrono.parse(input, yesterday);
	*/
	let parsed = chrono.parse(input);

	if(parsed.length) {
		$output.innerText = JSON.stringify(parsed, null, '\t') + '\n';
	
		for(const p of parsed) {
			console.log(p.start.date());
			$output.innerText += `Parsed date: ${p.start.date()} `;
			if(p.end) $output.innerText += ` - ${p.end.date()}`;
			$output.innerText += '\n';
		}
	}
});

Basically import the library, note changes in the textarea, and parse. If results are found I do the simple dump as I mentioned. One small oddity with the library is that the initial result does not actually include the date. You have to run .date() on the start and (optional) end values to get that. Hence that for loop. You can also see, commented out, how easy it is to use a reference date.

Go ahead and test it below.

I will say I found the 'duration' support didn't work terribly well. By that I mean it would find the date reference, but not always the 'end'. The sample input, "I have an appointment tomorrow from 10 to 11 AM", worked fine, but in my tests it was hit or miss. Again though, it got the start every time so that's something.

See the Pen chrono test by Raymond Camden (@cfjedimaster) on CodePen.

Turning it into a Web Component

At this point, I thought it might be cool to build a web component that would:

Use Chrono to find the date strings
Wrap each matched item with a <time> element, setting datetime and title to the parsed date
Use a bit of CSS to highlight the text
Allow for an attribute that lets you specify the date. In my mind, the main use for this is UGC (user generated content), things like comments for example. Comments are made at a point in time which means it should be easy to pass that to the component.

I named my component time-parse because I'm incredibly creative. Here's an example of it in play, both with and without a reference date:

<div>
    <time-parse>
    I'll be eating tomorrow. Or maybe in 3 hours? I'm not sure.
    </time-parse>
</div>

<div>
    <time-parse date="2026-06-04">
        This is an example in the past. I set the date to June 4th. 
    I'll be eating tomorrow. Or maybe in 3 hours? I'm not sure.
    </time-parse>
</div>

Here's the code I used. I'll talk a bit about my design decisions after:

import * as chrono from 'chrono-node';

class TimeParseComponent extends HTMLElement {

	constructor() {
		super();
	}
	
	connectedCallback() {

		// doing an inline style so i dont have to worry about specifying it just for the WC. This feels wrong a bit...
		const STYLE = 'text-decoration: underline;text-decoration-color: #ccc;';

		let dateRef = null;
		
		// look for date attribute
		if(this.hasAttribute("date")) {
			console.log('Date found, using as ref');
			dateRef = this.#parseLocalDate(this.getAttribute("date"));
			console.log('dateRef is ', dateRef);
		}
		
		let input = this.innerHTML;
		const parsed = chrono.parse(input, dateRef);
		if(!parsed || !parsed.length) return;
		console.log(`Found ${parsed.length} items to update`);
		/*
		For each, find the initial string, and wrap it with:
		<time datetime=PARSEDTIME title=PARSEDTIME>orig</time>

		Go backwards as we are changing the string
		*/
		for(let x=parsed.length-1; x >= 0; x--) {
			console.log(parsed[x]);
			// first get the date, currently not supporting end
			let date = this.#formatDateTime(parsed[x].start.date());
			let orig = input.substring(parsed[x].index, parsed[x].index + parsed[x].text.length);
			// now make the new string
			let newStr = `
<time datetime="${date}" title="${date}" style="${STYLE}">${orig}</time>
			`.trim();
			//console.log(newStr);

			input = input.slice(0, parsed[x].index) + newStr + input.slice(parsed[x].index + parsed[x].text.length);
		}

		// All done - 
		console.log('Final Result', input);
		this.innerHTML = input;
	}

	#formatDateTime(x) {
	  const pad = (n) => String(n).padStart(2, '0');
	
	  return [
	    x.getFullYear(),
	    pad(x.getMonth() + 1),
	    pad(x.getDate()),
	  ].join('-') + ' ' + [
	    pad(x.getHours()),
	    pad(x.getMinutes()),
	    pad(x.getSeconds()),
	  ].join(':');
	}

	#parseLocalDate(isoDate) {
	  const [y, m, d] = isoDate.split('-').map(Number);
	  return new Date(y, m - 1, d); // local midnight on that date
	}
}

if(!customElements.get('time-parse')) customElements.define('time-parse', TimeParseComponent);

Alright, so ignoring the basic web component setup, you can see the basic flow is:

Look to see if a date attribute was used, if so, that's our reference date.
Get the text inside the component and parse it.
For each found result, looping backwards, replace the match with new HTML that uses the time tag.
Finally, update the inner HTML inside the component.

Up top you'll notice a STYLE variable. I went with an inline style for... I don't know. I just didn't want to think about the shadow DOM and so forth. I figure with something so small it's ok. Feel free to fork the pen. ;)

You can try it out below. Also, once again, I love web components.

See the Pen time-parse demo by Raymond Camden (@cfjedimaster) on CodePen.

Use AI to not use AI (as much)

2026-06-22T18:00:00+00:00

This squarely falls into the "everyone probably knows this but it didn't click with me right away" category so please feel free to laugh at my ignorance, but it's something I realized over the past few months, and as I just used this technique this morning, I figured I'd share it on the blog. The idea is simple - it's trivial to ask a Gen AI tool to do something for you - and depending on the ask, may work great. But what I realized a few months back, especially in regards to having AI parse data, is that you can also use the opportunity to generate a tool (like a Python or Node script) so you don't need to return to the AI tool again. This becomes especially useful if you want to slightly tweak the output over time or gradually add more features.

For my example today, it was a GitHub alert. Last month I got a few emails about Actions storage usage and it repeated this month:

I know of GitHub Actions, but I don't really use them much myself. That being said, GitHub's billing and usage reports were good for an aggregate high level look at my account, but were surprisingly unhelpful in terms of telling me where my usage was coming from. Apparently I was supposed to go through my 300+ repositories and find this out by checking the settings for each? That's crazy. It's also completely possible I missed a way to get this value easier, but honestly, I wasn't sure what to do.

I finally found a usage report generator in my settings, I used that, and quickly got a CSV report. I took a quick look at it, nothing stood out, so I went to my AI tool and simply asked it to parse it for me.

And it did - swimmingly - giving me a culprit to point to - or in my case - simply delete. It was a repo I had set up to test something that was apparently storing some artifacts I didn't need. Problem solved.

But... I wasn't convinced this wasn't going to happen again, so I used the technique that first occurred to me a few months back, and is pretty obvious, but I simply asked my tool to generate a Python script for me that would create a report.

For this I used Cursor, a tool I've been using a lot lately, and in Plan mode, simply asked:

"pay attention to the csv. it is a GitHub usage report. I need a general Python script that can be run at the command line that parses this CSV and reports on usage. the idea is to help me figure out what repo is causing the most usage"

It chewed on the CSV a bit, and then asked what it should prioritize in terms of the report. Now, my email warning was about storage, but Cursor suggested total cost, so I went along. After it built the script, I liked the output, but the 'problem' repo (that I had already corrected) wasn't necessarily given enough attention.

I then went back to Cursor with:

"this works, but i noticed that testing-boxlang-desktop, which used a lot of storage, doesn't get call out quite as much. can we maybe add another report after the gross amount one that shows top repos by stoage?"

Thank god AI doesn't complain about typos so much as I didn't even notice that till just now. This iteration added a second report and really made it a great v1 for the script. Speaking of...

Just show me the code already...

Ok, so if you are also looking at a GitHub usage report and not sure what repo to blame, generate your summary, save the file, and use this script:

#!/usr/bin/env python3
"""Parse GitHub summarized usage CSV exports and report repo-level usage."""

from __future__ import annotations

import argparse
import csv
import json
import sys
from dataclasses import dataclass, field
from pathlib import Path

REQUIRED_COLUMNS = {
    "date",
    "product",
    "sku",
    "quantity",
    "unit_type",
    "gross_amount",
    "net_amount",
    "discount_amount",
    "repository",
}


def parse_float(value: str) -> float:
    if not value or not value.strip():
        return 0.0
    return float(value)


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Parse a GitHub summarized usage CSV and rank repositories by cost."
    )
    parser.add_argument("csv_file", type=Path, help="Path to summarized usage CSV")
    parser.add_argument(
        "--top",
        type=int,
        default=10,
        metavar="N",
        help="Number of repositories to show in ranking (default: 10)",
    )
    parser.add_argument(
        "--product",
        help="Filter rows by product (e.g. actions, git_lfs)",
    )
    parser.add_argument("--sku", help="Filter rows by SKU")
    parser.add_argument(
        "--from",
        dest="date_from",
        metavar="YYYY-MM-DD",
        help="Include rows on or after this date",
    )
    parser.add_argument(
        "--to",
        dest="date_to",
        metavar="YYYY-MM-DD",
        help="Include rows on or before this date",
    )
    parser.add_argument(
        "--json",
        action="store_true",
        help="Emit structured JSON instead of formatted text",
    )
    return parser.parse_args()


def load_rows(path: Path) -> list[dict[str, str]]:
    if not path.is_file():
        print(f"Error: file not found: {path}", file=sys.stderr)
        sys.exit(1)

    with path.open(newline="", encoding="utf-8-sig") as handle:
        reader = csv.DictReader(handle)
        if reader.fieldnames is None:
            print(f"Error: {path} is empty or has no header row", file=sys.stderr)
            sys.exit(1)

        missing = REQUIRED_COLUMNS - set(reader.fieldnames)
        if missing:
            missing_list = ", ".join(sorted(missing))
            print(
                f"Error: {path} is missing required columns: {missing_list}",
                file=sys.stderr,
            )
            sys.exit(1)

        return list(reader)


def filter_rows(
    rows: list[dict[str, str]],
    *,
    product: str | None,
    sku: str | None,
    date_from: str | None,
    date_to: str | None,
) -> list[dict[str, str]]:
    filtered: list[dict[str, str]] = []
    for row in rows:
        if product and row["product"] != product:
            continue
        if sku and row["sku"] != sku:
            continue
        if date_from and row["date"] < date_from:
            continue
        if date_to and row["date"] > date_to:
            continue
        filtered.append(row)
    return filtered


@dataclass
class SkuBreakdown:
    sku: str
    unit_type: str
    quantity: float = 0.0
    gross_amount: float = 0.0


@dataclass
class RepoUsage:
    repository: str
    gross_amount: float = 0.0
    net_amount: float = 0.0
    discount_amount: float = 0.0
    row_count: int = 0
    skus: dict[tuple[str, str], SkuBreakdown] = field(default_factory=dict)

    def add_row(self, row: dict[str, str]) -> None:
        gross = parse_float(row["gross_amount"])
        net = parse_float(row["net_amount"])
        discount = parse_float(row["discount_amount"])
        quantity = parse_float(row["quantity"])
        sku = row["sku"]
        unit_type = row["unit_type"]

        self.gross_amount += gross
        self.net_amount += net
        self.discount_amount += discount
        self.row_count += 1

        key = (sku, unit_type)
        if key not in self.skus:
            self.skus[key] = SkuBreakdown(sku=sku, unit_type=unit_type)
        breakdown = self.skus[key]
        breakdown.quantity += quantity
        breakdown.gross_amount += gross


def aggregate_by_repo(rows: list[dict[str, str]]) -> list[RepoUsage]:
    repos: dict[str, RepoUsage] = {}
    for row in rows:
        repository = row["repository"].strip() or "(unknown)"
        if repository not in repos:
            repos[repository] = RepoUsage(repository=repository)
        repos[repository].add_row(row)

    return sorted(repos.values(), key=lambda repo: repo.gross_amount, reverse=True)


def is_storage_row(row: dict[str, str]) -> bool:
    return "storage" in row["sku"].lower()


@dataclass
class RepoStorage:
    repository: str
    quantity: float = 0.0
    gross_amount: float = 0.0
    row_count: int = 0
    skus: dict[str, SkuBreakdown] = field(default_factory=dict)

    def add_row(self, row: dict[str, str]) -> None:
        gross = parse_float(row["gross_amount"])
        quantity = parse_float(row["quantity"])
        sku = row["sku"]
        unit_type = row["unit_type"]

        self.gross_amount += gross
        self.quantity += quantity
        self.row_count += 1

        if sku not in self.skus:
            self.skus[sku] = SkuBreakdown(sku=sku, unit_type=unit_type)
        breakdown = self.skus[sku]
        breakdown.quantity += quantity
        breakdown.gross_amount += gross


def aggregate_storage_by_repo(rows: list[dict[str, str]]) -> list[RepoStorage]:
    repos: dict[str, RepoStorage] = {}
    for row in rows:
        if not is_storage_row(row):
            continue
        repository = row["repository"].strip() or "(unknown)"
        if repository not in repos:
            repos[repository] = RepoStorage(repository=repository)
        repos[repository].add_row(row)

    return sorted(repos.values(), key=lambda repo: repo.quantity, reverse=True)


def storage_repo_payload(repo: RepoStorage, total_storage: float) -> dict:
    return {
        "repository": repo.repository,
        "quantity_gigabyte_hours": repo.quantity,
        "gross_amount": repo.gross_amount,
        "percent_of_total_storage": (
            (repo.quantity / total_storage * 100) if total_storage else 0.0
        ),
        "row_count": repo.row_count,
        "skus": [
            {
                "sku": item.sku,
                "unit_type": item.unit_type,
                "quantity": item.quantity,
                "gross_amount": item.gross_amount,
            }
            for item in sorted(repo.skus.values(), key=lambda sku_item: sku_item.quantity, reverse=True)
        ],
    }


def format_money(amount: float) -> str:
    return f"${amount:.4f}"


def format_percent(part: float, whole: float) -> str:
    if whole == 0:
        return "0.0%"
    return f"{(part / whole) * 100:.1f}%"


def print_storage_table(storage_repos: list[RepoStorage], top: int) -> None:
    print("Top repositories by storage")
    print("-" * 28)

    if not storage_repos:
        print("No storage usage found.")
        print()
        return

    total_storage = sum(repo.quantity for repo in storage_repos)
    print(
        f"{'#':>3}  {'Repository':<26} {'GB-hours':>10} {'%':>7} {'Gross':>10} {'Rows':>5}"
    )
    for index, repo in enumerate(storage_repos[:top], start=1):
        print(
            f"{index:>3}  {repo.repository:<26} "
            f"{repo.quantity:>10.2f} "
            f"{format_percent(repo.quantity, total_storage):>7} "
            f"{format_money(repo.gross_amount):>10} "
            f"{repo.row_count:>5}"
        )
    print()


def print_text_report(
    path: Path,
    rows: list[dict[str, str]],
    repos: list[RepoUsage],
    storage_repos: list[RepoStorage],
    top: int,
) -> None:
    total_gross = sum(repo.gross_amount for repo in repos)
    total_net = sum(repo.net_amount for repo in repos)
    dates = [row["date"] for row in rows]
    date_range = f"{min(dates)} to {max(dates)}" if dates else "n/a"

    print("GitHub Usage Report")
    print("=" * 19)
    print(f"File: {path.name}")
    print(f"Period: {date_range} ({len(rows)} rows)")
    print(f"Total gross: {format_money(total_gross)}   Total net: {format_money(total_net)}")
    print()

    if not repos:
        print("No matching usage rows found.")
        return

    print("Top repositories by gross amount")
    print("-" * 32)
    print(f"{'#':>3}  {'Repository':<26} {'Gross':>10} {'%':>7} {'Net':>10} {'Rows':>5}")
    for index, repo in enumerate(repos[:top], start=1):
        print(
            f"{index:>3}  {repo.repository:<26} "
            f"{format_money(repo.gross_amount):>10} "
            f"{format_percent(repo.gross_amount, total_gross):>7} "
            f"{format_money(repo.net_amount):>10} "
            f"{repo.row_count:>5}"
        )

    print()
    print_storage_table(storage_repos, top)
    print("Details for top repos")
    print("-" * 19)
    for repo in repos[:top]:
        print(f"{repo.repository} ({format_money(repo.gross_amount)} gross)")
        sku_items = sorted(repo.skus.values(), key=lambda item: item.gross_amount, reverse=True)
        for item in sku_items:
            print(
                f"  {item.sku:<22} {item.quantity:>10.2f} {item.unit_type:<16} "
                f"{format_money(item.gross_amount):>10}"
            )
        print()


def print_json_report(
    path: Path,
    rows: list[dict[str, str]],
    repos: list[RepoUsage],
    storage_repos: list[RepoStorage],
    top: int,
) -> None:
    total_gross = sum(repo.gross_amount for repo in repos)
    total_net = sum(repo.net_amount for repo in repos)
    total_storage = sum(repo.quantity for repo in storage_repos)
    dates = [row["date"] for row in rows]

    payload = {
        "file": str(path),
        "row_count": len(rows),
        "date_from": min(dates) if dates else None,
        "date_to": max(dates) if dates else None,
        "total_gross_amount": total_gross,
        "total_net_amount": total_net,
        "total_storage_gigabyte_hours": total_storage,
        "repositories": [
            {
                "rank": index,
                "repository": repo.repository,
                "gross_amount": repo.gross_amount,
                "net_amount": repo.net_amount,
                "discount_amount": repo.discount_amount,
                "row_count": repo.row_count,
                "percent_of_total_gross": (
                    (repo.gross_amount / total_gross * 100) if total_gross else 0.0
                ),
                "skus": [
                    {
                        "sku": item.sku,
                        "unit_type": item.unit_type,
                        "quantity": item.quantity,
                        "gross_amount": item.gross_amount,
                    }
                    for item in sorted(
                        repo.skus.values(),
                        key=lambda sku_item: sku_item.gross_amount,
                        reverse=True,
                    )
                ],
            }
            for index, repo in enumerate(repos[:top], start=1)
        ],
        "storage_repositories": [
            {"rank": index, **storage_repo_payload(repo, total_storage)}
            for index, repo in enumerate(storage_repos[:top], start=1)
        ],
    }
    print(json.dumps(payload, indent=2))


def main() -> None:
    args = parse_args()
    rows = load_rows(args.csv_file)
    filtered = filter_rows(
        rows,
        product=args.product,
        sku=args.sku,
        date_from=args.date_from,
        date_to=args.date_to,
    )
    repos = aggregate_by_repo(filtered)
    storage_repos = aggregate_storage_by_repo(filtered)

    if args.json:
        print_json_report(args.csv_file, filtered, repos, storage_repos, args.top)
    else:
        print_text_report(args.csv_file, filtered, repos, storage_repos, args.top)


if __name__ == "__main__":
    main()

You can also find this here: https://github.com/cfjedimaster/pythondemos/tree/main/ghusageparser. Note that this uses no external dependencies outside of standard library modules. Usage is simple:

python -h

Which gives:

Honestly, none of those arguments were ideas I had but they all make sense. And here's how the report looks:

The 'culprit' was testing-boxlang-desktop which as I said, was just for testing, so easy to delete. Honestly, tweetback surprised me. This is a repo I created as an export from Twitter and apparently it's got a lot of media. I didn't delete it - but may do so in the future.

Anyway, let me know what you think and if this could be helpful to you!

Photo by Simon Kadula on Unsplash

Links For You (6/21/26)

2026-06-21T18:00:00+00:00

Greetings and salutations, readers. It's been a few weeks since I shared one of these, mostly due to the job search being somewhat exhausting, but I've got a backup of links so it's time to get back in the habit. And of course, it's Father's Day and I want to wish all the dads out there (myself included) a very happy father's day. This weekend I got to officiate my first wedding (for my brother-in-law and his fiance) so my plan today is to do... nothing. Enjoy your links!

Mastodon and Translation with Chrome AI

First up is a presentation by Thomas Steiner demonstrating Chrome built-in AI APIs doing language detection and translation for Mastodon. I'm a pretty big fan of those APIs (my last presentation was on them!) so I enjoyed this quite a bit. Thomas has been a big help with my demos and posts on these APIs and is a scary smart dev.

Datatype - Text into Charts

Next is Datatype, a font that creates charts. Seriously. For example:

Sales {l:20,45,60,55,80,95} are up this quarter.

And this was driven by CSS and text:

<style>
@font-face {
  font-family: 'Datatype';
  src: url('https://static.raymondcamden.com/fonts/Datatype-Regular.woff2') format('woff2');
  font-weight: 100 900;      /* Variable weight axis */
  font-stretch: 0% 100%;     /* Variable width axis */
  font-display: swap;
}

.chart {
  font-family: 'Datatype', monospace;
}
</style>

<span class="chart">{l:20,45,60,55,80,95}</span>

It supports bar charts, sparklines, and pie charts. As it's just text, in theory it would be easy to animate and make it 'live' with just a bit of JavaScript.

You Don't Know HTML Lists

Finally there's a spectacular deep dive into HTML lists by Frank Taylor, You don't know HTML lists. You know this is going to be a great article with a sentence like this in the intro:

"We're skipping over the MDN and W3Schools introductory pages and instead we're going into the kind of stuff you discover after accidentally taking your cousin's Ritalin right before you open up the W3C specs."

I knew maybe... half of this? Maybe a bit more? Either way, it's a damn good investigation into a part of HTML you may not know even got that complex.

Just For Fun

Looking for your next read? Are you mostly through your current book and getting a bit of anxiety over whether or not you'll have your next read as soon as you finish? Good news, you're in luck. I've spoken about Scott Stroz in the past (and linked to some of his cool blogs too), he's one of my oldest, and best friends. He's a father as well to two incredible kids, one of which just released his first novel, "The Dreaded."

Tyler's shared some of his works for me in the past so as soon as this one became available, I went ahead and purchased a copy for myself. Grab your copy today - available on Kindle, paper and hardback.

Building a Form Handling Service in Val Town

2026-06-19T18:00:00+00:00

Many years ago, I made the switch from building primarily app-server backed sites (using Node, ColdFusion, PHP, etc) to fully static sites using tools like Jekyll, Hugo, and Eleventy. For the most part, it was a great shift in how I build, but there were a few things I had to figure out in that new world - one of them was simple form handling. While I could have used serverless just fine, it felt like overkill. Luckily, there were a few services out there that catered to this need. You would simply use a unique action for your form and that service would handle collecting the form data, emailing it to you, and redirecting the user back to the site.

A great example of this, and one I used in the past, is Formspree. You can see an example right on their home page:

<!-- random form on your site -->
<form action="https://formspree.io/f/{form_id}" method="post">
  <label for="email">Your Email</label>
  <input name="Email" id="email" type="email">
  <button type="submit">Submit</button>
</form>

Emailing isn't the only option for processing the result of course. Formspree's home page lists a bunch of integrations you can use, like Airtable and Google Sheets. Another feature of these services is that various form fields will trigger different behaviors. For example, I can use a hidden form field to set where the form should redirect to after submission. Or, if there is a field named email, when the form data is sent to the site owner, set the reply value to that value.

So with that in mind, a few days ago, the Val Town folks blogged about various examples in the community (I had a few included too!). In that blog, they shared this post:

I run my forms now via a free val.town instance, very easy to setup with ai and no lock in
— meta (@metaend.eth.xyz) June 14, 2026 at 2:27 AM

That clicked with me - of course Val Town would be a great solution for handling form posts - and I wondered - could we build a generic service such that any form could use it?

I came up with the following requirements:

First and foremost - the implementation should respond to regular form posts. In other words, I didn't want to build an API that would require JavaScript code in the form. Instead I wanted to follow the lead of services like Formspree and let you simply point your 'vanilla' form to a specific URL.
The form should allow me to specify who gets the result. That's a huge security issue of course, so my service will have a white list of allowed email addresses.
The form should allow me to specify where to redirect after submission. Like the above, this could be a security issue, so my service will have a white list of URLs that allow for partial matching, so you can allow foo.com for example and any redirect under that would work.

So far so good? Alright, let's look at the implementation.

Show me the code!

I'll link to the Val itself when done, but here's the entirety of the code, tied to a HTTP trigger so it can actually be used in forms:

import { email } from "https://esm.town/v/std/email";

/*
We are only allowed to send to one of these.
*/
const SAFE_EMAILS_TO = [
  "raymondcamden@gmail.com",
  "rcamden@gmail.com",
];

/*
A URL that is matched against redirects - the redirect must match the domain, well anything _after_ the input
*/
const SAFE_REDIRECT_TO = [
  "https://boring-morning-yak.codepen.app",
];

/*
The 'special keys' don't need to be in the form email.
*/
const SPECIAL_KEYS = ["_send", "_redirect", "_formname"];

/*
Every form must have a _send and _redirect field. Later we may add more validations.
Like validating _redirect. Duh.
*/
function verifyForm(f) {
  console.log("verifyForm", f.get("_send"), f.get("_redirect"));

  if (!f.get("_send") || f.get("_send").length === 0) return false;
  if (!f.get("_redirect") || f.get("_redirect").length === 0) return false;

  // ensure the email is ok
  if(SAFE_EMAILS_TO.indexOf(f.get("_send")) === -1) return false;
  
  //now ensure _redirect matches against at least one
  let validRedirect = false;
  const redirect = f.get("_redirect").toLowerCase();

  SAFE_REDIRECT_TO.forEach((u) => {
    u = u.toLowerCase();
    if (redirect.startsWith(u)) validRedirect = true;
  });

  return validRedirect;
}

/*
As there are multiple things that can go wrong, here's the general
error handler. As this is meant for Form POSTs, its ok to give a simple response.
*/
function returnError() {
  return new Response(
    "<!doctype html><meta charset=utf-8><title>500</title><h1>500 — Server Error</h1><p>Sorry, something broke on our end.</p>",
    { status: 500, headers: { "Content-Type": "text/html; charset=utf-8" } },
  );
}

export default async function (req: Request): Promise<Response> {
  let formData;
  const obj: Record<string, string> = {};

  try {
    formData = await req.formData();
    console.log("fd", formData);
  } catch (_e) {
    return returnError();
  }

  if (!verifyForm(formData)) return returnError();

  const redirect = formData.get("_redirect");

  let formName = "";
  /*
  One special field is _formname. If we have it, we include it
  in the subject + email
  */

  if (formData.get("_formname")) {
    formName = formData.get("_formname");
  } else {
    formName = `Form at ${req.headers.get("referer") ?? "unknown"}`;
  }

  const subject = `Form submission: ${formName}`;

  for (const key of new Set(formData.keys())) {
    obj[key] = formData.getAll(key).map(String).join(", ");
  }

  let html = `
<h2>Form Submission - ${formName}</h2> 
<table>
  `;

  for (const [key, value] of Object.entries(obj)) {
    console.log(key, value);
    if (SPECIAL_KEYS.indexOf(key) === -1) {
      html += `
      <tr><td style="min-width:300px">${key}</td><td>${value}</td></tr>
      `;
    }
  }

  html += `
</table>

<p>
Form submitted at ${new Intl.DateTimeFormat("en-US", { dateStyle: "short", timeStyle: "short", timeZone: "America/Chicago" }).format(new Date())}.
</p>
  `;

  console.log(html);

  const emailOptions = {
    // to: "someone_else@example.com", this would be formData.get('_email')
    html,
    subject,
  };

  if (obj["email"]) emailOptions.replyTo = obj["email"];

  await email(emailOptions);

  return new Response(null, {
    status: 303,
    headers: { Location: redirect },
  });

}

Up on top, you can see the various security variables I use to ensure the service can't be abused. I've got a list of emails that can receive the form data and a list of URLs where the user can be redirected. Again, the URLs are partially matched so you can do anything as long as it matches at the beginning.

The next variable, SPECIAL_KEYS, is just used to filter out the 'meta' values for my service and not include them in the email. This just reduces the noise for the reader.

The verifyForm handles checking our two required form fields. _send sets the recipient of the form data and _redirect handles where to go when done. For both, they have to exist, and then I check for valid values against the two variables defined on top of the script.

returnError is just a utility function to render an error. This can happen if the form didn't have the required, or correct values, or if there is an error reading the form data. I use a simple 500 error but I could imagine redirecting to an error page on the calling site instead.

Finally - the core default function does the real work. I get my form data, verify it, and then create an email. I've got code that looks for a hidden form field, _formname, which lets you give a nice label to the email.

The only real tricky part here is handling multi-value form fields, like checkboxes for example. The for loop over formData.keys() handles this and I've got Val Town's AI service to thank for the help here. I had an idea of how I was going to handle this, but the AI service suggested the code you see and honestly it was much better than what I would have written. More on the AI stuff in a second.

The last bit is just the email. Now, in a "real" implementation of this, I'd use an email service instead of Val's built-in service, but it works well enough for this demo. You can see the docs for their service to understand exactly what it can and cannot do, but the big thing for this demo is that I'm on the free tier so I can't specify the 'to' value. Note that I look for email in the form and if set, use that as the replyTo value. I call that out in my code so just note if you fork my Val and use it yourself, change this if you are on the paid tier. Or switch to an email service. You get the idea.

The Demo

Ok, finally, I built a simple CodePen form to show this in action: https://boring-morning-yak.codepen.app/. On this page you will see three forms. The first one is intentionally bad and results in a 500. The next two should work and will email me so - thanks for that. ;)

Here's an example of the email sent out:

Final Thoughts

Ok, before I ramble on a bit, you can find my val here: https://www.val.town/x/raymondcamden/form-bouncer. If you use it, let me know! Now for some things to consider.

My form does not handle file attachments. It could, but you would need something a bit more complex for that. Val Town has blob support so you could store it there, but I'd probably consider a private S3/R2 bucket instead. You could generate a link and include it in the email. You would have to also build something to handle removing old files from the bucket eventually. You would also want to sanity check the file types and sizes. Doable - but more work than I wanted to for this demo.
For form fields that can be null, like checkboxes and radio elements, they don't show up in the email at all. I could imagine a few ways around that. You could use a hidden form field to specify things like that. Maybe: <input name="_nullField" value="favoritemovie,favoritefoods" type="hidden">. The code would notice if one of these items isn't present and then render it in the email at least so it's clear the value was blank.
Another idea I had would be specifying 'friendly' labels for form fields. So example, my favorite movie comes out as favoriteMovie: Star Wars. If the idea here is to make "human readable" form results, I could see perhaps supporting something like this: <input name="_favoriteMovie_label" value="Favorite Movie" type="hidden">.
For validation, I'd do that all in the client, and by that I mean HTML first and then JavaScript.

And finally, Val Town's had an AI assistant for a while, but I never bothered with it till this demo, and damn was it useful. Not only did it help me with parsing the form object, it also reminded me of various aspects of the Request object that for the life of me I struggle to remember. It was a great companion. I will say on the free tier it doesn't take long to hit the limit, but I was able to get all the help I needed before I maxed it out. (I did get to a warning though.) Val Town's got a lot of good reasons to consider paying for it, and this is just one more. (I don't have a job and I just build dumb demos, so that's my excuse. ;)

Creating a Dynamic Favicon with Cloudinary

2026-06-16T18:00:00+00:00

Ok, chalk this up to something I may never actually use in production, but I was curious how well the browser would handle changing the favicon of a tab on the fly, and combining that with Cloudinary to dynamically modify the source. The inspiration for this was something simple - Google Calendar's favicon is unique per day, so for example, right now I see this:

As there is - at most - 31 days in a month - my assumption is that they simply generated all 31 at some point and in their code serving up the web page, they select the right one. To be honest, it's subtle and I don't always notice it, but it's a nice effect. I decided to take a look at how I'd implement this in Cloudinary with JavaScript.

The Icon

For my icon, I grabbed this nice cat icon from Flaticon: https://www.flaticon.com/free-icon/cat_8564642

Nice and simple, and not a bad choice for an icon.

This was originally a png, which you can use for a favicon, but I used Cloudinary's URL transformations to both resize it and turn it into an ICO (I added a linebreak to the URL to help it wrap):

https://res.cloudinary.com/raymondcamden/image/ 
fetch/c_fit,w_32/f_ico/https://static.raymondcamden.com/images/2026/06/cat.png

The size is handled in c_fit,w_32, setting it to 32 pixels wide while f_ico changes the format to ICO.

Adding Text

Cloudinary's transformations support adding text layers to the image, so the next thing I tried was adding that to the icon:

https://res.cloudinary.com/raymondcamden/image/
fetch/c_fit,w_32,o_33/f_ico/l_text:Arial_28_bold_center:1/fl_layer_apply/
https://static.raymondcamden.com/images/2026/06/cat.png

In the URL above, the portion beginning l_text is where I define my font, size, styling, position and finally, the actual number. I also added an opacity to the icon to make the text stand out. You can see that here, o_33, where 33 is the percent and was based on me just playing around until I felt the text was most clear.

You can see it here:

This worked well with 99 as well, but at most I think 2 characters is all you would want to fit in there.

Putting it Together

Alright, so for my fancy demo, I started off with a bit of HTML and a hard-coded favicon pointing to my cat:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
		<link rel="stylesheet" href="https://cdn.simplecss.org/simple.min.css">
    <link rel="stylesheet" href="./style.css">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <link id="favicon" rel="icon" type="image/x-icon" href="https://res.cloudinary.com/raymondcamden/image/fetch/c_fit,w_32/f_ico/https://static.raymondcamden.com/images/2026/06/cat.png">
    <title>Pen</title>
  </head>
  <body>

		<h2>Dynamic Favicon via Cloudinary</h2>
		 <p>
			 This demo shows how to dynamically create a favicon
			 via Cloudinary. It uses a source image that's resized and converted to ICO, but then can also support dynamic text (well, a small amount) written to the icon.
		 </p>
		<p>
			<button id="addBtn">Click me to increase the #</button>
			<button id="resetBtn">Click me to reset the #</button>
		</p>
		<script src="./script.js"></script>
  </body>
</html>

Note I've got two buttons. Each time you click the add button, I'm going to update the favicon with a number, while the reset button simply resets to the default.

Here's the JavaScript:

// Number used in the favicon
let NUMBER = 0;

document.addEventListener('DOMContentLoaded', async () => {

	const $favico = document.querySelector('#favicon');
	const defaultIco = $favico.href;
	
	document.querySelector('#addBtn').addEventListener('click', () => {
		NUMBER++
		setIco();
	});

	document.querySelector('#resetBtn').addEventListener('click', () => {
		NUMBER = 0;
		setIco();
	});
	
	const setIco = () => {
		if(NUMBER > 0) {
			$favico.href = `https://res.cloudinary.com/raymondcamden/image/fetch/c_fit,w_32,o_33/f_ico/l_text:Arial_28_bold_center:${NUMBER}/fl_layer_apply/https://static.raymondcamden.com/images/2026/06/cat.png`;
		} else {
			$favico.href = defaultIco;
		}
	};
	
}, false);

I grab a pointer to the favicon link in my HTML and copy out the default href value. Then I simply use two event handlers to handle each button. One increases the number, one resets it to 0. The last bit, setIco, just changes the href value.

You can test this yourself here: https://giving-flower-sunfish.codepen.app. In my testing with Chrome, it worked well. I saw the favicon update within about a second of clicking. YMMV of course. I just tested in Firefox and it worked just fine as well.

I've embedded the CodePen below, but of course you will need to run the deployed version to see it in action. Enjoy!

See the Pen Untitled by Raymond Camden (@cfjedimaster) on CodePen.

Testing Diffbot's Web Search API

2026-06-11T18:00:00+00:00

It's hard to believe I first experimented with Diffbot nearly five years ago. You can see that first post up on the Adobe Medium account - Natural Language Processing, Adobe PDF Extract, and Deep PDF Intelligence. Since then I've tested out various APIs and features from them and was lucky enough to connect with them recently about a new initiative, a web search API.

There's multiple examples of this out in the wild already, but most just scrape/hack against Google. Google had an API, the Custom Search JSON API (I even covered it back when folks still talked about the JAMStack) but the API is now deprecated and officially turning off January 1, 2027.

Diffbot's API (which quietly launched about two weeks ago) is against their own crawled index. Why does this matter? Honestly the docs do a damn good job of explaining why you should care (emphasis mine):

"Candidates are retrieved and reranked with a cross encoder model trained to rank factual relevance over popularity, primary sources over domain monopolies, and organic page rank over paid spend.

The net effect is search results that assume the user is not an idiot. A search for "hypothyroidism" returns relevant research study papers alongside content from publicly administered websites and reputable non-profit institutions."

Assuming users aren't idiots?!?!

Alright, so what's the API actually like? Cribbing from the docs, you make a GET to https://llm.diffbot.com/api/v1/web_search/ with:

Your search term as text in a query param
A max number of results via size that defaults to 10
An optional maxTokens value related to processing of the results
Lastly, a Diffbot key passed via an Authorization header

As of today, the API itself has no limits:

"Usage is currently unmetered while we open Web Search API up for public testing. Don't be the person to screw this up for everyone."

I'd expect in the future this will change and I'd check their main rate limits doc for the latest info.

As for actually using it, they've got a great Python SDK which makes this incredibly simple:

from diffbot import Diffbot

db = Diffbot(token="YOUR_TOKEN")
results = db.web_search("diffbot knowledge graph")
for r in results["search_results"]:
    print(r["score"], r["title"], r["pageUrl"])
    print(r["content"])

But with the REST API being so simple, I thought I'd build a quick demo in JavaScript and use my new favorite home for stuff like this, val.town.

Building a Web Search Alert

So this is probably the simplest implementation (and in the last hour the Diffbot team literally added new stuff to the docs, which means more content, woot) but I built a simple system that:

Once a week, hits the Diffbot Web Search API looking for a term
Filters the results based on the score value to only consider higher quality results
Emails it to me

You, my highly intelligent reader, are probably already thinking of ways to tweak that, and as I said, I plan to follow up on this (tomorrow probably), but here's the entirety of the system in one file:

I've got my key in an environment variable I snag first, and then define some core values:

My search term (and yes, you can craft more complex queries than just my name)
A max number of results
A filter to apply on the results

Then it's just a matter of hitting the endpoint. I take the results and filter based on my minimum desired value (scores go from 0 to 1 and in my testing, 0.5 helped).

Each result contains the URL of the result, the title, the score, and a portion of the content. For my email, I show each of the values, but I was a bit torn on how to handle the content value. It's markdown and I can easily turn Markdown into HTML, but it's a part of a web page and greatly screws up an HTML email.

So how does it look?

Ok, that's not terribly exciting, but you get the idea. I think where this starts to get cool is in combination with other tools as well. You will probably not be surprised to know this is covered in their AI skills as well, and I'm going to demonstrate that soon as well. Check it out for yourself and let me know what you think!

Can GenAI help you win in Vegas? (2026)

2026-06-07T18:00:00+00:00

No! Thanks for reading. Still here? Cool. So way back in 2023, I built a little demo that I thought was kinda cool. Early in 2023 I had used Alpine.js and the excellent Deck API to build a simple web-based Blackjack game: Creating a Blackjack Game with Alpine.js and the Deck of Cards API. I then took that demo and connected to Google's GenAI API, which back then was named Palm: Can GenAI help you win in Vegas?. It's been a few years and I thought I'd take a stab at it again, this time making use of Chrome's Prompt API. Technically I'd have much better luck using a bleeding edge Gemini model via a serverless function, and I may still take a stab at that later, but I thought I'd see how well the Prompt API worked.

I won't go into all the details on how the game is built, for that, check out the original post. Also, I won't go over again the UI/UX of AI prompting, which I covered in the last post. All I did was add a button: "Ask for Help!", which kicks off the process and then uses a JavaScript alert to provide feedback. That's not awesome but I'm fine with that. Ok, I lie, it's Sunday, I've got nothing but laundry to do - so I'll replace it with a native <dialog> instead!

To enable this new version, I made a couple of changes. First, I've got a new Alpine method to create the AI session. This is responsible for setting up the system instruction for the model as well:

async createSession() {
	console.log('createSession running');
	this.session = await LanguageModel.create({
		expectedOutputs: [
			{ type:'text', languages: ['en'] }
		],
		initialPrompts: [
			{
				role: 'system',
				content:
							`
You are an expert Blackjack advisor helping a player make decisions in a simplified game (no splitting, no doubling down, no surrender). Your goal is to advise the player whether to 'Hit' or 'Stand' based on standard basic Blackjack strategy.

CRITICAL GAME RULES:
- Goal: Beat the dealer's hand value without exceeding 21 (busting).
- Card Values: Cards 2-10 are face value. Jack, Queen, and King are worth 10. Aces are worth either 1 or 11, whichever is more beneficial without busting.
- Blackjack: A "Blackjack" is strictly a 2-card hand consisting of an Ace and a 10-value card (10, J, Q, K). An Ace and an 8 is just 19, not a Blackjack.
- Soft vs. Hard: A hand with an Ace counted as 11 is a "soft" hand (e.g., Ace + 6 = soft 17). Otherwise, it is a "hard" hand.

INSTRUCTIONS:
You will be provided with the player's current hand and the dealer's visible card.
Respond strictly in the following format:
ACTION: [Choose ONLY "Hit" or "Stand"]
REASON: [A brief, one-sentence logical explanation based on standard Blackjack probabilities and the dealer's visible card]
`,
		},
	],
	monitor(m) {
		m.addEventListener('downloadprogress', (e) => {
			if (e.loaded === 0) return;
			const pct = Math.floor(e.loaded * 100);
			if(pct !== 0 && pct !== 100) this.aiHelp = `Downloading model… ${pct}%`;
		});
	},
});

Note the level of detail in the system instruction. Initially I had just the initial paragraph and a bit about how to return the results. I took this to the Gemini desktop app and asked this:

I’ve built a web based Blackjack game. It’s a simplified version that doesn’t 
include splitting or doubling down. As part of the game, I used Chrome’s 
built-in Prompt API to offer advice to the player on whether to hit or stand. 
This works *mostly* ok, but I see mistakes, for example, Chrome’s Prompt API 
once said an Ace + 8 is a blackjack, when it has to be a face card or 10 as 
far as I know. To help me improve the prompt, can you give me a good system 
prompt that briefly, but completely, covers the rules, again though ignoring 
doubling down/splitting/etc. This is the current system instruction:

(I pasted the first version here)

I then took its improved prompt and added it to my code.

Next I had to wire this up to the AI advice button. This is the askForHelp method and the referenced schema:

const adviceSchema = {
  type: 'object',
  properties: {
    action: { type: 'string', enum:['HIT','STAND'] },
    reason: { type: 'string' }
  },
  required: ['action', 'reason']
};

async askForHelp() {
	console.log('lets call an (AI) friend');
	if(!this.session) {
		console.log('generating a session');
		this.aiHelp = '<i>Creating the AI session.</i>';
		await this.createSession();
	}
	this.aiHelp = '<i>Asking our AI friend...</i>';

	let totalOb = this.getCount(this.playerCards);

	// string to represent my hand, could be 2-5 cards
	let playerStr = 'My hand consists of:\n ';
	// this could be reduce(), im being lazy
	this.playerCards.forEach(p => {
		playerStr += `${p.value} of ${p.suit.toLowerCase()}\n`;
	});
	
	// string to set the total value for the prompt, helps it
	let totalStr = 'My hand has a total of ';
	if(totalOb.lowCount === totalOb.highCount) {
		totalStr += totalOb.lowCount;
	} else {
		totalStr += `${totalOb.lowCount} or ${totalOb.highCount}`;
	}
	
	let content = `
I'm playing blackjack and the dealer currently has ${this.pcCards[1].value} of ${this.pcCards[1].suit.toLowerCase()}.

${playerStr}

${totalStr} 

Should I hit or should I stay?
	`;
	console.log('content', content);
	let result = JSON.parse(await this.session.prompt(
		[{ role: 'user', content }], 
		{ responseConstraint: adviceSchema }
));
	console.log(result);
	
	let resultMsg = `
You should ${result.action}. Why?
${result.reason}
`;

	this.aiHelp = '';
	this.advice = resultMsg;
	this.$refs.adviceDialog.showModal();
}

Ok, there's a few things of note going on here. As with the previous version, I take the current game state and turn it into a prompt where I describe my hand. While working on this version I discovered a pretty big flaw from the previous game. When asking AI for advice, I only described two cards max. Now I ensure I describe my entire hand.

Now you may be wondering, why do I get the total value of my hand - shouldn't the model know how to calculate that? As before, at least in the Prompt API, the answer is no. Initially I removed that bit thinking the system instruction would be enough. But even though my system prompt describes how to get the total of a hand, I still found the model calculating the total wrong. Not all the time, but at least once. So the little helper string went back in.

The other change in this version is a proper schema to shape the response - give me an action (hit or stay) and a reason. This gets turned into a string and passed to my HTML dialog element. Here's how it looks in action:

In case that's hard to read, the dialog says:

"You should HIT. Why? With a hard 16, you need to improve your hand to stand a chance against the dealer's strong 10."

If I remember right, this advice makes sense, but I find it difficult personally to hit on anything 15 and higher. For that particular round I stayed and the dealer won with Blackjack, so I had no chance.

In my next test, the dealer was showing a King of Clubs and I had two Aces and the advice was:

"You should STAND. Why? You have a soft 2 or 12 which is a strong hand, and the dealer has a King, making it unlikely they will have a high hand."

That seems crazy, so I went ahead and got a new card which ended up being a seven. At that point the AI suggested staying, which I did, and I still lost as the dealer's other card was a 10.

In my next round, the dealer was showing a queen and I had a 5 and a 9. The AI suggested hitting which I completely agreed with and of course - I busted.

I played a few more times, and generally the model's suggestions seemed ok. I could see it being useful if I was a complete novice at the game, but I don't see whipping out my phone and asking AI for help any time soon. (I don't really game myself, but I assume most casinos have rules against this now. Anyone know offhand?)

What do you think? If you've got an up to date Chrome, you can test it here: https://codepen.io/cfjedimaster/full/KwNbvPq/afbf4079fe199863f11f75957817fcc8. Note that the first time you download the model it may take 5 to 10 minutes, but that applies across your device as a whole. If you run across another demo using the API you won't need to download it again.

If you want to take a look at the code, I've embedded it below. The dialog I added could really use some styles so if anyone wants to fork and share, let me know!

See the Pen Blackjack (Chrone AI) by Raymond Camden (@cfjedimaster) on CodePen.

AI versus a Grue

2026-06-02T18:00:00+00:00

"It is pitch dark. You are likely to be eaten by a grue." If you recognize that quote, congrats, you probably need to see your doctor about pain in your back. (Ok, pain everywhere.) For those of us of a certain age, or folks who like classic games, the Infocom series was a tremendous source of entertainment. Using plain text commands to navigate your environment, players had to use their minds to figure out puzzles and mazes in order to win the game. The IF (Interactive Fiction) community is still strong and of course, I've spoken before about my time playing and coding on MUDs, so with that in mind, I thought I'd try tackling something that I assumed probably wouldn't work well - seeing if Chrome's built-in AI could handle playing Zork 1, the most famous of Infocom's library. The short answer is... not so well. But honestly, it was kind of fun to try so I figured I'd share the results.

Getting Zork

Before I could even begin trying to test AI's ability to play a 50 year old game (almost 50, Zork 1 launched in 1977), I first needed to find a JavaScript implementation. This turned out to be a bit tricky.

I quickly found ifvms.js, an interactive fiction virtual machine library, but it was tailored to running at the command line. Also, there was little to no documentation on how to make use of the library. The repo mentions another repo, parchment which lets you play games on the web, but I struggled to find documentation there as well, or documentation specific to my use case.

To help, I went to Claude, and had it load ifvms.js and create a 'stubbed' version that I could use via calls like so:

// all of this loads Zork 1...
const res = await fetch('zork1.b64.txt');
const b64 = await res.text();

const binary = atob(b64.trim());
const arrayBuffer = new ArrayBuffer(binary.length);
const view = new Uint8Array(arrayBuffer);
for (let i = 0; i < binary.length; i++) {
    view[i] = binary.charCodeAt(i);
}

engine = new ZorkEngine();
engine.load(arrayBuffer);

// and then later:
let gameResponse = engine.getOutput(); // last thing the game did

// send a command
let lastResponse = engine.send(command);

That source file above mentioned in the first line comes from an online source. Zork itself is open source (https://github.com/historicalsource/zork1), but I forget where I got my copy of the source. It's not a text file, I renamed it to that when initially attempting to build my demo on CodePen. I believe it was pure binary I converted to base64 and then renamed.

Building the Game

So with Claude helping me build the version of ifvms I could use interactively, I then had to whip up a quick UI and point Chrome's Prompt API, which as of Chrome 148 is GA to everyone. (Well, everyone on Chrome.)

My UI was just a giant text area where I'd stream the output from the game and Chrome's inputs. All of that code is kinda basic, so I'll focus on the prompt aspect. Here's how I create my session:

$session = await LanguageModel.create({
    initialPrompts:[
        { 
            role: 'system', 
            content: 
                    `
You are playing the classic text adventure game Zork. You will be given the current game output, and you will 
respond with a single command to play the game. You will not explain your command, just give the command. 

Remember to keep your commands concise and to the point, as if you were playing the game yourself. Do not include 
any extra text or explanations.

Zork is a text-based adventure game where you explore a mysterious underground world filled with treasures, puzzles, 
and dangers. Your goal is to navigate through the various locations, solve puzzles, and collect treasures 
while avoiding traps and monsters.

Here are some examples of commands you might use in Zork:
- "go north"
- "take lamp"
- "open mailbox"
- "look around"
- "inventory"

Do your best to play the game effectively and efficiently, making smart choices based on the current game output.

Try not to keep returning to the same location repeatedly, as that can lead to getting stuck in loops. Instead, 
explore new areas and try different actions to progress through the game. Remember that you can travel in all directions.
                    `
        }
    ],		
    monitor(m) {
            m.addEventListener("downloadprogress", e => {
                console.log(`Downloaded ${e.loaded * 100}%`);
                if(e.loaded === 0 || e.loaded === 1) {
                    $output.innerHTML = '';
                    return;
                }
                $output.innerHTML = `Downloading AI model, currently at ${Math.floor(e.loaded * 100)}%`;
            });
        }		
});

As you can see, a majority of this is the big prompt. I iterated over this multiple times to help guide Chrome to effectively solve the game. (Which to be clear, it never did.)

Outside of that, the main loop of the game is this heartbeat function:

async function gameHeartBeat() {

    console.log('in hb');
    let gameResponse = engine.getOutput();
    if(!gameResponse) gameResponse = lastResponse;

    if(gameResponse) {
        $gameoutput.value += gameResponse + '\n';
        $gameoutput.scrollTop = $gameoutput.scrollHeight;

        let command = await $session.prompt(gameResponse);
        lastResponse = engine.send(command);

        $gameoutput.value += `> ${command}\n`;
        $gameoutput.scrollTop = $gameoutput.scrollHeight;

        console.log('Resp',command);
        setTimeout(gameHeartBeat, 1000 * 2);
    }
 
}

The variable $gameoutput is just a DOM pointer to the textarea used to render the game.

Before going any further, I'll note a huge issue with my code and that's the lack of session management. Chrome absolutely provides you a way to monitor that usage and re-init the session when it is nearly filled. I didn't bother with that because I was being lazy when I built this.

I'd also argue that we could help Chrome's model quite a bit by keeping track of a list of rooms it has already visited to help it remember and not loop over the same place. My prompt tries to do that, but I could also help it out myself.

All in all - this was a quick implementation and the results were... well what you would expect with a lightweight model and me just hacking quickly on it. ;)

Here's a transcript from a test I just did.

ZORK I: The Great Underground Empire
Infocom interactive fiction - a fantasy story
Copyright (c) 1981, 1982, 1983, 1984, 1985, 1986 Infocom, Inc. All rights reserved.
ZORK is a registered trademark of Infocom, Inc.
Release 119 / Serial number 880429

West of House
You are standing in an open field west of a white house, with a boarded front door.
There is a small mailbox here.

>                                                                                 West of HouseScore: 0  Turns: 0
> examine mailbox
The small mailbox is closed.

>                                                                                 West of HouseScore: 0  Turns: 1
> open mailbox
Opening the small mailbox reveals a leaflet.

>                                                                                 West of HouseScore: 0  Turns: 2
> read leaflet
(Taken)
"WELCOME TO ZORK!

ZORK is a game of adventure, danger, and low cunning. In it you will explore some of the most amazing territory ever seen by mortals. No computer should be without one!"

>                                                                                 West of HouseScore: 0  Turns: 3
> look around
West of House
You are standing in an open field west of a white house, with a boarded front door.
There is a small mailbox here.

>                                                                                 West of HouseScore: 0  Turns: 4
> go north
North of House
You are facing the north side of a white house. There is no door here, and all the windows are boarded up. To the north a narrow path winds through the trees.

>                                                                                 North of HouseScore: 0  Turns: 5
> go north
Forest Path
This is a path winding through a dimly lit forest. The path heads north-south here. One particularly large tree with some low branches stands at the edge of the path.

>                                                                                 Forest PathScore: 0  Turns: 6
> examine tree
There's nothing special about the tree.

>                                                                                 Forest PathScore: 0  Turns: 7
> go north
Clearing
You are in a clearing, with a forest surrounding you on all sides. A path leads south.
On the ground is a pile of leaves.

>                                                                                 ClearingScore: 0  Turns: 8
> take leaves
In disturbing the pile of leaves, a grating is revealed.
Taken.

>                                                                                 ClearingScore: 0  Turns: 9
> open grating
The grating is locked.

>                                                                                 ClearingScore: 0  Turns: 10
> look around
Clearing
You are in a clearing, with a forest surrounding you on all sides. A path leads south.
There is a grating securely fastened into the ground.

>                                                                                 ClearingScore: 0  Turns: 11
> go south
Forest Path

>                                                                                 Forest PathScore: 0  Turns: 12
> go north
Clearing

>                                                                                 ClearingScore: 0  Turns: 13
> examine leaves
There's nothing special about the pile of leaves.

>                                                                                 ClearingScore: 0  Turns: 14
> go south

In my tests, it never seems to get much further in the game than the outer area, but certainly tries hard, so I guess I'll give it a gold star for that.

If you want to try this yourself, you can point Chrome at https://cfjedimaster.github.io/webdemos/chrome_zork/.

If you want to peruse the code yourself, you can check it out here: https://github.com/cfjedimaster/webdemos/tree/master/chrome_zork

Now that I've got a bit more time on my hands (ahem), I may try hacking on this a bit more, but it was certainly fun to see it in action.

Photo by Joshua Sortino on Unsplash

Creating a Heavy Rain Alert with RainDrop and Val Town

2026-06-01T18:00:00+00:00

One of the "joys" of living in Louisiana is the rainy season, which is heavier in spring but honestly, feels like it lasts all year long. I can still remember being on a business trip in 2016, about to fly home, and hearing about some sort of 'rain event' back in Louisiana. This surprised me as there wasn't a hurricane involved, just an incredible amount of rain (up to 2-3 inches per hour). You can read more about it on the Wikipedia page about the event, but it goes without saying - rain is a big deal down here.

A while back I discovered RainDrop, which is an app and a web site that lets you check on rainfall totals. You can see my zipcode here, https://www.raindrop.farm/rainfall-totals/zipcode/70508#map, and while we aren't having any rain this second, we've got some forecast for today.

When I discovered the site, I did some digging and discovered they had an API: https://api.raindrop.farm/docs. This API gives you incredibly detailed information about rainfall (and snow) and can even return historical data.

Given an API key passed in an Authorization header, this gets the current precipitation for my location:

https://api.raindrop.farm/v1/precipitation/current?lat=30.216667&lon=-92.033333

Which returns (as of 11:34 AM, and I just heard thunder):

{
    "lat": 30.216667,
    "lon": -92.033333,
    "timestamp": "2026-06-01T16:30:00Z",
    "precipitationIntensity": 0.0
}

Ok - slight delay here - I just got out of a meeting, and the rain is here:

{
    "lat": 30.216667,
    "lon": -92.033333,
    "timestamp": "2026-06-01T17:06:00Z",
    "precipitationIntensity": 1.2999999523162842
}

That value is in millimeters per hour so it looks like just a trickle, so nothing to worry about. Of course, what if it was something to worry about? I thought - why not automate checking for this using my go to platform lately, Val Town.

The App

Alright, so the app I had in mind was fairly simple:

Every X minutes, use the RainDrop API to check the rain intensity and if it is over a certain threshold, send an alert my way.

My RainDrop API access had pretty high usage limits (120 a minute) that were above what made sense to realistically check. On the other hand, my free tier level at Val Town capped me at one execution per fifteen minutes.

To be honest, once every fifteen minutes seemed perfectly reasonable, but keep in mind that both RainDrop and Val Town would support much higher frequencies if necessary.

Given the above, I created a new val and set the trigger to Cron, set to every 15 minutes:

I then created an environment variable for my RainDrop key. With that in place, the entire "early warning flood system" (that's what I'll call it when doing interviews for my next job) is one file:

import { email } from "https://esm.town/v/std/email";

/**
 * Converts speed from millimeters per hour to inches per hour.
 * @param {number} mmPerHour - Speed in millimeters per hour.
 * @returns {number} Speed in inches per hour.
 */
function mmPerHourToInchesPerHour(mmPerHour) {
  return mmPerHour / 25.4;
}

function dtFormat(timestamp) {
  const date = new Date(timestamp);

  const options = {
    weekday: "long",
    year: "numeric",
    month: "long",
    day: "numeric",
    hour: "2-digit",
    minute: "2-digit",
    timeZoneName: "short",
  };

  // Create the formatter (e.g., for US English)
  const formatter = new Intl.DateTimeFormat("en-US", options);

  return formatter.format(date);
}

export default async function (interval: Interval) {
  // Lafayette, LA
  const lat = "30.216667";
  const lng = "-92.033333";

  // The threshold value is inches of rain per hour - any value >= will trigger a warning
  const threshold = 0.5;

  let key = Deno.env.get("API_KEY");
  let precipReq = await fetch(
    `https://api.raindrop.farm/v1/precipitation/current?lat=${lat}&lon=${lng}`,
    {
      headers: {
        "Authorization": key,
      },
    },
  );

  let precip = await precipReq.json();
  let rainInches = mmPerHourToInchesPerHour(precip.precipitationIntensity);
  console.log("rainInches", rainInches);
  console.log(precip);

  if (rainInches >= threshold) {
    let html = `
<h2>Heavy Rain Alert</h2>

<p>
As of ${
      dtFormat(precip.timestamp)
    }, we have detected ${rainInches.toFixed(2)} inches of rain per hour.
</p>
    `;

    await email({
      subject: "Rain Alert",
      html,
    });
  }
}

On top of my script are two utility functions with the interesting one being the simple wrapper to convert RainDrop's values to inches.

After that, I hit the API, check against a threshold (currently set to half an inch), and if it matches, I fire off an email. As a reminder, I'm using Val Town's built in "mail the owner" feature. I could also use a proper email API to have more control over the delivery, but this works well for now.

And of course, as soon as I built this there were no events, which is good I suppose, but I did a quick tweak to force it to email and here's an example. Not terribly thrilling with 0 inches:

If you want to play with this, you can fork the val here: https://www.val.town/x/raymondcamden/raindropAlert. And of course if you do, let me know!

Photo by reza shayestehpour on Unsplash