@wats/persistence 0.3.26 → 0.3.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -13,10 +13,11 @@ Current scope:
13
13
 
14
14
  - root persistence interfaces
15
15
  - SQLite local-development adapter target
16
+ - optional Postgres adapter subpath (`@wats/persistence/postgres`)
16
17
  - forward-only migration runner
17
18
  - redacted health diagnostics
18
19
 
19
- SQLite is intended for local and single-instance testing. Postgres, service integration, conversation APIs, CLI thread navigation, and status UI wiring are tracked as follow-up WATS issues.
20
+ SQLite is intended for local and single-instance testing. Postgres is optional: install `pg` yourself and import `createPostgresPersistence` from `@wats/persistence/postgres`. Conversation APIs, CLI thread navigation, and status UI wiring are tracked as follow-up WATS issues.
20
21
 
21
- Docs: https://github.com/Switchbord/wats
22
+ Docs: https://wats.sh/docs/reference/persistence
22
23
  License: MIT
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- export declare const CURRENT_SCHEMA_VERSION: 2;
1
+ export declare const CURRENT_SCHEMA_VERSION: 3;
2
2
  export declare const REDACTED_SQLITE_LOCATION: "[REDACTED_SQLITE_DATABASE]";
3
3
  export type PersistenceBackend = "sqlite" | "postgres";
4
4
  export type PersistenceErrorCode = "invalid_options" | "invalid_filename" | "invalid_record" | "migration_failed" | "migration_checksum_mismatch" | "migration_lock_failed" | "outbox_failed" | "store_closed";
@@ -63,6 +63,50 @@ export interface OutboxSucceededInput {
63
63
  readonly leaseId: number;
64
64
  readonly updatedAt: string;
65
65
  }
66
+ export type MessageDirection = "inbound" | "outbound";
67
+ export interface MessageRecordInput {
68
+ readonly rowId: string;
69
+ readonly waMessageId: string;
70
+ readonly direction: MessageDirection;
71
+ readonly fromPhone?: string;
72
+ readonly toPhone?: string;
73
+ readonly type: string;
74
+ readonly status: string;
75
+ readonly graphMessageId?: string;
76
+ readonly createdAt: string;
77
+ readonly updatedAt: string;
78
+ }
79
+ export interface MessageRecord {
80
+ readonly rowId: string;
81
+ readonly waMessageId: string;
82
+ readonly direction: MessageDirection;
83
+ readonly fromPhone: string | null;
84
+ readonly toPhone: string | null;
85
+ readonly type: string;
86
+ readonly status: string;
87
+ readonly graphMessageId: string | null;
88
+ readonly createdAt: string;
89
+ readonly updatedAt: string;
90
+ }
91
+ export interface MessageStatusEventInput {
92
+ readonly waMessageId: string;
93
+ readonly status: string;
94
+ readonly timestamp: string;
95
+ }
96
+ export interface MessageStatusEventRecord {
97
+ readonly id: number;
98
+ readonly waMessageId: string;
99
+ readonly status: string;
100
+ readonly timestamp: string;
101
+ }
102
+ export interface ListMessagesInput {
103
+ readonly limit: number;
104
+ readonly beforeRowId?: string;
105
+ }
106
+ export interface ListMessagesResult {
107
+ readonly items: readonly MessageRecord[];
108
+ readonly nextCursor: string | null;
109
+ }
66
110
  export interface PersistenceStore {
67
111
  readonly backend: PersistenceBackend;
68
112
  migrate(): Promise<MigrationReport>;
@@ -74,6 +118,12 @@ export interface PersistenceStore {
74
118
  claimOutboxItems(input: OutboxClaimInput): Promise<readonly OutboxItem[]>;
75
119
  markOutboxItemFailed(input: OutboxFailedInput): Promise<void>;
76
120
  markOutboxItemSucceeded(input: OutboxSucceededInput): Promise<void>;
121
+ recordMessage(input: MessageRecordInput): Promise<void>;
122
+ appendMessageStatus(input: MessageStatusEventInput): Promise<void>;
123
+ getMessage(input: {
124
+ waMessageId: string;
125
+ }): Promise<MessageRecord | null>;
126
+ listMessages(input: ListMessagesInput): Promise<ListMessagesResult>;
77
127
  close(): Promise<void>;
78
128
  }
79
129
  export declare class PersistenceError extends Error {
package/dist/index.js CHANGED
@@ -1,4 +1,4 @@
1
- export const CURRENT_SCHEMA_VERSION = 2;
1
+ export const CURRENT_SCHEMA_VERSION = 3;
2
2
  export const REDACTED_SQLITE_LOCATION = "[REDACTED_SQLITE_DATABASE]";
3
3
 
4
4
  export class PersistenceError extends Error {
@@ -0,0 +1,15 @@
1
+ import { type PersistenceStore } from "./index";
2
+ export declare const REDACTED_POSTGRES_LOCATION: "[REDACTED_POSTGRES_DATABASE]";
3
+ export interface PostgresPersistenceOptions {
4
+ readonly connectionString: string;
5
+ }
6
+ export interface PostgresQueryResult<Row extends Record<string, unknown> = Record<string, unknown>> {
7
+ readonly rows: readonly Row[];
8
+ readonly rowCount: number | null;
9
+ }
10
+ export interface PostgresClientLike {
11
+ query<Row extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<PostgresQueryResult<Row>>;
12
+ end(): Promise<void>;
13
+ }
14
+ export declare function createPostgresPersistence(options: PostgresPersistenceOptions): Promise<PersistenceStore>;
15
+ export declare function createPostgresPersistenceWithClient(client: PostgresClientLike): PersistenceStore;
@@ -0,0 +1,516 @@
1
+ class PostgresPersistenceStore {
2
+ backend = "postgres";
3
+ #client;
4
+ #closed = false;
5
+ constructor(client) {
6
+ this.#client = client;
7
+ }
8
+ async migrate() {
9
+ this.#assertOpen();
10
+ await this.#client.query(`CREATE TABLE IF NOT EXISTS wats_persistence_lock (
11
+ id INTEGER PRIMARY KEY CHECK (id = 1),
12
+ holder TEXT NOT NULL,
13
+ acquired_at TEXT NOT NULL
14
+ )`);
15
+ await this.#client.query(`CREATE TABLE IF NOT EXISTS wats_schema_migrations (
16
+ id TEXT PRIMARY KEY,
17
+ version INTEGER NOT NULL,
18
+ checksum TEXT NOT NULL,
19
+ applied_at TEXT NOT NULL
20
+ )`);
21
+ const holder = `wats-${Math.random().toString(36).slice(2)}`;
22
+ try {
23
+ const lock = await this.#client.query("INSERT INTO wats_persistence_lock (id, holder, acquired_at) VALUES (1, $1, $2) ON CONFLICT (id) DO NOTHING", [holder, nowIso()]);
24
+ if (lock.rowCount !== 1)
25
+ throw new PersistenceError("migration_lock_failed", "Postgres migration lock is already held.");
26
+ await this.#validateAppliedChecksums();
27
+ const applied = [];
28
+ for (const migration of POSTGRES_MIGRATIONS) {
29
+ const existing = await this.#client.query("SELECT id FROM wats_schema_migrations WHERE id = $1", [migration.id]);
30
+ if (existing.rows.length > 0 || (existing.rowCount ?? 0) > 0)
31
+ continue;
32
+ await this.#client.query("BEGIN");
33
+ try {
34
+ for (const statement of migration.statements)
35
+ await this.#client.query(statement);
36
+ await this.#client.query("INSERT INTO wats_schema_migrations (id, version, checksum, applied_at) VALUES ($1, $2, $3, $4)", [migration.id, migration.version, migration.checksum, nowIso()]);
37
+ await this.#client.query("COMMIT");
38
+ applied.push(migration.id);
39
+ } catch (cause) {
40
+ await this.#client.query("ROLLBACK");
41
+ throw new PersistenceError("migration_failed", "Postgres migration failed.", { cause });
42
+ }
43
+ }
44
+ return Object.freeze({ currentVersion: CURRENT_SCHEMA_VERSION, appliedMigrations: Object.freeze(applied), alreadyCurrent: applied.length === 0 });
45
+ } finally {
46
+ await this.#releaseLock(holder);
47
+ }
48
+ }
49
+ async health() {
50
+ this.#assertOpen();
51
+ const result = await this.#client.query("SELECT COALESCE(MAX(version), 0) AS version FROM wats_schema_migrations");
52
+ const version = result.rows[0]?.version;
53
+ return Object.freeze({ ok: true, backend: "postgres", currentVersion: version === undefined ? 0 : numeric(version), redactedLocation: REDACTED_POSTGRES_LOCATION });
54
+ }
55
+ async recordWebhookEvent(input) {
56
+ this.#assertOpen();
57
+ const record = validateWebhookEventRecord(input);
58
+ const result = await this.#client.query("INSERT INTO wats_webhook_events (event_key, event_hash, received_at) VALUES ($1, $2, $3) ON CONFLICT (event_key) DO NOTHING", [record.eventKey, record.eventHash, record.receivedAt]);
59
+ return result.rowCount === 1 ? "recorded" : "duplicate";
60
+ }
61
+ async getServiceRequest(input) {
62
+ this.#assertOpen();
63
+ const lookup = validateServiceRequestLookup(input);
64
+ const result = await this.#client.query("SELECT request_hash, response_json FROM wats_service_requests WHERE idempotency_key = $1", [lookup.idempotencyKey]);
65
+ const row = result.rows[0];
66
+ if (row === undefined)
67
+ return null;
68
+ if (row.request_hash !== lookup.requestHash)
69
+ return "conflict";
70
+ return Object.freeze({ responseJson: row.response_json });
71
+ }
72
+ async recordServiceRequest(input) {
73
+ this.#assertOpen();
74
+ const record = validateServiceRequestRecord(input);
75
+ await this.#client.query("INSERT INTO wats_service_requests (idempotency_key, request_hash, response_json, created_at) VALUES ($1, $2, $3, $4) ON CONFLICT (idempotency_key) DO NOTHING", [record.idempotencyKey, record.requestHash, record.responseJson, record.createdAt]);
76
+ }
77
+ async enqueueOutboxItem(input) {
78
+ this.#assertOpen();
79
+ const item = validateOutboxEnqueue(input);
80
+ const result = await this.#client.query("INSERT INTO wats_outbox (id, status, attempts, next_attempt_at, payload_hash, created_at, updated_at) VALUES ($1, 'pending', 0, $2, $3, $4, $5) ON CONFLICT (id) DO NOTHING", [item.id, item.nextAttemptAt, item.payloadHash, item.createdAt, item.createdAt]);
81
+ return result.rowCount === 1 ? "enqueued" : "duplicate";
82
+ }
83
+ async claimOutboxItems(input) {
84
+ this.#assertOpen();
85
+ const claim = validateOutboxClaim(input);
86
+ const leaseExpiredAt = subtractMillisecondsIso(claim.now, OUTBOX_PROCESSING_LEASE_MS);
87
+ await this.#client.query("BEGIN");
88
+ try {
89
+ const result = await this.#client.query(`SELECT id, status, attempts, lease_id, next_attempt_at, payload_hash, created_at, updated_at
90
+ FROM wats_outbox
91
+ WHERE (status = 'pending' AND (next_attempt_at IS NULL OR next_attempt_at <= $1))
92
+ OR (status = 'processing' AND updated_at <= $2)
93
+ ORDER BY created_at ASC, id ASC
94
+ LIMIT $3
95
+ FOR UPDATE SKIP LOCKED`, [claim.now, leaseExpiredAt, claim.limit]);
96
+ const rows = result.rows;
97
+ for (const row of rows) {
98
+ const update = await this.#client.query("UPDATE wats_outbox SET status = 'processing', attempts = attempts + 1, lease_id = lease_id + 1, next_attempt_at = NULL, updated_at = $1 WHERE id = $2 AND status = $3 AND lease_id = $4", [claim.now, row.id, row.status, numeric(row.lease_id)]);
99
+ if (update.rowCount !== 1)
100
+ throw new PersistenceError("outbox_failed", "Postgres outbox claim lease changed during claim.");
101
+ }
102
+ await this.#client.query("COMMIT");
103
+ return Object.freeze(rows.map((row) => outboxRowToItem({ ...row, status: "processing", attempts: numeric(row.attempts) + 1, lease_id: numeric(row.lease_id) + 1, next_attempt_at: null, updated_at: claim.now })));
104
+ } catch (cause) {
105
+ await this.#client.query("ROLLBACK");
106
+ if (cause instanceof PersistenceError)
107
+ throw cause;
108
+ throw new PersistenceError("outbox_failed", "Postgres outbox claim failed.", { cause });
109
+ }
110
+ }
111
+ async markOutboxItemFailed(input) {
112
+ this.#assertOpen();
113
+ const failure = validateOutboxFailed(input);
114
+ const result = await this.#client.query("UPDATE wats_outbox SET status = 'pending', next_attempt_at = $1, updated_at = $2 WHERE id = $3 AND status = 'processing' AND lease_id = $4", [failure.nextAttemptAt, failure.updatedAt, failure.id, failure.leaseId]);
115
+ if (result.rowCount !== 1)
116
+ throw new PersistenceError("outbox_failed", "Postgres outbox failure lease is stale.");
117
+ }
118
+ async markOutboxItemSucceeded(input) {
119
+ this.#assertOpen();
120
+ const success = validateOutboxSucceeded(input);
121
+ const result = await this.#client.query("UPDATE wats_outbox SET status = 'succeeded', next_attempt_at = NULL, updated_at = $1 WHERE id = $2 AND status = 'processing' AND lease_id = $3", [success.updatedAt, success.id, success.leaseId]);
122
+ if (result.rowCount !== 1)
123
+ throw new PersistenceError("outbox_failed", "Postgres outbox success lease is stale.");
124
+ }
125
+ async recordMessage(input) {
126
+ this.#assertOpen();
127
+ const record = validateMessageRecord(input);
128
+ await this.#client.query(`INSERT INTO wats_messages
129
+ (row_id, wa_message_id, direction, from_phone, to_phone, type, status, graph_message_id, created_at, updated_at)
130
+ VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
131
+ ON CONFLICT (row_id) DO NOTHING`, [record.rowId, record.waMessageId, record.direction, record.fromPhone, record.toPhone, record.type, record.status, record.graphMessageId, record.createdAt, record.updatedAt]);
132
+ }
133
+ async appendMessageStatus(input) {
134
+ this.#assertOpen();
135
+ const event = validateMessageStatusEvent(input);
136
+ await this.#client.query("BEGIN");
137
+ try {
138
+ await this.#client.query("INSERT INTO wats_message_status_events (wa_message_id, status, timestamp) VALUES ($1, $2, $3)", [event.waMessageId, event.status, event.timestamp]);
139
+ await this.#client.query("UPDATE wats_messages SET status = $1, updated_at = $2 WHERE wa_message_id = $3", [event.status, event.timestamp, event.waMessageId]);
140
+ await this.#client.query("COMMIT");
141
+ } catch (cause) {
142
+ await this.#client.query("ROLLBACK");
143
+ throw new PersistenceError("invalid_record", "Postgres message status append failed.", { cause });
144
+ }
145
+ }
146
+ async getMessage(input) {
147
+ this.#assertOpen();
148
+ const record = validateRecordInput(input, "message lookup");
149
+ const waMessageId = validateRecordString(record.waMessageId, "waMessageId");
150
+ const result = await this.#client.query(`SELECT row_id, wa_message_id, direction, from_phone, to_phone, type, status, graph_message_id, created_at, updated_at
151
+ FROM wats_messages WHERE wa_message_id = $1`, [waMessageId]);
152
+ const row = result.rows[0];
153
+ return row === undefined ? null : messageRowToRecord(row);
154
+ }
155
+ async listMessages(input) {
156
+ this.#assertOpen();
157
+ const query = validateListMessages(input);
158
+ const fetchLimit = query.limit + 1;
159
+ let rows;
160
+ if (query.beforeRowId === null) {
161
+ rows = (await this.#client.query(`SELECT row_id, wa_message_id, direction, from_phone, to_phone, type, status, graph_message_id, created_at, updated_at
162
+ FROM wats_messages
163
+ ORDER BY created_at DESC, row_id DESC
164
+ LIMIT $1`, [fetchLimit])).rows;
165
+ } else {
166
+ const cursor = await this.#client.query("SELECT row_id, created_at FROM wats_messages WHERE row_id = $1", [query.beforeRowId]);
167
+ const cursorRow = cursor.rows[0];
168
+ if (cursorRow === undefined)
169
+ return Object.freeze({ items: Object.freeze([]), nextCursor: null });
170
+ rows = (await this.#client.query(`SELECT row_id, wa_message_id, direction, from_phone, to_phone, type, status, graph_message_id, created_at, updated_at
171
+ FROM wats_messages
172
+ WHERE created_at < $1 OR (created_at = $2 AND row_id < $3)
173
+ ORDER BY created_at DESC, row_id DESC
174
+ LIMIT $4`, [cursorRow.created_at, cursorRow.created_at, cursorRow.row_id, fetchLimit])).rows;
175
+ }
176
+ const pageRows = rows.slice(0, query.limit);
177
+ const items = Object.freeze(pageRows.map((row) => messageRowToRecord(row)));
178
+ const nextCursor = rows.length > query.limit ? items[items.length - 1]?.rowId ?? null : null;
179
+ return Object.freeze({ items, nextCursor });
180
+ }
181
+ async close() {
182
+ if (this.#closed)
183
+ return;
184
+ this.#closed = true;
185
+ await this.#client.end();
186
+ }
187
+ async#releaseLock(holder) {
188
+ try {
189
+ await this.#client.query("DELETE FROM wats_persistence_lock WHERE id = 1 AND holder = $1", [holder]);
190
+ } catch {}
191
+ }
192
+ async#validateAppliedChecksums() {
193
+ const result = await this.#client.query("SELECT id, version, checksum FROM wats_schema_migrations ORDER BY version ASC");
194
+ for (const row of result.rows) {
195
+ const expected = migrationById(row.id);
196
+ if (expected === undefined || expected.version !== numeric(row.version) || expected.checksum !== row.checksum) {
197
+ throw new PersistenceError("migration_checksum_mismatch", "Postgres migration checksum mismatch.");
198
+ }
199
+ }
200
+ }
201
+ #assertOpen() {
202
+ if (this.#closed)
203
+ throw new PersistenceError("store_closed", "Persistence store is closed.");
204
+ }
205
+ }
206
+ import {
207
+ CURRENT_SCHEMA_VERSION,
208
+ PersistenceError
209
+ } from "./index";
210
+ export const REDACTED_POSTGRES_LOCATION = "[REDACTED_POSTGRES_DATABASE]";
211
+ const OUTBOX_PROCESSING_LEASE_MS = 300000;
212
+ const MAX_CONNECTION_STRING_LENGTH = 4096;
213
+ const POSTGRES_MIGRATIONS = Object.freeze([
214
+ {
215
+ id: "001_initial",
216
+ version: 1,
217
+ checksum: "sha256:wats-persistence-001-initial-v1",
218
+ statements: Object.freeze([
219
+ `CREATE TABLE IF NOT EXISTS wats_schema_migrations (
220
+ id TEXT PRIMARY KEY,
221
+ version INTEGER NOT NULL,
222
+ checksum TEXT NOT NULL,
223
+ applied_at TEXT NOT NULL
224
+ )`,
225
+ `CREATE TABLE IF NOT EXISTS wats_persistence_lock (
226
+ id INTEGER PRIMARY KEY CHECK (id = 1),
227
+ holder TEXT NOT NULL,
228
+ acquired_at TEXT NOT NULL
229
+ )`,
230
+ `CREATE TABLE IF NOT EXISTS wats_webhook_events (
231
+ event_key TEXT PRIMARY KEY,
232
+ event_hash TEXT NOT NULL,
233
+ received_at TEXT NOT NULL
234
+ )`,
235
+ `CREATE TABLE IF NOT EXISTS wats_service_requests (
236
+ idempotency_key TEXT PRIMARY KEY,
237
+ request_hash TEXT NOT NULL,
238
+ response_json TEXT NOT NULL,
239
+ created_at TEXT NOT NULL
240
+ )`,
241
+ `CREATE TABLE IF NOT EXISTS wats_outbox (
242
+ id TEXT PRIMARY KEY,
243
+ status TEXT NOT NULL,
244
+ attempts INTEGER NOT NULL,
245
+ next_attempt_at TEXT,
246
+ payload_hash TEXT NOT NULL,
247
+ created_at TEXT NOT NULL,
248
+ updated_at TEXT NOT NULL
249
+ )`
250
+ ])
251
+ },
252
+ {
253
+ id: "002_outbox_lease_id",
254
+ version: 2,
255
+ checksum: "sha256:wats-persistence-002-outbox-lease-id-v1",
256
+ statements: Object.freeze([
257
+ "ALTER TABLE wats_outbox ADD COLUMN lease_id INTEGER NOT NULL DEFAULT 0"
258
+ ])
259
+ },
260
+ {
261
+ id: "003_message_projection",
262
+ version: 3,
263
+ checksum: "sha256:wats-persistence-003-message-projection-v1",
264
+ statements: Object.freeze([
265
+ `CREATE TABLE IF NOT EXISTS wats_messages (
266
+ row_id TEXT PRIMARY KEY,
267
+ wa_message_id TEXT NOT NULL,
268
+ direction TEXT NOT NULL,
269
+ from_phone TEXT,
270
+ to_phone TEXT,
271
+ type TEXT NOT NULL,
272
+ status TEXT NOT NULL,
273
+ graph_message_id TEXT,
274
+ created_at TEXT NOT NULL,
275
+ updated_at TEXT NOT NULL
276
+ )`,
277
+ `CREATE INDEX IF NOT EXISTS wats_messages_wa_message_id_idx ON wats_messages (wa_message_id)`,
278
+ `CREATE INDEX IF NOT EXISTS wats_messages_created_at_idx ON wats_messages (created_at DESC, row_id DESC)`,
279
+ `CREATE TABLE IF NOT EXISTS wats_message_status_events (
280
+ id BIGSERIAL PRIMARY KEY,
281
+ wa_message_id TEXT NOT NULL,
282
+ status TEXT NOT NULL,
283
+ timestamp TEXT NOT NULL
284
+ )`,
285
+ `CREATE INDEX IF NOT EXISTS wats_message_status_events_wa_message_id_idx ON wats_message_status_events (wa_message_id, id)`
286
+ ])
287
+ }
288
+ ]);
289
+ function hasControlChars(value) {
290
+ return Array.from(value).some((char) => {
291
+ const code = char.codePointAt(0) ?? 0;
292
+ return code < 32 || code === 127;
293
+ });
294
+ }
295
+ function isRecord(value) {
296
+ if (typeof value !== "object" || value === null || Array.isArray(value))
297
+ return false;
298
+ const proto = Object.getPrototypeOf(value);
299
+ return proto === null || proto === Object.prototype;
300
+ }
301
+ function validateConnectionString(value) {
302
+ if (typeof value !== "string") {
303
+ throw new PersistenceError("invalid_options", "Postgres connectionString must be a postgres:// or postgresql:// URL.");
304
+ }
305
+ const trimmed = value.trim();
306
+ if (trimmed.length === 0 || trimmed.length > MAX_CONNECTION_STRING_LENGTH || hasControlChars(value)) {
307
+ throw new PersistenceError("invalid_options", "Postgres connectionString must be a postgres:// or postgresql:// URL.");
308
+ }
309
+ if (!trimmed.startsWith("postgres://") && !trimmed.startsWith("postgresql://")) {
310
+ throw new PersistenceError("invalid_options", "Postgres connectionString must be a postgres:// or postgresql:// URL.");
311
+ }
312
+ return trimmed;
313
+ }
314
+ function validateRecordInput(value, label) {
315
+ if (!isRecord(value))
316
+ throw new PersistenceError("invalid_record", `${label} must be an object.`);
317
+ return value;
318
+ }
319
+ function validateRecordString(value, label) {
320
+ if (typeof value !== "string" || value.trim().length === 0 || value.length > 1024 || hasControlChars(value)) {
321
+ throw new PersistenceError("invalid_record", `${label} must be a safe non-empty string.`);
322
+ }
323
+ return value;
324
+ }
325
+ function validateTimestamp(value, label) {
326
+ const raw = validateRecordString(value, label);
327
+ if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(raw)) {
328
+ throw new PersistenceError("invalid_record", `${label} must be an ISO timestamp.`);
329
+ }
330
+ if (new Date(raw).toISOString() !== raw) {
331
+ throw new PersistenceError("invalid_record", `${label} must be an ISO timestamp.`);
332
+ }
333
+ return raw;
334
+ }
335
+ function validateOptionalRecordString(value, label) {
336
+ if (value === undefined || value === null)
337
+ return null;
338
+ return validateRecordString(value, label);
339
+ }
340
+ function validatePayloadHash(value) {
341
+ const raw = validateRecordString(value, "payloadHash");
342
+ if (!/^sha256:[a-f0-9]{64}$/u.test(raw)) {
343
+ throw new PersistenceError("invalid_record", "payloadHash must be a sha256 hex digest.");
344
+ }
345
+ return raw;
346
+ }
347
+ function validateWebhookEventRecord(input) {
348
+ const record = validateRecordInput(input, "webhook event record");
349
+ return Object.freeze({
350
+ eventKey: validateRecordString(record.eventKey, "eventKey"),
351
+ eventHash: validateRecordString(record.eventHash, "eventHash"),
352
+ receivedAt: validateTimestamp(record.receivedAt, "receivedAt")
353
+ });
354
+ }
355
+ function validateServiceRequestLookup(input) {
356
+ const record = validateRecordInput(input, "service request lookup");
357
+ return Object.freeze({
358
+ idempotencyKey: validateRecordString(record.idempotencyKey, "idempotencyKey"),
359
+ requestHash: validateRecordString(record.requestHash, "requestHash")
360
+ });
361
+ }
362
+ function validateServiceRequestRecord(input) {
363
+ const record = validateRecordInput(input, "service request record");
364
+ const responseJson = validateRecordString(record.responseJson, "responseJson");
365
+ try {
366
+ JSON.parse(responseJson);
367
+ } catch (cause) {
368
+ throw new PersistenceError("invalid_record", "responseJson must be valid JSON.", { cause });
369
+ }
370
+ return Object.freeze({
371
+ idempotencyKey: validateRecordString(record.idempotencyKey, "idempotencyKey"),
372
+ requestHash: validateRecordString(record.requestHash, "requestHash"),
373
+ responseJson,
374
+ createdAt: validateTimestamp(record.createdAt, "createdAt")
375
+ });
376
+ }
377
+ function validateOutboxEnqueue(input) {
378
+ const record = validateRecordInput(input, "outbox item");
379
+ const createdAt = validateTimestamp(record.createdAt, "createdAt");
380
+ const nextAttemptAt = record.nextAttemptAt === undefined || record.nextAttemptAt === null ? createdAt : validateTimestamp(record.nextAttemptAt, "nextAttemptAt");
381
+ return Object.freeze({
382
+ id: validateRecordString(record.id, "id"),
383
+ payloadHash: validatePayloadHash(record.payloadHash),
384
+ createdAt,
385
+ nextAttemptAt
386
+ });
387
+ }
388
+ function validateOutboxClaim(input) {
389
+ const record = validateRecordInput(input, "outbox claim");
390
+ if (typeof record.limit !== "number" || !Number.isInteger(record.limit) || record.limit < 1 || record.limit > 100) {
391
+ throw new PersistenceError("invalid_record", "limit must be an integer from 1 to 100.");
392
+ }
393
+ return Object.freeze({ now: validateTimestamp(record.now, "now"), limit: record.limit });
394
+ }
395
+ function validateLeaseId(value) {
396
+ if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > Number.MAX_SAFE_INTEGER) {
397
+ throw new PersistenceError("invalid_record", "leaseId must be a positive safe integer.");
398
+ }
399
+ return value;
400
+ }
401
+ function validateOutboxFailed(input) {
402
+ const record = validateRecordInput(input, "outbox failure");
403
+ return Object.freeze({
404
+ id: validateRecordString(record.id, "id"),
405
+ leaseId: validateLeaseId(record.leaseId),
406
+ nextAttemptAt: validateTimestamp(record.nextAttemptAt, "nextAttemptAt"),
407
+ updatedAt: validateTimestamp(record.updatedAt, "updatedAt")
408
+ });
409
+ }
410
+ function validateOutboxSucceeded(input) {
411
+ const record = validateRecordInput(input, "outbox success");
412
+ return Object.freeze({
413
+ id: validateRecordString(record.id, "id"),
414
+ leaseId: validateLeaseId(record.leaseId),
415
+ updatedAt: validateTimestamp(record.updatedAt, "updatedAt")
416
+ });
417
+ }
418
+ function validateMessageDirection(value) {
419
+ if (value !== "inbound" && value !== "outbound") {
420
+ throw new PersistenceError("invalid_record", 'direction must be "inbound" or "outbound".');
421
+ }
422
+ return value;
423
+ }
424
+ function validateMessageRecord(input) {
425
+ const record = validateRecordInput(input, "message record");
426
+ return Object.freeze({
427
+ rowId: validateRecordString(record.rowId, "rowId"),
428
+ waMessageId: validateRecordString(record.waMessageId, "waMessageId"),
429
+ direction: validateMessageDirection(record.direction),
430
+ fromPhone: validateOptionalRecordString(record.fromPhone, "fromPhone"),
431
+ toPhone: validateOptionalRecordString(record.toPhone, "toPhone"),
432
+ type: validateRecordString(record.type, "type"),
433
+ status: validateRecordString(record.status, "status"),
434
+ graphMessageId: validateOptionalRecordString(record.graphMessageId, "graphMessageId"),
435
+ createdAt: validateTimestamp(record.createdAt, "createdAt"),
436
+ updatedAt: validateTimestamp(record.updatedAt, "updatedAt")
437
+ });
438
+ }
439
+ function validateMessageStatusEvent(input) {
440
+ const record = validateRecordInput(input, "message status event");
441
+ return Object.freeze({
442
+ waMessageId: validateRecordString(record.waMessageId, "waMessageId"),
443
+ status: validateRecordString(record.status, "status"),
444
+ timestamp: validateTimestamp(record.timestamp, "timestamp")
445
+ });
446
+ }
447
+ function validateListMessages(input) {
448
+ const record = validateRecordInput(input, "message list");
449
+ if (typeof record.limit !== "number" || !Number.isInteger(record.limit) || record.limit < 1 || record.limit > 100) {
450
+ throw new PersistenceError("invalid_record", "limit must be an integer from 1 to 100.");
451
+ }
452
+ return Object.freeze({
453
+ limit: record.limit,
454
+ beforeRowId: validateOptionalRecordString(record.beforeRowId, "beforeRowId")
455
+ });
456
+ }
457
+ function nowIso() {
458
+ return new Date().toISOString();
459
+ }
460
+ function subtractMillisecondsIso(timestamp, milliseconds) {
461
+ return new Date(new Date(timestamp).getTime() - milliseconds).toISOString();
462
+ }
463
+ function migrationById(id) {
464
+ return POSTGRES_MIGRATIONS.find((migration) => migration.id === id);
465
+ }
466
+ function numeric(value) {
467
+ return typeof value === "number" ? value : Number.parseInt(value, 10);
468
+ }
469
+ function outboxRowToItem(row) {
470
+ return Object.freeze({
471
+ id: row.id,
472
+ status: row.status,
473
+ attempts: numeric(row.attempts),
474
+ leaseId: numeric(row.lease_id),
475
+ payloadHash: row.payload_hash,
476
+ nextAttemptAt: row.next_attempt_at,
477
+ createdAt: row.created_at,
478
+ updatedAt: row.updated_at
479
+ });
480
+ }
481
+ function messageRowToRecord(row) {
482
+ return Object.freeze({
483
+ rowId: row.row_id,
484
+ waMessageId: row.wa_message_id,
485
+ direction: row.direction,
486
+ fromPhone: row.from_phone,
487
+ toPhone: row.to_phone,
488
+ type: row.type,
489
+ status: row.status,
490
+ graphMessageId: row.graph_message_id,
491
+ createdAt: row.created_at,
492
+ updatedAt: row.updated_at
493
+ });
494
+ }
495
+ export async function createPostgresPersistence(options) {
496
+ const connectionString = validateConnectionString(options?.connectionString);
497
+ const specifier = "pg";
498
+ let Client;
499
+ try {
500
+ const mod = await import("pg");
501
+ const defaultExport = mod.default;
502
+ Client = mod.Client ?? (typeof defaultExport === "function" ? defaultExport : defaultExport?.Client);
503
+ } catch (cause) {
504
+ throw new PersistenceError("invalid_options", "Postgres persistence requires the optional 'pg' package.", { cause });
505
+ }
506
+ if (Client === undefined) {
507
+ throw new PersistenceError("invalid_options", "Postgres persistence requires the optional 'pg' package.");
508
+ }
509
+ return createPostgresPersistenceWithClient(new Client({ connectionString }));
510
+ }
511
+ export function createPostgresPersistenceWithClient(client) {
512
+ if (client === null || typeof client !== "object" || typeof client.query !== "function" || typeof client.end !== "function") {
513
+ throw new PersistenceError("invalid_options", "Postgres client must expose query and end functions.");
514
+ }
515
+ return new PostgresPersistenceStore(client);
516
+ }
package/dist/sqlite.js CHANGED
@@ -143,6 +143,60 @@ class SqlitePersistenceStore {
143
143
  throw new PersistenceError("outbox_failed", "SQLite outbox success lease is stale.");
144
144
  }
145
145
  }
146
+ async recordMessage(input) {
147
+ this.#assertOpen();
148
+ const record = validateMessageRecord(input);
149
+ this.#database.run(`INSERT OR IGNORE INTO wats_messages
150
+ (row_id, wa_message_id, direction, from_phone, to_phone, type, status, graph_message_id, created_at, updated_at)
151
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, record.rowId, record.waMessageId, record.direction, record.fromPhone, record.toPhone, record.type, record.status, record.graphMessageId, record.createdAt, record.updatedAt);
152
+ }
153
+ async appendMessageStatus(input) {
154
+ this.#assertOpen();
155
+ const event = validateMessageStatusEvent(input);
156
+ this.#database.exec("BEGIN IMMEDIATE");
157
+ try {
158
+ this.#database.run("INSERT INTO wats_message_status_events (wa_message_id, status, timestamp) VALUES (?, ?, ?)", event.waMessageId, event.status, event.timestamp);
159
+ this.#database.run("UPDATE wats_messages SET status = ?, updated_at = ? WHERE wa_message_id = ?", event.status, event.timestamp, event.waMessageId);
160
+ this.#database.exec("COMMIT");
161
+ } catch (cause) {
162
+ this.#database.exec("ROLLBACK");
163
+ throw new PersistenceError("invalid_record", "SQLite message status append failed.", { cause });
164
+ }
165
+ }
166
+ async getMessage(input) {
167
+ this.#assertOpen();
168
+ const record = validateRecordInput(input, "message lookup");
169
+ const waMessageId = validateRecordString(record.waMessageId, "waMessageId");
170
+ const row = this.#database.query(`SELECT row_id, wa_message_id, direction, from_phone, to_phone, type, status, graph_message_id, created_at, updated_at
171
+ FROM wats_messages WHERE wa_message_id = ?`).get(waMessageId);
172
+ return row === null ? null : messageRowToRecord(row);
173
+ }
174
+ async listMessages(input) {
175
+ this.#assertOpen();
176
+ const query = validateListMessages(input);
177
+ const fetchLimit = query.limit + 1;
178
+ let rows;
179
+ if (query.beforeRowId === null) {
180
+ rows = this.#database.query(`SELECT row_id, wa_message_id, direction, from_phone, to_phone, type, status, graph_message_id, created_at, updated_at
181
+ FROM wats_messages
182
+ ORDER BY created_at DESC, row_id DESC
183
+ LIMIT ?`).all(fetchLimit);
184
+ } else {
185
+ const cursor = this.#database.query("SELECT row_id, created_at FROM wats_messages WHERE row_id = ?").get(query.beforeRowId);
186
+ if (cursor === null) {
187
+ return Object.freeze({ items: Object.freeze([]), nextCursor: null });
188
+ }
189
+ rows = this.#database.query(`SELECT row_id, wa_message_id, direction, from_phone, to_phone, type, status, graph_message_id, created_at, updated_at
190
+ FROM wats_messages
191
+ WHERE created_at < ? OR (created_at = ? AND row_id < ?)
192
+ ORDER BY created_at DESC, row_id DESC
193
+ LIMIT ?`).all(cursor.created_at, cursor.created_at, cursor.row_id, fetchLimit);
194
+ }
195
+ const pageRows = rows.slice(0, query.limit);
196
+ const items = Object.freeze(pageRows.map((row) => messageRowToRecord(row)));
197
+ const nextCursor = rows.length > query.limit ? items[items.length - 1]?.rowId ?? null : null;
198
+ return Object.freeze({ items, nextCursor });
199
+ }
146
200
  async close() {
147
201
  if (this.#closed)
148
202
  return;
@@ -238,6 +292,34 @@ const MIGRATIONS = Object.freeze([
238
292
  statements: Object.freeze([
239
293
  "ALTER TABLE wats_outbox ADD COLUMN lease_id INTEGER NOT NULL DEFAULT 0"
240
294
  ])
295
+ },
296
+ {
297
+ id: "003_message_projection",
298
+ version: 3,
299
+ checksum: "sha256:wats-persistence-003-message-projection-v1",
300
+ statements: Object.freeze([
301
+ `CREATE TABLE IF NOT EXISTS wats_messages (
302
+ row_id TEXT PRIMARY KEY,
303
+ wa_message_id TEXT NOT NULL,
304
+ direction TEXT NOT NULL,
305
+ from_phone TEXT,
306
+ to_phone TEXT,
307
+ type TEXT NOT NULL,
308
+ status TEXT NOT NULL,
309
+ graph_message_id TEXT,
310
+ created_at TEXT NOT NULL,
311
+ updated_at TEXT NOT NULL
312
+ )`,
313
+ `CREATE INDEX IF NOT EXISTS wats_messages_wa_message_id_idx ON wats_messages (wa_message_id)`,
314
+ `CREATE INDEX IF NOT EXISTS wats_messages_created_at_idx ON wats_messages (created_at DESC, row_id DESC)`,
315
+ `CREATE TABLE IF NOT EXISTS wats_message_status_events (
316
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
317
+ wa_message_id TEXT NOT NULL,
318
+ status TEXT NOT NULL,
319
+ timestamp TEXT NOT NULL
320
+ )`,
321
+ `CREATE INDEX IF NOT EXISTS wats_message_status_events_wa_message_id_idx ON wats_message_status_events (wa_message_id, id)`
322
+ ])
241
323
  }
242
324
  ]);
243
325
  function hasControlChars(value) {
@@ -398,6 +480,62 @@ function outboxRowToItem(row) {
398
480
  updatedAt: row.updated_at
399
481
  });
400
482
  }
483
+ function validateMessageDirection(value) {
484
+ if (value !== "inbound" && value !== "outbound") {
485
+ throw new PersistenceError("invalid_record", 'direction must be "inbound" or "outbound".');
486
+ }
487
+ return value;
488
+ }
489
+ function validateOptionalRecordString(value, label) {
490
+ if (value === undefined || value === null)
491
+ return null;
492
+ return validateRecordString(value, label);
493
+ }
494
+ function validateMessageRecord(input) {
495
+ const record = validateRecordInput(input, "message record");
496
+ return Object.freeze({
497
+ rowId: validateRecordString(record.rowId, "rowId"),
498
+ waMessageId: validateRecordString(record.waMessageId, "waMessageId"),
499
+ direction: validateMessageDirection(record.direction),
500
+ fromPhone: validateOptionalRecordString(record.fromPhone, "fromPhone"),
501
+ toPhone: validateOptionalRecordString(record.toPhone, "toPhone"),
502
+ type: validateRecordString(record.type, "type"),
503
+ status: validateRecordString(record.status, "status"),
504
+ graphMessageId: validateOptionalRecordString(record.graphMessageId, "graphMessageId"),
505
+ createdAt: validateTimestamp(record.createdAt, "createdAt"),
506
+ updatedAt: validateTimestamp(record.updatedAt, "updatedAt")
507
+ });
508
+ }
509
+ function validateMessageStatusEvent(input) {
510
+ const record = validateRecordInput(input, "message status event");
511
+ return Object.freeze({
512
+ waMessageId: validateRecordString(record.waMessageId, "waMessageId"),
513
+ status: validateRecordString(record.status, "status"),
514
+ timestamp: validateTimestamp(record.timestamp, "timestamp")
515
+ });
516
+ }
517
+ function validateListMessages(input) {
518
+ const record = validateRecordInput(input, "message list");
519
+ if (typeof record.limit !== "number" || !Number.isInteger(record.limit) || record.limit < 1 || record.limit > 100) {
520
+ throw new PersistenceError("invalid_record", "limit must be an integer from 1 to 100.");
521
+ }
522
+ const beforeRowId = validateOptionalRecordString(record.beforeRowId, "beforeRowId");
523
+ return Object.freeze({ limit: record.limit, beforeRowId });
524
+ }
525
+ function messageRowToRecord(row) {
526
+ return Object.freeze({
527
+ rowId: row.row_id,
528
+ waMessageId: row.wa_message_id,
529
+ direction: row.direction,
530
+ fromPhone: row.from_phone,
531
+ toPhone: row.to_phone,
532
+ type: row.type,
533
+ status: row.status,
534
+ graphMessageId: row.graph_message_id,
535
+ createdAt: row.created_at,
536
+ updatedAt: row.updated_at
537
+ });
538
+ }
401
539
  function subtractMillisecondsIso(timestamp, milliseconds) {
402
540
  return new Date(new Date(timestamp).getTime() - milliseconds).toISOString();
403
541
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wats/persistence",
3
- "version": "0.3.26",
3
+ "version": "0.3.27",
4
4
  "private": false,
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -14,6 +14,10 @@
14
14
  "./sqlite": {
15
15
  "types": "./dist/sqlite.d.ts",
16
16
  "import": "./dist/sqlite.js"
17
+ },
18
+ "./postgres": {
19
+ "types": "./dist/postgres.d.ts",
20
+ "import": "./dist/postgres.js"
17
21
  }
18
22
  },
19
23
  "files": [
@@ -24,20 +28,19 @@
24
28
  "publishConfig": {
25
29
  "access": "public"
26
30
  },
27
- "repository": {
28
- "type": "git",
29
- "url": "git+https://github.com/Switchbord/wats.git",
30
- "directory": "packages/persistence"
31
- },
32
- "homepage": "https://github.com/Switchbord/wats#readme",
33
- "bugs": {
34
- "url": "https://github.com/Switchbord/wats/issues"
35
- },
36
31
  "keywords": [
37
32
  "whatsapp",
38
33
  "whatsapp-cloud-api",
39
34
  "sqlite",
40
35
  "persistence",
41
36
  "wats"
42
- ]
37
+ ],
38
+ "peerDependencies": {
39
+ "pg": "^8.11.0"
40
+ },
41
+ "peerDependenciesMeta": {
42
+ "pg": {
43
+ "optional": true
44
+ }
45
+ }
43
46
  }