@digilogiclabs/platform-core 1.20.3 → 1.21.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 (36) hide show
  1. package/dist/{ConsoleEmail-CO0OM4UT.d.ts → ConsoleEmail-BbdpINKx.d.ts} +4 -46
  2. package/dist/{ConsoleEmail-DDB28vyS.d.mts → ConsoleEmail-DpxhsG9C.d.mts} +4 -46
  3. package/dist/{IAI-D8wA_i8N.d.mts → IAI-CWd11dzL.d.mts} +1 -105
  4. package/dist/{IAI-D8wA_i8N.d.ts → IAI-CWd11dzL.d.ts} +1 -105
  5. package/dist/IEmail-CsOcaQcb.d.mts +45 -0
  6. package/dist/IEmail-CsOcaQcb.d.ts +45 -0
  7. package/dist/ILogger-DLDBZaH4.d.mts +105 -0
  8. package/dist/ILogger-DLDBZaH4.d.ts +105 -0
  9. package/dist/{agents-Cc65YUoW.d.ts → agents-C42rGwRl.d.ts} +2 -1
  10. package/dist/{agents-DGciJI27.d.mts → agents-CES-Aq1K.d.mts} +2 -1
  11. package/dist/agents.d.mts +3 -2
  12. package/dist/agents.d.ts +3 -2
  13. package/dist/auth.d.mts +238 -1
  14. package/dist/auth.d.ts +238 -1
  15. package/dist/auth.js +198 -0
  16. package/dist/auth.js.map +1 -1
  17. package/dist/auth.mjs +183 -0
  18. package/dist/auth.mjs.map +1 -1
  19. package/dist/circuit-breaker-CP6kw0P5.d.ts +351 -0
  20. package/dist/circuit-breaker-CsQivd57.d.mts +351 -0
  21. package/dist/email-templates.d.mts +106 -1
  22. package/dist/email-templates.d.ts +106 -1
  23. package/dist/email-templates.js +608 -0
  24. package/dist/email-templates.js.map +1 -1
  25. package/dist/email-templates.mjs +596 -0
  26. package/dist/email-templates.mjs.map +1 -1
  27. package/dist/index.d.mts +12 -355
  28. package/dist/index.d.ts +12 -355
  29. package/dist/index.js +10 -7
  30. package/dist/index.js.map +1 -1
  31. package/dist/index.mjs +10 -7
  32. package/dist/index.mjs.map +1 -1
  33. package/dist/migrate.js +0 -0
  34. package/dist/testing.d.mts +5 -3
  35. package/dist/testing.d.ts +5 -3
  36. package/package.json +11 -11
@@ -1,4 +1,7 @@
1
+ import { I as IEmail } from './IEmail-CsOcaQcb.mjs';
2
+ import { R as RetryOptions, C as CircuitBreakerOptions } from './circuit-breaker-CsQivd57.mjs';
1
3
  export { e as escapeHtml } from './security-DMUNYqQI.mjs';
4
+ import './ILogger-DLDBZaH4.mjs';
2
5
 
3
6
  /**
4
7
  * Shared email template types.
@@ -207,4 +210,106 @@ interface SecurityEmailData {
207
210
  }
208
211
  declare function securityEmail(branding: EmailBranding, data: SecurityEmailData): EmailOutput;
209
212
 
210
- export { type DigestEmailData, type EmailBranding, type EmailCTA, type EmailLayoutOptions, type EmailOutput, type EmailStat, type EmailStep, type EmailTableRow, type ModerationAction, type ModerationEmailData, type NotificationEmailData, type SecurityEmailData, type TransactionEmailData, type WelcomeEmailData, calloutBlock, dataTable, digestEmail, divider, emailLayout, moderationEmail, notificationEmail, sectionHeading, securityEmail, statsBar, stepBlock, tipBlock, transactionEmail, welcomeEmail };
213
+ interface UnsubscribeConfig {
214
+ /**
215
+ * HMAC-SHA-256 secret. Must be at least 16 chars.
216
+ * Reuse the same secret across all email sends for a given recipient pool;
217
+ * rotating it invalidates outstanding unsubscribe links.
218
+ */
219
+ secret: string;
220
+ /** App base URL (e.g. `https://opensourcesports.io`). No trailing slash. */
221
+ baseUrl: string;
222
+ /**
223
+ * Optional `mailto:` address for the List-Unsubscribe header (RFC 2369).
224
+ * When provided, the header includes both the URL and the mailto variant
225
+ * (some clients still prefer mailto). Defaults to omitted if absent.
226
+ */
227
+ mailtoUnsubscribe?: string;
228
+ /**
229
+ * Unsubscribe URL path (defaults to `/unsubscribe`). The query string
230
+ * appended is `?token=<token>`.
231
+ */
232
+ path?: string;
233
+ }
234
+ interface UnsubscribeHelpers {
235
+ /** Generate a signed unsubscribe token for an email. */
236
+ generateToken(email: string): string;
237
+ /** Verify a token and return the email, or null if invalid. */
238
+ verifyToken(token: unknown): string | null;
239
+ /** Build the full unsubscribe URL — drop in email href. */
240
+ generateUrl(email: string): string;
241
+ /** RFC 2369 List-Unsubscribe header value. */
242
+ generateListUnsubscribeHeader(email: string): string;
243
+ /** RFC 8058 one-click header value (constant). */
244
+ generateListUnsubscribePostHeader(): "List-Unsubscribe=One-Click";
245
+ }
246
+ /**
247
+ * Construct a bundle of unsubscribe helpers bound to a single secret +
248
+ * base URL. Apps typically instantiate once at module load and reuse.
249
+ */
250
+ declare function createUnsubscribe(cfg: UnsubscribeConfig): UnsubscribeHelpers;
251
+
252
+ /**
253
+ * Resilient Email Transport Wrapper
254
+ *
255
+ * Wraps any `IEmail` adapter with retry + optional circuit-breaker +
256
+ * optional timeout. Solves the "Resend is briefly flaky / rate-limited /
257
+ * the network blipped" class of failure without each app re-implementing
258
+ * the same wrapping logic.
259
+ *
260
+ * Defaults are conservative:
261
+ * - retry: 3 attempts, 200ms base delay, exponential backoff with jitter
262
+ * - circuit breaker: disabled (opt-in)
263
+ * - timeout: disabled (opt-in)
264
+ *
265
+ * Wraps both `send` and `sendBatch` — `healthCheck` is NOT wrapped
266
+ * because retry-on-health-check would mask the very thing it probes.
267
+ *
268
+ * @example wrap the existing ResendEmail adapter
269
+ * ```typescript
270
+ * import { Resend } from "resend";
271
+ * import { ResendEmail } from "@digilogiclabs/platform-core";
272
+ * import { createResilientEmail } from "@digilogiclabs/platform-core/email-templates";
273
+ *
274
+ * const inner = new ResendEmail(new Resend(apiKey), "noreply@app.com");
275
+ * const email = createResilientEmail(inner, {
276
+ * retry: { maxAttempts: 3 },
277
+ * circuitBreaker: { failureThreshold: 5, openDurationMs: 30_000 },
278
+ * timeoutMs: 5_000,
279
+ * });
280
+ *
281
+ * await email.send({ to: { email: "user@example.com" }, subject, html });
282
+ * ```
283
+ *
284
+ * Works with any IEmail adapter — Resend, SMTP, Console — not just Resend.
285
+ * The factory name historically referenced Resend because that was the
286
+ * first consumer; the implementation is adapter-agnostic.
287
+ */
288
+
289
+ interface ResilientEmailOptions {
290
+ /**
291
+ * Retry config. Pass `false` to disable. Defaults to `{ maxAttempts: 3 }`
292
+ * (with the platform's standard exponential backoff + jitter).
293
+ */
294
+ retry?: Partial<RetryOptions> | false;
295
+ /**
296
+ * Circuit breaker config. Omit or pass `false` to disable.
297
+ * When enabled, the breaker wraps the retry loop so an open circuit
298
+ * fails fast without exhausting retries.
299
+ */
300
+ circuitBreaker?: CircuitBreakerOptions | false;
301
+ /**
302
+ * Timeout in milliseconds for a single send attempt. Omit to disable.
303
+ * Applied per-attempt, not per-call — a request that times out is
304
+ * still subject to retries.
305
+ */
306
+ timeoutMs?: number;
307
+ }
308
+ /**
309
+ * Wrap an `IEmail` adapter with retry, optional circuit breaker, and
310
+ * optional timeout. Returns a new `IEmail` — the inner adapter is not
311
+ * mutated.
312
+ */
313
+ declare function createResilientEmail(inner: IEmail, options?: ResilientEmailOptions): IEmail;
314
+
315
+ export { type DigestEmailData, type EmailBranding, type EmailCTA, type EmailLayoutOptions, type EmailOutput, type EmailStat, type EmailStep, type EmailTableRow, type ModerationAction, type ModerationEmailData, type NotificationEmailData, type ResilientEmailOptions, type SecurityEmailData, type TransactionEmailData, type UnsubscribeConfig, type UnsubscribeHelpers, type WelcomeEmailData, calloutBlock, createResilientEmail, createUnsubscribe, dataTable, digestEmail, divider, emailLayout, moderationEmail, notificationEmail, sectionHeading, securityEmail, statsBar, stepBlock, tipBlock, transactionEmail, welcomeEmail };
@@ -1,4 +1,7 @@
1
+ import { I as IEmail } from './IEmail-CsOcaQcb.js';
2
+ import { R as RetryOptions, C as CircuitBreakerOptions } from './circuit-breaker-CP6kw0P5.js';
1
3
  export { e as escapeHtml } from './security-DMUNYqQI.js';
4
+ import './ILogger-DLDBZaH4.js';
2
5
 
3
6
  /**
4
7
  * Shared email template types.
@@ -207,4 +210,106 @@ interface SecurityEmailData {
207
210
  }
208
211
  declare function securityEmail(branding: EmailBranding, data: SecurityEmailData): EmailOutput;
209
212
 
210
- export { type DigestEmailData, type EmailBranding, type EmailCTA, type EmailLayoutOptions, type EmailOutput, type EmailStat, type EmailStep, type EmailTableRow, type ModerationAction, type ModerationEmailData, type NotificationEmailData, type SecurityEmailData, type TransactionEmailData, type WelcomeEmailData, calloutBlock, dataTable, digestEmail, divider, emailLayout, moderationEmail, notificationEmail, sectionHeading, securityEmail, statsBar, stepBlock, tipBlock, transactionEmail, welcomeEmail };
213
+ interface UnsubscribeConfig {
214
+ /**
215
+ * HMAC-SHA-256 secret. Must be at least 16 chars.
216
+ * Reuse the same secret across all email sends for a given recipient pool;
217
+ * rotating it invalidates outstanding unsubscribe links.
218
+ */
219
+ secret: string;
220
+ /** App base URL (e.g. `https://opensourcesports.io`). No trailing slash. */
221
+ baseUrl: string;
222
+ /**
223
+ * Optional `mailto:` address for the List-Unsubscribe header (RFC 2369).
224
+ * When provided, the header includes both the URL and the mailto variant
225
+ * (some clients still prefer mailto). Defaults to omitted if absent.
226
+ */
227
+ mailtoUnsubscribe?: string;
228
+ /**
229
+ * Unsubscribe URL path (defaults to `/unsubscribe`). The query string
230
+ * appended is `?token=<token>`.
231
+ */
232
+ path?: string;
233
+ }
234
+ interface UnsubscribeHelpers {
235
+ /** Generate a signed unsubscribe token for an email. */
236
+ generateToken(email: string): string;
237
+ /** Verify a token and return the email, or null if invalid. */
238
+ verifyToken(token: unknown): string | null;
239
+ /** Build the full unsubscribe URL — drop in email href. */
240
+ generateUrl(email: string): string;
241
+ /** RFC 2369 List-Unsubscribe header value. */
242
+ generateListUnsubscribeHeader(email: string): string;
243
+ /** RFC 8058 one-click header value (constant). */
244
+ generateListUnsubscribePostHeader(): "List-Unsubscribe=One-Click";
245
+ }
246
+ /**
247
+ * Construct a bundle of unsubscribe helpers bound to a single secret +
248
+ * base URL. Apps typically instantiate once at module load and reuse.
249
+ */
250
+ declare function createUnsubscribe(cfg: UnsubscribeConfig): UnsubscribeHelpers;
251
+
252
+ /**
253
+ * Resilient Email Transport Wrapper
254
+ *
255
+ * Wraps any `IEmail` adapter with retry + optional circuit-breaker +
256
+ * optional timeout. Solves the "Resend is briefly flaky / rate-limited /
257
+ * the network blipped" class of failure without each app re-implementing
258
+ * the same wrapping logic.
259
+ *
260
+ * Defaults are conservative:
261
+ * - retry: 3 attempts, 200ms base delay, exponential backoff with jitter
262
+ * - circuit breaker: disabled (opt-in)
263
+ * - timeout: disabled (opt-in)
264
+ *
265
+ * Wraps both `send` and `sendBatch` — `healthCheck` is NOT wrapped
266
+ * because retry-on-health-check would mask the very thing it probes.
267
+ *
268
+ * @example wrap the existing ResendEmail adapter
269
+ * ```typescript
270
+ * import { Resend } from "resend";
271
+ * import { ResendEmail } from "@digilogiclabs/platform-core";
272
+ * import { createResilientEmail } from "@digilogiclabs/platform-core/email-templates";
273
+ *
274
+ * const inner = new ResendEmail(new Resend(apiKey), "noreply@app.com");
275
+ * const email = createResilientEmail(inner, {
276
+ * retry: { maxAttempts: 3 },
277
+ * circuitBreaker: { failureThreshold: 5, openDurationMs: 30_000 },
278
+ * timeoutMs: 5_000,
279
+ * });
280
+ *
281
+ * await email.send({ to: { email: "user@example.com" }, subject, html });
282
+ * ```
283
+ *
284
+ * Works with any IEmail adapter — Resend, SMTP, Console — not just Resend.
285
+ * The factory name historically referenced Resend because that was the
286
+ * first consumer; the implementation is adapter-agnostic.
287
+ */
288
+
289
+ interface ResilientEmailOptions {
290
+ /**
291
+ * Retry config. Pass `false` to disable. Defaults to `{ maxAttempts: 3 }`
292
+ * (with the platform's standard exponential backoff + jitter).
293
+ */
294
+ retry?: Partial<RetryOptions> | false;
295
+ /**
296
+ * Circuit breaker config. Omit or pass `false` to disable.
297
+ * When enabled, the breaker wraps the retry loop so an open circuit
298
+ * fails fast without exhausting retries.
299
+ */
300
+ circuitBreaker?: CircuitBreakerOptions | false;
301
+ /**
302
+ * Timeout in milliseconds for a single send attempt. Omit to disable.
303
+ * Applied per-attempt, not per-call — a request that times out is
304
+ * still subject to retries.
305
+ */
306
+ timeoutMs?: number;
307
+ }
308
+ /**
309
+ * Wrap an `IEmail` adapter with retry, optional circuit breaker, and
310
+ * optional timeout. Returns a new `IEmail` — the inner adapter is not
311
+ * mutated.
312
+ */
313
+ declare function createResilientEmail(inner: IEmail, options?: ResilientEmailOptions): IEmail;
314
+
315
+ export { type DigestEmailData, type EmailBranding, type EmailCTA, type EmailLayoutOptions, type EmailOutput, type EmailStat, type EmailStep, type EmailTableRow, type ModerationAction, type ModerationEmailData, type NotificationEmailData, type ResilientEmailOptions, type SecurityEmailData, type TransactionEmailData, type UnsubscribeConfig, type UnsubscribeHelpers, type WelcomeEmailData, calloutBlock, createResilientEmail, createUnsubscribe, dataTable, digestEmail, divider, emailLayout, moderationEmail, notificationEmail, sectionHeading, securityEmail, statsBar, stepBlock, tipBlock, transactionEmail, welcomeEmail };