@wats/persistence 0.3.30 → 0.5.0-beta

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.
@@ -1,4 +1,4 @@
1
- import { type ConversationWindowInput, type ConversationWindowState, type PersistenceStore } from "./index";
1
+ import { type ConversationWindowInput, type ConversationWindowState, type PersistenceStore } from "./index.js";
2
2
  /**
3
3
  * Compute the 24-hour customer-service-window state for a phone number.
4
4
  *
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  PersistenceError
3
- } from "./index";
3
+ } from "./index.js";
4
4
  const DEFAULT_WINDOW_MS = 86400000;
5
5
  const MIN_WINDOW_MS = 1;
6
6
  const MAX_WINDOW_MS = 604800000;
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
- export declare const CURRENT_SCHEMA_VERSION: 4;
1
+ export declare const CURRENT_SCHEMA_VERSION: 6;
2
2
  export declare const REDACTED_SQLITE_LOCATION: "[REDACTED_SQLITE_DATABASE]";
3
3
  export type PersistenceBackend = "sqlite" | "postgres";
4
- export type PersistenceErrorCode = "invalid_options" | "invalid_filename" | "invalid_record" | "migration_failed" | "migration_checksum_mismatch" | "migration_lock_failed" | "outbox_failed" | "store_closed";
4
+ export type PersistenceErrorCode = "invalid_options" | "invalid_filename" | "invalid_record" | "migration_failed" | "migration_checksum_mismatch" | "migration_lock_failed" | "outbox_failed" | "claim_failed" | "completion_failed" | "store_closed";
5
5
  export interface MigrationReport {
6
6
  readonly currentVersion: number;
7
7
  readonly appliedMigrations: readonly string[];
@@ -30,6 +30,20 @@ export interface ServiceRequestRecordInput extends ServiceRequestLookupInput {
30
30
  export type ServiceRequestLookupResult = null | "conflict" | {
31
31
  readonly responseJson: string;
32
32
  };
33
+ export interface ServiceRequestClaimInput {
34
+ readonly idempotencyKey: string;
35
+ readonly requestHash: string;
36
+ readonly createdAt: string;
37
+ }
38
+ export type ServiceRequestClaimResult = "claimed" | "pending" | "conflict" | {
39
+ readonly responseJson: string;
40
+ };
41
+ export interface ServiceRequestCompletionInput {
42
+ readonly idempotencyKey: string;
43
+ readonly requestHash: string;
44
+ readonly responseJson: string;
45
+ readonly createdAt: string;
46
+ }
33
47
  export type OutboxStatus = "pending" | "processing" | "succeeded";
34
48
  export interface OutboxItem {
35
49
  readonly id: string;
@@ -128,6 +142,8 @@ export interface PersistenceStore {
128
142
  recordWebhookEvent(input: WebhookEventRecordInput): Promise<WebhookEventRecordResult>;
129
143
  getServiceRequest(input: ServiceRequestLookupInput): Promise<ServiceRequestLookupResult>;
130
144
  recordServiceRequest(input: ServiceRequestRecordInput): Promise<void>;
145
+ claimServiceRequest?(input: ServiceRequestClaimInput): Promise<ServiceRequestClaimResult>;
146
+ completeServiceRequest?(input: ServiceRequestCompletionInput): Promise<void>;
131
147
  enqueueOutboxItem(input: OutboxEnqueueInput): Promise<OutboxEnqueueResult>;
132
148
  claimOutboxItems(input: OutboxClaimInput): Promise<readonly OutboxItem[]>;
133
149
  markOutboxItemFailed(input: OutboxFailedInput): Promise<void>;
@@ -146,12 +162,12 @@ export declare class PersistenceError extends Error {
146
162
  readonly code: PersistenceErrorCode;
147
163
  constructor(code: PersistenceErrorCode, message?: string, options?: ErrorOptions);
148
164
  }
149
- export { createSqlitePersistence } from "./sqlite";
150
- export type { SqlitePersistenceOptions } from "./sqlite";
151
- export { runOutboxWorkerOnce } from "./outbox";
152
- export type { OutboxWorkerOptions, OutboxWorkerReport } from "./outbox";
153
- export { startOutboxWorker } from "./outboxWorker";
154
- export type { OutboxScheduler, OutboxTimerHandle, OutboxWorkerHandle, OutboxWorkerTickReport, StartOutboxWorkerOptions } from "./outboxWorker";
155
- export { getConversationWindowState, canSendFreeForm } from "./conversationWindow";
156
- export { createPostgresPersistence, createPostgresPersistenceWithClient, REDACTED_POSTGRES_LOCATION } from "./postgres";
157
- export type { PostgresPersistenceOptions, PostgresClientLike, PostgresQueryResult } from "./postgres";
165
+ export { createSqlitePersistence } from "./sqlite.js";
166
+ export type { SqlitePersistenceOptions } from "./sqlite.js";
167
+ export { runOutboxWorkerOnce } from "./outbox.js";
168
+ export type { OutboxWorkerOptions, OutboxWorkerReport } from "./outbox.js";
169
+ export { startOutboxWorker } from "./outboxWorker.js";
170
+ export type { OutboxScheduler, OutboxTimerHandle, OutboxWorkerHandle, OutboxWorkerTickReport, StartOutboxWorkerOptions } from "./outboxWorker.js";
171
+ export { getConversationWindowState, canSendFreeForm } from "./conversationWindow.js";
172
+ export { createPostgresPersistence, createPostgresPersistenceWithClient, REDACTED_POSTGRES_LOCATION } from "./postgres.js";
173
+ export type { PostgresPersistenceOptions, PostgresClientLike, PostgresQueryResult } from "./postgres.js";
package/dist/index.js CHANGED
@@ -1,4 +1,4 @@
1
- export const CURRENT_SCHEMA_VERSION = 4;
1
+ export const CURRENT_SCHEMA_VERSION = 6;
2
2
  export const REDACTED_SQLITE_LOCATION = "[REDACTED_SQLITE_DATABASE]";
3
3
 
4
4
  export class PersistenceError extends Error {
@@ -9,15 +9,15 @@ export class PersistenceError extends Error {
9
9
  this.code = code;
10
10
  }
11
11
  }
12
- export { createSqlitePersistence } from "./sqlite";
13
- export { runOutboxWorkerOnce } from "./outbox";
14
- export { startOutboxWorker } from "./outboxWorker";
12
+ export { createSqlitePersistence } from "./sqlite.js";
13
+ export { runOutboxWorkerOnce } from "./outbox.js";
14
+ export { startOutboxWorker } from "./outboxWorker.js";
15
15
  export {
16
16
  getConversationWindowState,
17
17
  canSendFreeForm
18
- } from "./conversationWindow";
18
+ } from "./conversationWindow.js";
19
19
  export {
20
20
  createPostgresPersistence,
21
21
  createPostgresPersistenceWithClient,
22
22
  REDACTED_POSTGRES_LOCATION
23
- } from "./postgres";
23
+ } from "./postgres.js";
package/dist/outbox.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { OutboxItem, PersistenceStore } from "./index";
1
+ import type { OutboxItem, PersistenceStore } from "./index.js";
2
2
  export interface OutboxWorkerOptions {
3
3
  readonly now: string;
4
4
  readonly limit: number;
@@ -1,5 +1,5 @@
1
- import type { OutboxItem, PersistenceStore } from "./index";
2
- import { type OutboxWorkerReport } from "./outbox";
1
+ import type { OutboxItem, PersistenceStore } from "./index.js";
2
+ import { type OutboxWorkerReport } from "./outbox.js";
3
3
  /** Opaque timer handle returned by {@link OutboxScheduler.setTimeout}. */
4
4
  export type OutboxTimerHandle = unknown;
5
5
  /**
@@ -1,4 +1,4 @@
1
- import { runOutboxWorkerOnce } from "./outbox";
1
+ import { runOutboxWorkerOnce } from "./outbox.js";
2
2
  const DEFAULT_INTERVAL_MS = 5000;
3
3
  const DEFAULT_BATCH_LIMIT = 10;
4
4
  const DEFAULT_RETRY_DELAY_MS = 30000;
@@ -1,4 +1,4 @@
1
- import { type PersistenceStore } from "./index";
1
+ import { type PersistenceStore } from "./index.js";
2
2
  export declare const REDACTED_POSTGRES_LOCATION: "[REDACTED_POSTGRES_DATABASE]";
3
3
  export interface PostgresPersistenceOptions {
4
4
  readonly connectionString: string;
package/dist/postgres.js CHANGED
@@ -1,12 +1,30 @@
1
1
  class PostgresPersistenceStore {
2
2
  backend = "postgres";
3
3
  #client;
4
+ #closing = false;
4
5
  #closed = false;
6
+ #chain = Promise.resolve();
5
7
  constructor(client) {
6
8
  this.#client = client;
7
9
  }
10
+ #withLock(fn, errorCode = "outbox_failed") {
11
+ const run = this.#chain.then(fn, fn).then((value) => value, (cause) => {
12
+ if (cause instanceof PersistenceError)
13
+ throw cause;
14
+ throw new PersistenceError(errorCode, "Postgres operation failed.");
15
+ });
16
+ this.#chain = run.then(() => {
17
+ return;
18
+ }, () => {
19
+ return;
20
+ });
21
+ return run;
22
+ }
8
23
  async migrate() {
9
24
  this.#assertOpen();
25
+ return this.#withLock(() => this.#migrateLocked());
26
+ }
27
+ async#migrateLocked() {
10
28
  await this.#client.query(`CREATE TABLE IF NOT EXISTS wats_persistence_lock (
11
29
  id INTEGER PRIMARY KEY CHECK (id = 1),
12
30
  holder TEXT NOT NULL,
@@ -38,7 +56,7 @@ class PostgresPersistenceStore {
38
56
  applied.push(migration.id);
39
57
  } catch (cause) {
40
58
  await this.#client.query("ROLLBACK");
41
- throw new PersistenceError("migration_failed", "Postgres migration failed.", { cause });
59
+ throw new PersistenceError("migration_failed", "Postgres migration failed.");
42
60
  }
43
61
  }
44
62
  return Object.freeze({ currentVersion: CURRENT_SCHEMA_VERSION, appliedMigrations: Object.freeze(applied), alreadyCurrent: applied.length === 0 });
@@ -48,40 +66,95 @@ class PostgresPersistenceStore {
48
66
  }
49
67
  async health() {
50
68
  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 });
69
+ return this.#withLock(async () => {
70
+ const result = await this.#client.query("SELECT COALESCE(MAX(version), 0) AS version FROM wats_schema_migrations");
71
+ const version = result.rows[0]?.version;
72
+ return Object.freeze({ ok: true, backend: "postgres", currentVersion: version === undefined ? 0 : numeric(version), redactedLocation: REDACTED_POSTGRES_LOCATION });
73
+ });
54
74
  }
55
75
  async recordWebhookEvent(input) {
56
76
  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";
77
+ return this.#withLock(async () => {
78
+ const record = validateWebhookEventRecord(input);
79
+ 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]);
80
+ return result.rowCount === 1 ? "recorded" : "duplicate";
81
+ });
60
82
  }
61
83
  async getServiceRequest(input) {
62
84
  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 });
85
+ return this.#withLock(async () => {
86
+ const lookup = validateServiceRequestLookup(input);
87
+ const result = await this.#client.query("SELECT request_hash, response_json, status FROM wats_service_requests WHERE idempotency_key = $1", [lookup.idempotencyKey]);
88
+ const row = result.rows[0];
89
+ if (row === undefined)
90
+ return null;
91
+ if (row.request_hash !== lookup.requestHash)
92
+ return "conflict";
93
+ if (row.status === "claimed" || row.response_json === null)
94
+ return null;
95
+ return Object.freeze({ responseJson: row.response_json });
96
+ });
71
97
  }
72
98
  async recordServiceRequest(input) {
73
99
  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]);
100
+ return this.#withLock(async () => {
101
+ const record = validateServiceRequestRecord(input);
102
+ await this.#client.query("INSERT INTO wats_service_requests (idempotency_key, request_hash, response_json, created_at, status) VALUES ($1, $2, $3, $4, 'completed') ON CONFLICT (idempotency_key) DO NOTHING", [record.idempotencyKey, record.requestHash, record.responseJson, record.createdAt]);
103
+ });
104
+ }
105
+ async claimServiceRequest(input) {
106
+ this.#assertOpen();
107
+ return this.#withLock(async () => {
108
+ const claim = validateServiceRequestClaim(input);
109
+ const insert = await this.#client.query("INSERT INTO wats_service_requests (idempotency_key, request_hash, response_json, created_at, claimed_at, status) VALUES ($1, $2, NULL, $3, $3, 'claimed') ON CONFLICT (idempotency_key) DO NOTHING", [claim.idempotencyKey, claim.requestHash, claim.createdAt]);
110
+ if (insert.rowCount === 1)
111
+ return "claimed";
112
+ const result = await this.#client.query("SELECT request_hash, response_json, status FROM wats_service_requests WHERE idempotency_key = $1", [claim.idempotencyKey]);
113
+ const row = result.rows[0];
114
+ if (row === undefined) {
115
+ throw new PersistenceError("claim_failed", "Postgres service request claim did not persist.");
116
+ }
117
+ if (row.request_hash !== claim.requestHash)
118
+ return "conflict";
119
+ if (row.status === "completed" && row.response_json !== null) {
120
+ return Object.freeze({ responseJson: row.response_json });
121
+ }
122
+ return "pending";
123
+ }, "claim_failed");
124
+ }
125
+ async completeServiceRequest(input) {
126
+ this.#assertOpen();
127
+ return this.#withLock(async () => {
128
+ const completion = validateServiceRequestCompletion(input);
129
+ const existing = await this.#client.query("SELECT request_hash, status FROM wats_service_requests WHERE idempotency_key = $1", [completion.idempotencyKey]);
130
+ const row = existing.rows[0];
131
+ if (row === undefined) {
132
+ throw new PersistenceError("completion_failed", "Postgres service request completion requires a prior claim.");
133
+ }
134
+ if (row.request_hash !== completion.requestHash) {
135
+ throw new PersistenceError("completion_failed", "Postgres service request completion hash mismatch.");
136
+ }
137
+ if (row.status === "completed")
138
+ return;
139
+ const result = await this.#client.query("UPDATE wats_service_requests SET response_json = $1, status = 'completed', created_at = $2 WHERE idempotency_key = $3 AND request_hash = $4 AND status = 'claimed'", [completion.responseJson, completion.createdAt, completion.idempotencyKey, completion.requestHash]);
140
+ if (result.rowCount !== 1) {
141
+ throw new PersistenceError("completion_failed", "Postgres service request completion lease is stale.");
142
+ }
143
+ }, "completion_failed");
76
144
  }
77
145
  async enqueueOutboxItem(input) {
78
146
  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";
147
+ return this.#withLock(async () => {
148
+ const item = validateOutboxEnqueue(input);
149
+ 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]);
150
+ return result.rowCount === 1 ? "enqueued" : "duplicate";
151
+ });
82
152
  }
83
153
  async claimOutboxItems(input) {
84
154
  this.#assertOpen();
155
+ return this.#withLock(() => this.#claimOutboxItemsLocked(input));
156
+ }
157
+ async#claimOutboxItemsLocked(input) {
85
158
  const claim = validateOutboxClaim(input);
86
159
  const leaseExpiredAt = subtractMillisecondsIso(claim.now, OUTBOX_PROCESSING_LEASE_MS);
87
160
  await this.#client.query("BEGIN");
@@ -105,97 +178,149 @@ class PostgresPersistenceStore {
105
178
  await this.#client.query("ROLLBACK");
106
179
  if (cause instanceof PersistenceError)
107
180
  throw cause;
108
- throw new PersistenceError("outbox_failed", "Postgres outbox claim failed.", { cause });
181
+ throw new PersistenceError("outbox_failed", "Postgres outbox claim failed.");
109
182
  }
110
183
  }
111
184
  async markOutboxItemFailed(input) {
112
185
  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.");
186
+ return this.#withLock(async () => {
187
+ const failure = validateOutboxFailed(input);
188
+ 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]);
189
+ if (result.rowCount !== 1)
190
+ throw new PersistenceError("outbox_failed", "Postgres outbox failure lease is stale.");
191
+ });
117
192
  }
118
193
  async markOutboxItemSucceeded(input) {
119
194
  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.");
195
+ return this.#withLock(async () => {
196
+ const success = validateOutboxSucceeded(input);
197
+ 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]);
198
+ if (result.rowCount !== 1)
199
+ throw new PersistenceError("outbox_failed", "Postgres outbox success lease is stale.");
200
+ });
124
201
  }
125
202
  async recordMessage(input) {
126
203
  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]);
204
+ return this.#withLock(async () => {
205
+ const record = validateMessageRecord(input);
206
+ try {
207
+ await this.#client.query(`INSERT INTO wats_messages
208
+ (row_id, wa_message_id, direction, from_phone, to_phone, type, status, graph_message_id, created_at, updated_at)
209
+ VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
210
+ 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]);
211
+ } catch (cause) {
212
+ if (isUniqueViolation(cause))
213
+ return;
214
+ throw new PersistenceError("outbox_failed", "Postgres message record failed.");
215
+ }
216
+ await this.#reconcileStoredStatus(record.waMessageId, record.status, record.updatedAt);
217
+ });
218
+ }
219
+ async#reconcileStoredStatus(waMessageId, recordedStatus, recordedUpdatedAt) {
220
+ const events = await this.#client.query("SELECT status, timestamp FROM wats_message_status_events WHERE wa_message_id = $1 ORDER BY timestamp ASC", [waMessageId]);
221
+ if (events.rows.length === 0)
222
+ return;
223
+ let bestStatus = recordedStatus;
224
+ let bestUpdatedAt = recordedUpdatedAt;
225
+ for (const ev of events.rows) {
226
+ if (shouldAdvanceStatus(ev.status, bestStatus)) {
227
+ bestStatus = ev.status;
228
+ if (ev.timestamp > bestUpdatedAt)
229
+ bestUpdatedAt = ev.timestamp;
230
+ }
231
+ }
232
+ if (bestStatus !== recordedStatus || bestUpdatedAt !== recordedUpdatedAt) {
233
+ await this.#client.query("UPDATE wats_messages SET status = $1, updated_at = $2 WHERE wa_message_id = $3", [bestStatus, bestUpdatedAt, waMessageId]);
234
+ }
132
235
  }
133
236
  async appendMessageStatus(input) {
134
237
  this.#assertOpen();
238
+ return this.#withLock(() => this.#appendMessageStatusLocked(input));
239
+ }
240
+ async#appendMessageStatusLocked(input) {
135
241
  const event = validateMessageStatusEvent(input);
136
242
  await this.#client.query("BEGIN");
137
243
  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]);
244
+ await this.#client.query("INSERT INTO wats_message_status_events (wa_message_id, status, timestamp) VALUES ($1, $2, $3) ON CONFLICT (wa_message_id, status, timestamp) DO NOTHING", [event.waMessageId, event.status, event.timestamp]);
245
+ const current = await this.#client.query("SELECT status, updated_at FROM wats_messages WHERE wa_message_id = $1", [event.waMessageId]);
246
+ const row = current.rows[0];
247
+ if (row !== undefined && shouldAdvanceStatus(event.status, row.status)) {
248
+ const newUpdatedAt = event.timestamp > row.updated_at ? event.timestamp : row.updated_at;
249
+ await this.#client.query("UPDATE wats_messages SET status = $1, updated_at = $2 WHERE wa_message_id = $3", [event.status, newUpdatedAt, event.waMessageId]);
250
+ }
140
251
  await this.#client.query("COMMIT");
141
252
  } catch (cause) {
142
253
  await this.#client.query("ROLLBACK");
143
- throw new PersistenceError("invalid_record", "Postgres message status append failed.", { cause });
254
+ if (cause instanceof PersistenceError)
255
+ throw cause;
256
+ throw new PersistenceError("outbox_failed", "Postgres message status append failed.");
144
257
  }
145
258
  }
146
259
  async getMessage(input) {
147
260
  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);
261
+ return this.#withLock(async () => {
262
+ const record = validateRecordInput(input, "message lookup");
263
+ const waMessageId = validateRecordString(record.waMessageId, "waMessageId");
264
+ 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
265
+ FROM wats_messages WHERE wa_message_id = $1`, [waMessageId]);
266
+ const row = result.rows[0];
267
+ return row === undefined ? null : messageRowToRecord(row);
268
+ });
154
269
  }
155
270
  async listMessages(input) {
156
271
  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 });
272
+ return this.#withLock(async () => {
273
+ const query = validateListMessages(input);
274
+ const fetchLimit = query.limit + 1;
275
+ let rows;
276
+ if (query.beforeRowId === null) {
277
+ 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
278
+ FROM wats_messages
279
+ ORDER BY created_at DESC, row_id DESC
280
+ LIMIT $1`, [fetchLimit])).rows;
281
+ } else {
282
+ const cursor = await this.#client.query("SELECT row_id, created_at FROM wats_messages WHERE row_id = $1", [query.beforeRowId]);
283
+ const cursorRow = cursor.rows[0];
284
+ if (cursorRow === undefined)
285
+ return Object.freeze({ items: Object.freeze([]), nextCursor: null });
286
+ 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
287
+ FROM wats_messages
288
+ WHERE created_at < $1 OR (created_at = $2 AND row_id < $3)
289
+ ORDER BY created_at DESC, row_id DESC
290
+ LIMIT $4`, [cursorRow.created_at, cursorRow.created_at, cursorRow.row_id, fetchLimit])).rows;
291
+ }
292
+ const pageRows = rows.slice(0, query.limit);
293
+ const items = Object.freeze(pageRows.map((row) => messageRowToRecord(row)));
294
+ const nextCursor = rows.length > query.limit ? items[items.length - 1]?.rowId ?? null : null;
295
+ return Object.freeze({ items, nextCursor });
296
+ });
180
297
  }
181
298
  async getLatestInboundMessageAt(input) {
182
299
  this.#assertOpen();
183
- const record = validateRecordInput(input, "latest inbound lookup");
184
- const phone = validateRecordString(record.phone, "phone");
185
- const result = await this.#client.query(`SELECT created_at FROM wats_messages
186
- WHERE direction = 'inbound' AND from_phone = $1
187
- ORDER BY created_at DESC
188
- LIMIT 1`, [phone]);
189
- const row = result.rows[0];
190
- return row === undefined ? null : row.created_at;
300
+ return this.#withLock(async () => {
301
+ const record = validateRecordInput(input, "latest inbound lookup");
302
+ const phone = validateRecordString(record.phone, "phone");
303
+ const result = await this.#client.query(`SELECT created_at FROM wats_messages
304
+ WHERE direction = 'inbound' AND from_phone = $1
305
+ ORDER BY created_at DESC
306
+ LIMIT 1`, [phone]);
307
+ const row = result.rows[0];
308
+ return row === undefined ? null : row.created_at;
309
+ });
191
310
  }
192
311
  async countOutboxPending() {
193
312
  this.#assertOpen();
194
- const result = await this.#client.query("SELECT COUNT(*) AS count FROM wats_outbox WHERE status = $1", ["pending"]);
195
- const row = result.rows[0];
196
- return row === undefined ? 0 : numeric(row.count);
313
+ return this.#withLock(async () => {
314
+ const result = await this.#client.query("SELECT COUNT(*) AS count FROM wats_outbox WHERE status = $1", ["pending"]);
315
+ const row = result.rows[0];
316
+ return row === undefined ? 0 : numeric(row.count);
317
+ });
197
318
  }
198
319
  async close() {
320
+ this.#closing = true;
321
+ await this.#withLock(() => this.#closeLocked());
322
+ }
323
+ async#closeLocked() {
199
324
  if (this.#closed)
200
325
  return;
201
326
  this.#closed = true;
@@ -216,17 +341,36 @@ class PostgresPersistenceStore {
216
341
  }
217
342
  }
218
343
  #assertOpen() {
219
- if (this.#closed)
344
+ if (this.#closing || this.#closed)
220
345
  throw new PersistenceError("store_closed", "Persistence store is closed.");
221
346
  }
222
347
  }
223
348
  import {
224
349
  CURRENT_SCHEMA_VERSION,
225
350
  PersistenceError
226
- } from "./index";
351
+ } from "./index.js";
227
352
  export const REDACTED_POSTGRES_LOCATION = "[REDACTED_POSTGRES_DATABASE]";
228
353
  const OUTBOX_PROCESSING_LEASE_MS = 300000;
229
354
  const MAX_CONNECTION_STRING_LENGTH = 4096;
355
+ const PG_CONNECT_TIMEOUT_MILLIS = 1e4;
356
+ const STATUS_RANK = Object.freeze({
357
+ pending: 0,
358
+ sent: 1,
359
+ delivered: 2,
360
+ read: 3,
361
+ failed: 1
362
+ });
363
+ function statusRank(status) {
364
+ return STATUS_RANK[status] ?? 0;
365
+ }
366
+ function failedMayReplace(currentStatus) {
367
+ return statusRank(currentStatus) <= 1;
368
+ }
369
+ function shouldAdvanceStatus(newStatus, currentStatus) {
370
+ if (newStatus === "failed")
371
+ return failedMayReplace(currentStatus);
372
+ return statusRank(newStatus) > statusRank(currentStatus);
373
+ }
230
374
  const POSTGRES_MIGRATIONS = Object.freeze([
231
375
  {
232
376
  id: "001_initial",
@@ -310,6 +454,67 @@ const POSTGRES_MIGRATIONS = Object.freeze([
310
454
  `CREATE INDEX IF NOT EXISTS wats_messages_direction_from_phone_created_at_idx
311
455
  ON wats_messages (direction, from_phone, created_at DESC)`
312
456
  ])
457
+ },
458
+ {
459
+ id: "005_service_request_claims",
460
+ version: 5,
461
+ checksum: "sha256:wats-persistence-005-service-request-claims-v1",
462
+ statements: Object.freeze([
463
+ `CREATE TABLE IF NOT EXISTS wats_service_requests_new (
464
+ idempotency_key TEXT PRIMARY KEY,
465
+ request_hash TEXT NOT NULL,
466
+ response_json TEXT,
467
+ created_at TEXT NOT NULL,
468
+ status TEXT NOT NULL DEFAULT 'completed',
469
+ claimed_at TEXT
470
+ )`,
471
+ `INSERT INTO wats_service_requests_new (idempotency_key, request_hash, response_json, created_at, status)
472
+ SELECT idempotency_key, request_hash, response_json, created_at, 'completed'
473
+ FROM wats_service_requests`,
474
+ `DROP TABLE wats_service_requests`,
475
+ `ALTER TABLE wats_service_requests_new RENAME TO wats_service_requests`
476
+ ])
477
+ },
478
+ {
479
+ id: "006_message_uniqueness",
480
+ version: 6,
481
+ checksum: "sha256:wats-persistence-006-message-uniqueness-v1",
482
+ statements: Object.freeze([
483
+ `DELETE FROM wats_message_status_events
484
+ WHERE id IN (
485
+ SELECT id FROM (
486
+ SELECT id,
487
+ ROW_NUMBER() OVER (
488
+ PARTITION BY wa_message_id, status, timestamp
489
+ ORDER BY id ASC
490
+ ) AS rn
491
+ FROM wats_message_status_events
492
+ ) sub WHERE rn > 1
493
+ )`,
494
+ `DELETE FROM wats_messages
495
+ WHERE row_id IN (
496
+ SELECT row_id FROM (
497
+ SELECT row_id,
498
+ ROW_NUMBER() OVER (
499
+ PARTITION BY direction, wa_message_id
500
+ ORDER BY
501
+ CASE status
502
+ WHEN 'read' THEN 4
503
+ WHEN 'delivered' THEN 3
504
+ WHEN 'sent' THEN 2
505
+ WHEN 'pending' THEN 1
506
+ ELSE 0
507
+ END DESC,
508
+ row_id ASC
509
+ ) AS rn
510
+ FROM wats_messages
511
+ ) sub WHERE rn > 1
512
+ )`,
513
+ `CREATE UNIQUE INDEX IF NOT EXISTS wats_messages_direction_wa_message_id_uidx
514
+ ON wats_messages (direction, wa_message_id)`,
515
+ `CREATE UNIQUE INDEX IF NOT EXISTS wats_message_status_events_wa_message_id_status_timestamp_uidx
516
+ ON wats_message_status_events (wa_message_id, status, timestamp)`
517
+ ])
313
518
  }
314
519
  ]);
315
520
  function hasControlChars(value) {
@@ -324,6 +529,12 @@ function isRecord(value) {
324
529
  const proto = Object.getPrototypeOf(value);
325
530
  return proto === null || proto === Object.prototype;
326
531
  }
532
+ function isUniqueViolation(cause) {
533
+ if (cause === null || typeof cause !== "object")
534
+ return false;
535
+ const code = cause.code;
536
+ return code === "23505";
537
+ }
327
538
  function validateConnectionString(value) {
328
539
  if (typeof value !== "string") {
329
540
  throw new PersistenceError("invalid_options", "Postgres connectionString must be a postgres:// or postgresql:// URL.");
@@ -391,7 +602,30 @@ function validateServiceRequestRecord(input) {
391
602
  try {
392
603
  JSON.parse(responseJson);
393
604
  } catch (cause) {
394
- throw new PersistenceError("invalid_record", "responseJson must be valid JSON.", { cause });
605
+ throw new PersistenceError("invalid_record", "responseJson must be valid JSON.");
606
+ }
607
+ return Object.freeze({
608
+ idempotencyKey: validateRecordString(record.idempotencyKey, "idempotencyKey"),
609
+ requestHash: validateRecordString(record.requestHash, "requestHash"),
610
+ responseJson,
611
+ createdAt: validateTimestamp(record.createdAt, "createdAt")
612
+ });
613
+ }
614
+ function validateServiceRequestClaim(input) {
615
+ const record = validateRecordInput(input, "service request claim");
616
+ return Object.freeze({
617
+ idempotencyKey: validateRecordString(record.idempotencyKey, "idempotencyKey"),
618
+ requestHash: validateRecordString(record.requestHash, "requestHash"),
619
+ createdAt: validateTimestamp(record.createdAt, "createdAt")
620
+ });
621
+ }
622
+ function validateServiceRequestCompletion(input) {
623
+ const record = validateRecordInput(input, "service request completion");
624
+ const responseJson = validateRecordString(record.responseJson, "responseJson");
625
+ try {
626
+ JSON.parse(responseJson);
627
+ } catch (cause) {
628
+ throw new PersistenceError("invalid_record", "responseJson must be valid JSON.");
395
629
  }
396
630
  return Object.freeze({
397
631
  idempotencyKey: validateRecordString(record.idempotencyKey, "idempotencyKey"),
@@ -527,12 +761,27 @@ export async function createPostgresPersistence(options) {
527
761
  const defaultExport = mod.default;
528
762
  Client = mod.Client ?? (typeof defaultExport === "function" ? defaultExport : defaultExport?.Client);
529
763
  } catch (cause) {
530
- throw new PersistenceError("invalid_options", "Postgres persistence requires the optional 'pg' package.", { cause });
764
+ throw new PersistenceError("invalid_options", "Postgres persistence requires the optional 'pg' package.");
531
765
  }
532
766
  if (Client === undefined) {
533
767
  throw new PersistenceError("invalid_options", "Postgres persistence requires the optional 'pg' package.");
534
768
  }
535
- return createPostgresPersistenceWithClient(new Client({ connectionString }));
769
+ const client = new Client({ connectionString, connectionTimeoutMillis: PG_CONNECT_TIMEOUT_MILLIS });
770
+ if (typeof client.connect !== "function") {
771
+ try {
772
+ await client.end();
773
+ } catch {}
774
+ throw new PersistenceError("invalid_options", "Postgres client must expose a connect function for the factory path.");
775
+ }
776
+ try {
777
+ await client.connect();
778
+ } catch (cause) {
779
+ try {
780
+ await client.end();
781
+ } catch {}
782
+ throw new PersistenceError("invalid_options", "Postgres connection could not be established.");
783
+ }
784
+ return createPostgresPersistenceWithClient(client);
536
785
  }
537
786
  export function createPostgresPersistenceWithClient(client) {
538
787
  if (client === null || typeof client !== "object" || typeof client.query !== "function" || typeof client.end !== "function") {
package/dist/sqlite.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { type PersistenceStore } from "./index";
1
+ import { type PersistenceStore } from "./index.js";
2
2
  export interface SqlitePersistenceOptions {
3
3
  readonly filename: string;
4
4
  readonly readonly?: boolean;
package/dist/sqlite.js CHANGED
@@ -39,7 +39,7 @@ class SqlitePersistenceStore {
39
39
  applied.push(migration.id);
40
40
  } catch (cause) {
41
41
  this.#database.exec("ROLLBACK");
42
- throw new PersistenceError("migration_failed", "SQLite migration failed.", { cause });
42
+ throw new PersistenceError("migration_failed", "SQLite migration failed.");
43
43
  }
44
44
  }
45
45
  return Object.freeze({
@@ -71,23 +71,81 @@ class SqlitePersistenceStore {
71
71
  const message = cause instanceof Error ? cause.message : String(cause);
72
72
  if (/UNIQUE|constraint/i.test(message))
73
73
  return "duplicate";
74
- throw new PersistenceError("migration_failed", "SQLite webhook event record failed.", { cause });
74
+ throw new PersistenceError("migration_failed", "SQLite webhook event record failed.");
75
75
  }
76
76
  }
77
77
  async getServiceRequest(input) {
78
78
  this.#assertOpen();
79
79
  const lookup = validateServiceRequestLookup(input);
80
- const row = this.#database.query("SELECT request_hash, response_json FROM wats_service_requests WHERE idempotency_key = ?").get(lookup.idempotencyKey);
80
+ const row = this.#database.query("SELECT request_hash, response_json, status FROM wats_service_requests WHERE idempotency_key = ?").get(lookup.idempotencyKey);
81
81
  if (row === null)
82
82
  return null;
83
83
  if (row.request_hash !== lookup.requestHash)
84
84
  return "conflict";
85
+ if (row.status === "claimed" || row.response_json === null)
86
+ return null;
85
87
  return Object.freeze({ responseJson: row.response_json });
86
88
  }
87
89
  async recordServiceRequest(input) {
88
90
  this.#assertOpen();
89
91
  const record = validateServiceRequestRecord(input);
90
- this.#database.run("INSERT OR IGNORE INTO wats_service_requests (idempotency_key, request_hash, response_json, created_at) VALUES (?, ?, ?, ?)", record.idempotencyKey, record.requestHash, record.responseJson, record.createdAt);
92
+ try {
93
+ this.#database.run("INSERT OR IGNORE INTO wats_service_requests (idempotency_key, request_hash, response_json, created_at, status) VALUES (?, ?, ?, ?, 'completed')", record.idempotencyKey, record.requestHash, record.responseJson, record.createdAt);
94
+ } catch (cause) {
95
+ throw new PersistenceError("outbox_failed", "SQLite service request record failed.");
96
+ }
97
+ }
98
+ async claimServiceRequest(input) {
99
+ this.#assertOpen();
100
+ const claim = validateServiceRequestClaim(input);
101
+ let insert;
102
+ let row;
103
+ try {
104
+ insert = this.#database.run("INSERT OR IGNORE INTO wats_service_requests (idempotency_key, request_hash, response_json, created_at, claimed_at, status) VALUES (?, ?, NULL, ?, ?, 'claimed')", claim.idempotencyKey, claim.requestHash, claim.createdAt, claim.createdAt);
105
+ if (insert.changes === 1)
106
+ return "claimed";
107
+ row = this.#database.query("SELECT request_hash, response_json, status FROM wats_service_requests WHERE idempotency_key = ?").get(claim.idempotencyKey);
108
+ } catch (cause) {
109
+ if (cause instanceof PersistenceError)
110
+ throw cause;
111
+ throw new PersistenceError("claim_failed", "SQLite service request claim failed.");
112
+ }
113
+ if (row === null) {
114
+ throw new PersistenceError("claim_failed", "SQLite service request claim did not persist.");
115
+ }
116
+ if (row.request_hash !== claim.requestHash)
117
+ return "conflict";
118
+ if (row.status === "completed" && row.response_json !== null) {
119
+ return Object.freeze({ responseJson: row.response_json });
120
+ }
121
+ return "pending";
122
+ }
123
+ async completeServiceRequest(input) {
124
+ this.#assertOpen();
125
+ const completion = validateServiceRequestCompletion(input);
126
+ let existing;
127
+ try {
128
+ existing = this.#database.query("SELECT request_hash, status FROM wats_service_requests WHERE idempotency_key = ?").get(completion.idempotencyKey);
129
+ } catch (cause) {
130
+ throw new PersistenceError("completion_failed", "SQLite service request completion failed.");
131
+ }
132
+ if (existing === null) {
133
+ throw new PersistenceError("completion_failed", "SQLite service request completion requires a prior claim.");
134
+ }
135
+ if (existing.request_hash !== completion.requestHash) {
136
+ throw new PersistenceError("completion_failed", "SQLite service request completion hash mismatch.");
137
+ }
138
+ if (existing.status === "completed")
139
+ return;
140
+ let result;
141
+ try {
142
+ result = this.#database.run("UPDATE wats_service_requests SET response_json = ?, status = 'completed', created_at = ? WHERE idempotency_key = ? AND request_hash = ? AND status = 'claimed'", completion.responseJson, completion.createdAt, completion.idempotencyKey, completion.requestHash);
143
+ } catch (cause) {
144
+ throw new PersistenceError("completion_failed", "SQLite service request completion failed.");
145
+ }
146
+ if (result.changes !== 1) {
147
+ throw new PersistenceError("completion_failed", "SQLite service request completion lease is stale.");
148
+ }
91
149
  }
92
150
  async enqueueOutboxItem(input) {
93
151
  this.#assertOpen();
@@ -99,7 +157,7 @@ class SqlitePersistenceStore {
99
157
  const message = cause instanceof Error ? cause.message : String(cause);
100
158
  if (/UNIQUE|constraint/i.test(message))
101
159
  return "duplicate";
102
- throw new PersistenceError("outbox_failed", "SQLite outbox enqueue failed.", { cause });
160
+ throw new PersistenceError("outbox_failed", "SQLite outbox enqueue failed.");
103
161
  }
104
162
  }
105
163
  async claimOutboxItems(input) {
@@ -124,13 +182,18 @@ class SqlitePersistenceStore {
124
182
  return Object.freeze(rows.map((row) => outboxRowToItem({ ...row, status: "processing", attempts: row.attempts + 1, lease_id: row.lease_id + 1, next_attempt_at: null, updated_at: claim.now })));
125
183
  } catch (cause) {
126
184
  this.#database.exec("ROLLBACK");
127
- throw new PersistenceError("outbox_failed", "SQLite outbox claim failed.", { cause });
185
+ throw new PersistenceError("outbox_failed", "SQLite outbox claim failed.");
128
186
  }
129
187
  }
130
188
  async markOutboxItemFailed(input) {
131
189
  this.#assertOpen();
132
190
  const failure = validateOutboxFailed(input);
133
- const result = this.#database.run("UPDATE wats_outbox SET status = ?, next_attempt_at = ?, updated_at = ? WHERE id = ? AND status = ? AND lease_id = ?", "pending", failure.nextAttemptAt, failure.updatedAt, failure.id, "processing", failure.leaseId);
191
+ let result;
192
+ try {
193
+ result = this.#database.run("UPDATE wats_outbox SET status = ?, next_attempt_at = ?, updated_at = ? WHERE id = ? AND status = ? AND lease_id = ?", "pending", failure.nextAttemptAt, failure.updatedAt, failure.id, "processing", failure.leaseId);
194
+ } catch (cause) {
195
+ throw new PersistenceError("outbox_failed", "SQLite outbox failure failed.");
196
+ }
134
197
  if (result.changes !== 1) {
135
198
  throw new PersistenceError("outbox_failed", "SQLite outbox failure lease is stale.");
136
199
  }
@@ -138,7 +201,12 @@ class SqlitePersistenceStore {
138
201
  async markOutboxItemSucceeded(input) {
139
202
  this.#assertOpen();
140
203
  const success = validateOutboxSucceeded(input);
141
- const result = this.#database.run("UPDATE wats_outbox SET status = ?, next_attempt_at = NULL, updated_at = ? WHERE id = ? AND status = ? AND lease_id = ?", "succeeded", success.updatedAt, success.id, "processing", success.leaseId);
204
+ let result;
205
+ try {
206
+ result = this.#database.run("UPDATE wats_outbox SET status = ?, next_attempt_at = NULL, updated_at = ? WHERE id = ? AND status = ? AND lease_id = ?", "succeeded", success.updatedAt, success.id, "processing", success.leaseId);
207
+ } catch (cause) {
208
+ throw new PersistenceError("outbox_failed", "SQLite outbox success failed.");
209
+ }
142
210
  if (result.changes !== 1) {
143
211
  throw new PersistenceError("outbox_failed", "SQLite outbox success lease is stale.");
144
212
  }
@@ -146,21 +214,47 @@ class SqlitePersistenceStore {
146
214
  async recordMessage(input) {
147
215
  this.#assertOpen();
148
216
  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);
217
+ try {
218
+ this.#database.run(`INSERT OR IGNORE INTO wats_messages
219
+ (row_id, wa_message_id, direction, from_phone, to_phone, type, status, graph_message_id, created_at, updated_at)
220
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, record.rowId, record.waMessageId, record.direction, record.fromPhone, record.toPhone, record.type, record.status, record.graphMessageId, record.createdAt, record.updatedAt);
221
+ } catch (cause) {
222
+ throw new PersistenceError("outbox_failed", "SQLite message record failed.");
223
+ }
224
+ this.#reconcileStoredStatus(record.waMessageId, record.status, record.updatedAt);
225
+ }
226
+ #reconcileStoredStatus(waMessageId, recordedStatus, recordedUpdatedAt) {
227
+ const events = this.#database.query("SELECT status, timestamp FROM wats_message_status_events WHERE wa_message_id = ? ORDER BY timestamp ASC").all(waMessageId);
228
+ if (events.length === 0)
229
+ return;
230
+ let bestStatus = recordedStatus;
231
+ let bestUpdatedAt = recordedUpdatedAt;
232
+ for (const ev of events) {
233
+ if (shouldAdvanceStatus(ev.status, bestStatus)) {
234
+ bestStatus = ev.status;
235
+ if (ev.timestamp > bestUpdatedAt)
236
+ bestUpdatedAt = ev.timestamp;
237
+ }
238
+ }
239
+ if (bestStatus !== recordedStatus || bestUpdatedAt !== recordedUpdatedAt) {
240
+ this.#database.run("UPDATE wats_messages SET status = ?, updated_at = ? WHERE wa_message_id = ?", bestStatus, bestUpdatedAt, waMessageId);
241
+ }
152
242
  }
153
243
  async appendMessageStatus(input) {
154
244
  this.#assertOpen();
155
245
  const event = validateMessageStatusEvent(input);
156
246
  this.#database.exec("BEGIN IMMEDIATE");
157
247
  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);
248
+ this.#database.run("INSERT OR IGNORE INTO wats_message_status_events (wa_message_id, status, timestamp) VALUES (?, ?, ?)", event.waMessageId, event.status, event.timestamp);
249
+ const current = this.#database.query("SELECT status, updated_at FROM wats_messages WHERE wa_message_id = ?").get(event.waMessageId);
250
+ if (current !== null && shouldAdvanceStatus(event.status, current.status)) {
251
+ const newUpdatedAt = event.timestamp > current.updated_at ? event.timestamp : current.updated_at;
252
+ this.#database.run("UPDATE wats_messages SET status = ?, updated_at = ? WHERE wa_message_id = ?", event.status, newUpdatedAt, event.waMessageId);
253
+ }
160
254
  this.#database.exec("COMMIT");
161
255
  } catch (cause) {
162
256
  this.#database.exec("ROLLBACK");
163
- throw new PersistenceError("invalid_record", "SQLite message status append failed.", { cause });
257
+ throw new PersistenceError("outbox_failed", "SQLite message status append failed.");
164
258
  }
165
259
  }
166
260
  async getMessage(input) {
@@ -231,7 +325,7 @@ class SqlitePersistenceStore {
231
325
  try {
232
326
  this.#database.run("INSERT INTO wats_persistence_lock (id, holder, acquired_at) VALUES (?, ?, ?)", MIGRATION_LOCK_ID, holder, nowIso());
233
327
  } catch (cause) {
234
- throw new PersistenceError("migration_lock_failed", "SQLite migration lock is already held.", { cause });
328
+ throw new PersistenceError("migration_lock_failed", "SQLite migration lock is already held.");
235
329
  }
236
330
  }
237
331
  #releaseLock(holder) {
@@ -256,11 +350,30 @@ import {
256
350
  CURRENT_SCHEMA_VERSION,
257
351
  PersistenceError,
258
352
  REDACTED_SQLITE_LOCATION
259
- } from "./index";
353
+ } from "./index.js";
354
+ import { containsUnsafePathSegment } from "@wats/internal-utils";
260
355
  const SQLITE_MEMORY = ":memory:";
261
356
  const MAX_FILENAME_LENGTH = 4096;
262
357
  const MIGRATION_LOCK_ID = 1;
263
358
  const OUTBOX_PROCESSING_LEASE_MS = 300000;
359
+ const STATUS_RANK = Object.freeze({
360
+ pending: 0,
361
+ sent: 1,
362
+ delivered: 2,
363
+ read: 3,
364
+ failed: 1
365
+ });
366
+ function statusRank(status) {
367
+ return STATUS_RANK[status] ?? 0;
368
+ }
369
+ function failedMayReplace(currentStatus) {
370
+ return statusRank(currentStatus) <= 1;
371
+ }
372
+ function shouldAdvanceStatus(newStatus, currentStatus) {
373
+ if (newStatus === "failed")
374
+ return failedMayReplace(currentStatus);
375
+ return statusRank(newStatus) > statusRank(currentStatus);
376
+ }
264
377
  const MIGRATIONS = Object.freeze([
265
378
  {
266
379
  id: "001_initial",
@@ -344,6 +457,67 @@ const MIGRATIONS = Object.freeze([
344
457
  `CREATE INDEX IF NOT EXISTS wats_messages_direction_from_phone_created_at_idx
345
458
  ON wats_messages (direction, from_phone, created_at DESC)`
346
459
  ])
460
+ },
461
+ {
462
+ id: "005_service_request_claims",
463
+ version: 5,
464
+ checksum: "sha256:wats-persistence-005-service-request-claims-v1",
465
+ statements: Object.freeze([
466
+ `CREATE TABLE wats_service_requests_new (
467
+ idempotency_key TEXT PRIMARY KEY,
468
+ request_hash TEXT NOT NULL,
469
+ response_json TEXT,
470
+ created_at TEXT NOT NULL,
471
+ status TEXT NOT NULL DEFAULT 'completed',
472
+ claimed_at TEXT
473
+ )`,
474
+ `INSERT INTO wats_service_requests_new (idempotency_key, request_hash, response_json, created_at, status)
475
+ SELECT idempotency_key, request_hash, response_json, created_at, 'completed'
476
+ FROM wats_service_requests`,
477
+ `DROP TABLE wats_service_requests`,
478
+ `ALTER TABLE wats_service_requests_new RENAME TO wats_service_requests`
479
+ ])
480
+ },
481
+ {
482
+ id: "006_message_uniqueness",
483
+ version: 6,
484
+ checksum: "sha256:wats-persistence-006-message-uniqueness-v1",
485
+ statements: Object.freeze([
486
+ `DELETE FROM wats_message_status_events
487
+ WHERE id IN (
488
+ SELECT id FROM (
489
+ SELECT id,
490
+ ROW_NUMBER() OVER (
491
+ PARTITION BY wa_message_id, status, timestamp
492
+ ORDER BY id ASC
493
+ ) AS rn
494
+ FROM wats_message_status_events
495
+ ) WHERE rn > 1
496
+ )`,
497
+ `DELETE FROM wats_messages
498
+ WHERE row_id IN (
499
+ SELECT row_id FROM (
500
+ SELECT row_id,
501
+ ROW_NUMBER() OVER (
502
+ PARTITION BY direction, wa_message_id
503
+ ORDER BY
504
+ CASE status
505
+ WHEN 'read' THEN 4
506
+ WHEN 'delivered' THEN 3
507
+ WHEN 'sent' THEN 2
508
+ WHEN 'pending' THEN 1
509
+ ELSE 0
510
+ END DESC,
511
+ row_id ASC
512
+ ) AS rn
513
+ FROM wats_messages
514
+ ) WHERE rn > 1
515
+ )`,
516
+ `CREATE UNIQUE INDEX IF NOT EXISTS wats_messages_direction_wa_message_id_uidx
517
+ ON wats_messages (direction, wa_message_id)`,
518
+ `CREATE UNIQUE INDEX IF NOT EXISTS wats_message_status_events_wa_message_id_status_timestamp_uidx
519
+ ON wats_message_status_events (wa_message_id, status, timestamp)`
520
+ ])
347
521
  }
348
522
  ]);
349
523
  function hasControlChars(value) {
@@ -352,10 +526,6 @@ function hasControlChars(value) {
352
526
  return code < 32 || code === 127;
353
527
  });
354
528
  }
355
- function containsUnsafePathSegment(value) {
356
- const lower = value.toLowerCase();
357
- return value.includes("\\") || value.includes("?") || value.includes("#") || value.includes(":") || value.split("/").some((segment) => segment === ".." || segment === ".") || lower.includes("%2e%2e") || lower.includes("%252e%252e") || lower.includes("%2f") || lower.includes("%252f") || lower.includes("%5c") || lower.includes("%255c");
358
- }
359
529
  function looksTokenLike(value) {
360
530
  const lower = value.toLowerCase();
361
531
  return /(?:^|[^a-z])(token|secret|passwd|password|bearer|authorization|access[_-]?token)(?:[^a-z]|$)/u.test(lower);
@@ -435,7 +605,30 @@ function validateServiceRequestRecord(input) {
435
605
  try {
436
606
  JSON.parse(responseJson);
437
607
  } catch (cause) {
438
- throw new PersistenceError("invalid_record", "responseJson must be valid JSON.", { cause });
608
+ throw new PersistenceError("invalid_record", "responseJson must be valid JSON.");
609
+ }
610
+ return Object.freeze({
611
+ idempotencyKey: validateRecordString(record.idempotencyKey, "idempotencyKey"),
612
+ requestHash: validateRecordString(record.requestHash, "requestHash"),
613
+ responseJson,
614
+ createdAt: validateTimestamp(record.createdAt, "createdAt")
615
+ });
616
+ }
617
+ function validateServiceRequestClaim(input) {
618
+ const record = validateRecordInput(input, "service request claim");
619
+ return Object.freeze({
620
+ idempotencyKey: validateRecordString(record.idempotencyKey, "idempotencyKey"),
621
+ requestHash: validateRecordString(record.requestHash, "requestHash"),
622
+ createdAt: validateTimestamp(record.createdAt, "createdAt")
623
+ });
624
+ }
625
+ function validateServiceRequestCompletion(input) {
626
+ const record = validateRecordInput(input, "service request completion");
627
+ const responseJson = validateRecordString(record.responseJson, "responseJson");
628
+ try {
629
+ JSON.parse(responseJson);
630
+ } catch (cause) {
631
+ throw new PersistenceError("invalid_record", "responseJson must be valid JSON.");
439
632
  }
440
633
  return Object.freeze({
441
634
  idempotencyKey: validateRecordString(record.idempotencyKey, "idempotencyKey"),
@@ -574,7 +767,7 @@ async function loadBunSqlite() {
574
767
  const specifier = "bun:sqlite";
575
768
  return await import("bun:sqlite");
576
769
  } catch (cause) {
577
- throw new PersistenceError("migration_failed", "SQLite persistence requires Bun sqlite support.", { cause });
770
+ throw new PersistenceError("migration_failed", "SQLite persistence requires Bun sqlite support.");
578
771
  }
579
772
  }
580
773
  export async function createSqlitePersistence(options) {
@@ -584,6 +777,6 @@ export async function createSqlitePersistence(options) {
584
777
  const database = new sqlite.Database(filename, { readonly, create: !readonly });
585
778
  return new SqlitePersistenceStore(database);
586
779
  } catch (cause) {
587
- throw new PersistenceError("migration_failed", "SQLite database could not be opened.", { cause });
780
+ throw new PersistenceError("migration_failed", "SQLite database could not be opened.");
588
781
  }
589
782
  }
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "@wats/persistence",
3
- "version": "0.3.30",
3
+ "description": "Experimental persistence contracts + SQLite and Postgres adapters.",
4
+ "version": "0.5.0-beta",
4
5
  "private": false,
5
6
  "license": "MIT",
6
7
  "type": "module",
@@ -51,5 +52,8 @@
51
52
  "pg": {
52
53
  "optional": true
53
54
  }
55
+ },
56
+ "dependencies": {
57
+ "@wats/internal-utils": "^0.5.0-beta"
54
58
  }
55
59
  }