<?php
/**
 * @package ActivityLog404
 */

namespace ActivityLog404\Import;

defined( 'ABSPATH' ) || exit;

/**
 * Another activity log's history, read straight from its own tables (#21).
 *
 * A source is READ-ONLY toward those tables: it runs SELECTs and SHOW
 * COLUMNS, never an INSERT, UPDATE, DELETE, ALTER or DROP -- the site may be
 * trying us out with the other plugin still installed, and its history is
 * not ours to touch. It needs nothing of the other plugin's code, so an
 * import works with that plugin deactivated or deleted (its tables stay
 * behind on uninstall unless its owner chose otherwise).
 *
 * Rows are read in ascending source-id order, `$after_id` exclusive, which
 * is what makes an import resumable from one integer and idempotent per row.
 */
interface Source {

	/** Stable key, stored in every imported row's `import_source` (at most 20 characters). */
	public function key(): string;

	/** The plugin's name as its users know it, for the screen and for generic summaries. */
	public function label(): string;

	/** Whether the tables exist, and whether their shape is one this importer reads. */
	public function detect(): Detection;

	/**
	 * The whole source as it stands: how many rows, and the first and last
	 * timestamps among them (UTC, `Y-m-d H:i:s`, null when there are none),
	 * and the highest id -- the snapshot a run imports up to.
	 *
	 * @return array{count: int, first: ?string, last: ?string, max_id: int}
	 */
	public function preview(): array;

	/**
	 * The next rows after `$after_id`, up to and including `$max_id`, mapped
	 * to this plugin's event model.
	 *
	 * @param int $after_id Last source id already processed.
	 * @param int $max_id   The highest source id this run imports.
	 * @param int $limit    At most this many rows.
	 * @return array<int, array<string, mixed>> Each: source_id (int), timestamp (UTC), user_id, user_email, ip (as the source recorded it), event_type, object_type, object_id, summary, details.
	 */
	public function rows( int $after_id, int $max_id, int $limit ): array;
}