@krizaka/brief
The weekly brief: a few figured recommendations, each with one action.
Install
npm install @krizaka/briefA Krizaka product's weekly brief: a few figured recommendations, each with one action — « You have 5 free slots Thursday and Friday (450 $). 14 regulars have not booked for 6 weeks. [Invite them] ».
The product owns its data and its detectors; this block owns the contract, the guards, the ranking and the week.
import { composeBrief, isBriefDue, recommendation, weekOf } from "@krizaka/brief";
const { week } = weekOf(now, shop.timeZone);
const brief = composeBrief({
week,
ctx: snapshot,
detectors: [gaps, pricing, taxProvision], // (ctx) => Recommendation[], pure
guards: [{ name: "consent", check: (item, ctx) => (hasConsent(item, ctx) ? null : "NO_MARKETING_CONSENT") }],
}); // { items: top 3, vetoed: [{ item, guard, reason }], dropped }- Money is integer cents; figures are named integers; the words are the product's messages (keyed by
kind). id=<week>:<kind>:<subject>: the same data gives the same id, so an action is idempotent on it.- Ranking: urgency (
now,week,info), then impact, then id — total and stable. - A guard (the falcon) vetoes with a reason; vetoed items are kept for the audit, never shown.
weekOf(instant, timeZone)andisBriefDue(instant, timeZone, lastSentWeek, { weekday: 1, hour: 7 }): an hourly scheduler asks; a missed Monday still sends later in the week.- No framework, no database, no environment, no wall clock.
Apache-2.0 · Krizaka TS
Exports
The 18 names the package exports, read from its types.
| Name | Kind | What it is |
|---|---|---|
Brief | type | |
BriefAction | type | What the button does: the product executes it (its kind and its payload are its own). |
BriefError | class | |
BriefWeek | type | The brief's week, in the shop's time zone. |
byPriority | function | Urgency, then impact (larger first), then id: a total order, so the same data always gives the same brief. |
composeBrief | function | Runs the detectors, lets the guards veto, ranks, and keeps the top limit (3 by default). |
ComposeInput | type | |
Detector | type | Reads the product's data and returns what it found — pure, deterministic. |
DueRule | type | |
Guard | type | The falcon: refuses a recommendation (consent missing, a rule) by returning its reason, or lets it pass (null). |
isBriefDue | function | Whether the brief is due now: on or after the rule's weekday and hour of this week, and not yet sent this week. |
recommendation | function | Builds a recommendation, checks its money and figures are integers, and gives it its stable id. |
Recommendation | type | |
RecommendationInput | type | |
Urgency | type | |
URGENCY | constant | How soon the owner should act; the ranking reads this before the impact. |
Vetoed | type | |
weekOf | function | The week an instant falls in, for a shop in timeZone (America/Montreal…). |
Package
Changelog
0.1.0
Minor changes
- New block: the weekly brief — recommendation contract (integer money, figures, evidence, assumptions), guards that veto with a reason, a deterministic top-three ranking, and the week in the shop's time zone (
weekOf,isBriefDue). Refs #23.