@supersuit/artifacts 0.52.0 → 0.54.0

package/CHANGELOG.md

@@ -3,6 +3,45 @@
 `@supersuit/artifacts`. One entry per version, newest first. Each entry says what changed, how a
 host can tell whether it is affected (DETECTOR), what a host does about it (REMEDY), and the tests.
 
+## 0.54.0 (2026-10-25)
+
+**A page no longer records under a reader left on the browser by another page.** posthog-js keeps
+the last identity it was given on an origin, and `PageAnalytics` never cleared it, so a browser that
+opened one per-reader link sent every password or public page it opened afterward under that
+reader's recipient id and label, and a per-reader page's init-time `$pageview` went out under the
+previous reader before `identify()` switched it.
+
+- `PageAnalytics` calls `posthog.reset()` when the browser is identified as anyone other than the
+  page's own reader, before `register` (reset clears registered properties). An anonymous browser
+  is not reset, so its first visit still joins the reader it becomes; the device id survives.
+- `capture_pageview` is now `false`; the page captures `$pageview` itself once the reader is settled.
+- DETECTOR: in PostHog, a `password` or `public` `page_kind` event whose `distinct_id` starts with
+  `recipient:`, or whose person has a `name`, came from a host on an older version.
+- REMEDY: update the host. Events already recorded keep the leftover identity; a dashboard should
+  name a reader only by an id of the page's own kind (a recipient id on `per-reader`, an email on
+  `gated`) and count everything else by device.
+- Tests: `page-analytics-identity.test.tsx` mounts the component against a stand-in posthog-js
+  holding a leftover identity and checks the call order on every page kind.
+
+## 0.53.0 (2026-10-25)
+
+**Every per-reader link can record who minted it, on whose authority, when, and the funnel step it
+was sent for.** Superlinks: when an operator's agent sends a page, the link it makes names the
+person it is for, and the founders asked that it also name who made it ("<person>'s Pluma, on
+<person>'s explicit request, <time>"), so that a funnel move citing the link's opens has
+provenance rather than a typed claim.
+
+- `POST /recipients` `add` entries take `provenance: { actor, authority, at?, link?, funnel?, stage? }`.
+  `at` defaults to now; a missing actor or authority, a malformed time, a non-https link, a funnel
+  that is not a slug, or a stage without its funnel is refused (400) and nothing is added.
+- `add`'s `added`, `GET /recipients` and `GET /views` carry `provenance` per reader (`null` when
+  none). Stored on the reader's row by both stores; `Provenance` is exported with the store types.
+- DETECTOR: a sender that posts `provenance` and reads `added[i].provenance` back as missing or
+  `undefined` is talking to a host on 0.52.x or older, which drops the field.
+- REMEDY: bump. Links made before this carry `provenance: null`; nothing is migrated.
+- Tests: recipients-api.test.tsx (provenance kept and answered by add, the listing and views;
+  stamped now when no time is given; each malformed shape refused with 400).
+
 ## 0.52.0 (2026-10-25)
 
 **A render before the send is never counted as the reader opening the page.** A per-reader page

package/README.md

@@ -1037,8 +1037,8 @@ Routes (spread into your route files by `createArtifactRoutes`): `RECIPIENTS`, `
 | Route | Who | What |
 |---|---|---|
 | `GET /api/artifacts/<id>/recipients` | publish key | Every reader, with the working link for each |
-| `POST /api/artifacts/<id>/recipients` | publish key | Body `{ add?: [{ label, note?, group?, closes? }], revoke?: [rid] or '*', expires?: ISO time or null, closes?: { rids: [rid] or '*', at: ISO time or null }, sent?: { rids: [rid] or '*', at?: ISO time } }`. `add` answers each new reader's link; `expires: null` is Keep; `closes` sets, moves or clears a reader's feedback window; `sent` records when links reached their readers (see A render before the send) |
-| `GET /api/artifacts/<id>/views` | publish key | One line per reader: opened, came back, active seconds, plays, devices, comments, `sentAt` and `beforeSend`. Each comment is `{ id, parent, at, text }` (see Comment ids in /views). A page with no readers yet answers 200 with an empty list; a missing page answers 404 |
+| `POST /api/artifacts/<id>/recipients` | publish key | Body `{ add?: [{ label, note?, group?, closes?, provenance? }], revoke?: [rid] or '*', expires?: ISO time or null, closes?: { rids: [rid] or '*', at: ISO time or null }, sent?: { rids: [rid] or '*', at?: ISO time } }`. `add` answers each new reader's link and its `provenance` (see Who minted a link); `expires: null` is Keep; `closes` sets, moves or clears a reader's feedback window; `sent` records when links reached their readers (see A render before the send) |
+| `GET /api/artifacts/<id>/views` | publish key | One line per reader: opened, came back, active seconds, plays, devices, comments, `sentAt`, `beforeSend` and `provenance`. Each comment is `{ id, parent, at, text }` (see Comment ids in /views). A page with no readers yet answers 200 with an empty list; a missing page answers 404 |
 | `POST /api/artifacts/<id>/seen` | the page itself (public) | The reader's own signal, below |
 
 Config, both on `createArtifactRoutes`: `recipients` (a store from `createRecipientsStore(db, '<collection path>')`, or `memoryRecipientsStore()` in tests) and `recipientSecret`, a function returning the signing secret, read on every request. A secret shorter than 32 characters is treated as unset: per-reader pages stay shut and the routes answer 404 or 501. Signing with an empty secret throws.
@@ -1070,6 +1070,20 @@ fact reclassifies what is already there. A link with no `sentAt` is read exactly
 cost, stated: a reader who opens the link within the seconds between delivery and the sender's
 mark is counted as before-send; senders mark as soon as delivery is confirmed.
 
+### Who minted a link (0.53.0)
+
+Every link can say who made it, on whose authority, and when: `add: [{ label, provenance: { actor,
+authority, at?, link?, funnel?, stage? } }]`. `actor` is a person acting by hand or "<person>'s
+Pluma"; `authority` names what they acted under ("approved by <person> on the send card", "on
+<person>'s explicit request", "under the recurrent <name>"), with `link` to the session or message
+where one exists (https only); `at` defaults to now. `funnel` (a slug) and `stage` (an id, only with
+its funnel) name the funnel step the link was sent for, so a funnel move that cites the link's opens
+has provenance. A provenance with no actor or no authority, or a malformed time, link, funnel or
+stage, is refused (400) and nothing is added. It is kept on the reader's row and answered back by
+`add`, `GET /recipients` and `GET /views` (`null` for a link made without one). A host on 0.52.x
+ignores the field, so a sender that needs it reads it back from `added` and treats `null` as an old
+host.
+
 ### Expiry
 
 `expires` sets the date the page, its media, its readers, their views and their comments go. `sweepExpired()` (call it daily from a cron route) deletes them and returns `{ pages, files, skipped, failed }`: pages removed, media files removed, ids it refused to delete (an expiry that is not a past ISO time, or a page republished without per-reader links), and ids that failed and will be retried by the next run. Your `assets` must provide `deletePage`, or every expired page lands in `failed` and nothing is deleted. With a private bucket configured it deletes from both buckets. A Keep that lands mid-sweep is honored. Deleting a page also removes every prior version of its body.

package/lib/artifacts/index.d.ts

@@ -26,6 +26,6 @@ export { AUDIO_TYPES, audioExtFor, audioTypeFor, baseMime, MAX_AUDIO_BYTES, MAX_
 export { settleOnPublish, applySettingsPatch, withComments, declaredOf, passwordDigest, newPageKey, type DeclaredSettings, type LiveSettings, type SettingsPatch } from './settings.js';
 export type { PageSettings, SettingsFact, AccessLevel } from '../reader/settings-sheet.js';
 export { ridLink, parseRidParam, verifyRid, isUnfurlAgent, usableSecret, RECIPIENT_SECRET_MIN, ridOfReaderKey } from './recipients.js';
-export { createRecipientsStore, memoryRecipientsStore, summarizeViews, type RecipientsStore, type Recipient, type RecipientsRecord, type ViewDoc, type RecipientSummary } from './recipients-store.js';
+export { createRecipientsStore, memoryRecipientsStore, summarizeViews, type RecipientsStore, type Recipient, type RecipientsRecord, type ViewDoc, type RecipientSummary, type Provenance } from './recipients-store.js';
 export { migrateMemosToPrivate, MEMO_KEY, type MemoMigration } from './migrate-memos.js';
 export { parseTranscriptFence, scanVoiceNotes, transcriptFenceFromWords, wordsFromWhisperJson, isAudioSrc, TRANSCRIPT_LANG, MAX_TRANSCRIPT_WORDS, type TranscriptParagraphs, type TimedWord, type VoiceNoteBlock } from './voice-note.js';

package/lib/artifacts/recipients-store.d.ts

@@ -11,6 +11,19 @@ export type Recipient = {
     revokedAt?: string;
     closesAt?: string | null;
     sentAt?: string;
+    provenance?: Provenance;
+};
+/** Who minted a link, on whose authority, and when (a superlink, 0.53.0): `actor` is a person by
+ *  hand or "<person>'s Pluma"; `authority` is the request, recurrent or approval it acted under, with
+ *  `link` to the session or message where one exists; `funnel` and `stage` name the funnel step the
+ *  link was sent to move someone from, so a funnel move citing its opens has provenance. */
+export type Provenance = {
+    actor: string;
+    authority: string;
+    at: string;
+    link?: string;
+    funnel?: string;
+    stage?: string;
 };
 export type RecipientsRecord = {
     recipients: Record<string, Recipient>;
@@ -43,6 +56,7 @@ export type RecipientSummary = {
     revoked: boolean;
     closesAt: string | null;
     sentAt: string | null;
+    provenance: Provenance | null;
     beforeSend: BeforeSend;
     opened: boolean;
     firstOpenAt: string | null;
@@ -63,6 +77,7 @@ type NewRecipient = {
     owner?: boolean;
     group?: boolean;
     closesAt?: string;
+    provenance?: Provenance;
 };
 export interface RecipientsStore {
     get(artifactId: string): Promise<RecipientsRecord | null>;

package/lib/artifacts/recipients-store.js

@@ -15,7 +15,7 @@ function makeRecipients(input, taken) {
         const note = typeof i.note === 'string' && i.note.trim() ? i.note.trim().slice(0, NOTE_MAX) : undefined;
         // The owner never carries a window: setCloses skips them and the page hides the closed state
         // from them, so one stored here would offer Share on their link and then refuse it.
-        return { rid, label, addedAt: at, ...(note ? { note } : {}), ...(i.owner ? { owner: true } : {}), ...(i.group ? { group: true } : {}), ...(typeof i.closesAt === 'string' && !i.owner ? { closesAt: i.closesAt } : {}) };
+        return { rid, label, addedAt: at, ...(note ? { note } : {}), ...(i.owner ? { owner: true } : {}), ...(i.group ? { group: true } : {}), ...(typeof i.closesAt === 'string' && !i.owner ? { closesAt: i.closesAt } : {}), ...(i.provenance ? { provenance: { ...i.provenance } } : {}) };
     });
 }
 function revokeIn(rec, rids) {
@@ -212,6 +212,7 @@ export function summarizeViews(rec, views, comments) {
         return {
             rid: r.rid, label: r.label, group: r.group === true, revoked: !!r.revokedAt, closesAt: r.closesAt ?? null,
             sentAt: r.sentAt ?? null,
+            provenance: r.provenance ?? null,
             beforeSend: Number.isFinite(sentMs) ? { sessions: early.length, devices: preDevices.size, activeSeconds: early.reduce((n, v) => n + v.activeSeconds, 0), firstAt: early[0]?.firstAt ?? null } : null,
             opened: mine.length > 0,
             firstOpenAt: mine[0]?.firstAt ?? null,

package/lib/reader/page-analytics.js

@@ -11,6 +11,12 @@
 // than a gated one: the replay still shows where the reader went, how far and how fast, without the
 // words. Autocapture is told not to collect element text for the same reason. There is no opt-out:
 // the options come from posthogInitOptions, which a test holds to RECORDING_MASK for every kind.
+//
+// posthog-js keeps the last identity it was given on this origin, and a page that names nobody does
+// not clear it. So a browser that opened one reader's per-reader link reported every page it opened
+// after under that reader's id and label, and a per-reader page's init-time view went out under the
+// previous reader before identify switched it. The page now drops an identity it was not given
+// before it records anything, and captures its own page view once it has settled who the reader is.
 import { useEffect } from 'react';
 import { currentSection } from '../artifacts/toc-spy.js';
 /** Sections read for less than this are passed over, not read. */
@@ -65,7 +71,8 @@ export function posthogInitOptions(plan) {
     return {
         api_host: plan.host,
         person_profiles: 'identified_only',
-        capture_pageview: true,
+        // Captured by the page once it has settled who the reader is (see PageAnalytics).
+        capture_pageview: false,
         capture_pageleave: true,
         autocapture: true,
         // Autocapture records a clicked element's text; on these pages that text is the page.
@@ -85,11 +92,17 @@ export function PageAnalytics({ plan, rootId = 'artifact-narration-root' }) {
             if (cancelled)
                 return;
             posthog.init(key, posthogInitOptions({ host }));
+            const who = identity ? JSON.parse(identity) : null;
+            // A reader left on this browser by another page is dropped first: reset also clears the
+            // registered properties, so it comes before register. An anonymous browser is left alone, so
+            // its first visit still joins the reader it becomes.
+            const left = posthog.get_property('$user_state') === 'identified' ? posthog.get_distinct_id() : null;
+            if (left && left !== who?.distinctId)
+                posthog.reset();
             posthog.register({ artifact_id: pageId, page_kind: kind, ...(tenant ? { tenant } : {}) });
-            if (identity) {
-                const who = JSON.parse(identity);
+            if (who)
                 posthog.identify(who.distinctId, { ...(who.email ? { email: who.email } : {}), ...(who.name ? { name: who.name } : {}) });
-            }
+            posthog.capture('$pageview');
             const capture = (e, p) => posthog.capture(e, p);
             const root = document.getElementById(rootId);
             const ids = root ? Array.from(root.querySelectorAll('h2[id], h3[id]'), (h) => h.id) : [];

package/lib/routes/recipients-routes.d.ts

@@ -1,5 +1,5 @@
 import { NextResponse, type NextRequest } from 'next/server';
-import { type RecipientsStore } from '../artifacts/recipients-store.js';
+import { type Provenance, type RecipientsStore } from '../artifacts/recipients-store.js';
 import type { ArtifactStore } from '../artifacts/store.js';
 import type { StateStore } from '../artifacts/state-store.js';
 import type { ArtifactAssets } from '../artifacts/assets.js';
@@ -20,6 +20,15 @@ export type RecipientsRoutesCtx = {
     /** Where the sweep reports a page it skipped or could not finish. Defaults to console.warn. */
     log?: (message: string) => void;
 };
+/** A reader's provenance as sent, checked: who minted the link, on whose authority, when (default
+ *  now), and the funnel step it serves. -> the clean record, or the reason it is refused. */
+export declare function readProvenance(v: unknown, now?: Date): {
+    ok: true;
+    value: Provenance;
+} | {
+    ok: false;
+    why: string;
+};
 export declare function createRecipientsRoutes(given: RecipientsRoutesCtx): {
     SEEN: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;
     RECIPIENTS: (req: NextRequest, { params }: Params) => Promise<NextResponse<unknown>>;

package/lib/routes/recipients-routes.js

@@ -8,6 +8,38 @@ import { ARTIFACT_ID_RE } from './ids.js';
 const SESSION = /^[a-z0-9]{1,32}$/;
 const MEDIA = /^[A-Za-z0-9][A-Za-z0-9._-]{0,140}$/;
 const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+const SLUG = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+/** A reader's provenance as sent, checked: who minted the link, on whose authority, when (default
+ *  now), and the funnel step it serves. -> the clean record, or the reason it is refused. */
+export function readProvenance(v, now = new Date()) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return { ok: false, why: 'provenance is { actor, authority, at?, link?, funnel?, stage? }' };
+    const p = v;
+    const text = (x, max) => (typeof x === 'string' && x.trim() ? x.trim().slice(0, max) : '');
+    const actor = text(p.actor, 120), authority = text(p.authority, 300);
+    if (!actor || !authority)
+        return { ok: false, why: 'provenance needs who minted the link (actor) and on whose authority (authority)' };
+    if (p.at !== undefined && (typeof p.at !== 'string' || !ISO.test(p.at)))
+        return { ok: false, why: 'provenance.at must be an ISO time' };
+    let link;
+    if (p.link !== undefined) {
+        try {
+            const u = new URL(String(p.link));
+            if (u.protocol !== 'https:')
+                throw new Error('not https');
+            link = u.toString();
+        }
+        catch {
+            return { ok: false, why: 'provenance.link must be an https address' };
+        }
+    }
+    if (p.funnel !== undefined && (typeof p.funnel !== 'string' || !SLUG.test(p.funnel)))
+        return { ok: false, why: 'provenance.funnel must be a funnel slug' };
+    if (p.stage !== undefined && (typeof p.stage !== 'string' || !SLUG.test(p.stage) || p.funnel === undefined))
+        return { ok: false, why: 'provenance.stage must be a stage id, with its funnel' };
+    const at = typeof p.at === 'string' ? new Date(p.at).toISOString() : now.toISOString();
+    return { ok: true, value: { actor, authority, at, ...(link ? { link } : {}), ...(p.funnel ? { funnel: p.funnel } : {}), ...(p.stage ? { stage: p.stage } : {}) } };
+}
 const none = () => new NextResponse(null, { status: 204, headers: { 'cache-control': 'no-store' } });
 const json = (b, status = 200) => NextResponse.json(b, { status, headers: { 'cache-control': 'no-store' } });
 export function createRecipientsRoutes(given) {
@@ -65,7 +97,7 @@ export function createRecipientsRoutes(given) {
         const rec = (await ctx.recipients.get(id)) ?? { recipients: {}, expireAt: null, keep: false };
         return {
             id, expireAt: rec.expireAt, keep: rec.keep,
-            recipients: Object.values(rec.recipients).map((r) => ({ rid: r.rid, label: r.label, group: r.group === true, owner: r.owner === true, revoked: !!r.revokedAt, closesAt: r.closesAt ?? null, sentAt: r.sentAt ?? null, url: ridLink(ctx.pageUrl(id), id, r.rid, secret) })),
+            recipients: Object.values(rec.recipients).map((r) => ({ rid: r.rid, label: r.label, group: r.group === true, owner: r.owner === true, revoked: !!r.revokedAt, closesAt: r.closesAt ?? null, sentAt: r.sentAt ?? null, provenance: r.provenance ?? null, url: ridLink(ctx.pageUrl(id), id, r.rid, secret) })),
         };
     }
     /** GET and POST /api/artifacts/<id>/recipients: who a per-reader page was sent to (publish key). */
@@ -96,6 +128,17 @@ export function createRecipientsRoutes(given) {
         const adds = Array.isArray(b.add) ? b.add : [];
         if (adds.some((x) => x.closes !== undefined && (typeof x.closes !== 'string' || Number.isNaN(Date.parse(x.closes)))))
             return json({ error: 'closes must be an ISO time' }, 400);
+        const provenances = [];
+        for (const x of adds) {
+            if (x.provenance === undefined) {
+                provenances.push(undefined);
+                continue;
+            }
+            const p = readProvenance(x.provenance);
+            if (!p.ok)
+                return json({ error: p.why }, 400);
+            provenances.push(p.value);
+        }
         const win = b.closes;
         if (win !== undefined) {
             const ridsOk = !!win && (win.rids === '*' || (Array.isArray(win.rids) && win.rids.every((x) => typeof x === 'string' && RID_RE.test(x))));
@@ -122,13 +165,14 @@ export function createRecipientsRoutes(given) {
             sentAt = new Date(atMs).toISOString();
         }
         if (adds.length) {
-            const made = await ctx.recipients.add(id, adds.map((x) => ({
+            const made = await ctx.recipients.add(id, adds.map((x, i) => ({
                 label: x.label,
                 ...(typeof x.note === 'string' ? { note: x.note } : {}), ...(x.owner === true ? { owner: true } : {}), ...(x.group === true ? { group: true } : {}),
                 // Never for the owner, whatever store the host brought: their link has no window.
                 ...(typeof x.closes === 'string' && x.owner !== true ? { closesAt: new Date(x.closes).toISOString() } : {}),
+                ...(provenances[i] ? { provenance: provenances[i] } : {}),
             })));
-            added = made.map((r) => ({ rid: r.rid, label: r.label, url: ridLink(ctx.pageUrl(id), id, r.rid, secret) }));
+            added = made.map((r) => ({ rid: r.rid, label: r.label, url: ridLink(ctx.pageUrl(id), id, r.rid, secret), provenance: r.provenance ?? null }));
         }
         const revoked = b.revoke === '*' || Array.isArray(b.revoke)
             ? await ctx.recipients.revoke(id, b.revoke === '*' ? '*' : b.revoke.filter((x) => typeof x === 'string' && RID_RE.test(x)))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "description": "Publish markdown as branded, read-aloud pages from a Next.js app: the artifacts store, the route factory, the read-along reader, brand packs, password and confidential pages, and share cards.",
   "license": "MIT",
   "type": "module",