@supersuit/suggest-a-change 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.1.9 (2026-10-17)
+
+- **The door helpers are exported from `./server`.** `json`, `signIn`, `notFound`, `cappedText` and `peek` are what an app's own route wrapper needs to answer as the handlers do and never read a body past a cap. Two apps (cofounders-template, first-years-template) carried byte-identical copies; they now import these. The handlers use the same functions, so there is one copy of the door. No behaviour change.
+
 ## 0.1.8 (2026-10-17)
 
 - **The news reaches a person whose entry sits in a menu.** In the Cofounders and Us apps the entry lives in a three-dot menu that stays closed and remounts it on every open, so the 0.1.7 dot was never seen and the toast was drawn inside the closed menu. New in `./client`: `<SuggestNews adapters>`, mounted once at the root, shows the toast with no entry on screen (and keeps the outbox moving); `useSuggestNews(adapters)` returns `{ moved }` for the menu's trigger; `<SuggestDot adapters moved>` draws the entry's dot there (nothing at 0), and the class `sac-dot-host` gives the trigger the `position: relative` it needs. The toast is once per page load and account however many times the entry mounts, whichever of these asks first. `<SuggestEntry>` keeps its own dot and, alone, behaves as in 0.1.7.

package/README.md

@@ -212,6 +212,8 @@ A client adapter's `uploadPart` asks `upload-url`, PUTs the bytes straight to st
 
 The role stored on a report comes from the signed-in member and the `maintainers` list. A `who` sent by the phone is ignored; a report carrying `timeline`, `status`, `plan` or `decision` is refused. `sniffType(firstBytes)` names a file by its bytes (jpeg, png, webp, heic/heif, gif, mp4/mov, webm, m4a/aac, mp3, wav, ogg/opus; anything else is `null`) and `finalize` refuses a file whose bytes are not the type it was declared as.
 
+**A wrapper of your own answers in the module's words.** When an app's route has to check a caller or read one field before the handler runs, it uses the same door the handlers use: `json(status, body)` (JSON, never cached), `signIn()` (401) and `notFound()` (404), `cappedText(req, cap)` (the body as text, or a 413 `Response` past `cap` bytes, by the declared length and again by counting what arrives; no body reads as `""`), and `peek(text)` (a JSON object, or `{}` for anything else, for reading one field while the module judges the body). Copying these into an app made a second door that could drift from the first.
+
 **Settle carries a revision.** `agentList` gives each report a `revision`; the Mac sends it back with `settle`, and the store settles only if the report still has exactly that content. A follow-up or file that arrived in between answers 409 `stale`, drops the claim, and the next list offers the report with the addition. Adapters compute the same value with `reportRevision`.
 
 **The collector MUST verify.** `agentFile` answers the verified `bytes` and `sha256`; a Mac that downloads the link must check both before it trusts the file.

package/dist/server/handlers.js

@@ -10,6 +10,7 @@
 import { END, FLOW, STATUSES, TOLD, isAcceptedMedia, isReportId, mayMove, meaningFor, validateReport, wordsFor } from '../contract.mjs';
 import { effectiveLimits } from './rate.js';
 import { ACCEPTED_TYPES, canonicalType, sameType } from './sniff.js';
+import { json, notFound, signIn, cappedText } from './http.js';
 /** What a collector saw of a report: its verified files and its follow-ups. A store computes this from its own copy,
  *  inside `settle`, and settles only when it equals what the collector says it collected. */
 export function reportRevision(r) {
@@ -35,40 +36,17 @@ export const INCOMPLETE_GRACE_MS = 60 * 60_000;
 const FILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
 const FOLLOW = /^[A-Za-z0-9_-]{1,64}$/;
 const FORBIDDEN = ['timeline', 'status', 'plan', 'decision', 'files', 'receivedAt', 'followUps', 'claimedBy', 'settledBy'];
-const json = (status, body) => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } });
-const notFound = () => json(404, { error: 'not found' });
-const signIn = () => json(401, { error: 'sign in first' });
 const bad = (error) => json(400, { error });
 const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 /** Reads a JSON object body, refusing past `BODY_CAP` by the header and again by counting what arrives. */
 async function readBody(req, cap = BODY_CAP, optional = false) {
-    const declared = Number(req.headers.get('content-length'));
-    if (Number.isFinite(declared) && declared > cap)
-        return { res: json(413, { error: 'too large' }) };
-    if (!req.body)
+    if (!req.body && !(Number(req.headers.get('content-length')) > cap))
         return optional ? { body: {} } : { res: bad('a JSON body is needed') };
-    const reader = req.body.getReader();
-    const chunks = [];
-    let n = 0;
-    for (;;) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        n += value.byteLength;
-        if (n > cap) {
-            await reader.cancel().catch(() => { });
-            return { res: json(413, { error: 'too large' }) };
-        }
-        chunks.push(value);
-    }
-    const all = new Uint8Array(n);
-    let o = 0;
-    for (const c of chunks) {
-        all.set(c, o);
-        o += c.byteLength;
-    }
+    const text = await cappedText(req, cap);
+    if (typeof text !== 'string')
+        return { res: text };
     try {
-        const v = JSON.parse(new TextDecoder().decode(all));
+        const v = JSON.parse(text);
         return isObj(v) ? { body: v } : optional ? { body: {} } : { res: bad('a JSON object is needed') };
     }
     catch {

package/dist/server/http.d.ts

@@ -0,0 +1,10 @@
+/** A JSON response that is never cached. */
+export declare const json: (status: number, body: unknown) => Response;
+/** 401, the module's answer to a caller it does not know. */
+export declare const signIn: () => Response;
+/** 404, the module's answer to a report that is gone or not the caller's (the two are never told apart). */
+export declare const notFound: () => Response;
+/** The body as text, or a 413 once it passes `cap` bytes: by its declared length, and again by counting what arrives. A request with no body reads as ''. */
+export declare function cappedText(req: Request, cap: number): Promise<string | Response>;
+/** A JSON object out of text, or an empty one: the module judges the body itself; a wrapper only peeks at a field. */
+export declare function peek(text: string): Record<string, unknown>;

package/dist/server/http.js

@@ -0,0 +1,49 @@
+// The door, in the module's own words: the answers the handlers give for "who are you" and "no such report", a body
+// read that stops at a cap, and a peek at one field. Exported so an app's own route wrapper (one that has to check a
+// caller, or read a field, before the module sees the request) answers exactly as the module does and never reads a
+// body past the cap. Web-standard APIs only.
+/** A JSON response that is never cached. */
+export const json = (status, body) => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } });
+/** 401, the module's answer to a caller it does not know. */
+export const signIn = () => json(401, { error: 'sign in first' });
+/** 404, the module's answer to a report that is gone or not the caller's (the two are never told apart). */
+export const notFound = () => json(404, { error: 'not found' });
+/** The body as text, or a 413 once it passes `cap` bytes: by its declared length, and again by counting what arrives. A request with no body reads as ''. */
+export async function cappedText(req, cap) {
+    const declared = Number(req.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > cap)
+        return json(413, { error: 'too large' });
+    if (!req.body)
+        return '';
+    const reader = req.body.getReader();
+    const chunks = [];
+    let n = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        n += value.byteLength;
+        if (n > cap) {
+            await reader.cancel().catch(() => { });
+            return json(413, { error: 'too large' });
+        }
+        chunks.push(value);
+    }
+    const all = new Uint8Array(n);
+    let o = 0;
+    for (const c of chunks) {
+        all.set(c, o);
+        o += c.byteLength;
+    }
+    return new TextDecoder().decode(all);
+}
+/** A JSON object out of text, or an empty one: the module judges the body itself; a wrapper only peeks at a field. */
+export function peek(text) {
+    try {
+        const v = JSON.parse(text);
+        return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/server/index.d.ts

@@ -1,5 +1,6 @@
 export { createReportHandlers, reportRevision, TOLD, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, HELD_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.ts';
 export type { HostedStore, StoredReport, TimelineEntry, FileState, FollowUp, TellEvent, SubmitterNews, ReportHandlerOptions } from './handlers.ts';
+export { json, signIn, notFound, cappedText, peek } from './http.ts';
 export { sniffType, sameType, canonicalType, ACCEPTED_TYPES } from './sniff.ts';
 export { effectiveLimits } from './rate.ts';
 export type { Limits } from './rate.ts';

package/dist/server/index.js

@@ -1,5 +1,6 @@
 // "@supersuit/suggest-a-change/server": web-standard APIs only, no runtime dependency, nothing from react or the client.
 export { createReportHandlers, reportRevision, TOLD, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, HELD_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.js';
+export { json, signIn, notFound, cappedText, peek } from './http.js';
 export { sniffType, sameType, canonicalType, ACCEPTED_TYPES } from './sniff.js';
 export { effectiveLimits } from './rate.js';
 export { runStoreConformance, checks as conformanceChecks } from './conformance.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/suggest-a-change",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "The report format and flow behind a Suggest a change button: what a report is, who acts at each step, the screens, and the check every app runs. The contract has zero dependencies.",
   "type": "module",
   "bin": {

package/src/server/handlers.ts

@@ -10,6 +10,7 @@
 import { END, FLOW, STATUSES, TOLD, isAcceptedMedia, isReportId, mayMove, meaningFor, validateReport, wordsFor } from '../contract.mjs'
 import { effectiveLimits, type Limits } from './rate.ts'
 import { ACCEPTED_TYPES, canonicalType, sameType } from './sniff.ts'
+import { json, notFound, signIn, cappedText } from './http.ts'
 
 /** `by` is the actor (contract FLOW). `holder` is the maintainer whose Mac started or ended the work, written on a being-made
  *  or end entry: the approval on such a report never lapses, and it is how the list and the claim name who has it. */
@@ -129,34 +130,17 @@ const FILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/
 const FOLLOW = /^[A-Za-z0-9_-]{1,64}$/
 const FORBIDDEN = ['timeline', 'status', 'plan', 'decision', 'files', 'receivedAt', 'followUps', 'claimedBy', 'settledBy']
 
-const json = (status: number, body: unknown): Response =>
-  new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } })
-const notFound = () => json(404, { error: 'not found' })
-const signIn = () => json(401, { error: 'sign in first' })
 const bad = (error: string) => json(400, { error })
 const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
 
 type Body = { body: Record<string, unknown> } | { res: Response }
 /** Reads a JSON object body, refusing past `BODY_CAP` by the header and again by counting what arrives. */
 async function readBody(req: Request, cap = BODY_CAP, optional = false): Promise<Body> {
-  const declared = Number(req.headers.get('content-length'))
-  if (Number.isFinite(declared) && declared > cap) return { res: json(413, { error: 'too large' }) }
-  if (!req.body) return optional ? { body: {} } : { res: bad('a JSON body is needed') }
-  const reader = req.body.getReader()
-  const chunks: Uint8Array[] = []
-  let n = 0
-  for (;;) {
-    const { done, value } = await reader.read()
-    if (done) break
-    n += value.byteLength
-    if (n > cap) { await reader.cancel().catch(() => {}); return { res: json(413, { error: 'too large' }) } }
-    chunks.push(value)
-  }
-  const all = new Uint8Array(n)
-  let o = 0
-  for (const c of chunks) { all.set(c, o); o += c.byteLength }
+  if (!req.body && !(Number(req.headers.get('content-length')) > cap)) return optional ? { body: {} } : { res: bad('a JSON body is needed') }
+  const text = await cappedText(req, cap)
+  if (typeof text !== 'string') return { res: text }
   try {
-    const v = JSON.parse(new TextDecoder().decode(all))
+    const v = JSON.parse(text)
     return isObj(v) ? { body: v } : optional ? { body: {} } : { res: bad('a JSON object is needed') }
   } catch { return optional ? { body: {} } : { res: bad('the body is not JSON') } }
 }

package/src/server/http.ts

@@ -0,0 +1,38 @@
+// The door, in the module's own words: the answers the handlers give for "who are you" and "no such report", a body
+// read that stops at a cap, and a peek at one field. Exported so an app's own route wrapper (one that has to check a
+// caller, or read a field, before the module sees the request) answers exactly as the module does and never reads a
+// body past the cap. Web-standard APIs only.
+
+/** A JSON response that is never cached. */
+export const json = (status: number, body: unknown): Response =>
+  new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } })
+/** 401, the module's answer to a caller it does not know. */
+export const signIn = (): Response => json(401, { error: 'sign in first' })
+/** 404, the module's answer to a report that is gone or not the caller's (the two are never told apart). */
+export const notFound = (): Response => json(404, { error: 'not found' })
+
+/** The body as text, or a 413 once it passes `cap` bytes: by its declared length, and again by counting what arrives. A request with no body reads as ''. */
+export async function cappedText(req: Request, cap: number): Promise<string | Response> {
+  const declared = Number(req.headers.get('content-length'))
+  if (Number.isFinite(declared) && declared > cap) return json(413, { error: 'too large' })
+  if (!req.body) return ''
+  const reader = req.body.getReader()
+  const chunks: Uint8Array[] = []
+  let n = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    n += value.byteLength
+    if (n > cap) { await reader.cancel().catch(() => {}); return json(413, { error: 'too large' }) }
+    chunks.push(value)
+  }
+  const all = new Uint8Array(n)
+  let o = 0
+  for (const c of chunks) { all.set(c, o); o += c.byteLength }
+  return new TextDecoder().decode(all)
+}
+
+/** A JSON object out of text, or an empty one: the module judges the body itself; a wrapper only peeks at a field. */
+export function peek(text: string): Record<string, unknown> {
+  try { const v = JSON.parse(text) as unknown; return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {} } catch { return {} }
+}

package/src/server/index.ts

@@ -1,6 +1,7 @@
 // "@supersuit/suggest-a-change/server": web-standard APIs only, no runtime dependency, nothing from react or the client.
 export { createReportHandlers, reportRevision, TOLD, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, HELD_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.ts'
 export type { HostedStore, StoredReport, TimelineEntry, FileState, FollowUp, TellEvent, SubmitterNews, ReportHandlerOptions } from './handlers.ts'
+export { json, signIn, notFound, cappedText, peek } from './http.ts'
 export { sniffType, sameType, canonicalType, ACCEPTED_TYPES } from './sniff.ts'
 export { effectiveLimits } from './rate.ts'
 export type { Limits } from './rate.ts'