@exvio/os-backend-core 0.4.0

package/src/changelog/service.ts

@@ -0,0 +1,148 @@
+import { getCurrentTenant } from '../db/tenant-context.ts'
+import { ChangelogError } from './types.ts'
+import type {
+  ChangelogAcknowledgementInput,
+  ChangelogAcknowledgementResult,
+  ChangelogService,
+  ChangelogServiceOptions,
+  ChangelogSnapshot,
+  ChangelogStateInput,
+  ChangelogSubject,
+  ChangelogSubjectId,
+} from './types.ts'
+
+export function createChangelogService<Locale extends string, SubjectId extends ChangelogSubjectId>(
+  options: ChangelogServiceOptions<Locale, SubjectId>,
+): ChangelogService<Locale, SubjectId> {
+  if (!options?.catalogue || !options.acknowledgements) {
+    throw new ChangelogError({
+      code: 'invalid_catalogue',
+      message: 'Changelog service configuration is invalid',
+    })
+  }
+  const tenantResolver = options.tenantResolver ?? (() => {
+    const store = getCurrentTenant()
+    return store && !store.bypass ? store.tenantId : undefined
+  })
+
+  const subjectFor = (subjectId: SubjectId, explicitTenantId?: number): ChangelogSubject<SubjectId> => {
+    let tenantId: number
+    if (explicitTenantId !== undefined) {
+      validateTenant(explicitTenantId)
+      const activeTenantId = resolveOptionalTenant(tenantResolver)
+      if (activeTenantId !== undefined) {
+        validateTenant(activeTenantId)
+        if (activeTenantId !== explicitTenantId) {
+          throw new ChangelogError({
+            code: 'invalid_tenant',
+            message: 'Explicit changelog tenant does not match the active tenant',
+          })
+        }
+      }
+      tenantId = explicitTenantId
+    } else {
+      tenantId = resolveTenant(tenantResolver)
+    }
+    validateTenant(tenantId)
+    validateSubject(subjectId)
+    return Object.freeze({ tenantId, subjectId })
+  }
+
+  const getState = async (
+    input: ChangelogStateInput<Locale, SubjectId>,
+  ): Promise<ChangelogSnapshot<Locale>> => {
+    if (!input || typeof input !== 'object') {
+      throw new ChangelogError({ code: 'invalid_subject', message: 'Changelog subject is invalid' })
+    }
+    const subject = subjectFor(input.subjectId, input.tenantId)
+    const locale = input.locale ?? options.catalogue.resolveLocale(input.acceptLanguage)
+    if (!options.catalogue.isLocale(locale)) {
+      throw new ChangelogError({ code: 'invalid_locale', message: 'Changelog locale is invalid' })
+    }
+    let seenVersion: string | null
+    try {
+      seenVersion = await options.acknowledgements.getSeenVersion(subject)
+    } catch {
+      throw storeFailure()
+    }
+    if (seenVersion !== null && typeof seenVersion !== 'string') throw storeFailure()
+
+    return Object.freeze({
+      version: options.catalogue.latest.version,
+      seen: seenVersion === options.catalogue.latest.version,
+      seenVersion,
+      locale,
+      entries: options.catalogue.localize(locale),
+    })
+  }
+
+  const acknowledge = async (
+    input: ChangelogAcknowledgementInput<SubjectId>,
+  ): Promise<ChangelogAcknowledgementResult> => {
+    if (!input || typeof input !== 'object') {
+      return Object.freeze({ ok: false, reason: 'invalid_version' })
+    }
+    const subject = subjectFor(input.subjectId, input.tenantId)
+    const version = typeof input.version === 'string' ? input.version.trim() : ''
+    if (
+      !version
+      || version !== input.version
+      || version.length > options.catalogue.maxVersionLength
+    ) return Object.freeze({ ok: false, reason: 'invalid_version' })
+    if (!options.catalogue.isKnownVersion(version)) {
+      return Object.freeze({ ok: false, reason: 'unknown_version' })
+    }
+    try {
+      await options.acknowledgements.acknowledge(subject, version)
+    } catch {
+      throw storeFailure()
+    }
+    return Object.freeze({ ok: true, version })
+  }
+
+  return Object.freeze({ getState, acknowledge })
+}
+
+function resolveTenant(resolver: () => number | null | undefined): number {
+  const tenantId = resolveOptionalTenant(resolver)
+  if (tenantId === undefined) {
+    throw new ChangelogError({ code: 'missing_tenant', message: 'Changelog tenant context is required' })
+  }
+  return tenantId
+}
+
+function resolveOptionalTenant(resolver: () => number | null | undefined): number | undefined {
+  let tenantId: number | null | undefined
+  try {
+    tenantId = resolver()
+  } catch {
+    throw new ChangelogError({ code: 'missing_tenant', message: 'Changelog tenant context is unavailable' })
+  }
+  return tenantId ?? undefined
+}
+
+function validateTenant(tenantId: number): void {
+  if (!Number.isSafeInteger(tenantId) || tenantId <= 0) {
+    throw new ChangelogError({ code: 'invalid_tenant', message: 'Changelog tenant is invalid' })
+  }
+}
+
+function validateSubject(subjectId: ChangelogSubjectId): void {
+  const valid = typeof subjectId === 'number'
+    ? Number.isSafeInteger(subjectId) && subjectId > 0
+    : typeof subjectId === 'string'
+      ? subjectId.length > 0
+        && subjectId.length <= 256
+        && subjectId.trim() === subjectId
+      : false
+  if (!valid) {
+    throw new ChangelogError({ code: 'invalid_subject', message: 'Changelog subject is invalid' })
+  }
+}
+
+function storeFailure(): ChangelogError {
+  return new ChangelogError({
+    code: 'store_failure',
+    message: 'Changelog acknowledgement store failed',
+  })
+}

package/src/changelog/types.ts

@@ -0,0 +1,122 @@
+export type ChangelogSubjectId = string | number
+
+export interface ChangelogEntry<Locale extends string> {
+  readonly version: string
+  readonly date: string
+  readonly title: string
+  /** The default locale is required; other locales may fall back to it. */
+  readonly body: Readonly<Partial<Record<Locale, string>>>
+}
+
+export interface LocalizedChangelogEntry<Locale extends string> {
+  readonly version: string
+  readonly date: string
+  readonly title: string
+  readonly body: string
+  /** Actual body locale after per-entry fallback. */
+  readonly locale: Locale
+}
+
+export interface ChangelogSubject<SubjectId extends ChangelogSubjectId = ChangelogSubjectId> {
+  readonly tenantId: number
+  readonly subjectId: SubjectId
+}
+
+export interface ChangelogSnapshot<Locale extends string> {
+  readonly version: string
+  readonly seen: boolean
+  readonly seenVersion: string | null
+  /** Requested/negotiated response locale. Entries report their own fallback locale. */
+  readonly locale: Locale
+  readonly entries: readonly LocalizedChangelogEntry<Locale>[]
+}
+
+export interface ChangelogAcknowledgementStore<SubjectId extends ChangelogSubjectId> {
+  getSeenVersion(subject: ChangelogSubject<SubjectId>): Promise<string | null>
+  acknowledge(subject: ChangelogSubject<SubjectId>, version: string): Promise<void>
+}
+
+export type ChangelogAcknowledgementResult =
+  | { readonly ok: true; readonly version: string }
+  | { readonly ok: false; readonly reason: 'invalid_version' | 'unknown_version' }
+
+export type ChangelogErrorCode =
+  | 'invalid_catalogue'
+  | 'invalid_locale'
+  | 'invalid_subject'
+  | 'missing_tenant'
+  | 'invalid_tenant'
+  | 'store_failure'
+
+export interface ChangelogErrorOptions {
+  readonly code: ChangelogErrorCode
+  readonly message: string
+}
+
+/** Stable error envelope; storage/config causes are deliberately not retained. */
+export class ChangelogError extends Error {
+  readonly code: ChangelogErrorCode
+
+  constructor(options: ChangelogErrorOptions) {
+    super(options.message)
+    this.name = 'ChangelogError'
+    this.code = options.code
+  }
+}
+
+export interface AcceptLanguageResolverOptions<Locale extends string> {
+  readonly locales: readonly Locale[]
+  readonly defaultLocale: Locale
+  /** Lower/upper-case BCP-47 tags are normalized; values are internal locale keys. */
+  readonly languageTags?: Readonly<Record<string, Locale>>
+}
+
+export type AcceptLanguageResolver<Locale extends string> = (
+  acceptLanguage?: string | null,
+) => Locale
+
+export interface ChangelogCatalogueOptions<Locale extends string>
+  extends AcceptLanguageResolverOptions<Locale> {
+  readonly entries: readonly ChangelogEntry<Locale>[]
+  /** Must match the consumer acknowledgement column width. */
+  readonly maxVersionLength: number
+}
+
+export interface ChangelogCatalogue<Locale extends string> {
+  readonly entries: readonly ChangelogEntry<Locale>[]
+  readonly latest: ChangelogEntry<Locale>
+  readonly locales: readonly Locale[]
+  readonly defaultLocale: Locale
+  readonly maxVersionLength: number
+  resolveLocale(acceptLanguage?: string | null): Locale
+  isLocale(value: unknown): value is Locale
+  isKnownVersion(version: string): boolean
+  bodyFor(entry: ChangelogEntry<Locale>, locale: Locale): { body: string; locale: Locale }
+  localize(locale: Locale): readonly LocalizedChangelogEntry<Locale>[]
+}
+
+export interface ChangelogServiceOptions<Locale extends string, SubjectId extends ChangelogSubjectId> {
+  readonly catalogue: ChangelogCatalogue<Locale>
+  readonly acknowledgements: ChangelogAcknowledgementStore<SubjectId>
+  /** Defaults to the backend-core tenant ALS and ignores bypass scopes. */
+  readonly tenantResolver?: () => number | null | undefined
+}
+
+export interface ChangelogStateInput<Locale extends string, SubjectId extends ChangelogSubjectId> {
+  readonly subjectId: SubjectId
+  readonly tenantId?: number
+  readonly locale?: Locale
+  readonly acceptLanguage?: string | null
+}
+
+export interface ChangelogAcknowledgementInput<SubjectId extends ChangelogSubjectId> {
+  readonly subjectId: SubjectId
+  readonly tenantId?: number
+  /** Runtime input is unknown so HTTP adapters can pass decoded JSON directly. */
+  readonly version: unknown
+}
+
+export interface ChangelogService<Locale extends string, SubjectId extends ChangelogSubjectId> {
+  getState(input: ChangelogStateInput<Locale, SubjectId>): Promise<ChangelogSnapshot<Locale>>
+  acknowledge(input: ChangelogAcknowledgementInput<SubjectId>): Promise<ChangelogAcknowledgementResult>
+}

package/src/db/bypass-tenant.ts

@@ -0,0 +1,15 @@
+/**
+ * Caller-facing alias of withBypass with a name that makes review intent clear.
+ *
+ *   await bypassTenant(() =>
+ *     db.selectFrom('users').where('email', '=', email).execute()
+ *   )
+ *
+ * Use only for legitimate cross-tenant queries:
+ *   - OAuth callback before tenant is resolved
+ *   - Hub admin tenant CRUD on the `tenants` table itself
+ *   - System jobs that need to span tenants
+ *
+ * Code review should flag any other usage.
+ */
+export { withBypass as bypassTenant } from './tenant-context.ts'