@terreno/api 0.30.0 → 56.0.0-beta.0

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.
Files changed (226) hide show
  1. package/dist/api.d.ts +10 -0
  2. package/dist/api.js +110 -361
  3. package/dist/auth.d.ts +26 -0
  4. package/dist/auth.js +100 -1
  5. package/dist/betterAuth.d.ts +5 -0
  6. package/dist/betterAuthSetup.js +23 -4
  7. package/dist/docLoader.js +12 -9
  8. package/dist/errors.d.ts +13 -0
  9. package/dist/errors.js +29 -1
  10. package/dist/index.d.ts +17 -1
  11. package/dist/index.js +29 -1
  12. package/dist/middleware.d.ts +7 -0
  13. package/dist/middleware.js +16 -1
  14. package/dist/openApiCompat.d.ts +10 -1
  15. package/dist/openApiCompat.js +115 -47
  16. package/dist/permissions.d.ts +27 -0
  17. package/dist/permissions.js +42 -1
  18. package/dist/plugins.d.ts +13 -0
  19. package/dist/plugins.js +35 -1
  20. package/dist/realtime/changeStreamWatcher.d.ts +100 -3
  21. package/dist/realtime/changeStreamWatcher.js +542 -137
  22. package/dist/realtime/realtimeApp.d.ts +2 -0
  23. package/dist/realtime/realtimeApp.js +73 -21
  24. package/dist/realtime/sessionRevalidation.d.ts +90 -0
  25. package/dist/realtime/sessionRevalidation.js +438 -0
  26. package/dist/realtime/socketAuth.d.ts +97 -0
  27. package/dist/realtime/socketAuth.js +272 -0
  28. package/dist/realtime/socketUser.d.ts +54 -0
  29. package/dist/realtime/socketUser.js +75 -5
  30. package/dist/realtime/types.d.ts +40 -0
  31. package/dist/secretProviders.d.ts +23 -0
  32. package/dist/secretProviders.js +9 -3
  33. package/dist/sync/executors.d.ts +198 -0
  34. package/dist/sync/executors.js +670 -0
  35. package/dist/sync/loadHarness.js +807 -0
  36. package/dist/sync/models.d.ts +216 -0
  37. package/dist/sync/models.js +644 -0
  38. package/dist/sync/mutationHandler.d.ts +97 -0
  39. package/dist/sync/mutationHandler.js +886 -0
  40. package/dist/sync/registry.d.ts +73 -0
  41. package/dist/sync/registry.js +223 -0
  42. package/dist/sync/routes.d.ts +62 -0
  43. package/dist/sync/routes.js +936 -0
  44. package/dist/sync/scripts/compactTombstones.d.ts +47 -0
  45. package/dist/sync/scripts/compactTombstones.js +270 -0
  46. package/dist/sync/serialize.d.ts +20 -0
  47. package/dist/{tests/bunSetup.js → sync/serialize.js} +35 -68
  48. package/dist/sync/socketHandlers.d.ts +54 -0
  49. package/dist/sync/socketHandlers.js +470 -0
  50. package/dist/sync/streams.d.ts +85 -0
  51. package/dist/sync/streams.js +221 -0
  52. package/dist/sync/syncApp.d.ts +29 -0
  53. package/dist/sync/syncApp.js +44 -0
  54. package/dist/sync/syncBatch.d.ts +71 -0
  55. package/dist/sync/syncBatch.js +252 -0
  56. package/dist/sync/syncSeqPlugin.d.ts +8 -0
  57. package/dist/sync/syncSeqPlugin.js +903 -0
  58. package/dist/sync/types.d.ts +254 -0
  59. package/dist/sync/types.js +9 -0
  60. package/dist/terrenoApp.js +90 -27
  61. package/dist/vendor/wesleytodd-openapi/index.d.ts +1 -1
  62. package/dist/vendor/wesleytodd-openapi/lib/ui.d.ts +2 -1
  63. package/package.json +7 -6
  64. package/src/__tests__/openApiCompat.test.ts +20 -0
  65. package/src/actions.openApi.test.ts +7 -10
  66. package/src/api.test.ts +12 -0
  67. package/src/api.ts +87 -295
  68. package/src/auth.test.ts +128 -176
  69. package/src/auth.ts +109 -0
  70. package/src/betterAuth.ts +6 -0
  71. package/src/betterAuthSetup.test.ts +34 -0
  72. package/src/betterAuthSetup.ts +20 -1
  73. package/src/docLoader.ts +3 -1
  74. package/src/errors.ts +33 -0
  75. package/src/expressServer.test.ts +7 -1
  76. package/src/index.ts +42 -0
  77. package/src/middleware.test.ts +40 -1
  78. package/src/middleware.ts +15 -0
  79. package/src/openApiCompat.ts +99 -45
  80. package/src/permissions.test.ts +75 -1
  81. package/src/permissions.ts +49 -0
  82. package/src/plugins.test.ts +54 -0
  83. package/src/plugins.ts +43 -0
  84. package/src/realtime/changeStreamWatcher.ts +552 -114
  85. package/src/realtime/realtime.test.ts +157 -0
  86. package/src/realtime/realtimeApp.ts +75 -11
  87. package/src/realtime/sessionRevalidation.test.ts +423 -0
  88. package/src/realtime/sessionRevalidation.ts +273 -0
  89. package/src/realtime/socketAuth.test.ts +355 -0
  90. package/src/realtime/socketAuth.ts +228 -0
  91. package/src/realtime/socketUser.ts +69 -0
  92. package/src/realtime/types.ts +40 -0
  93. package/src/secretProviders.test.ts +7 -1
  94. package/src/secretProviders.ts +15 -3
  95. package/src/sync/ensureSyncIndexes.test.ts +144 -0
  96. package/src/sync/executors.test.ts +882 -0
  97. package/src/sync/executors.ts +703 -0
  98. package/src/sync/integration.test.ts +1160 -0
  99. package/src/sync/loadHarness.ts +618 -0
  100. package/src/sync/models.ts +640 -0
  101. package/src/sync/mutationHandler.test.ts +1252 -0
  102. package/src/sync/mutationHandler.ts +850 -0
  103. package/src/sync/registry.ts +232 -0
  104. package/src/sync/routes.ts +812 -0
  105. package/src/sync/scripts/compactTombstones.test.ts +249 -0
  106. package/src/sync/scripts/compactTombstones.ts +145 -0
  107. package/src/sync/serialize.ts +48 -0
  108. package/src/sync/sessionRevalidationIntegration.test.ts +281 -0
  109. package/src/sync/socketHandlers.ts +320 -0
  110. package/src/sync/streams.ts +188 -0
  111. package/src/sync/sync.test.ts +582 -0
  112. package/src/sync/syncApp.ts +44 -0
  113. package/src/sync/syncBatch.ts +219 -0
  114. package/src/sync/syncFrontier.test.ts +494 -0
  115. package/src/sync/syncPhaseC.test.ts +718 -0
  116. package/src/sync/syncRoutes.test.ts +865 -0
  117. package/src/sync/syncSeqPlugin.ts +738 -0
  118. package/src/sync/syncSocket.test.ts +1440 -0
  119. package/src/sync/types.ts +270 -0
  120. package/src/terrenoApp.ts +37 -17
  121. package/src/tests/bunSetup.ts +8 -0
  122. package/tsconfig.json +4 -4
  123. package/tsconfig.typedoc.json +7 -1
  124. package/dist/__tests__/openApiCompat.test.js +0 -317
  125. package/dist/__tests__/versionCheckPlugin.test.d.ts +0 -1
  126. package/dist/__tests__/versionCheckPlugin.test.js +0 -597
  127. package/dist/actions.openApi.test.d.ts +0 -1
  128. package/dist/actions.openApi.test.js +0 -255
  129. package/dist/actions.test.d.ts +0 -1
  130. package/dist/actions.test.js +0 -1089
  131. package/dist/api.arrayOperations.test.d.ts +0 -1
  132. package/dist/api.arrayOperations.test.js +0 -878
  133. package/dist/api.asyncHandler.test.d.ts +0 -1
  134. package/dist/api.asyncHandler.test.js +0 -236
  135. package/dist/api.coverage.test.d.ts +0 -1
  136. package/dist/api.coverage.test.js +0 -194
  137. package/dist/api.errorPaths.test.d.ts +0 -1
  138. package/dist/api.errorPaths.test.js +0 -801
  139. package/dist/api.errors.test.d.ts +0 -1
  140. package/dist/api.errors.test.js +0 -185
  141. package/dist/api.hooks.test.d.ts +0 -1
  142. package/dist/api.hooks.test.js +0 -950
  143. package/dist/api.query.test.d.ts +0 -1
  144. package/dist/api.query.test.js +0 -948
  145. package/dist/api.test.d.ts +0 -1
  146. package/dist/api.test.js +0 -2820
  147. package/dist/auth.compile.test.d.ts +0 -1
  148. package/dist/auth.compile.test.js +0 -201
  149. package/dist/auth.coverage.test.d.ts +0 -1
  150. package/dist/auth.coverage.test.js +0 -202
  151. package/dist/auth.test.d.ts +0 -1
  152. package/dist/auth.test.js +0 -2286
  153. package/dist/betterAuth.test.d.ts +0 -1
  154. package/dist/betterAuth.test.js +0 -181
  155. package/dist/betterAuthApp.test.d.ts +0 -1
  156. package/dist/betterAuthApp.test.js +0 -242
  157. package/dist/betterAuthSetup.test.d.ts +0 -1
  158. package/dist/betterAuthSetup.test.js +0 -762
  159. package/dist/config.test.d.ts +0 -1
  160. package/dist/config.test.js +0 -353
  161. package/dist/configuration.test.d.ts +0 -1
  162. package/dist/configuration.test.js +0 -980
  163. package/dist/configurationPlugin.test.d.ts +0 -1
  164. package/dist/configurationPlugin.test.js +0 -827
  165. package/dist/consentApp.test.d.ts +0 -1
  166. package/dist/consentApp.test.js +0 -1415
  167. package/dist/docLoader.test.d.ts +0 -1
  168. package/dist/docLoader.test.js +0 -137
  169. package/dist/envConfigurationPlugin.test.d.ts +0 -1
  170. package/dist/envConfigurationPlugin.test.js +0 -369
  171. package/dist/errors.test.d.ts +0 -1
  172. package/dist/errors.test.js +0 -607
  173. package/dist/expressServer.test.d.ts +0 -1
  174. package/dist/expressServer.test.js +0 -1249
  175. package/dist/githubAuth.test.d.ts +0 -1
  176. package/dist/githubAuth.test.js +0 -1142
  177. package/dist/httpClient.test.d.ts +0 -1
  178. package/dist/httpClient.test.js +0 -1471
  179. package/dist/logger.test.d.ts +0 -1
  180. package/dist/logger.test.js +0 -685
  181. package/dist/middleware.test.d.ts +0 -1
  182. package/dist/middleware.test.js +0 -241
  183. package/dist/notifiers/googleChatNotifier.test.d.ts +0 -1
  184. package/dist/notifiers/googleChatNotifier.test.js +0 -298
  185. package/dist/notifiers/slackNotifier.test.d.ts +0 -1
  186. package/dist/notifiers/slackNotifier.test.js +0 -297
  187. package/dist/notifiers/zoomNotifier.test.d.ts +0 -1
  188. package/dist/notifiers/zoomNotifier.test.js +0 -373
  189. package/dist/openApi.test.d.ts +0 -1
  190. package/dist/openApi.test.js +0 -620
  191. package/dist/openApiBuilder.test.d.ts +0 -1
  192. package/dist/openApiBuilder.test.js +0 -601
  193. package/dist/openApiEtag.test.d.ts +0 -1
  194. package/dist/openApiEtag.test.js +0 -86
  195. package/dist/openApiValidator.test.d.ts +0 -1
  196. package/dist/openApiValidator.test.js +0 -761
  197. package/dist/permissions.middleware.test.d.ts +0 -1
  198. package/dist/permissions.middleware.test.js +0 -308
  199. package/dist/permissions.test.d.ts +0 -1
  200. package/dist/permissions.test.js +0 -439
  201. package/dist/plugins.test.d.ts +0 -1
  202. package/dist/plugins.test.js +0 -890
  203. package/dist/populate.test.d.ts +0 -1
  204. package/dist/populate.test.js +0 -373
  205. package/dist/realtime/realtime.test.d.ts +0 -10
  206. package/dist/realtime/realtime.test.js +0 -3982
  207. package/dist/requestContext.test.d.ts +0 -1
  208. package/dist/requestContext.test.js +0 -412
  209. package/dist/scriptRunner.test.d.ts +0 -1
  210. package/dist/scriptRunner.test.js +0 -386
  211. package/dist/secretProviders.test.d.ts +0 -1
  212. package/dist/secretProviders.test.js +0 -726
  213. package/dist/syncConsents.test.d.ts +0 -1
  214. package/dist/syncConsents.test.js +0 -522
  215. package/dist/terrenoApp.test.d.ts +0 -1
  216. package/dist/terrenoApp.test.js +0 -489
  217. package/dist/tests/bunSetup.d.ts +0 -1
  218. package/dist/tests/fixtures/compileAuthEntry.d.ts +0 -1
  219. package/dist/tests/fixtures/compileAuthEntry.js +0 -37
  220. package/dist/tests/testEnv.d.ts +0 -0
  221. package/dist/tests/testEnv.js +0 -6
  222. package/dist/transformers.test.d.ts +0 -1
  223. package/dist/transformers.test.js +0 -423
  224. package/dist/utils.test.d.ts +0 -1
  225. package/dist/utils.test.js +0 -242
  226. /package/dist/{__tests__/openApiCompat.test.d.ts → sync/loadHarness.d.ts} +0 -0
@@ -0,0 +1,254 @@
1
+ /**
2
+ * Shared types for the SyncDB local-first sync protocol.
3
+ *
4
+ * These types are the contract between @terreno/api (server) and @terreno/syncdb (client):
5
+ * scope/stream configuration, snapshot payloads, mutation requests, and delta events.
6
+ * See docs/implementationPlans/syncdb-local-first.md.
7
+ */
8
+ /** Scope a collection's streams by document owner (default field: `ownerId`). */
9
+ export interface SyncScopeOwner {
10
+ type: "owner";
11
+ /** Field holding the owning user's id. Defaults to "ownerId". */
12
+ field?: string;
13
+ }
14
+ /** Scope a collection's streams by a tenant/workspace field (e.g. `organizationId`). */
15
+ export interface SyncScopeTenant {
16
+ type: "tenant";
17
+ /** Field holding the tenant/workspace id. */
18
+ field: string;
19
+ }
20
+ /** A single shared stream for the whole collection (all authenticated users). */
21
+ export interface SyncScopeBroadcast {
22
+ type: "broadcast";
23
+ }
24
+ /**
25
+ * Custom scope resolver: given a document, return its scope value (e.g. a workspace id).
26
+ * The stream key becomes `{collection}|custom:{value}`.
27
+ */
28
+ export type SyncScopeResolver = (doc: Record<string, unknown>) => string;
29
+ export type SyncScope = SyncScopeOwner | SyncScopeTenant | SyncScopeBroadcast | SyncScopeResolver;
30
+ /**
31
+ * Configuration for local-first sync on a modelRouter, parallel to `realtime`.
32
+ * Requires the model schema to use `isDeletedPlugin` (soft delete) and `syncPlugin`
33
+ * (seq stamping) — validated at registration.
34
+ */
35
+ export interface SyncConfig {
36
+ /** Which stream a document belongs to. Multi-tenant by default via the tenant scope. */
37
+ scope: SyncScope;
38
+ /**
39
+ * Custom serializer for sync payloads (snapshot entities and deltas).
40
+ * Falls back to the modelRouter responseHandler, then the document's toJSON.
41
+ */
42
+ responseHandler?: (doc: Record<string, unknown>, method: SyncMutationOperation) => unknown;
43
+ /**
44
+ * Server-side query restricting snapshots to the caller's documents. Derived
45
+ * automatically for owner scopes ({field: user.id}) and tenant scopes
46
+ * ({field: {$in: getUserScopes(...)}}); REQUIRED for custom resolver scopes, whose
47
+ * stream function cannot be inverted into a Mongo query.
48
+ */
49
+ snapshotFilter?: (user: {
50
+ id: string;
51
+ }) => Record<string, unknown> | Promise<Record<string, unknown>>;
52
+ /**
53
+ * C7: tombstone retention window in days (default 90). Tombstones older than this may
54
+ * be hard-deleted by the `compactTombstones` maintenance script; a client whose cursor
55
+ * predates the retained floor re-bootstraps (see `oldestRetainedSeq`).
56
+ */
57
+ retentionDays?: number;
58
+ }
59
+ export type SyncMutationOperation = "create" | "update" | "delete";
60
+ /** A single entity in a snapshot response. */
61
+ export interface SyncEntityPayload {
62
+ /** Document id. */
63
+ id: string;
64
+ /** Serialized document data (present for tombstones too, so clients can render conflicts). */
65
+ data: unknown;
66
+ /** The document's `_syncSeq` — the client's per-entity version and cursor source. */
67
+ seq: number;
68
+ /** True when the entity is a soft-delete tombstone. */
69
+ deleted: boolean;
70
+ }
71
+ /**
72
+ * Response shape for `GET /sync/snapshot` (C2: one stream per request).
73
+ */
74
+ export interface SyncSnapshotResponse {
75
+ /** The stream this page belongs to (echoed from the request). */
76
+ stream: string;
77
+ entities: SyncEntityPayload[];
78
+ /**
79
+ * Highest seq included in this page (C1: never above `frontierSeq`); pass back as
80
+ * `cursor` to continue.
81
+ */
82
+ cursor: number;
83
+ /** True when more pages remain past `cursor` (more committed OR uncommitted seqs). */
84
+ hasMore: boolean;
85
+ /** C1: the stream's stable frontier — the client must not advance its cursor beyond this. */
86
+ frontierSeq: number;
87
+ /**
88
+ * C7: the lowest seq still retained for this stream after tombstone compaction. A
89
+ * client whose stored cursor is below this may have missed compacted tombstones and
90
+ * must re-bootstrap the stream from 0 (sanctioned wipe: retention gap, not auth).
91
+ */
92
+ oldestRetainedSeq: number;
93
+ /**
94
+ * C3: opaque forward token for paging the legacy (seq-0) stratum by `_id`. Present
95
+ * while unstamped legacy documents remain; absent once the stratum is exhausted and
96
+ * paging proceeds by seq. The client echoes it back verbatim.
97
+ */
98
+ legacyCursor?: string;
99
+ }
100
+ /** Response shape for `GET /sync/entities` (point lookup for repair). */
101
+ export interface SyncEntitiesResponse {
102
+ entities: SyncEntityPayload[];
103
+ }
104
+ /** One stream a user currently belongs to, from `GET /sync/streams`. */
105
+ export interface SyncStreamInfo {
106
+ /** The stream key (e.g. "todos|owner:123"). */
107
+ stream: string;
108
+ /** The collection tag the stream belongs to. */
109
+ collection: string;
110
+ }
111
+ /** Response shape for `GET /sync/streams`. */
112
+ export interface SyncStreamsResponse {
113
+ streams: SyncStreamInfo[];
114
+ }
115
+ /** A client mutation delivered via `sync:mutate` or `POST /sync/mutate`. */
116
+ export interface SyncMutateRequest {
117
+ /** Client-generated stable id; the idempotency key. */
118
+ mutationId: string;
119
+ /** Collection tag (e.g. "todos"). */
120
+ collection: string;
121
+ operation: SyncMutationOperation;
122
+ /** Target document id (required for update/delete; client-generated allowed for create). */
123
+ id?: string;
124
+ /** Fields to write (create/update). */
125
+ data?: Record<string, unknown>;
126
+ /** The `_syncSeq` the client last saw for this document; enables LWW conflict detection. */
127
+ baseVersion?: number;
128
+ }
129
+ /** Successful mutation acknowledgement. */
130
+ export interface SyncAck {
131
+ mutationId: string;
132
+ /** The document id (server-assigned for creates). */
133
+ id: string;
134
+ /** The document's new `_syncSeq`. */
135
+ seq: number;
136
+ /**
137
+ * C5 (FIX 6): set when the document write succeeded and the ledger
138
+ * finalized `applied`, but the model's post-hook (`postCreate`/
139
+ * `postUpdate`/`postDelete`) threw. The mutation is still a full success —
140
+ * this is informational only, never a reason to retry or roll back.
141
+ */
142
+ warning?: string;
143
+ }
144
+ export type SyncNackCode = "conflict" | "unauthorized" | "validation" | "error" | "rate_limited";
145
+ /** Rejected mutation. Conflict nacks carry the canonical server document. */
146
+ export interface SyncNack {
147
+ mutationId: string;
148
+ code: SyncNackCode;
149
+ /** Canonical serialized server document (conflict nacks). */
150
+ serverDoc?: unknown;
151
+ /** The server document's current `_syncSeq` (conflict nacks). */
152
+ serverSeq?: number;
153
+ message?: string;
154
+ /**
155
+ * Minimum time (ms) the client should wait before retrying, filled by the
156
+ * server with the remaining rate-limit window (`rate_limited` nacks only).
157
+ */
158
+ retryAfterMs?: number;
159
+ }
160
+ /**
161
+ * A batch of client mutations delivered via `sync:mutateBatch` or
162
+ * `POST /sync/mutate/batch`. The server MUST apply strictly in array order and
163
+ * stop at the first non-ack outcome (see `applySyncMutationBatch`).
164
+ */
165
+ export interface SyncMutateBatchRequest {
166
+ /** Ordered mutations; each still carries its own mutationId. */
167
+ mutations: SyncMutateRequest[];
168
+ /**
169
+ * Client-generated correlation id, socket transport only (ignored over
170
+ * HTTP). Echoed back immediately via `sync:batchReceived {batchId}` before
171
+ * processing begins, so the client can distinguish "the server has no
172
+ * sync:mutateBatch handler" (silence past the grace period, batching
173
+ * unsupported) from "the server is just slow to finish this batch" (a
174
+ * receipt arrived; keep waiting up to the full batch timeout).
175
+ */
176
+ batchId?: string;
177
+ }
178
+ /** One result per PROCESSED mutation in a batch, in request order. */
179
+ export type SyncMutateBatchResult = {
180
+ type: "ack";
181
+ ack: SyncAck;
182
+ } | {
183
+ type: "nack";
184
+ nack: SyncNack;
185
+ };
186
+ /**
187
+ * Response to a batch mutation request.
188
+ *
189
+ * `results.length < request.mutations.length` means the server halted at the
190
+ * first non-ack: `results[results.length - 1]` is that failing outcome, and
191
+ * every mutation after it was NOT attempted (not ledgered, not applied) —
192
+ * still safe to resend in a later batch (INV-3).
193
+ */
194
+ export interface SyncMutateBatchResponse {
195
+ results: SyncMutateBatchResult[];
196
+ }
197
+ /**
198
+ * A change event delivered to subscribed clients via `sync:delta`.
199
+ *
200
+ * ## Per-entity ordering & the LWW-by-seq contract (C8)
201
+ *
202
+ * The server serializes delta dispatch PER entity (`{collection}:{id}`): two deltas for
203
+ * the same document are always emitted in change-stream (commit) order, so their `seq`
204
+ * values arrive monotonically for that entity. Deltas for DIFFERENT entities may arrive
205
+ * in any order (they dispatch concurrently). Clients therefore apply last-writer-wins
206
+ * BY SEQ within an entity: a delta whose `seq` is at or below the entity's applied seq is
207
+ * an idempotent no-op; only a strictly higher `seq` mutates local state. Combined with
208
+ * the C1 frontier (`frontierSeq`), a cursor never advances past an uncommitted seq, so no
209
+ * committed delta is ever permanently skipped.
210
+ */
211
+ export interface SyncDelta {
212
+ /** Collection tag (e.g. "todos"). */
213
+ collection: string;
214
+ /** Document id. */
215
+ id: string;
216
+ method: SyncMutationOperation;
217
+ /** Serialized document data (omitted for tombstone deltas emitted to a previous stream). */
218
+ data?: unknown;
219
+ /** The document's `_syncSeq`. */
220
+ seq: number;
221
+ /** Stream key this delta belongs to (e.g. "todos|owner:123"). */
222
+ stream: string;
223
+ /**
224
+ * C1: the stream's stable frontier at emit time. The client advances its cursor to
225
+ * `min(seq, frontierSeq)` so a delta observed out of commit order never advances a
226
+ * cursor past an uncommitted hole.
227
+ */
228
+ frontierSeq?: number;
229
+ /** True when the entity is soft-deleted. */
230
+ deleted?: boolean;
231
+ }
232
+ /**
233
+ * Payload of the `sync:resync-required` socket event (Task 9.16).
234
+ *
235
+ * Emitted server-wide when the change stream could not be resumed — the oplog no longer
236
+ * contains the resume point, so the events in the gap can never be delivered. Any cursor a
237
+ * client holds may now sit below changes (including deletions) it will never be told about,
238
+ * so the only safe response is to re-bootstrap every stream. Clients that do not handle the
239
+ * event still converge on their next full bootstrap; handling it just makes that immediate.
240
+ */
241
+ export interface SyncResyncHint {
242
+ /** Why the resync is needed. Only `history_lost` exists today. */
243
+ reason: "history_lost";
244
+ }
245
+ /** Fields added to synced documents by `syncPlugin`. */
246
+ export interface SyncedDocumentFields {
247
+ /** Monotonic per-stream sequence stamped on every synced write. */
248
+ _syncSeq?: number;
249
+ /**
250
+ * The document's previous stream key, set when a write moved the document between
251
+ * scopes (owner/tenant change); null when the last write did not move it.
252
+ */
253
+ _syncPrevStream?: string | null;
254
+ }
@@ -0,0 +1,9 @@
1
+ "use strict";
2
+ /**
3
+ * Shared types for the SyncDB local-first sync protocol.
4
+ *
5
+ * These types are the contract between @terreno/api (server) and @terreno/syncdb (client):
6
+ * scope/stream configuration, snapshot payloads, mutation requests, and delta events.
7
+ * See docs/implementationPlans/syncdb-local-first.md.
8
+ */
9
+ Object.defineProperty(exports, "__esModule", { value: true });
@@ -43,6 +43,42 @@ var __importStar = (this && this.__importStar) || (function () {
43
43
  return result;
44
44
  };
45
45
  })();
46
+ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
47
+ function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
48
+ return new (P || (P = Promise))(function (resolve, reject) {
49
+ function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
50
+ function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
51
+ function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
52
+ step((generator = generator.apply(thisArg, _arguments || [])).next());
53
+ });
54
+ };
55
+ var __generator = (this && this.__generator) || function (thisArg, body) {
56
+ var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
57
+ return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
58
+ function verb(n) { return function (v) { return step([n, v]); }; }
59
+ function step(op) {
60
+ if (f) throw new TypeError("Generator is already executing.");
61
+ while (g && (g = 0, op[0] && (_ = 0)), _) try {
62
+ if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
63
+ if (y = 0, t) op = [op[0] & 2, t.value];
64
+ switch (op[0]) {
65
+ case 0: case 1: t = op; break;
66
+ case 4: _.label++; return { value: op[1], done: false };
67
+ case 5: _.label++; y = op[1]; op = [0]; continue;
68
+ case 7: op = _.ops.pop(); _.trys.pop(); continue;
69
+ default:
70
+ if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
71
+ if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
72
+ if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
73
+ if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
74
+ if (t[2]) _.ops.pop();
75
+ _.trys.pop(); continue;
76
+ }
77
+ op = body.call(thisArg, _);
78
+ } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
79
+ if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
80
+ }
81
+ };
46
82
  var __values = (this && this.__values) || function(o) {
47
83
  var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
48
84
  if (m) return m.call(o);
@@ -75,6 +111,7 @@ var openApiCompat_1 = require("./openApiCompat");
75
111
  var openApiEtag_1 = require("./openApiEtag");
76
112
  var realtimeApp_1 = require("./realtime/realtimeApp");
77
113
  var requestContext_1 = require("./requestContext");
114
+ var registry_1 = require("./sync/registry");
78
115
  var index_1 = __importDefault(require("./vendor/wesleytodd-openapi/index"));
79
116
  /**
80
117
  * Fluent API for building Express applications with Terreno framework.
@@ -397,46 +434,72 @@ var TerrenoApp = /** @class */ (function () {
397
434
  * ```
398
435
  */
399
436
  TerrenoApp.prototype.start = function () {
400
- var e_3, _a;
401
437
  var _this = this;
438
+ var _a;
402
439
  // If realtime option is set, auto-register the RealtimeApp plugin
403
440
  if (this.options.realtime) {
404
441
  var hasRealtimePlugin = this.registrations.some(function (r) { return !_this.isModelRouterRegistration(r) && r instanceof realtimeApp_1.RealtimeApp; });
405
442
  if (!hasRealtimePlugin) {
406
443
  var realtimeConfig = typeof this.options.realtime === "object" ? this.options.realtime : {};
407
- this.register(new realtimeApp_1.RealtimeApp(realtimeConfig));
444
+ this.register(new realtimeApp_1.RealtimeApp(__assign(__assign({}, realtimeConfig), {
445
+ // Task 9.21 (D2): default the socket full-user load to this app's own user
446
+ // model. Without it socket authorization falls back to the synthetic
447
+ // JWT-claim user, which trusts the token's `admin` over the database and
448
+ // carries no membership fields for tenant-scoped sync.
449
+ userModel: (_a = realtimeConfig.userModel) !== null && _a !== void 0 ? _a : this.options.userModel })));
408
450
  }
409
451
  }
410
452
  var app = this.build();
411
453
  if (!this.options.skipListen) {
412
454
  var port_1 = process.env.PORT || "9000";
413
- try {
414
- var server = (0, node_http_1.createServer)(app);
415
- try {
416
- // Notify plugins that need access to the HTTP server (e.g. WebSocket plugins)
417
- for (var _b = __values(this.registrations), _c = _b.next(); !_c.done; _c = _b.next()) {
418
- var reg = _c.value;
419
- if (!this.isModelRouterRegistration(reg) && typeof reg.onServerCreated === "function") {
420
- reg.onServerCreated(server);
421
- }
455
+ // Await sync index creation before listening: the per-model snapshot indexes (a
456
+ // failed createIndex degrades the snapshot/catch-up query to a table scan) and the
457
+ // bookkeeping-model indexes enqueued by SyncApp (the unique mutationId index is what
458
+ // makes duplicate mutation deliveries idempotent, and the unique stream index is what
459
+ // keeps the counter upsert race from minting duplicate seqs). Either failure is a
460
+ // loud startup error rather than a silent correctness cliff. No-op when no sync
461
+ // models or SyncApp are registered. Detached because start() returns synchronously.
462
+ void (function () { return __awaiter(_this, void 0, void 0, function () {
463
+ var server, _a, _b, reg, error_1, stack;
464
+ var e_3, _c;
465
+ return __generator(this, function (_d) {
466
+ switch (_d.label) {
467
+ case 0:
468
+ _d.trys.push([0, 2, , 3]);
469
+ return [4 /*yield*/, (0, registry_1.ensureSyncIndexes)()];
470
+ case 1:
471
+ _d.sent();
472
+ server = (0, node_http_1.createServer)(app);
473
+ try {
474
+ // Notify plugins that need access to the HTTP server (e.g. WebSocket plugins)
475
+ for (_a = __values(this.registrations), _b = _a.next(); !_b.done; _b = _a.next()) {
476
+ reg = _b.value;
477
+ if (!this.isModelRouterRegistration(reg) && typeof reg.onServerCreated === "function") {
478
+ reg.onServerCreated(server);
479
+ }
480
+ }
481
+ }
482
+ catch (e_3_1) { e_3 = { error: e_3_1 }; }
483
+ finally {
484
+ try {
485
+ if (_b && !_b.done && (_c = _a.return)) _c.call(_a);
486
+ }
487
+ finally { if (e_3) throw e_3.error; }
488
+ }
489
+ server.listen(port_1, function () {
490
+ logger_1.logger.info("Listening on port ".concat(port_1));
491
+ });
492
+ return [3 /*break*/, 3];
493
+ case 2:
494
+ error_1 = _d.sent();
495
+ stack = error_1 instanceof Error ? error_1.stack : String(error_1);
496
+ logger_1.logger.error("Error trying to start HTTP server: ".concat(error_1, "\n").concat(stack));
497
+ process.exit(1);
498
+ return [3 /*break*/, 3];
499
+ case 3: return [2 /*return*/];
422
500
  }
423
- }
424
- catch (e_3_1) { e_3 = { error: e_3_1 }; }
425
- finally {
426
- try {
427
- if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
428
- }
429
- finally { if (e_3) throw e_3.error; }
430
- }
431
- server.listen(port_1, function () {
432
- logger_1.logger.info("Listening on port ".concat(port_1));
433
501
  });
434
- }
435
- catch (error) {
436
- var stack = error instanceof Error ? error.stack : String(error);
437
- logger_1.logger.error("Error trying to start HTTP server: ".concat(error, "\n").concat(stack));
438
- process.exit(1);
439
- }
502
+ }); })();
440
503
  }
441
504
  return app;
442
505
  };
@@ -16,7 +16,7 @@ declare function _exports(_routePrefix: any, _doc: any, _opts: any): {
16
16
  securitySchemes: (name?: any, description?: any) => any;
17
17
  links: (name?: any, description?: any) => any;
18
18
  callbacks: (name?: any, description?: any) => any;
19
- swaggerui(options: any): any[];
19
+ swaggerui(options: any): import("serve-static").RequestHandler<import("node:http").ServerResponse<import("node:http").IncomingMessage>>[];
20
20
  };
21
21
  declare namespace _exports {
22
22
  export { minimumViableDocument };
@@ -1 +1,2 @@
1
- export function serveSwaggerUI(documentUrl: any, opts?: {}): any[];
1
+ export function serveSwaggerUI(documentUrl: any, opts?: {}): serve.RequestHandler<import("node:http").ServerResponse<import("node:http").IncomingMessage>>[];
2
+ import serve = require("serve-static");
package/package.json CHANGED
@@ -7,7 +7,7 @@
7
7
  "@asteasolutions/zod-to-openapi": "^8.5.0",
8
8
  "@sentry/bun": "^10.39.0",
9
9
  "@sentry/profiling-node": "^10.25.0",
10
- "@terreno/test": "0.30.0",
10
+ "@terreno/test": "56.0.0-beta.0",
11
11
  "@types/qs": "^6.14.0",
12
12
  "ajv": "8.20.0",
13
13
  "ajv-formats": "^3.0.1",
@@ -20,7 +20,7 @@
20
20
  "swagger-ui-dist": "^5.11.8",
21
21
  "yaml": "^2.4.0",
22
22
  "axios": "^1.13.2",
23
- "better-auth": "^1.2.8",
23
+ "better-auth": "^1.6.25",
24
24
  "cors": "^2.8.5",
25
25
  "cron": "^4.3.4",
26
26
  "expo-server-sdk": "^6.0.0",
@@ -47,6 +47,7 @@
47
47
  "description": "Styled after the Django & Django REST Framework, a batteries-include framework for building REST APIs with Node/Express/Mongoose.",
48
48
  "devDependencies": {
49
49
  "@biomejs/biome": "^2.3.6",
50
+ "@terreno/syncdb": "56.0.0-beta.0",
50
51
  "@types/bcrypt": "^6.0.0",
51
52
  "@types/bun": "^1.3.8",
52
53
  "@types/cors": "^2.8.17",
@@ -68,8 +69,7 @@
68
69
  "mongoose": "8.23.0",
69
70
  "sinon": "^22.0.0",
70
71
  "supertest": "^7.2.2",
71
- "typedoc": "^0.28.17",
72
- "typescript": "~5.9.2",
72
+ "typescript": "~6.0.3",
73
73
  "zod": "^4.4.3"
74
74
  },
75
75
  "homepage": "https://github.com/FlourishHealth/terreno#readme",
@@ -110,10 +110,11 @@
110
110
  "compile": "node ../.github/scripts/compile-workspace-deps.js && bun tsc",
111
111
  "compile:watch": "bun tsc -w",
112
112
  "dev": "bun tsc -w",
113
- "docs": "typedoc --out docs src/index.ts",
113
+ "docs": "bunx typedoc@0.28.19 --out docs src/index.ts",
114
114
  "lint": "biome check ./src",
115
115
  "lint:fix": "biome check --write ./src",
116
116
  "lint:unsafefix": "biome check --fix --unsafe ./src",
117
+ "load": "bun src/sync/loadHarness.ts",
117
118
  "test": "bun test --update-snapshots",
118
119
  "test:ci": "bun test",
119
120
  "test:coverage": "bun run ../scripts/check-coverage.ts",
@@ -123,5 +124,5 @@
123
124
  "updateSnapshot": "bun test --update-snapshots"
124
125
  },
125
126
  "types": "dist/index.d.ts",
126
- "version": "0.30.0"
127
+ "version": "56.0.0-beta.0"
127
128
  }
@@ -118,6 +118,26 @@ describe("openApiCompat", () => {
118
118
  }
119
119
  });
120
120
 
121
+ it("annotates nested router.use mounts with the mount path", () => {
122
+ const app = express();
123
+ patchAppUse(app);
124
+
125
+ const outer = express.Router();
126
+ const inner = express.Router();
127
+ inner.get("/", (_req, res) => {
128
+ res.json({ok: true});
129
+ });
130
+ outer.use("/gpt/histories", inner);
131
+ app.use("/", outer);
132
+
133
+ const stack = getRouterStack(app);
134
+ const nestedMount = findLayer(
135
+ stack,
136
+ (layer) => layer.__openApiMountPath === "/gpt/histories"
137
+ );
138
+ expect(nestedMount).toBeDefined();
139
+ });
140
+
121
141
  it("returns the underlying use() return value", () => {
122
142
  const app = express();
123
143
  patchAppUse(app);
@@ -1,9 +1,9 @@
1
- // noExplicitAny: test mock typing
2
- // biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
3
1
  import {beforeEach, describe, expect, it} from "bun:test";
4
2
  import type express from "express";
5
3
  import supertest from "supertest";
6
- import {type ModelRouterOptions, modelRouter} from "./api";
4
+ import {modelRouter} from "./api";
5
+ import type {UserModel as UserMongooseModel} from "./auth";
6
+ import type {AddRoutes} from "./expressServer";
7
7
  import {Permissions} from "./permissions";
8
8
  import {TerrenoApp} from "./terrenoApp";
9
9
  import {FoodModel, setupDb, UserModel} from "./tests";
@@ -130,7 +130,7 @@ describe("action OpenAPI emission", () => {
130
130
  const foodRegistration = modelRouter("/food", FoodModel, foodActionRouterOptions);
131
131
  const app = new TerrenoApp({
132
132
  skipListen: true,
133
- userModel: UserModel as any,
133
+ userModel: UserModel as unknown as UserMongooseModel,
134
134
  })
135
135
  .register(foodRegistration)
136
136
  .build();
@@ -151,20 +151,17 @@ describe("action OpenAPI emission", () => {
151
151
  let app: express.Application;
152
152
 
153
153
  beforeEach(() => {
154
- const configureApp = (
155
- router: express.Router,
156
- routerOptions?: Partial<ModelRouterOptions<unknown>>
157
- ): void => {
154
+ const configureApp: AddRoutes = (router, routerOptions) => {
158
155
  router.use(
159
156
  "/food",
160
- modelRouter(FoodModel as any, {...foodActionRouterOptions, ...routerOptions})
157
+ modelRouter(FoodModel, {...foodActionRouterOptions, openApi: routerOptions?.openApi})
161
158
  );
162
159
  };
163
160
 
164
161
  app = new TerrenoApp({
165
162
  configureApp,
166
163
  skipListen: true,
167
- userModel: UserModel as any,
164
+ userModel: UserModel as unknown as UserMongooseModel,
168
165
  }).build();
169
166
  });
170
167
 
package/src/api.test.ts CHANGED
@@ -1960,6 +1960,9 @@ describe("@terreno/api", () => {
1960
1960
 
1961
1961
  it("returns 409 when If-Unmodified-Since is older than doc.updated", async () => {
1962
1962
  const staleTimestamp = DateTime.fromISO("2025-06-15T11:00:00.000Z").toHTTP();
1963
+ if (staleTimestamp === null) {
1964
+ throw new Error("expected HTTP If-Unmodified-Since value");
1965
+ }
1963
1966
 
1964
1967
  const res = await agent
1965
1968
  .patch(`/food/${spinach._id}`)
@@ -1976,6 +1979,9 @@ describe("@terreno/api", () => {
1976
1979
 
1977
1980
  it("succeeds when If-Unmodified-Since matches or is newer than doc.updated", async () => {
1978
1981
  const freshTimestamp = DateTime.fromISO("2025-06-15T13:00:00.000Z").toHTTP();
1982
+ if (freshTimestamp === null) {
1983
+ throw new Error("expected HTTP If-Unmodified-Since value");
1984
+ }
1979
1985
 
1980
1986
  const res = await agent
1981
1987
  .patch(`/food/${spinach._id}`)
@@ -1997,6 +2003,9 @@ describe("@terreno/api", () => {
1997
2003
 
1998
2004
  it("succeeds when If-Unmodified-Since exactly matches doc.updated", async () => {
1999
2005
  const exactTimestamp = DateTime.fromISO("2025-06-15T12:00:00.000Z").toHTTP();
2006
+ if (exactTimestamp === null) {
2007
+ throw new Error("expected HTTP If-Unmodified-Since value");
2008
+ }
2000
2009
 
2001
2010
  const res = await agent
2002
2011
  .patch(`/food/${spinach._id}`)
@@ -2009,6 +2018,9 @@ describe("@terreno/api", () => {
2009
2018
 
2010
2019
  it("prefers precise conflict timestamp header when present", async () => {
2011
2020
  const roundedStaleTimestamp = DateTime.fromISO("2025-06-15T11:59:59.000Z").toHTTP();
2021
+ if (roundedStaleTimestamp === null) {
2022
+ throw new Error("expected HTTP If-Unmodified-Since value");
2023
+ }
2012
2024
 
2013
2025
  const res = await agent
2014
2026
  .patch(`/food/${spinach._id}`)