<?php
/**
 * Reads the bundled dataset. No network, no database writes.
 */
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * @return array{generated:string,total:int,states:array} Empty arrays on failure.
 */
function usrs_data() {
	static $cache = null;
	if ( null !== $cache ) {
		return $cache;
	}
	$file = USRS_PATH . 'includes/data.json';
	if ( ! file_exists( $file ) ) {
		$cache = array( 'generated' => '', 'total' => 0, 'states' => array() );
		return $cache;
	}
	// Bundled file, read from disk -- wp_remote_get would be wrong here and
	// WP_Filesystem is for writes.
	$raw  = file_get_contents( $file ); // phpcs:ignore WordPress.WP.AlternativeFunctions
	$json = json_decode( $raw, true );
	$cache = is_array( $json ) && isset( $json['states'] )
		? $json
		: array( 'generated' => '', 'total' => 0, 'states' => array() );
	return $cache;
}

/** One state by two-letter code, or null. */
function usrs_state( $code ) {
	$code = strtoupper( sanitize_text_field( $code ) );
	foreach ( usrs_data()['states'] as $s ) {
		if ( $s['code'] === $code ) {
			return $s;
		}
	}
	return null;
}

/**
 * "August 2026": the month the bundled dataset was compiled, for the visible
 * "Data as of" caption. Empty if the dataset carries no date.
 */
function usrs_as_of() {
	$generated = usrs_data()['generated'];
	$time      = $generated ? strtotime( $generated . ' 00:00:00 UTC' ) : false;
	return $time ? wp_date( 'F Y', $time, new DateTimeZone( 'UTC' ) ) : '';
}