@digimuza/system-core 0.2.0 → 0.3.0-rc.1

package/src/core/context.ts

@@ -1,6 +1,7 @@
 import { buildCatalog, type Catalog, type ModuleManifest } from "./catalog.js"
 import { newTraceId } from "../diagnostics/tracing.js"
 import { silentLogger, type Logger } from "../diagnostics/logging.js"
+import type { Notifier } from "./notify.js"
 import type { Store } from "./store.js"
 import { SYSTEM_MODULES, SYSTEM_ROLES } from "./system-modules.js"
 
@@ -57,12 +58,20 @@ export interface SystemContext {
   readonly operationId: string
   readonly logger: Logger
   readonly superEmails: ReadonlySet<string>
+  /** Present when the app installed notifications (see `notifyIfInstalled`). */
+  readonly notifier?: Notifier
   now(): number
 }
 
-export function bindSystem(def: SystemDefinition, store: Store, options: { operationId?: string } = {}): SystemContext {
+export interface BindOptions {
+  operationId?: string
+  /** Builds the transaction's notifier (Convex layer, when notifications are installed). */
+  notifier?: (sys: SystemContext) => Notifier
+}
+
+export function bindSystem(def: SystemDefinition, store: Store, options: BindOptions = {}): SystemContext {
   const operationId = options.operationId ?? newTraceId()
-  return {
+  const sys: { -readonly [K in keyof SystemContext]: SystemContext[K] } = {
     def,
     store,
     operationId,
@@ -70,4 +79,6 @@ export function bindSystem(def: SystemDefinition, store: Store, options: { opera
     superEmails: def.superUserEmails(),
     now: () => def.now(),
   }
+  if (options.notifier) sys.notifier = options.notifier(sys)
+  return sys
 }

package/src/core/index.ts

@@ -18,3 +18,5 @@ export * from "./modules-service.js"
 export * from "./feature-flags.js"
 export * from "./jobs.js"
 export * from "./role-view.js"
+export * from "./notify.js"
+export * from "./audit-module.js"

package/src/core/notify.ts

@@ -0,0 +1,52 @@
+// The core's seam to `@digimuza/system-core/notifications` (DIG-74).
+//
+// Core services (roles) and package modules (finance) call `notifyIfInstalled`
+// inside their mutation. When the app installed notifications
+// (`defineConvexSystem({ notifications: notificationsHook() })`), the bound
+// SystemContext carries a `notifier` for this transaction; otherwise the call is
+// a no-op. A notification never breaks the business operation that caused it.
+import type { Actor } from "./access.js"
+import type { SystemContext } from "./context.js"
+
+/** JSON value stored as notification params. */
+export type NotificationParams = Record<string, unknown>
+
+export type NotifyTarget =
+  /** Explicit recipients (active users only; others are skipped). */
+  | { userIds: readonly string[] }
+  /** Active users who hold the permission right now (system-core `decide`). */
+  | { permission: string }
+
+export interface NotifyRequest {
+  to: NotifyTarget
+  /** A registered notification type id, e.g. `finance.invoice_awaiting_approval`. */
+  type: string
+  /** JSON params; the app renders the text from them. Never pre-rendered text. */
+  params: NotificationParams
+  /** App-relative link (`/app/...`). */
+  href?: string
+  /** Who caused it. With `to.permission`, this user (or an agent's owner) is excluded. */
+  actor?: Actor | "system" | null
+  /** Also notify the acting user when resolving `to.permission`. Default false. */
+  includeActor?: boolean
+}
+
+/** Bound per transaction by the Convex layer. */
+export interface Notifier {
+  /** Inserts notification rows and schedules emails. Returns the number of recipients. */
+  notify(request: NotifyRequest): Promise<number>
+}
+
+/**
+ * Sends a notification when the app installed notifications; returns 0 otherwise.
+ * Errors are logged (without params) and swallowed.
+ */
+export async function notifyIfInstalled(sys: SystemContext, request: NotifyRequest): Promise<number> {
+  if (!sys.notifier) return 0
+  try {
+    return await sys.notifier.notify(request)
+  } catch (error) {
+    sys.logger.error("notify_failed", { type: request.type, error })
+    return 0
+  }
+}

package/src/core/roles.ts

@@ -17,8 +17,9 @@ import { recordAudit } from "./audit.js"
 import type { SystemContext } from "./context.js"
 import { newId, randomString } from "./crypto.js"
 import { forbidden, notFound, validation } from "./errors.js"
+import { notifyIfInstalled } from "./notify.js"
 import { clampLimit, pairKey, type Page, type RoleRow, type SubroleRow } from "./store.js"
-import { P, PROFILE_ROLE_ID, WILDCARD_SCOPE } from "./system-modules.js"
+import { CORE_NOTIFICATION_TYPES, P, PROFILE_ROLE_ID, WILDCARD_SCOPE } from "./system-modules.js"
 
 export type GrantCheck = { ok: true } | { ok: false; reason: string }
 
@@ -183,6 +184,9 @@ export async function assignRoles(sys: SystemContext, actor: Actor | null, targe
   }
   if (assigned.length) {
     await recordAudit(sys, human, { action: "role.assign", targetType: "user", targetId: target.userId, changes: { addedRoles: assigned } })
+    // No-op unless the app installed notifications.
+    const roleNames = roles.filter((r) => assigned.includes(r.key)).map((r) => r.name)
+    await notifyIfInstalled(sys, { to: { userIds: [target.userId] }, type: CORE_NOTIFICATION_TYPES.roleAssigned, params: { roleNames }, actor: human })
   }
   return { assigned }
 }

package/src/core/system-modules.ts

@@ -121,6 +121,15 @@ export const SYSTEM_MODULES: readonly ModuleManifest[] = [
       p(P.assignmentDelete, "Revoke roles", "Revoke role assignments", true),
       p(P.delegationUpdate, "Edit delegation scope", "Change which roles a role may delegate", true),
     ],
+    notificationTypes: [
+      {
+        id: "roles.role_assigned",
+        moduleId: "roles",
+        defaultChannels: { inApp: true, email: true },
+        description: "You were given new roles",
+        params: ["roleNames"],
+      },
+    ],
     initialSubroles: [
       { id: "roles:viewer", name: "Role viewer", description: "Can view roles", permissions: [P.rolesRead] },
       {
@@ -178,6 +187,9 @@ export const SYSTEM_MODULES: readonly ModuleManifest[] = [
   },
 ]
 
+/** Notification types sent by the core itself. */
+export const CORE_NOTIFICATION_TYPES = { roleAssigned: "roles.role_assigned" } as const
+
 export const ADMIN_ROLE_ID = "system:admin"
 export const PROFILE_ROLE_ID = "system:profile"
 export const WILDCARD_SCOPE = "*"

package/src/finance/ai-tools.ts

@@ -0,0 +1,68 @@
+// AI tools of the finance module (DIG-71). Give them to an agent:
+//
+//   defineAiAgent({ id: "assistant", ..., tools: financeTools })
+//
+// Each tool runs through `executeAiTool`: arguments are validated, the actor is
+// re-authorized for the tool's permission, and the call is audited. The business
+// rules live in the shared invoice operations of `./index.ts`.
+//
+// Note: `./index.ts` re-exports this file, so only function declarations from it
+// may be used here at module top level (no consts: circular import).
+import { z } from "zod"
+import { defineAiTool } from "../ai/tools.js"
+import { notFound } from "../core/errors.js"
+import { approveInvoiceRecord, createInvoiceRecord, findInvoiceByNumber, listInvoiceViews } from "./index.js"
+
+const invoiceNumber = z.string().trim().min(1).max(64).describe("Invoice number, e.g. A-2025-001")
+
+export const financeListInvoicesTool = defineAiTool({
+  id: "finance.list_invoices",
+  description: "Lists invoices, newest first. Optionally filter by status (draft or approved). Amounts are in major units (e.g. 12.50 EUR).",
+  permission: "finance:invoice:read",
+  input: z.object({
+    status: z.enum(["draft", "approved"]).optional().describe("Only invoices with this status"),
+    limit: z.number().int().min(1).max(50).optional().describe("How many invoices to return (1-50, default 20)"),
+  }),
+  handler: async ({ db }, input) => {
+    const rows = await listInvoiceViews(db, { status: input.status, limit: input.limit ?? 20 })
+    return rows.map((r) => ({ number: r.number, customer: r.customer, amount: r.amountCents / 100, currency: r.currency, status: r.status }))
+  },
+})
+
+export const financeCreateInvoiceTool = defineAiTool({
+  id: "finance.create_invoice",
+  description: "Creates a draft invoice in EUR. Invoice numbers are unique. The user approves this call before it runs.",
+  permission: "finance:invoice:create",
+  requiresApproval: true,
+  input: z.object({
+    number: invoiceNumber,
+    customer: z.string().trim().min(1).max(200).describe("Customer name"),
+    amountEur: z.number().positive().max(1_000_000_000).describe("Amount in EUR, e.g. 12.50"),
+  }),
+  handler: async ({ db, sys, actor }, input) => {
+    const { invoiceId, number } = await createInvoiceRecord(db, sys, actor, {
+      number: input.number,
+      customer: input.customer,
+      amountCents: Math.round(input.amountEur * 100),
+      currency: "EUR",
+    })
+    return { invoiceId: invoiceId as string, number }
+  },
+})
+
+export const financeApproveInvoiceTool = defineAiTool({
+  id: "finance.approve_invoice",
+  description: "Approves a draft invoice by its number. Only drafts can be approved. The user approves this call before it runs.",
+  permission: "finance:invoice:approve",
+  requiresApproval: true,
+  input: z.object({ number: invoiceNumber }),
+  handler: async ({ db, sys, actor }, input) => {
+    const invoice = await findInvoiceByNumber(db, input.number)
+    if (!invoice) throw notFound("invoice_not_found")
+    const res = await approveInvoiceRecord(db, sys, actor, invoice.id, { via: "ai" })
+    return { number: res.number, status: res.status }
+  },
+})
+
+/** All finance tools, for an agent's `tools`. */
+export const financeTools = [financeListInvoicesTool, financeCreateInvoiceTool, financeApproveInvoiceTool] as const

package/src/finance/index.ts

@@ -13,10 +13,23 @@
 import { defineTable, mutationGeneric, queryGeneric } from "convex/server"
 import type { GenericId } from "convex/values"
 import { v } from "convex/values"
-import { isFeatureEnabled, recordAudit, SystemError, type Actor } from "../core/index.js"
+import { defineNotificationType, isFeatureEnabled, notifyIfInstalled, recordAudit, SystemError, type Actor, type SystemContext } from "../core/index.js"
 import { toConvexError, type ConvexSystem } from "../convex/functions.js"
 import { defineModule, type PermissionOf } from "../modules/index.js"
 
+/**
+ * Sent to holders of `finance:invoice:approve` (not the creator) when a draft is
+ * created. Params `{ number, customer, amountCents, currency }`; href
+ * `/app/finance?invoice=<number>`. Only when the app installed notifications.
+ */
+export const financeInvoiceAwaitingApproval = defineNotificationType({
+  id: "finance.invoice_awaiting_approval",
+  moduleId: "finance",
+  defaultChannels: { inApp: true, email: true },
+  description: "Nauja sąskaita laukia patvirtinimo",
+  params: ["number", "customer", "amountCents", "currency"],
+})
+
 export const finance = defineModule({
   id: "finance",
   kind: "business",
@@ -36,6 +49,7 @@ export const finance = defineModule({
     },
   ],
   featureFlags: [{ id: "finance:bulk-approve", description: "Tvirtinti kelias sąskaitas vienu veiksmu", default: false }],
+  notificationTypes: [financeInvoiceAwaitingApproval],
 })
 
 export const FinancePermissions = {
@@ -60,9 +74,14 @@ export const financeTables = {
     approvedAt: v.optional(v.number()),
   })
     .index("by_number", ["number"])
-    .index("by_status", ["status"]),
+    .index("by_status", ["status"])
+    // Global search (`financeSearch`): full text over the customer name.
+    .searchIndex("search_customer", { searchField: "customer" }),
 }
 
+/** App link to one invoice (search hits, notifications). */
+export const invoiceHref = (number: string) => `/app/finance?invoice=${encodeURIComponent(number)}`
+
 export type InvoiceStatus = "draft" | "approved"
 
 /** Convex ID of an invoice in the app's `invoices` table. */
@@ -79,7 +98,7 @@ export interface InvoiceView {
   approvedAt: number | null
 }
 
-interface InvoiceDoc {
+export interface InvoiceDoc {
   _id: InvoiceId
   _creationTime: number
   number: string
@@ -106,29 +125,94 @@ const actorArgs = { apiKey: v.optional(v.string()), operationId: v.optional(v.st
 const opts = (a: { apiKey?: string | undefined; operationId?: string | undefined }) => ({ apiKey: a.apiKey, operationId: a.operationId })
 
 function fail(code: "NOT_FOUND" | "CONFLICT" | "VALIDATION" | "FORBIDDEN", reason: string, operationId: string): never {
-  throw toConvexError(new SystemError(code, undefined, { reason, operationId }), operationId)
+  throw new SystemError(code, undefined, { reason, operationId })
+}
+
+// --- Invoice operations ---------------------------------------------------------------
+// Shared by the Convex functions below and the AI tools (`./ai-tools.ts`). They hold
+// the business rules and the audit; the caller has already checked the permission.
+// They throw SystemError (with the operation ID); Convex callers translate it.
+
+/** A loosely typed db handle: the app's schema contains `financeTables`. */
+export interface FinanceDb {
+  query(t: "invoices"): {
+    withIndex(i: string, f: (q: { eq(field: string, value: unknown): unknown }) => unknown): { order(o: "asc" | "desc"): { take(n: number): Promise<InvoiceDoc[]> }; unique(): Promise<InvoiceDoc | null> }
+    order(o: "asc" | "desc"): { take(n: number): Promise<InvoiceDoc[]> }
+  }
+  get(t: "invoices", id: string): Promise<InvoiceDoc | null>
+  insert(t: "invoices", doc: Record<string, unknown>): Promise<InvoiceId>
+  patch(t: "invoices", id: string, doc: Record<string, unknown>): Promise<void>
+}
+
+/** Newest first, optionally by status. */
+export async function listInvoiceViews(db: unknown, filter: { status?: InvoiceStatus | undefined; limit: number }): Promise<InvoiceView[]> {
+  const q = (db as FinanceDb).query("invoices")
+  const rows = filter.status
+    ? await q.withIndex("by_status", (i) => i.eq("status", filter.status)).order("desc").take(filter.limit)
+    : await q.order("desc").take(filter.limit)
+  return rows.map(view)
+}
+
+export async function findInvoiceByNumber(db: unknown, number: string): Promise<InvoiceView | null> {
+  const row = await (db as FinanceDb).query("invoices").withIndex("by_number", (i) => i.eq("number", number.trim())).unique()
+  return row ? view(row) : null
+}
+
+/** Validates, enforces unique numbers (CONFLICT), inserts a draft and audits `finance.invoice.create`. */
+export async function createInvoiceRecord(
+  db: unknown,
+  sys: SystemContext,
+  actor: Actor,
+  input: { number: string; customer: string; amountCents: number; currency?: string | undefined },
+): Promise<{ invoiceId: InvoiceId; number: string }> {
+  const number = input.number.trim()
+  const customer = input.customer.trim()
+  if (!number || !customer || !Number.isInteger(input.amountCents) || input.amountCents <= 0) fail("VALIDATION", "invalid_invoice", sys.operationId)
+  const currency = (input.currency ?? "EUR").toUpperCase()
+  if (!/^[A-Z]{3}$/.test(currency)) fail("VALIDATION", "invalid_currency", sys.operationId)
+  const d = db as FinanceDb
+  const existing = await d.query("invoices").withIndex("by_number", (i) => i.eq("number", number)).unique()
+  if (existing) fail("CONFLICT", "invoice_number_taken", sys.operationId)
+  const invoiceId = await d.insert("invoices", { number, customer, amountCents: input.amountCents, currency, status: "draft", createdBy: actorId(actor) })
+  await recordAudit(sys, actor, { action: "finance.invoice.create", targetType: "invoice", targetId: invoiceId, changes: { number } })
+  // The new draft awaits approval. No-op unless the app installed notifications.
+  await notifyIfInstalled(sys, {
+    to: { permission: "finance:invoice:approve" },
+    type: "finance.invoice_awaiting_approval",
+    params: { number, customer, amountCents: input.amountCents, currency },
+    href: invoiceHref(number),
+    actor,
+  })
+  return { invoiceId, number }
+}
+
+/** Approves a draft (NOT_FOUND if missing, CONFLICT unless draft) and audits `finance.invoice.approve`. */
+export async function approveInvoiceRecord(
+  db: unknown,
+  sys: SystemContext,
+  actor: Actor,
+  invoiceId: string,
+  changes?: Record<string, unknown>,
+): Promise<{ invoiceId: InvoiceId; number: string; status: InvoiceStatus }> {
+  const d = db as FinanceDb
+  const invoice = await d.get("invoices", invoiceId)
+  // A missing invoice and one the caller may not see look the same.
+  if (!invoice) fail("NOT_FOUND", "invoice_not_found", sys.operationId)
+  if (invoice.status !== "draft") fail("CONFLICT", "invoice_not_draft", sys.operationId)
+  await d.patch("invoices", invoiceId, { status: "approved", approvedBy: actorId(actor), approvedAt: sys.now() })
+  await recordAudit(sys, actor, { action: "finance.invoice.approve", targetType: "invoice", targetId: invoiceId, ...(changes ? { changes } : {}) })
+  return { invoiceId: invoice._id, number: invoice.number, status: "approved" }
 }
 
 /** The module's Convex functions, bound to the app's system. Re-export them from `convex/finance.ts`. */
 export function defineFinance(system: ConvexSystem) {
-  // A loosely typed db handle: the app's schema contains `financeTables`.
-  type Db = {
-    query(t: "invoices"): {
-      withIndex(i: string, f: (q: { eq(field: string, value: unknown): unknown }) => unknown): { order(o: "asc" | "desc"): { take(n: number): Promise<InvoiceDoc[]> }; unique(): Promise<InvoiceDoc | null> }
-      order(o: "asc" | "desc"): { take(n: number): Promise<InvoiceDoc[]> }
+  /** Runs an invoice operation, translating SystemError to ConvexError. */
+  async function guarded<R>(operationId: string, fn: () => Promise<R>): Promise<R> {
+    try {
+      return await fn()
+    } catch (e) {
+      throw toConvexError(e, operationId)
     }
-    get(t: "invoices", id: string): Promise<InvoiceDoc | null>
-    insert(t: "invoices", doc: Record<string, unknown>): Promise<InvoiceId>
-    patch(t: "invoices", id: string, doc: Record<string, unknown>): Promise<void>
-  }
-  const db = (ctx: { db: unknown }) => ctx.db as Db
-
-  async function approveOne(ctx: { db: unknown }, operationId: string, invoiceId: string, by: string) {
-    const invoice = await db(ctx).get("invoices", invoiceId)
-    // A missing invoice and one the caller may not see look the same.
-    if (!invoice) fail("NOT_FOUND", "invoice_not_found", operationId)
-    if (invoice!.status !== "draft") fail("CONFLICT", "invoice_not_draft", operationId)
-    await db(ctx).patch("invoices", invoiceId, { status: "approved", approvedBy: by, approvedAt: Date.now() })
   }
 
   return {
@@ -136,9 +220,7 @@ export function defineFinance(system: ConvexSystem) {
       args: { ...actorArgs, status: v.optional(v.union(v.literal("draft"), v.literal("approved"))) },
       handler: async (ctx, a): Promise<InvoiceView[]> => {
         await system.requirePermission(ctx, FinancePermissions.read, opts(a))
-        const q = db(ctx).query("invoices")
-        const rows = a.status ? await q.withIndex("by_status", (i) => i.eq("status", a.status)).order("desc").take(100) : await q.order("desc").take(100)
-        return rows.map(view)
+        return listInvoiceViews(ctx.db, { status: a.status, limit: 100 })
       },
     }),
 
@@ -146,15 +228,9 @@ export function defineFinance(system: ConvexSystem) {
       args: { ...actorArgs, number: v.string(), customer: v.string(), amountCents: v.number(), currency: v.optional(v.string()) },
       handler: async (ctx, a): Promise<{ invoiceId: InvoiceId; operationId: string }> => {
         const { sys, actor } = await system.requirePermission(ctx, FinancePermissions.create, opts(a))
-        const number = a.number.trim()
-        const customer = a.customer.trim()
-        if (!number || !customer || !Number.isInteger(a.amountCents) || a.amountCents <= 0) fail("VALIDATION", "invalid_invoice", sys.operationId)
-        const currency = (a.currency ?? "EUR").toUpperCase()
-        if (!/^[A-Z]{3}$/.test(currency)) fail("VALIDATION", "invalid_currency", sys.operationId)
-        const existing = await db(ctx).query("invoices").withIndex("by_number", (i) => i.eq("number", number)).unique()
-        if (existing) fail("CONFLICT", "invoice_number_taken", sys.operationId)
-        const invoiceId = await db(ctx).insert("invoices", { number, customer, amountCents: a.amountCents, currency, status: "draft", createdBy: actorId(actor) })
-        await recordAudit(sys, actor, { action: "finance.invoice.create", targetType: "invoice", targetId: invoiceId, changes: { number } })
+        const { invoiceId } = await guarded(sys.operationId, () =>
+          createInvoiceRecord(ctx.db, sys, actor, { number: a.number, customer: a.customer, amountCents: a.amountCents, currency: a.currency }),
+        )
         return { invoiceId, operationId: sys.operationId }
       },
     }),
@@ -163,8 +239,7 @@ export function defineFinance(system: ConvexSystem) {
       args: { ...actorArgs, invoiceId: v.id("invoices") },
       handler: async (ctx, a): Promise<{ operationId: string }> => {
         const { sys, actor } = await system.requirePermission(ctx, FinancePermissions.approve, opts(a))
-        await approveOne(ctx, sys.operationId, a.invoiceId, actorId(actor))
-        await recordAudit(sys, actor, { action: "finance.invoice.approve", targetType: "invoice", targetId: a.invoiceId })
+        await guarded(sys.operationId, () => approveInvoiceRecord(ctx.db, sys, actor, a.invoiceId))
         return { operationId: sys.operationId }
       },
     }),
@@ -174,16 +249,18 @@ export function defineFinance(system: ConvexSystem) {
       args: { ...actorArgs, invoiceIds: v.array(v.id("invoices")) },
       handler: async (ctx, a): Promise<{ approved: number; operationId: string }> => {
         const { sys, actor } = await system.requirePermission(ctx, FinancePermissions.approve, opts(a))
-        if (!(await isFeatureEnabled(sys, FINANCE_BULK_APPROVE_FLAG))) fail("FORBIDDEN", "flag_off", sys.operationId)
-        if (a.invoiceIds.length > FINANCE_BULK_LIMIT) fail("VALIDATION", "too_many", sys.operationId)
-        for (const id of a.invoiceIds) {
-          await approveOne(ctx, sys.operationId, id, actorId(actor))
-          await recordAudit(sys, actor, { action: "finance.invoice.approve", targetType: "invoice", targetId: id, changes: { bulk: true } })
-        }
-        return { approved: a.invoiceIds.length, operationId: sys.operationId }
+        return guarded(sys.operationId, async () => {
+          if (!(await isFeatureEnabled(sys, FINANCE_BULK_APPROVE_FLAG))) fail("FORBIDDEN", "flag_off", sys.operationId)
+          if (a.invoiceIds.length > FINANCE_BULK_LIMIT) fail("VALIDATION", "too_many", sys.operationId)
+          for (const id of a.invoiceIds) await approveInvoiceRecord(ctx.db, sys, actor, id, { bulk: true })
+          return { approved: a.invoiceIds.length, operationId: sys.operationId }
+        })
       },
     }),
   }
 }
 
 export type FinanceFunctions = ReturnType<typeof defineFinance>
+
+export { financeTools, financeListInvoicesTool, financeCreateInvoiceTool, financeApproveInvoiceTool } from "./ai-tools.js"
+export { financeSearch, searchInvoices } from "./search.js"

package/src/finance/search.ts

@@ -0,0 +1,58 @@
+// Global search provider of the finance module (DIG-72). Install it with
+//
+//   export const { search } = defineSearch(system, { providers: [financeSearch] }).functions
+//
+// Finds invoices by number (prefix, via the `by_number` index) and by customer
+// (full text, via the `search_customer` search index). Read-only and bounded.
+//
+// Note: `./index.ts` re-exports this file, so only function declarations from it
+// may be used here at module top level (no consts: circular import).
+import { defineSearchProvider, type SearchHit } from "../search/index.js"
+import { invoiceHref, type InvoiceDoc } from "./index.js"
+
+type IndexQ = { eq(f: string, v: unknown): IndexQ; gte(f: string, v: unknown): IndexQ; lt(f: string, v: unknown): IndexQ }
+type SearchQ = { search(f: string, q: string): SearchQ }
+interface InvoiceSearchDb {
+  query(t: "invoices"): {
+    withIndex(i: string, f: (q: IndexQ) => unknown): { take(n: number): Promise<InvoiceDoc[]> }
+    withSearchIndex(i: string, f: (q: SearchQ) => unknown): { take(n: number): Promise<InvoiceDoc[]> }
+  }
+}
+
+/** Invoices whose number starts with the query (as typed, then upper-cased), then customers matching it. */
+export async function searchInvoices(db: unknown, query: string, limit: number): Promise<InvoiceDoc[]> {
+  const d = db as InvoiceSearchDb
+  const out = new Map<string, InvoiceDoc>()
+  for (const prefix of new Set([query, query.toUpperCase()])) {
+    if (out.size >= limit) break
+    const rows = await d
+      .query("invoices")
+      .withIndex("by_number", (q) => q.gte("number", prefix).lt("number", `${prefix}￿`))
+      .take(limit)
+    for (const r of rows) out.set(r._id, r)
+  }
+  if (out.size < limit) {
+    const rows = await d
+      .query("invoices")
+      .withSearchIndex("search_customer", (q) => q.search("customer", query))
+      .take(limit)
+    for (const r of rows) if (!out.has(r._id)) out.set(r._id, r)
+  }
+  return [...out.values()].slice(0, limit)
+}
+
+export const financeSearch = defineSearchProvider({
+  id: "finance.invoices",
+  moduleId: "finance",
+  label: "Sąskaitos",
+  permission: "finance:invoice:read",
+  search: async ({ db }, { query, limit }): Promise<SearchHit[]> =>
+    (await searchInvoices(db, query, limit)).map((i) => ({
+      providerId: "finance.invoices",
+      id: i._id,
+      title: i.number,
+      subtitle: i.customer,
+      href: invoiceHref(i.number),
+      kind: "invoice",
+    })),
+})

package/src/index.ts

@@ -17,3 +17,5 @@ export type { SessionSummary, ModuleState } from "./core/modules-service.js"
 export type { PublicApiKey } from "./core/api-keys.js"
 export type { PublicInvite } from "./core/invites.js"
 export type { PublicUser, Profile } from "./core/users.js"
+export { auditToCsv, csvCell, AUDIT_CSV_COLUMNS, type AuditCsvEvent, type AuditCsvOptions } from "./audit/csv.js"
+export { auditModuleOf } from "./core/audit-module.js"

package/src/modules/index.ts

@@ -11,6 +11,9 @@ export {
   type PermissionDefinition,
   type SubroleTemplate,
   type FeatureFlagDefinition,
+  defineNotificationType,
+  NOTIFICATION_TYPE_ID,
+  type NotificationTypeDefinition,
   type PermissionOf,
   type Catalog,
 } from "../core/catalog.js"