@kernhq/module-inventory 0.1.2 → 0.3.0

package/src/server/services/attachments.ts

@@ -0,0 +1,215 @@
+import type { core } from '@kernhq/contracts'
+import { KernError, type Kernel, type Tx, uuidv7 } from '@kernhq/kernel'
+import { and, asc, eq } from 'drizzle-orm'
+import type { Attachment as AttachmentModel } from '../../contract/models.js'
+import { assets, attachments, repairs } from '../schema.js'
+import type { HistoryInput, NotifyService } from './notify.js'
+
+type Row = typeof attachments.$inferSelect
+
+/** What this module copies out of core's file record, and all it copies. */
+export interface FileFacts {
+  id: string
+  name: string
+  mimeType: string | null
+  size: number | null
+}
+
+/** The wire shape: drizzle gives Date objects for timestamps, the contract promises ISO strings. */
+export function toAttachment(row: Row): AttachmentModel {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId as AttachmentModel['workspaceId'],
+    assetId: row.assetId,
+    repairId: row.repairId,
+    fileId: row.fileId,
+    name: row.name,
+    mimeType: row.mimeType,
+    size: row.size,
+    uploadedBy: row.uploadedBy,
+    createdAt: row.createdAt.toISOString(),
+  }
+}
+
+/**
+ * Files kept against an asset — receipts, warranties, manuals, a repair invoice.
+ *
+ * **A module does not upload, and this class is what that sentence means in code.** The browser
+ * sends the bytes to core's file service and is handed an id; this records that the asset has that
+ * file, with the name and size copied at attach time so a list can be drawn without asking core once
+ * per row. Nothing here streams, signs, stores or deletes a byte — `remove` detaches, because the
+ * same file may be attached elsewhere and a module has no standing to destroy another module's row.
+ *
+ * The copied name is a snapshot on purpose: renaming a file in core does not rename it here, which
+ * is the same trade every module makes when it copies a label rather than joining across a schema
+ * boundary. What it buys is a files list that is one query rather than one query plus a call per row.
+ */
+export class AttachmentService {
+  constructor(
+    private readonly kernel: Kernel,
+    private readonly notify: NotifyService,
+  ) {}
+
+  /**
+   * What core knows about these files — **called before the transaction opens, never inside one.**
+   *
+   * `kernel.call` is a request to another service over the broker, and awaiting one while holding a
+   * pooled connection is the failure `AssetService.codeFormat` documents: the pool starves under
+   * concurrent writes, and an attach fails outright whenever core is briefly away. So the router
+   * gathers the facts first and hands them to `add`, which does nothing but write.
+   *
+   * Two checks, and the first one is the one that matters: **a file has to belong to this
+   * workspace.** The id arrives in the request, so without this a member of one workspace could
+   * attach another workspace's file and read its name and size back out of the list — the module
+   * boundary does not help here, because core answers this module as a service.
+   */
+  async describe(workspaceId: string, fileIds: readonly string[]): Promise<FileFacts[]> {
+    const unique = [...new Set(fileIds)]
+    const found = await Promise.all(
+      unique.map(async (id) => {
+        const file = await this.kernel.call<core.FileObject | null>('core.files.get', { id })
+        if (!file || file.workspaceId !== workspaceId)
+          throw KernError.badRequest('That file is not one this workspace can attach.')
+        if (file.status !== 'ready') throw KernError.badRequest('That file has not finished uploading yet.')
+        return {
+          id: file.id,
+          name: file.name,
+          mimeType: file.mimeType || null,
+          size: typeof file.size === 'number' ? file.size : null,
+        }
+      }),
+    )
+    return found
+  }
+
+  /**
+   * Every file on one asset, its repairs' included, oldest first.
+   *
+   * Not paged and not filtered by repair: one asset's files are bounded by how much paperwork one
+   * item collects, and the panel groups them in the browser. That is the one case where filtering
+   * client-side is right — the list is entirely loaded — and it is the opposite of what a paged
+   * asset list may do.
+   */
+  async list(tx: Tx, workspaceId: string, assetId: string): Promise<AttachmentModel[]> {
+    const rows = await tx
+      .select()
+      .from(attachments)
+      .where(and(eq(attachments.workspaceId, workspaceId), eq(attachments.assetId, assetId)))
+      .orderBy(asc(attachments.createdAt), asc(attachments.id))
+    return rows.map(toAttachment)
+  }
+
+  /**
+   * Record that this asset has these files.
+   *
+   * `onConflictDoNothing` on `(asset_id, file_id)`: attaching the same file to the same asset twice
+   * is not an error worth refusing — somebody pressed the button twice, or dropped the same receipt
+   * in again — and the second attempt simply adds nothing. The rows that *were* inserted come back,
+   * so the caller announces exactly what changed.
+   *
+   * An archived asset is deliberately allowed: finding the receipt for something you retired last
+   * month is a reason to file it, not a reason to be refused.
+   */
+  async add(
+    tx: Tx,
+    workspaceId: string,
+    actorId: string | null,
+    assetId: string,
+    repairId: string | null,
+    files: readonly FileFacts[],
+  ): Promise<{ rows: Row[]; activities: HistoryInput[] }> {
+    await this.requireAsset(tx, workspaceId, assetId)
+    if (repairId) await this.requireRepair(tx, workspaceId, assetId, repairId)
+    if (!files.length) return { rows: [], activities: [] }
+
+    const inserted = await tx
+      .insert(attachments)
+      .values(
+        files.map((file) => ({
+          id: uuidv7(),
+          workspaceId,
+          assetId,
+          repairId,
+          fileId: file.id,
+          name: file.name,
+          mimeType: file.mimeType,
+          size: file.size,
+          uploadedBy: actorId,
+        })),
+      )
+      .onConflictDoNothing({ target: [attachments.assetId, attachments.fileId] })
+      .returning()
+
+    /**
+     * One timeline entry per file, rather than one saying "3 files".
+     *
+     * A timeline is read to find out what happened to a thing, and "attached the purchase receipt"
+     * answers that where "attached 3 files" sends the reader looking. Attaching several at once is
+     * rare enough that the extra rows cost nothing.
+     */
+    const activities: HistoryInput[] = inserted.map((row) => ({
+      workspaceId,
+      assetId,
+      actorId,
+      action: 'attachment_added',
+      data: {
+        attachmentId: row.id,
+        name: row.name,
+        ...(row.repairId ? { repairId: row.repairId } : {}),
+      },
+    }))
+    for (const activity of activities) await this.notify.history(tx, activity)
+    return { rows: inserted, activities }
+  }
+
+  /** Detach one file. Core's copy of it is untouched — see the class docblock. */
+  async remove(
+    tx: Tx,
+    workspaceId: string,
+    actorId: string | null,
+    attachmentId: string,
+  ): Promise<{ row: Row; activity: HistoryInput }> {
+    const [row] = await tx
+      .select()
+      .from(attachments)
+      .where(and(eq(attachments.workspaceId, workspaceId), eq(attachments.id, attachmentId)))
+    if (!row) throw KernError.notFound('Attachment')
+
+    // Filtered by workspace as well as by id, like every other write in this module: `core`
+    // connects as a superuser with RLS bypassed, so the predicate in the statement is the only
+    // barrier there is, and a barrier that holds only because of what an earlier statement happened
+    // to do is not one.
+    await tx
+      .delete(attachments)
+      .where(and(eq(attachments.workspaceId, workspaceId), eq(attachments.id, attachmentId)))
+
+    const activity: HistoryInput = {
+      workspaceId,
+      assetId: row.assetId,
+      actorId,
+      action: 'attachment_removed',
+      data: { attachmentId: row.id, name: row.name },
+    }
+    await this.notify.history(tx, activity)
+    return { row, activity }
+  }
+
+  private async requireAsset(tx: Tx, workspaceId: string, assetId: string): Promise<void> {
+    const [row] = await tx
+      .select({ id: assets.id })
+      .from(assets)
+      .where(and(eq(assets.workspaceId, workspaceId), eq(assets.id, assetId)))
+    if (!row) throw KernError.notFound('Asset')
+  }
+
+  /** A repair the file is filed under has to be one of *this* asset's, not merely one that exists. */
+  private async requireRepair(tx: Tx, workspaceId: string, assetId: string, repairId: string): Promise<void> {
+    const [row] = await tx
+      .select({ id: repairs.id })
+      .from(repairs)
+      .where(
+        and(eq(repairs.workspaceId, workspaceId), eq(repairs.id, repairId), eq(repairs.assetId, assetId)),
+      )
+    if (!row) throw KernError.notFound('Repair')
+  }
+}

package/src/server/services/audience.ts

@@ -0,0 +1,77 @@
+import type { BuiltinRole, Principal } from '@kernhq/contracts'
+import type { Kernel } from '@kernhq/kernel'
+
+/**
+ * Who to tell when the thing that happened belongs to the workspace rather than to a person.
+ *
+ * Custody notifications have an obvious recipient — the person the item was handed to. A warranty
+ * running out on a spare in a cupboard, or a repair nobody has chased, does not: it belongs to
+ * whoever looks after the register. There is no "the office manager" field, and inventing one would
+ * be a setting somebody has to fill in before the feature works at all, so the question is asked of
+ * the permission system instead: **who may actually do the thing this message is asking for.**
+ *
+ * A warranty notice asks somebody to renew or replace, which is `inventory.asset.manage`. An overdue
+ * repair asks somebody to chase the vendor, which is `inventory.repair.manage`. Somebody leaving
+ * with a laptop asks somebody to take it back, which is `inventory.custody.manage`. Each message
+ * names the key it needs rather than settling for "the admins", because a workspace that gave its
+ * office manager a custom role did that on purpose.
+ */
+
+/** Most senior first, so the cap below keeps the people most likely to act. */
+const ROLE_RANK: Record<BuiltinRole, number> = { owner: 3, admin: 2, member: 1, guest: 0 }
+
+/**
+ * How many people one workspace-level notification may reach.
+ *
+ * A message sent to five thousand people is not a notification, it is a mailing list nobody reads —
+ * and on a large instance every member holds `inventory.asset.manage` by default, so an uncapped
+ * audience would be exactly that. Twenty is well past any real "who looks after the register" group
+ * and small enough that the check below stays a handful of calls rather than one per seat.
+ *
+ * The cap is applied **after** sorting by role, so the people it keeps are the senior ones rather
+ * than whichever rows the database happened to return first.
+ */
+const RECIPIENT_CAP = 20
+
+interface Member {
+  userId: string
+  role: BuiltinRole
+}
+
+/**
+ * The members of a workspace who genuinely hold a permission.
+ *
+ * Genuinely, not "hold the role it defaults to": `kernel.authz.can` reads custom roles and scope
+ * bindings as well as the built-in defaults, so a workspace that took `inventory.repair.manage` away
+ * from `member` and gave it to one custom role is answered correctly. Guessing from the role would
+ * have been one local call instead of a handful, and would have quietly told the wrong people.
+ *
+ * Every failure here is swallowed: this decides an audience for a best-effort notification, and a
+ * member whose principal core cannot produce right now is one fewer recipient, not a reason for a
+ * nightly sweep to stop half-way through a workspace.
+ */
+export async function membersWithPermission(
+  kernel: Kernel,
+  workspaceId: string,
+  permission: string,
+): Promise<string[]> {
+  const members = await kernel
+    .call<Member[]>('core.workspaces.members', { workspaceId })
+    .catch(() => [] as Member[])
+
+  const ordered = [...members].sort((a, b) => (ROLE_RANK[b.role] ?? 0) - (ROLE_RANK[a.role] ?? 0))
+
+  const allowed: string[] = []
+  for (const member of ordered) {
+    if (allowed.length >= RECIPIENT_CAP) break
+    const principal = await kernel
+      .call<Principal | null>('core.users.principal', { userId: member.userId })
+      .catch(() => null)
+    if (!principal) continue
+    const can = await kernel.authz
+      .can(principal, permission, { kind: 'workspace', workspaceId })
+      .catch(() => false)
+    if (can) allowed.push(member.userId)
+  }
+  return allowed
+}

package/src/server/services/categories.ts

@@ -0,0 +1,136 @@
+import { KernError, type Tx, uuidv7 } from '@kernhq/kernel'
+import { and, asc, eq, isNull } from 'drizzle-orm'
+import type { Category as CategoryModel } from '../../contract/models.js'
+import { categories } from '../schema.js'
+import { violated } from './db-errors.js'
+
+type Row = typeof categories.$inferSelect
+
+/** The unique index `0000_init.sql` put on (workspace_id, name). */
+const NAME_TAKEN = 'inventory_categories_ws_name_uq'
+
+/** The wire shape: drizzle gives Date objects for timestamps, the contract promises ISO strings. */
+export function toCategory(row: Row): CategoryModel {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId as CategoryModel['workspaceId'],
+    name: row.name,
+    order: row.order,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+    archivedAt: row.archivedAt?.toISOString() ?? null,
+  }
+}
+
+/**
+ * How a workspace groups what it owns.
+ *
+ * Small on purpose. A category is a name and a position in a list; everything interesting about an
+ * asset belongs to the asset. The one thing here worth reading twice is that nothing deletes — see
+ * `archive` below.
+ */
+export class CategoryService {
+  /**
+   * Ordered by `order` and then by name, which is what makes a workspace that never touches the
+   * order field still get an alphabetical picker rather than an arbitrary one — every row has
+   * `order` 0, so the tiebreak is doing all the work and has to be a name rather than an id.
+   */
+  async list(tx: Tx, workspaceId: string, includeArchived: boolean): Promise<CategoryModel[]> {
+    const filters = [eq(categories.workspaceId, workspaceId)]
+    if (!includeArchived) filters.push(isNull(categories.archivedAt))
+    const rows = await tx
+      .select()
+      .from(categories)
+      .where(and(...filters))
+      .orderBy(asc(categories.order), asc(categories.name))
+    return rows.map(toCategory)
+  }
+
+  async get(tx: Tx, workspaceId: string, categoryId: string): Promise<Row> {
+    const [row] = await tx
+      .select()
+      .from(categories)
+      .where(and(eq(categories.workspaceId, workspaceId), eq(categories.id, categoryId)))
+    if (!row) throw KernError.notFound('Category')
+    return row
+  }
+
+  /**
+   * A duplicate name is a `CONFLICT` with the name in it, never a 500.
+   *
+   * The unique index is what actually decides — checking first and inserting after is a race that
+   * two people adding "Laptops" at once will find — so the check is the insert, and the driver's
+   * 23505 is translated into a sentence rather than shown as "Failed query: insert into
+   * mod_inventory.categories …".
+   */
+  async create(tx: Tx, workspaceId: string, name: string, order: number): Promise<Row> {
+    try {
+      const [row] = await tx.insert(categories).values({ id: uuidv7(), workspaceId, name, order }).returning()
+      return row!
+    } catch (err) {
+      throw CategoryService.nameTaken(err, name)
+    }
+  }
+
+  async update(
+    tx: Tx,
+    workspaceId: string,
+    categoryId: string,
+    patch: { name?: string; order?: number },
+  ): Promise<Row> {
+    const previous = await this.get(tx, workspaceId, categoryId)
+    // `undefined` means "not mentioned". Neither field is nullable, so there is no "clear it" here
+    // and no reason for the `null`-versus-`undefined` care `assets.update` needs.
+    const values = {
+      name: patch.name ?? previous.name,
+      order: patch.order ?? previous.order,
+      updatedAt: new Date(),
+    }
+    try {
+      const [row] = await tx
+        .update(categories)
+        .set(values)
+        .where(and(eq(categories.workspaceId, workspaceId), eq(categories.id, categoryId)))
+        .returning()
+      return row!
+    } catch (err) {
+      throw CategoryService.nameTaken(err, values.name)
+    }
+  }
+
+  /**
+   * Archive and restore, which are one procedure because they are one column.
+   *
+   * **Nothing here deletes, and that is the decision this file exists to record.**
+   * `assets.category_id` carries no foreign key — a module keeps its ids plain — so a delete would
+   * leave every asset filed under this category pointing at a row that is not there: a blank column
+   * on the row, a picker that cannot explain what the asset used to be, and an `asset_history`
+   * entry saying "category changed to <nothing>". None of it recoverable, all of it caused by a
+   * settings screen. An archived category disappears from every picker and every filter and leaves
+   * each asset able to say what it is.
+   */
+  async archive(tx: Tx, workspaceId: string, categoryId: string, archived: boolean): Promise<Row> {
+    const [row] = await tx
+      .update(categories)
+      .set({ archivedAt: archived ? new Date() : null, updatedAt: new Date() })
+      .where(and(eq(categories.workspaceId, workspaceId), eq(categories.id, categoryId)))
+      .returning()
+    if (!row) throw KernError.notFound('Category')
+    return row
+  }
+
+  /**
+   * The unique index refused it, or something else did and must not be disguised.
+   *
+   * Rethrowing the original for anything that is not this constraint matters: turning every failed
+   * insert into "that name is taken" would hide a real fault behind a sentence a person would act
+   * on by renaming something, for ever.
+   */
+  private static nameTaken(err: unknown, name: string): unknown {
+    if (!violated(err, NAME_TAKEN)) return err
+    return KernError.conflict(
+      `This workspace already has a category called “${name}”.`,
+      'inventory.category.name_taken',
+    )
+  }
+}

package/src/server/services/cursor.ts

@@ -0,0 +1,104 @@
+import { KernError } from '@kernhq/kernel'
+
+/**
+ * The one page boundary this module issues, for every list it pages.
+ *
+ * **The bookmarked row's id, and the sort it was issued under.** Nothing else — in particular not
+ * the sort key itself, which is what it used to carry. That earlier shape (`{k: <sort key>, i:
+ * <id>}`) was wrong three separate ways, each of them reachable by anyone who could type into the
+ * address bar:
+ *
+ *   - **It could not be trusted.** `decode` checked only that `i` was a *string*, and `i` is
+ *     interpolated into `(col, id) < ($1, $2::uuid)`. `{"k":"x","i":"not-a-uuid"}` therefore
+ *     reached Postgres as a 22P02 nobody caught — an unhandled 500 and an error-level log line per
+ *     request, at the 600-a-minute the rate limiter allows.
+ *   - **It was not bound to its sort.** A cursor issued under `sort=recent` replayed under
+ *     `sort=code` compared a uuid against a code, so page two came back equal to page one and
+ *     "Load more" never ended.
+ *   - **It was unbounded.** `sort=name` on a 200-character Persian name encoded to 602 characters,
+ *     and `Cursor` in `@kernhq/contracts` is `max(512)` — so a long enough name broke "Load more"
+ *     with a validation error, in exactly the locales least likely to be tested.
+ *
+ * Carrying the id alone and reading the sort key back from that row in SQL answers all three: the
+ * cursor is a fixed ~60 characters whatever the name, a value that is not a uuid is refused before
+ * it is anywhere near the database, and a cursor whose sort disagrees with the request is refused
+ * rather than quietly misread. Base64 so nothing in the product is tempted to read it — it is a
+ * bookmark, not an offset, and its shape is this file's business.
+ *
+ * It lives here rather than in `assets.ts` because the repair list pages too, and a second bookmark
+ * format would be a second set of those three bugs. `src/client/mock.ts` mirrors this byte for
+ * byte; read them as one pair and change them as one pair.
+ *
+ * The asset timeline is the one list that does **not** use this one: it is ordered by a sequence
+ * rather than by a row id, so its bookmark is `SeqBookmark` below.
+ */
+export interface Bookmark<S extends string> {
+  i: string
+  s: S
+}
+
+export const encodeMark = <S extends string>(mark: Bookmark<S>): string =>
+  Buffer.from(JSON.stringify(mark), 'utf8').toString('base64url')
+
+/** Cheap and total, and it runs before the value can reach a `::uuid` cast. */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export function decodeMark<S extends string>(cursor: string, sort: S): Bookmark<S> {
+  const refuse = () => KernError.badRequest('That page marker is not one this list issued')
+  let parsed: Partial<Bookmark<S>> | null
+  try {
+    parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as Partial<Bookmark<S>> | null
+  } catch {
+    throw refuse()
+  }
+  if (typeof parsed?.i !== 'string' || !UUID.test(parsed.i)) throw refuse()
+  // One comparison covers both a sort this list never issues and a sort it issued under a
+  // *different* request. Either way the bookmark cannot be read against the ordering asked for,
+  // and pretending otherwise is what made "Load more" loop for ever.
+  if (parsed.s !== sort) throw refuse()
+  return { i: parsed.i, s: sort }
+}
+
+/**
+ * The other page boundary: a row's **sequence number**, and the sort it was issued under.
+ *
+ * The asset timeline is ordered by `asset_history.seq` rather than by the row id, because a uuidv7
+ * is only ordered to the millisecond and two entries written inside one — an attach and a detach, a
+ * create and its first entry — sort by ten random bytes. `schema.ts` argues that at the column. A
+ * bookmark into that ordering has to name the sequence value, so it is a number rather than a uuid
+ * and needs its own codec: handing `decodeMark` a number would have it refused as "not a uuid", and
+ * relaxing `decodeMark` to accept either is how one of the two shapes ends up unvalidated.
+ *
+ * It keeps all three properties the uuid bookmark has, and for the same reasons:
+ *
+ *   - **bounded** — a base64url of `{"n":<integer>,"s":"recent"}` is around forty characters
+ *     whatever the row, well inside `Cursor`'s `max(512)` in `@kernhq/contracts`;
+ *   - **checked before it reaches SQL** — anything that is not a safe positive integer is refused
+ *     here rather than interpolated into a `bigint` comparison for Postgres to reject as a 22P02;
+ *   - **bound to its sort** — a bookmark issued under one ordering is meaningless under another,
+ *     and reading it anyway is what made "Load more" loop for ever.
+ *
+ * `Number.isSafeInteger` is the upper bound as well as the type check: the column is a `bigint` and
+ * the sequence would have to hand out nine quadrillion history rows to reach it, but a cursor
+ * arrives from outside and `JSON.parse` will happily produce `1e400`.
+ */
+export interface SeqBookmark<S extends string> {
+  n: number
+  s: S
+}
+
+export const encodeSeqMark = <S extends string>(mark: SeqBookmark<S>): string =>
+  Buffer.from(JSON.stringify(mark), 'utf8').toString('base64url')
+
+export function decodeSeqMark<S extends string>(cursor: string, sort: S): SeqBookmark<S> {
+  const refuse = () => KernError.badRequest('That page marker is not one this list issued')
+  let parsed: Partial<SeqBookmark<S>> | null
+  try {
+    parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as Partial<SeqBookmark<S>> | null
+  } catch {
+    throw refuse()
+  }
+  if (typeof parsed?.n !== 'number' || !Number.isSafeInteger(parsed.n) || parsed.n < 1) throw refuse()
+  if (parsed.s !== sort) throw refuse()
+  return { n: parsed.n, s: sort }
+}