Contract

contract wb1!

law for addon lua and web d1. any field change bumps version and needs web importer update same day.

format

wb1! + base64url( raw-deflate( json ) )

no newline, single line. wow editbox high but avoid ws.

• wb0! camp dna share url existing
• wb1! inventory + lockouts this repo v1
• wb2! reserved

one envelope for 1 and 20 so decoder no branch.

envelope v1

{
  "v":1,
  "addon":"1.0.0",
  "exportedAt":1724001234,
  "gameVersion":"12.1.0",
  "interface":120100,
  "bundle":{"count":3,"freshestSeenAt":1724001200,"oldestSeenAt":1723980000},
  "characters":[ ... ]
}

char fields: guid, name, realm slug, faction, class, level, gold, bags[], bank[], reagentBank, warbank root, mail, auctions, currencies[], profs[], cooldowns[], instances[], bosses killed bool in encounter order + name, worldBosses[], keystone{}, runs[], score, weeklyVault map, consumables rolled up phial/potion/food/rune, seenAt stamps.

all _at times unix seconds utc from time(), not ms. null if never seen. web converts.

• bank never opened: free=null, items=[] -> unknown vs empty. ui prints "not opened" not "0 free".
• warbank seenByGuid -> web "by vocnar" credit. payload root + own d1 table avoids repeating 5 tabs x 6 chars (~22kb saved, deflate 32kb window cant fold copies).
• currencies.maxQuantity 0 = no cap, weeklyMax 0 = not weekly.
• consumables derived cache for tonight plan speed. absent = unknown not zero (prevents hard block on 0 phials when we didnt look).
• items inventory only, no equips (api has it). link optional.

impl gotchas fixed in code, doc kept

1. not LibDeflate:EncodeForPrint. that uses own 6-bit alphabet neither base64 nor base64url, swap +/ for -_ cant make it atob readable. addon carries real rfc4648 sec5 encoder.
2. raw deflate not zlib. CompressDeflate emits bare stream no header, DecompressionStream('deflate') rejects. must 'deflate-raw' or pako.inflateRaw.

caps

• 20 chars (dos)
• 1mb decoded not 25kb. measured 1 full 39kb json 8.6kb wire, 6 154/26, 20 474/73. enforced chunk-by-chunk during inflate not after (bomb mitigation).
• validated v==1, array 1..20, each guid+name+seenAt.lastSeen.

wire: libdeflate lvl9 -> base64url strip = -> prefix.

absent vs empty

• section absent -> never seen -> unknown -> grey, not delete
• char missing from bundle -> not gone -> old snapshot aging red
• consumables absent until id table filled -> absent not zero

vectors

• docs/contract/vectors/v1-min.json
• v1-min.wb1
• planned v1-full.json, v1-6.json + ci check-contract-vectors

warbank split

root + warband_bank_cache one row per user. each char seenAt.warbank for dots. seenByName credit line.

versioning

single wb1 version strict. any change bumps prefix and breaks paste if sides disagree. web checks prefix first.

spec lives addon repo, enforced in app warband-import.ts.