[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8},"actionData","errors","root",{"_105":106,"_107":108},"routes/embed.x.$handle.$name.$",{"_9":10,"_11":12,"_13":14,"_15":16,"_17":18,"_19":20,"_21":-5},"handle","plusjade","name","source-sdk","path","sdk/contract.ts","project",{"_22":48,"_11":12,"_35":49,"_50":-5,"_51":44,"_52":53,"_54":53,"_55":56,"_57":-5,"_58":59,"_60":-5,"_61":44,"_62":-5,"_63":-5,"_64":65,"_66":67,"_68":-5,"_69":-5,"_70":-5,"_71":-5,"_72":73,"_74":73,"_75":76,"_77":76,"_78":76,"_79":73,"_80":73,"_81":82,"_83":84,"_85":86,"_87":44},"file",{"_22":23,"_11":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":36,"_37":38,"_39":40,"_41":42,"_43":44,"_45":-5,"_13":46},"permalink","https://www.val.town/x/plusjade/source-sdk/code/sdk/contract.ts","extension","id","d3ca80ab-fd3f-48bd-971a-02398cda1e37","contract.ts","fileId","01a07fdc-4571-76ba-9009-e9aa49b6faf9","parentId","01a07fdc-4570-7068-b849-a2f0d645edd4","branchId","18439a77-9162-403a-ad4d-e69e4496f0d9","branchVersion",12,"latest",true,"createdAt",["D",1789077285831],"version",2,"fileType","script","content","// Temporal item contract, result helpers and guards shared by every source.\n// Runtime imports must stay inside sdk/; tools/sdk-check.ts enforces the boundary.\n// Source authors start at ../README.md and import ../mod.ts.\n\nexport const PROTOCOL_VERSION = 1;\n\n// The longest window `items()` will accept. Its real job is catching a\n// mixed-unit bug — one bound in seconds, the other in milliseconds — which\n// neither bound's own magnitude check can see, because a millisecond value is\n// still a plausible far-future second value.\nexport const MAX_ITEM_SPAN_SECONDS = 30 * 24 * 60 * 60;\n\n// The one payload shape every source produces, whatever it is a source of.\n// There is no away/home, no score, no domain — a source decides what to *say*\n// and the client renders these fields blind.\n//\n// `caption: null` is a protocol value, not an absent field: it tells the\n// client to format `startsAt` itself as a local time. A source that wants no\n// caption at all still sends null — and a source whose events are only\n// day-precise must NOT send null, or the client will render a fabricated\n// clock time (see ../README.md, \"Day-granular events\").\n//\n// An item is a WINDOW, not an instant: `[startsAt, expiresAt)`. Both bounds\n// are required and `expiresAt` must be strictly greater, so every consumer can\n// derive `phase()` from the clock alone with no further reads. A genuinely\n// instantaneous event publishes a one-second window rather than omitting the\n// bound; a nullable expiry would classify as already-expired under `now >\n// null` and vanish from `WHERE expires_at > :now`, both silently.\n//\n// `expiresAt` is an ESTIMATE and is never displayed. Sources without live\n// ingest publish a typical duration; a longer-than-typical event reads as\n// expired while still running, which is bounded and acceptable. Rendering it\n// as a fact (\"ends at 4:15 PM\") is not.\n//\n// Both are Unix EPOCH SECONDS, not milliseconds. This is the single most\n// common implementation mistake: sending ms decodes on the client as a date\n// ~57,000 years out, and no type-level check catches it because both are\n// numbers. `items()` below rejects values too large to be a plausible\n// second-precision time, and rejects an implausible span — together those\n// catch the mixed-unit case, but not two consistently-wrong bounds.\nexport type Item = {\n id: string;\n mainText: string;\n subText: string;\n caption: string | null;\n emphasized: boolean;\n startsAt: number;\n expiresAt: number;\n /**\n * @deprecated Transitional duplicate of `startsAt` for consumers that\n * predate the window. Sources emit it during the migration window only;\n * drop it once no old client remains.\n */\n timestamp?: number;\n};\n\n// Where an item sits relative to the clock. The vocabulary is deliberately\n// domain-free: the protocol says `current`, and the SOURCE decides whether\n// that reads as \"LIVE\" or \"PEAK\". These values are state, not display text,\n// and must never reach a user.\nexport type Phase = \"upcoming\" | \"current\" | \"expired\";\n\n// The single derivation every consumer uses. Route phase decisions through\n// this rather than comparing bounds inline, so one definition of \"current\"\n// exists across the source, the parent and any future consumer.\nexport function phase(item: Pick, now: number): Phase {\n if (now < item.startsAt) return \"upcoming\";\n return now < item.expiresAt ? \"current\" : \"expired\";\n}\n\n// Builds a window from a start plus a duration the SOURCE owns. The SDK has\n// no domain model, so it will never supply the duration itself — pass a named\n// constant with a rationale, not a bare number.\n//\n// Throws rather than rejecting: a non-positive or non-finite duration is a bug\n// in the source, not a caller's bad input.\nexport function windowFrom(startsAt: number, durationSeconds: number): Pick {\n if (!Number.isFinite(startsAt)) throw new Error(\"windowFrom: startsAt must be finite\");\n if (!Number.isFinite(durationSeconds) || durationSeconds < 1) {\n throw new Error(\"windowFrom: durationSeconds must be at least 1 second\");\n }\n return { startsAt, expiresAt: startsAt + durationSeconds };\n}\n\nexport function record(value: unknown): value is Record {\n return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction instant(value: unknown): value is number {\n return typeof value === \"number\" && Number.isFinite(value) && Math.abs(value) <= 8640000000000;\n}\n\n// The gate every source's output passes through before it leaves the val.\n// serveSource applies this automatically, so an implementer cannot ship a\n// malformed item by forgetting to check: a failing read returns 502\n// invalid_source_output from this source rather than failing composition at\n// the parent, where nothing would name which source produced the bad item.\n//\n// `id` must be unique within one response and stable across polls of the same\n// underlying thing; the parent namespaces it per source, so it only has to be\n// unique here.\n//\n// The window rules are strict `>` and a bounded span. Strict, because an\n// accidental `expiresAt === startsAt` would reintroduce the zero-duration case\n// the required bound exists to eliminate; bounded, because a span outside\n// MAX_ITEM_SPAN_SECONDS almost always means one bound was written in\n// milliseconds.\nexport function items(value: unknown): value is Item[] {\n return Array.isArray(value) && value.every(v => record(v)\n && typeof v.id === \"string\" && v.id.length > 0\n && typeof v.mainText === \"string\" && typeof v.subText === \"string\"\n && (v.caption === null || typeof v.caption === \"string\")\n && typeof v.emphasized === \"boolean\"\n && instant(v.startsAt) && instant(v.expiresAt)\n && (v.expiresAt as number) > (v.startsAt as number)\n && (v.expiresAt as number) - (v.startsAt as number) <= MAX_ITEM_SPAN_SECONDS\n && (v.timestamp === undefined || instant(v.timestamp)))\n && new Set(value.map(v => v.id)).size === value.length;\n}\n\n// How a source hands a rejection back to the SDK instead of throwing. One\n// type for both settings parsing and write operations, so there is a single\n// failure idiom to learn.\n//\n// `error` becomes the protocol's error code verbatim, so it should be a\n// stable snake_case token the parent can branch on (\"unknown_selection\"), not\n// a sentence. `status` defaults to 400 — the codes worth overriding are 404\n// for a thing that does not exist and 422 for a well-formed request this\n// source will not perform.\n//\n// Returning a rejection is not the same as throwing: a throw is a bug and\n// surfaces as a 500, while a rejection is this source correctly refusing.\nexport type Result =\n | { ok: true; value: T }\n | { ok: false; error: string; status?: number };\n\nexport function accept(value: T): Result {\n return { ok: true, value };\n}\n\nexport function reject(error: string, status = 400): Result {\n return { ok: false, error, status };\n}\n","deleted",false,"label",[47,24],"sdk","eb040b9b-c2e1-4e49-ab5b-059a85d1d61b",["D",1788851529508],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","Shared temporal source protocol and authoring SDK","imageUrl","userId","b0a8da26-58e7-4d19-8b5c-eedf487df9a9","pinnedFileId","pinPreview","pinMigrated","screenshotVersion","likeCount",0,"orgId","5a10edca-919b-4a78-babb-71908f69af93","tursoName","tursoHostname","tursoMeasuredAt","pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_9":10,"_104":100},"org",{"_9":10,"_98":-5,"_99":100,"_58":59,"_101":102,"_103":44},"branch",{"_37":88,"_11":89,"_22":30,"_90":48,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":-5,"_96":12,"_97":10},"isOwned",16,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","displayName","avatar","https://img.clerk.com/eyJ0eXBlIjoicHJveHkiLCJzcmMiOiJodHRwczovL2ltYWdlcy5jbGVyay5kZXYvb2F1dGhfZ2l0aHViL2ltZ18yVHpab25kTlBTM3M3WmpCa3NMSTd5akVwWksuanBlZyJ9","tier","free","canRestrictVals","profileImageUrl","ctx",{"_81":-5,"_138":139,"_140":141,"_142":143,"_144":44,"_145":44,"_146":44,"_147":34,"_148":-5,"_149":-7,"_150":-7,"_151":65,"_152":44,"_153":44,"_154":-5,"_155":44,"_156":44,"_157":44,"_158":-5},"ENV",{"_109":110,"_111":112,"_113":89,"_114":115,"_116":117,"_118":119,"_120":121,"_122":123,"_124":125,"_126":127,"_128":129,"_130":131,"_132":133,"_134":135,"_136":137},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town","orgs",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]