your-attention 0.1.0 → 0.1.1

package/dist/src/client.js

@@ -0,0 +1,459 @@
+// A client for agents and integrations. It finds the inbox in this order:
+// 1. YOUR_ATTENTION_URL and YOUR_ATTENTION_TOKEN
+// 2. ~/.your-attention/client.json, written by `your-attention pair`
+// 3. the inbox running on this machine, with its local agent token
+import fs from 'node:fs';
+import path from 'node:path';
+import { bodyProblemsMessage, checkDiagrams, findDiagrams } from './core/diagrams.js';
+import { InboxError } from './core/inbox.js';
+import { isSealed } from './core/sealed.js';
+                                                                                                                                                                     
+import { homeDir } from './node/home.js';
+import { questionLines } from '../web/answers.js';
+
+                               
+              
+                
+                                                                                                               
+                  
+                                                                                                                     
+              
+ 
+
+/** The inbox and token for an extension: YOUR_ATTENTION_URL with YOUR_ATTENTION_TOKEN, or the local extension token. */
+export function loadExtensionConfig(home = homeDir())                           {
+  const url = process.env['YOUR_ATTENTION_URL'];
+  const token = process.env['YOUR_ATTENTION_TOKEN'];
+  if (url && token) return { url, token };
+  try {
+    const server = JSON.parse(fs.readFileSync(path.join(home, 'server.json'), 'utf8'))                   ;
+    return { url: server.url, token: fs.readFileSync(path.join(home, 'extension-token'), 'utf8').trim() };
+  } catch {
+    return undefined;
+  }
+}
+
+export function loadConfig(home = homeDir())                           {
+  const url = process.env['YOUR_ATTENTION_URL'];
+  const token = process.env['YOUR_ATTENTION_TOKEN'];
+  if (url && token) return { url, token };
+  const read = (f        )                     => {
+    try { return fs.readFileSync(path.join(home, f), 'utf8').trim(); } catch { return undefined; }
+  };
+  // A file that does not parse is a file this machine cannot use, the same as a missing one: `status` reports it as
+  // unreadable, and every other caller answers "no inbox" rather than a stack trace.
+  const parse = (text                    )          => {
+    if (!text) return undefined;
+    try { return JSON.parse(text); } catch { return undefined; }
+  };
+  // A file that parses to anything but a pair of strings is a pairing this machine cannot use, the same as a missing
+  // one: `status` reports it as unreadable or addressless, and every other caller answers "no inbox" rather than
+  // failing on `undefined.replace` or on a URL of 42.
+  const usable = (value         )                           => {
+    if (typeof value !== 'object' || value === null) return undefined;
+    const { url, token, urls, id } = value                                                                    ;
+    if (typeof url !== 'string' || url === '' || typeof token !== 'string' || token === '') return undefined;
+    // `urls` reaches `Client`, which calls `.replace` on each entry, so anything but a list of strings is dropped here
+    // rather than crashing there. So is every other field a file may carry.
+    const mirrors = Array.isArray(urls) ? urls.filter((u)              => typeof u === 'string' && u !== '') : [];
+    return { url, token, ...(mirrors.length ? { urls: mirrors } : {}), ...(typeof id === 'string' ? { id } : {}) };
+  };
+  const paired = usable(read('client.json') === undefined ? undefined : parse(read('client.json')));
+  if (paired) return paired;
+  const server = usable({ url: (parse(read('server.json'))                                 )?.url, token: read('agent-token') });
+  if (server) return server;
+  return undefined;
+}
+
+/** The inbox this machine paired with as owner, for the commands that act as the person: owner.json, written by
+ * `your-attention pair --role owner`, or an owner pairing that an older version saved in client.json. */
+export function ownerPairing(home = homeDir())                                                  {
+  for (const f of ['owner.json', 'client.json']) {
+    try {
+      const c = JSON.parse(fs.readFileSync(path.join(home, f), 'utf8'))                ;
+      if (c.url && c.token) return { ...c, url: c.url.replace(/\/$/, ''), source: path.join(home, f) };
+    } catch { /* no such pairing */ }
+  }
+  return undefined;
+}
+
+/** What to do on a machine whose only pairing with `url` is an agent's. */
+export function notOwnerAdvice(url        )         {
+  return `This machine is paired with ${url} as an agent, so it can't act as you. Pair it as owner with \`your-attention pair ${url} --role owner\`, which keeps the agent pairing. Or open the inbox on your phone from the phone button of a page that is signed in.`;
+}
+
+                                                       
+
+export class Client {
+  /** The link in use. */
+  url        ;
+  /** Every link to the same inbox, tried in order. */
+           urls          ;
+                   token        ;
+          inboxId                    ;
+  /** Answers already handed to the agent, so one that arrives over two links counts once. */
+                   seen = new Set        ();
+  /** This process, the same across reconnects, so the inbox sends a restarted agent the answers its earlier process never read. */
+           instance = crypto.randomUUID();
+  /** The newest guidance version each agent of this process has seen, from a hello or a guidance event. */
+                   guidanceSeen = new Map                ();
+  /** What the inbox checks itself, from GET /v1/info. An inbox from before the field checks everything. */
+          inboxChecks                                                           ;
+
+  constructor(config              ) {
+    this.urls = [config.url, ...(config.urls ?? [])].map((u) => u.replace(/\/$/, ''));
+    this.url = this.urls[0] ?? '';
+    this.token = config.token;
+    this.inboxId = config.id;
+  }
+
+  /** Check that a link leads to the same inbox as the first link. A link to another inbox is skipped,
+   * and so is every other link while the client does not know which inbox the first one leads to. */
+          async sameInbox(url        )                   {
+    const idOf = async (u        )                              =>
+      ((await (await fetch(`${u}/v1/info`, { signal: AbortSignal.timeout(5000) })).json())                   ).id;
+    if (!this.inboxId) {
+      try { this.inboxId = await idOf(this.urls[0] ?? url); } catch { /* the first link is down */ }
+    }
+    if (url === this.urls[0]) return true;
+    if (!this.inboxId) return false;
+    return (await idOf(url)) === this.inboxId;
+  }
+
+          async call   (method        , route        , body          )             {
+    // The same message id on every try, so the inbox applies the message once whichever link brings it.
+    const headers                         = { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' };
+    if (method !== 'GET') headers['x-message-id'] = crypto.randomUUID();
+    let lastError         ;
+    for (const url of [this.url, ...this.urls.filter((u) => u !== this.url)]) {
+      let res          ;
+      try {
+        if (url !== this.url && !(await this.sameInbox(url))) continue;
+        res = await fetch(`${url}${route}`, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+      } catch (e) {
+        lastError = e;
+        continue;
+      }
+      this.url = url;
+      const data = (await res.json().catch(() => ({})))                          ;
+      if (!res.ok) throw new Error(`${method} ${route}: ${res.status} ${data.error ?? ''}`.trim());
+      return data;
+    }
+    throw new Error(`${method} ${route}: no link answered (${(lastError         )?.message ?? 'none tried'})`);
+  }
+
+  /** True the first time an answer is seen, false for a copy from another link or a replay. */
+          fresh(ev            )          {
+    if (ev.type !== 'answer') return true;
+    const key = `${ev.card.id}:${ev.answer.savedAt}:${ev.answer.forcedAt ?? 0}`;
+    if (this.seen.has(key)) return false;
+    this.seen.add(key);
+    return true;
+  }
+
+  /** The bytes of a file on a card this client posted, such as an image the person pasted into an answer. */
+  async attachment(id        )                                   {
+    let lastError         ;
+    for (const url of [this.url, ...this.urls.filter((u) => u !== this.url)]) {
+      try {
+        if (url !== this.url && !(await this.sameInbox(url))) continue;
+        const res = await fetch(`${url}/v1/attachments/${encodeURIComponent(id)}`, { headers: { authorization: `Bearer ${this.token}` } });
+        if (!res.ok) throw new Error(`GET /v1/attachments/${id}: ${res.status}`);
+        this.url = url;
+        return new Uint8Array(await res.arrayBuffer());
+      } catch (e) {
+        lastError = e;
+      }
+    }
+    throw new Error(`no link answered (${(lastError         )?.message ?? 'none tried'})`);
+  }
+
+  /** The posted card. A revision the person won't see carries `warning`, and `inheritedTags` names the keys the card
+   * took from the agent's default tags. */
+  async post(card         )                                                                 {
+    await this.checkFirst('POST /v1/cards', { card: { ...card, attachments: undefined } });
+    return this.call('POST', '/v1/cards', card);
+  }
+
+  /** The default tags this token keeps for one agent id: every card that agent posts inherits them. */
+  defaultTags(agent        )                       {
+    return this.call('GET', `/v1/tags?agent=${encodeURIComponent(agent)}`);
+  }
+
+  /** Set, merge, remove or clear the default tags this token keeps for one agent id. */
+  setDefaultTags(agent        , write                                 )                       {
+    return this.call('PUT', '/v1/tags', { agent, ...write });
+  }
+
+  /** An inbox that does not check diagrams or bodies itself, such as the hosted one, takes them unchecked. So the client
+   * reads what the inbox would store, after templates and widgets, and checks it as a laptop inbox would, before it sends the card.
+   * It fails with the laptop inbox's own words. */
+          async checkFirst(route        , req                                                                                                     )                {
+    this.inboxChecks ??= this.call                                                   ('GET', '/v1/info')
+      .then((i) => i.checks ?? { diagrams: true, body: true }, (e         ) => { this.inboxChecks = undefined; throw e; });
+    const checks = await this.inboxChecks;
+    if (checks.diagrams && checks.body) return;
+    const fields = await this.call                                                           ('POST', '/v1/preview', req);
+    try {
+      // Mermaid loads on the first diagram, and the OpenUI parser on the first body.
+      const diagrams = findDiagrams(fields);
+      if (!checks.diagrams && diagrams.length) await checkDiagrams(diagrams, (await import('./adapters/mermaid.js')).checkMermaid);
+      const problems = !checks.body && fields.body !== undefined ? (await import('./adapters/openui-body.js')).bodyErrors(fields.body) : [];
+      if (problems.length) throw new InboxError(400, bodyProblemsMessage(problems));
+    } catch (e) {
+      if (e instanceof InboxError) throw new Error(`${route}: ${e.status} ${e.message}`);
+      throw e;
+    }
+  }
+
+  list()                                           { return this.call('GET', '/v1/cards'); }
+  get(id        )                                         { return this.call('GET', `/v1/cards/${encodeURIComponent(id)}`); }
+  close(id        , kind           , outcome        , ifUnanswered = false)                {
+    return this.call('POST', `/v1/cards/${encodeURIComponent(id)}/close`, { kind, outcome, ifUnanswered });
+  }
+  async patch(id        , edits                                , field         )                                       {
+    const route = `/v1/cards/${encodeURIComponent(id)}/patch`;
+    await this.checkFirst(`POST ${route}`, { id, edits, field });
+    return this.call('POST', route, { edits, field });
+  }
+  status(id        , status        )                { return this.call('POST', `/v1/cards/${encodeURIComponent(id)}/status`, { status }); }
+  saveTemplate(name        , source        , feedback         )                    { return this.call('POST', '/v1/templates', { name, source, feedback }); }
+  saveWidget(name        , source        , feedback         , extra                                       = {})                    { return this.call('POST', '/v1/widgets', { name, source, feedback, ...extra }); }
+  /** The card guidance, and the catalog of widgets an agent can place. */
+  guidance()                                                              { return this.call('GET', '/v1/guidance'); }
+  /** Propose new guidance as `agent`, which receives the person's answer and comment on the card. */
+  proposeGuidance(text        , opts                                     )                { return this.call('POST', '/v1/guidance', { text, ...opts }); }
+  ack(id        )                  { return this.call('POST', `/v1/cards/${encodeURIComponent(id)}/ack`, {}); }
+  claim(id        , agent        )                { return this.call('POST', `/v1/cards/${encodeURIComponent(id)}/claim`, { agent }); }
+  search(q        , opts                                         = {})                                             {
+    return this.call('GET', `/v1/search?q=${encodeURIComponent(q)}&limit=${opts.limit ?? 20}${opts.answered ? '&answered=1' : ''}`);
+  }
+  deadLetters()                                            { return this.call('GET', '/v1/dead-letters'); }
+  /** The answers this client has not acknowledged, with their card ids. Every field is checked: an address that answers
+   * with JSON of its own can leave `cards` out, and a caller that trusts it reads `.length` of nothing. */
+  async unread(agent         )                                               {
+    const reply = await this.call                                       ('GET', `/v1/unread${agent ? `?agent=${encodeURIComponent(agent)}` : ''}`);
+    const cards = Array.isArray(reply?.cards) ? reply.cards.filter((c)              => typeof c === 'string') : [];
+    const unread = typeof reply?.unread === 'number' && Number.isFinite(reply.unread) ? reply.unread : cards.length;
+    return { unread, cards };
+  }
+  /** Ask the inbox to send the answers to this agent's cards to a webhook. The owner approves it on a system card, and the
+   * secret that signs each call comes back here once. */
+  subscribe(agent        , webhook                                                   )                                                                            {
+    return this.call('POST', '/v1/cards', { agent, kind: 'system', title: `Send the answers for ${agent} to a webhook`, system: { type: 'subscribe', webhook, events: ['answer'] } });
+  }
+  unsubscribe(agent        )                               {
+    return this.call('POST', '/v1/cards', { agent, kind: 'system', title: `Stop sending the answers for ${agent} to a webhook`, system: { type: 'unsubscribe' } });
+  }
+  subscriptions()                                { return this.call('GET', '/v1/subscriptions'); }
+
+  /** Receive answers for one agent until `signal` aborts. Reconnects after a drop, over the next link when one fails.
+   * `auto`, the default, uses a WebSocket and falls back to server-sent events on a link that cannot carry one.
+   * `poll` long-polls, for clients that cannot keep a connection. `channelOff` tells the inbox that this session
+   * discards channel notifications, so the person sees why an answer does not arrive. */
+  async stream(agent        , onEvent                                          , signal             , transport            = 'auto', opts                           = {})                {
+    const channel = opts.channelOff ? '&channel=off' : '';
+    let link = 0;
+    const noSocket = new Set        ();
+    // A link that answered 410 for its event stream serves events over its socket only. Asking it again every
+    // second is what woke a hosted inbox's Durable Object ~35 times a second, so it is never asked again.
+    const noStream = new Set        ();
+    const deliver = async (ev            )                => {
+      if (!this.fresh(ev)) return;
+      // Record a guidance version before the handler runs, so a fetch that a hello started never hands over older text.
+      if (ev.type === 'guidance') this.guidanceSeen.set(agent, Math.max(this.guidanceSeen.get(agent) ?? 0, ev.guidance.version));
+      await onEvent(ev);
+      // The inbox sends guidance events only to agents online at the approval. A hello on a reconnect carries the
+      // current version, so an agent that was away when the person approved a newer one fetches it and gets it here.
+      if (ev.type !== 'hello') return;
+      const known = this.guidanceSeen.get(agent);
+      // The first hello of this process sets the version it starts from.
+      if (known === undefined) { this.guidanceSeen.set(agent, ev.guidance); return; }
+      if (ev.guidance <= known) return;
+      try {
+        const g = await this.guidance();
+        // A guidance event may have arrived while the fetch ran: hand over the fetched text only when it is newer still.
+        if (g.version <= (this.guidanceSeen.get(agent) ?? 0)) return;
+        this.guidanceSeen.set(agent, g.version);
+        await onEvent({ type: 'guidance', id: `hello-${g.version}`, guidance: { text: g.text, version: g.version, at: g.at } });
+      } catch { /* the next hello tries again, and the agent can read the guidance with card_guidance */ }
+    };
+    // A retry after a failure waits longer each time, so an inbox that is down, or that refuses a transport,
+    // is not woken once a second forever. A transport that ran to its end resets the count.
+    let failures = 0;
+    const backoff = ()         => {
+      const base = Math.min(30_000, 1000 * 2 ** Math.min(Math.max(failures, 1) - 1, 5));
+      return Math.round(base * (0.8 + Math.random() * 0.4));
+    };
+    while (!signal.aborted) {
+      const url = this.urls[link % this.urls.length] ?? this.url;
+      let wait = 1000;
+      try {
+        if (this.urls.length > 1 && !(await this.sameInbox(url))) throw new Error('another inbox');
+        this.url = url;
+        // The event stream is a fallback for a link whose socket does not open, and only until it refuses.
+        const overStream = transport === 'sse' || (transport === 'auto' && noSocket.has(url) && !noStream.has(url));
+        let ran = true;
+        if (transport === 'poll') await this.overPoll(url, agent, deliver, signal, channel);
+        else if (overStream) await this.overSse(url, agent, deliver, signal, channel);
+        else {
+          const opened = await this.overSocket(url, agent, deliver, signal, channel);
+          // A socket that never opened on a link that answers means the link cannot carry one. A link that does not answer is down: retry it.
+          if (!opened && transport === 'auto') {
+            if (!(await this.answers(url))) throw new Error('the link is down');
+            noSocket.add(url);
+            ran = false;
+            // Try the stream once when the link has not refused it; otherwise wait before the next socket.
+            wait = noStream.has(url) ? (failures++, backoff()) : 0;
+          }
+        }
+        if (ran) failures = 0;
+      } catch (e) {
+        if (signal.aborted) return;
+        const status = (e                       ).status;
+        if (status === 410) {
+          // The inbox serves events over its socket only, as a hosted inbox does. An explicit transport asked for
+          // a stream that this link will never serve, so it reports instead of retrying.
+          if (transport !== 'auto') throw e;
+          noStream.add(url);
+          failures++;
+          wait = backoff();
+        } else if (status === 401 || status === 403 || status === 404) {
+          // A token or address the inbox refuses stays refused: report it instead of retrying forever.
+          throw e;
+        } else {
+          link++;
+          failures++;
+          wait = backoff();
+        }
+      }
+      if (wait === 0) continue;
+      if (!signal.aborted) await new Promise((r) => setTimeout(r, wait));
+    }
+  }
+
+          async answers(url        )                   {
+    try { return (await fetch(`${url}/v1/info`, { signal: AbortSignal.timeout(5000) })).ok; } catch { return false; }
+  }
+
+          async overSse(url        , agent        , deliver                                   , signal             , channel        )                {
+    const res = await fetch(`${url}/v1/stream?agent=${encodeURIComponent(agent)}&instance=${this.instance}${channel}`, {
+      headers: { authorization: `Bearer ${this.token}`, accept: 'text/event-stream' },
+      signal,
+    });
+    if (!res.ok || !res.body) throw new TransportRefused('stream', res.status);
+    const reader = res.body.getReader();
+    const dec = new TextDecoder();
+    let buf = '';
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) return;
+      buf += dec.decode(value, { stream: true });
+      let end        ;
+      while ((end = buf.indexOf('\n\n')) >= 0) {
+        const data = buf.slice(0, end).split('\n').find((l) => l.startsWith('data: '));
+        buf = buf.slice(end + 2);
+        if (!data) continue;
+        const ev = JSON.parse(data.slice(6))                                 ;
+        if (ev.type !== 'beat') await deliver(ev);
+      }
+    }
+  }
+
+  /** Resolves when the socket closes: true if it opened first, false if it never did. */
+          overSocket(url        , agent        , deliver                                   , signal             , channel        )                   {
+    return new Promise((resolve) => {
+      let opened = false;
+      const ws = new WebSocket(`${url.replace(/^http/, 'ws')}/v1/ws?agent=${encodeURIComponent(agent)}&instance=${this.instance}${channel}`);
+      // An abort ends the stream now: a socket close waits for the far end's answer, and an idle inbox may not send
+      // one for as long as the process lives, which would leave a stopped client unable to exit.
+      const stop = ()       => { ws.close(); done(); };
+      signal.addEventListener('abort', stop, { once: true });
+      // The global WebSocket cannot send headers, so the token goes in the first frame.
+      // The client pings every 20 seconds. A Durable Object answers without waking, and closes a socket that stops.
+      let beat                                            ;
+      ws.addEventListener('open', () => {
+        opened = true;
+        ws.send(JSON.stringify({ type: 'auth', token: this.token }));
+        beat = setInterval(() => { if (ws.readyState === WebSocket.OPEN) ws.send('{"type":"ping"}'); }, 20_000);
+      });
+      ws.addEventListener('message', (m) => {
+        let ev                          ;
+        try { ev = JSON.parse(String(m.data))                            ; } catch { return ws.close(); }
+        // A beat only says the stream is alive, as it does over the event stream and the long-poll, so it never reaches
+        // the caller as an agent event.
+        if (ev && typeof ev === 'object' && ev.type !== 'pong' && ev.type !== 'error' && ev.type !== 'beat') deliver(ev              ).catch(() => ws.close());
+      });
+      let ended = false;
+      const done = ()       => {
+        if (ended) return;
+        ended = true;
+        if (beat !== undefined) clearInterval(beat);
+        signal.removeEventListener('abort', stop);
+        ws.close();
+        resolve(opened);
+      };
+      ws.addEventListener('close', done);
+      // A socket that fails to connect fires error and may never fire close.
+      ws.addEventListener('error', done);
+    });
+  }
+
+          async overPoll(url        , agent        , deliver                                   , signal             , channel        )                {
+    while (!signal.aborted) {
+      const res = await fetch(`${url}/v1/poll?agent=${encodeURIComponent(agent)}&instance=${this.instance}${channel}&wait=25`, { headers: { authorization: `Bearer ${this.token}` }, signal });
+      if (!res.ok) throw new TransportRefused('poll', res.status);
+      for (const ev of ((await res.json())                            ).events) await deliver(ev);
+    }
+  }
+}
+
+/** A transport the inbox answered with an HTTP status instead of a stream, so the loop can tell permanent from transient. */
+class TransportRefused extends Error {
+           status        ;
+  constructor(name        , status        ) {
+    super(`${name}: ${status}`);
+    this.status = status;
+  }
+}
+
+/** Plain text for an answer, as an agent reads it. */
+/** What an integration tells the agent about a card that triage or the inbox page sent back. */
+export function describeReturned(ev                                           )         {
+  return `${ev.by ?? 'Triage'} sent back card ${ev.card.id} ("${ev.card.title}"): ${ev.reason} Revise it with card_patch or post a better card.`;
+}
+
+export function describeAnswer(card      , answer        , imagePaths           )         {
+  const lines           = [];
+  if (card.questions?.length) lines.push(...questionLines(card, answer.values));
+  card.approvals?.forEach((a, i) => {
+    const r = answer.approvalResults?.[i];
+    // Only a recorded send reads as sent: an answer with no result entry says nothing about the pane.
+    const done = !answer.values[`approval_${i}`] ? 'not approved'
+      : r && 'sentAt' in r ? 'approved, and the inbox typed it into the pane as the person\'s message'
+      : r && 'error' in r ? `approved, but not sent: ${r.error}`
+      : 'approved, but the inbox recorded no send';
+    lines.push(`Approval ${i + 1} for pane ${a.pane}, "${a.text}": ${done}`);
+  });
+  for (const [k, v] of Object.entries(answer.values)) {
+    if (card.questions?.length && /^q\d+(_comment)?$/.test(k)) continue;
+    if (card.approvals?.length && /^approval_\d+$/.test(k)) continue;
+    // A sealed secret is never written out: the integration opens it into a file and names the file.
+    if (isSealed(v)) { lines.push(`${k}: (sealed)`); continue; }
+    // A check box or switch group answers with each item on or off, by the item names the agent gave.
+    const on = v && typeof v === 'object' && !Array.isArray(v) ? Object.keys(v).filter((x) => (v                           )[x]) : undefined;
+    const label = on ? on.join(', ') || '(none turned on)'
+      : k === 'choice' && card.options
+        ? [v].flat().map((x) => card.options?.find((o) => (o.id ?? o.label) === x)?.label ?? String(x)).join(', ')
+        : [v].flat().join(', ');
+    lines.push(`${k}: ${label}`);
+  }
+  if (answer.comment) lines.push(`Comment: ${answer.comment}`);
+  // Pasted images are files: name each path, or say how many came when the integration has not saved them.
+  const images = answer.images ?? [];
+  if (imagePaths?.length) images.forEach((f, i) => lines.push(`Image${f.field ? ` pasted in ${f.field}` : ''}: ${imagePaths[i] ?? f.name}`));
+  else if (images.length) lines.push(`${images.length} pasted image${images.length === 1 ? '' : 's'}`);
+  // Each widget on the card can add text for the agent, filled from this answer, such as what to do next.
+  for (const r of answer.responses ?? []) lines.push('', r);
+  return lines.join('\n') || 'An empty answer: the person sent nothing more.';
+}

package/dist/src/cloudflare/collector.js

@@ -0,0 +1,53 @@
+// The usage collector: a small Worker apart from the inbox Worker. A laptop inbox posts one
+// report a day here, and the collector writes it to the Analytics Engine dataset that hosted
+// inboxes write directly. It checks each report against the fixed fields, and keeps no address.
+import { dataPoint, parseReport } from '../core/telemetry.js';
+
+                               
+                                
+                                                                                                
+                      
+ 
+
+/** A report is about 300 bytes. */
+const MAX_BODY = 2048;
+
+const json = (data         , status        )           => Response.json(data, { status, headers: { 'cache-control': 'no-store' } });
+
+/** Read at most MAX_BODY bytes, counting what arrives, so a wrong Content-Length cannot make the Worker read more. */
+async function readBody(req         )                              {
+  if (!req.body) return '';
+  const reader = req.body.getReader();
+  const chunks               = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > MAX_BODY) { await reader.cancel(); return undefined; }
+    chunks.push(value);
+  }
+  const all = new Uint8Array(size);
+  let at = 0;
+  for (const c of chunks) { all.set(c, at); at += c.byteLength; }
+  return new TextDecoder().decode(all);
+}
+
+export default {
+  async fetch(req         , env              )                    {
+    const url = new URL(req.url);
+    if (req.method === 'GET' && url.pathname === '/v1/health') return json({ ok: true }, 200);
+    if (req.method !== 'POST' || url.pathname !== '/v1/report') return json({ error: 'not found' }, 404);
+    if (env.LIMITER && !(await env.LIMITER.limit({ key: req.headers.get('cf-connecting-ip') ?? 'unknown' })).success) return json({ error: 'too many reports, try again tomorrow' }, 429);
+    const text = await readBody(req);
+    if (text === undefined) return json({ error: `the body is over ${MAX_BODY} bytes` }, 413);
+    let body         ;
+    try { body = JSON.parse(text); } catch { return json({ error: 'the body is not JSON' }, 400); }
+    const report = parseReport(body, Date.now());
+    if (typeof report === 'string') return json({ error: report }, 400);
+    // Hosted inboxes write their own data points. A report here that claims an invite is not from a laptop.
+    if (report.source !== 'laptop' || report.invite !== '') return json({ error: 'only laptop reports come here' }, 400);
+    env.USAGE.writeDataPoint(dataPoint(report));
+    return new Response(null, { status: 204 });
+  },
+};