@serve.zone/dcrouter-apiclient 34.9.2 → 34.10.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.
@@ -7,6 +7,7 @@ export interface IEmail {
7
7
  direction: TEmailDirection;
8
8
  status: TEmailStatus;
9
9
  from: string;
10
+ /** The first recipient the message is delivered to (its SMTP envelope), not its To field. */
10
11
  to: string;
11
12
  subject: string;
12
13
  timestamp: string;
@@ -141,7 +142,13 @@ export interface IEmailDetail extends IEmail {
141
142
  nextAttemptAt?: number;
142
143
  /** 1-based number of the next scheduled delivery attempt. */
143
144
  nextAttemptNumber?: number;
145
+ /**
146
+ * Display data, not the recipients. Of a delivery-queue item: its message's
147
+ * To addresses (a raw item, which is not parsed, holds its envelope here).
148
+ * Of an accepted message: its SMTP envelope recipients.
149
+ */
144
150
  toList: string[];
151
+ /** Display data: the addresses of the message's Cc field. */
145
152
  cc?: string[];
146
153
  smtpLog: ISmtpLogEntry[];
147
154
  connectionInfo: IConnectionInfo;
@@ -209,3 +216,74 @@ export interface IReq_ResendEmail extends plugins.typedrequestInterfaces.impleme
209
216
  error?: string;
210
217
  };
211
218
  }
219
+ /**
220
+ * Counts of the accepted-mail rows stored for a window, by handoff path and
221
+ * outcome: numbers only, no address and no row. A recipient is an identity
222
+ * recipient when an identity stored at the time of the read takes its inbound
223
+ * mail through a typed endpoint or CoreMail; identities created or removed
224
+ * since a message was accepted count as they are stored now.
225
+ */
226
+ export interface IMailHandoffCounts {
227
+ /** Inclusive accepted-at bounds of the window, epoch milliseconds. */
228
+ windowStart: number;
229
+ windowEnd: number;
230
+ /** Rows read in the window. */
231
+ rowsScanned: number;
232
+ /** True when the window holds more rows than one read scans; the newest rows were counted. */
233
+ truncated: boolean;
234
+ /** Rows accepted through the spool (`acceptMessage`, `acceptRawMessage`). */
235
+ spooled: {
236
+ total: number;
237
+ /** Rows that record each recipient's delivery owner. */
238
+ partitioned: number;
239
+ /**
240
+ * Rows `queued` at the read and accepted 30 minutes or more before it. The
241
+ * age counts from acceptance, not from the last handoff or queue report, so
242
+ * a row whose queue item is between delivery retries is counted too.
243
+ */
244
+ queuedOlderThan30Min: number;
245
+ /** Rows with a recipient whose owner part is recorded `failed`. */
246
+ withFailedOwnerEntry: number;
247
+ };
248
+ /** Rows accepted as durable envelopes (`acceptEnvelope`). */
249
+ durable: {
250
+ total: number;
251
+ /** Rows with at least one identity recipient. */
252
+ withIdentityRecipient: number;
253
+ /** Identity recipients by the inbound target of their identity. */
254
+ identityByTarget: {
255
+ typedEndpoint: number;
256
+ coreMail: number;
257
+ };
258
+ /** Identity recipients by whether the SMTP session that delivered the message authenticated. */
259
+ identityBySession: {
260
+ authenticated: number;
261
+ unauthenticated: number;
262
+ };
263
+ /**
264
+ * Identity recipients by how far their handoff got: `handedToOwner` taken
265
+ * by its typed endpoint or CoreMail service, `relayed` taken by SmartMTA's
266
+ * delivery queue, `pending` waiting for a handoff, `failed` no owner has
267
+ * it and nothing is scheduled: a failed handoff, an abandoned dispatch, or
268
+ * a recipient only the stored copy holds.
269
+ */
270
+ identityByOutcome: {
271
+ relayed: number;
272
+ pending: number;
273
+ handedToOwner: number;
274
+ failed: number;
275
+ };
276
+ };
277
+ }
278
+ export interface IReq_GetMailHandoffCounts extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetMailHandoffCounts> {
279
+ method: 'getMailHandoffCounts';
280
+ request: {
281
+ identity?: authInterfaces.IIdentity;
282
+ apiToken?: string;
283
+ /** Inclusive accepted-at lower bound in epoch milliseconds. Requires `to`. Absent = the retention window. */
284
+ from?: number;
285
+ /** Inclusive accepted-at upper bound in epoch milliseconds. Requires `from`. */
286
+ to?: number;
287
+ };
288
+ response: IMailHandoffCounts;
289
+ }
package/package.json CHANGED
@@ -28,7 +28,7 @@
28
28
  "MAC authentication"
29
29
  ],
30
30
  "name": "@serve.zone/dcrouter-apiclient",
31
- "version": "34.9.2",
31
+ "version": "34.10.0",
32
32
  "type": "module",
33
33
  "description": "Object-oriented TypeScript client and shared TypedRequest contracts for the dcrouter OpsServer API.",
34
34
  "main": "./dist_ts_apiclient/index.js",
@@ -48,7 +48,7 @@
48
48
  "@api.global/typedrequest-interfaces": "7.1.0",
49
49
  "@api.global/typedsocket": "8.5.0",
50
50
  "@push.rocks/smartchallenge": "^1.1.0",
51
- "@push.rocks/smartmta": "^14.2.0",
51
+ "@push.rocks/smartmta": "^14.3.0",
52
52
  "@push.rocks/smartnetwork": "^4.10.1",
53
53
  "@push.rocks/smartproxy": "^27.22.1",
54
54
  "@serve.zone/interfaces": "32.87.0"
@@ -12,6 +12,7 @@ export interface IEmail {
12
12
  direction: TEmailDirection;
13
13
  status: TEmailStatus;
14
14
  from: string;
15
+ /** The first recipient the message is delivered to (its SMTP envelope), not its To field. */
15
16
  to: string;
16
17
  subject: string;
17
18
  timestamp: string;
@@ -168,7 +169,13 @@ export interface IEmailDetail extends IEmail {
168
169
  nextAttemptAt?: number;
169
170
  /** 1-based number of the next scheduled delivery attempt. */
170
171
  nextAttemptNumber?: number;
172
+ /**
173
+ * Display data, not the recipients. Of a delivery-queue item: its message's
174
+ * To addresses (a raw item, which is not parsed, holds its envelope here).
175
+ * Of an accepted message: its SMTP envelope recipients.
176
+ */
171
177
  toList: string[];
178
+ /** Display data: the addresses of the message's Cc field. */
172
179
  cc?: string[];
173
180
  smtpLog: ISmtpLogEntry[];
174
181
  connectionInfo: IConnectionInfo;
@@ -264,3 +271,72 @@ export interface IReq_ResendEmail extends plugins.typedrequestInterfaces.impleme
264
271
  error?: string;
265
272
  };
266
273
  }
274
+
275
+ // ============================================================================
276
+ // Get Mail Handoff Counts Request
277
+ // ============================================================================
278
+
279
+ /**
280
+ * Counts of the accepted-mail rows stored for a window, by handoff path and
281
+ * outcome: numbers only, no address and no row. A recipient is an identity
282
+ * recipient when an identity stored at the time of the read takes its inbound
283
+ * mail through a typed endpoint or CoreMail; identities created or removed
284
+ * since a message was accepted count as they are stored now.
285
+ */
286
+ export interface IMailHandoffCounts {
287
+ /** Inclusive accepted-at bounds of the window, epoch milliseconds. */
288
+ windowStart: number;
289
+ windowEnd: number;
290
+ /** Rows read in the window. */
291
+ rowsScanned: number;
292
+ /** True when the window holds more rows than one read scans; the newest rows were counted. */
293
+ truncated: boolean;
294
+ /** Rows accepted through the spool (`acceptMessage`, `acceptRawMessage`). */
295
+ spooled: {
296
+ total: number;
297
+ /** Rows that record each recipient's delivery owner. */
298
+ partitioned: number;
299
+ /**
300
+ * Rows `queued` at the read and accepted 30 minutes or more before it. The
301
+ * age counts from acceptance, not from the last handoff or queue report, so
302
+ * a row whose queue item is between delivery retries is counted too.
303
+ */
304
+ queuedOlderThan30Min: number;
305
+ /** Rows with a recipient whose owner part is recorded `failed`. */
306
+ withFailedOwnerEntry: number;
307
+ };
308
+ /** Rows accepted as durable envelopes (`acceptEnvelope`). */
309
+ durable: {
310
+ total: number;
311
+ /** Rows with at least one identity recipient. */
312
+ withIdentityRecipient: number;
313
+ /** Identity recipients by the inbound target of their identity. */
314
+ identityByTarget: { typedEndpoint: number; coreMail: number };
315
+ /** Identity recipients by whether the SMTP session that delivered the message authenticated. */
316
+ identityBySession: { authenticated: number; unauthenticated: number };
317
+ /**
318
+ * Identity recipients by how far their handoff got: `handedToOwner` taken
319
+ * by its typed endpoint or CoreMail service, `relayed` taken by SmartMTA's
320
+ * delivery queue, `pending` waiting for a handoff, `failed` no owner has
321
+ * it and nothing is scheduled: a failed handoff, an abandoned dispatch, or
322
+ * a recipient only the stored copy holds.
323
+ */
324
+ identityByOutcome: { relayed: number; pending: number; handedToOwner: number; failed: number };
325
+ };
326
+ }
327
+
328
+ export interface IReq_GetMailHandoffCounts extends plugins.typedrequestInterfaces.implementsTR<
329
+ plugins.typedrequestInterfaces.ITypedRequest,
330
+ IReq_GetMailHandoffCounts
331
+ > {
332
+ method: 'getMailHandoffCounts';
333
+ request: {
334
+ identity?: authInterfaces.IIdentity;
335
+ apiToken?: string;
336
+ /** Inclusive accepted-at lower bound in epoch milliseconds. Requires `to`. Absent = the retention window. */
337
+ from?: number;
338
+ /** Inclusive accepted-at upper bound in epoch milliseconds. Requires `from`. */
339
+ to?: number;
340
+ };
341
+ response: IMailHandoffCounts;
342
+ }