@wtfalch/threads 0.1.0 → 0.2.0

package/dist/audit.d.ts

@@ -0,0 +1,74 @@
+import type { Db } from './threads.js';
+/**
+ * The moderation events this package can write, when the host hands
+ * `createThreads` a writer. Declared here so the host can merge them into
+ * its ledger's vocabulary before it binds the writer; the names sit in the
+ * `thread` namespace and nowhere else, which is what lets a host bind the
+ * writer to that namespace alone. `tenantVisible` is false throughout: a
+ * forum is one per app, not one per organisation.
+ */
+export declare const THREADS_AUDIT_EVENTS: {
+    readonly 'thread.pinned': {
+        readonly tenantVisible: false;
+    };
+    readonly 'thread.unpinned': {
+        readonly tenantVisible: false;
+    };
+    readonly 'thread.locked': {
+        readonly tenantVisible: false;
+    };
+    readonly 'thread.unlocked': {
+        readonly tenantVisible: false;
+    };
+    readonly 'thread.hidden': {
+        readonly tenantVisible: false;
+    };
+    readonly 'thread.unhidden': {
+        readonly tenantVisible: false;
+    };
+    readonly 'thread.comment_hidden': {
+        readonly tenantVisible: false;
+    };
+    readonly 'thread.comment_unhidden': {
+        readonly tenantVisible: false;
+    };
+    readonly 'thread.moved': {
+        readonly tenantVisible: false;
+    };
+    readonly 'thread.status_changed': {
+        readonly tenantVisible: false;
+    };
+    readonly 'thread.marked_duplicate': {
+        readonly tenantVisible: false;
+    };
+    readonly 'thread.standing_changed': {
+        readonly tenantVisible: false;
+    };
+};
+export type ThreadsAuditAction = keyof typeof THREADS_AUDIT_EVENTS;
+/** One moderation act, as the host's writer receives it. The actor is the `who` the host's own gate admitted. */
+export interface ThreadsAuditEvent {
+    readonly action: ThreadsAuditAction;
+    readonly actor: {
+        readonly id: string;
+        readonly display: string;
+    };
+    readonly target: {
+        readonly type: 'thread' | 'thread_comment' | 'person';
+        readonly id: string;
+    };
+    readonly before?: unknown;
+    readonly after?: unknown;
+    /** The person the act was about, when that is not the actor: a standing change. */
+    readonly subject?: {
+        readonly class: 'human';
+        readonly id: string;
+    };
+}
+/**
+ * What a host passes as `createThreads({ audit })`: a writer already bound
+ * to its ledger and to the `thread` namespace (`@wtfalch/audit`'s
+ * `ledger.writer`, structurally). The package calls it inside the
+ * transaction that makes the change, so a refused row rolls the change back.
+ */
+export type ThreadsAudit = (event: ThreadsAuditEvent, tx: Db) => Promise<void>;

package/dist/audit.js

@@ -0,0 +1,22 @@
+/**
+ * The moderation events this package can write, when the host hands
+ * `createThreads` a writer. Declared here so the host can merge them into
+ * its ledger's vocabulary before it binds the writer; the names sit in the
+ * `thread` namespace and nowhere else, which is what lets a host bind the
+ * writer to that namespace alone. `tenantVisible` is false throughout: a
+ * forum is one per app, not one per organisation.
+ */
+export const THREADS_AUDIT_EVENTS = {
+    'thread.pinned': { tenantVisible: false },
+    'thread.unpinned': { tenantVisible: false },
+    'thread.locked': { tenantVisible: false },
+    'thread.unlocked': { tenantVisible: false },
+    'thread.hidden': { tenantVisible: false },
+    'thread.unhidden': { tenantVisible: false },
+    'thread.comment_hidden': { tenantVisible: false },
+    'thread.comment_unhidden': { tenantVisible: false },
+    'thread.moved': { tenantVisible: false },
+    'thread.status_changed': { tenantVisible: false },
+    'thread.marked_duplicate': { tenantVisible: false },
+    'thread.standing_changed': { tenantVisible: false },
+};

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from './schema.js';
 export * from './gates.js';
 export * from './tree.js';
 export * from './threads.js';
+export * from './audit.js';

package/dist/index.js

@@ -2,3 +2,4 @@ export * from './schema.js';
 export * from './gates.js';
 export * from './tree.js';
 export * from './threads.js';
+export * from './audit.js';

package/dist/threads.d.ts

@@ -1,4 +1,5 @@
 import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import type { ThreadsAudit } from './audit.js';
 import { type Gates, type Subject, type Who } from './gates.js';
 import { type Category, type Comment, type Person, type Thread, type ThreadStatus, schema } from './schema.js';
 /**
@@ -22,6 +23,8 @@ export interface ThreadsOptions {
     gates: Gates;
     limits?: Partial<Limits>;
     now?: () => Date;
+    /** The host's audit writer for moderation, bound to the `thread` namespace. Optional: without it, moderation leaves no trail here. */
+    audit?: ThreadsAudit;
 }
 export type Sort = 'activity' | 'newest' | 'votes';
 export interface ListOptions {

package/dist/threads.js

@@ -1,4 +1,4 @@
-import { and, asc, desc, eq, inArray, isNull, ne, sql } from 'drizzle-orm';
+import { and, asc, desc, eq, gt, inArray, isNull, ne, sql } from 'drizzle-orm';
 import { CATEGORY, ThreadsError, categorySubject, } from './gates.js';
 import { schema, threadCategories, threadComments, threadOutbox, threadPeople, threadSubscriptions, threadVotes, threads, } from './schema.js';
 export const DEFAULT_LIMITS = { threadsPerHour: 5, commentsPerTenMinutes: 30 };
@@ -18,6 +18,13 @@ export function createThreads(opts) {
     const { db, gates } = opts;
     const limits = { ...DEFAULT_LIMITS, ...opts.limits };
     const now = opts.now ?? (() => new Date());
+    const display = (who) => who.name ?? who.id;
+    /** Records a moderation act on the caller's transaction, when the host wants a trail. */
+    async function audited(tx, who, event) {
+        if (!opts.audit)
+            return;
+        await opts.audit({ ...event, actor: { id: who.id, display: display(who) } }, tx);
+    }
     async function mayRead(subject, who) {
         if (!(await gates.read(subject, who))) {
             throw new ThreadsError('forbidden', 'not allowed to read here');
@@ -70,10 +77,13 @@ export function createThreads(opts) {
     }
     async function underLimit(table, authorId, windowMs, max, what) {
         const since = new Date(now().getTime() - windowMs);
+        // `gt`, not a raw `sql` fragment: the operator maps the Date through the
+        // column's type, which every driver accepts; a bare Date parameter is
+        // refused by postgres-js and only happened to work on PGlite.
         const [row] = await db
             .select({ n: sql `count(*)::int` })
             .from(table)
-            .where(and(eq(table.authorId, authorId), sql `${table.createdAt} > ${since}`));
+            .where(and(eq(table.authorId, authorId), gt(table.createdAt, since)));
         if ((row?.n ?? 0) >= max)
             throw new ThreadsError('rate_limited', `too many ${what}, try later`);
     }
@@ -427,21 +437,40 @@ export function createThreads(opts) {
         return { t, who: await mayModerate(subjectOf(t), who) };
     }
     async function setFlag(who, threadId, flag, value) {
-        await moderated(who, threadId);
-        await db
-            .update(threads)
-            .set({ [flag]: value, updatedAt: sql `now()` })
-            .where(eq(threads.id, threadId));
+        const { t, who: mod } = await moderated(who, threadId);
+        if (t[flag] === value)
+            return;
+        const action = {
+            pinned: value ? 'thread.pinned' : 'thread.unpinned',
+            locked: value ? 'thread.locked' : 'thread.unlocked',
+            hidden: value ? 'thread.hidden' : 'thread.unhidden',
+        }[flag];
+        await db.transaction(async (tx) => {
+            await tx
+                .update(threads)
+                .set({ [flag]: value, updatedAt: sql `now()` })
+                .where(eq(threads.id, threadId));
+            await audited(tx, mod, { action, target: { type: 'thread', id: String(threadId) } });
+        });
     }
     async function hideComment(who, commentId, hidden = true) {
         const [c] = await db.select().from(threadComments).where(eq(threadComments.id, commentId));
         if (!c)
             throw new ThreadsError('not_found', 'no such comment');
-        await moderated(who, c.threadId);
-        await db
-            .update(threadComments)
-            .set({ hidden, updatedAt: sql `now()` })
-            .where(eq(threadComments.id, commentId));
+        const { who: mod } = await moderated(who, c.threadId);
+        if (c.hidden === hidden)
+            return;
+        await db.transaction(async (tx) => {
+            await tx
+                .update(threadComments)
+                .set({ hidden, updatedAt: sql `now()` })
+                .where(eq(threadComments.id, commentId));
+            await audited(tx, mod, {
+                action: hidden ? 'thread.comment_hidden' : 'thread.comment_unhidden',
+                target: { type: 'thread_comment', id: String(commentId) },
+                after: { threadId: c.threadId },
+            });
+        });
     }
     async function move(who, threadId, categoryId) {
         const { t } = await moderated(who, threadId);
@@ -450,18 +479,26 @@ export function createThreads(opts) {
         const cat = await categoryById(categoryId);
         if (!cat)
             throw new ThreadsError('not_found', 'no such category');
-        await mayModerate(categorySubject(categoryId), who);
-        await db
-            .update(threads)
-            .set({
-            subjectId: String(categoryId),
-            status: cat.kind === 'feedback' ? (t.status ?? 'open') : null,
-            updatedAt: sql `now()`,
-        })
-            .where(eq(threads.id, threadId));
+        const mod = await mayModerate(categorySubject(categoryId), who);
+        await db.transaction(async (tx) => {
+            await tx
+                .update(threads)
+                .set({
+                subjectId: String(categoryId),
+                status: cat.kind === 'feedback' ? (t.status ?? 'open') : null,
+                updatedAt: sql `now()`,
+            })
+                .where(eq(threads.id, threadId));
+            await audited(tx, mod, {
+                action: 'thread.moved',
+                target: { type: 'thread', id: String(threadId) },
+                before: { categoryId: t.subjectId },
+                after: { categoryId: String(categoryId) },
+            });
+        });
     }
     async function setStatus(who, threadId, status) {
-        const { t } = await moderated(who, threadId);
+        const { t, who: mod } = await moderated(who, threadId);
         if (t.status === null)
             throw new ThreadsError('invalid', 'only feedback has a status');
         if (t.status === status)
@@ -471,6 +508,12 @@ export function createThreads(opts) {
                 .update(threads)
                 .set({ status, updatedAt: sql `now()` })
                 .where(eq(threads.id, threadId));
+            await audited(tx, mod, {
+                action: 'thread.status_changed',
+                target: { type: 'thread', id: String(threadId) },
+                before: { status: t.status },
+                after: { status },
+            });
             const listeners = await tx
                 .select({ personId: threadSubscriptions.personId })
                 .from(threadSubscriptions)
@@ -487,11 +530,16 @@ export function createThreads(opts) {
     }
     /** The duplicate points at the original and its votes move there; a page redirects. */
     async function markDuplicate(who, threadId, ofId) {
-        const { t } = await moderated(who, threadId);
+        const { t, who: mod } = await moderated(who, threadId);
         const [original] = await db.select().from(threads).where(eq(threads.id, ofId));
         if (!original || original.id === t.id)
             throw new ThreadsError('not_found', 'no such original');
         await db.transaction(async (tx) => {
+            await audited(tx, mod, {
+                action: 'thread.marked_duplicate',
+                target: { type: 'thread', id: String(threadId) },
+                after: { duplicateOf: ofId },
+            });
             const votes = await tx.select().from(threadVotes).where(eq(threadVotes.threadId, threadId));
             if (votes.length > 0) {
                 await tx
@@ -513,8 +561,21 @@ export function createThreads(opts) {
     }
     /** Standing is per person, not per subject; the gate asked is `category:*`, the owner's. */
     async function setStanding(who, personId, standing) {
-        await mayModerate(categorySubject('*'), who);
-        await db.update(threadPeople).set({ standing }).where(eq(threadPeople.id, personId));
+        const mod = await mayModerate(categorySubject('*'), who);
+        const [before] = await db
+            .select({ standing: threadPeople.standing })
+            .from(threadPeople)
+            .where(eq(threadPeople.id, personId));
+        await db.transaction(async (tx) => {
+            await tx.update(threadPeople).set({ standing }).where(eq(threadPeople.id, personId));
+            await audited(tx, mod, {
+                action: 'thread.standing_changed',
+                target: { type: 'person', id: personId },
+                subject: { class: 'human', id: personId },
+                before: { standing: before?.standing ?? null },
+                after: { standing },
+            });
+        });
     }
     // ---- outbox ------------------------------------------------------------
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/threads",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Threads, comments, votes and subscriptions attached to a subject the host names: a forum, a feedback board, a comment section. Per-app Postgres, host-supplied gates, React on @wtfalch/design.",
   "repository": {
     "type": "git",
@@ -9,9 +9,7 @@
   },
   "license": "MIT",
   "type": "module",
-  "files": [
-    "dist"
-  ],
+  "files": ["dist"],
   "bin": {
     "threads-migrations": "./dist/bin/migrations.js"
   },
@@ -34,6 +32,12 @@
   "engines": {
     "node": ">=22.0.0"
   },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && mkdir -p dist/migrations && cp src/migrations/*.sql dist/migrations/ && cp src/react/threads.css dist/threads.css",
+    "prepack": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
   "peerDependencies": {
     "@wtfalch/design": ">=0.3.0",
     "drizzle-orm": ">=0.39.0",
@@ -59,14 +63,10 @@
     "@wtfalch/design": "^0.3.0",
     "drizzle-orm": "^0.39.3",
     "jsdom": "^30.0.1",
+    "postgres": "^3.4.5",
     "react": "^19",
     "react-dom": "^19",
     "typescript": "^5.9.0",
     "vitest": "^4.1.6"
-  },
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && mkdir -p dist/migrations && cp src/migrations/*.sql dist/migrations/ && cp src/react/threads.css dist/threads.css",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 William Tallis Falch
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.