Credits

Access via client.credits.

signtraker.credits.CreditsClient

CreditsClient(api_key: Optional[str] = None, base_url: Optional[str] = None, *, subdomain: Optional[str] = None, timeout_seconds: Optional[float] = None, max_retries: Optional[int] = None, retry_backoff_seconds: Optional[float] = None)

Bases: BaseClient

Client for the /api/credits endpoints.

Source code in signtraker/base_client.py

def __init__(
    self,
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    *,
    subdomain: Optional[str] = None,
    timeout_seconds: Optional[float] = None,
    max_retries: Optional[int] = None,
    retry_backoff_seconds: Optional[float] = None,
) -> None:
    """Initialize the base client.

    The base URL is resolved from the first available of: ``base_url``,
    ``subdomain`` (expanded to ``https://{subdomain}.signtraker.com``), the
    ``SIGNTRAKER_BASE_URL`` env var, or the ``SIGNTRAKER_SUBDOMAIN`` env var.

    Args:
        api_key: API key. Falls back to the ``SIGNTRAKER_API_KEY`` env var.
        base_url: Full API base URL (e.g.
            ``"https://acme.signtraker.com"``). Overrides ``subdomain``.
        subdomain: Tenant subdomain used to build the base URL when
            ``base_url`` is not provided.
        timeout_seconds: Per-request timeout. Falls back to env/default.
        max_retries: Retry attempts for transient failures.
        retry_backoff_seconds: Base backoff between retries (exponential).

    Raises:
        AuthenticationError: If no API key can be resolved.
        SignTrakerConfigError: If no base URL or subdomain can be resolved.
    """
    self.api_key = api_key or _getenv_with_alias(ENV_API_KEY, ENV_API_KEY_ALT)
    if not self.api_key:
        raise AuthenticationError(
            "API key is required. Set SIGNTRAKER_API_KEY or pass api_key."
        )
    self.base_url = self._resolve_base_url(base_url, subdomain)
    self.timeout_seconds = (
        float(timeout_seconds)
        if timeout_seconds is not None
        else _parse_env_float(ENV_TIMEOUT_SECONDS, DEFAULT_TIMEOUT_SECONDS)
    )
    self.max_retries = (
        int(max_retries)
        if max_retries is not None
        else _parse_env_int(ENV_MAX_RETRIES, DEFAULT_MAX_RETRIES)
    )
    self.retry_backoff_seconds = (
        float(retry_backoff_seconds)
        if retry_backoff_seconds is not None
        else _parse_env_float(
            ENV_RETRY_BACKOFF_SECONDS, DEFAULT_RETRY_BACKOFF_SECONDS
        )
    )
    self.session = requests.Session()
    self.session.headers.update(
        {
            "Authorization": f"ST-API {self.api_key}",
            "Content-Type": "application/json",
            "Accept": "application/json",
        }
    )

list_awards

list_awards(*, awarded_to: Optional[int] = None, filter: Optional[str] = None, top: Optional[int] = None, skip: Optional[int] = None, orderby: Optional[ODataValue] = None, select: Optional[ODataValue] = None) -> List[Dict[str, Any]]

List credit awards, optionally filtered to a specific recipient.

Parameters:

Name	Type	Description	Default
awarded_to	Optional[int]	Agent ID to filter awards granted to that agent.	None
filter	Optional[str]	OData $filter expression.	None
top	Optional[int]	OData $top (maximum number of records to return).	None
skip	Optional[int]	OData $skip (number of records to skip).	None
orderby	Optional[ODataValue]	OData $orderby value or sequence of fields.	None
select	Optional[ODataValue]	OData $select value or sequence of fields.	None

Returns:

Type	Description
List[Dict[str, Any]]	The list of award records.

Raises:

Type	Description
AuthenticationError	If the API key is invalid.
SignTrakerError	For other API errors.

Source code in signtraker/credits.py

def list_awards(
    self,
    *,
    awarded_to: Optional[int] = None,
    filter: Optional[str] = None,
    top: Optional[int] = None,
    skip: Optional[int] = None,
    orderby: Optional[ODataValue] = None,
    select: Optional[ODataValue] = None,
) -> List[Dict[str, Any]]:
    """List credit awards, optionally filtered to a specific recipient.

    Args:
        awarded_to: Agent ID to filter awards granted to that agent.
        filter: OData ``$filter`` expression.
        top: OData ``$top`` (maximum number of records to return).
        skip: OData ``$skip`` (number of records to skip).
        orderby: OData ``$orderby`` value or sequence of fields.
        select: OData ``$select`` value or sequence of fields.

    Returns:
        The list of award records.

    Raises:
        AuthenticationError: If the API key is invalid.
        SignTrakerError: For other API errors.
    """
    params = build_odata_params(
        filter=filter,
        top=top,
        skip=skip,
        orderby=orderby,
        select=select,
        extra={"awardedTo": awarded_to},
    )
    return cast(List[Dict[str, Any]], self.get("api/credits/awards", params))

create_award

create_award(award: Dict[str, Any]) -> Dict[str, Any]

Create a credit award.

Parameters:

Name	Type	Description	Default
award	Dict[str, Any]	The award payload. Restrictions may include Printing.	required

Returns:

Type	Description
Dict[str, Any]	The created award record.

Raises:

Type	Description
ValidationError	If the payload is invalid.
AuthenticationError	If the API key is invalid.
SignTrakerError	For other API errors.

Source code in signtraker/credits.py

def create_award(self, award: Dict[str, Any]) -> Dict[str, Any]:
    """Create a credit award.

    Args:
        award: The award payload. ``Restrictions`` may include ``Printing``.

    Returns:
        The created award record.

    Raises:
        ValidationError: If the payload is invalid.
        AuthenticationError: If the API key is invalid.
        SignTrakerError: For other API errors.
    """
    return cast(Dict[str, Any], self.post("api/credits/awards", json_data=award))