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

package/README.md

@@ -0,0 +1,23 @@
+# @owlmeans/marketing-consent-mongo
+
+Mongo storage for `@owlmeans/server-marketing-consent`'s two resources — `marketing-consent-state`
+and `marketing-consent-log`. Schemas are imported from `@owlmeans/server-marketing-consent`, never
+duplicated here.
+
+See `.agents/skills/marketing-consent-mongo/SKILL.md` for usage.
+
+<!-- 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-mongo",
+  "version": "0.1.18-rc.0",
+  "generatedAt": "2026-09-22T17:37:10.924Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "marketing-consent-mongo",
+      "category": "package-specific",
+      "file": "skills/marketing-consent-mongo/SKILL.md",
+      "canonicalPath": ".agents/skills/marketing-consent-mongo/SKILL.md"
+    }
+  ]
+}

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

@@ -0,0 +1,100 @@
+---
+name: marketing-consent-mongo
+description: How to use @owlmeans/marketing-consent-mongo — Mongo storage for @owlmeans/server-marketing-consent's two resources (marketing-consent-state, marketing-consent-log). Auto-invoked when registering marketing-consent resources on a Mongo-backed platform context, or touching the two Mongo indexes/schemas this package builds.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/marketing-consent-mongo
+
+**Layer:** Infra
+**Install:** `"@owlmeans/marketing-consent-mongo": "^0.1.18-rc.0"` in `dependencies` (peers `mongodb`, `ajv`)
+
+Mongo storage for `@owlmeans/server-marketing-consent`'s two resources —
+`marketing-consent-state` (`RES_MARKETING_CONSENT_STATE`) and `marketing-consent-log`
+(`RES_MARKETING_CONSENT_LOG`) — the same relationship `@owlmeans/server-auth-identity` has to
+its own Mongo resources. Use it on the platform itself (Viable runs Mongo); a generated target
+project uses the Postgres sibling, `@owlmeans/marketing-consent-postgres`, instead.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `appendMarketingConsentMongo(ctx, opts?)` | Registers both resources — a no-op per resource if it is already registered (`ctx.hasResource`), so a second call never throws or re-registers |
+| `makeMarketingConsentStateMongo(dbAlias?, serviceAlias?)` | Mongo resource for `MarketingConsentStateRecord` |
+| `makeMarketingConsentLogMongo(dbAlias?, serviceAlias?)` | Mongo resource for `MarketingConsentLogRecord` |
+
+```ts
+import { appendMarketingConsentMongo } from '@owlmeans/marketing-consent-mongo'
+import { appendMarketingConsentService } from '@owlmeans/server-marketing-consent'
+
+appendMarketingConsentMongo(context)       // register the two resources first
+appendMarketingConsentService(context)     // then the service that resolves them by alias
+```
+
+## Why the schema is imported, not duplicated
+
+Both makers assign `resource.schema` from `MarketingConsentStateSchema`/`MarketingConsentLogSchema`
+— `@owlmeans/server-marketing-consent`'s own AJV schemas — never a local redeclaration. That
+package's skill already explains why `decisions` is an ARRAY and not an object keyed by consent
+key (a dotted key like `marketing.email` is read as a PATH by Mongo dot-notation); this package
+just stores that shape, it does not reshape it.
+
+## The one adjustment: `id` is dropped from the Mongo validator's `required`
+
+`MarketingConsentStateSchema`/`MarketingConsentLogSchema` correctly list `id` in `required` — that
+is the right contract for `@owlmeans/server-marketing-consent`'s own AJV validation of a
+fully-formed record, where `id` is always present after `mongo-resource` demarshals `_id`. Handed
+to `mongo-resource` **as-is**, though, that same `required: ['id', ...]` becomes the collection's
+`$jsonSchema` validator — and a Mongo document never carries a literal `id` field, only `_id`.
+Verified against a real (embedded) MongoDB while building this package: assigning the schema
+unmodified makes every `create()` fail with `MongoServerError: Document failed validation`
+(`missingProperties: ["id"]`), because the document `mongo-resource` actually inserts has no `id`
+key for the validator to find.
+
+`resource.ts`'s private `forMongoValidator(schema)` fixes this the same way
+`@owlmeans/server-payment`'s own hand-written Mongo schemas already do it — keep `id` in
+`properties` (nullable/optional there is fine) but drop it from `required` — by shallow-cloning
+the schema and filtering `required`. `properties` stays the exact same object the shared schema
+exports; nothing about the record shape is duplicated or reinterpreted, only the Mongo-specific
+`required` list is narrowed. `tests/schema.spec.ts` asserts this precisely: `resource.schema.
+properties` is reference-equal to the shared schema's `properties`, and `required` equals the
+shared list minus `id`.
+
+This is a general gap in `@owlmeans/mongo-resource`'s schema→validator conversion (`schemaToMongoSchema`
+carries `required` through verbatim, with no special case for `id`), not something specific to
+marketing-consent — any future package that assigns a shared "full record" AJV schema straight to
+a `MongoResource.schema` will hit the same failure. This package works around it locally; it does
+not fix `mongo-resource` itself.
+
+## The two indexes
+
+- `idx_mc_state_subject` on `{ subject: 1 }`, **unique** — one current-state record per person
+  (`subject` is already `subjectKey(subject)`, so this is a collection-level backstop against a
+  create race, not the primary uniqueness mechanism).
+- `idx_mc_state_user` on `{ userId: 1 }` — lookups by account, independent of `subject`'s
+  entity-scoping.
+- `idx_mc_log_subject_key` on `{ subject: 1, key: 1, decidedAt: -1 }` — the log's one real read,
+  "the latest decision for this subject and key", served straight off the index.
+- `idx_mc_log_user` on `{ userId: 1, decidedAt: -1 }` — an account's decision history in order.
+
+## Testing
+
+`tests/schema.spec.ts` needs no live Mongo — the schema-wiring assertions above. `tests/
+resource.spec.ts` is Category C (`/testing-integration`): gated on `MONGO_URL`, self-skips
+cleanly when unreachable. It boots a real `ServerContext` through `tests/context.ts` (mirrors
+`@owlmeans/mongo`'s and `@owlmeans/server-payment`'s own harness), registers both resources via
+`appendMarketingConsentMongo`, and covers: a state record with a dotted key inside `decisions`
+round-tripping verbatim, the unique index rejecting a second state record for the same `subject`,
+a log record, and `appendMarketingConsentMongo` being a true no-op — `hasResource` true and the
+same resource instances — the second time it runs.
+
+## Related
+
+- `@owlmeans/server-marketing-consent` — the two record shapes/schemas, the service that resolves
+  these resources by alias, and why `decisions` is an array
+- `@owlmeans/mongo-resource` — the maker (`makeMongoResource`), `index()`, schema→validator
+  conversion
+- `@owlmeans/server-auth-identity` — the `appendXResources(ctx, dbAlias?)` shape this package's
+  `appendMarketingConsentMongo` copies
+- `@owlmeans/marketing-consent-postgres` — the Postgres sibling for generated target projects

package/build/helper.d.ts

@@ -0,0 +1,14 @@
+import type { BasicContext } from '@owlmeans/context';
+export interface MarketingConsentMongoOptions {
+    dbAlias?: string;
+    serviceAlias?: string;
+}
+/**
+ * Registers the two Mongo resources `@owlmeans/server-marketing-consent`'s `MarketingConsentService`
+ * resolves by alias. No-op per resource if it is already registered, the same guard
+ * `@owlmeans/server-auth-identity`'s `appendAuthIdentityResources` uses for its own services — so a
+ * second call (an app composing several `append*` helpers that all happen to touch this alias)
+ * never re-registers or throws.
+ */
+export declare const appendMarketingConsentMongo: (ctx: BasicContext<any>, opts?: MarketingConsentMongoOptions) => 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;AAIrD,MAAM,WAAW,4BAA4B;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,QACjC,YAAY,CAAC,GAAG,CAAC,SAAS,4BAA4B,KAC1D,IAOF,CAAA"}

package/build/helper.js

@@ -0,0 +1,18 @@
+import { RES_MARKETING_CONSENT_LOG, RES_MARKETING_CONSENT_STATE } from '@owlmeans/server-marketing-consent';
+import { makeMarketingConsentLogMongo, makeMarketingConsentStateMongo } from './resource.js';
+/**
+ * Registers the two Mongo resources `@owlmeans/server-marketing-consent`'s `MarketingConsentService`
+ * resolves by alias. No-op per resource if it is already registered, the same guard
+ * `@owlmeans/server-auth-identity`'s `appendAuthIdentityResources` uses for its own services — so a
+ * second call (an app composing several `append*` helpers that all happen to touch this alias)
+ * never re-registers or throws.
+ */
+export const appendMarketingConsentMongo = (ctx, opts) => {
+    if (!ctx.hasResource(RES_MARKETING_CONSENT_STATE)) {
+        ctx.registerResource(makeMarketingConsentStateMongo(opts?.dbAlias, opts?.serviceAlias));
+    }
+    if (!ctx.hasResource(RES_MARKETING_CONSENT_LOG)) {
+        ctx.registerResource(makeMarketingConsentLogMongo(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;AAC3G,OAAO,EAAE,4BAA4B,EAAE,8BAA8B,EAAE,MAAM,eAAe,CAAA;AAO5F;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CACzC,GAAsB,EAAE,IAAmC,EACrD,EAAE;IACR,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,2BAA2B,CAAC,EAAE,CAAC;QAClD,GAAG,CAAC,gBAAgB,CAAC,8BAA8B,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAA;IACzF,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,yBAAyB,CAAC,EAAE,CAAC;QAChD,GAAG,CAAC,gBAAgB,CAAC,4BAA4B,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAA;IACvF,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,15 @@
+import type { MongoResource } from '@owlmeans/mongo-resource';
+import type { MarketingConsentLogRecord, MarketingConsentStateRecord } from '@owlmeans/server-marketing-consent';
+/**
+ * One record per subject (`id` = `subjectKey(subject)`, already unique by construction), so the
+ * unique index on `subject` is the collection-level backstop against a create race producing two
+ * current-state rows for the same person.
+ */
+export declare const makeMarketingConsentStateMongo: (dbAlias?: string, serviceAlias?: string) => MongoResource<MarketingConsentStateRecord>;
+/**
+ * Append-only evidence log. The compound index serves the one read this record shape exists
+ * for — "the latest decision for this subject and key" — sorted straight off the index rather
+ * than folded from a full per-subject scan.
+ */
+export declare const makeMarketingConsentLogMongo: (dbAlias?: string, serviceAlias?: string) => MongoResource<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,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAK7D,OAAO,KAAK,EAAE,yBAAyB,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAA;AAyBhH;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,aAC/B,MAAM,iBAAiB,MAAM,KACtC,aAAa,CAAC,2BAA2B,CAQ3C,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,aAC7B,MAAM,iBAAiB,MAAM,KACtC,aAAa,CAAC,yBAAyB,CAQzC,CAAA"}

package/build/resource.js

@@ -0,0 +1,48 @@
+import { makeMongoResource } from '@owlmeans/mongo-resource';
+import { MarketingConsentLogSchema, MarketingConsentStateSchema, RES_MARKETING_CONSENT_LOG, RES_MARKETING_CONSENT_STATE } from '@owlmeans/server-marketing-consent';
+/**
+ * A stored Mongo document never carries a literal `id` field — only `_id`, which mongo-resource
+ * derives `id` FROM on every read and never writes on `create()`. The shared schema's `required`
+ * list is correct for `@owlmeans/server-marketing-consent`'s own AJV validation of a fully-formed
+ * record (post-demarshal, where `id` is always present) — but handed to `mongo-resource` verbatim
+ * as the collection's `$jsonSchema` validator, it makes EVERY `create()` fail with "Document
+ * failed validation" (`missingProperties: ["id"]`), because the document actually inserted never
+ * has that key. Verified against a real (embedded) MongoDB while building this package: assigning
+ * `MarketingConsentStateSchema` as-is reproduces the failure, dropping `id` from `required` fixes
+ * it. `properties` (and everything else) stays the exact same object `@owlmeans/
+ * server-marketing-consent` exports — nothing here is duplicated, only the Mongo-specific
+ * `required` list is narrowed, the same `id`-not-required shape `@owlmeans/server-payment`'s own
+ * hand-written Mongo schemas already use for their records.
+ */
+const forMongoValidator = (schema) => {
+    const source = schema;
+    if (source.required == null) {
+        return schema;
+    }
+    return { ...schema, required: source.required.filter(field => field !== 'id') };
+};
+/**
+ * One record per subject (`id` = `subjectKey(subject)`, already unique by construction), so the
+ * unique index on `subject` is the collection-level backstop against a create race producing two
+ * current-state rows for the same person.
+ */
+export const makeMarketingConsentStateMongo = (dbAlias, serviceAlias) => {
+    const resource = makeMongoResource(RES_MARKETING_CONSENT_STATE, dbAlias, serviceAlias);
+    resource.schema = forMongoValidator(MarketingConsentStateSchema);
+    resource.index('idx_mc_state_subject', { subject: 1 }, { unique: true });
+    resource.index('idx_mc_state_user', { userId: 1 });
+    return resource;
+};
+/**
+ * Append-only evidence log. The compound index serves the one read this record shape exists
+ * for — "the latest decision for this subject and key" — sorted straight off the index rather
+ * than folded from a full per-subject scan.
+ */
+export const makeMarketingConsentLogMongo = (dbAlias, serviceAlias) => {
+    const resource = makeMongoResource(RES_MARKETING_CONSENT_LOG, dbAlias, serviceAlias);
+    resource.schema = forMongoValidator(MarketingConsentLogSchema);
+    resource.index('idx_mc_log_subject_key', { subject: 1, key: 1, decidedAt: -1 });
+    resource.index('idx_mc_log_user', { userId: 1, decidedAt: -1 });
+    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,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAE5D,OAAO,EACL,yBAAyB,EAAE,2BAA2B,EAAE,yBAAyB,EACjF,2BAA2B,EAC5B,MAAM,oCAAoC,CAAA;AAI3C;;;;;;;;;;;;;GAaG;AACH,MAAM,iBAAiB,GAAG,CAAC,MAAiB,EAAa,EAAE;IACzD,MAAM,MAAM,GAAG,MAAiC,CAAA;IAChD,IAAI,MAAM,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAA;IACf,CAAC;IACD,OAAO,EAAE,GAAI,MAAiB,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,EAAe,CAAA;AAC1G,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAC5C,OAAgB,EAAE,YAAqB,EACK,EAAE;IAC9C,MAAM,QAAQ,GAAG,iBAAiB,CAChC,2BAA2B,EAAE,OAAO,EAAE,YAAY,CACnD,CAAA;IACD,QAAQ,CAAC,MAAM,GAAG,iBAAiB,CAAC,2BAA2B,CAAC,CAAA;IAChE,QAAQ,CAAC,KAAK,CAAC,sBAAsB,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;IACxE,QAAQ,CAAC,KAAK,CAAC,mBAAmB,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;IAClD,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAC1C,OAAgB,EAAE,YAAqB,EACG,EAAE;IAC5C,MAAM,QAAQ,GAAG,iBAAiB,CAChC,yBAAyB,EAAE,OAAO,EAAE,YAAY,CACjD,CAAA;IACD,QAAQ,CAAC,MAAM,GAAG,iBAAiB,CAAC,yBAAyB,CAAC,CAAA;IAC9D,QAAQ,CAAC,KAAK,CAAC,wBAAwB,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,CAAA;IAC/E,QAAQ,CAAC,KAAK,CAAC,iBAAiB,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,CAAA;IAC/D,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@owlmeans/marketing-consent-mongo",
+  "version": "0.1.18-rc.0",
+  "license": "MIT",
+  "description": "Mongo storage for @owlmeans/server-marketing-consent's two resources (marketing-consent-state, marketing-consent-log) — schemas imported, never duplicated. For the platform; generated target projects use @owlmeans/marketing-consent-postgres.",
+  "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/mongo-resource": "^0.1.18-rc.32",
+    "@owlmeans/resource": "^0.1.18-rc.31",
+    "@owlmeans/server-marketing-consent": "^0.1.18-rc.0"
+  },
+  "peerDependencies": {
+    "ajv": "*",
+    "mongodb": "*"
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@owlmeans/mongo": "^0.1.18-rc.31",
+    "@owlmeans/server-context": "^0.1.18-rc.32",
+    "@owlmeans/test": "^0.1.18-rc.29",
+    "@owlmeans/test-integration": "^0.1.18-rc.26",
+    "@types/bun": "^1.4.0",
+    "ajv": "^8.17.1",
+    "mongodb": "^7.5.0",
+    "nodemon": "^3.1.14",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/helper.ts

@@ -0,0 +1,26 @@
+import type { BasicContext } from '@owlmeans/context'
+import { RES_MARKETING_CONSENT_LOG, RES_MARKETING_CONSENT_STATE } from '@owlmeans/server-marketing-consent'
+import { makeMarketingConsentLogMongo, makeMarketingConsentStateMongo } from './resource.js'
+
+export interface MarketingConsentMongoOptions {
+  dbAlias?: string
+  serviceAlias?: string
+}
+
+/**
+ * Registers the two Mongo resources `@owlmeans/server-marketing-consent`'s `MarketingConsentService`
+ * resolves by alias. No-op per resource if it is already registered, the same guard
+ * `@owlmeans/server-auth-identity`'s `appendAuthIdentityResources` uses for its own services — so a
+ * second call (an app composing several `append*` helpers that all happen to touch this alias)
+ * never re-registers or throws.
+ */
+export const appendMarketingConsentMongo = (
+  ctx: BasicContext<any>, opts?: MarketingConsentMongoOptions
+): void => {
+  if (!ctx.hasResource(RES_MARKETING_CONSENT_STATE)) {
+    ctx.registerResource(makeMarketingConsentStateMongo(opts?.dbAlias, opts?.serviceAlias))
+  }
+  if (!ctx.hasResource(RES_MARKETING_CONSENT_LOG)) {
+    ctx.registerResource(makeMarketingConsentLogMongo(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,64 @@
+import { makeMongoResource } from '@owlmeans/mongo-resource'
+import type { MongoResource } from '@owlmeans/mongo-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'
+import type { AnySchema } from 'ajv'
+
+/**
+ * A stored Mongo document never carries a literal `id` field — only `_id`, which mongo-resource
+ * derives `id` FROM on every read and never writes on `create()`. The shared schema's `required`
+ * list is correct for `@owlmeans/server-marketing-consent`'s own AJV validation of a fully-formed
+ * record (post-demarshal, where `id` is always present) — but handed to `mongo-resource` verbatim
+ * as the collection's `$jsonSchema` validator, it makes EVERY `create()` fail with "Document
+ * failed validation" (`missingProperties: ["id"]`), because the document actually inserted never
+ * has that key. Verified against a real (embedded) MongoDB while building this package: assigning
+ * `MarketingConsentStateSchema` as-is reproduces the failure, dropping `id` from `required` fixes
+ * it. `properties` (and everything else) stays the exact same object `@owlmeans/
+ * server-marketing-consent` exports — nothing here is duplicated, only the Mongo-specific
+ * `required` list is narrowed, the same `id`-not-required shape `@owlmeans/server-payment`'s own
+ * hand-written Mongo schemas already use for their records.
+ */
+const forMongoValidator = (schema: AnySchema): AnySchema => {
+  const source = schema as { required?: string[] }
+  if (source.required == null) {
+    return schema
+  }
+  return { ...(schema as object), required: source.required.filter(field => field !== 'id') } as AnySchema
+}
+
+/**
+ * One record per subject (`id` = `subjectKey(subject)`, already unique by construction), so the
+ * unique index on `subject` is the collection-level backstop against a create race producing two
+ * current-state rows for the same person.
+ */
+export const makeMarketingConsentStateMongo = (
+  dbAlias?: string, serviceAlias?: string
+): MongoResource<MarketingConsentStateRecord> => {
+  const resource = makeMongoResource<MarketingConsentStateRecord>(
+    RES_MARKETING_CONSENT_STATE, dbAlias, serviceAlias
+  )
+  resource.schema = forMongoValidator(MarketingConsentStateSchema)
+  resource.index('idx_mc_state_subject', { subject: 1 }, { unique: true })
+  resource.index('idx_mc_state_user', { userId: 1 })
+  return resource
+}
+
+/**
+ * Append-only evidence log. The compound index serves the one read this record shape exists
+ * for — "the latest decision for this subject and key" — sorted straight off the index rather
+ * than folded from a full per-subject scan.
+ */
+export const makeMarketingConsentLogMongo = (
+  dbAlias?: string, serviceAlias?: string
+): MongoResource<MarketingConsentLogRecord> => {
+  const resource = makeMongoResource<MarketingConsentLogRecord>(
+    RES_MARKETING_CONSENT_LOG, dbAlias, serviceAlias
+  )
+  resource.schema = forMongoValidator(MarketingConsentLogSchema)
+  resource.index('idx_mc_log_subject_key', { subject: 1, key: 1, decidedAt: -1 })
+  resource.index('idx_mc_log_user', { userId: 1, decidedAt: -1 })
+  return resource
+}

package/tests/context.ts

@@ -0,0 +1,94 @@
+import { mongoGate, randomNamespace } from '@owlmeans/test-integration'
+import type { IntegrationGate, MongoEnv } from '@owlmeans/test-integration'
+import { appendMongo } from '@owlmeans/mongo'
+import type { MongoDbService } from '@owlmeans/mongo-resource'
+import { config, makeServerContext } from '@owlmeans/server-context'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import { MongoClient } from 'mongodb'
+import { appendMarketingConsentMongo } from '../src/helper.js'
+
+/**
+ * Category-C harness: a real `ServerContext` over a real Mongo database, with the two resources
+ * registered through `appendMarketingConsentMongo` exactly as a consuming app would — mirrors
+ * `@owlmeans/mongo`'s and `@owlmeans/server-payment`'s own `tests/context.ts`. One database per
+ * suite, dropped by that suite's own teardown.
+ */
+export const gate: IntegrationGate<MongoEnv> = mongoGate()
+
+const url = (): string => gate.env.MONGO_URL as string
+
+/** Short lived client for setup and assertions outside any context. */
+export const raw = async <R>(fn: (client: MongoClient) => Promise<R>): Promise<R> => {
+  const client = new MongoClient(url())
+  try {
+    await client.connect()
+
+    return await fn(client)
+  } finally {
+    await client.close().catch(() => undefined)
+  }
+}
+
+export interface Booted {
+  context: ServerContext<ServerConfig>
+  mongo: MongoDbService
+}
+
+export interface MongoSuite {
+  database: string
+  boot: () => Promise<Booted>
+  teardown: () => Promise<void>
+}
+
+export const makeSuite = (label: string): MongoSuite => {
+  const prefix = process.env.MONGO_TEST_DB_PREFIX ?? 'omt'
+  const database = randomNamespace(`${prefix}_${label}`)
+  const clients: MongoClient[] = []
+
+  const boot = async (): Promise<Booted> => {
+    const parsed = new URL(url())
+    const cfg: ServerConfig = config('mc-mongo-test', {
+      dbs: [{
+        service: 'mongo',
+        alias: 'mongo',
+        host: decodeURIComponent(parsed.hostname).replace(/^\[|\]$/g, ''),
+        port: parsed.port !== '' ? parseInt(parsed.port, 10) : 27017,
+        schema: database,
+        ...(parsed.username !== ''
+          ? { user: decodeURIComponent(parsed.username), secret: decodeURIComponent(parsed.password) }
+          : {})
+      }]
+    } as Partial<ServerConfig>)
+
+    const context = makeServerContext(cfg) as ServerContext<ServerConfig>
+    appendMongo(context)
+    appendMarketingConsentMongo(context)
+
+    context.configure()
+    const mongo = context.service<MongoDbService>('mongo')
+    try {
+      await context.init()
+    } finally {
+      for (const client of Object.values(mongo.clients ?? {}) as MongoClient[]) {
+        if (!clients.includes(client)) {
+          clients.push(client)
+        }
+      }
+    }
+
+    return { context, mongo }
+  }
+
+  const teardown = async (): Promise<void> => {
+    if (gate.skip) {
+      return
+    }
+    await raw(async client => { await client.db(database).dropDatabase() })
+      .catch(error => console.error(`marketing-consent-mongo test teardown (${database}):`, error))
+    while (clients.length > 0) {
+      await clients.pop()?.close().catch(() => undefined)
+    }
+  }
+
+  return { database, boot, teardown }
+}

package/tests/resource.spec.ts

@@ -0,0 +1,100 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+import type { MongoResource } from '@owlmeans/mongo-resource'
+import type { MarketingConsentLogRecord, MarketingConsentStateRecord } from '@owlmeans/server-marketing-consent'
+import { RES_MARKETING_CONSENT_LOG, RES_MARKETING_CONSENT_STATE } from '@owlmeans/server-marketing-consent'
+import { appendMarketingConsentMongo } from '../src/helper.js'
+import { gate, makeSuite } from './context.js'
+
+const suite = makeSuite('mc-resource')
+const it = gate.skip ? test.skip : test
+
+const decision = (key: string) => ({
+  key, granted: true, revisedAt: '2026-01-01T00:00:00.000Z', mode: 'opt-in' as const,
+  decidedAt: '2026-01-01T00:00:00.000Z', source: 'settings' as const,
+})
+
+describe('@owlmeans/marketing-consent-mongo — resources against a real Mongo', () => {
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'mongo gate closed', () => {})
+
+    return
+  }
+
+  afterAll(async () => {
+    await suite.teardown()
+  })
+
+  it('stores a state record with a dotted consent key and reads it back verbatim', async () => {
+    const { context } = await suite.boot()
+    const state = context.resource<MongoResource<MarketingConsentStateRecord>>(RES_MARKETING_CONSENT_STATE)
+
+    const now = new Date().toISOString()
+    const created = await state.create({
+      subject: 'subject-1',
+      userId: 'user-1',
+      // A dotted key ("marketing.email") is illegal as a Mongo FIELD name but fine as a plain
+      // STRING VALUE inside an array element — the exact reason `decisions` is an array and not
+      // an object keyed by consent key (see @owlmeans/server-marketing-consent's model.ts).
+      decisions: [decision('marketing.email'), decision('trackers.advertising')],
+      createdAt: now,
+      updatedAt: now,
+    })
+
+    expect(typeof created.id).toBe('string')
+
+    const reread = await state.get(created.id!)
+    expect(reread.subject).toBe('subject-1')
+    expect(reread.userId).toBe('user-1')
+    expect(reread.decisions).toHaveLength(2)
+    expect(reread.decisions.map(d => d.key)).toEqual(['marketing.email', 'trackers.advertising'])
+    expect(reread.decisions[0]).toMatchObject(decision('marketing.email'))
+    expect(reread.createdAt).toBe(now)
+    expect(reread.updatedAt).toBe(now)
+  })
+
+  it('rejects a second state record for the same subject', async () => {
+    const { context } = await suite.boot()
+    const state = context.resource<MongoResource<MarketingConsentStateRecord>>(RES_MARKETING_CONSENT_STATE)
+
+    const now = new Date().toISOString()
+    await state.create({
+      subject: 'subject-dup', userId: 'user-a', decisions: [], createdAt: now, updatedAt: now,
+    })
+
+    await expect(state.create({
+      subject: 'subject-dup', userId: 'user-b', decisions: [], createdAt: now, updatedAt: now,
+    })).rejects.toThrow()
+  })
+
+  it('stores an append-only log record', async () => {
+    const { context } = await suite.boot()
+    const log = context.resource<MongoResource<MarketingConsentLogRecord>>(RES_MARKETING_CONSENT_LOG)
+
+    const now = new Date().toISOString()
+    const created = await log.create({
+      subject: 'subject-log', userId: 'user-log', kind: 'consent', key: 'marketing.email',
+      granted: true, revisedAt: now, mode: 'opt-in', decidedAt: now, source: 'settings',
+    })
+
+    expect(typeof created.id).toBe('string')
+    const reread = await log.get(created.id!)
+    expect(reread.key).toBe('marketing.email')
+    expect(reread.kind).toBe('consent')
+  })
+
+  it('appendMarketingConsentMongo is a no-op the second time it runs', async () => {
+    const { context } = await suite.boot()
+
+    expect(context.hasResource(RES_MARKETING_CONSENT_STATE)).toBe(true)
+    expect(context.hasResource(RES_MARKETING_CONSENT_LOG)).toBe(true)
+
+    const state = context.resource<MongoResource<MarketingConsentStateRecord>>(RES_MARKETING_CONSENT_STATE)
+    const log = context.resource<MongoResource<MarketingConsentLogRecord>>(RES_MARKETING_CONSENT_LOG)
+
+    expect(() => appendMarketingConsentMongo(context)).not.toThrow()
+
+    // Same resource instances — nothing was re-registered.
+    expect(context.resource<MongoResource<MarketingConsentStateRecord>>(RES_MARKETING_CONSENT_STATE)).toBe(state)
+    expect(context.resource<MongoResource<MarketingConsentLogRecord>>(RES_MARKETING_CONSENT_LOG)).toBe(log)
+  })
+})

package/tests/schema.spec.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test'
+import { MarketingConsentLogSchema, MarketingConsentStateSchema } from '@owlmeans/server-marketing-consent'
+import { makeMarketingConsentLogMongo, makeMarketingConsentStateMongo } from '../src/resource.js'
+
+/**
+ * Needs no live Mongo. Proves the two makers build the collection validator FROM the shared
+ * schemas in `@owlmeans/server-marketing-consent` — `properties` is the exact same object,
+ * nothing is redeclared — while narrowing `required` to drop `id`, which a stored Mongo document
+ * never carries (see the comment on `forMongoValidator` in `../src/resource.ts` for why: handing
+ * the schema to Mongo's `$jsonSchema` validator as-is makes every `create()` fail).
+ */
+describe('@owlmeans/marketing-consent-mongo — schema wiring', () => {
+  test('the state resource shares the state schema\'s properties and drops `id` from required', () => {
+    const resource = makeMarketingConsentStateMongo()
+    const schema = resource.schema as { properties: unknown, required: string[] }
+
+    expect(schema.properties).toBe(MarketingConsentStateSchema.properties as never)
+    expect(schema.required).toEqual(
+      (MarketingConsentStateSchema.required as string[]).filter(field => field !== 'id')
+    )
+    expect(schema.required).not.toContain('id')
+  })
+
+  test('the log resource shares the log schema\'s properties and drops `id` from required', () => {
+    const resource = makeMarketingConsentLogMongo()
+    const schema = resource.schema as { properties: unknown, required: string[] }
+
+    expect(schema.properties).toBe(MarketingConsentLogSchema.properties as never)
+    expect(schema.required).toEqual(
+      (MarketingConsentLogSchema.required as string[]).filter(field => field !== 'id')
+    )
+    expect(schema.required).not.toContain('id')
+  })
+})

package/tsconfig.json

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