@kernhq/module-inventory 0.2.0 → 0.4.0

package/src/client/widgets/RepairsWidget.svelte

@@ -0,0 +1,124 @@
+<script lang="ts">
+import { formatDate, type WidgetProps, WidgetState } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import type { RepairListItem } from '../../contract/index.js'
+import { getInventoryApi } from '../api-instance.js'
+import { isolated } from '../bidi.js'
+import { t } from '../i18n.js'
+import { assetHref } from '../links.js'
+import { inventoryKeys } from '../query.js'
+
+/**
+ * What is away being fixed, right now.
+ *
+ * A second card rather than a `view` setting on the first one, because this one is **behind a
+ * capability**: `capability: 'repairs'` in `module.ts` means the shell does not offer it at all to a
+ * workspace that does not record repairs, where an option inside a settings dropdown would offer
+ * the question and then answer it with an empty card. That is the whole difference between a switch
+ * that means something and a switch that does not.
+ *
+ * It asks `repairs.list` at workspace scope — the one question a per-asset list cannot answer — and
+ * the asset's tag and name arrive joined, so nothing here has to look an id up.
+ *
+ * A row opens the **asset**, not the repair: a repair has no screen of its own, and the panel's
+ * Repairs tab is where somebody logs it back in — which is the thing anybody reading "away since
+ * 3 March" actually wants to do next. `WidgetProps` is what carries the `workspaceSlug` that link
+ * needs; this file declared two props by hand and could therefore not build one.
+ */
+const { workspaceId, workspaceSlug, settings }: WidgetProps = $props()
+
+const limit = $derived(Number(settings?.limit ?? 5))
+const api = getInventoryApi()
+
+const filters = $derived({ open: true, limit })
+
+const repairs = createQuery(() => ({
+  queryKey: inventoryKeys.repairs(workspaceId, filters),
+  queryFn: () => api.repairs.list({ workspaceId, ...filters }),
+  enabled: Boolean(workspaceId),
+}))
+
+const items = $derived<readonly RepairListItem[]>(repairs.data?.items ?? [])
+</script>
+
+<WidgetState
+  pending={repairs.isPending}
+  error={repairs.error}
+  empty={!items.length}
+  emptyTitle={t('widget_repairs_empty')}
+  emptyIcon="wrench"
+  onRetry={() => repairs.refetch()}
+>
+  <ul>
+    {#each items as repair (repair.id)}
+      <li>
+        <!-- An anchor, so the keyboard route and the pointer route are one route. -->
+        <a class="row" href={assetHref(workspaceSlug, repair.assetId)}
+          aria-label={t('open_asset', isolated({ name: repair.assetName }))}>
+          <span class="code">{repair.assetCode}</span>
+          <span class="name">{repair.assetName}</span>
+          <span class="since">
+            {t('repair_away_since', isolated({ date: formatDate(repair.sentOn) }))}
+          </span>
+        </a>
+      </li>
+    {/each}
+  </ul>
+</WidgetState>
+
+<style>
+  ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+  }
+  .row {
+    display: flex;
+    align-items: baseline;
+    gap: 10px;
+    font-size: 13px;
+    min-width: 0;
+    color: inherit;
+    text-decoration: none;
+    /* Ten vertical pixels take the row past the 24px WCAG 2.5.8 target height; the inline padding
+       is given back by an equal negative margin, so the card's own gutter is unchanged. */
+    padding-block: 5px;
+    padding-inline: 6px;
+    margin-inline: -6px;
+    border-radius: var(--kern-r-sm);
+  }
+  .row:hover {
+    background: var(--kern-surface-hover);
+  }
+  .code {
+    font-size: 11px;
+    color: var(--kern-ink-500);
+    font-variant-numeric: tabular-nums;
+    min-width: 64px;
+    /* A tag is read character by character off a sticker, so it stays left-to-right inside a
+       Persian or Arabic card and the bidi algorithm does not reorder its digits. */
+    direction: ltr;
+    unicode-bidi: isolate;
+  }
+  .name {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: var(--kern-ink-900);
+    /* A value somebody typed decides its own direction: `plaintext` takes it from the value's
+       first strong character, so a Latin name inside a Persian screen reads left to right and
+       keeps its own trailing punctuation instead of donating it to the paragraph. */
+    unicode-bidi: plaintext;
+  }
+  .since {
+    flex: none;
+    font-size: 11px;
+    /* Muted with a colour, never opacity: a faded line is unreadable whatever its token says. */
+    color: var(--kern-ink-500);
+  }
+</style>

package/src/contract/capabilities.ts

@@ -22,22 +22,60 @@ import { defineCapabilities } from '@kernhq/contracts'
  *   the rows stay exactly where they are. Anything that would need data thrown away to reverse is
  *   not a capability, however much it looks like one.
  *
- * The rest arrive with the work that makes them mean something: `repairs`, `attachments` and
- * `labels` with the finished register; `custom_fields` and `locations` beside them; `stock` and
- * `procurement` with stock control; `depreciation` and `reservations` last. Adding one here before
- * its procedures exist is the mistake this comment is here to prevent.
+ * The rest arrive with the work that makes them mean something: `labels` with the finished register;
+ * `custom_fields` and `locations` beside them; `stock` and `procurement` with stock control;
+ * `depreciation` and `reservations` last. Adding one here before its procedures exist is the mistake
+ * this comment is here to prevent.
  */
 export const inventoryCapabilities = defineCapabilities([
   {
     id: 'core',
     label: 'Assets',
-    // Says only what the module answers today. Custody and the change history are what the schema
-    // is shaped for and neither has a procedure yet, so naming them here promised a workspace two
-    // features it would then go looking for.
-    description: 'The asset register: what the company owns, item by item',
+    // Says only what the module answers today, which is the rule this line has been held to in both
+    // directions: custody and the change history were taken *out* of it while neither had a
+    // procedure, and put back in the change that gave them one.
+    description:
+      'The asset register: what the company owns item by item, who is holding each one, and how each one got there',
     required: true,
     level: 1,
   },
+  {
+    /**
+     * The first capability anyone can actually switch, and the reason it is one is the shape of the
+     * customers: an office that hands out laptops wants a register and never records a repair,
+     * while a company with a workshop wants little else. One answer for the whole workspace, not
+     * per person — so a capability rather than a permission — and switching it off writes a boolean
+     * into module settings and leaves every repair row exactly where it was.
+     *
+     * `dependsOn: ['core']` says the obvious out loud: a repair is a trip *an asset* made, so there
+     * is nothing to record without the register. It also means the closure prunes this
+     * automatically if `core` could ever be off, rather than each screen remembering to check two
+     * switches.
+     */
+    id: 'repairs',
+    label: 'Repairs',
+    description:
+      'What went away to be fixed, to whom, what it cost and when it came back — and the `under repair` status that follows an open one',
+    dependsOn: ['core'],
+    defaultEnabled: true,
+    level: 1,
+  },
+  {
+    /**
+     * Files against an asset or a repair — a purchase receipt, a warranty card, a repair invoice.
+     *
+     * Separate from `repairs` because plenty of workspaces want one without the other: an office
+     * that keeps receipts and never records a repair, and a workshop that records repairs and keeps
+     * no paperwork. Switching it off hides the Files tab and answers 404; the rows and the files in
+     * core's storage are untouched, which is what makes it a capability rather than a migration.
+     */
+    id: 'attachments',
+    label: 'Files',
+    description: 'Receipts, warranties and manuals kept against an asset or one of its repairs',
+    dependsOn: ['core'],
+    defaultEnabled: true,
+    level: 1,
+  },
 ])
 
 export type InventoryCapabilityId = (typeof inventoryCapabilities)[number]['id']
@@ -52,4 +90,10 @@ export type InventoryCapabilityId = (typeof inventoryCapabilities)[number]['id']
  * A procedure absent from this map belongs to the module as a whole and is reachable whenever
  * Inventory is on — which for `core` is always, because it is `required`.
  */
-export const inventoryCapabilityProcedures: Record<string, readonly string[]> = {}
+export const inventoryCapabilityProcedures: Record<string, readonly string[]> = {
+  repairs: ['repairs.list', 'repairs.create', 'repairs.update', 'repairs.complete'],
+  attachments: ['attachments.list', 'attachments.add', 'attachments.remove'],
+  // `stats.summary` is deliberately absent. It counts assets, which is `core`, and it answers
+  // `outForRepair: null` rather than a number when the workspace has `repairs` off — a count line
+  // and a dashboard card must not disappear because a *different* feature is switched off.
+}

package/src/contract/events.ts

@@ -31,4 +31,53 @@ export const inventoryEvents = {
     'inventory.asset.restored',
     z.object({ assetId: z.uuid(), workspaceId: WorkspaceId }),
   ),
+  /**
+   * One event for all three of assign, transfer and return, because a subscriber cares that the
+   * answer to "who has it" moved and not by which verb.
+   *
+   * `userId` is null when it came back to stock and `previousUserId` is null when it went out from
+   * stock, so the pair says which of the three happened without a fourth field claiming to. Both
+   * are ids, like everything else here: a subscriber that needs the person asks core with its own
+   * principal, so an event cannot become a way to read a name past a permission check.
+   *
+   * Nothing subscribes to it inside this module. It exists for what is outside — an offboarding
+   * automation that asks what somebody still holds, most obviously — which is the whole reason a
+   * module emits events rather than only writing its own history row.
+   */
+  custodyChanged: defineEvent(
+    'inventory.custody.changed',
+    z.object({
+      assetId: z.uuid(),
+      workspaceId: WorkspaceId,
+      userId: z.uuid().nullable(),
+      previousUserId: z.uuid().nullable(),
+    }),
+  ),
+  /**
+   * An item went to a repairer, and an item came back.
+   *
+   * Two events rather than one, where custody has one for three verbs — because a subscriber to
+   * custody cares only that "who has it" moved, while these two are opposite facts with opposite
+   * reactions: something outside this module wants to tell the holder their laptop has gone, and
+   * something else wants to tell them it is back. A single `repair.changed` would make every
+   * subscriber re-read the row to find out which happened.
+   *
+   * No `repair.updated`: correcting a vendor or filling in an invoice a week later is not a fact
+   * anything outside this module reacts to, and the screens that do care are refreshed by
+   * `kernel.realtime.change`, which needs no declaration. Declaring one so the set looks symmetrical
+   * is the same lie as a capability nothing checks.
+   */
+  repairOpened: defineEvent(
+    'inventory.repair.opened',
+    z.object({ assetId: z.uuid(), repairId: z.uuid(), workspaceId: WorkspaceId }),
+  ),
+  repairCompleted: defineEvent(
+    'inventory.repair.completed',
+    z.object({ assetId: z.uuid(), repairId: z.uuid(), workspaceId: WorkspaceId }),
+  ),
+  // No category and no attachment events, deliberately. An event is for something outside this
+  // module to react to, and nothing outside it has an opinion about a workspace renaming "Laptops"
+  // or filing a receipt; the screens that do care are refreshed by `kernel.realtime.change`, which
+  // needs no declaration. Declaring one here so the list looks complete is the same lie as a
+  // capability nothing checks.
 }

package/src/contract/index.ts

@@ -10,6 +10,7 @@
 export * from './capabilities.js'
 export * from './events.js'
 export * from './models.js'
+export * from './notifications.js'
 export * from './permissions.js'
 export * from './router.js'
 export * from './settings.js'

package/src/contract/models.ts

@@ -18,6 +18,12 @@ export const MODULE_ID = 'inventory'
  *
  * Stored rather than derived, because every list filter asks for it — and kept in step inside the
  * same transaction that writes the row it derives from, never by a job afterwards.
+ *
+ * **`under_repair` belongs to the `repairs` capability**, so a workspace with that switch off never
+ * has an asset in it: the procedure that ends a repair answers 404 there, and a status nothing can
+ * move an item out of is a register the workspace cannot correct. The one thing a job does here is
+ * bring the rows *nobody touches* back into step after that switch moves, in both directions —
+ * `deriveStatus` in `src/server/services/status.ts` argues it, and nothing is destroyed either way.
  */
 export const AssetStatus = z.enum(['in_stock', 'assigned', 'reserved', 'under_repair', 'lost', 'retired'])
 export type AssetStatus = z.infer<typeof AssetStatus>
@@ -32,6 +38,119 @@ export type AssetStatus = z.infer<typeof AssetStatus>
 export const CustomValues = z.record(z.string(), z.unknown())
 export type CustomValues = z.infer<typeof CustomValues>
 
+/**
+ * A workspace's own grouping of what it owns — Laptops, Furniture, Cameras.
+ *
+ * Archived rather than deleted, and `archivedAt` is the whole reason: `assets.category_id` is a
+ * plain uuid with no foreign key, so a deleted category leaves every asset filed under it pointing
+ * at a row that is not there. The list column goes blank and the timeline entry that recorded the
+ * move loses the name it recorded. Archiving takes it out of every picker and every filter and
+ * leaves each asset able to say what it is.
+ */
+export const Category = z.object({
+  id: z.uuid(),
+  workspaceId: WorkspaceId,
+  name: z.string().min(1).max(120),
+  /**
+   * Where it sits in the sequence. **Storage, not a setting.**
+   *
+   * Nobody thinks about their categories as integers, so no screen shows this number and no input
+   * accepts one: `categories.reorder` takes the ids in the order somebody dragged them into and
+   * renumbers the live ones `0…n-1` in one transaction. `create` and a restore append, so two live
+   * categories never share a value — which is the state a "position" field invited on every save.
+   *
+   * The name is still the tiebreak in `list`, because a workspace seeded before this existed, or a
+   * row written by hand, can still hold a duplicate; it just stops being the ordinary case.
+   */
+  order: z.number().int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  archivedAt: z.string().nullable(),
+})
+export type Category = z.infer<typeof Category>
+
+/**
+ * What a person types when they add or rename a category: a name, and nothing else.
+ *
+ * `order` used to be here, optional, and it was the only way to move a category — a number field on
+ * a settings form, with a hint explaining that lower comes first and that ties fall back to names.
+ * The sequence is written by `categories.reorder` now, so an `order` on create or update would be a
+ * second way to set the same thing, disagreeing with the first the moment anybody used it.
+ */
+export const CategoryInput = z.object({
+  name: z.string().trim().min(1).max(120),
+})
+export type CategoryInput = z.infer<typeof CategoryInput>
+
+/**
+ * How many categories one workspace may have live at once — and the reason it is a *stated* limit.
+ *
+ * `categories.reorder` has to name every live category exactly once, so its input array needs a
+ * bound; every zod array that a client fills does, or a single request can ask the server to hold an
+ * arbitrary list in memory. A bound on that array alone is a **silent ceiling**: a workspace with
+ * more live categories than the number could still create, rename and archive them, and only
+ * reordering would fail — the one procedure with no other way to do the job.
+ *
+ * So the same number is enforced where somebody meets it. `categories.create` and a restore both
+ * refuse with `inventory.category.limit_reached` once a workspace holds this many live categories,
+ * which is a sentence naming the number at the moment it matters. Archiving one frees a place, which
+ * is why the limit counts the **live** rows rather than every row ever made: the advice the refusal
+ * gives has to be true.
+ */
+export const MAX_LIVE_CATEGORIES = 500
+
+/**
+ * One stretch of time during which one person held one asset.
+ *
+ * Effective-dated, exactly as HR keeps employments: nothing is ever updated in place, a change
+ * closes the open row and inserts a new one. `effectiveTo === null` means "still holding it", and
+ * `inventory_custody_no_overlap` — a GiST exclusion constraint on
+ * `(asset_id =, tstzrange(effective_from, effective_to, '[)') &&)` — makes two of those for one
+ * asset impossible in the database rather than merely unlikely in the service.
+ */
+export const CustodyPeriod = z.object({
+  id: z.uuid(),
+  workspaceId: WorkspaceId,
+  assetId: z.uuid(),
+  /**
+   * The member who held it. A plain uuid — a cross-schema foreign key is what the module boundary
+   * exists to prevent — resolved against core membership at read time, which is also why a person
+   * who has since left the workspace still has readable history.
+   */
+  userId: z.uuid(),
+  note: z.string().max(500).nullable(),
+  effectiveFrom: z.string(),
+  effectiveTo: z.string().nullable(),
+  /** Who did the handing over, which is not always who received it. */
+  createdBy: z.uuid().nullable(),
+  createdAt: z.string(),
+})
+export type CustodyPeriod = z.infer<typeof CustodyPeriod>
+
+/**
+ * One entry in an asset's timeline.
+ *
+ * `action` is a **plain string, deliberately not an enum**. The rows are append-only and outlive
+ * the image that wrote them: an instance rolled back to a previous release would fail to parse its
+ * own history the moment a newer image had written an action the older enum does not list — a
+ * timeline that 500s rather than one that says a little less. The client renders a sentence per
+ * action it knows and a neutral one for anything else. What is written today is `created`,
+ * `updated`, `assigned`, `transferred`, `returned`, `retired`, `restored`, `repair_logged`,
+ * `repair_completed`, `attachment_added` and `attachment_removed`.
+ */
+export const AssetHistoryEntry = z.object({
+  id: z.uuid(),
+  assetId: z.uuid(),
+  /** Null for anything the platform did rather than a person. */
+  actorId: z.uuid().nullable(),
+  action: z.string().max(40),
+  changes: z.array(z.object({ field: z.string(), from: z.unknown(), to: z.unknown() })),
+  /** Action-specific ids — who received an item, who handed it over. Never a row. */
+  data: z.record(z.string(), z.unknown()),
+  occurredAt: z.string(),
+})
+export type AssetHistoryEntry = z.infer<typeof AssetHistoryEntry>
+
 export const Asset = z.object({
   id: z.uuid(),
   workspaceId: WorkspaceId,
@@ -63,6 +182,157 @@ export const Asset = z.object({
 })
 export type Asset = z.infer<typeof Asset>
 
+/**
+ * What a custody procedure answers with: the asset as it now stands, and the period this call
+ * opened.
+ *
+ * Both, because a screen needs both and fetching the asset again afterwards is a second round trip
+ * that can read a row somebody else has changed in between — the panel would then show a handover
+ * that has already been undone. `period` is null on a return: something closed, nothing opened.
+ */
+export const CustodyResult = z.object({
+  asset: Asset,
+  period: CustodyPeriod.nullable(),
+})
+export type CustodyResult = z.infer<typeof CustodyResult>
+
+/**
+ * One trip an item made to a repairer.
+ *
+ * `returnedOn === null` means it is still away, and that single fact is what puts the asset in
+ * `under_repair` — see `deriveStatus` in `src/server/services/status.ts`, which is the only place
+ * the three columns that drive a status are read together.
+ *
+ * **A repair is not custody, and neither one cancels the other.** A laptop assigned to Dan that goes
+ * to the repairer is still Dan's responsibility: the custody period stays open, `custodianUserId`
+ * stays set, and only `status` moves. That is why a repair does not touch custody and custody does
+ * not refuse a repaired item — the two answer different questions ("who is answerable for it" and
+ * "where is it"), and collapsing them would mean an item could not come back to the person who sent
+ * it.
+ */
+export const Repair = z.object({
+  id: z.uuid(),
+  workspaceId: WorkspaceId,
+  assetId: z.uuid(),
+  summary: z.string().min(1).max(200),
+  detail: z.string().max(4000).nullable(),
+  vendor: z.string().max(200).nullable(),
+  /** Minor units, like `Asset.priceMinor` — one convention for money across the module. */
+  costMinor: z.number().int().nullable(),
+  currency: z.string().length(3).nullable(),
+  sentOn: z.string(),
+  /** Null while it is still away. Set by `repairs.complete` and by nothing else. */
+  returnedOn: z.string().nullable(),
+  createdBy: z.uuid().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+})
+export type Repair = z.infer<typeof Repair>
+
+/**
+ * A repair in a list, with the two things a reader needs to know *which item* it is about.
+ *
+ * **Joined at read time, never stored here.** `mod_inventory.repairs` holds no asset name, so
+ * renaming an asset renames it everywhere at once — a copied label is a label that goes stale, and
+ * this module already refuses to copy a person's name for the same reason. The join is inside one
+ * schema, which is the kind a module is allowed to make; the kind it is not is a join across the
+ * boundary into another module's tables.
+ *
+ * It extends `Repair` rather than replacing it, so a component that renders a repair renders one of
+ * these without knowing the difference. `create`, `update` and `complete` answer with a plain
+ * `Repair`: the caller of those already knows which asset it asked about.
+ */
+export const RepairListItem = Repair.extend({
+  assetCode: z.string().min(1).max(40),
+  assetName: z.string().min(1).max(200),
+})
+export type RepairListItem = z.infer<typeof RepairListItem>
+
+/**
+ * Everything a person can say about a repair.
+ *
+ * **No field here carries `.default()`, for the reason `AssetInput` spells out**: `update` is built
+ * from `.partial()`, and `.partial()` does not strip a default — zod still substitutes it for a key
+ * the request never sent, so a patch that renames a repair would silently re-date it. `sentOn` is
+ * optional rather than defaulted for the same reason; `repairs.create` fills today's date on the
+ * server, which is the only clock this module trusts.
+ */
+export const RepairInput = z.object({
+  summary: z.string().trim().min(1).max(200),
+  detail: z.string().max(4000).nullish(),
+  vendor: z.string().max(200).nullish(),
+  costMinor: z.number().int().min(0).nullish(),
+  currency: z.string().length(3).nullish(),
+  /** `sent_on` is `not null` in the database, so this is optional but never nullable. */
+  sentOn: z.iso.date().optional(),
+})
+export type RepairInput = z.infer<typeof RepairInput>
+
+export const RepairPatchInput = RepairInput.partial()
+export type RepairPatchInput = z.infer<typeof RepairPatchInput>
+
+/**
+ * What a repair mutation answers with: the repair, and the asset as it now stands.
+ *
+ * Both, for the reason `CustodyResult` carries both — sending an item away moves `assets.status`,
+ * and a screen that had to fetch the asset again afterwards would be reading a row somebody else
+ * may have changed in between.
+ */
+export const RepairResult = z.object({
+  repair: Repair,
+  asset: Asset,
+})
+export type RepairResult = z.infer<typeof RepairResult>
+
+/**
+ * A file recorded against an asset — a receipt, a warranty card, a manual.
+ *
+ * **The bytes are core's, not this module's.** A module does not upload: the browser uploads through
+ * core's file service and hands this module the id it was given, and reading one back is a download
+ * URL core signs. All that lives here is the fact that this asset has that file, plus the name and
+ * size copied at attach time so a list can be drawn without asking core once per row.
+ *
+ * `repairId` is what separates "the invoice for the screen replacement" from "the purchase receipt":
+ * null means it belongs to the asset itself.
+ */
+export const Attachment = z.object({
+  id: z.uuid(),
+  workspaceId: WorkspaceId,
+  assetId: z.uuid(),
+  repairId: z.uuid().nullable(),
+  fileId: z.uuid(),
+  name: z.string().max(300),
+  mimeType: z.string().max(200).nullable(),
+  /** Bytes, as core reported them when the file was attached. */
+  size: z.number().int().nullable(),
+  uploadedBy: z.uuid().nullable(),
+  createdAt: z.string(),
+})
+export type Attachment = z.infer<typeof Attachment>
+
+/**
+ * The register in numbers: what a page's count line and a dashboard card need in one request.
+ *
+ * `total` counts what the list shows by default — live rows — and `archived` is beside it rather
+ * than inside it, because a count line that silently included archived rows would disagree with the
+ * list under it.
+ *
+ * **`outForRepair` is null when the workspace does not track repairs.** Zero would be a claim
+ * ("nothing is away"), and a workspace with the `repairs` capability off has not made that claim —
+ * it has no opinion at all. The screens show the tile only when a number arrives, which is the same
+ * rule as hiding the Repairs tab, expressed in the data instead of in a second capability lookup.
+ */
+export const InventoryStats = z.object({
+  total: z.number().int().nonnegative(),
+  archived: z.number().int().nonnegative(),
+  /** Every status, zero-filled, so a screen can render the set without knowing which exist. */
+  byStatus: z.record(AssetStatus, z.number().int().nonnegative()),
+  outForRepair: z.number().int().nonnegative().nullable(),
+  /** Live assets nobody is holding — what is actually available to hand out. */
+  unassigned: z.number().int().nonnegative(),
+})
+export type InventoryStats = z.infer<typeof InventoryStats>
+
 /**
  * How a list is ordered, and therefore what a page cursor is a bookmark *into*.
  *

package/src/contract/notifications.ts

@@ -0,0 +1,73 @@
+import type { core } from '@kernhq/contracts'
+
+/**
+ * What Inventory will interrupt somebody about.
+ *
+ * Four things, and each of them changes what somebody has to *do*. That is the test: a rename, a new
+ * category, an item coming back — those are facts a screen shows when somebody looks, and a
+ * notification type nobody wants is a notification type everybody switches off along with the one
+ * that mattered.
+ *
+ * A type declared here and never sent is the same lie as a permission nothing checks. Each of these
+ * names its sender, and every one of them exists:
+ *
+ * - `custody.assigned` — `CustodyService`, on `assign` and `transfer`.
+ * - `warranty.expiring` — the `warranty-sweep` job, once per asset.
+ * - `repair.overdue` — the `repair-overdue` job, once per repair.
+ * - `custody.return_due` — the offboarding subscription, when HR says somebody has left or core says
+ *   they have been removed from the workspace.
+ *
+ * The keys keep their `inventory.custody.*` spelling rather than being renamed to
+ * `inventory.asset.*`: a notification type is the key a person's own preferences are stored under,
+ * so renaming one silently resets everybody who had switched it off.
+ */
+export const inventoryNotificationTypes: core.NotificationTypeDef[] = [
+  {
+    /**
+     * Everybody who has ever found a laptop on their desk with no idea it was now theirs is the
+     * reason this is `urgent` and reaches email — an asset register that records a handover the
+     * recipient never learns about has recorded an argument for later.
+     */
+    type: 'inventory.custody.assigned',
+    label: 'An item was handed to you',
+    description: 'Somebody made you the holder of an asset in the register.',
+    defaults: { inapp: true, push: true, email: true },
+    urgent: true,
+  },
+  {
+    /**
+     * Not urgent, and email is off by default. A warranty running out in a month is a thing to plan
+     * for, not a thing to stop for — and it arrives on a schedule rather than because somebody did
+     * something, which is exactly the kind of message that trains people to ignore the rest.
+     */
+    type: 'inventory.warranty.expiring',
+    label: 'A warranty is about to run out',
+    description: "An item's warranty expires soon. Sent once per item, to whoever is holding it.",
+    defaults: { inapp: true, push: false, email: false },
+    urgent: false,
+  },
+  {
+    /**
+     * Push, because this one is an action somebody has to take — ring the repairer — and nobody
+     * goes looking for it. Still not urgent: a laptop that has been away a fortnight can wait until
+     * the phone is picked up.
+     */
+    type: 'inventory.repair.overdue',
+    label: 'A repair has been away too long',
+    description: 'An item sent for repair has not been logged as returned. Sent once per repair.',
+    defaults: { inapp: true, push: true, email: false },
+    urgent: false,
+  },
+  {
+    /**
+     * Somebody is leaving and still has company property. Email, because it is a list of things to
+     * collect from a person who may not be at their desk much longer, and an in-app badge nobody
+     * opens until Monday is how a laptop leaves the building.
+     */
+    type: 'inventory.custody.return_due',
+    label: 'Somebody leaving still holds company property',
+    description: 'A member has left, or is leaving, and items are still recorded as theirs.',
+    defaults: { inapp: true, push: true, email: true },
+    urgent: true,
+  },
+]