create-mithaq 0.1.1 → 0.2.1

package/template/templates/mithaq/src/mail/mailers.ts

@@ -0,0 +1,36 @@
+/** One message, written twice: plain text for every client, HTML for those that draw it. */
+export type Mail = { to: string; subject: string; text: string; html: string }
+
+/** What sends this project's mail: one function, so an adapter for another service is a few lines. */
+export type Mailer = { send(mail: Mail): Promise<void> }
+
+/**
+ * Development only: the message goes to the server's log, links and all, and nothing leaves the
+ * machine. Never use it in production, where the log would hold every reset and sign-in link.
+ */
+export const logMailer: Mailer = {
+  send: async ({ to, subject, text }) => {
+    // The log reads as an inbox, so nobody waits for a message that never left.
+    console.log(`[asas mail] Development: emails print here instead of being sent.\nTo ${to}: ${subject}\n${text}`)
+  },
+}
+
+/** Where Resend's API answers, as its own SDK names it. */
+export const defaultResendBaseURL = 'https://api.resend.com'
+
+/**
+ * Resend's HTTP API over `fetch`, so no SDK is installed. `from` is an address at a domain the Resend
+ * account verified; `baseURL` is another address that speaks Resend's API, such as a test's catcher.
+ * A refusal throws with the status alone: the address and the body stay out of the log.
+ */
+export const resendMailer = ({ apiKey, from, baseURL }: { apiKey: string; from: string; baseURL: string }): Mailer => ({
+  send: async ({ to, subject, text, html }) => {
+    const response = await fetch(`${baseURL}/emails`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ from, to: [to], subject, text, html }),
+    })
+    if (!response.ok) throw new Error(`Resend refused a message: ${response.status} ${response.statusText}`)
+  },
+})
+// mithaq-admin 0.0.0 37f2bedf34183fb350814b0e9f4a1453fb4f5491d359794f443461f04bf81e9e

package/template/templates/{asas/src/audit-log/sink.ts → mithaq/src/mithaq/audit-sink.ts}

@@ -9,8 +9,23 @@ import { same } from 'mithaq/admin'
  */
 export const auditLogName = 'auditLog'
 
-/** One changed column: what it held before the write and what it holds after. */
-export type Change = { from: unknown; to: unknown }
+/**
+ * One changed column: what it held before the write and what it holds after. A change one side of
+ * which was too long to keep whole is `truncated`: both sides are JSON text, the long one cut short.
+ */
+export type Change = { from: unknown; to: unknown; truncated?: true }
+
+/** How many characters of one side of a change an entry keeps: one large json value never swells the log. */
+export const keptLength = 2000
+
+const textOf = (value: unknown) => {
+  if (value === null) return null
+  // By code point, so the cut never leaves half of a surrogate pair, which Postgres refuses.
+  const points = [...JSON.stringify(value)]
+  return points.length > keptLength ? `${points.slice(0, keptLength).join('')}…` : points.join('')
+}
+// By code point, as `textOf` cuts, so a side is cut exactly when it is marked cut.
+const tooLong = (value: unknown) => [...(JSON.stringify(value) ?? '')].length > keptLength
 
 /**
  * What the Activity panel draws as a dash: absent, `null`, an empty string or
@@ -22,12 +37,16 @@ export const empty = (value: unknown) => value === undefined || value === null |
 /**
  * The columns whose value differs, each with its value on both sides and
  * `null` for a side that held none. A column empty on both sides is no change,
- * so a create lists only what it set and a delete only what the row held.
+ * so a create lists only what it set and a delete only what the row held. A
+ * side longer than `keptLength` is kept as the start of its JSON.
  */
 export const changesOf = (before: Readonly<Record<string, unknown>>, after: Readonly<Record<string, unknown>>) => {
   const changes: Record<string, Change> = {}
   for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
-    if (!same(before[key], after[key]) && !(empty(before[key]) && empty(after[key]))) changes[key] = { from: before[key] ?? null, to: after[key] ?? null }
+    if (same(before[key], after[key]) || (empty(before[key]) && empty(after[key]))) continue
+    const [from, to] = [before[key] ?? null, after[key] ?? null]
+    // Both sides as JSON text where either is cut, so the panel reads a cut change one way.
+    changes[key] = tooLong(from) || tooLong(to) ? { from: textOf(from), to: textOf(to), truncated: true } : { from, to }
   }
   return changes
 }
@@ -78,12 +97,15 @@ export const auditSink: AuditHandler = async ({ effect, kayan, operation, dataBe
     organization: stringOf(after?.[owner] ?? before[owner]),
     kayan: kayan.name,
     record: String(record),
-    operation,
+    // An update that took a draft to published is named a publish, as Payload's
+    // own history says it, so the Activity filters it apart from an edit.
+    operation: operation === 'update' && changes._status?.to === 'published' ? 'publish' : operation,
     actor: stringOf(actor?.id) ?? (typeof actor?.command === 'string' ? `${actor.command} (${String(actor.osUser)})` : null),
     impersonatedBy: stringOf(actor?.impersonatedBy),
-    // JSON in a text column, because the language ships no json kind. The log
-    // refuses any filter or sort on it, since a `contains` over the text would
-    // read a value its reader may not.
-    changes: JSON.stringify(changes),
+    // The object itself, a jsonb value. The log is never ordered by it, and
+    // searched by it only within the kayan whose columns its reader may be
+    // told of (`reachOf`), since a match in any other would tell a value its
+    // reader may not read.
+    changes,
   } })
 }

package/template/templates/{auth/src/platform-roles.ts → mithaq/src/mithaq/auth/backoffice-roles.ts}

@@ -1,20 +1,24 @@
 import type { SystemRoles } from 'mithaq'
 
-/** One kayan read whole on the platform: its list, its count, one row, and each column named. */
+/** One kayan read whole on the backoffice: its list, its count, one row, and each column named. */
 const reads = (kayan: string, fields: readonly string[]) => [`${kayan}.find`, `${kayan}.count`, `${kayan}.findByID`, ...fields.map((field) => `${kayan}.fields.${field}`)]
 const stamps = ['id', 'createdAt', 'updatedAt'] as const
 
 /**
- * The columns of a kayan the platform lists that no staff role reads, each
- * one a decision written down rather than a name left out. No platform role
- * reads one, `super_admin`'s `'*'` included: the platform's row closes each
- * by name whatever keys the actor holds. `accessCode` is the code a live
- * course's learners join with, a tenant's secret.
+ * The columns of a kayan the backoffice lists that no staff role reads, each
+ * one a decision written down rather than a name left out. No backoffice role
+ * reads one, `super_admin`'s `'*'` included: the backoffice's row closes each
+ * by name whatever keys the actor holds.
  */
-export const secret = ['courses.fields.accessCode'] as const
+export const secret: readonly `${string}.fields.${string}`[] = [
+  // add-on: courses
+  // The code a live course's learners join with, a tenant's secret.
+  'courses.fields.accessCode',
+  // end add-on: courses
+]
 
 /**
- * The kayan the platform lists that no staff role reads at all, a decision
+ * The kayan the backoffice lists that no staff role reads at all, a decision
  * about the whole kayan rather than about its columns: no staff role holds a
  * key of one, and only `super_admin`'s `'*'` lists it. `localUsers` is read
  * and verified by a super admin alone, which the kayan's own access says, so a
@@ -26,48 +30,65 @@ export const superAdminOnly = ['localUsers'] as const
 /** The people, the organizations and their members, which the provider owns. */
 const people = [
   ...reads('user', [...stamps, 'name', 'email', 'emailVerified', 'image', 'role', 'banned', 'banReason', 'banExpires']),
-  ...reads('organization', [...stamps, 'name', 'slug', 'logo', 'metadata']),
-  ...reads('member', [...stamps, 'organizationId', 'userId', 'role']),
+  ...reads('organization', [...stamps, 'name', 'names', 'slug', 'logo', 'metadata']),
+  ...reads('member', [...stamps, 'organizationId', 'userId', 'role', 'lastSeenAt']),
 ]
 
 /** Each tenant's business, across every organization. */
 const business = [
+  // add-on: courses
   // Every column but the one `secret` names.
-  ...reads('courses', [...stamps, 'organization', 'title', 'summary', 'details', 'cover', 'fee', 'currency', 'level', 'notifications', 'delivery', 'audience', 'archived', 'topics', 'opensOn', 'archiveReason', 'tags', 'scheduledSessions', '_status']),
+  ...reads('courses', [...stamps, 'organization', 'title', 'summary', 'details', 'cover', 'fee', 'currency', 'level', 'notifications', 'delivery', 'audience', 'archived', 'topics', 'opensOn', 'archiveReason', 'tags', 'scheduledSessions', '_status', 'selfEnroll']),
   // A course's versions, each cut to the columns above, so staff read a
   // draft's history across every organization and restore none of it: no
   // staff role but `super_admin`'s `'*'` holds `courses.restoreVersion`.
   'courses.findVersions',
   'courses.findVersionByID',
-  ...reads('sessions', [...stamps, 'organization', 'course', 'startsAt', 'capacity', 'venue', 'format', 'archived', 'details', 'enrollments']),
+  ...reads('sessions', [...stamps, 'organization', 'course', 'startsAt', 'capacity', 'venue', 'format', 'archived', 'details', 'enrollments', 'archiveReason']),
   ...reads('enrollments', [...stamps, 'organization', 'session', 'student', 'deletedAt']),
+  // end add-on: courses
   ...reads('tags', [...stamps, 'organization', 'name']),
 ]
 
 /** Who holds what inside each tenant: its role rows and its assignments. */
-const grants = [...reads('roles', [...stamps, 'organization', 'name', 'label', 'permissions']), ...reads('memberRoles', [...stamps, 'organization', 'user', 'role'])]
+const grants: string[] = [
+  // add-on: roles
+  ...reads('roles', [...stamps, 'organization', 'name', 'label', 'permissions']),
+  ...reads('memberRoles', [...stamps, 'organization', 'user', 'role']),
+  // end add-on: roles
+]
+
+/**
+ * The staff history: who impersonated whom, set whose backoffice role and banned whom. `super_admin`
+ * reads it by its `'*'` and `explorer` by these keys; never support, whose impersonations it records.
+ */
+const history: string[] = [
+  // add-on: audit-log
+  ...reads('backofficeLog', ['id', 'createdAt', 'action', 'actor', 'actorEmail', 'target', 'targetEmail', 'previousRole', 'role', 'banReason']),
+  // end add-on: audit-log
+]
 
 /**
- * The platform roles: staff above every tenant, held on Better Auth's own
+ * The backoffice roles: staff above every tenant, held on Better Auth's own
  * `user.role` rather than on a tenant's assignment. The column may hold several,
  * comma-separated, which is how the admin plugin reads it.
  *
  * Each holds catalog keys the way a tenant role does, and the access target
- * holds them only in the platform app: in the tenant app an actor holds its
+ * holds them only in the backoffice app: in the tenant app an actor holds its
  * membership's roles in its active organization and nothing of these. The
  * admin plugin's own roles are built from the same lists below, so the routes
  * that set a role, ban and impersonate refuse what the list does not name.
  *
  * `organization.rename` is this template's own statement, added beside these in
  * `asas.ts`. Every read is a kayan's own keys: its list, its count and one row,
- * and one key per column, since a platform role reads a column only where it
- * holds that column's key. A project adds its own platform role, `billing` say,
+ * and one key per column, since a backoffice role reads a column only where it
+ * holds that column's key. A project adds its own backoffice role, `billing` say,
  * as one more entry here.
  */
-export const platformRoles = {
-  /** Every key, and so the only role that grants a platform role, `user.set-role`, and renames an organization, `organization.rename`. */
+export const backofficeRoles = {
+  /** Every key, and so the only role that grants a backoffice role, `user.set-role`, and renames an organization, `organization.rename`. */
   super_admin: {
-    label: { ar: 'مدير المنصة', en: 'Platform administrator' },
+    label: { ar: 'مدير لوحة الإدارة الخلفية', en: 'Backoffice administrator' },
     permissions: '*',
   },
   /**
@@ -77,11 +98,11 @@ export const platformRoles = {
    */
   support: {
     label: { ar: 'الدعم', en: 'Support' },
-    permissions: ['screen.platform', 'user.impersonate', ...people, ...business],
+    permissions: ['screen.backoffice', 'user.impersonate', ...people, ...business],
   },
-  /** Reads everything on the platform, each tenant's roles included, and changes nothing. */
+  /** Reads everything on the backoffice, each tenant's roles and the staff history included, and changes nothing. */
   explorer: {
     label: { ar: 'مستكشف', en: 'Explorer' },
-    permissions: ['screen.platform', ...people, ...business, ...grants],
+    permissions: ['screen.backoffice', ...people, ...business, ...grants, ...history],
   },
 } as const satisfies SystemRoles