Ezeas Client API SDK (Python, async)
Project description
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_idandclient_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
Requires Python 3.9+.
Quick start
import asyncio
from ezeas_client import EzeasClient
async def main() -> None:
client_id = "your-client-id"
client_secret = "your-client-secret"
async with EzeasClient(
client_id=client_id,
client_secret=client_secret,
) 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": "jane.doe@example.com",
"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
EzeasClient(client_id, client_secret)
Creates a new async client instance.
client_id: string issued by ezeasclient_secret: shared secret issued by ezeas
The recommended usage is via async with:
async with EzeasClient(client_id, client_secret) 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
Noneif the body is empty).
- Parses and returns JSON (or
- For 4xx responses:
- Raises
Exceptionwith the backend error payload as text.
- Raises
- For 5xx responses:
- Raises
Exceptionwith a message in the form:"Internal server error <status>: <body>"
- Raises
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_idclient_id:client_idiat: issued-at (seconds since epoch)exp: expiry (seconds since epoch, typicallyiat + 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.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ezeas_client-0.1.7.tar.gz.
File metadata
- Download URL: ezeas_client-0.1.7.tar.gz
- Upload date:
- Size: 4.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/2.1.4 CPython/3.13.7 Windows/11
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c43c611397e35f1a0ad6ada98d41a5811a392883c326fae701829aeb47892e3f
|
|
| MD5 |
488f6961d0de69c6a7c732d288d4d948
|
|
| BLAKE2b-256 |
b61309fa0adbaca44426647bb5e77778f58436848da172b8fe2ca5fcc040a3b8
|
File details
Details for the file ezeas_client-0.1.7-py3-none-any.whl.
File metadata
- Download URL: ezeas_client-0.1.7-py3-none-any.whl
- Upload date:
- Size: 5.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/2.1.4 CPython/3.13.7 Windows/11
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4290ae6861d0c64fde483b8c567101d5b26bc877766256db058b1c01e4d97289
|
|
| MD5 |
5ea4e63532246c8d660182c64b7505f0
|
|
| BLAKE2b-256 |
571682753b75df556bc8991d9ed30d414aea023707af290a617fd257448ce2fb
|
