Issue 24: SDK Heartbeat Loop and State Machine

[laraibg786]

Goal

Build a background heartbeat scheduler with an internal state machine (ACTIVE, GRACE, EXPIRED, REVOKED) and callback hooks for state changes. The SDK manages the polling lifecycle; the host app registers callbacks.

Requirements

Functional

• client.start_heartbeat(session_token, interval_seconds=300) → spawns background loop.
• client.stop_heartbeat() → gracefully stops the loop.
• State machine transitions: ACTIVE → GRACE → EXPIRED; REVOKED is terminal.
• on_status_change(old_state, new_state, metadata) callback fired on every state transition.
• on_error(exception) callback fired on unrecoverable heartbeat failure.
• Retry up to 3 times on transient errors before calling on_error.

Technical

• Threading: Use threading.Thread for sync; asyncio task for async.
• Configurable interval: Default 5 minutes; demo mode supports 1 minute.
• Graceful shutdown: Wait for in-flight heartbeat before stopping.

Acceptance Criteria

• start_heartbeat() spawns background loop.
• State transitions fire on_status_change callback.
• stop_heartbeat() cleanly terminates the loop.
• Error recovery retries 3 times before calling on_error.

Dependencies

• Blocked by: Issue 19: Heartbeat Evaluation Logic #19, Issue 20: Heartbeat Grace Period Enforcement #20, Issue 23: Python SDK Core Client #23.
• Blocks: Issue 25: SDK Test Suite #25, Issue 27: SDK Demo Application #27.