@solidstarters/solid-core 1.2.145 → 1.2.148

package/src/seeders/module-metadata-seeder.service.ts

@@ -134,18 +134,18 @@ export class ModuleMetadataSeederService {
 
             // Process module metadata first. 
             const moduleMetadata: CreateModuleMetadataDto = overallMetadata.moduleMetadata;
-            this.logger.debug(`[Start] Processing module metadata for ${moduleMetadata.name}`)
+            this.logger.log(`[Start] Processing module metadata for ${moduleMetadata.name}`)
             await this.seedModuleModelFields(moduleMetadata);
-            this.logger.debug(`[End] Processing module metadata for ${moduleMetadata.name}`)
+            this.logger.log(`[End] Processing module metadata for ${moduleMetadata.name}`)
 
             // Media Storage provider templates
-            this.logger.debug(`[Start] Processing Media Storage Provider for ${moduleMetadata.name}`);
+            this.logger.log(`[Start] Processing Media Storage Provider for ${moduleMetadata.name}`);
             const mediaStorageProviders = overallMetadata.mediaStorageProviders;
             await this.seedMediaStorageProviders(mediaStorageProviders);
-            this.logger.debug(`[End] Processing Media Storage Provider for ${moduleMetadata.name}`);
+            this.logger.log(`[End] Processing Media Storage Provider for ${moduleMetadata.name}`);
 
             // Custom role handling
-            this.logger.debug(`[End] Processing roles for ${moduleMetadata.name}`)
+            this.logger.log(`[End] Processing roles for ${moduleMetadata.name}`)
             const roles = overallMetadata.roles;
 
             // Every role configuration in the seeder json can optionally have a permissions attribute. 
@@ -159,67 +159,67 @@ export class ModuleMetadataSeederService {
                     await this.roleService.addPermissionsToRole(role.name, role.permissions)
                 }
             }
-            this.logger.debug(`[End] Processing roles for ${moduleMetadata.name}`)
+            this.logger.log(`[End] Processing roles for ${moduleMetadata.name}`)
 
             // Custom user handling
-            this.logger.debug(`[Start] Processing users for ${moduleMetadata.name}`);
+            this.logger.log(`[Start] Processing users for ${moduleMetadata.name}`);
             const users = overallMetadata.users;
             usersDetail = users;
             await this.seedUsers(users);
-            this.logger.debug(`[End] Processing users for ${moduleMetadata.name}`)
+            this.logger.log(`[End] Processing users for ${moduleMetadata.name}`)
 
             // Application Module View handling 
-            this.logger.debug(`[Start] Processing views for ${moduleMetadata.name}`);
+            this.logger.log(`[Start] Processing views for ${moduleMetadata.name}`);
             const views = overallMetadata.views;
             await this.seedViews(views);
-            this.logger.debug(`[End] Processing views for ${moduleMetadata.name}`)
+            this.logger.log(`[End] Processing views for ${moduleMetadata.name}`)
 
             // Application Module Action handling
-            this.logger.debug(`[Start] Processing actions for ${moduleMetadata.name}`);
+            this.logger.log(`[Start] Processing actions for ${moduleMetadata.name}`);
             const actions = overallMetadata.actions;
             await this.seedActions(actions);
-            this.logger.debug(`[End] Processing actions for ${moduleMetadata.name}`)
+            this.logger.log(`[End] Processing actions for ${moduleMetadata.name}`)
 
             // Application Module Menu handling 
-            this.logger.debug(`[Start] Processing menus for ${moduleMetadata.name}`);
+            this.logger.log(`[Start] Processing menus for ${moduleMetadata.name}`);
             const menus = overallMetadata.menus;
             await this.seedMenus(menus);
-            this.logger.debug(`[End] Processing menus for ${moduleMetadata.name}`)
+            this.logger.log(`[End] Processing menus for ${moduleMetadata.name}`)
 
             // Email templates 
-            this.logger.debug(`[Start] Processing email templates for ${moduleMetadata.name}`);
+            this.logger.log(`[Start] Processing email templates for ${moduleMetadata.name}`);
             const emailTemplates: CreateEmailTemplateDto[] = overallMetadata.emailTemplates;
             await this.seedEmailTemplates(emailTemplates, moduleMetadata);
-            this.logger.debug(`[End] Processing email templates for ${moduleMetadata.name}`);
+            this.logger.log(`[End] Processing email templates for ${moduleMetadata.name}`);
 
             // Sms templates
-            this.logger.debug(`[Start] Processing sms templates for ${moduleMetadata.name}`);
+            this.logger.log(`[Start] Processing sms templates for ${moduleMetadata.name}`);
             const smsTemplates: CreateSmsTemplateDto[] = overallMetadata.smsTemplates;
-            await this.seedSmsTemplates(smsTemplates);
-            this.logger.debug(`[End] Processing sms templates for ${moduleMetadata.name}`);
+            await this.seedSmsTemplates(smsTemplates, moduleMetadata);
+            this.logger.log(`[End] Processing sms templates for ${moduleMetadata.name}`);
 
             // Settings
-            this.logger.debug(`[Start] Processing settings for ${moduleMetadata.name}`);
+            this.logger.log(`[Start] Processing settings for ${moduleMetadata.name}`);
             await this.seetingService.seedDefaultSettings();
-            this.logger.debug(`[End] Processing settings for ${moduleMetadata.name}`);
+            this.logger.log(`[End] Processing settings for ${moduleMetadata.name}`);
 
             // Security rules
-            this.logger.debug(`[Start] Processing security rules for ${moduleMetadata.name}`);
+            this.logger.log(`[Start] Processing security rules for ${moduleMetadata.name}`);
             const securityRules: CreateSecurityRuleDto[] = overallMetadata.securityRules;
             await this.seedSecurityRules(securityRules);
-            this.logger.debug(`[End] Processing security rules for ${moduleMetadata.name}`);
+            this.logger.log(`[End] Processing security rules for ${moduleMetadata.name}`);
 
             // List Of Values
-            this.logger.debug(`[Start] Processing List Of Values for ${moduleMetadata.name}`);
+            this.logger.log(`[Start] Processing List Of Values for ${moduleMetadata.name}`);
             const listOfValues: CreateListOfValuesDto[] = overallMetadata.listOfValues;
             await this.seedListOfValues(listOfValues);
-            this.logger.debug(`[End] Processing List Of Values for ${moduleMetadata.name}`);
+            this.logger.log(`[End] Processing List Of Values for ${moduleMetadata.name}`);
 
             // Dashboards
-            this.logger.debug(`[Start] Processing dashboards for ${moduleMetadata.name}`);
+            this.logger.log(`[Start] Processing dashboards for ${moduleMetadata.name}`);
             const dashboards: CreateDashboardDto[] = overallMetadata.dashboards;
             await this.seedDashboards(dashboards);
-            this.logger.debug(`[End] Processing dashboards for ${moduleMetadata.name}`);
+            this.logger.log(`[End] Processing dashboards for ${moduleMetadata.name}`);
 
 
             this.logger.debug(`[End] module seed data: ${overallMetadata}`);
@@ -229,7 +229,7 @@ export class ModuleMetadataSeederService {
         // Post seed data file processing. 
 
         // 1. Give all permissions to the Admin role.
-        this.logger.debug(`About to add all permissions to the Admin role`);
+        this.logger.log(`About to add all permissions to the Admin role`);
         await this.roleService.addAllPermissionsToRole("Admin");
         // 2. Give wrapSettings permissions to the Public role.
         const internalRolePermission = [
@@ -259,7 +259,7 @@ export class ModuleMetadataSeederService {
             'AuthenticationController.logout'
         ]
         await this.roleService.addPermissionToRole('Internal User', internalRolePermission);
-        await this.roleService.addPermissionToRole('Public', ['SettingController.wrapSettings','AuthenticationController.logout']);
+        await this.roleService.addPermissionToRole('Public', ['SettingController.wrapSettings', 'AuthenticationController.logout']);
         this.logger.log(`All Seeders finished`);
         this.logger.log(`Newly created username is: ${usersDetail?.length > 0 ? usersDetail[0]?.username : ''} and password is ${usersDetail?.length > 0 ? usersDetail[0]?.password : ''}`);
     }
@@ -350,7 +350,7 @@ export class ModuleMetadataSeederService {
 
     }
 
-    async seedSmsTemplates(smsTemplates: CreateSmsTemplateDto[]) {
+    async seedSmsTemplates(smsTemplates: CreateSmsTemplateDto[], moduleMetadata: CreateModuleMetadataDto) {
         if (!smsTemplates) {
             return;
         }
@@ -360,23 +360,26 @@ export class ModuleMetadataSeederService {
             this.logger.log(`Found ${smsTemplate.name} sms template`);
 
             // We need to load the actual template contents. 
-            if (smsTemplate.body) {
-                // const smsTemplateFilePath = path.join(process.cwd(), smsTemplate.body);
-                // smsTemplate.body = fs.readFileSync(smsTemplateFilePath, 'utf-8').toString()
-
+            if (moduleMetadata.name === 'solid-core') {
                 const modulePath = path.dirname(require.resolve('@solidstarters/solid-core'));
-
-                // Resolve the `src` folder
                 const seedDataPath = path.join(modulePath, '../src/seeders/seed-data/sms-templates');
-
-                // Example usage
                 const filePath = path.join(seedDataPath, smsTemplate.body);
-
-
-                smsTemplate.body = fs.readFileSync(filePath, 'utf-8').toString();
-
+                this.logger.log(`Seeding sms template from solid-core at path: ${filePath}`);
+                if (fs.existsSync(filePath)) {
+                    smsTemplate.body = fs.readFileSync(filePath, 'utf-8').toString();
+                }
+            }
+            else {
+                // Check if file exists
+                const emailTemplateHandlebar = `module-metadata/${moduleMetadata.name}/sms-templates/${smsTemplate.body}`
+                const fullPath = path.join(process.cwd(), emailTemplateHandlebar);
+                this.logger.log(`Seeding custom sms template from consuming model at path: ${fullPath}`);
+                if (fs.existsSync(fullPath)) {
+                    smsTemplate.body = fs.readFileSync(fullPath, 'utf-8').toString();
+                }
             }
 
+
             // Save to DB.
             await this.smsTemplateService.removeByName(smsTemplate.name);
             await this.smsTemplateService.create(smsTemplate);

package/src/services/authentication.service.ts

@@ -34,7 +34,7 @@ import { ActiveUserData } from '../interfaces/active-user-data.interface';
 import { HashingService } from './hashing.service';
 import { InvalidatedRefreshTokenError, RefreshTokenIdsStorageService } from './refresh-token-ids-storage.service';
 import { UserService } from './user.service';
-import { EventDetails, EventType } from "../interfaces";
+import { EventDetails, EventType, IMail } from "../interfaces";
 import {
     ForgotPasswordSendVerificationTokenOn,
     RegistrationValidationSource,
@@ -48,6 +48,7 @@ import { UserActivityHistoryService } from './user-activity-history.service';
 import { RequestContextService } from './request-context.service';
 import { ERROR_MESSAGES } from 'src/constants/error-messages';
 import { SUCCESS_MESSAGES } from 'src/constants/success-messages';
+import { MailFactory } from 'src/factories/mail.factory';
 
 
 enum LoginProvider {
@@ -64,7 +65,7 @@ interface otp {
 @Injectable()
 export class AuthenticationService {
     private readonly logger = new Logger(AuthenticationService.name);
-
+    // private readonly mailService: IMail;
     constructor(
         private readonly userService: UserService,
         @InjectRepository(User) private readonly userRepository: Repository<User>,
@@ -77,7 +78,8 @@ export class AuthenticationService {
         private readonly iamConfiguration: ConfigType<typeof iamConfig>,
         private readonly refreshTokenIdsStorage: RefreshTokenIdsStorageService,
         private readonly httpService: HttpService,
-        private readonly mailService: SMTPEMailService,
+        // private readonly mailService: SMTPEMailService,
+        private readonly mailServiceFactory: MailFactory,
         private readonly smsService: Msg91OTPService,
         private readonly eventEmitter: EventEmitter2,
         private readonly settingService: SettingService,
@@ -86,7 +88,9 @@ export class AuthenticationService {
         private readonly commonConfiguration: ConfigType<typeof commonConfig>,
         private readonly userActivityHistoryService: UserActivityHistoryService,
         private readonly requestContextService: RequestContextService,
-    ) { }
+    ) {
+        // this.mailService = this.mailServiceFactory.getMailService();
+     }
 
     private async getConfig(key: string): Promise<any> {
         return this.settingService.getConfigValue(key);
@@ -253,8 +257,8 @@ export class AuthenticationService {
 
     private async notifyUserOnForcePasswordChange(user: User, autoGeneratedPwd: string) {
         const companyLogo = await this.getCompanyLogo();
-
-        this.mailService.sendEmailUsingTemplate(
+        const mailService = this.mailServiceFactory.getMailService();
+        mailService.sendEmailUsingTemplate(
             user.email,
             'on-force-password-change',
             {
@@ -268,6 +272,8 @@ export class AuthenticationService {
                 companyLogoUrl: companyLogo
             },
             this.commonConfiguration.shouldQueueEmails,
+            null,
+            null,
             'user',
             user.id
         );
@@ -375,7 +381,8 @@ export class AuthenticationService {
         if (this.iamConfiguration.dummyOtp)
             return; // Do nothing if dummy otp is configured.
         if (registrationValidationSources.includes(RegistrationValidationSource.EMAIL)) {
-            this.mailService.sendEmailUsingTemplate(
+            const mailService = this.mailServiceFactory.getMailService();
+            mailService.sendEmailUsingTemplate(
                 user.email,
                 'otp-on-register',
                 {
@@ -387,6 +394,8 @@ export class AuthenticationService {
                     companyLogoUrl: companyLogo
                 },
                 this.commonConfiguration.shouldQueueEmails,
+                null,
+                null,
                 'user',
                 user.id
             );
@@ -563,7 +572,8 @@ export class AuthenticationService {
         if (this.iamConfiguration.dummyOtp)
             return; // Do nothing if dummy otp is configured.
         if (loginType === RegistrationValidationSource.EMAIL) {
-            this.mailService.sendEmailUsingTemplate(
+            const mailService = this.mailServiceFactory.getMailService();
+            mailService.sendEmailUsingTemplate(
                 user.email,
                 'otp-on-login',
                 {
@@ -575,6 +585,8 @@ export class AuthenticationService {
                     companyLogoUrl: companyLogo
                 },
                 this.commonConfiguration.shouldQueueEmails,
+                null,
+                null,
                 'user',
                 user.id
             );
@@ -767,7 +779,8 @@ export class AuthenticationService {
         const forgotPasswordSendVerificationTokenOn = this.iamConfiguration.forgotPasswordSendVerificationTokenOn;
 
         if (forgotPasswordSendVerificationTokenOn == ForgotPasswordSendVerificationTokenOn.EMAIL) {
-            this.mailService.sendEmailUsingTemplate(
+            const mailService = this.mailServiceFactory.getMailService();
+            mailService.sendEmailUsingTemplate(
                 user.email,
                 'forgot-password',
                 {
@@ -780,6 +793,8 @@ export class AuthenticationService {
                     companyLogoUrl: companyLogo
                 },
                 this.commonConfiguration.shouldQueueEmails,
+                null,
+                null,
                 'user',
                 user.id
             );

package/src/services/mail/elastic-email.service.ts

@@ -9,10 +9,12 @@ import { PdfService } from '../pdf.service';
 import { FileService } from '../file.service';
 import { IMail, MailAttachment, MailAttachmentWrapper } from "../../interfaces";
 import { PublisherFactory } from '../queues/publisher-factory.service';
+import { MailProvider } from 'src/decorators/mail-provider.decorator';
 
 const ElasticEmail = require('@elasticemail/elasticemail-client');
 
 @Injectable()
+@MailProvider()
 export class ElasticEmailService implements IMail {
     private readonly logger = new Logger(ElasticEmailService.name);
     private readonly emailsApi;

package/src/services/mail/smtp-email.service.ts

@@ -1,15 +1,17 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
 import { ConfigType } from '@nestjs/config';
-import { QueueMessage } from 'src/interfaces/mq';
+import Handlebars from "handlebars";
 import commonConfig from 'src/config/common.config';
+import { MailProvider } from 'src/decorators/mail-provider.decorator';
+import { QueueMessage } from 'src/interfaces/mq';
+import { IMail, MailAttachment, MailAttachmentWrapper } from "../../interfaces";
 import { EmailTemplateService } from '../email-template.service';
-import Handlebars from "handlebars";
-import { IMail, MailAttachment } from "../../interfaces";
 import { PublisherFactory } from '../queues/publisher-factory.service';
 
 const nodemailer = require("nodemailer");
 
 @Injectable()
+@MailProvider()
 export class SMTPEMailService implements IMail {
     private readonly logger = new Logger(SMTPEMailService.name);
     private readonly transporter: any;
@@ -33,8 +35,20 @@ export class SMTPEMailService implements IMail {
         });
     }
 
-    async sendEmailUsingTemplate(to: string, templateName: string, templateParams: any, shouldQueueEmails = false, parentEntity = null, parentEntityId = null, attachments: MailAttachment[] = [], cc: string[] = [], bcc: string[] = [], from: string = null): Promise<void> {
-        // Load template and evaluate it. 
+    async sendEmailUsingTemplate(
+        to: string,
+        templateName: string,
+        templateParams: any,
+        shouldQueueEmails = false,
+        wrapperAttachments?: MailAttachmentWrapper[],
+        attachments?: MailAttachment[],
+        parentEntity?: any,
+        parentEntityId?: any,
+        cc?: string[],
+        bcc?: string[],
+        from?: string
+    ) {
+        // Load template and evaluate it.
         const emailTemplate = await this.emailTemplateService.findOneByName(templateName);
         if (!emailTemplate) {
             throw new Error(`Invalid template name ${templateName}`);
@@ -49,10 +63,22 @@ export class SMTPEMailService implements IMail {
         const subject = subjectTemplate(templateParams);
 
         // Finally send the email.
-        await this.sendEmail(to, subject, body, shouldQueueEmails, parentEntity, parentEntityId, attachments, cc, bcc, from);
+        return await this.sendEmail(to, subject, body, shouldQueueEmails, wrapperAttachments, attachments, parentEntity, parentEntityId, cc, bcc, from);
     }
 
-    async sendEmail(to: string, subject: string, body: string, shouldQueueEmails = false, parentEntity = null, parentEntityId = null, attachments: MailAttachment[] = [], cc: string[] = [], bcc: string[] = [], from: string = null): Promise<void> {
+    async sendEmail(
+        to: string,
+        subject: string,
+        body: string,
+        shouldQueueEmails = false,
+        wrapperAttachments?: MailAttachmentWrapper[],
+        attachments?: MailAttachment[],
+        parentEntity?: any,
+        parentEntityId?: any,
+        cc?: string[],
+        bcc?: string[],
+        from?: string
+    ) {
         const message = {
             payload: {
                 from: from || this.commonConfiguration.smtpMail.from,
@@ -69,33 +95,34 @@ export class SMTPEMailService implements IMail {
 
         // Send using queue if the developer has explicitly invoked with true.
         if (shouldQueueEmails === true) {
-            this.sendEmailAsynchronously(message);
+            return this.sendEmailAsynchronously(message);
         }
         // If developer has not, however system config mandates that we send using queue, still we send.
         else if (shouldQueueEmails == false && this.commonConfiguration.shouldQueueEmails === true) {
-            this.sendEmailAsynchronously(message);
+            return this.sendEmailAsynchronously(message);
         }
-        // Else we send synch
+        // Else we send synchronously
         else {
-            await this.sendEmailSynchronously(message);
+            return await this.sendEmailSynchronously(message);
         }
     }
 
     async sendEmailAsynchronously(message) {
         const { to, subject, body } = message.payload;
-        // this.notificationPublisherService.publish(message);
-        // this.emailPublisher.publish(message);
-        // this.emailDbPublisher.publish(message);
-
-        this.publisherFactory.publish(message, 'EmailQueuePublisher');
-
         this.logger.debug(`Queueing email to ${to} with subject ${subject} and body ${body}`);
+        return this.publisherFactory.publish(message, 'SmtpEmailQueuePublisher');
     }
 
-    async sendEmailSynchronously(message: QueueMessage<any>): Promise<void> {
-        const { from, to, subject, body, attachments, cc, bcc } = message.payload;
+    async sendEmailSynchronously(message: QueueMessage<any>) {
+        const { from, to, subject, body, attachments = [], cc, bcc } = message.payload;
 
-        const attachmentsList = attachments.map((attachment: MailAttachment) => {
+        // if any of the required fields are missing, throw an error.
+        if (!from || !to || !subject || !body) {
+            this.logger.error(`Required fields are missing in the email message: ${JSON.stringify(message.payload)}`);
+            return;
+        }
+
+        const attachmentsList = attachments?.map((attachment: MailAttachment) => {
             const attachmentEntry = {
                 filename: attachment.filename,
                 contentType: attachment.contentType,
@@ -107,7 +134,7 @@ export class SMTPEMailService implements IMail {
                 attachmentEntry['content'] = attachment.content;
             }
             return attachmentEntry;
-        });
+        }) || [];
 
         // throw new Error('Random error....');
         const r = await this.transporter.sendMail({

package/src/services/poller.service.ts

@@ -0,0 +1,163 @@
+// src/common/poller/poller.service.ts
+import {
+    Injectable,
+    Logger,
+    OnModuleDestroy,
+    BeforeApplicationShutdown,
+} from '@nestjs/common';
+
+export interface PollOptions {
+    /** Wait after a successful iteration */
+    baseDelayMs?: number;            // default 1000
+    /** Maximum delay after repeated failures */
+    maxDelayMs?: number;             // default 30000
+    /** Per-iteration timeout guard */
+    timeoutPerIterationMs?: number;  // default 60000
+    /** Add jitter to spread load */
+    jitter?: boolean;                // default true
+}
+
+type ProcessNextFn = (queueName: string) => Promise<unknown>;
+
+interface PollerState {
+    queueName: string;
+    processNext: ProcessNextFn;
+    opts: Required<PollOptions>;
+    inFlight: boolean;
+    stopped: boolean;
+    backoff: number;
+    nextTimer?: NodeJS.Timeout;
+}
+
+@Injectable()
+export class PollerService implements OnModuleDestroy, BeforeApplicationShutdown {
+    private readonly logger = new Logger(PollerService.name);
+    private readonly pollers = new Map<string, PollerState>();
+
+    start(queueName: string, processNext: ProcessNextFn, options: PollOptions = {}): void {
+        if (this.pollers.has(queueName)) {
+            this.logger.warn(`Poller "${queueName}" already started; ignoring.`);
+            return;
+        }
+
+        const opts: Required<PollOptions> = {
+            baseDelayMs: options.baseDelayMs ?? 1000,
+            maxDelayMs: options.maxDelayMs ?? 30_000,
+            timeoutPerIterationMs: options.timeoutPerIterationMs ?? 60_000,
+            jitter: options.jitter ?? true,
+        };
+
+        const state: PollerState = {
+            queueName,
+            processNext,
+            opts,
+            inFlight: false,
+            stopped: false,
+            backoff: opts.baseDelayMs,
+            nextTimer: undefined,
+        };
+
+        this.pollers.set(queueName, state);
+        // kick off on next tick
+        setImmediate(() => this.poll(state).catch(() => { }));
+        this.logger.log(`Started poller "${queueName}"`);
+    }
+
+    stop(queueName: string): void {
+        const state = this.pollers.get(queueName);
+        if (!state) return;
+
+        state.stopped = true;
+        if (state.nextTimer) {
+            clearTimeout(state.nextTimer);
+            state.nextTimer = undefined;
+        }
+        this.pollers.delete(queueName);
+        this.logger.log(`Stopped poller "${queueName}"`);
+    }
+
+    stopAll(): void {
+        for (const name of Array.from(this.pollers.keys())) {
+            this.stop(name);
+        }
+    }
+
+    async onModuleDestroy(): Promise<void> {
+        this.stopAll();
+    }
+
+    async beforeApplicationShutdown(): Promise<void> {
+        this.stopAll();
+    }
+
+    // ---- internals ----
+
+    private async poll(state: PollerState): Promise<void> {
+        if (state.stopped || state.inFlight) return;
+        state.inFlight = true;
+
+        try {
+            await this.withTimeout(
+                state.processNext(state.queueName),
+                state.opts.timeoutPerIterationMs,
+            );
+
+            // success: reset backoff and schedule next run after base delay
+            state.backoff = state.opts.baseDelayMs;
+            // this.logger.debug(`[${state.queueName}] iteration completed`);
+            this.schedule(state, state.opts.baseDelayMs);
+        } catch (err: unknown) {
+            const msg = this.errorToString(err);
+            this.logger.error(`[${state.queueName}] iteration failed: ${msg}`);
+
+            // failure: schedule with backoff + optional jitter, then increase backoff
+            const wait = this.computeWait(state.backoff, state.opts);
+            state.backoff = Math.min(state.backoff * 2, state.opts.maxDelayMs);
+            this.schedule(state, wait);
+        } finally {
+            state.inFlight = false;
+        }
+    }
+
+    private schedule(state: PollerState, delayMs: number) {
+        if (state.stopped) return;
+        if (state.nextTimer) clearTimeout(state.nextTimer);
+
+        state.nextTimer = setTimeout(() => {
+            // clear reference before calling poll to avoid re-entrancy confusion
+            state.nextTimer = undefined;
+            this.poll(state).catch(() => { });
+        }, delayMs);
+    }
+
+    private computeWait(currentBackoff: number, opts: Required<PollOptions>): number {
+        if (!opts.jitter) return currentBackoff;
+        // Full jitter: random in [250ms, currentBackoff * 2], clamped to maxDelayMs
+        const doubled = Math.min(currentBackoff * 2, opts.maxDelayMs);
+        const jittered = Math.floor(Math.random() * doubled);
+        return Math.max(250, jittered);
+    }
+
+    private async withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
+        let timer: NodeJS.Timeout | undefined;
+        try {
+            return await Promise.race<T>([
+                p,
+                new Promise<never>((_, rej) => {
+                    timer = setTimeout(() => rej(new Error(`Iteration timed out after ${ms} ms`)), ms);
+                }),
+            ]);
+        } finally {
+            if (timer) clearTimeout(timer);
+        }
+    }
+
+    private errorToString(err: unknown): string {
+        if (err instanceof Error) return err.stack ?? err.message;
+        try {
+            return JSON.stringify(err);
+        } catch {
+            return String(err);
+        }
+    }
+}