@spec cancel_scheduled() :: {:ok, non_neg_integer()}

Cancels all scheduled sitemap jobs.

This is called when scheduling is disabled.

@spec ensure_cache_warm() ::
  {:ok, Oban.Job.t()} | :file_exists | :disabled | {:error, term()}

Ensures sitemap file exists on application startup.

With file-only architecture, this is optional - sitemap will be generated on first request if file doesn't exist. Use this for explicit pre-warming.

Returns

• {:ok, job} - Regeneration job scheduled (file doesn't exist)
• :file_exists - Sitemap file already exists
• :disabled - Sitemap module is disabled

Examples

# In Application.start/2 or supervisor child
PhoenixKit.Modules.Sitemap.SchedulerWorker.ensure_cache_warm()

Performs sitemap regeneration.

This callback is invoked by Oban when the scheduled job runs. It checks if scheduling is still enabled before regenerating.

@spec regenerate_module_now(String.t()) :: {:ok, Oban.Job.t()} | {:error, term()}

Triggers immediate regeneration for a specific source module.

Regenerates only the specified source's sitemap file and rebuilds the index.

@spec regenerate_now() :: {:ok, Oban.Job.t()} | {:error, term()}

Triggers immediate sitemap regeneration.

This creates a job that runs immediately, bypassing the schedule.

@spec schedule(keyword()) :: {:ok, Oban.Job.t()} | {:error, term()} | :disabled

Schedules the next sitemap regeneration.

The job is scheduled based on sitemap_schedule_interval_hours setting. If scheduling is disabled, no job is created.

Options

• :delay_hours - Override the configured interval (optional)

Examples

# Schedule with configured interval
PhoenixKit.Modules.Sitemap.SchedulerWorker.schedule()

# Schedule with custom delay
PhoenixKit.Modules.Sitemap.SchedulerWorker.schedule(delay_hours: 1)

@spec schedule_next() :: {:ok, Oban.Job.t()} | {:error, term()} | :disabled

Schedules the next regeneration after current job completes.

@spec status() :: map()

Returns the current scheduling status and next run time.