@igstack/app-catalog-backend-core 6.3.0 → 6.4.0

package/src/modules/feedback/service.ts

@@ -0,0 +1,295 @@
+import { getDbClient } from '../../db/client'
+import type { Actor } from '../visitor/visitorIdentity'
+
+/** How long an author may edit their own wording. */
+export const EDIT_WINDOW_MS = 60 * 60 * 1000
+
+export const MAX_BODY_LENGTH = 1000
+export const MAX_SUBJECT_LENGTH = 120
+export const MAX_ATTACHMENTS = 3
+
+/** One piece of feedback as a client sees it. Never carries an author hash. */
+export interface FeedbackView {
+  id: string
+  authorName: string
+  /** Null when the visitor sent a bare flag with no words. */
+  body: string | null
+  /** What they were looking for, on a catalog-level ask. Null on entry feedback. */
+  subject: string | null
+  /** Slug of the entry this is about, or null for a catalog-level ask. */
+  resourceSlug: string | null
+  /** Display name of that entry, so the tracker can label a row without a second query. */
+  resourceName: string | null
+  attachmentIds: string[]
+  status: 'applied' | 'acknowledged' | null
+  reviewerReply: string | null
+  /** When a maintainer last touched it — what "unread" is computed against. */
+  reviewedAt: string | null
+  createdAt: string
+  editedAt: string | null
+  /** Whether this browser wrote it — what makes Edit and Dismiss appear. */
+  isMine: boolean
+  /**
+   * The absolute instant this browser's edit window closes, or null when it is not
+   * theirs. Absolute rather than a remaining duration so a client with a skewed clock
+   * hides the control at the same moment the server starts refusing the edit.
+   */
+  canEditUntil: string | null
+}
+
+type Row = {
+  id: string
+  authorHash: string
+  authorAlias: string
+  body: string | null
+  subject: string | null
+  status: 'applied' | 'acknowledged' | null
+  reviewerReply: string | null
+  reviewedAt: Date | null
+  editedAt: Date | null
+  createdAt: Date
+  resource?: { slug: string; displayName: string } | null
+  attachments?: { id: string }[]
+}
+
+function toView(row: Row, actor: Actor | null): FeedbackView {
+  const isMine = !!actor && row.authorHash === actor.hash
+  return {
+    id: row.id,
+    authorName: row.authorAlias,
+    body: row.body,
+    subject: row.subject,
+    resourceSlug: row.resource?.slug ?? null,
+    resourceName: row.resource?.displayName ?? null,
+    attachmentIds: (row.attachments ?? []).map((a) => a.id),
+    status: row.status,
+    reviewerReply: row.reviewerReply,
+    reviewedAt: row.reviewedAt?.toISOString() ?? null,
+    createdAt: row.createdAt.toISOString(),
+    editedAt: row.editedAt?.toISOString() ?? null,
+    isMine,
+    canEditUntil: isMine
+      ? new Date(row.createdAt.getTime() + EDIT_WINDOW_MS).toISOString()
+      : null,
+  }
+}
+
+const WITH_RELATIONS = {
+  resource: { select: { slug: true, displayName: true } },
+  attachments: { select: { id: true } },
+} as const
+
+async function resourceIdForSlug(slug: string): Promise<string | null> {
+  const resource = await getDbClient().dbResource.findUnique({
+    where: { slug },
+    select: { id: true },
+  })
+  return resource?.id ?? null
+}
+
+export interface FeedbackList {
+  items: FeedbackView[]
+  /** Unreviewed count — what the badge shows. `status IS NULL` is the whole definition. */
+  openCount: number
+}
+
+/** Oldest first: a thread reads top to bottom. */
+export async function listFeedback(
+  resourceSlug: string,
+  actor: Actor | null,
+): Promise<FeedbackList> {
+  const resourceId = await resourceIdForSlug(resourceSlug)
+  if (!resourceId) return { items: [], openCount: 0 }
+
+  const rows = await getDbClient().dbFeedback.findMany({
+    where: { resourceId },
+    orderBy: { createdAt: 'asc' },
+    include: WITH_RELATIONS,
+  })
+  return {
+    items: rows.map((row) => toView(row, actor)),
+    openCount: rows.filter((row) => row.status === null).length,
+  }
+}
+
+/**
+ * Everything this browser filed, across entries, for the tracker.
+ *
+ * Sorted the way the tracker renders: unreviewed first, then newest. Postgres sorts
+ * NULLs last by default, so `status` ascending would bury the pending rows — hence the
+ * explicit two-key ordering rather than relying on the default.
+ */
+export async function listMyFeedback(
+  actor: Actor | null,
+): Promise<FeedbackView[]> {
+  if (!actor) return []
+  const rows = await getDbClient().dbFeedback.findMany({
+    where: { authorHash: actor.hash },
+    orderBy: [
+      { status: { sort: 'asc', nulls: 'first' } },
+      { createdAt: 'desc' },
+    ],
+    include: WITH_RELATIONS,
+  })
+  return rows.map((row) => toView(row, actor))
+}
+
+export class FeedbackError extends Error {
+  constructor(
+    readonly reason:
+      | 'not-found'
+      | 'not-author'
+      | 'window-closed'
+      | 'already-reviewed'
+      | 'empty'
+      | 'too-many-attachments',
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+function normaliseBody(body: string | undefined | null): string | null {
+  if (body === undefined || body === null) return null
+  const trimmed = body.trim()
+  // A bare flag is a valid signal, so empty is stored as absent rather than refused.
+  return trimmed ? trimmed.slice(0, MAX_BODY_LENGTH) : null
+}
+
+export interface AddFeedbackInput {
+  /** Omitted for a catalog-level ask. */
+  resourceSlug?: string
+  /** Required when there is no resourceSlug — it is the substance of the ask. */
+  subject?: string
+  body?: string
+  attachmentIds?: string[]
+}
+
+export async function addFeedback(
+  input: AddFeedbackInput,
+  actor: Actor,
+): Promise<FeedbackView> {
+  const { resourceSlug, subject, body, attachmentIds = [] } = input
+
+  if (!resourceSlug && !subject?.trim()) {
+    throw new FeedbackError(
+      'empty',
+      'Tell us which entry this is about, or what you were looking for',
+    )
+  }
+  if (attachmentIds.length > MAX_ATTACHMENTS) {
+    throw new FeedbackError(
+      'too-many-attachments',
+      `Up to ${MAX_ATTACHMENTS} images`,
+    )
+  }
+
+  let resourceId: string | null = null
+  if (resourceSlug) {
+    resourceId = await resourceIdForSlug(resourceSlug)
+    if (!resourceId) {
+      throw new FeedbackError('not-found', `Unknown resource: ${resourceSlug}`)
+    }
+  }
+
+  const row = await getDbClient().$transaction(async (tx) => {
+    const created = await tx.dbFeedback.create({
+      data: {
+        resourceId,
+        subject: resourceId
+          ? null
+          : subject!.trim().slice(0, MAX_SUBJECT_LENGTH),
+        authorHash: actor.hash,
+        authorAlias: actor.alias,
+        body: normaliseBody(body),
+      },
+      select: { id: true },
+    })
+
+    // Claim only images this browser uploaded and nobody has claimed yet, so an id
+    // guessed from someone else's upload cannot be pulled onto your feedback.
+    //
+    // `updateMany` with the conditions in the WHERE, rather than a nested `connect`:
+    // `connect` takes only the id, and because `feedbackId` is a single FK it would
+    // MOVE a claimed image off its owner's feedback instead of refusing.
+    if (attachmentIds.length > 0) {
+      await tx.dbFeedbackAttachment.updateMany({
+        where: {
+          id: { in: attachmentIds },
+          authorHash: actor.hash,
+          feedbackId: null,
+        },
+        data: { feedbackId: created.id },
+      })
+    }
+
+    return tx.dbFeedback.findUniqueOrThrow({
+      where: { id: created.id },
+      include: WITH_RELATIONS,
+    })
+  })
+  return toView(row, actor)
+}
+
+/**
+ * Load a row and check this actor may still change its wording.
+ *
+ * Enforced here, not in the UI: the control disappearing is a courtesy, and a request
+ * that arrives a second late must still be refused.
+ */
+async function loadOwnForEdit(id: string, actor: Actor) {
+  const row = await getDbClient().dbFeedback.findUnique({ where: { id } })
+  if (!row) throw new FeedbackError('not-found', 'This no longer exists')
+  if (row.authorHash !== actor.hash) {
+    throw new FeedbackError('not-author', 'Only the author can change this')
+  }
+  if (Date.now() > row.createdAt.getTime() + EDIT_WINDOW_MS) {
+    throw new FeedbackError(
+      'window-closed',
+      'Wording can only be changed in the first hour',
+    )
+  }
+  return row
+}
+
+export async function editFeedback(
+  id: string,
+  body: string,
+  actor: Actor,
+): Promise<FeedbackView> {
+  await loadOwnForEdit(id, actor)
+  const row = await getDbClient().dbFeedback.update({
+    where: { id },
+    data: { body: normaliseBody(body), editedAt: new Date() },
+    include: WITH_RELATIONS,
+  })
+  return toView(row, actor)
+}
+
+/**
+ * Withdraw your own feedback.
+ *
+ * Allowed for as long as nobody has reviewed it, with no time limit — the edit window
+ * exists to stop someone rewriting words others have already read, and that reasoning
+ * does not apply to withdrawing something no maintainer has acted on. Once reviewed it
+ * is public record carrying a maintainer's reply, so withdrawing would delete their
+ * answer; from then on it is refused.
+ */
+export async function dismissFeedback(
+  id: string,
+  actor: Actor,
+): Promise<{ id: string }> {
+  const row = await getDbClient().dbFeedback.findUnique({ where: { id } })
+  if (!row) throw new FeedbackError('not-found', 'This no longer exists')
+  if (row.authorHash !== actor.hash) {
+    throw new FeedbackError('not-author', 'Only the author can withdraw this')
+  }
+  if (row.status !== null) {
+    throw new FeedbackError(
+      'already-reviewed',
+      'This has been answered, so it stays on the entry',
+    )
+  }
+  await getDbClient().dbFeedback.delete({ where: { id } })
+  return { id }
+}

package/src/modules/{comments → visitor}/visitorIdentity.ts

@@ -18,6 +18,25 @@ export interface Visitor {
   alias: string
 }
 
+/** Who the server thinks is acting, whether or not they ever signed in. */
+export type ActorKind = 'user' | 'visitor'
+
+/**
+ * One identity for every surface that needs one.
+ *
+ * `hash` is the secret-derived half: it authorises editing and withdrawing, is stored on
+ * rows, and never leaves the server. `publicId` is the half a client may hold — it
+ * identifies without authorising, which is what analytics needs and what the httpOnly
+ * cookie deliberately cannot give it. Same split better-auth already uses between its
+ * session cookie and `user.id`.
+ */
+export interface Actor {
+  hash: string
+  publicId: string
+  alias: string
+  kind: ActorKind
+}
+
 const ADJECTIVES = [
   'Ancient',
   'Brave',
@@ -144,3 +163,68 @@ export function resolveVisitor(
   const hash = hashToken(token)
   return { hash, alias: aliasForHash(hash) }
 }
+
+/**
+ * A non-authorising id derived from the hash.
+ *
+ * Safe to hand a client: knowing it proves nothing and authorises nothing, because the
+ * check is always against the full hash of the cookie the browser actually sent.
+ */
+export function publicIdFromHash(hash: string): string {
+  return hash.slice(0, 16)
+}
+
+/**
+ * Who is acting, signed in or not.
+ *
+ * `userId` is passed in rather than looked up, so this stays synchronous and testable in
+ * a node environment — the caller already has the session when it builds the request
+ * context. When login arrives this starts returning `kind: 'user'` and nothing
+ * downstream has to change.
+ */
+export function resolveActor(
+  req: { headers: { cookie?: string } },
+  res?: Parameters<typeof resolveVisitor>[1],
+  userId?: string | null,
+): Actor | null {
+  if (userId) {
+    return {
+      hash: hashToken(`user:${userId}`),
+      publicId: publicIdFromHash(hashToken(`user:${userId}`)),
+      alias: aliasForHash(hashToken(`user:${userId}`)),
+      kind: 'user',
+    }
+  }
+  const visitor = resolveVisitor(req, res)
+  if (!visitor) return null
+  return {
+    hash: visitor.hash,
+    publicId: publicIdFromHash(visitor.hash),
+    alias: visitor.alias,
+    kind: 'visitor',
+  }
+}
+
+/**
+ * A deterministic identity from a seed, for tests and local development.
+ *
+ * Returns the raw token *and* its hash, so a database fixture and a browser cookie can
+ * refer to the same person: seed rows with `hash`, hand the browser `token`. Without
+ * this, nothing scoped to one visitor is testable — the cookie is httpOnly on purpose,
+ * so page scripts cannot set it.
+ */
+export function visitorFromSeed(seed: string): {
+  token: string
+  hash: string
+  publicId: string
+  alias: string
+} {
+  const token = createHash('sha256').update(`seed:${seed}`).digest('hex')
+  const hash = hashToken(token)
+  return {
+    token,
+    hash,
+    publicId: publicIdFromHash(hash),
+    alias: aliasForHash(hash),
+  }
+}

package/src/server/acTrpcContext.ts

@@ -1,5 +1,5 @@
 import type { AppCatalogCompanySpecificBackend } from '../types'
-import type { Visitor } from '../modules/comments/visitorIdentity'
+import type { Actor } from '../modules/visitor/visitorIdentity'
 import type { User } from 'better-auth/types'
 
 export interface AcTrpcContext {
@@ -7,25 +7,26 @@ export interface AcTrpcContext {
   user: User | null
   isAdmin: boolean
   /**
-   * The anonymous browser behind this request, independent of `user` — the catalog
-   * is browsable logged out, and comments are attributed to this instead. Null when
-   * the context was built without a response to issue the cookie on.
+   * Who is acting on this request — the signed-in user when there is one, otherwise the
+   * anonymous browser behind it. The catalog is browsable logged out and feedback is
+   * attributed to this rather than to `user`. Null when the context was built without a
+   * response to issue the cookie on.
    */
-  visitor: Visitor | null
+  actor: Actor | null
 }
 
 export interface AcTrpcContextOptions {
   companySpecificBackend: AppCatalogCompanySpecificBackend
   user?: User | null
   isAdmin?: boolean
-  visitor?: Visitor | null
+  actor?: Actor | null
 }
 
 export function createAcTrpcContext({
   companySpecificBackend,
   user = null,
   isAdmin = false,
-  visitor = null,
+  actor = null,
 }: AcTrpcContextOptions): AcTrpcContext {
-  return { companySpecificBackend, user, isAdmin, visitor }
+  return { companySpecificBackend, user, isAdmin, actor }
 }

package/src/server/controller.ts

@@ -8,7 +8,7 @@ import type { Resource } from '../types/common/appCatalogTypes'
 
 import type { BetterAuth } from '../modules/auth/auth'
 import { createAuthRouter } from '../modules/auth/authRouter.js'
-import { createCommentsRouter } from '../modules/comments/commentsRouter'
+import { createFeedbackRouter } from '../modules/feedback/feedbackRouter'
 import { publicProcedure, router, t } from './trpcSetup'
 import { z } from 'zod'
 
@@ -67,7 +67,7 @@ export function createTrpcRouter(
         }),
     }),
 
-    comments: createCommentsRouter(),
+    feedback: createFeedbackRouter(),
 
     // Auth routes (requires auth instance)
     auth: createAuthRouter(t, auth, options),

package/src/types/common/appCatalogTypes.ts

@@ -203,6 +203,18 @@ export interface Resource {
   tiers?: TierVariant[]
   /** Deep links that take one typed identifier — see {@link QuickJump}. */
   quickJumps?: QuickJump[]
+  /**
+   * What this resource's children are called, as a plural noun ("Accounts",
+   * "Namespaces", "Databases"). Set on the PARENT, not the children.
+   *
+   * The detail card names its children tab with this. Children are modelled as
+   * plain resources carrying a `parentSlug`, so nothing in the data says what
+   * kind of thing they are — and a tab reading "Accounts 430" tells the reader
+   * what is in there, where the generic fallback tells them nothing. Omit it and
+   * the card says "Resources"; only the handful of entries that actually have
+   * children need to set it.
+   */
+  childrenLabel?: string
 
   // --- Fields merged from former SubResource ---
   /** Slug of parent resource (undefined for top-level applications) */

package/src/types/common/approvalMethodTypes.ts

@@ -57,6 +57,18 @@ export type ApprovalMethod = {
    * Displayed approval method
    */
   displayName: string
+  /**
+   * One or two words for places that cannot afford `displayName`, above all the
+   * detail card's access tab — which names the route it describes, so the reader
+   * knows what they are in for before they open it.
+   *
+   * `displayName` is written to stand alone in prose and routinely will not fit:
+   * a name ending in "Bot" or "Portal" repeats what the context already says,
+   * and the longest in use runs past thirty characters. Falls back to
+   * `displayName` when unset, so this is only worth setting where that reads
+   * badly in a tab.
+   */
+  shortName?: string
   /**
    * Optionally - older name of approval method if there were migration in organization.
    */