@supersuit/artifacts 0.47.0 → 0.48.0

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 `@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.48.0
+
+**Unpublishing keeps the history.** `POST /api/artifacts?id=<id>&unpublish=1` takes a page off the
+web and keeps everything that happened on it: the record, every version, every comment, every
+file. Every reader-facing path (the page, its versions, its share card, comments, answers, per-reader
+links) reads through a view of the store that does not see an unpublished page, so each answers
+404; the publisher's own routes (publish, the narration GET, uploads, DELETE) still reach it. A
+republish to the id puts the page back at the same link. Until now the only way to take a page
+down was DELETE, which destroys every version and every comment for good. DELETE is unchanged,
+and is now the explicit "destroy" rather than the only "take down". The new store method is
+`setUnpublished(id, at | null)`; the Firestore store has it, and a store without it answers 501.
+On the publish route rather than a new one, so no host has a route file to add, and a host older
+than this answers the empty body with a 400 and changes nothing.
+
+- DETECTOR: a publisher that sends `?unpublish=1` and gets a 400 is talking to a host before 0.48.0.
+- REMEDY: update the dependency. Nothing to configure.
+- Tests: unpublish.test.tsx.
+
 ## 0.47.0
 
 **Figures and Helm scenes play inline, as two new embed fences.** A ```` ```figure ```` block

package/README.md

@@ -116,6 +116,13 @@ hostname and pick by the `host` header.
 body. The response carries the page's id and URL. Posting a file whose front matter carries
 that `id:` republishes it in place, keeping every earlier version.
 
+**Taking a page down keeps its history (0.48.0).** `POST /api/artifacts?id=<id>&unpublish=1`
+(publish key, empty body) takes the page off the web: every reader path answers 404, and the
+record, every version, every comment and every file are kept. Republishing to that id puts it back
+at the same link. `DELETE /api/artifacts/<id>` is the separate act that destroys all of it. A host
+older than 0.48.0 answers the unpublish with a 400 and changes nothing, so a publisher can never
+mistake it for a delete; a store without `setUnpublished` answers 501, likewise changing nothing.
+
 ## The page menu
 
 Every page, past version and door carries one small round **⋯** button in the top right corner

package/lib/artifacts/store.d.ts

@@ -57,6 +57,10 @@ export type ArtifactRecord = {
      *  given: a version is never described by anything its author did not write. */
     note?: string;
     views: number;
+    /** When the page was taken off the web (0.48.0). The record, every version, every comment and
+     *  every file are KEPT: an unpublished page is served to no reader, and a republish to its id
+     *  puts it back. DELETE is the separate act that destroys. */
+    unpublishedAt?: string;
 };
 /** One line of a page's history. `at` is when that version went live. */
 export type VersionEntry = {
@@ -130,6 +134,9 @@ export interface ArtifactStore {
     version?(id: string, n: number): Promise<VersionRecord | null>;
     /** Write (or, with null, clear) the change note on one version after the fact. */
     setNote?(id: string, n: number, note: string | null): Promise<boolean>;
+    /** Take a page off the web keeping everything (an ISO time), or put it back (null). False when
+     *  no such page. A store without it can only destroy, and the host refuses to unpublish. */
+    setUnpublished?(id: string, at: string | null): Promise<boolean>;
     /** Every page of one kind, newest first, without bodies (0.37.0): the owner's documents and the
      *  owner's broadcasts are two lists. */
     list?(kind: ArtifactKind): Promise<ArtifactListItem[]>;

package/lib/artifacts/store.js

@@ -69,6 +69,13 @@ export function createArtifactStore(db, collection = 'artifacts') {
         history: (id) => historyOf(col, id),
         version: (id, n) => versionOf(col, id, n),
         setNote: (id, n, note) => setNote(col, id, n, note),
+        setUnpublished: async (id, at) => {
+            const ref = col().doc(id);
+            if (!(await ref.get()).exists)
+                return false;
+            await ref.update({ unpublishedAt: at ?? FieldValue.delete() });
+            return true;
+        },
         list: async (kind) => {
             // `select` keeps every body out of the listing; a tenant's pages number in the hundreds.
             const snap = await col().select('title', 'summary', 'template', 'createdAt', 'updatedAt', 'views').get();
@@ -231,6 +238,8 @@ async function saveArtifact(col, input) {
             // `updatedAt` is when this version went live; finishing its own publish does not move it.
             ...(fresh || input.markdown !== existing.markdown ? { updatedAt: now } : {}),
             note: nextNote ?? FieldValue.delete(),
+            // A republish is the page going back up: an unpublished page is live again at the same link.
+            unpublishedAt: FieldValue.delete(),
             ...(existing.versions ? { versions: FieldValue.delete() } : {}),
         });
         return { id: input.id, version: next, created: false };

package/lib/routes/artifacts.d.ts

@@ -229,6 +229,10 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
     }>>;
     POST: (request: NextRequest) => Promise<NextResponse<{
         error: string;
+    }> | NextResponse<{
+        id: string;
+        unpublished: boolean;
+        at: string;
     }> | NextResponse<{
         warning?: string | undefined;
         expireAt?: string | null | undefined;

package/lib/routes/artifacts.js

@@ -71,7 +71,11 @@ function ViewingAsReader({ back }) {
     return (_jsx("div", { "data-viewing-as-reader": true, "data-nospeak": true, className: "fixed inset-x-0 top-3 z-50 flex justify-center px-3", children: _jsxs("p", { className: "m-0 rounded-full border border-[color:var(--a-line-strong)] bg-[color:var(--a-surface)] px-4 py-1.5 font-sans text-xs text-[color:var(--a-strong)] shadow-lg", children: ["Viewing as a reader \u00B7 ", _jsx("a", { href: back, className: "underline", children: "Back to your view" })] }) }));
 }
 export function createArtifactRoutes(config) {
-    const { store, siteUrl } = config;
+    const { store: kept, siteUrl } = config;
+    // An unpublished page (0.48.0) is KEPT, versions, comments and files all, and served to nobody:
+    // every reader-facing path reads through this view, which does not see it. The publisher's own
+    // routes (POST, GET, DELETE, the uploads) read `kept`, so the page can be put back or destroyed.
+    const store = { ...kept, get: async (id) => { const a = await kept.get(id); return a?.unpublishedAt ? null : a; } };
     // The pack as configured draws the share card; the page paints with its theme variables, so a
     // page follows its light, dark or system mode (brand/theme.ts).
     const pack = config.brand;
@@ -771,6 +775,21 @@ export function createArtifactRoutes(config) {
     async function POST(request) {
         if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+        // `?unpublish=1`: take the page off the web and keep everything. On the publish route rather
+        // than a route of its own so no host has a file to add, and so a host older than 0.48.0 refuses
+        // the empty body with a 400 instead of doing anything at all: it can never be mistaken for a delete.
+        if (request.nextUrl.searchParams.get('unpublish') === '1') {
+            const id = request.nextUrl.searchParams.get('id');
+            if (!id || !ARTIFACT_ID.test(id))
+                return NextResponse.json({ error: 'unpublish needs ?id=<page id>' }, { status: 400 });
+            if (!kept.setUnpublished)
+                return NextResponse.json({ error: 'this store cannot keep a page unpublished; nothing was changed' }, { status: 501 });
+            const at = new Date().toISOString();
+            if (!(await kept.get(id)) || !(await kept.setUnpublished(id, at)))
+                return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
+            revalidatePath(pagePath(id));
+            return NextResponse.json({ id, unpublished: true, at });
+        }
         const text = await request.text();
         let parsed = parseArtifactSource(text);
         if (!parsed.ok)
@@ -779,7 +798,7 @@ export function createArtifactRoutes(config) {
         // The kind is sticky, like `links:`: a republish of a broadcast that leaves `template:` out is
         // still a broadcast, and one that says `document` is refused rather than quietly changed.
         if (id && parsed.meta.template === 'document') {
-            const stored = await store.get(id);
+            const stored = await kept.get(id);
             if (stored && kindOf(stored) === 'broadcast') {
                 const again = parseArtifactSource(text, { defaultKind: 'broadcast' });
                 if (!again.ok)
@@ -792,10 +811,10 @@ export function createArtifactRoutes(config) {
         // Fail closed: private media needs a private store. Without one the media would have to sit in
         // the public bucket, which may carry a bucket-wide public read grant, so nothing is saved.
         // `media:` is sticky, so a stored page that already keeps private media counts too.
-        if (!keepsPrivateMedia() && (parsed.meta.privateMedia || (id && (await store.get(id))?.privateMedia)))
+        if (!keepsPrivateMedia() && (parsed.meta.privateMedia || (id && (await kept.get(id))?.privateMedia)))
             return NextResponse.json({ error: NO_PRIVATE_STORE }, { status: 501 });
         if (id && parsed.meta.state) {
-            const existing = await store.get(id);
+            const existing = await kept.get(id);
             const changed = shapeChanges(existing?.state, parsed.meta.state);
             if (changed.length)
                 return NextResponse.json({ error: changed.join('; ') }, { status: 400 });
@@ -822,7 +841,7 @@ export function createArtifactRoutes(config) {
         // `?amend=1` is the publisher finishing the publish it started (image URLs, then narration).
         const note = cleanNote(request.nextUrl.searchParams.get('note')) ?? parsed.meta.change;
         const amend = request.nextUrl.searchParams.get('amend') === '1';
-        const result = await store.save({ id, meta: parsed.meta, markdown: parsed.body, note, amend });
+        const result = await kept.save({ id, meta: parsed.meta, markdown: parsed.body, note, amend });
         if ('notFound' in result)
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         // A broadcast with no date gets one: 90 days from now. A date already set (by the sender, or
@@ -850,7 +869,7 @@ export function createArtifactRoutes(config) {
         if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         const { id } = await params;
-        const a = await store.get(id);
+        const a = await kept.get(id);
         if (!a)
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         return NextResponse.json({ id, text: narrationText({ title: a.title, subtitle: a.subtitle, summary: a.summary, markdown: a.markdown }) });
@@ -867,7 +886,7 @@ export function createArtifactRoutes(config) {
         const { id, name } = await params;
         if (!ARTIFACT_ID.test(id))
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
-        if (!(await store.get(id)))
+        if (!(await kept.get(id)))
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         if (!ASSET_NAME.test(name))
             return NextResponse.json({ error: 'asset name must be one path segment: letters, digits, dot, dash, underscore' }, { status: 400 });
@@ -917,7 +936,7 @@ export function createArtifactRoutes(config) {
         const { id, name } = await params;
         if (!ARTIFACT_ID.test(id))
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
-        if (!(await store.get(id)))
+        if (!(await kept.get(id)))
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         if (!ASSET_NAME.test(name))
             return NextResponse.json({ error: 'asset name must be one path segment: letters, digits, dot, dash, underscore' }, { status: 400 });
@@ -977,7 +996,7 @@ export function createArtifactRoutes(config) {
         if (!authed(request))
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         const { id } = await params;
-        if (!ARTIFACT_ID.test(id) || !(await store.get(id)))
+        if (!ARTIFACT_ID.test(id) || !(await kept.get(id)))
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         let files = 0;
         if (config.assets?.deletePage) {
@@ -995,7 +1014,7 @@ export function createArtifactRoutes(config) {
         catch (e) {
             return NextResponse.json({ error: `the page's readers could not be forgotten, so the page was kept; delete it again: ${e instanceof Error ? e.message : String(e)}` }, { status: 502 });
         }
-        const ok = await store.delete(id);
+        const ok = await kept.delete(id);
         if (!ok)
             return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
         revalidatePath(pagePath(id));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.47.0",
+  "version": "0.48.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",