Type: Documentation / developer experience
Not a code defect — the SDK behaves as its type signatures declare. This is about making those contracts discoverable so callers don't guess wrong.
Environment: fulcra-api 0.1.38 (PyPI), pandas 2.3.3, Python 3.11. Verified against method signatures via inspect; I couldn't complete the OAuth device flow from my environment (Auth0 device-code endpoint returned 403 through my network egress), so the DataFrame column/index names below are inferred defensively, not confirmed against live responses.
Summary: While building example code, I assumed FulcraAPI.sleep_cycles() returned a list[dict] and iterated it that way. It actually returns a pandas DataFrame (as its signature declares: -> pandas.core.frame.DataFrame). The SDK was correct; my assumption was wrong. Root cause: return types — and DataFrame schemas in particular — aren't surfaced where a caller reads them.
Ask 1 — state the return type in each data-access method's docstring. Return types are mixed: DataFrame (sleep_cycles, metric_time_series, location_time_series) vs List[Dict] (calendar_events, apple_workouts, apple_location_updates/visits, calendars). A one-line Returns: note per method would remove the ambiguity.
Ask 2 — document each DataFrame's index and columns (name, dtype, unit). For sleep_cycles() I had to probe for column names (start_time/duration/end_time) because the layout isn't documented — including whether duration is seconds or minutes.
Type: Documentation / developer experience
Not a code defect — the SDK behaves as its type signatures declare. This is about making those contracts discoverable so callers don't guess wrong.
Environment: fulcra-api 0.1.38 (PyPI), pandas 2.3.3, Python 3.11. Verified against method signatures via inspect; I couldn't complete the OAuth device flow from my environment (Auth0 device-code endpoint returned 403 through my network egress), so the DataFrame column/index names below are inferred defensively, not confirmed against live responses.
Summary: While building example code, I assumed FulcraAPI.sleep_cycles() returned a list[dict] and iterated it that way. It actually returns a pandas DataFrame (as its signature declares: -> pandas.core.frame.DataFrame). The SDK was correct; my assumption was wrong. Root cause: return types — and DataFrame schemas in particular — aren't surfaced where a caller reads them.
Ask 1 — state the return type in each data-access method's docstring. Return types are mixed: DataFrame (sleep_cycles, metric_time_series, location_time_series) vs List[Dict] (calendar_events, apple_workouts, apple_location_updates/visits, calendars). A one-line Returns: note per method would remove the ambiguity.
Ask 2 — document each DataFrame's index and columns (name, dtype, unit). For sleep_cycles() I had to probe for column names (start_time/duration/end_time) because the layout isn't documented — including whether duration is seconds or minutes.