Drive Jar Shelf from your own code

{ "ok": true,  "data":  { ... } }
{ "ok": false, "error": { "code": "...", "message": "..." } }

{"task": "plan", "verdict": "move", "headline": "...", "goals": [{"id": "g1", "call": "keep", "say": "...", "keep_in": "..."}, ...], "tradeoff": "...", "first_month": "...", "checkpoint": "..."}

{
 "task": "plan",
 "currency": "$",
 "monthly": "$900",
 "goals": "Emergency fund; New laptop; Summer trip",
 "facts": "verdict: fits (rule 3 - every goal gets the monthly it needs)\nmonthly to share: $900; needed by all goals together: $881; spare: $19 a month\ngrowth assumed: 3% a year; targets grow with prices: no\nsaving starts: November 2026; look again in: May 2027\nfunding order: g1, g2, g3 (money goes down this list; each goal gets what it needs while money is left)\ng1: Emergency fund (emergency fund) - target $9,000 by October 2027 (12 months of saving) - the date is fixed - saved so far $4,000 - needs $401 a month - gets $401 a month - call keep - on track for $9,000 by October 2027 - keep it in: easy-access savings\ng2: New laptop (car or big purchase) - target $1,500 by April 2027 (6 months of saving) - the date can move - saved so far $0 - needs $249 a month - gets $249 a month - call keep - on track for $1,500 by April 2027 - keep it in: easy-access savings\ng3: Summer trip (trip or event) - target $2,400 by July 2027 (9 months of saving) - the date can move - saved so far $300 - needs $231 a month - gets $231 a month - call keep - on track for $2,400 by July 2027 - keep it in: easy-access savings"
}

{
 "task": "plan",
 "verdict": "fits",
 "headline": "$900 a month covers the $881 all your goals need, with some left over.",
 "goals": [
  {
   "id": "g1",
   "call": "keep",
   "say": "Emergency fund gets the full $401 a month it needs, keeping it headed toward $9,000 by October 2027.",
   "keep_in": "Easy-access savings keeps it ready for when the fixed date arrives."
  },
  {
   "id": "g2",
   "call": "keep",
   "say": "New laptop gets the full $249 a month it needs, keeping it headed toward $1,500 by April 2027.",
   "keep_in": "Easy-access savings suits it, since the laptop is needed soon."
  },
  {
   "id": "g3",
   "call": "keep",
   "say": "Summer trip gets the full $231 a month it needs, keeping it headed toward $2,400 by July 2027.",
   "keep_in": "Easy-access savings works well, since the trip is coming up soon."
  }
 ],
 "tradeoff": "With $19 a month spare, you could put more into any one goal or leave it as a buffer for now.",
 "first_month": "In November 2026, put $401 into Emergency fund, $249 into New laptop, and $231 into Summer trip.",
 "checkpoint": "Look again in May 2027, or sooner if the monthly amount or a target changes, and go through the plan again."
}

{
 "task": "plan",
 "currency": "£",
 "monthly": "£1,380",
 "goals": "Rainy-day pot; Flat deposit; Lisbon trip",
 "facts": "verdict: move (rule 2 - every fixed date is covered, and Lisbon trip reaches the target later)\nmonthly to share: £1,380; needed by all goals together: £1,430; short by £50 a month\ngrowth assumed: 3.5% a year; targets grow with prices: no\nsaving starts: November 2026; look again in: May 2027\nfunding order: g1, g2, g3 (money goes down this list; each goal gets what it needs while money is left)\ng1: Rainy-day pot (emergency fund) - target £6,000 by August 2027 (10 months of saving) - the date is fixed - saved so far £2,000 - needs £389 a month - gets £389 a month - call keep - on track for £6,000 by August 2027 - keep it in: easy-access savings\ng2: Flat deposit (home deposit) - target £30,000 by December 2028 (26 months of saving) - the date can move - saved so far £8,000 - needs £793 a month - gets £793 a month - call keep - on track for £30,000 by December 2028 - keep it in: easy-access savings\ng3: Lisbon trip (trip or event) - target £2,000 by June 2027 (8 months of saving) - the date can move - saved so far £0 - needs £248 a month - gets £198 a month - call stretch - reaches £1,600 by June 2027 - at £198 a month it reaches the target in August 2027, 2 months later - keep it in: easy-access savings"
}

{
 "task": "plan",
 "verdict": "move",
 "headline": "£1,380 a month falls short of the £1,430 needed together, so the Lisbon trip will take longer.",
 "goals": [
  {
   "id": "g1",
   "call": "keep",
   "say": "Your Rainy-day pot gets the £389 a month it needs and is on track to reach £6,000 by August 2027.",
   "keep_in": "Easy-access savings, so it is there when needed."
  },
  {
   "id": "g2",
   "call": "keep",
   "say": "Your Flat deposit gets the £793 a month it needs and is on track to reach £30,000 by December 2028.",
   "keep_in": "Easy-access savings, keeping it ready for when you need it."
  },
  {
   "id": "g3",
   "call": "stretch",
   "say": "The Lisbon trip gets £198 a month instead of the £248 it needs, reaching its £2,000 target in August 2027, 2 months later than planned.",
   "keep_in": "Easy-access savings, so the money is there when you need it."
  }
 ],
 "tradeoff": "You can accept the Lisbon trip reaching its target 2 months late, or find another £50 a month to keep it on time.",
 "first_month": "In November 2026, put £389 into the Rainy-day pot, £793 into the Flat deposit and £198 into the Lisbon trip.",
 "checkpoint": "Look again in May 2027, or sooner if the monthly amount or a target changes, and run the plan again."
}

{
 "task": "plan",
 "currency": "$",
 "monthly": "$1,300",
 "goals": "Wedding; Emergency fund; Second car",
 "facts": "verdict: short (rule 1 - Emergency fund cannot reach its target by its date with what is left; Second car gets nothing after the goals above)\nmonthly to share: $1,300; needed by all goals together: $1,839; short by $539 a month\ngrowth assumed: 2% a year; targets grow with prices: no\nsaving starts: November 2026; look again in: May 2027\nfunding order: g1, g2, g3 (money goes down this list; each goal gets what it needs while money is left)\ng1: Wedding (trip or event) - target $18,000 by September 2027 (11 months of saving) - the date is fixed - saved so far $5,000 - needs $1,164 a month - gets $1,164 a month - call keep - on track for $18,000 by September 2027 - keep it in: easy-access savings\ng2: Emergency fund (emergency fund) - target $5,000 by December 2027 (14 months of saving) - the date is fixed - saved so far $1,000 - needs $281 a month - gets $136 a month - call top_up - short by $145 a month - at $136 a month it reaches $2,948 of $5,000 by December 2027 - keep it in: easy-access savings\ng3: Second car (car or big purchase) - target $8,000 by June 2028 (20 months of saving) - the date can move - saved so far $0 - needs $394 a month - gets $0 a month - call pause - nothing is left for it after the goals above - nothing is saved for it yet - keep it in: easy-access savings"
}

{
 "task": "plan",
 "verdict": "short",
 "headline": "Your $1,300 a month falls short of the $1,839 all goals need, leaving Emergency fund and Second car off track.",
 "goals": [
  {
   "id": "g1",
   "call": "keep",
   "say": "Wedding's full monthly is being met, leaving it on track to reach $18,000 by September 2027.",
   "keep_in": "Easy-access savings, so the funds are there right when they're due."
  },
  {
   "id": "g2",
   "call": "top_up",
   "say": "Emergency fund gets $136 of the $281 it needs each month, a $145 gap, reaching $2,948 instead of $5,000 by December 2027; add $145 more monthly, or accept a $2,948 target.",
   "keep_in": "Easy-access savings, so the money is ready for its fixed date."
  },
  {
   "id": "g3",
   "call": "pause",
   "say": "Second car isn't getting any money yet because the goals ahead of it are using the full $1,300, and no savings have started for it; funding can begin once one of those goals wraps up or the monthly amount increases.",
   "keep_in": "Easy-access savings, since its date can move, allowing more flexibility."
  }
 ],
 "tradeoff": "Covering the extra $539 each month would bring every goal back on schedule, or Emergency fund and Second car could settle for less by their dates, or simply wait longer.",
 "first_month": "In November 2026, $1,164 goes to Wedding and $136 to Emergency fund, with nothing going to Second car for now.",
 "checkpoint": "Check back in May 2027, or earlier if the monthly amount or any target shifts, and rerun the plan."
}

{
 "task": "plan",
 "currency": "€",
 "monthly": "€900",
 "goals": "University fund; Retirement pot",
 "facts": "verdict: move (rule 2 - every fixed date is covered, and Retirement pot reaches the target later)\nmonthly to share: €900; needed by all goals together: €971; short by €71 a month\ngrowth assumed: 5% a year; targets grow with prices: 2% a year\nsaving starts: November 2026; look again in: May 2027\nfunding order: g1, g2 (money goes down this list; each goal gets what it needs while money is left)\ng1: University fund (education) - target €60,000 in today's money (€79,038 by then) by September 2040 (167 months of saving) - the date is fixed - saved so far €5,000 - needs €287 a month - gets €287 a month - call keep - on track for €79,038 by September 2040 - keep it in: a spread of long-term investments\ng2: Retirement pot (retirement) - target €400,000 in today's money (€713,863 by then) by January 2056 (351 months of saving) - the date can move - saved so far €40,000 - needs €684 a month - gets €613 a month - call stretch - reaches €658,177 by January 2056 - at €613 a month it reaches the target in February 2058, 25 months later - keep it in: a spread of long-term investments"
}

{
 "task": "plan",
 "verdict": "move",
 "headline": "Your plan falls short, with €900 against €971 needed each month, as Retirement pot reaches its target later.",
 "goals": [
  {
   "id": "g1",
   "call": "keep",
   "say": "University fund gets the €287 a month it needs, keeping it on track to reach €79,038 by September 2040.",
   "keep_in": "A spread of long-term investments, with time to absorb market swings."
  },
  {
   "id": "g2",
   "call": "stretch",
   "say": "Retirement pot gets €613 a month instead of the €684 it needs, reaching its target in February 2058, 25 months later than planned.",
   "keep_in": "A spread of long-term investments, with time to absorb market swings."
  }
 ],
 "tradeoff": "Retirement pot reaching its target later works, or add €71 a month to keep it on its original date.",
 "first_month": "In November 2026, put €287 into University fund and €613 into Retirement pot.",
 "checkpoint": "Check back in May 2027, sooner if the amount you save or a goal's target shifts, and rerun the numbers."
}

const K = GoalKit;
const form = K.form({ cur: "$", monthly: "900", rate: "3", infl: "", start: "2026-11", goals: [
  { name: "Emergency fund", kind: "emergency", target: "9000", saved: "4000", by: "2027-10", fixed: true },
  { name: "Summer trip", kind: "trip", target: "2400", saved: "300", by: "2027-07", fixed: false }] });
const built = K.buildInput(form);       // built.facts holds each goal's need, share, call and the verdict
const wire = K.toWire(built.input);     // POST this to /estimate and /run
// then: const reply = K.normalize(K.parseReply(job.output.output));
// K.check(reply, built).notes          // the page's re-check of the reply
// K.md(built, reply, K.title(form))    // the plan as Markdown; K.ics(built) gives monthly reminders

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="paste-your-token-here"   # from https://jar-shelf.skillsafe.ai/tokens.html
api() { # api METHOD PATH [JSON-BODY]
  curl -s -X "$1" "$BASE$2" -H "Content-Type: application/json" \
    ${TOKEN:+-H "Authorization: Bearer $TOKEN"} ${3:+--data "$3"}
}

# a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
TOKEN=$(curl -s -X POST "$BASE/guest" -H "Content-Type: application/json" -d '{"slug":"jar-shelf"}' | jq -r '.data.token')

api GET /me | jq '.data | {subject_type, credits}' 

# input.json: the run input object - {"task": "plan", "currency": "$", "monthly": "$900", "goals": "...", "facts": "...", ...}
# - see the field table
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}' 

KEY="jar-shelf:plan:$(shasum -a 256 input.json | cut -c1-16):a1"
JOB=$(curl -s -X POST "$BASE/run" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $KEY" --data @input.json | jq -r '.data.job_id')
while :; do
  J=$(api GET "/jobs/$JOB"); S=$(echo "$J" | jq -r '.data.status')
  case "$S" in succeeded|failed|cancelled) break;; esac; sleep 2
done
echo "$J" | jq -r '.data.output.output' > reply.json   # one JSON object, the reply contract
echo "$J" | jq '.data | {charged_credits, truncated}' 

# Server-Sent Events: tick/delta events while the job runs, then a final event with the job
curl -N -s -X POST "$BASE/run-stream" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: jar-shelf:plan:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json