wealthbox-cli 1.0.0__py3-none-any.whl

wealthbox_tools/client/projects.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wealthbox_tools.models import ProjectCreateInput, ProjectListQuery, ProjectUpdateInput
+
+
+class ProjectsMixin:
+    """Projects Resource"""
+
+    async def list_projects(self, query: ProjectListQuery | None = None) -> dict[str, Any]:
+        params = query.model_dump(exclude_none=True) if query else None
+        resp = await self._request("GET", "/projects", params=params)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def get_project(self, project_id: int) -> dict[str, Any]:
+        resp = await self._request("GET", f"/projects/{project_id}")  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def create_project(self, data: ProjectCreateInput) -> dict[str, Any]:
+        payload = data.model_dump(exclude_none=True)
+        resp = await self._request("POST", "/projects", json=payload)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def update_project(self, project_id: int, data: ProjectUpdateInput) -> dict[str, Any]:
+        payload = data.model_dump(exclude_unset=True)
+        resp = await self._request("PUT", f"/projects/{project_id}", json=payload)  # type: ignore[attr-defined]
+        return resp.json()

wealthbox_tools/client/tasks.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wealthbox_tools.models import TaskCreateInput, TaskListQuery, TaskUpdateInput
+
+
+class TasksMixin:
+    """Task resource methods. Mixed into WealthboxClient."""
+
+    async def list_tasks(self, query: TaskListQuery | None = None) -> dict[str, Any]:
+        params = query.model_dump(exclude_none=True) if query else None
+        resp = await self._request("GET", "/tasks", params=params)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def get_task(self, task_id: int) -> dict[str, Any]:
+        resp = await self._request("GET", f"/tasks/{task_id}")  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def create_task(self, data: TaskCreateInput) -> dict[str, Any]:
+        payload = data.model_dump(exclude_none=True)
+        resp = await self._request("POST", "/tasks", json=payload)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def update_task(self, task_id: int, data: TaskUpdateInput) -> dict[str, Any]:
+        payload = data.model_dump(exclude_unset=True)
+        resp = await self._request("PUT", f"/tasks/{task_id}", json=payload)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def delete_task(self, task_id: int) -> None:
+        await self._request("DELETE", f"/tasks/{task_id}")  # type: ignore[attr-defined]

wealthbox_tools/client/users.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wealthbox_tools.models.common import PaginationQuery
+
+
+class UsersMixin:
+    """Users Resource"""
+    
+    async def list_users(self, query: PaginationQuery | None = None) -> dict[str, Any]:
+        params = query.model_dump(exclude_none=True) if query else None
+        resp = await self._request("GET", "/users", params=params)  # type: ignore[attr-defined]
+        return resp.json()

wealthbox_tools/client/workflows.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wealthbox_tools.models import (
+    WorkflowCreateInput,
+    WorkflowListQuery,
+    WorkflowStepCompleteInput,
+    WorkflowTemplateListQuery,
+)
+
+
+class WorkflowsMixin:
+    """Workflows Resource"""
+
+    async def list_workflows(self, query: WorkflowListQuery | None = None) -> dict[str, Any]:
+        params = query.model_dump(exclude_none=True) if query else None
+        resp = await self._request("GET", "/workflows", params=params)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def get_workflow(self, workflow_id: int) -> dict[str, Any]:
+        resp = await self._request("GET", f"/workflows/{workflow_id}")  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def create_workflow(self, data: WorkflowCreateInput) -> dict[str, Any]:
+        payload = data.model_dump(exclude_none=True)
+        resp = await self._request("POST", "/workflows", json=payload)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def complete_workflow_step(
+        self, workflow_id: int, step_id: int, data: WorkflowStepCompleteInput
+    ) -> dict[str, Any]:
+        payload = data.model_dump(exclude_none=True)
+        resp = await self._request("PUT", f"/workflows/{workflow_id}/steps/{step_id}", json=payload)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def revert_workflow_step(self, workflow_id: int, step_id: int) -> dict[str, Any]:
+        resp = await self._request("PUT", f"/workflows/{workflow_id}/steps/{step_id}", json={"revert": True})  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def list_workflow_templates(self, query: WorkflowTemplateListQuery | None = None) -> dict[str, Any]:
+        params = query.model_dump(exclude_none=True) if query else None
+        resp = await self._request("GET", "/workflow_templates", params=params)  # type: ignore[attr-defined]
+        return resp.json()

wealthbox_tools/models/__init__.py

@@ -0,0 +1,134 @@
+"""Pydantic models for Wealthbox tool payload/query validation."""
+
+from .activity import ActivityListQuery
+from .comments import CommentListQuery
+from .common import (
+    ContactRoleAssignment,
+    EmailAddress,
+    LinkedToRef,
+    PhoneNumber,
+    StreetAddress,
+)
+from .contacts import ContactCreateInput, ContactListQuery, ContactUpdateInput
+from .custom_fields import CategoryListQuery, CustomFieldValue
+from .enums import (
+    ActivityType,
+    CategoryType,
+    CommentResourceType,
+    ContactsOrder,
+    DocumentType,
+    EventsOrder,
+    EventsState,
+    Gender,
+    HouseholdTitle,
+    MaritalStatus,
+    NoteResourceType,
+    NotesOrder,
+    OpportunityAmountKind,
+    OpportunityOrder,
+    OpportunityResourceType,
+    RecordType,
+    TaskFrame,
+    TaskPriority,
+    TaskResourceType,
+    TaskType,
+    WorkflowResourceType,
+    WorkflowStatus,
+)
+from .events import EventCreateInput, EventListQuery, EventUpdateInput
+from .households import HouseholdMemberInput
+from .notes import NoteCreateInput, NoteListQuery, NoteUpdateInput
+from .opportunities import OpportunityAmount, OpportunityCreateInput, OpportunityListQuery, OpportunityUpdateInput
+from .projects import ProjectCreateInput, ProjectListQuery, ProjectUpdateInput
+from .tasks import TaskCreateInput, TaskListQuery, TaskUpdateInput
+from .workflows import (
+    WorkflowCreateInput,
+    WorkflowListQuery,
+    WorkflowMilestone,
+    WorkflowStepCompleteInput,
+    WorkflowStepRevertInput,
+    WorkflowTemplateListQuery,
+)
+
+__all__ = [
+    # Enums
+    "RecordType",
+    "Gender",
+    "MaritalStatus",
+    "EventsOrder",
+    "HouseholdTitle",
+    "DocumentType",
+    "ContactsOrder",
+    "ActivityType",
+    "CategoryType",
+    "CommentResourceType",
+    "NotesOrder",
+    "NoteResourceType",
+    "OpportunityAmountKind",
+    "OpportunityOrder",
+    "OpportunityResourceType",
+    "TaskFrame",
+    "TaskPriority",
+    "TaskResourceType",
+    "TaskType",
+    "EventsState",
+    "WorkflowResourceType",
+    "WorkflowStatus",
+
+    # Activity
+    "ActivityListQuery",
+
+    # Comments
+    "CommentListQuery",
+
+    # Contacts
+    "ContactCreateInput",
+    "ContactListQuery",
+    "ContactUpdateInput",
+    "ContactRoleAssignment",
+    "EmailAddress",
+    "LinkedToRef",
+    "PhoneNumber",
+    "StreetAddress",
+
+    # Events
+    "EventCreateInput",
+    "EventListQuery",
+    "EventUpdateInput",
+
+    # Households
+    "HouseholdMemberInput",
+
+    # Categories
+    "CategoryListQuery",
+    "CustomFieldValue",
+
+    # Notes
+    "NoteCreateInput",
+    "NoteListQuery",
+    "NoteUpdateInput",
+
+    # Opportunities
+    "OpportunityAmount",
+    "OpportunityCreateInput",
+    "OpportunityListQuery",
+    "OpportunityUpdateInput",
+
+    # Projects
+    "ProjectCreateInput",
+    "ProjectListQuery",
+    "ProjectUpdateInput",
+
+    # Tasks
+    "TaskCreateInput",
+    "TaskListQuery",
+    "TaskUpdateInput",
+
+    # Workflows
+    "WorkflowCreateInput",
+    "WorkflowListQuery",
+    "WorkflowMilestone",
+    "WorkflowStepCompleteInput",
+    "WorkflowStepRevertInput",
+    "WorkflowTemplateListQuery",
+]

wealthbox_tools/models/activity.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from .common import DateTimeField, WealthboxModel
+from .enums import ActivityType
+
+
+class ActivityListQuery(WealthboxModel):
+    contact: int | None = None
+    cursor: str | None = None
+    type: ActivityType | None = None
+    updated_since: DateTimeField = None
+    updated_before: DateTimeField = None
+    

wealthbox_tools/models/comments.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from .common import DateTimeField, PaginationQuery
+from .enums import CommentResourceType
+
+
+class CommentListQuery(PaginationQuery):
+    resource_id: int | None = Field(default=None, ge=1)
+    resource_type: CommentResourceType | None = None
+    updated_since: DateTimeField = None
+    updated_before: DateTimeField = None

wealthbox_tools/models/common.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import re
+from typing import Annotated
+
+from pydantic import AfterValidator, BaseModel, ConfigDict, Field, field_validator, model_validator
+
+# ---------------------------------------------------------------------------
+# Reusable date / datetime validators
+# ---------------------------------------------------------------------------
+
+_DATE_RE = re.compile(r'^\d{4}-\d{2}-\d{2}$')
+# ISO 8601 datetime: YYYY-MM-DDTHH:MM:SS with optional Z or ±HH:MM offset
+_DATETIME_ISO_RE = re.compile(r'^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2})?$')
+_EMAIL_RE = re.compile(r'^[^@\s]+@[^@\s]+\.[^@\s]+$')
+
+_LINKED_TO_TYPES = frozenset({"Contact", "Project", "Opportunity"})
+_LINKED_TO_TYPES_DISPLAY = ", ".join(sorted(_LINKED_TO_TYPES))
+
+_DATETIME_EXAMPLE = "e.g. '2026-04-01T10:00:00-07:00' or '2026-04-01T10:00:00Z'"
+
+
+def _check_date(v: str | None) -> str | None:
+    if v is not None and not _DATE_RE.match(v):
+        raise ValueError("must be in YYYY-MM-DD format (e.g. '1975-10-27')")
+    return v
+
+
+def _check_datetime(v: str | None) -> str | None:
+    if v is not None and not _DATETIME_ISO_RE.match(v):
+        raise ValueError(f"must be ISO 8601 datetime ({_DATETIME_EXAMPLE})")
+    return v
+
+
+def _check_email(v: str | None) -> str | None:
+    if v is not None and not _EMAIL_RE.match(v):
+        raise ValueError(f"'{v}' is not a valid email address")
+    return v
+
+
+# Annotated type aliases — use these as field type annotations so format
+# validation is applied automatically. Import into each model module that uses them.
+DateField = Annotated[str | None, AfterValidator(_check_date)]
+DateTimeField = Annotated[str | None, AfterValidator(_check_datetime)]
+# For required (non-optional) datetime string fields.
+NonNullDateTimeField = Annotated[str, AfterValidator(_check_datetime)]
+EmailField = Annotated[str | None, AfterValidator(_check_email)]
+
+
+# ---------------------------------------------------------------------------
+# Base models
+# ---------------------------------------------------------------------------
+
+class WealthboxModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+
+class RequireAnyFieldModel(WealthboxModel):
+    @model_validator(mode="after")
+    def ensure_any_field_present(self) -> "RequireAnyFieldModel":
+        # Updates should allow explicit null for clearable fields while still
+        # rejecting completely empty payloads.
+        if not self.model_fields_set:
+            raise ValueError("At least one field must be provided.")
+        return self
+
+
+class PaginationQuery(WealthboxModel):
+    page: int | None = Field(default=None, ge=1)
+    per_page: int | None = Field(default=25, ge=1, le=100)
+
+
+# ---------------------------------------------------------------------------
+# Nested contact sub-objects
+# ---------------------------------------------------------------------------
+
+class EmailAddress(WealthboxModel):
+    id: int | None = Field(default=None, ge=1)
+    address: EmailField = None
+    kind: str | None = None
+    principal: bool | None = None
+    destroy: bool | None = None
+
+
+class PhoneNumber(WealthboxModel):
+    id: int | None = Field(default=None, ge=1)
+    address: str | None = None
+    kind: str | None = None
+    principal: bool | None = None
+    extension: str | None = None
+    destroy: bool | None = None
+
+
+class StreetAddress(WealthboxModel):
+    id: int | None = Field(default=None, ge=1)
+    kind: str | None = None
+    principal: bool | None = None
+    street_line_1: str | None = None
+    street_line_2: str | None = None
+    city: str | None = None
+    state: str | None = None
+    zip_code: str | None = None
+    country: str | None = None
+    destroy: bool | None = None
+
+
+class ContactRoleAssignment(WealthboxModel):
+    id: int | None = Field(default=None, ge=1)
+    type: str | None = None
+
+
+class LinkedToRef(WealthboxModel):
+    id: int = Field(ge=1, description="Wealthbox object ID (positive integer)")
+    type: str = Field(description="Wealthbox object type; allowed: Contact, Project, Opportunity")
+
+    @field_validator("type")
+    @classmethod
+    def validate_linked_to_type(cls, v: str) -> str:
+        if v not in _LINKED_TO_TYPES:
+            raise ValueError(
+                f"'{v}' is not a valid linked_to type; must be one of: {_LINKED_TO_TYPES_DISPLAY}"
+            )
+        return v

wealthbox_tools/models/contacts.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from pydantic import Field, model_validator
+
+from .common import (
+    ContactRoleAssignment,
+    DateField,
+    DateTimeField,
+    EmailAddress,
+    PaginationQuery,
+    PhoneNumber,
+    RequireAnyFieldModel,
+    StreetAddress,
+    WealthboxModel,
+)
+from .custom_fields import CustomFieldValue
+from .enums import (
+    ContactsOrder,
+    Gender,
+    HouseholdTitle,
+    MaritalStatus,
+    RecordType,
+)
+
+
+class ContactListQuery(PaginationQuery):
+    id: int | None = Field(default=None, ge=1)
+    contact_type: str | None = None
+    name: str | None = None
+    email: str | None = None
+    phone: str | None = None
+    external_unique_id: str | None = None
+    active: bool | None = None
+    tags: list[str] | None = None
+    deleted: bool | None = None
+    deleted_since: DateTimeField = None
+    household_title: HouseholdTitle | None = None
+    type: RecordType | None = None
+    order: ContactsOrder | None = None
+    updated_since: DateTimeField = None
+    updated_before: DateTimeField = None
+
+
+class ContactCreateInput(WealthboxModel):
+    # Core identity
+    type: RecordType | None = None
+    prefix: str | None = None
+    first_name: str | None = None
+    middle_name: str | None = None
+    last_name: str | None = None
+    suffix: str | None = None
+    nickname: str | None = None
+    name: str | None = None
+
+    # Person/company attributes
+    job_title: str | None = None
+    company_name: str | None = None
+    marital_status: MaritalStatus | None = None
+    gender: Gender | None = None
+    birth_date: DateField = None
+    anniversary: DateField = None
+    client_since: DateField = None
+    date_of_death: DateField = None
+
+    contact_type: str | None = None
+    contact_source: str | None = None
+    status: str | None = None
+    assigned_to: int | None = Field(default=None, ge=1)
+    visible_to: str | None = None
+    external_unique_id: str | None = None
+    background_information: str | None = None
+    important_information: str | None = None
+
+
+    # Nested arrays
+    email_addresses: list[EmailAddress] | None = None
+    phone_numbers: list[PhoneNumber] | None = None
+    street_addresses: list[StreetAddress] | None = None
+    tags: list[str] | None = None
+    custom_fields: list[CustomFieldValue] | None = None
+    contact_roles: list[ContactRoleAssignment] | None = None
+
+
+    @model_validator(mode="after")
+    def ensure_non_empty_create(self) -> "ContactCreateInput":
+        # Enforce non-empty payload for create only; update has its own rules.
+        if type(self) is ContactCreateInput and not self.model_dump(exclude_none=True):
+            raise ValueError("At least one field must be provided.")
+        return self
+
+
+class ContactUpdateInput(RequireAnyFieldModel):
+    # Core identity
+    type: RecordType | None = None
+    prefix: str | None = None
+    first_name: str | None = None
+    middle_name: str | None = None
+    last_name: str | None = None
+    suffix: str | None = None
+    nickname: str | None = None
+    name: str | None = None
+
+    # Person/company attributes
+    job_title: str | None = None
+    company_name: str | None = None
+    marital_status: MaritalStatus | None = None
+    gender: Gender | None = None
+    birth_date: DateField = None
+    anniversary: DateField = None
+    client_since: DateField = None
+    date_of_death: DateField = None
+
+    contact_type: str | None = None
+    contact_source: str | None = None
+    status: str | None = None
+    assigned_to: int | None = Field(default=None, ge=1)
+    visible_to: str | None = None
+    external_unique_id: str | None = None
+    background_information: str | None = None
+    important_information: str | None = None
+
+    # Nested arrays
+    email_addresses: list[EmailAddress] | None = None
+    phone_numbers: list[PhoneNumber] | None = None
+    street_addresses: list[StreetAddress] | None = None
+    tags: list[str] | None = None
+    custom_fields: list[CustomFieldValue] | None = None
+    contact_roles: list[ContactRoleAssignment] | None = None
+
+    # Update-only fields
+    destroy: bool | None = None

wealthbox_tools/models/custom_fields.py

@@ -0,0 +1,19 @@
+"""Pydantic models for metadata tool validation."""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field
+
+from .common import PaginationQuery, WealthboxModel
+from .enums import DocumentType
+
+
+class CustomFieldValue(WealthboxModel):
+    id: int | None = Field(default=None, ge=1)
+    name: str | None = None
+    value: Any | None = None
+
+
+class CategoryListQuery(PaginationQuery):
+    document_type: DocumentType | None = None