@spec copy_events(term(), term(), keyword()) ::
  {:ok, copy_result()} | {:error, term()}

Copies events from a local source page stream into a target.

Supported sources:

• {:local, filter} - page local storage using page_events/2
• filter - shorthand for {:local, filter}
• :local - use opts[:filter]

Supported targets:

• :local - import each page through import_events/2
• a one-arity function - called once per non-empty page
• {:fun, function} - same as a one-arity function

Options are the same as page_events/2. :progress may be a two-arity callback receiving events such as :page, :imported, and :completed.

@spec get_server(
  String.t(),
  keyword()
) :: {:ok, server()} | :error | {:error, term()}

Fetches a single normalized sync server definition.

Returns :error when the server id is unknown.

@spec import_events(
  [map()],
  keyword()
) :: {:ok, map()} | {:error, term()}

Imports a batch of events through Parrhesia.API.Events.publish_many/2.

The caller controls validation/authentication through the supplied request context. Sync callers normally pass %RequestContext{caller: :sync} for already-validated remote relay pages.

@spec list_servers(keyword()) :: {:ok, [server()]} | {:error, term()}

Lists all configured sync servers, including their runtime state.

@spec page_events(
  map(),
  keyword()
) :: {:ok, event_page()} | {:error, term()}

Pages local stored events with the same policy checks as relay reads.

This is the in-process counterpart to the SYNC-PAGE wire frame. It is intended for application-level clone/fetch flows that first narrow access with their own policy layer and then need a stable keyset cursor over matching Nostr events.

Required options:

• :context - a Parrhesia.API.RequestContext

Supported options:

• :limit or :page_size - positive page size, defaults to 500
• :order - :asc (default) or :desc
• :after_key / :until_key - {created_at, event_id_hex} keyset bounds
• :authorize_event - optional callback for app-level per-event filtering

@spec put_server(
  map(),
  keyword()
) :: {:ok, server()} | {:error, term()}

Creates or replaces a sync server definition.

@spec remove_server(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Removes a stored sync server definition and stops its worker if it is running.

@spec server_stats(
  String.t(),
  keyword()
) :: {:ok, map()} | :error | {:error, term()}

Returns runtime counters and timestamps for a single sync server.

Returns :error when the server id is unknown.

@spec start_server(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Marks a sync server as running and reconciles its worker state.

@spec stop_server(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Stops a sync server and records a disconnect timestamp in runtime state.

@spec stream_events(
  map(),
  keyword()
) :: {:ok, Enumerable.t()} | {:error, term()}

Returns a lazy stream over page_events/2 using ascending keyset pagination.

Stream pages are fetched only as the enumerable is consumed. If a later page fails, the stream exits with {:parrhesia_sync_page_error, reason}.

@spec sync_health(keyword()) :: {:ok, map()} | {:error, term()}

Returns a health summary for the sync subsystem.

@spec sync_now(
  String.t(),
  keyword()
) :: :ok | {:error, term()}

Triggers an immediate sync run for a server.

@spec sync_stats(keyword()) :: {:ok, map()} | {:error, term()}

Returns aggregate counters across all configured sync servers.