Add OBS overlays (goal, timer, counter, alerts) with ETag polling

Align timer state key with rules engine (timer_ends_at).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
shadowdaoandClaude Sonnet 5.5 committed 2026-11-15 08:45:22 -08:00
1 parent 7155396312
commit 65082fb2f5
10 files changed
+815

No files matched your search

+135
View File
@@ -0,0 +1,135 @@
<?php
declare( strict_types=1 );
namespace StreamGoals\Overlay;
use StreamGoals\Core\Money;
/**
* Pure, WordPress-free payload builders. Everything returned here is public-safe.
*/
final class Payloads {
public const ANON_NAME = 'Anonymous';
private const SYMBOLS = array( 'USD' => '$', 'EUR' => '€', 'GBP' => '£', 'JPY' => '¥', 'CAD' => 'CA$', 'AUD' => 'A$' );
public static function money( int $minor, string $currency ): string {
$m = new Money( max( 0, $minor ), strtoupper( $currency ) );
$amount = $m->toDecimalString();
[ $whole, $frac ] = array_pad( explode( '.', $amount, 2 ), 2, null );
$whole = preg_replace( '/\B(?=(\d{3})+(?!\d))/', ',', $whole );
$amount = null === $frac ? $whole : $whole . '.' . $frac;
$cur = strtoupper( $currency );
return isset( self::SYMBOLS[ $cur ] ) ? self::SYMBOLS[ $cur ] . $amount : $cur . ' ' . $amount;
}
public static function percent( int $raised, int $target ): int {
if ( $target <= 0 ) {
return 0;
}
return max( 0, min( 100, intdiv( max( 0, $raised ) * 100, $target ) ) );
}
public static function goal( ?array $goal, int $raised ): array {
if ( null === $goal ) {
return array( 'active' => false, 'title' => '', 'raised_minor' => 0, 'target_minor' => 0, 'percent' => 0,
'currency' => 'USD', 'raised_display' => '', 'target_display' => '' );
}
$cur = strtoupper( (string) ( $goal['currency'] ?? 'USD' ) );
$target = max( 0, (int) ( $goal['target_minor'] ?? 0 ) );
$raised = max( 0, $raised );
return array(
'active' => true,
'title' => (string) ( $goal['title'] ?? '' ),
'raised_minor' => $raised,
'target_minor' => $target,
'percent' => self::percent( $raised, $target ),
'currency' => $cur,
'raised_display' => self::money( $raised, $cur ),
'target_display' => self::money( $target, $cur ),
);
}
/**
* @param string|null $endsAt sg_state `timer_ends_at` (epoch seconds, or a UTC datetime string).
* @param string|null $pausedRemaining sg_state `paused_remaining` seconds; non-null means paused.
*/
public static function timer( ?string $endsAt, ?string $pausedRemaining, int $now ): array {
$ends = self::toEpoch( $endsAt );
if ( null !== $pausedRemaining && '' !== $pausedRemaining && is_numeric( $pausedRemaining ) ) {
$rem = max( 0, (int) $pausedRemaining );
return array( 'active' => true, 'paused' => true, 'ends_at' => $now + $rem, 'remaining_seconds' => $rem, 'server_now' => $now );
}
if ( null === $ends ) {
return array( 'active' => false, 'paused' => false, 'ends_at' => 0, 'remaining_seconds' => 0, 'server_now' => $now );
}
// remaining_seconds is only meaningful when paused; a running timer's value would change every second and defeat 304s.
return array( 'active' => true, 'paused' => false, 'ends_at' => $ends, 'remaining_seconds' => 0, 'server_now' => $now );
}
public static function counter( string $label, int $value ): array {
return array( 'label' => $label, 'value' => $value );
}
/**
* @param array<int,array<string,mixed>> $rows
* @param int|null $since Null means "first poll": no alerts, just a baseline last_id.
*/
public static function alerts( array $rows, ?int $since, int $limit = 10 ): array {
$safe = array();
foreach ( $rows as $r ) {
if ( 'completed' !== ( $r['status'] ?? '' ) || 'approved' !== ( $r['moderation'] ?? '' ) ) {
continue;
}
$safe[] = $r;
}
usort( $safe, static fn( $a, $b ) => (int) $a['id'] <=> (int) $b['id'] );
$lastId = $since ?? 0;
foreach ( $safe as $r ) {
$lastId = max( $lastId, (int) $r['id'] );
}
if ( null === $since ) {
return array( 'alerts' => array(), 'last_id' => $lastId );
}
$alerts = array();
foreach ( $safe as $r ) {
if ( (int) $r['id'] <= $since ) {
continue;
}
$cur = strtoupper( (string) ( $r['currency'] ?? 'USD' ) );
$anon = ! empty( $r['is_anonymous'] );
$name = trim( (string) ( $r['donor_name'] ?? '' ) );
$alerts[] = array(
'id' => (int) $r['id'],
'name' => ( $anon || '' === $name ) ? self::ANON_NAME : $name,
'amount_minor' => (int) $r['base_minor'],
'amount_display' => self::money( (int) $r['base_minor'], $cur ),
'currency' => $cur,
'message' => (string) ( $r['message'] ?? '' ),
);
}
$alerts = array_slice( $alerts, 0, max( 1, $limit ) );
if ( $alerts ) {
$lastId = max( $since, (int) end( $alerts )['id'] ); // don't skip rows beyond the limit
}
return array( 'alerts' => $alerts, 'last_id' => $lastId );
}
/** Strong ETag over the payload, ignoring the volatile server_now so unchanged data yields 304s. */
public static function etag( array $payload ): string {
unset( $payload['server_now'] );
return '"' . md5( (string) json_encode( $payload, JSON_UNESCAPED_UNICODE ) ) . '"';
}
private static function toEpoch( ?string $v ): ?int {
if ( null === $v || '' === $v ) {
return null;
}
if ( ctype_digit( $v ) ) {
return (int) $v;
}
$t = strtotime( $v . ' UTC' );
return false === $t ? null : $t;
}
}