# `PhoenixKit.ScheduledJobs.Handler`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/scheduled_jobs/handler.ex#L1)

Behaviour for scheduled job handlers.

Implement this behaviour to create handlers for different types of scheduled jobs.
The scheduler will dynamically load and call handlers based on the `handler_module`
stored in the scheduled job record.

## Example Implementation

    defmodule MyApp.Posts.ScheduledPostHandler do
      @behaviour PhoenixKit.ScheduledJobs.Handler

      @impl true
      def job_type, do: "publish_post"

      @impl true
      def resource_type, do: "post"

      @impl true
      def execute(post_uuid, _args) do
        case MyApp.Posts.get_post(post_uuid) do
          nil -> {:error, :not_found}
          post -> MyApp.Posts.publish_post(post)
        end
      end
    end

## Callbacks

- `job_type/0` - Returns a unique string identifying this job type (e.g., "publish_post", "send_email")
- `resource_type/0` - Returns the type of resource this handler operates on (e.g., "post", "email")
- `execute/2` - Executes the job. Receives the resource_uuid and args map. Returns `:ok` or `{:ok, result}` on success, `{:error, reason}` on failure.

## Return Values

The `execute/2` callback should return:
- `:ok` - Job completed successfully
- `{:ok, result}` - Job completed successfully with a result (logged but not stored)
- `{:error, reason}` - Job failed, will be retried if attempts < max_attempts

## Registration

Handlers don't need to be explicitly registered. The scheduler dynamically loads
the handler module from the job record and calls the execute function.

# `execute`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/scheduled_jobs/handler.ex#L78)

```elixir
@callback execute(resource_uuid :: binary(), args :: map()) ::
  :ok | {:ok, any()} | {:error, any()}
```

Executes the scheduled job.

## Parameters

- `resource_uuid` - The UUID of the target resource
- `args` - A map of additional arguments stored with the job

## Returns

- `:ok` - Job completed successfully
- `{:ok, result}` - Job completed successfully with additional result data
- `{:error, reason}` - Job failed (will be retried if attempts < max_attempts)

# `job_type`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/scheduled_jobs/handler.ex#L54)

```elixir
@callback job_type() :: String.t()
```

Returns the job type identifier for this handler.

This should be a unique string that identifies the type of job.
Examples: "publish_post", "send_email", "send_notification"

# `resource_type`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/scheduled_jobs/handler.ex#L62)

```elixir
@callback resource_type() :: String.t()
```

Returns the resource type this handler operates on.

This should match the `resource_type` field in the scheduled job record.
Examples: "post", "email", "notification"

---

*Consult [api-reference.md](api-reference.md) for complete listing*