@owlmeans/marketing-consent-postgres 0.1.18-rc.0

package/README.md

@@ -0,0 +1,15 @@
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
+
+```sh
+npx @owlmeans/agent-skills@^0.1.18-rc.33
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 2,
+  "package": "@owlmeans/marketing-consent-postgres",
+  "version": "0.1.18-rc.0",
+  "generatedAt": "2026-09-22T17:37:10.922Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "marketing-consent-postgres",
+      "category": "package-specific",
+      "file": "skills/marketing-consent-postgres/SKILL.md",
+      "canonicalPath": ".agents/skills/marketing-consent-postgres/SKILL.md"
+    }
+  ]
+}

package/agent-meta/skills/marketing-consent-postgres/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: marketing-consent-postgres
+description: How to use @owlmeans/marketing-consent-postgres — the Postgres extension that registers the two @owlmeans/server-marketing-consent resources (marketing-consent-state, marketing-consent-log) for a GENERATED TARGET PROJECT. Auto-invoked when wiring marketing-consent storage into a target project's Postgres backend, or touching the state/log table shape.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/marketing-consent-postgres
+
+**Layer:** Infra extension
+**Install:** `"@owlmeans/marketing-consent-postgres": "^0.1.18-rc.0"` in `dependencies` (peers `pg`, `ajv`)
+
+The Postgres counterpart to `@owlmeans/server-marketing-consent`'s two resources. This package is
+for a **generated target project**, which runs Postgres — the platform's own equivalent for
+projects that stayed on Mongo is `@owlmeans/marketing-consent-mongo` (a separate, not-yet-built
+package); Viable itself runs Mongo and never needs this one.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `makeMarketingConsentStatePostgres(dbAlias?, serviceAlias?)` | `PostgresResource<MarketingConsentStateRecord>` at `RES_MARKETING_CONSENT_STATE` |
+| `makeMarketingConsentLogPostgres(dbAlias?, serviceAlias?)` | `PostgresResource<MarketingConsentLogRecord>` at `RES_MARKETING_CONSENT_LOG` |
+| `appendMarketingConsentPostgres(ctx, opts?)` | Registers both, each guarded by `ctx.hasResource(...)` — safe to call more than once |
+
+## The schema is imported, never redeclared
+
+Both makers set `resource.schema` to `MarketingConsentStateSchema` / `MarketingConsentLogSchema`
+from `@owlmeans/server-marketing-consent` — this package owns no AJV schema of its own. The two
+record shapes are shared with the (not yet built) `@owlmeans/marketing-consent-mongo` sibling;
+duplicating the schema here would let the two extensions drift apart from what
+`MarketingConsentService` actually reads and writes.
+
+## `decisions` / `terms` / `documents` / `notices` are one jsonb column each — never split
+
+`MarketingConsentStateRecord.decisions` is an ARRAY, never an object keyed by consent key —
+`server-marketing-consent`'s own skill explains why: a dotted key like `"marketing.email"` is read
+as a PATH by Postgres jsonb operators, so an object-keyed shape breaks the moment a second key is
+added. This package does nothing to make that safe by itself — it relies on
+`@owlmeans/postgres-resource`'s **default** schema-to-table rule: any `array` of objects (or any
+nested `object` property) compiles to a single opaque `jsonb` column, never a child table and never
+one column per field. No `pg:` override is applied here, and none is needed — `tests/schema.spec.ts`
+asserts this directly against `schemaToTableSpec`, which is the one test that would catch a
+regression here (in this package, in `postgres-resource`'s compiler, or in a future schema edit
+that accidentally reshapes `decisions` into something path-addressable).
+
+## Indexes
+
+- `idx_mc_state_subject` — `{ columns: ['subject'], unique: true }`: one state row per subject,
+  the same invariant `subjectKey(subject)` being the record's own `id` already gives on the Mongo
+  side.
+- `idx_mc_state_user` — `{ columns: ['userId'] }`: lookups across a user's profiles/entities.
+- `idx_mc_log_subject_key` — `{ columns: ['subject', 'key', 'decidedAt'] }`: a subject's history
+  for one consent key, newest first.
+- `idx_mc_log_user` — `{ columns: ['userId', 'decidedAt'] }`: a user's whole consent/terms history.
+
+## Wiring
+
+```ts
+import { appendMarketingConsentPostgres } from '@owlmeans/marketing-consent-postgres'
+import { appendMarketingConsentService } from '@owlmeans/server-marketing-consent'
+
+appendMarketingConsentPostgres(context) // register the two Postgres resources first
+appendMarketingConsentService(context)  // the service resolves them by alias, lazily, per call
+```
+
+Registration order relative to the service append only matters for the resources needing to exist
+by the first `status`/`save`/`terms` call — `server-marketing-consent`'s own skill covers this.
+
+## Testing
+
+`bun test ./tests` — `tests/schema.spec.ts` needs no live database (the jsonb-shape assertion
+above); `tests/resource.spec.ts` is env-gated on `POSTGRES_URL` exactly like
+`@owlmeans/postgres-resource`'s own integration suites (`@owlmeans/test-integration`'s
+`postgresGate()`), and skips cleanly with no server reachable.
+
+## Related
+
+- `@owlmeans/server-marketing-consent` — the service, the record types, the AJV schemas this
+  package imports (read its skill first)
+- `@owlmeans/postgres-resource` — the resource factory, the schema-to-table compiler, `PgIndexSpec`
+- `@owlmeans/marketing-consent-mongo` — the Mongo counterpart for the platform's own database (not
+  yet built)

package/build/helper.d.ts

@@ -0,0 +1,12 @@
+import type { BasicContext } from '@owlmeans/context';
+export interface MarketingConsentPostgresOptions {
+    dbAlias?: string;
+    serviceAlias?: string;
+}
+/**
+ * Registers the two Postgres resources this package owns, once. A context that already has
+ * either resource registered — a repeated call from an app that composes contexts in more than
+ * one place — is left alone, which is also what keeps this idempotent across a hot reload.
+ */
+export declare const appendMarketingConsentPostgres: (ctx: BasicContext<any>, opts?: MarketingConsentPostgresOptions) => void;
+//# sourceMappingURL=helper.d.ts.map

package/build/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAKrD,MAAM,WAAW,+BAA+B;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,QACpC,YAAY,CAAC,GAAG,CAAC,SAAS,+BAA+B,KAC7D,IAOF,CAAA"}

package/build/helper.js

@@ -0,0 +1,16 @@
+import { RES_MARKETING_CONSENT_LOG, RES_MARKETING_CONSENT_STATE } from '@owlmeans/server-marketing-consent';
+import { makeMarketingConsentLogPostgres, makeMarketingConsentStatePostgres } from './resource.js';
+/**
+ * Registers the two Postgres resources this package owns, once. A context that already has
+ * either resource registered — a repeated call from an app that composes contexts in more than
+ * one place — is left alone, which is also what keeps this idempotent across a hot reload.
+ */
+export const appendMarketingConsentPostgres = (ctx, opts) => {
+    if (!ctx.hasResource(RES_MARKETING_CONSENT_STATE)) {
+        ctx.registerResource(makeMarketingConsentStatePostgres(opts?.dbAlias, opts?.serviceAlias));
+    }
+    if (!ctx.hasResource(RES_MARKETING_CONSENT_LOG)) {
+        ctx.registerResource(makeMarketingConsentLogPostgres(opts?.dbAlias, opts?.serviceAlias));
+    }
+};
+//# sourceMappingURL=helper.js.map

package/build/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,yBAAyB,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAA;AAE3G,OAAO,EAAE,+BAA+B,EAAE,iCAAiC,EAAE,MAAM,eAAe,CAAA;AAOlG;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAC5C,GAAsB,EAAE,IAAsC,EACxD,EAAE;IACR,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,2BAA2B,CAAC,EAAE,CAAC;QAClD,GAAG,CAAC,gBAAgB,CAAC,iCAAiC,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAA;IAC5F,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,yBAAyB,CAAC,EAAE,CAAC;QAChD,GAAG,CAAC,gBAAgB,CAAC,+BAA+B,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAA;IAC1F,CAAC;AACH,CAAC,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,3 @@
+export * from './resource.js';
+export * from './helper.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA"}

package/build/index.js

@@ -0,0 +1,3 @@
+export * from './resource.js';
+export * from './helper.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA"}

package/build/resource.d.ts

@@ -0,0 +1,19 @@
+import type { PostgresResource } from '@owlmeans/postgres-resource';
+import type { MarketingConsentLogRecord, MarketingConsentStateRecord } from '@owlmeans/server-marketing-consent';
+/**
+ * One row per subject. `decisions`/`terms` compile to a single `jsonb` column each — the AJV
+ * schema declares them as a nested array/object with no `pg:` override, and
+ * `schemaToTableSpec`'s default rule for "any array of objects, or a nested object" is exactly
+ * that: one opaque `jsonb` column, never a child table or one column per field. That is load
+ * bearing here, not incidental — `decisions` holds dotted keys such as `"marketing.email"`, and
+ * flattening it into columns or a keyed jsonb path would make that key readable as a PATH by
+ * Postgres' own jsonb operators (see `@owlmeans/server-marketing-consent`'s `model.ts`). This
+ * maker never reshapes the record; it only imports the schema and adds the indexes below.
+ */
+export declare const makeMarketingConsentStatePostgres: (dbAlias?: string, serviceAlias?: string) => PostgresResource<MarketingConsentStateRecord>;
+/**
+ * Append-only evidence log — same jsonb-column reasoning as the state table above applies to
+ * its `documents`/`notices` properties.
+ */
+export declare const makeMarketingConsentLogPostgres: (dbAlias?: string, serviceAlias?: string) => PostgresResource<MarketingConsentLogRecord>;
+//# sourceMappingURL=resource.d.ts.map

package/build/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AAKnE,OAAO,KAAK,EAAE,yBAAyB,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAA;AAEhH;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,aAClC,MAAM,iBAAiB,MAAM,KACtC,gBAAgB,CAAC,2BAA2B,CAS9C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,+BAA+B,aAChC,MAAM,iBAAiB,MAAM,KACtC,gBAAgB,CAAC,yBAAyB,CAS5C,CAAA"}

package/build/resource.js

@@ -0,0 +1,31 @@
+import { makePostgresResource } from '@owlmeans/postgres-resource';
+import { MarketingConsentLogSchema, MarketingConsentStateSchema, RES_MARKETING_CONSENT_LOG, RES_MARKETING_CONSENT_STATE } from '@owlmeans/server-marketing-consent';
+/**
+ * One row per subject. `decisions`/`terms` compile to a single `jsonb` column each — the AJV
+ * schema declares them as a nested array/object with no `pg:` override, and
+ * `schemaToTableSpec`'s default rule for "any array of objects, or a nested object" is exactly
+ * that: one opaque `jsonb` column, never a child table or one column per field. That is load
+ * bearing here, not incidental — `decisions` holds dotted keys such as `"marketing.email"`, and
+ * flattening it into columns or a keyed jsonb path would make that key readable as a PATH by
+ * Postgres' own jsonb operators (see `@owlmeans/server-marketing-consent`'s `model.ts`). This
+ * maker never reshapes the record; it only imports the schema and adds the indexes below.
+ */
+export const makeMarketingConsentStatePostgres = (dbAlias, serviceAlias) => {
+    const resource = makePostgresResource(RES_MARKETING_CONSENT_STATE, dbAlias, serviceAlias);
+    resource.schema = MarketingConsentStateSchema;
+    resource.index('idx_mc_state_subject', { columns: ['subject'], unique: true });
+    resource.index('idx_mc_state_user', { columns: ['userId'] });
+    return resource;
+};
+/**
+ * Append-only evidence log — same jsonb-column reasoning as the state table above applies to
+ * its `documents`/`notices` properties.
+ */
+export const makeMarketingConsentLogPostgres = (dbAlias, serviceAlias) => {
+    const resource = makePostgresResource(RES_MARKETING_CONSENT_LOG, dbAlias, serviceAlias);
+    resource.schema = MarketingConsentLogSchema;
+    resource.index('idx_mc_log_subject_key', { columns: ['subject', 'key', 'decidedAt'] });
+    resource.index('idx_mc_log_user', { columns: ['userId', 'decidedAt'] });
+    return resource;
+};
+//# sourceMappingURL=resource.js.map

package/build/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAElE,OAAO,EACL,yBAAyB,EAAE,2BAA2B,EACtD,yBAAyB,EAAE,2BAA2B,EACvD,MAAM,oCAAoC,CAAA;AAG3C;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAC/C,OAAgB,EAAE,YAAqB,EACQ,EAAE;IACjD,MAAM,QAAQ,GAAG,oBAAoB,CACnC,2BAA2B,EAAE,OAAO,EAAE,YAAY,CACnD,CAAA;IACD,QAAQ,CAAC,MAAM,GAAG,2BAA2B,CAAA;IAC7C,QAAQ,CAAC,KAAK,CAAC,sBAAsB,EAAE,EAAE,OAAO,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;IAC9E,QAAQ,CAAC,KAAK,CAAC,mBAAmB,EAAE,EAAE,OAAO,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;IAE5D,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAC7C,OAAgB,EAAE,YAAqB,EACM,EAAE;IAC/C,MAAM,QAAQ,GAAG,oBAAoB,CACnC,yBAAyB,EAAE,OAAO,EAAE,YAAY,CACjD,CAAA;IACD,QAAQ,CAAC,MAAM,GAAG,yBAAyB,CAAA;IAC3C,QAAQ,CAAC,KAAK,CAAC,wBAAwB,EAAE,EAAE,OAAO,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,WAAW,CAAC,EAAE,CAAC,CAAA;IACtF,QAAQ,CAAC,KAAK,CAAC,iBAAiB,EAAE,EAAE,OAAO,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,EAAE,CAAC,CAAA;IAEvE,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@owlmeans/marketing-consent-postgres",
+  "version": "0.1.18-rc.0",
+  "license": "MIT",
+  "description": "Postgres-backed resources for @owlmeans/marketing-consent — the state and log tables of a generated target project, compiled from the shared AJV schema in @owlmeans/server-marketing-consent.",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 2 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@owlmeans/context": "^0.1.18-rc.29",
+    "@owlmeans/marketing-consent": "^0.1.18-rc.0",
+    "@owlmeans/postgres-resource": "^0.1.18-rc.31",
+    "@owlmeans/resource": "^0.1.18-rc.31",
+    "@owlmeans/server-marketing-consent": "^0.1.18-rc.0"
+  },
+  "peerDependencies": {
+    "ajv": "*",
+    "pg": "*"
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@owlmeans/test": "^0.1.18-rc.29",
+    "@owlmeans/test-integration": "^0.1.18-rc.26",
+    "@types/bun": "^1.4.0",
+    "@types/pg": "^8.20.4",
+    "ajv": "^8.17.1",
+    "nodemon": "^3.1.14",
+    "pg": "^8.22.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/helper.ts

@@ -0,0 +1,25 @@
+import type { BasicContext } from '@owlmeans/context'
+import { RES_MARKETING_CONSENT_LOG, RES_MARKETING_CONSENT_STATE } from '@owlmeans/server-marketing-consent'
+
+import { makeMarketingConsentLogPostgres, makeMarketingConsentStatePostgres } from './resource.js'
+
+export interface MarketingConsentPostgresOptions {
+  dbAlias?: string
+  serviceAlias?: string
+}
+
+/**
+ * Registers the two Postgres resources this package owns, once. A context that already has
+ * either resource registered — a repeated call from an app that composes contexts in more than
+ * one place — is left alone, which is also what keeps this idempotent across a hot reload.
+ */
+export const appendMarketingConsentPostgres = (
+  ctx: BasicContext<any>, opts?: MarketingConsentPostgresOptions
+): void => {
+  if (!ctx.hasResource(RES_MARKETING_CONSENT_STATE)) {
+    ctx.registerResource(makeMarketingConsentStatePostgres(opts?.dbAlias, opts?.serviceAlias))
+  }
+  if (!ctx.hasResource(RES_MARKETING_CONSENT_LOG)) {
+    ctx.registerResource(makeMarketingConsentLogPostgres(opts?.dbAlias, opts?.serviceAlias))
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './resource.js'
+export * from './helper.js'

package/src/resource.ts

@@ -0,0 +1,47 @@
+import { makePostgresResource } from '@owlmeans/postgres-resource'
+import type { PostgresResource } from '@owlmeans/postgres-resource'
+import {
+  MarketingConsentLogSchema, MarketingConsentStateSchema,
+  RES_MARKETING_CONSENT_LOG, RES_MARKETING_CONSENT_STATE
+} from '@owlmeans/server-marketing-consent'
+import type { MarketingConsentLogRecord, MarketingConsentStateRecord } from '@owlmeans/server-marketing-consent'
+
+/**
+ * One row per subject. `decisions`/`terms` compile to a single `jsonb` column each — the AJV
+ * schema declares them as a nested array/object with no `pg:` override, and
+ * `schemaToTableSpec`'s default rule for "any array of objects, or a nested object" is exactly
+ * that: one opaque `jsonb` column, never a child table or one column per field. That is load
+ * bearing here, not incidental — `decisions` holds dotted keys such as `"marketing.email"`, and
+ * flattening it into columns or a keyed jsonb path would make that key readable as a PATH by
+ * Postgres' own jsonb operators (see `@owlmeans/server-marketing-consent`'s `model.ts`). This
+ * maker never reshapes the record; it only imports the schema and adds the indexes below.
+ */
+export const makeMarketingConsentStatePostgres = (
+  dbAlias?: string, serviceAlias?: string
+): PostgresResource<MarketingConsentStateRecord> => {
+  const resource = makePostgresResource<MarketingConsentStateRecord>(
+    RES_MARKETING_CONSENT_STATE, dbAlias, serviceAlias
+  )
+  resource.schema = MarketingConsentStateSchema
+  resource.index('idx_mc_state_subject', { columns: ['subject'], unique: true })
+  resource.index('idx_mc_state_user', { columns: ['userId'] })
+
+  return resource
+}
+
+/**
+ * Append-only evidence log — same jsonb-column reasoning as the state table above applies to
+ * its `documents`/`notices` properties.
+ */
+export const makeMarketingConsentLogPostgres = (
+  dbAlias?: string, serviceAlias?: string
+): PostgresResource<MarketingConsentLogRecord> => {
+  const resource = makePostgresResource<MarketingConsentLogRecord>(
+    RES_MARKETING_CONSENT_LOG, dbAlias, serviceAlias
+  )
+  resource.schema = MarketingConsentLogSchema
+  resource.index('idx_mc_log_subject_key', { columns: ['subject', 'key', 'decidedAt'] })
+  resource.index('idx_mc_log_user', { columns: ['userId', 'decidedAt'] })
+
+  return resource
+}

package/tests/context.ts

@@ -0,0 +1,92 @@
+import { postgresGate, randomNamespace } from '@owlmeans/test-integration'
+import type { IntegrationGate, PostgresEnv } from '@owlmeans/test-integration'
+import { PgAutoSync, resetDeclarations } 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 { RES_MARKETING_CONSENT_LOG, RES_MARKETING_CONSENT_STATE } from '@owlmeans/server-marketing-consent'
+
+import { appendMarketingConsentPostgres } from '../src/index.js'
+
+/**
+ * Env-gated integration harness, the same shape `@owlmeans/postgres`'s own tests use: a real
+ * `ServerContext` against a throwaway schema, dropped in `teardown()`. Lives here rather than
+ * importing the sibling package's own `tests/context.ts`, which is test-only source that no
+ * package exports.
+ */
+export const gate: IntegrationGate<PostgresEnv> = 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 Booted {
+  context: ServerContext<ServerConfig>
+  pg: PostgresService
+}
+
+export interface Suite {
+  schema: string
+  boot: () => Promise<Booted>
+  teardown: () => Promise<void>
+}
+
+export const makeSuite = (label: string): Suite => {
+  const prefix = process.env.POSTGRES_TEST_DB_PREFIX ?? 'omt'
+  const schema = randomNamespace(`${prefix}_${label}`)
+  const pools: Pool[] = []
+
+  const boot = async (): Promise<Booted> => {
+    /** A fresh declaration per suite run — this spec simulates a freshly started process. */
+    resetDeclarations(RES_MARKETING_CONSENT_STATE)
+    resetDeclarations(RES_MARKETING_CONSENT_LOG)
+
+    const cfg: ServerConfig = config('mc-pg-test', {
+      dbs: [{
+        service: 'postgres', alias: 'postgres', host: '127.0.0.1', schema,
+        meta: { url: url(), max: 2, retries: 3, retryDelayMillis: 200, autoSync: PgAutoSync.Full }
+      }]
+    } as Partial<ServerConfig>)
+
+    const context = makeServerContext(cfg) as ServerContext<ServerConfig>
+    appendPostgres(context)
+    appendMarketingConsentPostgres(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 => console.error(`marketing-consent-postgres test teardown (${schema}):`, error))
+    while (pools.length > 0) {
+      await pools.pop()?.end().catch(() => undefined)
+    }
+  }
+
+  return { schema, boot, teardown }
+}

package/tests/resource.spec.ts

@@ -0,0 +1,121 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { RecordExists } from '@owlmeans/resource'
+import type { PostgresResource } from '@owlmeans/postgres-resource'
+import {
+  RES_MARKETING_CONSENT_LOG, RES_MARKETING_CONSENT_STATE
+} from '@owlmeans/server-marketing-consent'
+import type {
+  MarketingConsentLogRecord, MarketingConsentStateRecord
+} from '@owlmeans/server-marketing-consent'
+
+import { appendMarketingConsentPostgres } from '../src/index.js'
+import type { Booted } from './context.js'
+import { gate, makeSuite } from './context.js'
+
+/**
+ * Env-gated against a real Postgres — skips cleanly (never fails) when `POSTGRES_URL` isn't
+ * reachable, the same gate `@owlmeans/postgres-resource`'s own integration suites use.
+ */
+const suite = makeSuite('resource')
+const it = gate.skip ? test.skip : test
+
+describe('@owlmeans/marketing-consent-postgres — resources against a real context', () => {
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'postgres gate closed', () => {})
+
+    return
+  }
+
+  let booted: Booted
+  let state: PostgresResource<MarketingConsentStateRecord>
+  let log: PostgresResource<MarketingConsentLogRecord>
+
+  beforeAll(async () => {
+    booted = await suite.boot()
+    state = booted.context.resource<PostgresResource<MarketingConsentStateRecord>>(
+      RES_MARKETING_CONSENT_STATE
+    )
+    log = booted.context.resource<PostgresResource<MarketingConsentLogRecord>>(
+      RES_MARKETING_CONSENT_LOG
+    )
+  })
+
+  afterAll(async () => {
+    await suite.teardown()
+  })
+
+  it('reconciles both tables at boot without error', () => {
+    /** `beforeAll` already drove `context.init()` — reaching here at all is the assertion. */
+    expect(state.table.qualified).toBe(`"${suite.schema}"."marketing_consent_state"`)
+    expect(log.table.qualified).toBe(`"${suite.schema}"."marketing_consent_log"`)
+  })
+
+  it('stores a dotted decision key verbatim and reads it back', async () => {
+    const record = await state.create({
+      subject: 'ent-1|user-1|',
+      userId: 'user-1',
+      entityId: 'ent-1',
+      decisions: [
+        {
+          key: 'marketing.email', granted: true, revisedAt: '2026-01-01T00:00:00.000Z',
+          mode: 'opt-in', decidedAt: '2026-01-01T00:00:00.000Z', source: 'settings'
+        },
+        {
+          key: 'trackers.advertising', granted: false, revisedAt: '2026-01-01T00:00:00.000Z',
+          mode: 'opt-out', decidedAt: '2026-01-01T00:00:00.000Z', source: 'settings'
+        }
+      ],
+      createdAt: '2026-01-01T00:00:00.000Z',
+      updatedAt: '2026-01-01T00:00:00.000Z'
+    })
+
+    const loaded = await state.get(record.id as string)
+    /** Verbatim array, not folded into an object keyed by the dotted consent key. */
+    expect(loaded.decisions).toEqual([
+      {
+        key: 'marketing.email', granted: true, revisedAt: '2026-01-01T00:00:00.000Z',
+        mode: 'opt-in', decidedAt: '2026-01-01T00:00:00.000Z', source: 'settings'
+      },
+      {
+        key: 'trackers.advertising', granted: false, revisedAt: '2026-01-01T00:00:00.000Z',
+        mode: 'opt-out', decidedAt: '2026-01-01T00:00:00.000Z', source: 'settings'
+      }
+    ])
+    expect(Array.isArray(loaded.decisions)).toBe(true)
+  })
+
+  it('rejects a duplicate subject through the unique index', async () => {
+    await state.create({
+      subject: 'ent-2|user-2|', userId: 'user-2', decisions: [],
+      createdAt: '2026-01-01T00:00:00.000Z', updatedAt: '2026-01-01T00:00:00.000Z'
+    })
+
+    await expect(state.create({
+      subject: 'ent-2|user-2|', userId: 'user-2', decisions: [],
+      createdAt: '2026-01-02T00:00:00.000Z', updatedAt: '2026-01-02T00:00:00.000Z'
+    })).rejects.toThrow(RecordExists)
+  })
+
+  it('appends a log row untouched by state writes', async () => {
+    const row = await log.create({
+      subject: 'ent-3|user-3|', userId: 'user-3', kind: 'consent', key: 'marketing.email',
+      granted: true, mode: 'opt-in', decidedAt: '2026-01-01T00:00:00.000Z', source: 'settings'
+    })
+
+    expect(await log.get(row.id as string)).toMatchObject({ key: 'marketing.email', granted: true })
+  })
+
+  it('is a no-op the second time it registers on the same context', () => {
+    const before = booted.context.resource<PostgresResource<MarketingConsentStateRecord>>(
+      RES_MARKETING_CONSENT_STATE
+    )
+
+    appendMarketingConsentPostgres(booted.context)
+
+    const after = booted.context.resource<PostgresResource<MarketingConsentStateRecord>>(
+      RES_MARKETING_CONSENT_STATE
+    )
+    /** Same registered instance — the second call never re-registered a resource. */
+    expect(after).toBe(before)
+  })
+})

package/tests/schema.spec.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from 'bun:test'
+import { getDeclaration, resetDeclarations, schemaToTableSpec } from '@owlmeans/postgres-resource'
+import {
+  MarketingConsentLogSchema, MarketingConsentStateSchema,
+  RES_MARKETING_CONSENT_LOG, RES_MARKETING_CONSENT_STATE
+} from '@owlmeans/server-marketing-consent'
+
+import { makeMarketingConsentLogPostgres, makeMarketingConsentStatePostgres } from '../src/resource.js'
+
+/**
+ * No live database needed — `schemaToTableSpec` is the same compiler `init()` runs against a
+ * real connection, so this is the one test that would have caught the CRITICAL risk this
+ * package exists to avoid: `decisions`/`terms` silently expanding into per-field columns or a
+ * child table instead of staying one opaque `jsonb` blob each.
+ */
+describe('@owlmeans/marketing-consent-postgres — schema shape', () => {
+  test('the maker assigns the imported schema, not a copy', () => {
+    resetDeclarations(RES_MARKETING_CONSENT_STATE)
+    resetDeclarations(RES_MARKETING_CONSENT_LOG)
+
+    const state = makeMarketingConsentStatePostgres()
+    const log = makeMarketingConsentLogPostgres()
+
+    expect(state.schema).toBe(MarketingConsentStateSchema)
+    expect(log.schema).toBe(MarketingConsentLogSchema)
+  })
+
+  test('decisions and terms compile to one jsonb column each, never a child table', () => {
+    const spec = schemaToTableSpec(
+      RES_MARKETING_CONSENT_STATE, MarketingConsentStateSchema, 'app', 'marketing_consent_state', true
+    )
+
+    const decisions = spec.byProperty.decisions
+    const terms = spec.byProperty.terms
+
+    expect(decisions.jsonb).toBe(true)
+    expect(decisions.sqlType).toBe('jsonb')
+    /** Not a native Postgres array column — the whole array is one opaque jsonb value. */
+    expect(decisions.array).toBe(false)
+
+    expect(terms.jsonb).toBe(true)
+    expect(terms.sqlType).toBe('jsonb')
+    expect(terms.array).toBe(false)
+
+    /** Exactly the schema's own top-level properties — nothing expanded into extra columns. */
+    expect(spec.columns.map(column => column.property).sort()).toEqual([
+      'createdAt', 'decisions', 'entityId', 'gpc', 'id', 'profileId', 'subject', 'terms',
+      'updatedAt', 'userId'
+    ])
+  })
+
+  test('the log table\'s documents/notices are also single jsonb columns', () => {
+    const spec = schemaToTableSpec(
+      RES_MARKETING_CONSENT_LOG, MarketingConsentLogSchema, 'app', 'marketing_consent_log', true
+    )
+
+    expect(spec.byProperty.documents.jsonb).toBe(true)
+    expect(spec.byProperty.documents.array).toBe(false)
+    expect(spec.byProperty.notices.jsonb).toBe(true)
+    expect(spec.byProperty.notices.array).toBe(false)
+  })
+
+  test('the makers declare the indexes the API sketch promises', () => {
+    resetDeclarations(RES_MARKETING_CONSENT_STATE)
+    resetDeclarations(RES_MARKETING_CONSENT_LOG)
+    makeMarketingConsentStatePostgres()
+    makeMarketingConsentLogPostgres()
+
+    const stateIndexes = getDeclaration(RES_MARKETING_CONSENT_STATE).indexes
+    expect(stateIndexes).toContainEqual(
+      expect.objectContaining({ name: 'idx_mc_state_subject', columns: ['subject'], unique: true })
+    )
+    expect(stateIndexes).toContainEqual(
+      expect.objectContaining({ name: 'idx_mc_state_user', columns: ['userId'] })
+    )
+
+    const logIndexes = getDeclaration(RES_MARKETING_CONSENT_LOG).indexes
+    expect(logIndexes).toContainEqual(
+      expect.objectContaining({ name: 'idx_mc_log_subject_key', columns: ['subject', 'key', 'decidedAt'] })
+    )
+    expect(logIndexes).toContainEqual(
+      expect.objectContaining({ name: 'idx_mc_log_user', columns: ['userId', 'decidedAt'] })
+    )
+  })
+})

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"]
+}