# Copyright (c) CloudZero - ALL RIGHTS RESERVED - PROPRIETARY AND CONFIDENTIAL
# Unauthorized copying of this file and/or project, via any medium is strictly prohibited.
# Direct all questions to legal@cloudzero.com

from typing import Any, NotRequired, TypedDict

DATA_KEY = 'data'
CURSOR_KEY = 'cursor'


class IapiResponse(TypedDict):
    """Typed envelope for an internal API (IAPI) response.

    The IAPI wire contract is a JSON object with two meaningful keys:

    - data (required): the response payload.
    - cursor (optional): an opaque pagination token. When present, the IAPI
      client paginates automatically by re-invoking with the cursor until the
      server stops returning one.

    IapiResponse is a TypedDict, so an instance is a plain dict at runtime.
    Constructing IapiResponse(data=result) produces {'data': result} and
    serializes/validates exactly like the hand-built dicts handlers returned
    before. This keeps the wire format unchanged while giving handler authors a
    discoverable, type-checked envelope:

        return IapiResponse(data=result)
        return IapiResponse(data=page, cursor=next_token)
    """

    data: Any
    cursor: NotRequired[str]
