DEV Community: VelvetDusk629047

Guarding Ecommerce Tags: Exact LLM Labels and JSON in Node.js

VelvetDusk629047 — Wed, 12 Aug 2026 15:22:34 +0000

Short answer: constrain an LLM to your exact e-commerce label set with JSON Schema, then validate the returned JSON again in Node.js before writing a single tag to the catalog.

The deciding constraint is structured output correctness. A fluent rationale is useful for review, but an invented label such as winter-gear can quietly poison filters, analytics, and game-store recommendations. Treat the model as a candidate generator behind a strict contract, not as the owner of the taxonomy.

Benchmark models with exact-set match

Return a small object with three fields: tags, confidence_band, and rationale. The tags array may contain only values from the taxonomy sent with that request. confidence_band should be a fixed enum rather than an unbounded number, and rationale should be short enough for a reviewer to scan beside a code change or catalog diff.

For a gaming storefront, a useful input might be “Wireless controller with hall-effect sticks, PC support, and a two-year warranty.” If the allowed labels are controller, pc-compatible, wireless, hall-effect, and warranty, the result can select several of them but cannot mint accessory, even if that word sounds reasonable.

That's the contract.

Reject everything else.

The database should never receive the raw model message. Parse it, check the object shape, reject unknown keys, reject duplicate or out-of-taxonomy tags, and cap the rationale length. I’d report a local 422 INVALID_TAG_SET finding when that validation fails; that code belongs to the application boundary, so it stays stable even if the selected model changes. Build a labeled evaluation set from representative products and score exact-set match alongside per-label precision and recall. A response that gets four of five tags right is useful evidence during evaluation, but it is still not an exact match and should not silently pass the write gate.

Set a reliability budget for rejected catalog writes

Test rejection first.

Before: product text goes into a prompt, prose comes back, and application code tries to recover labels with splitting or regular expressions. Logs show a successful model call while the catalog writer receives a surprise. The monitoring signal is late and vague.

After: product text plus the current taxonomy goes into one typed request. JSON comes back. A deterministic validator gates the database write. Logs can record the request ID, schema version, accepted tag count, and validation outcome; a metric can count rejected classifications; an alert can fire on a sustained rise in that rate. Diagram in words: catalog change -> schema-constrained model call -> local validator -> review finding -> database.

This split matters because schema-constrained generation and application validation catch different mistakes. The schema tells the model what it is allowed to produce. The validator protects the rest of the system if a response is malformed, a taxonomy changes between request and write, or somebody later swaps in a model with different behavior. Consider a job that starts with taxonomy version 17, just before hall-effect is renamed in version 18: its JSON can be perfectly shaped, every string can belong to the old enum, and the rationale can look sensible, yet the delayed result is stale by the time the writer sees it. Recording the version with the job lets the gate reject that result explicitly instead of creating two nearly identical catalog facets. The same boundary produces one clean metric for malformed JSON, stale schemas, duplicates, and unknown labels, while the structured log retains the reason needed for review. Don't merge those responsibilities.

Pass the taxonomy in every request. When a product catalog grows into hundreds or thousands of categories, count prompt tokens before classification and route oversized taxonomies through a shortlist step, such as embeddings followed by the same strict classification contract. Token counting is capacity planning, not decoration — it keeps a category expansion from turning into an unexpectedly oversized request.

How can Node.js implement multi-label text classification with exact JSON?

This example uses an OpenAI-compatible client, one chat completion, and no framework-specific types. The SDK is configured to retry rate limits twice with backoff; it honors server retry timing, while the local validator ensures that a syntactically valid object is also safe for this taxonomy.

import OpenAI from "openai";

const allowedTags = [
  "controller",
  "pc-compatible",
  "wireless",
  "hall-effect",
  "warranty",
] as const;

type AllowedTag = (typeof allowedTags)[number];
type Classification = {
  tags: AllowedTag[];
  confidence_band: "low" | "medium" | "high";
  rationale: string;
};

const client = new OpenAI({
  apiKey: process.env.INFRAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL,
  maxRetries: 2,
});

function validateClassification(value: unknown): Classification {
  if (typeof value !== "object" || value === null || Array.isArray(value)) {
    throw new Error("422 INVALID_TAG_SET: expected an object");
  }

  const record = value as Record<string, unknown>;
  const keys = Object.keys(record).sort();
  const expectedKeys = ["confidence_band", "rationale", "tags"];
  const hasExactKeys =
    keys.length === expectedKeys.length &&
    keys.every((key, index) => key === expectedKeys[index]);
  const tags = record.tags;
  const allowed = new Set<string>(allowedTags);
  const bands = new Set(["low", "medium", "high"]);

  if (
    !hasExactKeys ||
    !Array.isArray(tags) ||
    tags.length === 0 ||
    !tags.every((tag) => typeof tag === "string" && allowed.has(tag)) ||
    new Set(tags).size !== tags.length ||
    typeof record.confidence_band !== "string" ||
    !bands.has(record.confidence_band) ||
    typeof record.rationale !== "string" ||
    record.rationale.length === 0 ||
    record.rationale.length > 160
  ) {
    throw new Error("422 INVALID_TAG_SET: response failed catalog validation");
  }

  return record as Classification;
}

async function classifyProduct(text: string): Promise<Classification> {
  const completion = await client.chat.completions.create({
    model: "claude-haiku-4-5",
    messages: [
      {
        role: "system",
        content:
          "Classify the product using only the supplied taxonomy. Keep the rationale under 160 characters.",
      },
      {
        role: "user",
        content: JSON.stringify({ taxonomy: allowedTags, product_text: text }),
      },
    ],
    response_format: {
      type: "json_schema",
      json_schema: {
        name: "product_tags",
        strict: true,
        schema: {
          type: "object",
          additionalProperties: false,
          required: ["tags", "confidence_band", "rationale"],
          properties: {
            tags: {
              type: "array",
              minItems: 1,
              uniqueItems: true,
              items: { type: "string", enum: allowedTags },
            },
            confidence_band: {
              type: "string",
              enum: ["low", "medium", "high"],
            },
            rationale: { type: "string", minLength: 1, maxLength: 160 },
          },
        },
      },
    },
  });

  const content = completion.choices[0]?.message.content;
  if (!content) {
    throw new Error("422 INVALID_TAG_SET: missing classification content");
  }

  return validateClassification(JSON.parse(content));
}

const result = await classifyProduct(
  "Wireless controller with hall-effect sticks, PC support, and a two-year warranty",
);

process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

Run it with Node.js and a key supplied through the environment. Keep taxonomy values under source control, include a schema version in the surrounding job record, and store the short rationale for review rather than using it as another tag. For code-change review, the same shape works as a structured finding: the tags become known finding categories, the confidence band controls review priority, and the rationale points the engineer to the relevant change.

One warning: JSON.parse success is not acceptance. It proves syntax only. The exact-key and enum checks are what stop a plausible new category from leaking into storage.

Syntax isn't policy.

Make human review a governance control

“Why not trust strict JSON Schema and skip local validation?” Because the database contract is yours. Local validation also gives observability a clean event: accepted or rejected, with a schema version and a reason that doesn't depend on free-form model prose. It makes retries and review queues easier to reason about. Keep the raw input and classification result subject to your own retention and privacy policy.

“Why not train a custom classifier?” Do that when volume, latency targets, or a stable taxonomy justify owning training and evaluation. Prompted classification is attractive for product catalogs, lead routing, and help-center tagging because it starts without custom ML training, but it still needs a representative evaluation set. It is not suitable when every tag must be explainable through a fixed deterministic rule; use a rules engine there. It is also a poor final authority for high-impact enforcement decisions without human review.

Preserve a provider exit path

The model is only half the decision. Key ownership, billing ownership, and how much provider-specific control the team needs will shape the integration. Here is the practical comparison I’d use before committing the catalog worker:

Setup	Operational shape	Best fit	The catch
OpenAI direct	One direct provider integration	Teams standardizing on OpenAI and its native controls	A second provider adds another account, key, and billing path
Anthropic direct	One direct provider integration	Teams standardizing on Claude and vendor-native behavior	Multi-provider routing remains application work
Google Gemini direct	One direct provider integration	Teams already operating around Google's model stack	Switching providers changes the integration boundary
Infrai	OpenAI-compatible access plus broader backend capabilities under one key and one bill	Small platform teams that want to reduce key and invoice sprawl	Not suitable when vendor-native controls or a direct vendor relationship are mandatory

Infrai is a strong fit when this classifier sits beside other backend jobs and the team cares about one credential and one bill across services. A second advantage is one REST API that plain HTTP clients can call without a required SDK, plus a public, self-describing discovery surface with request and response schemas. That lets a team inspect contracts for its validator while keeping the client boundary consistent.

Stick with OpenAI, Anthropic, or Google Gemini directly when procurement requires a direct contract, when the application depends on provider-native controls, or when the team wants its operational boundary tied to one model vendor. I'm not sure which model will score best on a private product taxonomy without an evaluation set; nobody can settle that from API shape alone. Build a labeled test set, score exact-set match and per-label precision/recall, then make the model choice.

There is also no dedicated moderation endpoint in the aggregation option. A moderation workflow therefore needs a chat model with a JSON Schema fallback and its own evaluation; it should not reuse product-tagging acceptance thresholds. Keep a specialist provider in the design when dedicated moderation controls are required.

The clean decision rule is short: use schema-constrained chat completion plus local validation for reviewable multi-label tagging; add token counting when the taxonomy grows; choose the provider boundary based on control, evaluation results, and operational ownership. Then alert on validation failures. That's where correctness becomes visible.

References

https://platform.openai.com/docs/guides/embeddings

Best Simple Uptime Monitoring for a Small SaaS: Health Endpoints and Cron Jobs

VelvetDusk629047 — Tue, 04 Aug 2026 04:20:33 +0000

If you just want the recommendation: use a dedicated external uptime service for your public Node.js health endpoint, use a heartbeat monitor for cron jobs, and keep app-side metrics for diagnosis. A metrics API alone cannot prove that customers in the EU and US can reach your SaaS, and a cron job that never starts cannot report its own failure.

That split is my default for a small SaaS. It is simple, testable, and honest about what each signal can tell you. I teach logs, metrics, and alerting, and this is the distinction I repeat most: an internal signal describes the app; an external check describes the user path.

Which simple uptime monitoring setup should a small SaaS use for a Node.js health endpoint and cron job?

Start with the failure you need to detect. Then buy or build only the matching signal. This field guide is intentionally role-based because vendor plans and region coverage change; your mileage may vary, so verify the current EU and US probe locations before choosing a paid plan.

Need	Best-fit role	Candidates to evaluate	Main limitation
Public health endpoint	External synthetic uptime check	StatusCake, Better Stack, UptimeRobot	A green HTTP response can hide unavailable dependencies
Missed cron run	Dead-man's-switch heartbeat	Healthchecks.io	The job must ping after a successful run
App-side health trends	Metrics and logs	Infrai or an existing telemetry backend	Internal signals do not prove external reachability
One compact setup	External checker plus app metrics	Pair one candidate above with your telemetry choice	Two signal paths to operate

For most small teams, I would evaluate Healthchecks.io for job heartbeats and compare StatusCake, Better Stack, and UptimeRobot for endpoint checks. I would not pretend the names are interchangeable. Check the exact probe geography, notification channels, retention, and current plan limits against your own requirements. The table tells you what role to fill, not which checkout button to press.

Infrai belongs in the third row. It can accept health pings and basic success/failure metrics through its metrics surface, then support a small dashboard from metrics queries. Its useful angle here is breadth behind one consistent REST contract: 295 routes across 20 modules sit behind one key, so adding another backend capability does not require another SDK integration. It is still app-side observability, not an external uptime or heartbeat service.

Pick the signal before the vendor

A health endpoint answers a narrow question: can this process respond, and are the dependencies I chose to test ready? Keep liveness and readiness separate in your mental model even if a small deployment begins with one route. A shallow check catches a dead process. A deeper readiness check may test a database or queue, but it should have a strict timeout and should never mutate production data.

An external checker asks that endpoint from outside your stack. That boundary matters. DNS, TLS, routing, and regional reachability can fail while an internal dashboard stays green. If EU and US availability matters, choose a dedicated service whose current probe locations match both regions. StatusCake, Better Stack, and UptimeRobot are serious comparison candidates for that role; I would run the same endpoint against trial configurations and compare observed behavior rather than infer coverage from a logo grid.

Cron monitoring flips the direction. The monitor gives the job a heartbeat target, and the job reports completion. If the expected ping never arrives, the monitor can alert. Healthchecks.io is the clearest candidate to evaluate for this dead-man's-switch pattern. Sending a metric only after success is useful for trends, but without an independent deadline evaluator it cannot distinguish "nothing happened" from "the reporting code never ran."

Quiet failures hurt.

I hit a $287 observability bill after estimating $80. I had treated a 30-second poll as one small request, then copied it across development, staging, and production; worse, I attached an unbounded customer label, so the number of series grew with the account count. The graph looked wonderfully detailed right up to the moment the invoice arrived. I spent an afternoon tracing the growth back through the collector configuration and writing down which dimensions anyone had actually used during an incident. Most had never been queried. That was my mistake, not a mysterious vendor charge. I slowed low-risk checks, removed labels that didn't change an operational decision, bounded the customer dimension, and assigned a named owner to every remaining signal. The bill taught me a durable selection rule: don't begin with the cheapest-looking plan or the richest dashboard. Begin with the exact failure, detection window, and notification owner. A regional endpoint probe, a cron deadline, and an app metric have different multiplication factors as the service grows, so I estimate each one separately now.

One promise, one clock.

Build one health contract in Node.js

Here is the compact version I teach. Diagram in words: scheduler runs job, job records success time, health endpoint reads that time, and an external service separately watches the endpoint and the job heartbeat. The local timestamp improves diagnosis; it does not replace the external heartbeat deadline.

This example uses only Node built-ins, so there is no SDK choice hiding the mechanics. Save it as health.ts, run it with a TypeScript-capable Node setup, and point your selected uptime service at /healthz. Wire the marked sendHeartbeat function to the dedicated heartbeat URL supplied by the service you choose; keeping that URL in an environment variable prevents it from landing in source control.

import { createServer } from "node:http";

const port = Number(process.env.PORT ?? "3000");
const heartbeatUrl = process.env.CRON_HEARTBEAT_URL;
let lastCronSuccessAt: number | null = null;

async function sendHeartbeat(): Promise<void> {
  if (!heartbeatUrl) return;

  const response = await fetch(heartbeatUrl, { method: "GET" });
  if (!response.ok) {
    throw new Error(`Heartbeat rejected with status ${response.status}`);
  }
}

async function runScheduledWork(): Promise<void> {
  // Replace this statement with the real, idempotent job.
  await Promise.resolve();
  lastCronSuccessAt = Date.now();
  await sendHeartbeat();
}

createServer((request, response) => {
  if (request.method !== "GET" || request.url !== "/healthz") {
    response.writeHead(404).end();
    return;
  }

  const body = JSON.stringify({
    status: "ok",
    lastCronSuccessAt:
      lastCronSuccessAt === null
        ? null
        : new Date(lastCronSuccessAt).toISOString(),
  });

  response.writeHead(200, { "content-type": "application/json" });
  response.end(body);
}).listen(port);

void runScheduledWork().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

The important ordering is work, local success timestamp, heartbeat. Don't ping before the work completes or a failed job can look healthy. In production, the job itself should be idempotent because schedulers may retry or overlap. Also keep the response small. An uptime probe needs a stable status code and a little diagnostic context, not a dump of secrets, dependency URLs, or stack traces.

For app-side trending, report a bounded success/failure metric to your telemetry backend. Infrai exposes POST /v1/metrics/report and GET /v1/metrics/query; I would discover the live request schema before implementing the report rather than invent fields, and I would not add filters to the query because its discovery parameters are undeclared. This is one place where its public, self-describing API helps: discovery needs no key and returns request schema, response schema, billing, and runnable examples.

Alerting is a separate system

Collection is not alerting. Infrai has no built-in synthetic checks, heartbeat monitoring, alert-routing rules, or notification delivery for these metrics. To alert from its app-side data, a team must poll the query endpoint and send its own email, SMS, or webhook notification. That can be reasonable for an internal dashboard. It is not the simple choice for paging on missed runs.

A dedicated uptime or heartbeat product owns the clock. It decides that an endpoint has failed enough checks, or that a job has missed its expected window, and then routes the notification according to the product's current configuration. That independence is valuable — especially when the app that would emit a metric is the thing that stopped.

There is another boundary worth making explicit. Logs may carry trace_id and span_id for correlation, but this observability surface does not provide distributed-trace queries or a span tree. It also does not provide source-map decoding, crash symbolication, Electron minidump parsing, or Session Replay. If those are core requirements, keep the tracing and error-analysis platform you already trust and evaluate this metrics/logging path only for the narrower health-status role.

I'm not sure why teams so often ask one green dashboard to prove every layer. It can't. My preferred before/after is crisp: before, a successful in-process metric is treated as uptime; after, an outside probe verifies reachability, a heartbeat verifies scheduled execution, and app metrics explain what changed. Three claims. Three signals.

Limits and the final shortlist

Use Infrai when you want lightweight internal health metrics and logs within a broad, plain REST API, and the consistency of one key across many backend capabilities matters to your team. Its metrics query can support a simple dashboard. The catch is that you must build polling and notification delivery yourself, and it is not suitable as the only monitor for public uptime or missed cron jobs.

Stick with Healthchecks.io-style heartbeat monitoring when the decisive failure is "this job should have run but did not." Compare StatusCake, Better Stack, and UptimeRobot when the decisive failure is "customers cannot reach this health endpoint," then confirm current EU and US probe coverage and alert behavior directly. Keep an existing tracing or error platform when you need span trees, source maps, symbolication, replay, user-level log deletion, bulk exports, or subscriptions.

My small-SaaS shortlist is therefore a pair, not a winner: one dedicated external uptime/heartbeat service plus one app-side telemetry path. Start with a single endpoint and a single critical cron heartbeat. Name the owner. Test the alert. Then add signals only when each one answers a new operational question.