@owlmeans/bot-postgres 0.0.0-stage → 0.1.18-rc.2

package/src/helper.ts

@@ -0,0 +1,33 @@
+import type { BasicContext } from '@owlmeans/context'
+import { RES_BOT_ACTIVITY, RES_BOT_CONNECTION, RES_BOT_RULE, RES_BOT_UPDATE } from '@owlmeans/server-bot'
+
+import {
+  makeBotActivityResource, makeBotConnectionResource, makeBotRuleResource, makeBotUpdateResource,
+} from './resource.js'
+import type { BotPostgresOptions } from './types.js'
+
+/**
+ * Registers the four bot resources, each only while its alias is free — a second call (a context
+ * composed in two places, a hot reload) leaves the registered ones alone. Registration order against
+ * `appendBot` is free: the service resolves its resources by alias on every call.
+ */
+export const appendPostgresBot = (ctx: BasicContext<any>, opts: BotPostgresOptions = {}): void => {
+  const { dbAlias, serviceAlias, resources = {} } = opts
+  const connection = resources.connection ?? RES_BOT_CONNECTION
+  const rule = resources.rule ?? RES_BOT_RULE
+  const update = resources.update ?? RES_BOT_UPDATE
+  const activity = resources.activity ?? RES_BOT_ACTIVITY
+
+  if (!ctx.hasResource(connection)) {
+    ctx.registerResource(makeBotConnectionResource(dbAlias, connection, serviceAlias))
+  }
+  if (!ctx.hasResource(rule)) {
+    ctx.registerResource(makeBotRuleResource(dbAlias, rule, serviceAlias))
+  }
+  if (!ctx.hasResource(update)) {
+    ctx.registerResource(makeBotUpdateResource(dbAlias, update, serviceAlias))
+  }
+  if (!ctx.hasResource(activity)) {
+    ctx.registerResource(makeBotActivityResource(dbAlias, activity, serviceAlias))
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export type * from './types.js'
+export * from './resource.js'
+export * from './helper.js'

package/src/resource.ts

@@ -0,0 +1,100 @@
+import { makePostgresResource, pgDeclarationHelper, pgNameHelper } from '@owlmeans/postgres-resource'
+import type { PostgresResource } from '@owlmeans/postgres-resource'
+import type { ResourceRecord } from '@owlmeans/resource'
+import {
+  BotActivityRecordSchema, BotConnectionRecordSchema, BotRuleRecordSchema, BotUpdateRecordSchema,
+  RES_BOT_ACTIVITY, RES_BOT_CONNECTION, RES_BOT_RULE, RES_BOT_UPDATE,
+} from '@owlmeans/server-bot'
+import type { BotActivityRecord, BotConnectionRecord, BotRuleRecord, BotUpdateRecord } from '@owlmeans/server-bot'
+
+import type { BotActivityResource, BotConnectionResource, BotRuleResource, BotUpdateResource } from './types.js'
+import type { IndexList } from './types.local.js'
+
+/**
+ * Declare the indexes a maker owns, each once. Declarations are kept per alias at module scope, so a
+ * maker that runs twice (a target's file wrapping it, a spec) would otherwise declare every index
+ * again and the compiler would warn about the duplicate on every boot. The name carries the table,
+ * so a second set of bot tables under other aliases in the same schema never collides with the first.
+ */
+const declareIndexes = <T extends ResourceRecord>(resource: PostgresResource<T>, alias: string, indexes: IndexList): void => {
+  const table = pgNameHelper.pgIdentifier(alias)
+  const declared = pgDeclarationHelper.getDeclaration(alias).indexes
+  for (const [suffix, spec] of indexes) {
+    const name = `${table}_${suffix}`
+    if (!declared.some(index => index.name === name)) {
+      resource.index(name, spec)
+    }
+  }
+}
+
+/**
+ * `bot-connection` — the connections of every scope. The schema is `server-bot`'s own, assigned, never
+ * copied: `identity` compiles to one `jsonb` column, `setup` and `credentialsSet` to `text[]`, the
+ * sealed credentials to one `text` column. Indexes follow the reads: a scope's list by creation, and
+ * the worker's reconciliation (enabled, connected, polling or on the gateway).
+ */
+export const makeBotConnectionResource = (
+  dbAlias?: string, alias: string = RES_BOT_CONNECTION, serviceAlias?: string
+): BotConnectionResource => {
+  const resource = makePostgresResource<BotConnectionRecord, BotConnectionResource>(alias, dbAlias, serviceAlias)
+  resource.schema = BotConnectionRecordSchema
+  declareIndexes(resource, alias, [
+    ['scope_created', { columns: ['scope', 'createdAt'] }],
+    ['receive', { columns: ['enabled', 'status', 'receive'] }],
+  ])
+
+  return resource
+}
+
+/**
+ * `bot-rule` — keyword rules, scope-wide (`connection` null) or bound to one connection; `keywords` is
+ * `text[]`, `order` a `double precision` column (quoted wherever the store names it).
+ */
+export const makeBotRuleResource = (
+  dbAlias?: string, alias: string = RES_BOT_RULE, serviceAlias?: string
+): BotRuleResource => {
+  const resource = makePostgresResource<BotRuleRecord, BotRuleResource>(alias, dbAlias, serviceAlias)
+  resource.schema = BotRuleRecordSchema
+  declareIndexes(resource, alias, [
+    ['scope', { columns: ['scope'] }],
+    ['scope_connection', { columns: ['scope', 'connection'] }],
+  ])
+
+  return resource
+}
+
+/**
+ * `bot-update` — the inbox. `dedupe` is UNIQUE: two concurrent deliveries of one platform update
+ * collide here (`RecordExists`) and the service reads the stored row back. The normalized `update`
+ * is one `jsonb` column, `handled` a `text[]`. Indexes follow the dispatcher (pending rows by age,
+ * expired leases), a connection's newest update, and the retention purge.
+ */
+export const makeBotUpdateResource = (
+  dbAlias?: string, alias: string = RES_BOT_UPDATE, serviceAlias?: string
+): BotUpdateResource => {
+  const resource = makePostgresResource<BotUpdateRecord, BotUpdateResource>(alias, dbAlias, serviceAlias)
+  resource.schema = BotUpdateRecordSchema
+  declareIndexes(resource, alias, [
+    ['dedupe', { columns: ['dedupe'], unique: true }],
+    ['inbox', { columns: ['status', 'receivedAt'] }],
+    ['lease', { columns: ['status', 'claimedAt'] }],
+    ['connection_received', { columns: ['connection', 'receivedAt'] }],
+    ['retention', { columns: ['status', 'processedAt'] }],
+  ])
+
+  return resource
+}
+
+/** `bot-activity` — what every action did; `target` is one `jsonb` column. Read newest first per scope. */
+export const makeBotActivityResource = (
+  dbAlias?: string, alias: string = RES_BOT_ACTIVITY, serviceAlias?: string
+): BotActivityResource => {
+  const resource = makePostgresResource<BotActivityRecord, BotActivityResource>(alias, dbAlias, serviceAlias)
+  resource.schema = BotActivityRecordSchema
+  declareIndexes(resource, alias, [
+    ['scope_at', { columns: ['scope', 'at'] }],
+    ['scope_connection_at', { columns: ['scope', 'connection', 'at'] }],
+  ])
+
+  return resource
+}

package/src/types.local.ts

@@ -0,0 +1,4 @@
+import type { PgIndexSpec } from '@owlmeans/postgres-resource'
+
+/** The indexes a maker owns, by name suffix — the full name is `<table>_<suffix>`. */
+export type IndexList = ReadonlyArray<readonly [suffix: string, spec: PgIndexSpec]>

package/src/types.ts

@@ -0,0 +1,28 @@
+import type { PostgresResource } from '@owlmeans/postgres-resource'
+import type {
+  BotActivityRecord, BotConnectionRecord, BotResourceAliases, BotRuleRecord, BotUpdateRecord,
+} from '@owlmeans/server-bot'
+
+/** `bot-connection` — one row per connected bot, its credentials sealed in one text column. */
+export interface BotConnectionResource extends PostgresResource<BotConnectionRecord> {}
+
+/** `bot-rule` — the keyword rules of a scope, scope-wide or bound to one connection. */
+export interface BotRuleResource extends PostgresResource<BotRuleRecord> {}
+
+/** `bot-update` — the inbox: one row per inbound platform update, unique by its `dedupe` key. */
+export interface BotUpdateResource extends PostgresResource<BotUpdateRecord> {}
+
+/** `bot-activity` — one row per action a bot took (or refused), newest read first. */
+export interface BotActivityResource extends PostgresResource<BotActivityRecord> {}
+
+export interface BotPostgresOptions {
+  /** The `cfg.dbs` entry the four tables live in — default `postgres`. */
+  dbAlias?: string
+  /** The Postgres connection service — default `postgres`. */
+  serviceAlias?: string
+  /**
+   * The resources' aliases — default `bot-connection`, `bot-rule`, `bot-update`, `bot-activity`.
+   * The bot service must be given the same ones (`appendBot(ctx, { resources })`).
+   */
+  resources?: BotResourceAliases
+}

package/tests/conformance.spec.ts

@@ -0,0 +1,41 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { botConformance, botConformanceCasesFor, makeBotConformanceSubject } from '@owlmeans/server-bot/conformance'
+import type { BotConformanceSubject } from '@owlmeans/server-bot/conformance'
+
+import { gate, makeSuite } from './context.js'
+
+/**
+ * The store conformance suite of `@owlmeans/server-bot`, against a real database: every case,
+ * including the one only a store with a unique dedupe index qualifies for. Each case works in a scope
+ * of its own, so one booted context serves them all.
+ */
+const suite = makeSuite('conformance')
+const cases = botConformanceCasesFor(['unique'])
+
+describe('@owlmeans/bot-postgres — store conformance', () => {
+  test('a store with the unique dedupe index qualifies for every case', () => {
+    expect(cases.length).toBe(botConformance.length)
+  })
+
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'postgres gate closed', () => {})
+
+    return
+  }
+
+  let subject: BotConformanceSubject
+
+  beforeAll(async () => {
+    await suite.boot({
+      prepare: context => { subject = makeBotConformanceSubject(context, { capabilities: ['unique'] }) },
+    })
+  })
+
+  afterAll(async () => {
+    await suite.teardown()
+  })
+
+  for (const entry of cases) {
+    test(entry.name, async () => { await entry.run(subject) }, 20_000)
+  }
+})

package/tests/context.ts

@@ -0,0 +1,103 @@
+import { randomNamespace, gateHelper } from '@owlmeans/test-integration'
+import type { IntegrationGate, PostgresEnv } from '@owlmeans/test-integration'
+import { configureLog, logger } from '@owlmeans/log'
+import { PgAutoSync } from '@owlmeans/postgres-resource'
+import { config, makeServerContext } from '@owlmeans/server-context'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import { Pool } from 'pg'
+
+import { appendPostgres } from '@owlmeans/postgres'
+import type { PostgresService } from '@owlmeans/postgres'
+
+import { appendPostgresBot } from '../src/index.js'
+import type { BotPostgresOptions } from '../src/index.js'
+
+// Handler failures and refused actions are expected in the conformance cases; `LOG_LEVEL=debug` shows them.
+configureLog({ level: process.env.LOG_LEVEL ?? 'error' })
+
+const log = logger('bot-postgres:tests')
+
+/**
+ * Env-gated integration harness, the shape `@owlmeans/marketing-consent-postgres` and
+ * `@owlmeans/planning-postgres` use: a real `ServerContext` per boot against a throwaway schema of
+ * this suite's own, dropped in `teardown()`. Specs skip cleanly when `POSTGRES_URL` is unset or
+ * nothing answers at it.
+ */
+export const gate: IntegrationGate<PostgresEnv> = gateHelper.postgresGate()
+
+const url = (): string => gate.env.POSTGRES_URL as string
+
+export const raw = async <R>(fn: (pool: Pool) => Promise<R>): Promise<R> => {
+  const pool = new Pool({ connectionString: url(), max: 1 })
+  try {
+    return await fn(pool)
+  } finally {
+    await pool.end().catch(() => undefined)
+  }
+}
+
+export interface BootOptions {
+  /** Passed to `appendPostgresBot`. */
+  bot?: BotPostgresOptions
+  /** Runs after the resources are registered and before `init()` — where a service is appended. */
+  prepare?: (context: ServerContext<ServerConfig>) => void
+}
+
+export interface Booted {
+  context: ServerContext<ServerConfig>
+  pg: PostgresService
+}
+
+export interface Suite {
+  schema: string
+  boot: (opts?: BootOptions) => Promise<Booted>
+  teardown: () => Promise<void>
+}
+
+export const makeSuite = (label: string): Suite => {
+  const prefix = process.env.POSTGRES_TEST_DB_PREFIX ?? 'omt'
+  const schema = randomNamespace(`${prefix}_bot_${label}`)
+  const pools: Pool[] = []
+
+  const boot = async (opts: BootOptions = {}): Promise<Booted> => {
+    const cfg: ServerConfig = config('bot-pg-test', {
+      dbs: [{
+        service: 'postgres', alias: 'postgres', host: '127.0.0.1', schema,
+        meta: { url: url(), max: 4, retries: 3, retryDelayMillis: 200, autoSync: PgAutoSync.Full },
+      }],
+    } as Partial<ServerConfig>)
+
+    const context = makeServerContext(cfg) as ServerContext<ServerConfig>
+    appendPostgres(context)
+    appendPostgresBot(context, opts.bot)
+    opts.prepare?.(context)
+
+    context.configure()
+    const pg = context.service<PostgresService>('postgres')
+    try {
+      await context.init()
+    } finally {
+      for (const pool of Object.values(pg.clients ?? {})) {
+        if (!pools.includes(pool)) {
+          pools.push(pool)
+        }
+      }
+    }
+
+    return { context, pg }
+  }
+
+  const teardown = async (): Promise<void> => {
+    if (gate.skip) {
+      return
+    }
+    await raw(async pool => { await pool.query(`DROP SCHEMA IF EXISTS "${schema}" CASCADE`) })
+      .catch(error => log.error('Test schema not dropped', { schema, error }))
+    /** After the drop — a pool still holding the schema open makes CASCADE wait. */
+    while (pools.length > 0) {
+      await pools.pop()?.end().catch(() => undefined)
+    }
+  }
+
+  return { schema, boot, teardown }
+}

package/tests/schema.spec.ts

@@ -0,0 +1,187 @@
+import { describe, expect, test } from 'bun:test'
+import { AppType, makeBasicContext, type BasicConfig } from '@owlmeans/context'
+import { addLogPlugin, memoryPlugin } from '@owlmeans/log'
+import { pgDeclarationHelper, pgDiffHelper, pgSchemaHelper } from '@owlmeans/postgres-resource'
+import type { TableSpec } from '@owlmeans/postgres-resource'
+import {
+  BotActivityRecordSchema, BotConnectionRecordSchema, BotRuleRecordSchema, BotUpdateRecordSchema,
+  RES_BOT_ACTIVITY, RES_BOT_CONNECTION, RES_BOT_RULE, RES_BOT_UPDATE,
+} from '@owlmeans/server-bot'
+
+import {
+  appendPostgresBot, makeBotActivityResource, makeBotConnectionResource, makeBotRuleResource, makeBotUpdateResource,
+} from '../src/index.js'
+import type { BotUpdateResource } from '../src/index.js'
+
+const ALIASES = [RES_BOT_CONNECTION, RES_BOT_RULE, RES_BOT_UPDATE, RES_BOT_ACTIVITY]
+
+const SCHEMAS: Record<string, object> = {
+  [RES_BOT_CONNECTION]: BotConnectionRecordSchema,
+  [RES_BOT_RULE]: BotRuleRecordSchema,
+  [RES_BOT_UPDATE]: BotUpdateRecordSchema,
+  [RES_BOT_ACTIVITY]: BotActivityRecordSchema,
+}
+
+const reset = (): void => {
+  for (const alias of ALIASES) {
+    pgDeclarationHelper.resetDeclarations(alias)
+  }
+}
+
+const makeAll = (): void => {
+  makeBotConnectionResource()
+  makeBotRuleResource()
+  makeBotUpdateResource()
+  makeBotActivityResource()
+}
+
+/** What `init()` compiles for an alias: the shared schema plus the maker's declared indexes. */
+const specOf = (alias: string): TableSpec => pgSchemaHelper.schemaToTableSpec(
+  alias, SCHEMAS[alias] as never, 'app', alias.replace('-', '_'), true, pgDeclarationHelper.getDeclaration(alias).indexes
+)
+
+const typeOf = (spec: TableSpec, property: string) => {
+  const column = spec.byProperty[property]
+
+  return { sqlType: column.sqlType, jsonb: column.jsonb, array: column.array, notNull: column.notNull }
+}
+
+/** The DDL a fresh table is created with — what `init()` runs against an empty schema. */
+const ddlOf = (spec: TableSpec): string[] =>
+  pgDiffHelper.planSync(spec, { exists: false, columns: [], indexes: [], constraints: [] }).statements.map(entry => entry.sql)
+
+/**
+ * No database: `schemaToTableSpec` is the compiler `init()` runs, so what each table becomes is
+ * pinned here — nested objects are one `jsonb` column, string lists native `text[]`, timestamps
+ * `text` (never `timestamptz`, which would marshal through `Date`), and the reserved `order` column
+ * is quoted wherever it is named.
+ */
+describe('@owlmeans/bot-postgres — table shapes', () => {
+  test('each maker assigns server-bot\'s schema, not a copy, under the default alias', () => {
+    reset()
+    const made = [makeBotConnectionResource(), makeBotRuleResource(), makeBotUpdateResource(), makeBotActivityResource()]
+
+    expect(made.map(resource => resource.alias)).toEqual(ALIASES)
+    expect(made.map(resource => resource.schema)).toEqual(ALIASES.map(alias => SCHEMAS[alias]))
+    made.forEach((resource, at) => expect(resource.schema).toBe(SCHEMAS[ALIASES[at]] as never))
+  })
+
+  test('every table has exactly its schema\'s properties as columns, timestamps as text', () => {
+    reset()
+    makeAll()
+    for (const alias of ALIASES) {
+      const spec = specOf(alias)
+      const properties = Object.keys((SCHEMAS[alias] as { properties: object }).properties).sort()
+      expect([alias, spec.columns.map(column => column.property).sort()]).toEqual([alias, properties])
+      expect([alias, spec.primaryKey]).toEqual([alias, ['id']])
+      for (const column of spec.columns.filter(entry => /At$/.test(entry.property))) {
+        expect([alias, column.property, column.sqlType, column.jsonType]).toEqual([alias, column.property, 'text', 'string'])
+      }
+    }
+  })
+
+  test('nested objects are one jsonb column each; string lists are native text[]', () => {
+    reset()
+    makeAll()
+    const connection = specOf(RES_BOT_CONNECTION)
+    const rule = specOf(RES_BOT_RULE)
+    const update = specOf(RES_BOT_UPDATE)
+    const activity = specOf(RES_BOT_ACTIVITY)
+
+    const jsonb = { sqlType: 'jsonb', jsonb: true, array: false }
+    expect(typeOf(connection, 'identity')).toEqual({ ...jsonb, notNull: false })
+    expect(typeOf(update, 'update')).toEqual({ ...jsonb, notNull: true })
+    expect(typeOf(activity, 'target')).toEqual({ ...jsonb, notNull: false })
+
+    const strings = { sqlType: 'text[]', jsonb: false, array: true }
+    expect(typeOf(connection, 'setup')).toEqual({ ...strings, notNull: false })
+    expect(typeOf(connection, 'credentialsSet')).toEqual({ ...strings, notNull: true })
+    expect(typeOf(rule, 'keywords')).toEqual({ ...strings, notNull: true })
+    expect(typeOf(update, 'handled')).toEqual({ ...strings, notNull: true })
+
+    /** The sealed credentials are ONE opaque text column, never split per credential key. */
+    expect(typeOf(connection, 'sealed')).toEqual({ sqlType: 'text', jsonb: false, array: false, notNull: false })
+    expect(typeOf(update, 'attempts').sqlType).toBe('integer')
+    expect(typeOf(connection, 'enabled').sqlType).toBe('boolean')
+    expect(connection.checks.map(check => check.name).sort()).toEqual([
+      'bot_connection_platform_enum', 'bot_connection_receive_enum', 'bot_connection_status_enum', 'bot_connection_transport_enum',
+    ])
+  })
+
+  test('the rule\'s order is a double precision column, quoted in the DDL', () => {
+    reset()
+    makeAll()
+    const rule = specOf(RES_BOT_RULE)
+
+    expect([rule.byProperty.order.column, rule.byProperty.order.sqlType, rule.byProperty.order.notNull])
+      .toEqual(['order', 'double precision', true])
+    expect(typeOf(rule, 'connection')).toEqual({ sqlType: 'text', jsonb: false, array: false, notNull: false })
+    const [create] = ddlOf(rule)
+    expect(create).toContain('"order" double precision NOT NULL')
+    expect(create).not.toMatch(/[^"]order[^"]/)
+  })
+
+  test('the inbox dedupe key is a unique index, and every index the reads need is declared', () => {
+    reset()
+    makeAll()
+    const names = (alias: string) => pgDeclarationHelper.getDeclaration(alias).indexes
+      .map(index => [index.name, index.columns, index.unique === true])
+
+    expect(names(RES_BOT_CONNECTION)).toEqual([
+      ['bot_connection_scope_created', ['scope', 'createdAt'], false],
+      ['bot_connection_receive', ['enabled', 'status', 'receive'], false],
+    ])
+    expect(names(RES_BOT_RULE)).toEqual([
+      ['bot_rule_scope', ['scope'], false],
+      ['bot_rule_scope_connection', ['scope', 'connection'], false],
+    ])
+    expect(names(RES_BOT_UPDATE)).toEqual([
+      ['bot_update_dedupe', ['dedupe'], true],
+      ['bot_update_inbox', ['status', 'receivedAt'], false],
+      ['bot_update_lease', ['status', 'claimedAt'], false],
+      ['bot_update_connection_received', ['connection', 'receivedAt'], false],
+      ['bot_update_retention', ['status', 'processedAt'], false],
+    ])
+    expect(names(RES_BOT_ACTIVITY)).toEqual([
+      ['bot_activity_scope_at', ['scope', 'at'], false],
+      ['bot_activity_scope_connection_at', ['scope', 'connection', 'at'], false],
+    ])
+    expect(ddlOf(specOf(RES_BOT_UPDATE))).toContain(
+      'CREATE UNIQUE INDEX "bot_update_dedupe" ON "app"."bot_update" USING btree ("dedupe")'
+    )
+  })
+
+  test('a maker run twice declares its indexes once, and nothing warns at compile time', () => {
+    reset()
+    const memory = memoryPlugin('bot-postgres-schema')
+    const remove = addLogPlugin(memory)
+    try {
+      makeAll()
+      makeAll()
+      for (const alias of ALIASES) {
+        const names = pgDeclarationHelper.getDeclaration(alias).indexes.map(index => index.name)
+        expect([alias, names.length]).toEqual([alias, new Set(names).size])
+        specOf(alias)
+      }
+      expect(memory.records.filter(record => record.level === 'warn' || record.level === 'error')).toEqual([])
+    } finally {
+      remove()
+    }
+  })
+
+  test('appendPostgresBot registers the four once, and custom aliases name their own tables and indexes', () => {
+    const context = makeBasicContext<BasicConfig>({ ready: false, service: 'bot-pg-schema', type: AppType.Backend, services: {} })
+    appendPostgresBot(context)
+    const first = ALIASES.map(alias => context.resource(alias))
+    appendPostgresBot(context)
+    expect(ALIASES.map(alias => context.resource(alias))).toEqual(first)
+    first.forEach((resource, at) => expect(context.resource(ALIASES[at])).toBe(resource))
+
+    const custom = { connection: 'chat-connection', rule: 'chat-rule', update: 'chat-update', activity: 'chat-activity' }
+    appendPostgresBot(context, { resources: custom })
+    expect(Object.values(custom).map(alias => context.resource<BotUpdateResource>(alias).schema))
+      .toEqual(ALIASES.map(alias => SCHEMAS[alias]))
+    expect(pgDeclarationHelper.getDeclaration('chat-update').indexes.map(index => index.name))
+      .toContain('chat_update_dedupe')
+  })
+})

package/tests/tables.spec.ts

@@ -0,0 +1,89 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+import { makePgIntrospectHelper, pgDiffHelper } from '@owlmeans/postgres-resource'
+import type { PostgresResource } from '@owlmeans/postgres-resource'
+import { BotChatKind, BotMatchMode, BotPlatform, BotRuleAction, BotUpdateKind } from '@owlmeans/bot'
+import { RecordExists } from '@owlmeans/resource'
+import { BotInboxStatus, RES_BOT_ACTIVITY, RES_BOT_CONNECTION, RES_BOT_RULE, RES_BOT_UPDATE } from '@owlmeans/server-bot'
+import type { BotUpdateRecord } from '@owlmeans/server-bot'
+
+import { appendPostgresBot } from '../src/index.js'
+import type { BotRuleResource, BotUpdateResource } from '../src/index.js'
+import { gate, makeSuite } from './context.js'
+
+const ALIASES = [RES_BOT_CONNECTION, RES_BOT_RULE, RES_BOT_UPDATE, RES_BOT_ACTIVITY]
+
+const suite = makeSuite('tables')
+const it = gate.skip ? test.skip : test
+
+/** An inbox row as the service writes it — no id: Postgres mints it. */
+const inboxRow = (dedupe: string): Omit<BotUpdateRecord, 'id'> => ({
+  scope: 'tables', connection: 'c-1', platform: BotPlatform.Telegram, dedupe,
+  status: BotInboxStatus.Pending, attempts: 0, handled: [], receivedAt: '2026-10-26T10:00:00.000Z',
+  update: {
+    connection: 'c-1', scope: 'tables', platform: BotPlatform.Telegram, kind: BotUpdateKind.Message,
+    chat: { id: '-100', kind: BotChatKind.Group }, addressed: false, receivedAt: '2026-10-26T10:00:00.000Z',
+  },
+})
+
+describe('@owlmeans/bot-postgres — tables against a real database', () => {
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'postgres gate closed', () => {})
+
+    return
+  }
+
+  afterAll(async () => {
+    await suite.teardown()
+  })
+
+  it('a second boot reconciles nothing on any of the four tables', async () => {
+    await suite.boot()
+    const again = await suite.boot()
+    const { pool } = await again.context.resource<PostgresResource<never>>(RES_BOT_CONNECTION).db()
+    const client = await pool.connect()
+    try {
+      for (const alias of ALIASES) {
+        const table = again.context.resource<PostgresResource<never>>(alias).table
+        expect(table.qualified).toBe(`"${suite.schema}"."${alias.replace('-', '_')}"`)
+        const live = await makePgIntrospectHelper(client).introspectTable(table.schema, table.table, table.qualified)
+        expect([alias, pgDiffHelper.planSync(table, live).statements.map(statement => statement.sql)]).toEqual([alias, []])
+      }
+    } finally {
+      client.release()
+    }
+  })
+
+  it('round-trips nested values, string lists and the order column; the dedupe key is unique', async () => {
+    const { context } = await suite.boot()
+    const updates = context.resource<BotUpdateResource>(RES_BOT_UPDATE)
+    const rules = context.resource<BotRuleResource>(RES_BOT_RULE)
+
+    const row = await updates.create(inboxRow('c-1:telegram:1'))
+    expect(typeof row.id).toBe('string')
+    const stored = await updates.get(row.id!)
+    expect([stored.handled, stored.update.chat, stored.claimedAt]).toEqual([[], { id: '-100', kind: BotChatKind.Group }, null])
+    await expect(updates.create(inboxRow('c-1:telegram:1'))).rejects.toThrow(RecordExists)
+
+    const rule = await rules.create({
+      scope: 'tables', name: 'Spam', keywords: ['casino', 'free money'], mode: BotMatchMode.Word, action: BotRuleAction.Delete,
+      enabled: true, order: 2.5, createdAt: '2026-10-26T10:00:00.000Z', updatedAt: '2026-10-26T10:00:00.000Z',
+    })
+    const sorted = await rules.list({ scope: 'tables' }, { sort: [{ field: 'order', order: 'desc' }] })
+    expect(sorted.items.map(item => [item.id, item.order, item.keywords, item.connection])).toEqual([
+      [rule.id, 2.5, ['casino', 'free money'], null],
+    ])
+  })
+
+  it('custom aliases get tables and index names of their own', async () => {
+    const custom = { connection: 'chat-connection', rule: 'chat-rule', update: 'chat-update', activity: 'chat-activity' }
+    const { context } = await suite.boot({ bot: { resources: custom } })
+    const registered = context.resource(custom.update)
+    appendPostgresBot(context, { resources: custom })
+    expect(context.resource(custom.update)).toBe(registered)
+
+    const updates = context.resource<BotUpdateResource>(custom.update)
+    expect(updates.table.table).toBe('chat_update')
+    await updates.create(inboxRow('c-1:telegram:2'))
+    await expect(updates.create(inboxRow('c-1:telegram:2'))).rejects.toThrow(RecordExists)
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "types": ["bun"],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": ["./**/*", "../src/**/*"]
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
+}