@supersuit/suggest-a-change 0.1.13 → 0.2.0

package/dist/server/geo.d.ts

@@ -0,0 +1,17 @@
+export type Geo = {
+    city?: string;
+    region?: string;
+    country?: string;
+};
+export type GeoHook = (req: Request) => Geo | null | undefined | Promise<Geo | null | undefined>;
+export declare const PLACE_LABEL = "Roughly where they were";
+export declare const PLACE_WHY = "from their internet connection, never their exact location; some problems only happen in one region";
+/** The context item for a place from the request, or null when there is nothing to say. */
+export declare function placeItem(g: Geo | null | undefined): {
+    key: string;
+    label: string;
+    value: string;
+    why: string;
+} | null;
+/** The context with the phone's own `place` dropped and the receiver's added; unchanged when there is neither. */
+export declare function withPlace(ctx: unknown, req: Request, geo: GeoHook | undefined): Promise<unknown>;

package/dist/server/geo.js

@@ -0,0 +1,35 @@
+// ROUGHLY WHERE THE SENDER WAS, from the request the receiver got, never from a browser prompt. The receiver (the
+// server handlers, or a suggestion relay) adds it as one context item; a place the phone claims is dropped. Hosts put
+// it in headers already, so a geo hook is one line:
+//
+//   Vercel:     (req) => ({ city: decodeURIComponent(req.headers.get("x-vercel-ip-city") ?? ""), region: req.headers.get("x-vercel-ip-country-region") ?? "", country: req.headers.get("x-vercel-ip-country") ?? "" })
+//   Cloudflare: (req) => ({ city: req.headers.get("cf-ipcity") ?? "", region: req.headers.get("cf-region") ?? "", country: req.headers.get("cf-ipcountry") ?? "" })
+//               (cf-ipcity and cf-region need Cloudflare's "Add visitor location headers" managed transform; cf-ipcountry is always there)
+export const PLACE_LABEL = 'Roughly where they were';
+export const PLACE_WHY = 'from their internet connection, never their exact location; some problems only happen in one region';
+/** The context item for a place from the request, or null when there is nothing to say. */
+export function placeItem(g) {
+    if (!g)
+        return null;
+    const value = [g.city, g.region, g.country].map((x) => (typeof x === 'string' ? x.trim().slice(0, 100) : '')).filter(Boolean).join(', ');
+    return value ? { key: 'place', label: PLACE_LABEL, value, why: PLACE_WHY } : null;
+}
+/** The context with the phone's own `place` dropped and the receiver's added; unchanged when there is neither. */
+export async function withPlace(ctx, req, geo) {
+    const has = Boolean(ctx && typeof ctx === 'object' && !Array.isArray(ctx));
+    const base = has ? { ...ctx } : {};
+    const items = Array.isArray(base.items) ? base.items.filter((i) => i?.key !== 'place') : undefined;
+    let place = null;
+    try {
+        place = geo ? placeItem(await geo(req)) : null;
+    }
+    catch {
+        place = null;
+    }
+    if (!has && !place)
+        return ctx;
+    const next = [...(items ?? []), ...(place ? [place] : [])].slice(0, 40);
+    if (next.length || items)
+        base.items = next;
+    return base;
+}

package/dist/server/handlers.d.ts

@@ -1,7 +1,16 @@
 import { TOLD } from '../contract.mjs';
+import { type AttachmentHost, type Fetch, type Person } from '../github/index.ts';
 import { type Limits } from './rate.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. */
+import { type GeoHook } from './geo.ts';
+export interface IssueRef {
+    repo: string;
+    number: number;
+    url: string;
+}
+/** `by` is the actor (contract FLOW). `holder` is the maintainer whose Mac filed or closed the issue, written on that
+ *  entry: the approval on such a report never lapses, and it is how the list and the claim name who has it. `issue` is
+ *  written on the move to open. `flags` are the kinds the privacy catch found (never the words), on a held entry; the
+ *  member's own view never shows them. */
 export interface TimelineEntry {
     status: string;
     by: string;
@@ -9,6 +18,8 @@ export interface TimelineEntry {
     step?: string;
     note?: string;
     holder?: string;
+    issue?: IssueRef;
+    flags?: string[];
 }
 export interface FileState {
     pending?: {
@@ -36,6 +47,11 @@ export interface StoredReport {
     who: {
         member: string;
         role: string;
+        contact?: {
+            email?: string;
+            phone?: string;
+            handle?: string;
+        };
     };
     timeline: TimelineEntry[];
     receivedAt: string;
@@ -149,7 +165,23 @@ export interface SubmitterNews {
     words: string;
     meaning: string;
     ended: boolean;
-    note?: string;
+    note?: string; /** The issue it became, so a push can link it. */
+    issue?: IssueRef;
+}
+/** Filing straight from the app's server: each complete report becomes an issue, with no Mac in the loop. */
+export interface GitHubFiling {
+    /** owner/name of the repo the issues go to. */
+    repo: string;
+    /** A token that can open issues there (and push, when `attachments` is a branchHost with it). */
+    token: string;
+    /** Where screenshots and recordings go. Without one they are listed as still being added. */
+    attachments?: AttachmentHost;
+    /** Third parties the privacy catch looks for (anyone but the sender and the owner). */
+    people?: Person[];
+    /** The sender's name as the issue says it; without it the issue says "A member". Never their key or email. */
+    nameOf?(member: string): string | undefined | Promise<string | undefined>;
+    /** For GitHub calls and for reading the stored files back through their read links. */
+    fetch?: Fetch;
 }
 export interface ReportHandlerOptions {
     store: HostedStore;
@@ -175,6 +207,25 @@ export interface ReportHandlerOptions {
     tellSubmitter: ((news: SubmitterNews) => void | Promise<void>) | {
         none: string;
     };
+    /** When given, a report is filed as an issue the moment it is complete: at submit when it has no files, else when its
+     *  last file is verified. A privacy hit holds it for the owner instead; GitHub failing leaves it received for a Mac. */
+    github?: GitHubFiling;
+    /** Roughly where the sender was, from the request (never a browser prompt). Added to the report's context as one item;
+     *  a place the phone claims is dropped. On Vercel: `(req) => ({ city: decodeURIComponent(req.headers.get('x-vercel-ip-city') ?? ''),
+     *  region: req.headers.get('x-vercel-ip-country-region') ?? '', country: req.headers.get('x-vercel-ip-country') ?? '' })`. */
+    geo?: GeoHook;
+    /** How to reach a member, from what the app knows of them. The phone only says whether to share it (by sending
+     *  `who.contact`, which it does while the person leaves it ticked); what it sent there is ignored. Without this, no
+     *  report carries a contact. A contact of the wrong shape is dropped. */
+    contactOf?(member: string): {
+        email?: string;
+        phone?: string;
+        handle?: string;
+    } | null | undefined | Promise<{
+        email?: string;
+        phone?: string;
+        handle?: string;
+    } | null | undefined>;
     now?: () => number;
 }
 export declare const LEASE_MS: number;

package/dist/server/handlers.js

@@ -7,10 +7,12 @@
 // a report is decided here from the signed-in member and the explicit maintainers list, never from the
 // request. Nothing is uploaded through this server: `uploadUrl` issues a direct-to-storage link with the
 // size and type fixed, and `finalize` checks what actually landed.
-import { END, FLOW, STATUSES, TOLD, isAcceptedMedia, isReportId, mayMove, meaningFor, validateReport, wordsFor } from '../contract.mjs';
+import { END, FLOW, LEGACY, STATUSES, TOLD, currentStatus, isAcceptedMedia, isReportId, mayMove, meaningFor, validContact, validIssue, validateReport, wordsFor } from '../contract.mjs';
+import { fileSuggestion, privacyCatch } from '../github/index.js';
 import { effectiveLimits } from './rate.js';
 import { ACCEPTED_TYPES, canonicalType, sameType } from './sniff.js';
 import { json, notFound, signIn, cappedText } from './http.js';
+import { withPlace } from './geo.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,7 +37,9 @@ export const VOICE_BYTES_PER_SECOND = 200_000;
 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 FORBIDDEN = ['timeline', 'status', 'plan', 'decision', 'issue', 'files', 'receivedAt', 'followUps', 'claimedBy', 'settledBy'];
+/** Every stored status that means closed, old ones included: what a store's atomic follow-up write refuses on. */
+const CLOSED_STORED = [...END, ...Object.keys(LEGACY).filter((k) => END.includes(LEGACY[k]))];
 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. */
@@ -54,10 +58,19 @@ async function readBody(req, cap = BODY_CAP, optional = false) {
     }
 }
 const iso = (ms) => new Date(ms).toISOString();
+/** The status as stored (a store's precondition compares this one). */
 const lastStatus = (r) => r.timeline[r.timeline.length - 1]?.status ?? 'received';
-/** Past asking the owner: the work has started or ended, and whoever holds the approval keeps it. */
-const PAST_ASKING = ['being-made', ...END];
-/** The maintainer named on the latest move that started or ended the work; none on a report from before 0.1.4. */
+/** The status it means now: an old (0.1.x) status folded into the new one. Every decision below reads this. */
+const cur = (r) => currentStatus(lastStatus(r));
+/** Filed or closed: whoever holds the approval keeps it. */
+const FILED = [...TOLD];
+const issueOf = (r) => {
+    for (let i = r.timeline.length - 1; i >= 0; i--)
+        if (r.timeline[i].issue)
+            return r.timeline[i].issue;
+    return undefined;
+};
+/** The maintainer named on the latest move that filed or closed it (or an old one that started or ended the work). */
 const holderOf = (r) => {
     for (let i = r.timeline.length - 1; i >= 0; i--)
         if (r.timeline[i].holder)
@@ -124,6 +137,8 @@ export function createReportHandlers(opts) {
         ...(r.answers !== undefined ? { answers: r.answers } : {}),
         ...(r.app !== undefined ? { app: r.app } : {}),
         where: r.where, diagnostics: r.diagnostics, media: r.media ?? [], voice: r.voice ?? [],
+        ...(issueOf(r) ? { issue: issueOf(r) } : {}),
+        ...(r.context !== undefined ? { context: r.context } : {}),
         timeline: (r.timeline ?? []).map((t) => ({ status: t.status, by: t.by, at: t.at, ...(t.step ? { step: t.step } : {}), ...(t.note ? { note: t.note } : {}) })),
         followUps: (r.followUps ?? []).map((f) => ({ followId: f.followId, words: f.words, at: f.at, by: f.by, voice: f.voice })),
     });
@@ -212,9 +227,22 @@ export function createReportHandlers(opts) {
                     return bad('diagnostics values are short text');
             }
         }
+        // How to reach the sender comes from the host, never the phone: the phone only says whether to share it.
+        const asked = isObj(raw.who) && raw.who.contact !== undefined;
+        let contact;
+        try {
+            contact = asked && opts.contactOf ? await opts.contactOf(member) : undefined;
+        }
+        catch {
+            contact = undefined;
+        }
+        if (contact !== undefined && (contact === null || validContact(contact).length))
+            contact = undefined;
+        const context = raw.context === undefined && !opts.geo ? undefined : await withPlace(raw.context, req, opts.geo);
         const report = {
             id: raw.id, kind: raw.kind, words, media, voice: v.voice,
-            who: { member, role: roleOf(member) },
+            who: { member, role: roleOf(member), ...(contact !== undefined ? { contact } : {}) },
+            ...(context !== undefined ? { context } : {}),
             ...(answers ? { answers } : {}),
             app: { ...(opts.app ?? {}) },
             where, diagnostics,
@@ -226,7 +254,7 @@ export function createReportHandlers(opts) {
         const existing = await store.get(id);
         // The same member sending the same id again is a repeat, even at the day's limit: it was stored.
         if (existing?.who?.member === member)
-            return json(200, { id, status: lastStatus(existing) });
+            return json(200, { id, status: cur(existing) });
         if ((await store.countToday(member)) >= limits.perPersonPerDay)
             return json(429, { error: 'you have reached today\'s limit of suggestions' });
         const at = iso(now());
@@ -237,10 +265,14 @@ export function createReportHandlers(opts) {
             // Lost a race with the same member (a repeat), or the id belongs to someone else. Someone else's id is REFUSED
             // (not re-issued, not dropped silently): nothing is created or overwritten, and the phone is told to start again.
             const now2 = await store.get(id);
-            return now2?.who?.member === member ? json(200, { id, status: lastStatus(now2) }) : json(409, { error: 'that suggestion cannot use this id; start it again' });
+            return now2?.who?.member === member ? json(200, { id, status: cur(now2) }) : json(409, { error: 'that suggestion cannot use this id; start it again' });
         }
         await tell({ type: 'submitted', reportId: id, member });
-        return json(200, { id, status: 'received' });
+        // Nothing to wait for: with the github option it becomes an issue now.
+        if (opts.github && !fileNames(report).length)
+            await fileNow(id);
+        const after = await store.get(id);
+        return json(200, { id, status: after ? cur(after) : 'received' });
     }
     async function mine(req) {
         const m = wrongMethod(req, 'GET');
@@ -253,8 +285,8 @@ export function createReportHandlers(opts) {
         const rows = (await store.listFor(member)).filter((r) => r.who?.member === member);
         rows.sort((a, b) => (a.receivedAt < b.receivedAt ? 1 : -1));
         // A declined report carries its one-line reason, which the member's own view already shows; no other note is listed.
-        const reason = (r) => { const t = r.timeline[r.timeline.length - 1]; return t?.status === 'not-now' && t.note ? { note: t.note } : {}; };
-        return json(200, rows.map((r) => ({ id: r.id, status: lastStatus(r), kind: r.kind, at: Date.parse(r.receivedAt), ...reason(r) })));
+        const reason = (r) => { const t = r.timeline[r.timeline.length - 1]; return cur(r) === 'not-planned' && t?.note ? { note: t.note } : {}; };
+        return json(200, rows.map((r) => ({ id: r.id, status: cur(r), kind: r.kind, at: Date.parse(r.receivedAt), ...reason(r), ...(issueOf(r) ? { issue: issueOf(r) } : {}) })));
     }
     async function one(req, id) {
         const m = wrongMethod(req, 'GET');
@@ -290,13 +322,13 @@ export function createReportHandlers(opts) {
             return notFound();
         if ((r.followUps ?? []).some((f) => f.followId === followId))
             return json(200, { id, followId }); // a repeat
-        if (END.includes(lastStatus(r)))
+        if (END.includes(cur(r)))
             return json(409, { error: 'this suggestion is closed; start a new one' });
         const v = voiceEntries(raw.voice, limits.followUpVoiceNotes, new Set(fileNames(r)));
         if ('error' in v)
             return bad(v.error);
         // The caps are enforced again inside the store's atomic write: the read above is only a fast path.
-        const added = await store.addFollowUp(id, { followId, words, at: iso(now()), by: roleOf(member), voice: v.voice.map(({ file, ms }) => ({ file, ms })) }, { max: limits.followUps, maxVoice: limits.followUps * limits.followUpVoiceNotes, voiceTotalMs: limits.voiceTotalMs, closed: [...END] });
+        const added = await store.addFollowUp(id, { followId, words, at: iso(now()), by: roleOf(member), voice: v.voice.map(({ file, ms }) => ({ file, ms })) }, { max: limits.followUps, maxVoice: limits.followUps * limits.followUpVoiceNotes, voiceTotalMs: limits.voiceTotalMs, closed: CLOSED_STORED });
         if (added === 'missing')
             return notFound();
         if (added === 'closed')
@@ -394,6 +426,8 @@ export function createReportHandlers(opts) {
         const verified = { type: real.type, bytes: real.bytes, sha256: real.sha256, at: iso(now()) };
         await store.setFile(id, file, verified);
         await store.reopen(id); // verified after a Mac collected the report: it is offered again with this file
+        if (opts.github)
+            await fileNow(id); // its last file: with the github option it becomes an issue now
         return json(200, { file, type: verified.type, bytes: verified.bytes, sha256: verified.sha256 });
     }
     const complete = (r) => fileNames(r).every((f) => r.files?.[f]?.sha256);
@@ -415,7 +449,7 @@ export function createReportHandlers(opts) {
             for (const r of batch) {
                 if (out.length >= limits.agentPage)
                     break;
-                if (END.includes(lastStatus(r)) && holderOf(r) !== by) {
+                if (END.includes(cur(r)) && holderOf(r) !== by) {
                     await store.claim(r.id, by, LEASE_MS);
                     if ((await store.settle(r.id, by, reportRevision(r))) === 'settled')
                         settled++;
@@ -431,9 +465,9 @@ export function createReportHandlers(opts) {
                 break;
         }
         // `revision` is what this Mac is being shown; it goes back with the settle so a report that grew in between is not settled.
-        // `heldBy` names another maintainer whose Mac is making the report, so this Mac files it as taken.
+        // `heldBy` names another maintainer whose Mac filed the issue, so this Mac leaves it to that one.
         return json(200, { reports: out.map((r) => {
-                const holder = lastStatus(r) === 'being-made' ? holderOf(r) : undefined;
+                const holder = cur(r) === 'open' ? holderOf(r) : undefined;
                 return { ...r, revision: reportRevision(r), ...(holder && holder !== by ? { heldBy: holder } : {}) };
             }) });
     }
@@ -473,24 +507,23 @@ export function createReportHandlers(opts) {
             return json(409, { error: 'this report was not claimed by this Mac' });
         if (settled === 'stale')
             return json(409, { error: 'this report changed after it was listed; list again', stale: true });
-        const moves = mayMove(lastStatus(r), 'with-freeda');
-        if (moves)
-            await store.setStatus(id, { status: 'with-freeda', by: FLOW['with-freeda'].actor, at: iso(now()) }, lastStatus(r));
+        // Collecting is not filing: the report stays received until the Mac files the issue or holds it.
         await store.moveCollected(id);
         await tell({ type: 'settled', reportId: id });
-        return json(200, { id, status: moves ? 'with-freeda' : lastStatus(r) });
+        return json(200, { id, status: cur(r) });
     }
-    /** Takes (or renews) the approval for `by`. A closed report is never taken, by anyone: it answers who closed it. A
-     *  report being made stays with the Mac that started it. Taken for a move that starts or ends the work, or on a
-     *  report already being made, the lease is HELD_MS, so it does not lapse; before that, a week. Writes nothing when refused. */
+    /** Takes (or renews) the approval for `by`. A closed report is never taken, except to reopen it by the Mac that
+     *  filed it (or by anyone when nobody is named); otherwise it answers who closed it. An open issue stays with the Mac
+     *  that filed it. Taken for filing or closing, or on an open issue, the lease is HELD_MS, so it does not lapse; before
+     *  that, a week. Writes nothing when refused. */
     async function takeApproval(r, by, to) {
-        const from = lastStatus(r);
+        const from = cur(r);
         const holder = holderOf(r);
-        if (END.includes(from))
+        if (END.includes(from) && !(to === 'open' && (!holder || holder === by)))
             return { closed: from, ...(holder ? { claimedBy: holder } : {}) };
-        if (from === 'being-made' && holder && holder !== by)
+        if (from === 'open' && holder && holder !== by)
             return { claimedBy: holder };
-        const lasting = from === 'being-made' || (to !== undefined && PAST_ASKING.includes(to));
+        const lasting = FILED.includes(from) || (to !== undefined && FILED.includes(to));
         return store.claimApproval(r.id, by, lasting ? HELD_MS : APPROVAL_LEASE_MS);
     }
     async function agentClaimApproval(req, id) {
@@ -542,39 +575,108 @@ export function createReportHandlers(opts) {
         const note = got.body.note === undefined ? undefined : str(got.body.note, 200);
         if (step === null || note === null)
             return bad('step and note are short text');
+        const rawIssue = got.body.issue;
+        if (rawIssue !== undefined && validIssue(rawIssue).length)
+            return bad(`the issue is not valid: ${validIssue(rawIssue).join('; ')}`);
+        const given = rawIssue;
         const r = isReportId(id) ? await store.get(id) : null;
         if (!r)
             return notFound();
-        const from = lastStatus(r);
+        const from = cur(r);
         if (from === status)
             return json(200, { id, status }); // a repeat
         if (!mayMove(from, status))
             return json(409, { error: `a report cannot go from ${from} to ${status}` });
-        // Once the owner is being asked, the Mac that holds the approval decides what happens next. Leaving
-        // waiting-on-owner, starting the work and ending it need the claim (taken here if nobody holds it).
-        const needsApproval = from === 'waiting-on-owner' || PAST_ASKING.includes(status);
+        const issue = given ? { repo: given.repo, number: given.number, url: given.url } : undefined;
+        if (status === 'open' && !issue && !issueOf(r))
+            return bad('a move to open names the issue it became: { repo, number, url }');
+        // Once it is held for the owner, the Mac that holds the approval decides what happens next. Leaving held,
+        // filing and closing need the claim (taken here if nobody holds it).
+        const needsApproval = from === 'held' || FILED.includes(status);
         if (needsApproval) {
             const c = await takeApproval(r, by, status);
             if (!('ok' in c))
                 return json(409, { error: 'another Mac holds the approval for this report', ...(c.claimedBy ? { claimedBy: c.claimedBy } : {}) });
         }
-        // The maintainer is named on a move that starts or ends the work, so the hold is known from the report itself.
-        const holder = PAST_ASKING.includes(status) ? { holder: by } : {};
-        const moved = await store.setStatus(id, { status, by: FLOW[status].actor, at: iso(now()), ...(step ? { step } : {}), ...(note ? { note } : {}), ...holder }, from);
+        // The maintainer is named on a move that files or closes it, so the hold is known from the report itself.
+        const holder = FILED.includes(status) ? { holder: by } : {};
+        // Declined before it was ever filed is the owner's decision, not GitHub's.
+        const actor = status === 'not-planned' && from !== 'open' ? 'owner' : FLOW[status].actor;
+        const moved = await store.setStatus(id, { status, by: actor, at: iso(now()), ...(step ? { step } : {}), ...(note ? { note } : {}), ...holder, ...(issue ? { issue } : {}) }, lastStatus(r));
         if (!moved) {
             // The lasting lease was taken for a move that did not happen: bring it back to a week.
-            if (needsApproval && from !== 'being-made' && PAST_ASKING.includes(status))
+            if (needsApproval && !FILED.includes(from) && FILED.includes(status))
                 await store.claimApproval(id, by, APPROVAL_LEASE_MS);
             return json(409, { error: 'the report changed while this was sent; read it again' });
         }
-        await tell({ type: 'status', reportId: id, member: r.who?.member, status });
+        // A maintainer is not told that the issue they just filed from their own report exists; a close is still news.
+        await moved_(r, status, { by, note, issue: issue ?? issueOf(r) });
+        return json(200, { id, status });
+    }
+    /** After a move landed: the ids-only tell, and the person who suggested it on a telling move. */
+    async function moved_(r, status, { by, note, issue }) {
         const member = r.who?.member;
-        // A maintainer is not told that the work they just started on their own report has started; an end is still news.
-        const ownStart = status === 'being-made' && member === by;
-        if (member && TOLD.includes(status) && !ownStart) {
-            await news({ member, reportId: id, status, words: wordsFor(status, { owner }), meaning: meaningFor(status, { owner }), ended: END.includes(status), ...(status === 'not-now' && note ? { note } : {}) });
+        await tell({ type: 'status', reportId: r.id, member, status });
+        const ownFiling = status === 'open' && member === by;
+        if (member && TOLD.includes(status) && !ownFiling) {
+            await news({ member, reportId: r.id, status, words: wordsFor(status, { owner }), meaning: meaningFor(status, { owner, issue }), ended: END.includes(status), ...(status === 'not-planned' && note ? { note } : {}), ...(issue ? { issue } : {}) });
+        }
+    }
+    /** FILING FROM THE APP'S SERVER (the github option). Runs once a report is complete. One caller files it: the approval
+     *  is taken atomically under a one-time name, the report is read again under it, and a second caller finds it taken
+     *  or already filed. A privacy hit holds it for the owner (the kinds on the entry, never the words); GitHub failing
+     *  leaves it received and the approval free, so a maintainer's Mac can file it. Never fails the person's request. */
+    async function fileNow(id) {
+        const g = opts.github;
+        if (!g)
+            return;
+        const first = await store.get(id);
+        if (!first || cur(first) !== 'received' || !complete(first))
+            return;
+        const lock = `@app:${Math.random().toString(36).slice(2, 10)}`;
+        const got = await store.claimApproval(id, lock, HELD_MS);
+        if (!('ok' in got))
+            return;
+        try {
+            const r = await store.get(id);
+            if (!r || cur(r) !== 'received' || !complete(r))
+                return;
+            const report = { id: r.id, kind: r.kind, words: r.words ?? '', who: r.who, voice: r.voice ?? [], media: r.media ?? [], where: r.where, diagnostics: r.diagnostics, followUps: r.followUps ?? [], ...(r.context ? { context: r.context } : {}) };
+            const { hits } = privacyCatch(report, { people: g.people ?? [], secrets: [r.who.member, ...maintainers] });
+            if (hits.length) {
+                const flags = [...new Set(hits.map((h) => h.kind))];
+                await store.setStatus(id, { status: 'held', by: FLOW.held.actor, at: iso(now()), flags }, lastStatus(r));
+                return;
+            }
+            const f = g.fetch ?? globalThis.fetch;
+            const files = [];
+            if (g.attachments) {
+                for (const name of fileNames(r)) {
+                    const v = r.files?.[name];
+                    if (!v?.sha256)
+                        continue;
+                    const link = await store.readUrl({ reportId: id, file: name, ttlMs: READ_TTL_MS });
+                    const res = await f(link.url);
+                    if (!res.ok)
+                        continue; // left as still being added
+                    files.push({ name, type: String(v.type), bytes: new Uint8Array(await res.arrayBuffer()) });
+                }
+            }
+            const filerName = (await g.nameOf?.(r.who.member)) || undefined;
+            const filed = await fileSuggestion({ repo: g.repo, token: g.token, fetch: f }, {
+                report,
+                compose: { appName: opts.app?.name, ...(typeof opts.app?.label === 'string' && opts.app.label ? { appLabel: opts.app.label } : {}), appVersion: typeof report.diagnostics?.appVersion === 'string' ? report.diagnostics.appVersion : undefined, filerName, filerRole: r.who.role },
+                files,
+                ...(g.attachments ? { attachments: g.attachments } : {}),
+            });
+            const issue = { repo: g.repo, number: filed.number, url: filed.url };
+            if (await store.setStatus(id, { status: 'open', by: FLOW.open.actor, at: iso(now()), issue }, lastStatus(r)))
+                await moved_(r, 'open', { issue });
+        }
+        catch { /* GitHub or storage failed: it stays received for a Mac to file */ }
+        finally {
+            await store.releaseApproval(id, lock);
         }
-        return json(200, { id, status });
     }
     return { submit, uploadUrl, finalize, mine, one, append, agentList, agentFile, agentSettle, agentClaimApproval, agentReleaseApproval, agentStatus };
 }

package/dist/server/index.d.ts

@@ -1,6 +1,8 @@
 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 type { HostedStore, StoredReport, TimelineEntry, FileState, FollowUp, TellEvent, SubmitterNews, ReportHandlerOptions, GitHubFiling, IssueRef } from './handlers.ts';
 export { json, signIn, notFound, cappedText, peek } from './http.ts';
+export { placeItem, withPlace, PLACE_LABEL, PLACE_WHY } from './geo.ts';
+export type { Geo, GeoHook } from './geo.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,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.js';
 export { json, signIn, notFound, cappedText, peek } from './http.js';
+export { placeItem, withPlace, PLACE_LABEL, PLACE_WHY } from './geo.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.13",
+  "version": "0.2.0",
   "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": {
@@ -17,6 +17,10 @@
       "types": "./dist/server/index.d.ts",
       "import": "./dist/server/index.js"
     },
+    "./github": {
+      "types": "./dist/github/index.d.ts",
+      "import": "./dist/github/index.js"
+    },
     "./check": "./src/check/index.mjs",
     "./styles.css": "./src/client/styles.css",
     "./package.json": "./package.json"

package/src/client/adapters.ts

@@ -7,10 +7,15 @@ import type { Store } from './idb.ts'
 import type { StoreAdapter } from './reports.ts'
 import type { startTake } from './recorder.ts'
 import type { Words } from './words.ts'
+import type { Destination } from '../github/compose.ts'
+import type { AppContextItem } from './context.ts'
 
 export type Role = 'operator' | 'member' | 'maintainer'
 export type Kind = 'change' | 'broken' | 'feedback'
-export type Identity = { account: string; role: Role }
+/** `name` (or `username`) is how the person is called in the app; it goes in the context, and the account never does. */
+export type Identity = { account: string; role: Role; name?: string; username?: string }
+/** How whoever fixes it can reach the sender: what the app already knows. */
+export type Contact = { email?: string; phone?: string; handle?: string }
 
 export type HeardUpload = (key: string, blob: Blob, ms: number) => Promise<{ audio: string; text: string } | { refused: string }>
 
@@ -75,4 +80,16 @@ export interface Adapters {
   startTake?: typeof startTake
   /** False when the receiving side cannot take a voice note added to a report afterwards (the detail view then says so). */
   appendVoice?: boolean
+  /** Where a sent report files as a GitHub issue. With it, the sheet lists exactly what goes and where above Send
+   *  (the same list the issue is written from); null or absent keeps the one-line note. */
+  destination?(): Promise<SheetDestination | null>
+  /** Anything app-specific that would help fix it, each with why it is shared (an item without a why is dropped). Or
+   *  `{ items?, precise? }`, where `precise: true` also asks the browser for the person's location (its permission prompt). */
+  context?: (() => Promise<AppContextItem[]>) | { items?(): Promise<AppContextItem[]>; precise?: boolean }
+  /** How to reach the sender, from what the app already knows. Shared by default to a private repo, off for a public one. */
+  contact?(): Promise<Contact | null>
 }
+
+/** The issue's destination as the sheet shows it: the repo, whether it is public, the GitHub login it files from,
+ *  whether files can reach it yet, and (optionally) the sender's name as the issue will say it. */
+export interface SheetDestination extends Destination { name?: string }