ajera 0.1.3__tar.gz

ajera-0.1.3/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.3
+Name: ajera
+Version: 0.1.3
+Summary: Deltek Ajera Python API Client
+Author: SB&O Inc
+Author-email: SB&O Inc <contact@sboinc.com>
+Requires-Dist: click>=8.0.0
+Requires-Dist: requests>=2.0,<3
+Requires-Dist: pydantic>=2.10.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+[![CI](https://github.com/sbo-inc/ajera/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/sbo-inc/ajera/actions/workflows/ci.yaml)
+
+# Deltek Ajera Python client
+
+A typed Python client and command-line interface for the [Deltek Ajera](https://www.deltek.com/en/project-based-erp/ajera) API.
+
+Ajera exposes a single JSON-RPC style endpoint; this package wraps it in an ergonomic, fully type-hinted client built on [Pydantic](https://docs.pydantic.dev/) models, plus an `ajera` CLI for quick access from the terminal. Responses are validated and normalized into predictable Python objects so you can work with employees, projects, vendors, invoices, and general-ledger data without hand-rolling request payloads.
+
+## Features
+
+- **Typed models** - every response is parsed into Pydantic models with descriptive fields.
+- **Python client and CLI** - use it as a library or straight from the shell via `ajera`.
+- **Sensible defaults** - handles session tokens and per-method API versions for you.
+- **Read and write** - list, get, update, and create across the supported APIs.
+
+## Installation
+
+```bash
+pip install ajera
+# or, with uv:
+uv add ajera
+```
+
+Requires Python 3.12+.
+
+## Configuration
+
+Credentials are read from environment variables (or can be passed directly to `AjeraClient`):
+
+| Variable | Description |
+| --- | --- |
+| `AJERA_API_URL` | The Ajera API endpoint URL for your tenant. |
+| `AJERA_API_USERNAME` | API username. |
+| `AJERA_API_PASSWORD` | API password. |
+
+```bash
+export AJERA_API_URL="https://ajera.com/V0000000/AjeraAPI.ashx?..."
+export AJERA_API_USERNAME="your-username"
+export AJERA_API_PASSWORD="your-password"
+```
+
+For setting up an API user and generating credentials, see the [Deltek Ajera Learning Hub API docs](https://learning.deltek.com/bundle/ajera/page/Content/api_setting_up_api_user.htm).
+
+## Quick start
+
+### Python
+
+```python
+from ajera import AjeraClient
+
+# Reads AJERA_API_URL / AJERA_API_USERNAME / AJERA_API_PASSWORD from the
+# environment, or pass url=, username=, password= explicitly.
+client = AjeraClient()
+
+for employee in client.list_employees():
+    print(employee.employee_key, employee.first_name, employee.last_name)
+```
+
+### CLI
+
+```console
+$ ajera employees list
+[
+  {
+    "employee_key": 42,
+    "first_name": "Ada",
+    "last_name": "Lovelace",
+    ...
+  },
+  ...
+]
+```
+
+> **Note:** List commands backed by an active/inactive status return only **active** records by
+> default. Pass `--status` to override - e.g. `--status Inactive`, or
+> `--status Active --status Inactive` to include both.
+
+## Reference Documentation
+
+This client adheres (to the extent possible) to the API documentation provided by Deltek Ajera, which can be found at:
+
+https://help.deltek.com/product/Ajera/api/index.html
+
+## API reference
+
+Each section below maps a CLI command group to the Ajera API(s) it is built on. The Python client
+exposes the same operations as `client.<method>()` (e.g. `client.list_employees()`,
+`client.get_projects(...)`).
+
+### Employees
+
+Docs: [Employees API](https://help.deltek.com/product/Ajera/api/employees.html) · [List Methods API](https://help.deltek.com/product/Ajera/api/list_methods.html)
+
+`pays`, `payroll-taxes`, and `wage-tables` come from the List Methods API; the rest come from the Employees API.
+
+| Command | Description |
+| --- | --- |
+| `ajera employees list` | List employees. |
+| `ajera employees get <id>...` | Get one or more employees by ID. |
+| `ajera employees update <key> [options]` | Update simple fields on one employee. |
+| `ajera employees types` | List employee types. |
+| `ajera employees deductions` | List deductions. |
+| `ajera employees fringes` | List fringes. |
+| `ajera employees pays` | List pay types. |
+| `ajera employees payroll-taxes` | List payroll taxes. |
+| `ajera employees wage-tables` | List wage tables. |
+
+### Clients
+
+Docs: [Clients API](https://help.deltek.com/product/Ajera/api/clients.html)
+
+| Command | Description |
+| --- | --- |
+| `ajera clients list` | List clients. |
+| `ajera clients get <id>...` | Get one or more clients by ID. |
+| `ajera clients update <key> [options]` | Update simple fields on one client. |
+| `ajera clients types` | List client types. |
+
+### Contacts
+
+Docs: [Contacts API](https://help.deltek.com/product/Ajera/api/contacts.html)
+
+| Command | Description |
+| --- | --- |
+| `ajera contacts list` | List contacts. |
+| `ajera contacts get <id>...` | Get one or more contacts by ID. |
+| `ajera contacts update <key> [options]` | Update simple fields on one contact. |
+| `ajera contacts types` | List contact types. |
+
+### Vendors
+
+Docs: [Vendors API](https://help.deltek.com/product/Ajera/api/vendors.html) · [Vendor Invoices API (v2)](https://help.deltek.com/product/Ajera/api/version2/vendor_invoices.html)
+
+The `invoices` subcommands come from the Vendor Invoices (v2) API; the rest come from the Vendors API.
+
+| Command | Description |
+| --- | --- |
+| `ajera vendors list` | List vendors. |
+| `ajera vendors get <id>...` | Get one or more vendors by ID. |
+| `ajera vendors update <key> [options]` | Update simple fields on one vendor. |
+| `ajera vendors types` | List vendor types. |
+| `ajera vendors invoices list` | List vendor invoices, optionally filtered. |
+| `ajera vendors invoices get <key>...` | Get one or more vendor invoices, with their line items. |
+| `ajera vendors invoices create [options]` | Create a vendor invoice with a single line item. |
+
+### Projects
+
+Docs: [Projects API (v2)](https://help.deltek.com/product/Ajera/api/version2/projects.html) · [Projects API (v1)](https://help.deltek.com/product/Ajera/api/projects.html) · [List Methods API](https://help.deltek.com/product/Ajera/api/list_methods.html)
+
+`list`, `get`, `update`, and `create` use the v2 Projects API; `totals`, `types`, and `templates`
+use the v1 Projects API; `chargeable-phases` comes from the List Methods API.
+
+| Command | Description |
+| --- | --- |
+| `ajera projects list` | List projects, optionally filtered. |
+| `ajera projects get <id>...` | Get one or more projects by ID. |
+| `ajera projects create <description> [options]` | Create a new project. |
+| `ajera projects update <key> [options]` | Update simple fields on one project. |
+| `ajera projects totals <id>` | Get a project's financial totals. |
+| `ajera projects types` | List project types. |
+| `ajera projects templates list` | List project templates, optionally filtered. |
+| `ajera projects templates get <id>...` | Get one or more project templates by ID. |
+| `ajera projects chargeable-phases <project-key>` | List the chargeable phases of a project. |
+
+### General Ledger
+
+Docs: [GL Accounts API](https://help.deltek.com/product/Ajera/api/gl_accounts.html) · [List Methods API](https://help.deltek.com/product/Ajera/api/list_methods.html)
+
+`account-groups` comes from the List Methods API; `list` and `get` come from the GL Accounts API.
+
+| Command | Description |
+| --- | --- |
+| `ajera ledger list` | List general ledger accounts. |
+| `ajera ledger get [id]...` | Get general ledger account details, with calculated amounts. |
+| `ajera ledger account-groups` | List general ledger account groups. |
+
+### Reference lists
+
+Docs: [List Methods API](https://help.deltek.com/product/Ajera/api/list_methods.html)
+
+Lightweight lookup lists. (Other List Methods endpoints are grouped with their domain - see
+`employees`, `ledger`, and `projects` above.)
+
+| Command | Description |
+| --- | --- |
+| `ajera activities` | List activities. |
+| `ajera bank-accounts` | List bank accounts. |
+| `ajera companies` | List companies. |
+| `ajera departments` | List departments. |
+| `ajera invoice-formats` | List invoice formats. |
+| `ajera rate-tables` | List rate tables. |

ajera-0.1.3/README.md

@@ -0,0 +1,191 @@
+[![CI](https://github.com/sbo-inc/ajera/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/sbo-inc/ajera/actions/workflows/ci.yaml)
+
+# Deltek Ajera Python client
+
+A typed Python client and command-line interface for the [Deltek Ajera](https://www.deltek.com/en/project-based-erp/ajera) API.
+
+Ajera exposes a single JSON-RPC style endpoint; this package wraps it in an ergonomic, fully type-hinted client built on [Pydantic](https://docs.pydantic.dev/) models, plus an `ajera` CLI for quick access from the terminal. Responses are validated and normalized into predictable Python objects so you can work with employees, projects, vendors, invoices, and general-ledger data without hand-rolling request payloads.
+
+## Features
+
+- **Typed models** - every response is parsed into Pydantic models with descriptive fields.
+- **Python client and CLI** - use it as a library or straight from the shell via `ajera`.
+- **Sensible defaults** - handles session tokens and per-method API versions for you.
+- **Read and write** - list, get, update, and create across the supported APIs.
+
+## Installation
+
+```bash
+pip install ajera
+# or, with uv:
+uv add ajera
+```
+
+Requires Python 3.12+.
+
+## Configuration
+
+Credentials are read from environment variables (or can be passed directly to `AjeraClient`):
+
+| Variable | Description |
+| --- | --- |
+| `AJERA_API_URL` | The Ajera API endpoint URL for your tenant. |
+| `AJERA_API_USERNAME` | API username. |
+| `AJERA_API_PASSWORD` | API password. |
+
+```bash
+export AJERA_API_URL="https://ajera.com/V0000000/AjeraAPI.ashx?..."
+export AJERA_API_USERNAME="your-username"
+export AJERA_API_PASSWORD="your-password"
+```
+
+For setting up an API user and generating credentials, see the [Deltek Ajera Learning Hub API docs](https://learning.deltek.com/bundle/ajera/page/Content/api_setting_up_api_user.htm).
+
+## Quick start
+
+### Python
+
+```python
+from ajera import AjeraClient
+
+# Reads AJERA_API_URL / AJERA_API_USERNAME / AJERA_API_PASSWORD from the
+# environment, or pass url=, username=, password= explicitly.
+client = AjeraClient()
+
+for employee in client.list_employees():
+    print(employee.employee_key, employee.first_name, employee.last_name)
+```
+
+### CLI
+
+```console
+$ ajera employees list
+[
+  {
+    "employee_key": 42,
+    "first_name": "Ada",
+    "last_name": "Lovelace",
+    ...
+  },
+  ...
+]
+```
+
+> **Note:** List commands backed by an active/inactive status return only **active** records by
+> default. Pass `--status` to override - e.g. `--status Inactive`, or
+> `--status Active --status Inactive` to include both.
+
+## Reference Documentation
+
+This client adheres (to the extent possible) to the API documentation provided by Deltek Ajera, which can be found at:
+
+https://help.deltek.com/product/Ajera/api/index.html
+
+## API reference
+
+Each section below maps a CLI command group to the Ajera API(s) it is built on. The Python client
+exposes the same operations as `client.<method>()` (e.g. `client.list_employees()`,
+`client.get_projects(...)`).
+
+### Employees
+
+Docs: [Employees API](https://help.deltek.com/product/Ajera/api/employees.html) · [List Methods API](https://help.deltek.com/product/Ajera/api/list_methods.html)
+
+`pays`, `payroll-taxes`, and `wage-tables` come from the List Methods API; the rest come from the Employees API.
+
+| Command | Description |
+| --- | --- |
+| `ajera employees list` | List employees. |
+| `ajera employees get <id>...` | Get one or more employees by ID. |
+| `ajera employees update <key> [options]` | Update simple fields on one employee. |
+| `ajera employees types` | List employee types. |
+| `ajera employees deductions` | List deductions. |
+| `ajera employees fringes` | List fringes. |
+| `ajera employees pays` | List pay types. |
+| `ajera employees payroll-taxes` | List payroll taxes. |
+| `ajera employees wage-tables` | List wage tables. |
+
+### Clients
+
+Docs: [Clients API](https://help.deltek.com/product/Ajera/api/clients.html)
+
+| Command | Description |
+| --- | --- |
+| `ajera clients list` | List clients. |
+| `ajera clients get <id>...` | Get one or more clients by ID. |
+| `ajera clients update <key> [options]` | Update simple fields on one client. |
+| `ajera clients types` | List client types. |
+
+### Contacts
+
+Docs: [Contacts API](https://help.deltek.com/product/Ajera/api/contacts.html)
+
+| Command | Description |
+| --- | --- |
+| `ajera contacts list` | List contacts. |
+| `ajera contacts get <id>...` | Get one or more contacts by ID. |
+| `ajera contacts update <key> [options]` | Update simple fields on one contact. |
+| `ajera contacts types` | List contact types. |
+
+### Vendors
+
+Docs: [Vendors API](https://help.deltek.com/product/Ajera/api/vendors.html) · [Vendor Invoices API (v2)](https://help.deltek.com/product/Ajera/api/version2/vendor_invoices.html)
+
+The `invoices` subcommands come from the Vendor Invoices (v2) API; the rest come from the Vendors API.
+
+| Command | Description |
+| --- | --- |
+| `ajera vendors list` | List vendors. |
+| `ajera vendors get <id>...` | Get one or more vendors by ID. |
+| `ajera vendors update <key> [options]` | Update simple fields on one vendor. |
+| `ajera vendors types` | List vendor types. |
+| `ajera vendors invoices list` | List vendor invoices, optionally filtered. |
+| `ajera vendors invoices get <key>...` | Get one or more vendor invoices, with their line items. |
+| `ajera vendors invoices create [options]` | Create a vendor invoice with a single line item. |
+
+### Projects
+
+Docs: [Projects API (v2)](https://help.deltek.com/product/Ajera/api/version2/projects.html) · [Projects API (v1)](https://help.deltek.com/product/Ajera/api/projects.html) · [List Methods API](https://help.deltek.com/product/Ajera/api/list_methods.html)
+
+`list`, `get`, `update`, and `create` use the v2 Projects API; `totals`, `types`, and `templates`
+use the v1 Projects API; `chargeable-phases` comes from the List Methods API.
+
+| Command | Description |
+| --- | --- |
+| `ajera projects list` | List projects, optionally filtered. |
+| `ajera projects get <id>...` | Get one or more projects by ID. |
+| `ajera projects create <description> [options]` | Create a new project. |
+| `ajera projects update <key> [options]` | Update simple fields on one project. |
+| `ajera projects totals <id>` | Get a project's financial totals. |
+| `ajera projects types` | List project types. |
+| `ajera projects templates list` | List project templates, optionally filtered. |
+| `ajera projects templates get <id>...` | Get one or more project templates by ID. |
+| `ajera projects chargeable-phases <project-key>` | List the chargeable phases of a project. |
+
+### General Ledger
+
+Docs: [GL Accounts API](https://help.deltek.com/product/Ajera/api/gl_accounts.html) · [List Methods API](https://help.deltek.com/product/Ajera/api/list_methods.html)
+
+`account-groups` comes from the List Methods API; `list` and `get` come from the GL Accounts API.
+
+| Command | Description |
+| --- | --- |
+| `ajera ledger list` | List general ledger accounts. |
+| `ajera ledger get [id]...` | Get general ledger account details, with calculated amounts. |
+| `ajera ledger account-groups` | List general ledger account groups. |
+
+### Reference lists
+
+Docs: [List Methods API](https://help.deltek.com/product/Ajera/api/list_methods.html)
+
+Lightweight lookup lists. (Other List Methods endpoints are grouped with their domain - see
+`employees`, `ledger`, and `projects` above.)
+
+| Command | Description |
+| --- | --- |
+| `ajera activities` | List activities. |
+| `ajera bank-accounts` | List bank accounts. |
+| `ajera companies` | List companies. |
+| `ajera departments` | List departments. |
+| `ajera invoice-formats` | List invoice formats. |
+| `ajera rate-tables` | List rate tables. |

ajera-0.1.3/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "ajera"
+version = "0.1.3"
+description = "Deltek Ajera Python API Client"
+readme = "README.md"
+authors = [{ name = "SB&O Inc", email = "contact@sboinc.com" }]
+requires-python = ">=3.12"
+dependencies = [
+    "click >= 8.0.0",
+    "requests >=2.0, <3",
+    "pydantic >= 2.10.0",
+]
+
+[dependency-groups]
+dev = [
+    "mypy",
+    "ruff",
+    "pytest",
+]
+
+[tool.pytest.ini_options]
+markers = [
+    "integration: marks tests that require a live Ajera API instance",
+]
+
+[project.scripts]
+ajera = "ajera.cli:main"
+
+[build-system]
+requires = ["uv_build<0.9.0"]
+build-backend = "uv_build"

ajera-0.1.3/src/ajera/__init__.py

@@ -0,0 +1,5 @@
+from ajera.client import AjeraClient
+
+__all__ = [
+    "AjeraClient",
+]

ajera-0.1.3/src/ajera/cli/__init__.py

@@ -0,0 +1,95 @@
+import logging
+import sys
+
+import click
+import requests
+
+from ajera.cli.commands import (
+    activities,
+    bank_accounts,
+    clients,
+    companies,
+    contacts,
+    departments,
+    employees,
+    invoice_formats,
+    ledger,
+    projects,
+    rate_tables,
+    vendors,
+)
+from ajera.cli.context import ClientContext
+from ajera.cli.group import CommonClickGroup
+
+CLI_DOCS = """
+Deltek Ajera API command-line interface.
+
+Connection settings are read from environment variables:
+
+\b
+- AJERA_API_URL to define the API endpoint.
+- AJERA_API_USERNAME / AJERA_API_PASSWORD for authentication.
+- AJERA_API_HEADERS as a JSON object of extra request headers.
+"""
+
+
+@click.group(
+    cls=CommonClickGroup,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help=CLI_DOCS,
+)
+@click.option(
+    "--log",
+    is_flag=True,
+    default=False,
+    help="Enable request logging at INFO level.",
+)
+@click.version_option(package_name="ajera", prog_name="ajera")
+@click.pass_context
+def cli(ctx: click.Context, log: bool) -> None:
+    ctx.obj = ClientContext(log=log)
+
+
+# Register all domain-specific command groups.
+# Runtime gating is handled by AJERA_CLI_DISABLE.
+for module in (
+    employees,
+    clients,
+    contacts,
+    vendors,
+    projects,
+    ledger,
+    activities,
+    companies,
+    departments,
+    rate_tables,
+    bank_accounts,
+    invoice_formats,
+):
+    cli.add_command(module.group)
+
+
+def main() -> None:
+    """
+    Console-script entry point.
+
+    Translates expected errors into a non-zero exit with a readable message
+    instead of a traceback.
+    """
+    try:
+        cli(standalone_mode=False)
+    except click.ClickException as exc:
+        exc.show()
+        sys.exit(exc.exit_code)
+    except click.exceptions.Abort:
+        sys.exit(1)
+    except requests.HTTPError as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+    except Exception as exc:  # noqa: BLE001
+        logging.getLogger("ajera").debug("CLI error", exc_info=True)
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+
+__all__ = ["cli", "main"]

ajera-0.1.3/src/ajera/cli/__main__.py

@@ -0,0 +1,4 @@
+from ajera.cli import main
+
+if __name__ == "__main__":
+    main()

ajera-0.1.3/src/ajera/cli/commands/activities.py

@@ -0,0 +1,31 @@
+import click
+
+from ajera.cli.context import ClientContext
+from ajera.cli.options import status_option
+from ajera.cli.output import render
+
+
+@click.command(name="activities")
+@status_option
+@click.option(
+    "--description-like",
+    "filter_by_description_like",
+    type=str,
+    default=None,
+    help="Filter where the description contains this substring.",
+)
+@click.pass_obj
+def group(
+    ctx: ClientContext,
+    filter_by_status: tuple[str, ...],
+    filter_by_description_like: str | None,
+) -> None:
+    """
+    List activities (active only by default).
+    """
+    render(
+        ctx.client.list_activities(
+            filter_by_status=list(filter_by_status),
+            filter_by_description_like=filter_by_description_like,
+        )
+    )

ajera-0.1.3/src/ajera/cli/commands/bank_accounts.py

@@ -0,0 +1,18 @@
+import click
+
+from ajera.cli.context import ClientContext
+from ajera.cli.options import status_option
+from ajera.cli.output import render
+
+
+@click.command(name="bank-accounts")
+@status_option
+@click.pass_obj
+def group(
+    ctx: ClientContext,
+    filter_by_status: tuple[str, ...],
+) -> None:
+    """
+    List bank accounts (active only by default).
+    """
+    render(ctx.client.list_bank_accounts(filter_by_status=list(filter_by_status)))