fix(integration): add venue/promoter accessor functions to public API (#248)

Three more public wrapper functions for term-meta accessors that
downstream consumers (extrachill-events templates, location-meta,
abilities) call frequently and would otherwise need to keep using
class_exists() guards against \DataMachineEvents\Core\Venue_Taxonomy
and Promoter_Taxonomy directly.

- data_machine_events_get_venue_data(int $term_id): ?array
- data_machine_events_get_venue_address(int $term_id, ?array): string
- data_machine_events_get_promoter_data(int $term_id): ?array

All declared idempotently with function_exists() guards. Degrade to
null/empty when the underlying classes are missing.

Refs #244

Co-authored-by: homeboy-ci[bot] <266378653+homeboy-ci[bot]@users.noreply.github.com>

Author: chubes4

docs/integration-api.md

@@ -169,6 +169,24 @@ Pass-through parameters mirror the underlying ability:
 
 Returns `[ 'posts' => WP_Post[], 'total' => int, … ]`.
 
+### `data_machine_events_get_venue_data( int $term_id ): ?array`
+
+Return the structured venue data array stored against a `venue` term —
+address fields, lat/lng, website, etc. Returns `null` when the term does
+not exist or has no venue data. Use this instead of calling
+`Venue_Taxonomy::get_venue_data()` directly.
+
+### `data_machine_events_get_venue_address( int $term_id, ?array $venue_data = null ): string`
+
+Return the formatted single-line address for a venue term. Pass
+`$venue_data` if you already have it to avoid an extra meta read. Use this
+instead of `Venue_Taxonomy::get_formatted_address()`.
+
+### `data_machine_events_get_promoter_data( int $term_id ): ?array`
+
+Return the structured promoter data array stored against a `promoter` term.
+Use this instead of `Promoter_Taxonomy::get_promoter_data()`.
+
 ### `data_machine_events_get_event_datetime( int $post_id ): string`
 
 Return the start datetime string for an event, or empty string when no row

inc/public-api.php

@@ -190,6 +190,74 @@ function data_machine_events_query_events( array $params ): array {
 	}
 }
 
+if ( ! function_exists( 'data_machine_events_get_venue_data' ) ) {
+	/**
+	 * Get raw venue term metadata.
+	 *
+	 * Returns the structured venue data array stored against a venue term —
+	 * address, lat/lng, city, region, country, website, etc. Returns null when
+	 * the term does not exist or has no associated venue data.
+	 *
+	 * @since 0.32.1
+	 *
+	 * @param int $term_id Venue term ID.
+	 * @return array|null Venue data array or null.
+	 */
+	function data_machine_events_get_venue_data( int $term_id ): ?array {
+		if ( ! class_exists( '\DataMachineEvents\Core\Venue_Taxonomy' ) ) {
+			return null;
+		}
+
+		$data = \DataMachineEvents\Core\Venue_Taxonomy::get_venue_data( $term_id );
+		return is_array( $data ) ? $data : null;
+	}
+}
+
+if ( ! function_exists( 'data_machine_events_get_venue_address' ) ) {
+	/**
+	 * Get the formatted single-line address string for a venue term.
+	 *
+	 * Combines street, city, region, postal code, and country into a
+	 * comma-delimited human-readable address.
+	 *
+	 * @since 0.32.1
+	 *
+	 * @param int        $term_id    Venue term ID.
+	 * @param array|null $venue_data Optional pre-fetched venue data array
+	 *                               to avoid an extra term meta lookup.
+	 * @return string Formatted address or empty string.
+	 */
+	function data_machine_events_get_venue_address( int $term_id, ?array $venue_data = null ): string {
+		if ( ! class_exists( '\DataMachineEvents\Core\Venue_Taxonomy' ) ) {
+			return '';
+		}
+
+		return (string) \DataMachineEvents\Core\Venue_Taxonomy::get_formatted_address( $term_id, $venue_data );
+	}
+}
+
+if ( ! function_exists( 'data_machine_events_get_promoter_data' ) ) {
+	/**
+	 * Get raw promoter term metadata.
+	 *
+	 * Returns the structured promoter data array stored against a promoter term.
+	 * Returns null when the term does not exist or has no associated data.
+	 *
+	 * @since 0.32.1
+	 *
+	 * @param int $term_id Promoter term ID.
+	 * @return array|null Promoter data array or null.
+	 */
+	function data_machine_events_get_promoter_data( int $term_id ): ?array {
+		if ( ! class_exists( '\DataMachineEvents\Core\Promoter_Taxonomy' ) ) {
+			return null;
+		}
+
+		$data = \DataMachineEvents\Core\Promoter_Taxonomy::get_promoter_data( $term_id );
+		return is_array( $data ) ? $data : null;
+	}
+}
+
 if ( ! function_exists( 'data_machine_events_get_event_datetime' ) ) {
 	/**
 	 * Get the start datetime for an event, formatted as a string.