Drive Half-Hour Wander from your own code

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

{"task": "wander", "status": "ok", "reason": "", "walk_title": "...",
 "stops": [{"n": 1, "spot": "the flower stall", "pull": 3, "look_for": "...", "keep": "keep"},
           {"n": 2, ...}, ...],
 "keeper": 1, "dropped": [4, 5, 6], "total_minutes": 44, "total_after": 31,
 "verdict": "trim", "verdict_reason": "...", "plan_note": "...", "closing": "..."}

{
 "task": "wander",
 "tone": "curious",
 "budget": "30",
 "loop_minutes": "15",
 "stops": "1 | the corner bakery | 3 | the clock over the door has stopped at ten past four\n2 | the canal footbridge | 4 | ducks wait under it in the mornings\n3 | the little park | 5 | nice\n4 | the library steps | 2 | -",
 "page_facts": "budget | 30\nloop_minutes | 15\nstop_minutes | 14\ntotal_minutes | 29\nover_by | 0\nspare | 1\nverdict | set-off\ngrace | 2\nharm_words | none\nunsafe_words | none\ncapitalised_words | none"
}

{
 "task": "wander",
 "status": "ok",
 "reason": "",
 "walk_title": "bakery footbridge park steps",
 "stops": [
  {
   "n": 1,
   "spot": "the corner bakery",
   "pull": 3,
   "look_for": "See if the stopped clock over the door still shows ten past four.",
   "keep": "keep"
  },
  {
   "n": 2,
   "spot": "the canal footbridge",
   "pull": 3,
   "look_for": "Watch for the ducks that wait under the canal footbridge in the mornings.",
   "keep": "keep"
  },
  {
   "n": 3,
   "spot": "the little park",
   "pull": 2,
   "look_for": "Pick one thing in the little park that catches your eye and look closer.",
   "keep": "keep"
  },
  {
   "n": 4,
   "spot": "the library steps",
   "pull": 1,
   "look_for": "Choose something on the library steps worth a second glance.",
   "keep": "keep"
  }
 ],
 "keeper": 1,
 "dropped": [],
 "total_minutes": 29,
 "total_after": 29,
 "verdict": "set-off",
 "verdict_reason": "Your walk comes to 29 minutes against the 30 you have, so you can set off as planned.",
 "plan_note": "The walk fits as you listed it, with the corner bakery the best stop to linger at.",
 "closing": "Time to head out and enjoy your walk."
}

{
 "task": "wander",
 "tone": "playful",
 "budget": "30",
 "loop_minutes": "18",
 "stops": "1 | the flower stall | 3 | buckets of tulips line the pavement\n2 | the old cinema front | 4 | the sign is missing a letter\n3 | the allotment gate | 6 | someone painted it bright blue\n4 | the cafe on Mill Street | 4 | good\n5 | the post box | 2 | -\n6 | the hill with the bench | 7 | you can see the gasworks from the top",
 "page_facts": "budget | 30\nloop_minutes | 18\nstop_minutes | 26\ntotal_minutes | 44\nover_by | 14\nspare | 0\nverdict | trim\ngrace | 2\nharm_words | none\nunsafe_words | none\ncapitalised_words | Mill, Street"
}

{
 "task": "wander",
 "status": "ok",
 "reason": "",
 "walk_title": "flower stall, cinema front, allotment gate",
 "stops": [
  {
   "n": 1,
   "spot": "the flower stall",
   "pull": 3,
   "look_for": "Look out for the buckets of tulips that line the pavement.",
   "keep": "keep"
  },
  {
   "n": 2,
   "spot": "the old cinema front",
   "pull": 3,
   "look_for": "See if you can spot which letter is missing from the sign.",
   "keep": "keep"
  },
  {
   "n": 3,
   "spot": "the allotment gate",
   "pull": 3,
   "look_for": "Take a moment to spot the bright blue paint on the gate.",
   "keep": "keep"
  },
  {
   "n": 4,
   "spot": "the cafe on Mill Street",
   "pull": 2,
   "look_for": "Choose one thing at the cafe on Mill Street you have not noticed before.",
   "keep": "drop"
  },
  {
   "n": 5,
   "spot": "the post box",
   "pull": 1,
   "look_for": "Pick one thing at the post box you have not noticed before.",
   "keep": "drop"
  },
  {
   "n": 6,
   "spot": "the hill with the bench",
   "pull": 3,
   "look_for": "See the gasworks from the top for yourself.",
   "keep": "drop"
  }
 ],
 "keeper": 1,
 "dropped": [
  4,
  5,
  6
 ],
 "total_minutes": 44,
 "total_after": 31,
 "verdict": "trim",
 "verdict_reason": "Your planned stops add up to 44 minutes against the 30 you have, so this walk needs a trim before you can comfortably set off.",
 "plan_note": "Stepping off: the cafe on Mill Street, the post box and the hill with the bench, bringing your walk down to 31 minutes.",
 "closing": "Trim it down and you are ready to wander."
}

{
 "task": "wander",
 "tone": "calm",
 "budget": "45",
 "loop_minutes": "20",
 "stops": "1 | the pond | 4 | herons stand on the far bank\n2 | the bus shelter mural | 2 | a painted fox on the back wall\n3 | the second-hand bookshop | 6 | -",
 "page_facts": "budget | 45\nloop_minutes | 20\nstop_minutes | 12\ntotal_minutes | 32\nover_by | 0\nspare | 13\nverdict | room-to-spare\ngrace | 2\nharm_words | none\nunsafe_words | none\ncapitalised_words | none"
}

{
 "task": "wander",
 "status": "ok",
 "reason": "",
 "walk_title": "pond mural bookshop",
 "stops": [
  {
   "n": 1,
   "spot": "the pond",
   "pull": 3,
   "look_for": "See the herons that stand on the far bank.",
   "keep": "keep"
  },
  {
   "n": 2,
   "spot": "the bus shelter mural",
   "pull": 3,
   "look_for": "Look for the painted fox on the back wall.",
   "keep": "keep"
  },
  {
   "n": 3,
   "spot": "the second-hand bookshop",
   "pull": 1,
   "look_for": "Pick whatever at the second-hand bookshop catches your attention.",
   "keep": "keep"
  }
 ],
 "keeper": 2,
 "dropped": [],
 "total_minutes": 32,
 "total_after": 32,
 "verdict": "room-to-spare",
 "verdict_reason": "Your walk comes to 32 minutes against the 45 you have, leaving room to spend longer at one stop.",
 "plan_note": "You have 13 spare minutes to linger at the bus shelter mural, the best stop on this walk.",
 "closing": "Take it slow and enjoy the extra time."
}

{
 "task": "wander",
 "tone": "playful",
 "budget": "30",
 "loop_minutes": "12",
 "stops": "1 | the old railway tracks behind the station | 5 | you can walk along them to the next town\n2 | the newsagent | 2 | -",
 "page_facts": "budget | 30\nloop_minutes | 12\nstop_minutes | 7\ntotal_minutes | 19\nover_by | 0\nspare | 11\nverdict | room-to-spare\ngrace | 2\nharm_words | none\nunsafe_words | railway tracks\ncapitalised_words | none"
}

{
 "task": "wander",
 "status": "declined",
 "reason": "This app only builds walks from places that are safe and fine to walk and look at - try an everyday list of streets, shops or parks instead.",
 "walk_title": "",
 "stops": [],
 "keeper": 0,
 "dropped": [],
 "total_minutes": 0,
 "total_after": 0,
 "verdict": "",
 "verdict_reason": "",
 "plan_note": "",
 "closing": "Thanks for sharing - wishing you a lovely day."
}

const K = WanderKit, D = WalkDraw;
const built = K.buildInput({ tone: "curious", budget: "30", loop: "15",
  stops: "the corner bakery | 3 | the clock over the door has stopped
the little park | 5 | nice" });
built.parsed.stops;              // [{n: 1, spot: "the corner bakery", minutes: 3, note: "the clock over the door has stopped"}, ...]
built.sums;                      // {loop: 15, add: 8, total: 23, budget: 30, verdict: "set-off", ...}
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.check(reply, built).plan                           // the best stop, the trim and the total after, worked by the page
// D.svg({ budget: 30, loop: 15, stops: [{ n: 1, spot: "the corner bakery", minutes: 3, keep: true, keeper: true }] })   // the dial and stick as SVG
// K.md(built, reply)                                   // the walk card as Markdown

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="paste-your-token-here"   # from https://half-hour-wander.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":"half-hour-wander"}' | jq -r '.data.token')

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

# input.json: the run input object - {"task": "wander", "tone": "curious", "budget": "30", "loop_minutes": "15", "stops": "1 | spot | 3 | note\n2 | spot | 4 | -", "page_facts": "budget | 30\n..."} - see the field table
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}' 

KEY="half-hour-wander:wander:$(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: half-hour-wander:wander:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json