@owlmeans/marketing-consent-postgres 0.1.18-rc.16 → 0.1.18-rc.18

package/README.md

@@ -1,3 +1,112 @@
+# @owlmeans/marketing-consent-postgres
+
+PostgreSQL storage for `@owlmeans/server-marketing-consent`: it registers the two resources the
+`MarketingConsentService` resolves by alias — `marketing-consent-state` and `marketing-consent-log` —
+with the shared AJV schemas and the indexes the service relies on. A Postgres-backed server
+(typically a generated target project) adds it next to `appendMarketingConsentService`. A
+Mongo-backed server uses `@owlmeans/marketing-consent-mongo` instead.
+
+## Installation
+
+```bash
+bun add @owlmeans/marketing-consent-postgres@^0.1.18-rc.18
+```
+
+Peer dependencies: `pg`, `ajv`.
+
+## Concepts
+
+- **Two resources** — `PostgresResource<MarketingConsentStateRecord>` at
+  `RES_MARKETING_CONSENT_STATE` and `PostgresResource<MarketingConsentLogRecord>` at
+  `RES_MARKETING_CONSENT_LOG`, both aliases exported by `@owlmeans/server-marketing-consent`.
+- **Shared schema** — `resource.schema` is exactly `MarketingConsentStateSchema` /
+  `MarketingConsentLogSchema`; this package declares no schema of its own.
+- **jsonb columns** — `decisions`, `terms`, `documents` and `notices` each compile to one opaque
+  `jsonb` column by `@owlmeans/postgres-resource`'s default table rule; nothing is split into child
+  tables or per-field columns.
+- **Unique subject** — one state row per `subject`, enforced by a unique index; the row `id` is
+  minted by Postgres.
+
+## Usage
+
+### Register the resources and the service
+
+```typescript
+import { appendPostgres } from '@owlmeans/postgres'
+import { appendMarketingConsentPostgres } from '@owlmeans/marketing-consent-postgres'
+import { appendMarketingConsentService } from '@owlmeans/server-marketing-consent'
+
+appendPostgres(context)                    // the Postgres connection service, cfg.dbs[...]
+appendMarketingConsentPostgres(context)    // the two resources
+appendMarketingConsentService(context)     // the service that resolves them by alias
+
+await context.configure().init()           // resource init reconciles tables and indexes (meta.autoSync, default Full)
+```
+
+`appendMarketingConsentPostgres` skips a resource whose alias is already registered, so calling it
+twice is safe.
+
+### A non-default database or connection service
+
+```typescript
+appendMarketingConsentPostgres(context, { dbAlias: 'consents', serviceAlias: 'postgres-secondary' })
+```
+
+### Use the makers directly
+
+```typescript
+import { makeMarketingConsentLogPostgres, makeMarketingConsentStatePostgres } from '@owlmeans/marketing-consent-postgres'
+
+context.registerResource(makeMarketingConsentStatePostgres('consents'))
+context.registerResource(makeMarketingConsentLogPostgres('consents'))
+```
+
+## API
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `appendMarketingConsentPostgres(ctx, opts?)` | function | Registers both resources, each only if its alias is free |
+| `makeMarketingConsentStatePostgres(dbAlias?, serviceAlias?)` | function | `PostgresResource<MarketingConsentStateRecord>` |
+| `makeMarketingConsentLogPostgres(dbAlias?, serviceAlias?)` | function | `PostgresResource<MarketingConsentLogRecord>` |
+| `MarketingConsentPostgresOptions` | type | `{ dbAlias?, serviceAlias? }` |
+
+### Indexes
+
+| Table | Index | Columns |
+|---|---|---|
+| state | `idx_mc_state_subject` (unique) | `subject` |
+| state | `idx_mc_state_user` | `userId` |
+| log | `idx_mc_log_subject_key` | `subject`, `key`, `decidedAt` |
+| log | `idx_mc_log_user` | `userId`, `decidedAt` |
+
+## Testing
+
+`tests/schema.spec.ts` needs no database: it runs `pgSchemaHelper.schemaToTableSpec` over the shared
+schemas and asserts the jsonb columns, the exact top-level column list and the declared indexes.
+`tests/resource.spec.ts` is an integration suite gated on `POSTGRES_URL` (it skips without one) that
+boots a real `ServerContext` with `PgAutoSync.Full` on a throwaway schema.
+
+## Common pitfalls
+
+- Adding a `pg:` override or a schema edit that turns `decisions` into columns or a keyed jsonb
+  object — dotted keys such as `marketing.email` would be read as jsonb paths.
+- Redeclaring the schema locally — the storage would drift from what the service reads and writes.
+- Registering the service without a storage package — the service fails on its first call when the
+  alias lookup misses.
+- Renaming the resource aliases — they come from `@owlmeans/server-marketing-consent` and must stay
+  as declared there.
+
+The `marketing-consent-postgres` skill covers this package; the `server-marketing-consent` skill
+covers the record shapes and the service.
+
+## Related packages
+
+- [`@owlmeans/server-marketing-consent`](../server-marketing-consent) — the service, record types, schemas and aliases
+- [`@owlmeans/marketing-consent-mongo`](../marketing-consent-mongo) — the MongoDB counterpart
+- [`@owlmeans/postgres-resource`](../postgres-resource) — `makePostgresResource`, `index()`, the schema-to-table compiler
+- [`@owlmeans/postgres`](../postgres) — `appendPostgres`, the connection service
+- [`@owlmeans/marketing-consent`](../marketing-consent) — the shared consent contracts
+
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
 
@@ -6,7 +115,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.51
+npx @owlmeans/agent-skills@^0.1.18-rc.54
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/marketing-consent-postgres",
-  "version": "0.1.18-rc.16",
-  "generatedAt": "2026-10-06T11:45:57.670Z",
+  "version": "0.1.18-rc.18",
+  "generatedAt": "2026-10-15T10:20:01.303Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/marketing-consent-postgres
 
 **Layer:** Infra extension
-**Install:** `"@owlmeans/marketing-consent-postgres": "^0.1.18-rc.16"` in `dependencies` (peers `pg`, `ajv`)
+**Install:** `"@owlmeans/marketing-consent-postgres": "^0.1.18-rc.18"` 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/marketing-consent-postgres",
-  "version": "0.1.18-rc.16",
+  "version": "0.1.18-rc.18",
   "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",
@@ -24,10 +24,10 @@
   },
   "dependencies": {
     "@owlmeans/context": "^0.1.18-rc.34",
-    "@owlmeans/marketing-consent": "^0.1.18-rc.10",
-    "@owlmeans/postgres-resource": "^0.1.18-rc.44",
+    "@owlmeans/marketing-consent": "^0.1.18-rc.11",
+    "@owlmeans/postgres-resource": "^0.1.18-rc.46",
     "@owlmeans/resource": "^0.1.18-rc.40",
-    "@owlmeans/server-marketing-consent": "^0.1.18-rc.16"
+    "@owlmeans/server-marketing-consent": "^0.1.18-rc.18"
   },
   "peerDependencies": {
     "ajv": "*",
@@ -35,8 +35,8 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test": "^0.1.18-rc.35",
-    "@owlmeans/test-integration": "^0.1.18-rc.33",
+    "@owlmeans/test": "^0.1.18-rc.36",
+    "@owlmeans/test-integration": "^0.1.18-rc.34",
     "@types/bun": "^1.4.2",
     "@types/pg": "^8.23.1",
     "ajv": "^8.20.0",