@kernhq/module-inventory 0.1.0

package/src/client/module.ts

@@ -0,0 +1,96 @@
+import { defineClientModule } from '@kernhq/ui'
+import { inventoryMessageBundles, t } from './i18n.js'
+import { INVENTORY_PERMISSIONS } from './permissions.js'
+
+/**
+ * This module as the shell sees it.
+ *
+ * Everything the interface offers is declared here — navigation, routes, commands, widgets,
+ * settings pages, sidebars, presenters — and the shell renders whatever it finds. There are no
+ * route files in the app to keep in step: deleting this package removes the feature completely,
+ * which is the test of whether something is a module at all.
+ *
+ * Labels are **getters** because a module is defined once at import time while the interface
+ * language can change afterwards. Reading them on render keeps the rail in the language chosen.
+ */
+export const inventoryClientModule = defineClientModule({
+  id: 'inventory',
+  name: 'Inventory',
+  icon: 'briefcase',
+  messages: inventoryMessageBundles,
+
+  nav: [
+    {
+      id: 'inventory',
+      get label() {
+        return t('nav')
+      },
+      icon: 'briefcase',
+      href: '/inventory',
+      order: 55,
+      permission: INVENTORY_PERMISSIONS.view,
+    },
+  ],
+
+  /**
+   * Routes are declarations, not files. `:name` matches one segment and reaches the component as
+   * `params.name`; specificity decides ties, literal segments first.
+   */
+  routes: [
+    {
+      path: '/inventory',
+      component: () => import('./pages/AssetsPage.svelte'),
+      get title() {
+        return t('title')
+      },
+      permission: INVENTORY_PERMISSIONS.view,
+    },
+  ],
+
+  commands: [
+    {
+      id: 'inventory.open',
+      get label() {
+        return t('nav')
+      },
+      icon: 'briefcase',
+      permission: INVENTORY_PERMISSIONS.view,
+      run: (ctx) => ctx.navigate('/inventory'),
+    },
+  ],
+
+  widgets: [
+    {
+      id: 'inventory.recent',
+      get title() {
+        return t('widget_title')
+      },
+      get description() {
+        return t('widget_desc')
+      },
+      icon: 'briefcase',
+      permission: INVENTORY_PERMISSIONS.view,
+      sizes: ['m', 'l'],
+      defaultSize: 'm',
+      order: 55,
+      settings: [
+        {
+          kind: 'number',
+          key: 'limit',
+          get label() {
+            return t('common.setting_rows')
+          },
+          default: 5,
+          min: 3,
+          max: 20,
+        },
+      ],
+      component: () => import('./widgets/OverviewWidget.svelte'),
+    },
+  ],
+
+  /** A settings page's `id` is its URL: the shell mounts it at `/<ws>/settings/inventory/<id>`. */
+  settingsPages: [],
+})
+
+export default inventoryClientModule

package/src/client/pages/AssetsPage.svelte

@@ -0,0 +1,266 @@
+<script lang="ts">
+import {
+  Badge,
+  type BadgeTone,
+  Button,
+  EmptyState,
+  Input,
+  Select,
+  type SelectOption,
+  Skeleton,
+  Spinner,
+  StatTile,
+  session,
+} from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import { getInventoryApi } from '../api-instance.js'
+import AssetFormDialog from '../components/AssetFormDialog.svelte'
+import { t } from '../i18n.js'
+import { canInventory, INVENTORY_PERMISSIONS } from '../permissions.js'
+import { inventoryKeys } from '../query.js'
+
+/**
+ * This module's screen.
+ *
+ * The shell passes `workspaceId` and `workspaceSlug`, and `params` for any `:name` segment the
+ * route declared. **Do not read `$app/state` or `$app/navigation`** — they are SvelteKit aliases,
+ * this package is type-checked on its own, and they resolve only because the app happens to be
+ * compiling you. Ask `navigation` from `@kernhq/ui` for the current location instead.
+ */
+interface Props {
+  workspaceId: string
+  workspaceSlug: string
+  params?: Record<string, string>
+}
+const { workspaceId }: Props = $props()
+
+const api = getInventoryApi()
+
+let search = $state('')
+let statusFilter = $state<string>('')
+let showArchived = $state(false)
+let dialogOpen = $state(false)
+
+// Debounce the search into the cache key, so typing does not refetch per keystroke.
+let q = $state('')
+$effect(() => {
+  const value = search
+  const timer = setTimeout(() => (q = value), 250)
+  return () => clearTimeout(timer)
+})
+
+const filters = $derived.by(() => {
+  const f: Record<string, unknown> = {}
+  if (q) f.q = q
+  if (statusFilter) f.status = statusFilter
+  if (!showArchived) f.archived = false
+  return Object.keys(f).length ? f : undefined
+})
+
+const assetsQuery = createQuery(() => ({
+  queryKey: inventoryKeys.assets(workspaceId, filters),
+  queryFn: () =>
+    api.assets.list({
+      workspaceId,
+      ...(q ? { q } : {}),
+      ...(statusFilter
+        ? { status: statusFilter as 'in_stock' | 'assigned' | 'under_repair' | 'retired' }
+        : {}),
+    }),
+  enabled: Boolean(workspaceId),
+}))
+
+const assets = $derived(assetsQuery.data?.items ?? [])
+const shownAssets = $derived(showArchived ? assets : assets.filter((a) => !a.archivedAt))
+const counts = $derived({
+  total: assets.length,
+  assigned: assets.filter((a) => a.status === 'assigned').length,
+  inStock: assets.filter((a) => a.status === 'in_stock').length,
+  repair: assets.filter((a) => a.status === 'under_repair').length,
+})
+
+const statusOptions: SelectOption[] = [
+  { value: '', label: t('filter_all_statuses') },
+  { value: 'in_stock', label: t('status_in_stock') },
+  { value: 'assigned', label: t('status_assigned') },
+  { value: 'under_repair', label: t('status_under_repair') },
+  { value: 'retired', label: t('status_retired') },
+]
+
+function statusTone(status: string): BadgeTone {
+  switch (status) {
+    case 'assigned':
+      return 'info'
+    case 'under_repair':
+      return 'warning'
+    case 'retired':
+      return 'grey'
+    default:
+      return 'success'
+  }
+}
+const statusLabel = (status: string) => t(`status_${status}`)
+</script>
+
+<svelte:head><title>{t('title')} · {session.workspaces.find((w) => w.id === workspaceId)?.name ?? ''}</title></svelte:head>
+
+<section>
+  <header>
+    <h1>{t('nav')}</h1>
+    <div class="actions">
+      <Input bind:value={search} type="search" size="sm" placeholder={t('search_placeholder')} aria-label={t('search_placeholder')} />
+      <Select bind:value={statusFilter} options={statusOptions} size="sm" />
+      {#if canInventory('manage')}
+        <Button size="sm" onclick={() => (dialogOpen = true)}>{t('new')}</Button>
+      {/if}
+    </div>
+  </header>
+
+  <div class="tiles">
+    <StatTile size="md" label={t('count', { n: counts.total })} value={String(counts.total)} />
+    <StatTile size="md" label={t('status_in_stock')} value={String(counts.inStock)} />
+    <StatTile size="md" label={t('status_assigned')} value={String(counts.assigned)} />
+    <StatTile size="md" label={t('status_under_repair')} value={String(counts.repair)} />
+  </div>
+
+  {#if assetsQuery.isPending}
+    <Spinner />
+  {:else if assetsQuery.isError}
+    <p class="error">{t('common.error')}</p>
+  {:else if shownAssets.length === 0}
+    <EmptyState icon="briefcase" title={t('empty')} description={t('empty_desc')}>
+      {#snippet actions()}
+        {#if canInventory('manage')}
+          <Button onclick={() => (dialogOpen = true)}>{t('new')}</Button>
+        {/if}
+      {/snippet}
+    </EmptyState>
+  {:else}
+    <p class="count">{t('count', { n: shownAssets.length })}</p>
+    <div class="table" role="table" aria-label={t('title')}>
+      <div class="thead" role="row">
+        <span role="columnheader">{t('code')}</span>
+        <span role="columnheader">{t('name')}</span>
+        <span role="columnheader">{t('location')}</span>
+        <span role="columnheader">{t('warranty_until')}</span>
+        <span role="columnheader">{t('category')}</span>
+      </div>
+      {#each shownAssets as asset (asset.id)}
+        <div class="trow" role="row" tabindex="-1">
+          <span class="cell code" role="cell"><code>{asset.code}</code></span>
+          <span class="cell who" role="cell">
+            <span class="stack">
+              <span class="name">{asset.name}</span>
+              {#if asset.serialNumber}<span class="sub">S/N {asset.serialNumber}</span>{/if}
+            </span>
+          </span>
+          <span class="cell muted" role="cell">{asset.location ?? '—'}</span>
+          <span class="cell muted" role="cell">{asset.warrantyUntil ?? '—'}</span>
+          <span class="cell" role="cell">
+            {#if asset.archivedAt}
+              <Badge tone="grey">{t('archived')}</Badge>
+            {:else}
+              <Badge tone={statusTone(asset.status)}>{statusLabel(asset.status)}</Badge>
+            {/if}
+          </span>
+        </div>
+      {/each}
+    </div>
+  {/if}
+</section>
+
+<AssetFormDialog bind:open={dialogOpen} {workspaceId} />
+
+<style>
+  header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+    flex-wrap: wrap;
+  }
+  h1 {
+    font-size: 18px;
+    font-weight: 600;
+    color: var(--kern-ink-900);
+  }
+  .actions {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+  .tiles {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+    gap: 10px;
+    margin-top: 14px;
+  }
+  .count {
+    margin: 14px 0 6px;
+    font-size: 12px;
+    color: var(--kern-ink-500);
+  }
+  .error {
+    color: var(--kern-danger);
+    font-size: 13px;
+  }
+  .table {
+    margin-top: 4px;
+    border: 1px solid var(--kern-line);
+    border-radius: 10px;
+    overflow: hidden;
+    background: var(--kern-paper);
+  }
+  .thead,
+  .trow {
+    display: grid;
+    grid-template-columns: 110px minmax(0, 2fr) minmax(0, 1fr) minmax(0, 1fr) 120px;
+    gap: 10px;
+    align-items: center;
+    padding: 8px 12px;
+  }
+  .thead {
+    font-size: 11px;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--kern-ink-500);
+    background: var(--kern-canvas-subtle, transparent);
+    border-bottom: 1px solid var(--kern-line);
+  }
+  .trow {
+    border-bottom: 1px solid var(--kern-line);
+    font-size: 13px;
+  }
+  .trow:last-child {
+    border-bottom: none;
+  }
+  .cell {
+    min-width: 0;
+  }
+  code {
+    font-size: 12px;
+    color: var(--kern-ink-700);
+  }
+  .who .stack {
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+  }
+  .name {
+    font-weight: 500;
+    color: var(--kern-ink-900);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .sub {
+    font-size: 11px;
+    color: var(--kern-ink-500);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .muted {
+    color: var(--kern-ink-500);
+  }
+</style>

package/src/client/permissions.ts

@@ -0,0 +1,30 @@
+import { session } from '@kernhq/ui'
+import { inventoryPermissions, MODULE_ID } from '../contract.js'
+
+/**
+ * What this module lets somebody do.
+ *
+ * **Derived from the contract, never re-typed.** `key()` throws at import if a name is not declared,
+ * which is the whole point: a hand-copied permission string type-checks perfectly while being wrong,
+ * and a wrong one silently hides a control or offers one the server refuses.
+ *
+ * Hide what a person may never do; disable — with a reason — what they cannot do right now. The
+ * server checks again on every call regardless; this only stops the interface offering a door that
+ * will not open.
+ */
+const key = (suffix: string) => {
+  const found = inventoryPermissions.find((p) => p.key === `${MODULE_ID}.${suffix}`)
+  if (!found) throw new Error(`${MODULE_ID}: no permission declared for ${MODULE_ID}.${suffix}`)
+  return found.key
+}
+
+export const INVENTORY_PERMISSIONS = {
+  view: key('asset.view'),
+  manage: key('asset.manage'),
+} as const
+
+export type InventoryPermission = keyof typeof INVENTORY_PERMISSIONS
+
+export function canInventory(permission: InventoryPermission): boolean {
+  return session.can(INVENTORY_PERMISSIONS[permission])
+}

package/src/client/query.ts

@@ -0,0 +1,12 @@
+/**
+ * Query keys for Inventory.
+ *
+ * `[module, entity, …scope]`, so a realtime `change` event invalidates precisely what it touched.
+ * Filters are part of the key wherever a screen can ask the same question two ways — a cached list
+ * for "all" must not be served when somebody asked for "assigned".
+ */
+export const inventoryKeys = {
+  assets: (ws: string, filters?: Record<string, unknown>) =>
+    filters ? (['inventory', 'assets', ws, filters] as const) : (['inventory', 'assets', ws] as const),
+  asset: (ws: string, id: string) => ['inventory', 'asset', ws, id] as const,
+}

package/src/client/widgets/OverviewWidget.svelte

@@ -0,0 +1,92 @@
+<script lang="ts">
+import { Badge, type BadgeTone, WidgetState } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import { getInventoryApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+
+/**
+ * A dashboard card.
+ *
+ * `WidgetState` draws loading, failed and empty so every card on the board reports those three the
+ * same way — and so a module does not have to translate "Retry" to show a widget that failed.
+ */
+interface Props {
+  workspaceId: string
+  settings?: Record<string, string | number | boolean | null>
+}
+const { workspaceId, settings }: Props = $props()
+
+const limit = $derived(Number(settings?.limit ?? 5))
+const api = getInventoryApi()
+
+const assets = createQuery(() => ({
+  queryKey: ['inventory', 'assets', workspaceId],
+  queryFn: () => api.assets.list({ workspaceId }),
+  enabled: Boolean(workspaceId),
+}))
+
+const items = $derived((assets.data?.items ?? []).filter((a) => !a.archivedAt).slice(0, limit))
+
+function statusTone(status: string): BadgeTone {
+  switch (status) {
+    case 'assigned':
+      return 'info'
+    case 'under_repair':
+      return 'warning'
+    case 'retired':
+      return 'grey'
+    default:
+      return 'success'
+  }
+}
+</script>
+
+<WidgetState
+  pending={assets.isPending}
+  error={assets.error}
+  empty={!items.length}
+  emptyTitle={t('empty')}
+  emptyIcon="briefcase"
+  onRetry={() => assets.refetch()}
+>
+  <ul>
+    {#each items as asset (asset.id)}
+      <li>
+        <span class="code">{asset.code}</span>
+        <span class="name">{asset.name}</span>
+        <Badge tone={statusTone(asset.status)}>{t(`status_${asset.status}`)}</Badge>
+      </li>
+    {/each}
+  </ul>
+</WidgetState>
+
+<style>
+  ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  li {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    font-size: 13px;
+  }
+  .code {
+    font-size: 11px;
+    color: var(--kern-ink-500);
+    font-variant-numeric: tabular-nums;
+    min-width: 64px;
+  }
+  .name {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: var(--kern-ink-900);
+  }
+</style>

package/src/contract.ts

@@ -0,0 +1,143 @@
+import { baseContract, defineEvent, definePermissions, PageInput, page, WorkspaceId } from '@kernhq/contracts'
+import { z } from 'zod'
+
+/**
+ * What this module offers, as data.
+ *
+ * Imported by **both** halves — the server implements it, the client calls it — so nothing here may
+ * touch Node. The contract is the only thing that crosses that line, which is why a procedure that
+ * exists here and not in the router is a lie that compiles. `module.test.ts` checks exactly that.
+ */
+
+/** Lowercase, 2-32 characters. Names the API prefix, the Postgres schema `mod_<id>` and every event. */
+export const MODULE_ID = 'inventory'
+
+/**
+ * An asset's lifecycle. `in_stock` and `assigned` follow custody (an open row in
+ * `custody_periods` means assigned); `under_repair` follows an open repair; `retired` is set by
+ * hand when an item leaves the company. Stored, because every list filter needs it, and kept in
+ * step inside the same transaction that writes the row it derives from.
+ */
+export const AssetStatus = z.enum(['in_stock', 'assigned', 'under_repair', 'retired'])
+export type AssetStatus = z.infer<typeof AssetStatus>
+
+export const Asset = z.object({
+  id: z.uuid(),
+  workspaceId: WorkspaceId,
+  /** Human-facing asset tag (`INV-0001`), assigned by the server, unique per workspace. */
+  code: z.string().min(1).max(40),
+  name: z.string().min(1).max(200),
+  description: z.string().max(4000),
+  categoryId: z.uuid().nullable(),
+  status: AssetStatus,
+  /**
+   * The member currently holding the item. A plain uuid — cross-schema foreign keys are what the
+   * module boundary exists to prevent — resolved against core membership at read time.
+   */
+  custodianUserId: z.uuid().nullable(),
+  custodySince: z.string().nullable(),
+  serialNumber: z.string().max(200).nullable(),
+  location: z.string().max(200).nullable(),
+  purchasedOn: z.string().nullable(),
+  purchasedFrom: z.string().max(200).nullable(),
+  /** Minor units (cents), the convention billing established; formatted on the client. */
+  priceMinor: z.number().int().nullable(),
+  currency: z.string().length(3).nullable(),
+  warrantyUntil: z.string().nullable(),
+  photoFileId: z.uuid().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  archivedAt: z.string().nullable(),
+})
+export type Asset = z.infer<typeof Asset>
+
+const ws = z.object({ workspaceId: WorkspaceId })
+
+const AssetCreateInput = z.object({
+  name: z.string().min(1).max(200),
+  description: z.string().max(4000).default(''),
+  categoryId: z.uuid().nullish(),
+  serialNumber: z.string().max(200).nullish(),
+  location: z.string().max(200).nullish(),
+  purchasedFrom: z.string().max(200).nullish(),
+  purchasedOn: z.iso.date().nullish(),
+  warrantyUntil: z.iso.date().nullish(),
+  priceMinor: z.number().int().min(0).nullish(),
+  currency: z.string().length(3).nullish(),
+})
+
+export const inventoryContract = {
+  assets: {
+    list: baseContract
+      .route({ method: 'GET', path: '/assets', tags: ['inventory'] })
+      .input(
+        ws.extend({
+          ...PageInput.shape,
+          q: z.string().max(200).optional(),
+          categoryId: z.uuid().optional(),
+          status: AssetStatus.optional(),
+          sort: z.enum(['recent', 'name', 'code']).default('recent'),
+        }),
+      )
+      .output(page(Asset)),
+    get: baseContract
+      .route({ method: 'GET', path: '/assets/{assetId}', tags: ['inventory'] })
+      .input(ws.extend({ assetId: z.uuid() }))
+      .output(Asset),
+    create: baseContract
+      .route({ method: 'POST', path: '/assets', tags: ['inventory'] })
+      .input(ws.extend(AssetCreateInput.shape))
+      .output(Asset),
+    update: baseContract
+      .route({ method: 'PATCH', path: '/assets/{assetId}', tags: ['inventory'] })
+      .input(
+        ws.extend({
+          assetId: z.uuid(),
+          ...AssetCreateInput.partial().shape,
+        }),
+      )
+      .output(Asset),
+    archive: baseContract
+      .route({ method: 'POST', path: '/assets/{assetId}/archive', tags: ['inventory'] })
+      .input(ws.extend({ assetId: z.uuid(), archived: z.boolean().default(true) }))
+      .output(Asset),
+  },
+}
+export type InventoryContract = typeof inventoryContract
+
+/** `<module>.<entity>.<action>`. Anything that emits one declares it here. Payloads carry ids, never rows. */
+export const inventoryEvents = {
+  assetCreated: defineEvent(
+    'inventory.asset.created',
+    z.object({ assetId: z.uuid(), workspaceId: WorkspaceId }),
+  ),
+  assetUpdated: defineEvent(
+    'inventory.asset.updated',
+    z.object({ assetId: z.uuid(), workspaceId: WorkspaceId }),
+  ),
+  assetArchived: defineEvent(
+    'inventory.asset.archived',
+    z.object({ assetId: z.uuid(), workspaceId: WorkspaceId }),
+  ),
+}
+
+/**
+ * `<module>.<resource>.<action>`, each with the narrowest scope that works and the roles that hold it
+ * by default. A workspace can add or remove any of them afterwards with a custom role.
+ */
+export const inventoryPermissions = definePermissions([
+  {
+    key: 'inventory.asset.view',
+    label: 'View assets',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin', 'member', 'guest'],
+    dangerous: false,
+  },
+  {
+    key: 'inventory.asset.manage',
+    label: 'Create and edit assets',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin', 'member'],
+    dangerous: false,
+  },
+])