Mert

A few months back I sat in on a claim-dispute review for a degraded vaccine shipment. The temperature logger had transmitted readings every 30 minutes for the entire journey. The data looked clean. The shipment arrived ruined. The insurer denied the claim because the audit trail couldn’t prove when the excursion occurred, what else was happening at the time, or whether the device clock had drifted relative to the warehouse system that received the goods.

The hardware was fine. The firmware was wrong.

This post is for the embedded engineers, IoT platform builders, and firmware leads who are about to ship — or have already shipped — a cold chain monitoring device that will eventually become evidence in a regulatory inspection or insurance claim. There are three failure modes that account for the overwhelming majority of audit findings I’ve seen across deployments in 100+ countries, and all three are firmware-layer problems with concrete code patterns to solve them.

What Does Audit-Defensible Telemetry Actually Require?

A regulatory auditor — FDA FSMA 204, EU GDP, WHO TRS 957 — isn’t looking at your dashboard. They’re looking at whether the raw data your device produced can be reassembled into a defensible chain of custody. That means three concrete things at the firmware layer: time you can trust, events not just points, and no silent gaps.

Every record must be timestamped against a source that doesn’t drift, with documented bounds on how much drift is possible. When a threshold gets crossed, the device must produce a bounded event with start, end, peak, duration, and Mean Kinetic Temperature impact — not just a stream of raw readings that downstream systems have to reconstruct. And if connectivity drops, the device must buffer locally, mark the offline period explicitly, and replay with idempotent sequence numbers when it reconnects.

Anything less and your data is evidence the opposing side will use, not evidence you can rely on. The three failure modes below are each a missing pillar of that requirement set.

How Does Clock Drift Break Your Audit Trail?

The single most common audit finding I see. A device’s RTC drifts by 30 seconds per day. After a 60-day shipment, its timestamps are off by 30 minutes relative to the warehouse system. An auditor compares the excursion event at 14:30:00 to the dock manifest showing the truck arrived at 14:58:00 and concludes the chain of custody narrative is broken. Defending the data costs the program weeks of forensic work, and sometimes the claim regardless.

The fix is layered time synchronization. Cellular NITZ is your primary source — most LTE-M and NB-IoT carriers expose it on attach. GNSS time-fixing is your fallback when there’s a satellite lock. The internal RTC is the last resort, and any reading sourced only from RTC drift should be tagged with the drift bound so an auditor sees the uncertainty explicitly rather than discovering it during a deposition.

typedef enum {
    TIME_SRC_NITZ   = 0,
    TIME_SRC_GNSS   = 1,
    TIME_SRC_RTC    = 2,
} time_source_t;

typedef struct {
    uint64_t       timestamp_utc_ms;
    time_source_t  source;
    uint32_t       drift_bound_ms;
} timestamped_t;

timestamped_t get_authoritative_time(void) {
    timestamped_t t;
    if (cellular_nitz_available()) {
        t.timestamp_utc_ms = cellular_get_nitz_ms();
        t.source = TIME_SRC_NITZ;
        t.drift_bound_ms = 0;
        rtc_sync_to(t.timestamp_utc_ms);
        return t;
    }
    if (gnss_has_fix()) {
        t.timestamp_utc_ms = gnss_get_utc_ms();
        t.source = TIME_SRC_GNSS;
        t.drift_bound_ms = 0;
        rtc_sync_to(t.timestamp_utc_ms);
        return t;
    }
    t.timestamp_utc_ms = rtc_now_ms();
    t.source = TIME_SRC_RTC;
    t.drift_bound_ms = rtc_drift_since_last_sync_ms();
    return t;
}

Every record carries its time source. If an auditor flags a timestamp that came from drifting RTC, you produce the drift bound and explain it. If it came from NITZ or GNSS, you have an authoritative anchor and the conversation moves on.

Why Do Raw Points Fail Where Bounded Events Pass?

Most cold chain devices emit a stream of temperature readings every N minutes. When a reading crosses a threshold, they emit an alert. The reading goes into the cloud. The alert goes into the dashboard. Auditors then have to reassemble what happened from raw points — and reassembly is where every claim dispute I’ve ever seen starts to wobble.

EU GDP and WHO TRS 957 both expect bounded excursion events — when did it start, when did it end, what was peak deviation, what was cumulative duration above threshold, and was Mean Kinetic Temperature preserved? That’s a state machine in firmware, not a comparator in the cloud.

typedef enum {
    EXC_NORMAL = 0,
    EXC_THRESHOLD_CROSSED,
    EXC_IN_EXCURSION,
    EXC_EVENT_FINALIZED,
} excursion_state_t;

typedef struct {
    excursion_state_t  state;
    uint64_t           start_ts_ms;
    uint64_t           end_ts_ms;
    float              threshold_c;
    float              peak_value_c;
    float              cumulative_sum_c_seconds;
    char               event_id[16];
} excursion_event_t;

void excursion_update(excursion_event_t *evt, float reading_c, uint64_t ts_ms) {
    bool over = reading_c > evt->threshold_c;
    switch (evt->state) {
        case EXC_NORMAL:
            if (over) {
                evt->state = EXC_THRESHOLD_CROSSED;
                evt->start_ts_ms = ts_ms;
                evt->peak_value_c = reading_c;
                ulid_generate(evt->event_id);
            }
            break;
        case EXC_THRESHOLD_CROSSED:
        case EXC_IN_EXCURSION:
            if (over) {
                evt->state = EXC_IN_EXCURSION;
                if (reading_c > evt->peak_value_c) evt->peak_value_c = reading_c;
                evt->cumulative_sum_c_seconds +=
                    (reading_c - evt->threshold_c) * SAMPLE_INTERVAL_SECONDS;
            } else {
                evt->state = EXC_EVENT_FINALIZED;
                evt->end_ts_ms = ts_ms;
                emit_excursion_event(evt);
                memset(evt, 0, sizeof(*evt));
            }
            break;
        default: break;
    }
}

When emit_excursion_event fires, it produces a complete record an auditor can drop directly into a compliance report. Reconstruction is no longer the cloud’s problem. The device emits the answer at the moment it has all the context, which is the only moment it ever truly does.

How Do You Stop Silent Connectivity Gaps From Wrecking the Record?

A device passes through a metal-shielded warehouse for four hours. Cellular drops out. The firmware quietly buffers locally — but when connectivity returns, it pushes the readings as if they had been transmitted in real time, with no marker indicating they came from the offline period. The dashboard looks continuous. The audit trail has a hidden four-hour gap that an investigator can trivially detect by comparing transmission timestamps to reading timestamps.

The fix is sequence numbers and idempotent replay. Every reading gets a monotonically increasing sequence number assigned at sample time, not transmit time. The cloud side keeps a high-water mark per device and ignores any sequence number it has already processed. The replay is safe to retry indefinitely, and the offline window appears in the audit log as a contiguous range of sequence numbers with sample timestamps inside the offline window — fully traceable.

typedef struct {
    uint64_t  sequence;
    uint64_t  timestamp_utc_ms;
    char      event_id[16];
    uint8_t   payload[PAYLOAD_MAX];
    uint8_t   retries;
    bool      acked;
} telemetry_record_t;

static uint64_t g_next_sequence = 0;

void telemetry_buffer_sample(const sensor_reading_t *r) {
    telemetry_record_t rec = {
        .sequence         = ++g_next_sequence,
        .timestamp_utc_ms = r->ts.timestamp_utc_ms,
    };
    ulid_generate(rec.event_id);
    encode_payload(&rec.payload, r);
    nvm_queue_push(&rec);
}

void telemetry_flush(void) {
    while (nvm_queue_has_pending() && cellular_is_up()) {
        telemetry_record_t rec = nvm_queue_peek();
        int rc = cellular_post_record(&rec);
        if (rc == HTTP_OK || rc == HTTP_CONFLICT_DUPLICATE) {
            nvm_queue_pop();
        } else {
            rec.retries++;
            if (rec.retries > MAX_RETRIES) {
                log_record_failed(&rec);
                nvm_queue_pop();
            }
            break;
        }
    }
}

The cloud receiver only needs to check the high-water mark before inserting:

def ingest_record(device_id, record):
    high_water = redis.get(f"hw:{device_id}") or 0
    if record["sequence"] <= int(high_water):
        return 409
    insert_into_audit_log(device_id, record)
    redis.set(f"hw:{device_id}", record["sequence"])
    return 200

Now a four-hour offline period appears in the audit log as a contiguous range of sequence numbers with sample timestamps from the offline window — auditable, explicit, defensible. The same logic survives power cycles when the queue lives in non-volatile memory, and a malicious actor cannot rewrite the sequence without invalidating downstream signatures.

What Should Every Sample Record Actually Look Like?

Putting the three patterns together, every sample your firmware emits should look something like this on the wire — explicit time source attribution, an immutable sequence number, a calibration reference, a firmware fingerprint, and a cryptographic signature. Each of those fields exists to close one specific audit hole, and an auditor reading the schema can reverse-engineer the design intent without asking you.

{
  "device_id": "GPT29-AB123",
  "sequence": 482190,
  "sample_ts": "2026-05-19T14:30:00Z",
  "time_source": "NITZ",
  "time_drift_bound_ms": 0,
  "samples": {
    "temperature_c": 4.2,
    "humidity_rh": 38,
    "light_lux": 0,
    "shock_g": 0.2,
    "tilt_deg": 8
  },
  "calibration_id": "cal_2026Q1_NIST",
  "firmware_sha256": "a7c4...e9b1",
  "signature": "ed25519:7f3a..."
}

Five sensors, one synchronized timestamp with its source attribution, a calibration reference, a firmware fingerprint, and a signature. A regulator can audit any individual record back to a calibrated sensor, a known firmware build, and a synchronized time anchor. For comparison, a temperature-only logger transmitting basic readings is producing data. The schema above is producing evidence.

What Does This Pattern Actually Enable?

Once your firmware emits this shape of record, the audit story writes itself. Continuity is enforced by sequence numbers. Calibration is traceable. Events are bounded. Time is authoritative. Multi-sensor context provides the causal evidence for root cause analysis when a shipment fails. Signing locks down tamper resistance, so a defense team can’t claim the timestamps were rewritten between the device and the storage layer.

I’ve built variations of this pattern into Eelink’s GPT29 cold chain monitor — six sensors in a single enclosure, each sampling independently, each record signed and sequenced. The firmware-level work is mostly in the state machine and the buffer-replay layer; the cryptographic signing is incidental once you have a key in secure storage. The hardest part isn’t any individual piece. It’s committing to the full architecture before the procurement team asks for evidence and the answer has to already exist on the wire.

What Approach Have You Taken on Your Own Deployment?

If you’ve built or deployed cold chain telemetry that’s been through an actual regulatory or insurance audit, I’d love to hear what failed and what worked. The patterns above are field-tested across thousands of devices, but every deployment surfaces edge cases — clock-synchronization races on first cellular attach, sequence-counter resets after firmware updates, sensor calibration drift between annual recalibrations, and the awkward moment when a partial event survives a watchdog reset. Drop a comment with what you’ve seen, especially the ones you had to learn the hard way.

If you’re at the architecture-decision stage and want to compare notes, I read every message at appleko.io/contact.

This article was written with AI assistance for research and drafting. The firmware patterns, code, and field observations are based on real deployments I’ve worked on.

Every morning, a video goes live on my YouTube channel. I didn’t film it. I didn’t edit it. My computer did all of it while I slept.

Here’s the story of how I built Progress Bar of the Year – a fully automated YouTube Shorts channel that posts a daily update on how much of the current year has passed – and the surprisingly elegant tech stack behind it.

The Idea: Simple, But Strangely Satisfying

The premise couldn’t be simpler: every day, a short video goes up showing what percentage of the year has elapsed, paired with a fun historical fact about something that happened on this same day in a previous year.

That’s it.

But there’s something almost meditative about watching the year tick forward – and something genuinely cool about a channel that runs itself. No burnout, no filming schedule, no editor. Just code, running quietly on a small computer in the corner.

The Tech Stack at a Glance

Let’s break down each piece.

Step 1: The Math – How Much of the Year Has Passed?

What it does: Calculates today’s date, the total days in the current year, and the percentage of the year that’s gone by.

How it works: This is pure JavaScript – no libraries needed. The logic boils down to three things:

const now = new Date();
const startOfYear = new Date(now.getFullYear(), 0, 1);
const endOfYear = new Date(now.getFullYear() + 1, 0, 1);

const elapsed = now - startOfYear;
const total = endOfYear - startOfYear;
const percentage = ((elapsed / total) * 100).toFixed(2);

It also accounts for leap years automatically, since endOfYear - startOfYear will naturally be 366 days in a leap year.

Why this approach: JavaScript’s Date object handles all the heavy lifting. There’s no edge case to manually code – the language figures out whether it’s February 28th or 29th, whether we’re in a leap year, all of it. Simple and bulletproof.

Output: A number like 38.21 – meaning 38.21% of 2026 has already passed.

Step 2: The History Hook – Google Gemini API

What it does: Fetches a genuinely interesting historical event that happened on this exact calendar day in a previous year.

Why AI instead of a static database? A hardcoded database of historical facts would work – but it would be finite, brittle, and boring to maintain. The Gemini API gives us:

• An effectively unlimited and varied set of historical facts
• Natural language output ready to display on screen
• The ability to request facts in a specific format or tone

How it works: A prompt is sent to the Gemini API each day with the current month and day, asking for a notable historical event:

const prompt = `
  Give me one interesting historical event that happened on ${month} ${day} 
  in any previous year. Keep it to 1-2 sentences. Be specific with the year.
`;

const response = await gemini.generateContent(prompt);
const fact = response.text();

The API returns something like: “49 years ago on this day, the first public screening of Star Wars generated enormous excitement among audiences who had never seen anything like it.”

Why this matters for the channel: It transforms what could be a dry statistics update into something actually worth watching. Every video has a little historical surprise baked in. It gives viewers a reason to come back — not just for the percentage, but for the story of the day.

Step 3: Video Generation – Remotion

What it does: Takes the percentage and the historical fact and renders them into a polished, animated MP4 video – entirely in code.

What is Remotion? Remotion is a framework that lets you write videos using React. Instead of opening Premiere Pro or After Effects, you define your video as a React component. Animations, timing, transitions – all written in TypeScript. Then you render it to an actual video file using Node.js.

Why Remotion over other tools?

• Full programmatic control – Every pixel, every animation, every timing decision is in code. No manual steps, no GUI.
• Consistent output – The same code produces the same visual style every single day, automatically.
• React-based – If you already know React, you’re immediately productive.
• High quality – Remotion renders frame-by-frame at whatever resolution and framerate you specify. The output is a proper video file, not a screen recording.

What the video looks like: A dark, minimal design with:

• The year progress percentage in large type
• A smooth animated progress bar filling to the correct point
• Today’s date
• The historical fact rendered as clean text below
• A short looping background animation for visual polish

The entire VideoTemplate.tsx component is just a React component with Remotion’s <AbsoluteFill>, <spring>, and timing hooks to drive the animation.

export const VideoTemplate: React.FC<VideoProps> = ({ percentage, fact, date }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  const progress = spring({ frame, fps, config: { damping: 200 } });

  return (
    <AbsoluteFill style={{ background: '#0f0f1a' }}>
      <ProgressBar width={progress * percentage} />
      <PercentageText value={percentage} />
      <HistoricalFact text={fact} />
    </AbsoluteFill>
  );
};

Once the component is ready, rendering is a single CLI command (or programmatic call):

npx remotion render VideoTemplate out/video.mp4

Step 4: Uploading to YouTube – YouTube Data API v3

What it does: Takes the rendered MP4 and automatically uploads it to the YouTube channel with a title, description, and the correct Shorts formatting – no human involvement.

How the YouTube Data API works: Google provides an official API for interacting with YouTube programmatically. After a one-time OAuth2 authentication setup (where you grant your app permission to upload to your channel), you can upload videos, set metadata, manage playlists, and more – all from code.

The upload flow:

const youtube = google.youtube({ version: 'v3', auth: oauth2Client });

await youtube.videos.insert({
  part: ['snippet', 'status'],
  requestBody: {
    snippet: {
      title: `Year Progress Update - ${formattedDate}`,
      description: `${percentage}% of ${year} has passed.nn${historicalFact}`,
      tags: ['yearProgress', 'motivation', 'history'],
      categoryId: '22',
    },
    status: {
      privacyStatus: 'public',
    },
  },
  media: {
    body: fs.createReadStream('out/video.mp4'),
  },
});

Making it a YouTube Short: YouTube Shorts are simply vertical videos (9:16 aspect ratio) under 60 seconds. Remotion renders the video at 1080×1920, and that’s all YouTube needs to classify it as a Short – no special API flag required.

The token refresh problem: OAuth2 tokens expire. To keep the automation running forever without manually re-authenticating, the app stores refresh tokens in tokens.json and automatically refreshes the access token before each upload. This is the kind of detail that separates a weekend project from something that actually keeps running for months.

Step 5: The Bash Script – Gluing It All Together

What it does: run-daily.sh is the conductor. It runs once a day and orchestrates the entire pipeline end-to-end.

Why a bash script? The core logic is in Node.js/TypeScript, but crontab (which triggers the daily run) works at the OS level. A bash script acts as the perfect bridge – it can set up the environment, invoke Node, handle errors, and maintain a log.

What the script does, step by step:

#!/bin/bash

PROJECT_DIR="/Users/mdshuvo/yearlyprogress"
STATE_FILE="$PROJECT_DIR/last-upload-date.txt"
LOG_FILE="$PROJECT_DIR/log.txt"

TODAY=$(date +%Y-%m-%d)

# Read the last run date
if [ -f "$STATE_FILE" ]; then
  LAST_RUN=$(cat "$STATE_FILE")
else
  LAST_RUN=""
fi

# Skip if already ran today
if [ "$LAST_RUN" = "$TODAY" ]; then
  exit 0
fi

cd "$PROJECT_DIR" || exit 1

# Run the main script, append output to log
/Users/mdshuvo/.nvm/versions/node/... >> "$LOG_FILE" 2>&1

# Trim the log to keep only the last 2000 lines
if [ -f "$LOG_FILE" ]; then
  tail -n 2000 "$LOG_FILE" > "$LOG_FILE.tmp" && mv "$LOG_FILE.tmp" "$LOG_FILE"
fi

Key design decisions:

• Idempotency – The state file check ensures the script never accidentally uploads twice on the same day, even if crontab triggers it multiple times.
• Logging – All output is appended to log.txt for easy debugging if something goes wrong.
• Log trimming – The log is kept to 2,000 lines so it doesn’t grow forever and fill up the disk.
• nvm path – The full path to the Node binary is specified, because crontab runs in a minimal environment that doesn’t load your shell’s .bashrc or .zshrc. This is a classic gotcha that trips up many automation projects.

Step 6: The Crontab – Set It and Forget It

What it does: Tells my computer(Mac mini) to run run-daily.sh automatically at a set time every day.

What is crontab? It’s a Unix job scheduler built into macOS and Linux. You define a schedule using a simple syntax, point it at a script, and the OS handles the rest – forever, or until you delete the entry.

The crontab entry:

0 9 * * * /Users/mdshuvo/yearlyprogress/run-daily.sh

This runs the script at 9:00 AM every day. The five fields represent: minute, hour, day of month, month, day of week. Five stars with the first two set means “every day at 9:00.”

The result: Every morning at 9 AM, without any human action, computer runs the script, generates the video, and uploads it to YouTube. By the time most people are having their morning coffee, the day’s video is live.

What Makes This Project Special

Beyond the individual pieces, what’s interesting here is how each layer is chosen for a specific reason:

• JavaScript for logic – Universal, fast to write, perfect for date manipulation and API calls.
• Gemini for content – Turns a static metric into a story worth watching.
• Remotion for video – Treats video like software, making it reproducible and automatable.
• YouTube Data API for distribution – The last mile, handled entirely in code.
• Bash for orchestration – Lightweight, reliable, and plays perfectly with crontab.
• crontab for scheduling – The simplest possible scheduler, built into the OS.

No overengineering. No cloud infrastructure to manage. No monthly bills for a complex pipeline. Just a small computer, some clever code, and a crontab entry.

What’s Next?

A few directions this project could grow:

• Multiple languages – Generate the same video in Bengali, Spanish, French, etc. to reach broader audiences.
• Milestone alerts – Special videos at 25%, 50%, 75%, and 99% with more elaborate animations.
• Thumbnail generation – Use a canvas library or Puppeteer to auto-generate custom thumbnails.
• Analytics tracking – Pull view counts back from the YouTube API and log the growth over time.
• Multi-channel – Clone the pipeline for a “Day of the Year” or “Days Until New Year” variant.

Try It Yourself

All the core tools used are free or have generous free tiers:

• Remotion – Free for open-source and personal projects
• Google Gemini API – Free tier available
• YouTube Data API v3 – Free with a Google account

If you want to watch the year tick away one percentage point at a time, the channel is live at youtube.com/@ProgressOfYear. A new video drops every morning.

Built with JavaScript, Remotion, Gemini

I’m a solo developer with about five years of experience, mostly outside AI. The last few months I’ve been getting serious about it — reading docs, building small things with Claude, learning how it differs from the web APIs I’m used to.

While I was setting up Anthropic prompt caching for a project, I got stuck on a question I couldn’t easily answer: how do I know it’s actually working? The docs explained the cache_control API and the 90% discount on cached tokens. But the only way to verify a call had hit the cache was to manually parse cache_read_input_tokens from the response usage on every request. Nobody seems to do this.

That gap turned into my first published npm package, prompt-cache-optimizer. This post is what I learned about the four ways prompt caching silently fails, and what the package does to catch them.

What prompt caching is supposed to do

When you call messages.create with a long, stable prefix (system prompt, tool definitions, retrieved documents), Anthropic lets you mark a cache_control breakpoint. On the first call, that prefix gets written to the cache at ~1.25x the normal input rate. On any subsequent call within the cache TTL, the cached tokens are read back at 10% of the input rate.

That’s a 90% discount on whatever portion of your prompt is stable. For a chatbot that re-sends a 10K-token system prompt every turn, this is the difference between a $5K monthly bill and a $500 one.
The math is incredible. The execution is finicky.

The four ways prompt caching silently fails

1. Misplaced breakpoints
   cache_control markers cache everything before them in the request. Put the breakpoint in the wrong place and you cache the wrong things. Worse, the call still succeeds — Anthropic happily processes it, you get a normal response, you just paid full price.

2. Prefix drift across calls
   The cache only hits if the cacheable prefix is byte-identical to what was cached. If you reorder your tools array between calls, or shuffle retrieved documents, or insert a timestamp anywhere in your system prompt — the prefix is different, cache misses, you pay full price.

Worse, you also pay the 1.25x write cost to cache the new (now-different) prefix, which expires in 5 minutes if nothing else hits it. So you’re paying more than you would without caching at all.

1. TTL expiration
   Anthropic recently dropped the default cache TTL from 1 hour to 5 minutes. A lot of setups that “had caching working” started silently regressing — calls that came in 6 minutes apart instead of 4 minutes started missing the cache. Nobody got an error. The bill just went up.

2. No measurement
   The only way to verify any of the above is to parse cache_read_input_tokens and cache_creation_input_tokens from every single response, compute a hit rate, and compare against an expected baseline. Nobody does this. Most teams “set up caching” once, watch the first response come back with high cached tokens, and assume it works forever.

The wrapper I built
I shipped a small TypeScript package called prompt-cache-optimizer that fixes the measurement problem and warns about the other three.

It’s a drop-in wrapper for @anthropic-ai/sdk. Use it exactly like the SDK:

import { CachedAnthropic, placeBreakpoints } from "prompt-cache-optimizer";

const client = new CachedAnthropic({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  warnIfHitRateBelow: 0.6,
});

const { system, messages } = placeBreakpoints({
  system: longSystemPrompt,
  messages: conversation,
  strategy: "after-system",
});

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system,
  messages,
});

console.log(response.cacheInfo);
// {
//   hit: true,
//   cachedTokens: 8420,
//   uncachedTokens: 312,
//   cacheWriteTokens: 0,
//   dollarsSaved: 0.024,
//   dollarsSpent: 0.001
// }

Every response gets a cacheInfo field with the parsed numbers. The client also tracks aggregate stats:

console.log(client.stats());
// {
//   totalCalls: 142,
//   cacheHits: 124,
//   hitRate: 0.873,
//   totalCachedTokens: 1_240_000,
//   dollarsSaved: 3.72,
//   dollarsSpent: 1.41,
// }

And when something looks wrong, it emits passive warnings instead of throwing:

• cache-write-without-read → your cacheable prefix changed call-over-call (the silent failure mode)
• low-hit-rate → rolling cache hit rate dropped below your threshold
• no-cache-control-found → you forgot to mark anything cacheable
• unknown-model → pricing unknown, dollar accounting skipped

Route them anywhere you like:

new CachedAnthropic({
  apiKey,
  onWarning: (event) => logger.warn(event),
});

Real numbers
The included example processes 5 questions reusing a large system prompt. Here’s the actual output:

Five calls. The first writes to cache (cost: a tiny bit more than uncached). Calls 2-5 each hit the cache.

• 80% hit rate (4 hits, 1 miss — the first call always misses since that’s when the cache gets written)
• $0.017 saved on $0.020 spent
• Same workload without caching would have cost $0.037 — a 46% reduction

At higher call volumes the proportions get even better. A chatbot answering 1000 questions/day with a 10K-token system prompt easily hits 70%+ cost reductions.

How big the install is
The package is ~50KB unpacked, has zero runtime dependencies, and treats @anthropic-ai/sdk as a peer dependency. It does not phone home, store payloads, or require an account.

Roadmap
v0.1 is intentionally focused on measurement and explicit helpers. Coming up:

• v0.2 — auto-placement of cache_control breakpoints based on observed prompt stability (no more manual placeBreakpoints())
• v0.3 — safe message/tool reordering to maximize the stable prefix
• v0.4 — OpenAI and Gemini prompt caching support
• v1.0 — persistent stats adapter, middleware mode

Try it

npm install prompt-cache-optimizer @anthropic-ai/sdk

• npm: https://www.npmjs.com/package/prompt-cache-optimizer
• GitHub: https://github.com/leonhail-nell/prompt-cache-optimizer

If you find it useful, a GitHub star is the single biggest signal that helps other developers find it. If it saves you real money on your Anthropic bill, I’d love to hear about it — file an issue or DM me.