factorial-api-client 1.0.0__tar.gz

factorial_api_client-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+# TypeScript
+typescript/node_modules/
+typescript/dist/
+
+# Python
+python/.venv/
+**/__pycache__/
+**/*.pyc
+**/*.pyo
+python/dist/
+
+# Environment
+.envrc
+
+# OS
+.DS_Store

factorial_api_client-1.0.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: factorial-api-client
+Version: 1.0.0
+Summary: Official Python SDK for the Factorial API
+Project-URL: Homepage, https://github.com/factorialco/factorial-api-sdks
+Project-URL: Documentation, https://apidoc.factorialhr.com
+License: MIT
+Keywords: api,factorial,hr,openapi,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: attrs>=23.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-dateutil>=2.8.0
+Description-Content-Type: text/markdown
+
+# factorial-api-client (Python)
+
+Official Python SDK for the [Factorial API](https://apidoc.factorialhr.com).
+
+
+## Versioning
+
+The SDK uses standard semver (`MAJOR.MINOR.PATCH`), independent of the Factorial API version date.
+
+| SDK version | Factorial API version |
+|-------------|----------------------|
+| `1.x.y`     | `2026-04-01`         |
+
+Factorial releases new API versions quarterly (Jan/Apr/Jul/Oct).
+
+See the [Factorial API versioning docs](https://apidoc.factorialhr.com/docs/api-versioning) for details.
+
+## Installation
+
+```bash
+pip install factorial-api-client
+```
+
+## Quick start
+
+```python
+from factorial_api_client import FactorialClient
+
+client = FactorialClient(api_key="YOUR_KEY")
+
+# First page only
+result = client.employees.employee.list()
+employees = result.data
+
+# Cursor-paginated iterator (sync)
+for emp in client.employees.employee.paginate(max_items=100):
+    print(emp.full_name)
+
+# Collect all pages into a list
+all_employees = client.employees.employee.all()
+
+# Async iterator
+import asyncio
+
+async def main():
+    async for emp in await client.employees.employee.paginate_async(max_items=100):
+        print(emp.full_name)
+
+asyncio.run(main())
+```
+
+## Authentication
+
+Pass your API key via `api_key=` or an OAuth2 bearer token via `token=`:
+
+```python
+# API key (sent as x-api-key header)
+client = FactorialClient(api_key="YOUR_KEY")
+
+# OAuth2 bearer token
+client = FactorialClient(token="YOUR_BEARER_TOKEN")
+```
+
+## Domain namespaces
+
+The client is organised as `client.{domain}.{resource}.{method}()`.
+
+| Domain | Example |
+|--------|---------|
+| `employees` | `client.employees.employee.list()` |
+| `ats` | `client.ats.application.list()` |
+| `attendance` | `client.attendance.shift.list()` |
+| `timeoff` | `client.timeoff.leave.list()` |
+| `contracts` | `client.contracts.contract_version.list()` |
+| `payroll` | `client.payroll.supplement.list()` |
+| `documents` | `client.documents.document.list()` |
+| `performance` | `client.performance.review_process.list()` |
+| ... | 36 domains total |
+
+Available methods per resource: `list`, `get`, `create`, `update`, `delete`,
+`paginate`, `paginate_async`, `all`, plus any custom action endpoints.
+
+## Pagination
+
+All list endpoints support cursor-based pagination via `paginate()` / `paginate_async()` / `all()`:
+
+```python
+# Stop after 50 items
+for emp in client.employees.employee.paginate(max_items=50):
+    ...
+
+# Collect everything (use carefully on large datasets)
+all_leaves = client.timeoff.leave.all()
+```

factorial_api_client-1.0.0/README.md

@@ -0,0 +1,94 @@
+# factorial-api-client (Python)
+
+Official Python SDK for the [Factorial API](https://apidoc.factorialhr.com).
+
+
+## Versioning
+
+The SDK uses standard semver (`MAJOR.MINOR.PATCH`), independent of the Factorial API version date.
+
+| SDK version | Factorial API version |
+|-------------|----------------------|
+| `1.x.y`     | `2026-04-01`         |
+
+Factorial releases new API versions quarterly (Jan/Apr/Jul/Oct).
+
+See the [Factorial API versioning docs](https://apidoc.factorialhr.com/docs/api-versioning) for details.
+
+## Installation
+
+```bash
+pip install factorial-api-client
+```
+
+## Quick start
+
+```python
+from factorial_api_client import FactorialClient
+
+client = FactorialClient(api_key="YOUR_KEY")
+
+# First page only
+result = client.employees.employee.list()
+employees = result.data
+
+# Cursor-paginated iterator (sync)
+for emp in client.employees.employee.paginate(max_items=100):
+    print(emp.full_name)
+
+# Collect all pages into a list
+all_employees = client.employees.employee.all()
+
+# Async iterator
+import asyncio
+
+async def main():
+    async for emp in await client.employees.employee.paginate_async(max_items=100):
+        print(emp.full_name)
+
+asyncio.run(main())
+```
+
+## Authentication
+
+Pass your API key via `api_key=` or an OAuth2 bearer token via `token=`:
+
+```python
+# API key (sent as x-api-key header)
+client = FactorialClient(api_key="YOUR_KEY")
+
+# OAuth2 bearer token
+client = FactorialClient(token="YOUR_BEARER_TOKEN")
+```
+
+## Domain namespaces
+
+The client is organised as `client.{domain}.{resource}.{method}()`.
+
+| Domain | Example |
+|--------|---------|
+| `employees` | `client.employees.employee.list()` |
+| `ats` | `client.ats.application.list()` |
+| `attendance` | `client.attendance.shift.list()` |
+| `timeoff` | `client.timeoff.leave.list()` |
+| `contracts` | `client.contracts.contract_version.list()` |
+| `payroll` | `client.payroll.supplement.list()` |
+| `documents` | `client.documents.document.list()` |
+| `performance` | `client.performance.review_process.list()` |
+| ... | 36 domains total |
+
+Available methods per resource: `list`, `get`, `create`, `update`, `delete`,
+`paginate`, `paginate_async`, `all`, plus any custom action endpoints.
+
+## Pagination
+
+All list endpoints support cursor-based pagination via `paginate()` / `paginate_async()` / `all()`:
+
+```python
+# Stop after 50 items
+for emp in client.employees.employee.paginate(max_items=50):
+    ...
+
+# Collect everything (use carefully on large datasets)
+all_leaves = client.timeoff.leave.all()
+```

factorial_api_client-1.0.0/factorial_api_client/__init__.py

@@ -0,0 +1,32 @@
+"""
+factorial-api-client — Python SDK for the Factorial API.
+
+Quick start::
+
+    from factorial_api_client import FactorialClient
+
+    client = FactorialClient(api_key="YOUR_KEY")
+
+    # Synchronous
+    employees = client.employees.employee.list()
+    for emp in client.employees.employee.paginate(max_items=50):
+        print(emp.full_name)
+    all_employees = client.employees.employee.all()
+
+    # Async
+    import asyncio
+    async def main():
+        async for emp in client.employees.employee.paginate_async(max_items=50):
+            print(emp.full_name)
+    asyncio.run(main())
+"""
+
+from factorial_api_client.client import FactorialClient
+from factorial_api_client.pagination import collect_all, paginate, paginate_async
+
+__all__ = [
+    "FactorialClient",
+    "paginate",
+    "paginate_async",
+    "collect_all",
+]