@syncello/auth 4.1.0 → 4.2.0

package/dist/index.d.cts

@@ -251,6 +251,14 @@ interface ResendWebhookPayload {
 interface EmailBranding {
     /** Full URL to the header logo. Default: `${appUrl}/email-header-image.png` */
     logoUrl?: string;
+    /**
+     * Logo width in CSS px. With `logoHeight`, the logo renders at that fixed size with `width`
+     * and `height` attributes, so clients reserve its space and Outlook sizes it right. Default:
+     * unset, and the logo fills half the email's width.
+     */
+    logoWidth?: number;
+    /** Logo height in CSS px; required with `logoWidth`. */
+    logoHeight?: number;
     /** CTA button background. Default: '#00fe9a' */
     buttonBgColor?: string;
     /** CTA button text color. Default: '#000004' */
@@ -2855,6 +2863,52 @@ declare function generate2faEnabledEmail(data: TwoFactorEnabledEmailData, appNam
  */
 declare function generate2faDisabledEmail(data: TwoFactorDisabledEmailData, appName?: string, appUrl?: string, branding?: EmailBranding): EmailTemplate;
 
+/**
+ * The HTML email template: a white card on a light page, the logo, heading, body, an optional
+ * button with its link to copy, an optional notice, a footer note and the footer band, coloured
+ * from the branding options. Tables and inline styles throughout, and a VML button for Outlook.
+ */
+
+/** A consumer's own email, in plain text: {@link renderEmail} escapes every value. */
+interface EmailContent {
+    /** The heading, also the document title. */
+    heading: string;
+    /** Body paragraphs; a newline inside one becomes a line break. */
+    paragraphs: readonly string[];
+    /** Lists after the paragraphs, such as a digest's records. */
+    sections?: readonly EmailSection[];
+    /** A button after the body, with its link to copy underneath. */
+    button?: {
+        label: string;
+        url: string;
+    };
+    /** A neutral callout under the button, such as a link's lifetime. */
+    notice?: string;
+    /** Small print at the end of the card. */
+    footerNote?: string;
+    /** The app's base URL: the default logo's host, and the host every link must be on. */
+    appUrl: string;
+    /** Named in the logo's alt text and the footer (default: "App"). */
+    appName?: string;
+    branding?: EmailBranding;
+}
+/** A titled list in an {@link EmailContent}; each `url` must be on the app's host. */
+interface EmailSection {
+    title: string;
+    url?: string;
+    rows: readonly {
+        text: string;
+        url?: string;
+    }[];
+}
+/**
+ * Render a consumer's own email in the template the auth emails use, so it matches them and
+ * follows their branding. Every value is plain text and escaped here; every URL must be http(s)
+ * on `appUrl`'s host or a subdomain.
+ * @throws If a URL is not http(s) on `appUrl`'s host, or the logo size is invalid
+ */
+declare function renderEmail(content: EmailContent): string;
+
 type EmailEventsTable$1 = PgTableWithColumns<any>;
 type UsersTable = PgTableWithColumns<any>;
 /**
@@ -2890,4 +2944,4 @@ declare function calculateBounceRate(db: PostgresJsDatabase<Record<string, unkno
  */
 declare function calculateComplaintRate(db: PostgresJsDatabase<Record<string, unknown>>, emailEventsTable: EmailEventsTable, hoursAgo?: number): Promise<number>;
 
-export { AUTH_DEFAULTS, type AccountLockoutTables, type Auth, type AuthConfig, type AuthContext, type AuthDatabase, type AuthSchema, CHALLENGE_TTL_MS, type ChallengePayload, CloudflareEmailAdapter, type DeviceType, type EmailAdapter, type EmailBranding, type EmailChangeConfirmationData, type EmailChangeNotificationData, type EmailChangeTables, type EmailSendOptions, type EmailSendResult, EmailService, type EmailTemplate, type EmailType, type Env, type InferNewSession, type InferNewUser, type InferSession, type InferUser, type InvitationHookUser, type InvitationHooks, MAX_CHALLENGE_ATTEMPTS, PASSWORDLESS_MAX_ATTEMPTS, PASSWORDLESS_TTL_MS, type PasswordResetEmailData, type PasswordlessCodeResult, type PasswordlessLinkResult, type PasswordlessSuccess, type PasswordlessTables, type ProblemDetails, ProblemTypes, ResendAdapter, type ResendEventType, type ResendWebhookPayload, type SendEmailBinding, type SendEmailResult, type SessionData, type SessionTables, type SignupMode, type SvixHeaders, TRUSTED_DEVICE_COOKIE_BASE, TRUSTED_DEVICE_TTL_MS, type TotpVerifyResult, type TwoFactorCodeEmailData, type TwoFactorDisabledEmailData, type TwoFactorEnabledEmailData, type ValidationResult, type Variables, type VerificationEmailData, authRoutes, calculateBounceRate, calculateComplaintRate, cancelEmailChange, checkAccountLocked, checkBreachedPassword, cleanupExpiredPasswordlessChallenges, clearAccountLockout, clearChallengeCookie, clearSessionCookie, clearTrustedDeviceCookie, confirmEmailChange, createAuth, createAuthMiddleware, createChallengeToken, createDeviceToken, createEmailAdapter, createPasswordlessChallenge, createProblemDetails, createSession, csrf, decryptTotpSecret, deleteAllUserSessions, deleteChallengeToken, deleteSession, encryptTotpSecret, extractAppUrl, formatBackupCode, generate2faCodeEmail, generate2faDisabledEmail, generate2faEnabledEmail, generateApiKey, generateBackupCodes, generateCode, generateCodeChallenge, generateCodeVerifier, generateEmailChangeConfirmation, generateEmailChangeNotification, generateFingerprint, generatePasswordResetEmail, generateQrCodeUri, generateSecureToken, generateTotpSecret, generateTraceId, generateVerificationEmail, getAllowedOrigins, getAuthContext, getChallengeCookieName, getClientIp, getKeyPrefix, getMinutesUntilUnlock, getSessionCookieName, getTotpCounter, getTrustedDeviceCookieName, handleWebhookEvent, hashApiKey, hashBackupCode, hashPassword, hashToken, incrementFailedAttempts, invalidateAllUserSessions, isCapacitorApp, isCloudflarePreviewUrl, isDeepLinkUri, isValidApiKeyFormat, logError, logSecurityEvent, logger, normalizeBackupCode, optionalAuth, parseDeviceName, parseDeviceType, passwordlessEmail, problemJson, problems, rateLimit, recentPasswordlessFailures, refreshSession, requestEmailChange, requireAuth, requireVerifiedEmail, retrieveChallengeToken, sessionRefreshDue, setChallengeCookie, setSessionCookie, setTrustedDeviceCookie, storeChallengeToken, updateChallengeAttempts, validateChallengePayload, validateOrigin, validatePassword, validatePasswordWithBreachCheck, validateSession, validateTrustedDevice, verifyBackupCode, verifyCodeChallenge, verifyPassword, verifyPasswordWithRotation, verifyPasswordlessCode, verifyPasswordlessLink, verifyTotpCode, verifyTurnstileToken, verifyWebhookSignature };
+export { AUTH_DEFAULTS, type AccountLockoutTables, type Auth, type AuthConfig, type AuthContext, type AuthDatabase, type AuthSchema, CHALLENGE_TTL_MS, type ChallengePayload, CloudflareEmailAdapter, type DeviceType, type EmailAdapter, type EmailBranding, type EmailChangeConfirmationData, type EmailChangeNotificationData, type EmailChangeTables, type EmailContent, type EmailSection, type EmailSendOptions, type EmailSendResult, EmailService, type EmailTemplate, type EmailType, type Env, type InferNewSession, type InferNewUser, type InferSession, type InferUser, type InvitationHookUser, type InvitationHooks, MAX_CHALLENGE_ATTEMPTS, PASSWORDLESS_MAX_ATTEMPTS, PASSWORDLESS_TTL_MS, type PasswordResetEmailData, type PasswordlessCodeResult, type PasswordlessLinkResult, type PasswordlessSuccess, type PasswordlessTables, type ProblemDetails, ProblemTypes, ResendAdapter, type ResendEventType, type ResendWebhookPayload, type SendEmailBinding, type SendEmailResult, type SessionData, type SessionTables, type SignupMode, type SvixHeaders, TRUSTED_DEVICE_COOKIE_BASE, TRUSTED_DEVICE_TTL_MS, type TotpVerifyResult, type TwoFactorCodeEmailData, type TwoFactorDisabledEmailData, type TwoFactorEnabledEmailData, type ValidationResult, type Variables, type VerificationEmailData, authRoutes, calculateBounceRate, calculateComplaintRate, cancelEmailChange, checkAccountLocked, checkBreachedPassword, cleanupExpiredPasswordlessChallenges, clearAccountLockout, clearChallengeCookie, clearSessionCookie, clearTrustedDeviceCookie, confirmEmailChange, createAuth, createAuthMiddleware, createChallengeToken, createDeviceToken, createEmailAdapter, createPasswordlessChallenge, createProblemDetails, createSession, csrf, decryptTotpSecret, deleteAllUserSessions, deleteChallengeToken, deleteSession, encryptTotpSecret, extractAppUrl, formatBackupCode, generate2faCodeEmail, generate2faDisabledEmail, generate2faEnabledEmail, generateApiKey, generateBackupCodes, generateCode, generateCodeChallenge, generateCodeVerifier, generateEmailChangeConfirmation, generateEmailChangeNotification, generateFingerprint, generatePasswordResetEmail, generateQrCodeUri, generateSecureToken, generateTotpSecret, generateTraceId, generateVerificationEmail, getAllowedOrigins, getAuthContext, getChallengeCookieName, getClientIp, getKeyPrefix, getMinutesUntilUnlock, getSessionCookieName, getTotpCounter, getTrustedDeviceCookieName, handleWebhookEvent, hashApiKey, hashBackupCode, hashPassword, hashToken, incrementFailedAttempts, invalidateAllUserSessions, isCapacitorApp, isCloudflarePreviewUrl, isDeepLinkUri, isValidApiKeyFormat, logError, logSecurityEvent, logger, normalizeBackupCode, optionalAuth, parseDeviceName, parseDeviceType, passwordlessEmail, problemJson, problems, rateLimit, recentPasswordlessFailures, refreshSession, renderEmail, requestEmailChange, requireAuth, requireVerifiedEmail, retrieveChallengeToken, sessionRefreshDue, setChallengeCookie, setSessionCookie, setTrustedDeviceCookie, storeChallengeToken, updateChallengeAttempts, validateChallengePayload, validateOrigin, validatePassword, validatePasswordWithBreachCheck, validateSession, validateTrustedDevice, verifyBackupCode, verifyCodeChallenge, verifyPassword, verifyPasswordWithRotation, verifyPasswordlessCode, verifyPasswordlessLink, verifyTotpCode, verifyTurnstileToken, verifyWebhookSignature };

package/dist/index.d.ts

@@ -251,6 +251,14 @@ interface ResendWebhookPayload {
 interface EmailBranding {
     /** Full URL to the header logo. Default: `${appUrl}/email-header-image.png` */
     logoUrl?: string;
+    /**
+     * Logo width in CSS px. With `logoHeight`, the logo renders at that fixed size with `width`
+     * and `height` attributes, so clients reserve its space and Outlook sizes it right. Default:
+     * unset, and the logo fills half the email's width.
+     */
+    logoWidth?: number;
+    /** Logo height in CSS px; required with `logoWidth`. */
+    logoHeight?: number;
     /** CTA button background. Default: '#00fe9a' */
     buttonBgColor?: string;
     /** CTA button text color. Default: '#000004' */
@@ -2855,6 +2863,52 @@ declare function generate2faEnabledEmail(data: TwoFactorEnabledEmailData, appNam
  */
 declare function generate2faDisabledEmail(data: TwoFactorDisabledEmailData, appName?: string, appUrl?: string, branding?: EmailBranding): EmailTemplate;
 
+/**
+ * The HTML email template: a white card on a light page, the logo, heading, body, an optional
+ * button with its link to copy, an optional notice, a footer note and the footer band, coloured
+ * from the branding options. Tables and inline styles throughout, and a VML button for Outlook.
+ */
+
+/** A consumer's own email, in plain text: {@link renderEmail} escapes every value. */
+interface EmailContent {
+    /** The heading, also the document title. */
+    heading: string;
+    /** Body paragraphs; a newline inside one becomes a line break. */
+    paragraphs: readonly string[];
+    /** Lists after the paragraphs, such as a digest's records. */
+    sections?: readonly EmailSection[];
+    /** A button after the body, with its link to copy underneath. */
+    button?: {
+        label: string;
+        url: string;
+    };
+    /** A neutral callout under the button, such as a link's lifetime. */
+    notice?: string;
+    /** Small print at the end of the card. */
+    footerNote?: string;
+    /** The app's base URL: the default logo's host, and the host every link must be on. */
+    appUrl: string;
+    /** Named in the logo's alt text and the footer (default: "App"). */
+    appName?: string;
+    branding?: EmailBranding;
+}
+/** A titled list in an {@link EmailContent}; each `url` must be on the app's host. */
+interface EmailSection {
+    title: string;
+    url?: string;
+    rows: readonly {
+        text: string;
+        url?: string;
+    }[];
+}
+/**
+ * Render a consumer's own email in the template the auth emails use, so it matches them and
+ * follows their branding. Every value is plain text and escaped here; every URL must be http(s)
+ * on `appUrl`'s host or a subdomain.
+ * @throws If a URL is not http(s) on `appUrl`'s host, or the logo size is invalid
+ */
+declare function renderEmail(content: EmailContent): string;
+
 type EmailEventsTable$1 = PgTableWithColumns<any>;
 type UsersTable = PgTableWithColumns<any>;
 /**
@@ -2890,4 +2944,4 @@ declare function calculateBounceRate(db: PostgresJsDatabase<Record<string, unkno
  */
 declare function calculateComplaintRate(db: PostgresJsDatabase<Record<string, unknown>>, emailEventsTable: EmailEventsTable, hoursAgo?: number): Promise<number>;
 
-export { AUTH_DEFAULTS, type AccountLockoutTables, type Auth, type AuthConfig, type AuthContext, type AuthDatabase, type AuthSchema, CHALLENGE_TTL_MS, type ChallengePayload, CloudflareEmailAdapter, type DeviceType, type EmailAdapter, type EmailBranding, type EmailChangeConfirmationData, type EmailChangeNotificationData, type EmailChangeTables, type EmailSendOptions, type EmailSendResult, EmailService, type EmailTemplate, type EmailType, type Env, type InferNewSession, type InferNewUser, type InferSession, type InferUser, type InvitationHookUser, type InvitationHooks, MAX_CHALLENGE_ATTEMPTS, PASSWORDLESS_MAX_ATTEMPTS, PASSWORDLESS_TTL_MS, type PasswordResetEmailData, type PasswordlessCodeResult, type PasswordlessLinkResult, type PasswordlessSuccess, type PasswordlessTables, type ProblemDetails, ProblemTypes, ResendAdapter, type ResendEventType, type ResendWebhookPayload, type SendEmailBinding, type SendEmailResult, type SessionData, type SessionTables, type SignupMode, type SvixHeaders, TRUSTED_DEVICE_COOKIE_BASE, TRUSTED_DEVICE_TTL_MS, type TotpVerifyResult, type TwoFactorCodeEmailData, type TwoFactorDisabledEmailData, type TwoFactorEnabledEmailData, type ValidationResult, type Variables, type VerificationEmailData, authRoutes, calculateBounceRate, calculateComplaintRate, cancelEmailChange, checkAccountLocked, checkBreachedPassword, cleanupExpiredPasswordlessChallenges, clearAccountLockout, clearChallengeCookie, clearSessionCookie, clearTrustedDeviceCookie, confirmEmailChange, createAuth, createAuthMiddleware, createChallengeToken, createDeviceToken, createEmailAdapter, createPasswordlessChallenge, createProblemDetails, createSession, csrf, decryptTotpSecret, deleteAllUserSessions, deleteChallengeToken, deleteSession, encryptTotpSecret, extractAppUrl, formatBackupCode, generate2faCodeEmail, generate2faDisabledEmail, generate2faEnabledEmail, generateApiKey, generateBackupCodes, generateCode, generateCodeChallenge, generateCodeVerifier, generateEmailChangeConfirmation, generateEmailChangeNotification, generateFingerprint, generatePasswordResetEmail, generateQrCodeUri, generateSecureToken, generateTotpSecret, generateTraceId, generateVerificationEmail, getAllowedOrigins, getAuthContext, getChallengeCookieName, getClientIp, getKeyPrefix, getMinutesUntilUnlock, getSessionCookieName, getTotpCounter, getTrustedDeviceCookieName, handleWebhookEvent, hashApiKey, hashBackupCode, hashPassword, hashToken, incrementFailedAttempts, invalidateAllUserSessions, isCapacitorApp, isCloudflarePreviewUrl, isDeepLinkUri, isValidApiKeyFormat, logError, logSecurityEvent, logger, normalizeBackupCode, optionalAuth, parseDeviceName, parseDeviceType, passwordlessEmail, problemJson, problems, rateLimit, recentPasswordlessFailures, refreshSession, requestEmailChange, requireAuth, requireVerifiedEmail, retrieveChallengeToken, sessionRefreshDue, setChallengeCookie, setSessionCookie, setTrustedDeviceCookie, storeChallengeToken, updateChallengeAttempts, validateChallengePayload, validateOrigin, validatePassword, validatePasswordWithBreachCheck, validateSession, validateTrustedDevice, verifyBackupCode, verifyCodeChallenge, verifyPassword, verifyPasswordWithRotation, verifyPasswordlessCode, verifyPasswordlessLink, verifyTotpCode, verifyTurnstileToken, verifyWebhookSignature };
+export { AUTH_DEFAULTS, type AccountLockoutTables, type Auth, type AuthConfig, type AuthContext, type AuthDatabase, type AuthSchema, CHALLENGE_TTL_MS, type ChallengePayload, CloudflareEmailAdapter, type DeviceType, type EmailAdapter, type EmailBranding, type EmailChangeConfirmationData, type EmailChangeNotificationData, type EmailChangeTables, type EmailContent, type EmailSection, type EmailSendOptions, type EmailSendResult, EmailService, type EmailTemplate, type EmailType, type Env, type InferNewSession, type InferNewUser, type InferSession, type InferUser, type InvitationHookUser, type InvitationHooks, MAX_CHALLENGE_ATTEMPTS, PASSWORDLESS_MAX_ATTEMPTS, PASSWORDLESS_TTL_MS, type PasswordResetEmailData, type PasswordlessCodeResult, type PasswordlessLinkResult, type PasswordlessSuccess, type PasswordlessTables, type ProblemDetails, ProblemTypes, ResendAdapter, type ResendEventType, type ResendWebhookPayload, type SendEmailBinding, type SendEmailResult, type SessionData, type SessionTables, type SignupMode, type SvixHeaders, TRUSTED_DEVICE_COOKIE_BASE, TRUSTED_DEVICE_TTL_MS, type TotpVerifyResult, type TwoFactorCodeEmailData, type TwoFactorDisabledEmailData, type TwoFactorEnabledEmailData, type ValidationResult, type Variables, type VerificationEmailData, authRoutes, calculateBounceRate, calculateComplaintRate, cancelEmailChange, checkAccountLocked, checkBreachedPassword, cleanupExpiredPasswordlessChallenges, clearAccountLockout, clearChallengeCookie, clearSessionCookie, clearTrustedDeviceCookie, confirmEmailChange, createAuth, createAuthMiddleware, createChallengeToken, createDeviceToken, createEmailAdapter, createPasswordlessChallenge, createProblemDetails, createSession, csrf, decryptTotpSecret, deleteAllUserSessions, deleteChallengeToken, deleteSession, encryptTotpSecret, extractAppUrl, formatBackupCode, generate2faCodeEmail, generate2faDisabledEmail, generate2faEnabledEmail, generateApiKey, generateBackupCodes, generateCode, generateCodeChallenge, generateCodeVerifier, generateEmailChangeConfirmation, generateEmailChangeNotification, generateFingerprint, generatePasswordResetEmail, generateQrCodeUri, generateSecureToken, generateTotpSecret, generateTraceId, generateVerificationEmail, getAllowedOrigins, getAuthContext, getChallengeCookieName, getClientIp, getKeyPrefix, getMinutesUntilUnlock, getSessionCookieName, getTotpCounter, getTrustedDeviceCookieName, handleWebhookEvent, hashApiKey, hashBackupCode, hashPassword, hashToken, incrementFailedAttempts, invalidateAllUserSessions, isCapacitorApp, isCloudflarePreviewUrl, isDeepLinkUri, isValidApiKeyFormat, logError, logSecurityEvent, logger, normalizeBackupCode, optionalAuth, parseDeviceName, parseDeviceType, passwordlessEmail, problemJson, problems, rateLimit, recentPasswordlessFailures, refreshSession, renderEmail, requestEmailChange, requireAuth, requireVerifiedEmail, retrieveChallengeToken, sessionRefreshDue, setChallengeCookie, setSessionCookie, setTrustedDeviceCookie, storeChallengeToken, updateChallengeAttempts, validateChallengePayload, validateOrigin, validatePassword, validatePasswordWithBreachCheck, validateSession, validateTrustedDevice, verifyBackupCode, verifyCodeChallenge, verifyPassword, verifyPasswordWithRotation, verifyPasswordlessCode, verifyPasswordlessLink, verifyTotpCode, verifyTurnstileToken, verifyWebhookSignature };