ezeas-client 0.1.5

Ezeas Client API SDK (Python, async)

Ezeas Client SDK (Python)

Minimal async client for the Ezeas Client API using HS256 JWT.

This SDK is intended for backend integrations (Python 3.9+). It handles:

• Generating and caching short-lived JWT access tokens using client_id and client_secret
• Sending authenticated requests to the Ezeas Client API
• Minimal error handling for business errors (4xx) vs internal errors (5xx)

Installation

From PyPI (production):

pip install ezeas-client

From TestPyPI (pre-release/testing):

pip install -i https://test.pypi.org/simple/ ezeas-client

Requires Python 3.9+.

Quick start

import asyncio
from ezeas_client import AsyncEzeasClient

async def main() -> None:
    client_id = "your-client-id"
    client_secret = "your-client-secret"

    async with AsyncEzeasClient(
        client_id=client_id,
        client_secret=client_secret,
        _base_url="https://www.ezeas.com",  # or "http://localhost:8000" for development
    ) as client:
        # Create contact
        contact_result = await client.create_contact(
            {
                "external_id": "EXT-123",
                "employee_number": "EMP-001",
                "first_name": "Jane",
                "last_name": "Doe",
                "mobile": "0400000000",
                "email": "[e-mail]",
                "tenure_date": "2025-11-01",
            }
        )
        print("Contact result:", contact_result)

        # Create timesheet
        timesheet_result = await client.create_timesheet(
            {
                "job_code": "JOB-001",
                "timesheet_entries": [
                    {
                        "date": "2025-11-01",
                        "hours_ordinary": 8.0,
                        "hours_time_and_half": 2.0,
                        "hours_double_time": 0.0,
                    },
                    {
                        "date": "2025-11-02",
                        "hours_ordinary": 7.5,
                        "hours_time_and_half": 0.0,
                        "hours_double_time": 0.0,
                    },
                ],
            }
        )
        print("Timesheet result:", timesheet_result)

if __name__ == "__main__":
    asyncio.run(main())

Types

The SDK uses TypedDict internally. The logical shapes are:

from typing import TypedDict, List

class ContactInput(TypedDict):
    external_id: str
    employee_number: str
    first_name: str
    last_name: str
    mobile: str
    email: str
    tenure_date: str


class TimesheetEntry(TypedDict):
    date: str
    hours_ordinary: float
    hours_time_and_half: float
    hours_double_time: float


class TimesheetInput(TypedDict):
    job_code: str
    timesheet_entries: List[TimesheetEntry]

You can pass either these shapes or any plain dict with the same keys.

API

AsyncEzeasClient(client_id, client_secret, _base_url=None)

Creates a new async client instance.

• client_id: string issued by Ezeas
• client_secret: shared secret issued by Ezeas
• _base_url: override base URL (defaults to https://www.ezeas.com)

The recommended usage is via async with:

async with AsyncEzeasClient(client_id, client_secret, _base_url="http://localhost:8000") as client:
    ...

await client.create_contact(data)

Creates a contact for the account associated with this client_id.

• data: ContactInput (or a plain dict with the same shape)

Returns the parsed JSON response from the Ezeas API (or None if the response has no body).

await client.create_timesheet(data)

Creates a timesheet for the account associated with this client_id.

• data: TimesheetInput (or a plain dict with the same shape)

Returns the parsed JSON response from the Ezeas API (or None if the response has no body).

Error handling

Internally, the SDK uses httpx.AsyncClient. The current behaviour is:

• For 2xx responses:
  • Parses and returns JSON (or None if the body is empty).
• For 4xx responses:
  • Raises Exception with the backend error payload as text.
• For 5xx responses:
  • Raises Exception with a message in the form:
    • "Internal server error <status>: <body>"

You can wrap calls in your own try/except logic to map these to your application's error model.

Token format

The SDK generates short-lived JWT access tokens using HS256:

• Header:
  • alg: "HS256"
  • typ: "JWT"
• Payload:
  • sub: client_id
  • client_id: client_id
  • iat: issued-at (seconds since epoch)
  • exp: expiry (seconds since epoch, typically iat + 900)

The token is signed with client_secret.

The Ezeas API validates this token server-side and resolves the associated account from the client credentials.