datex-studio-cli 0.4.14__tar.gz → 0.4.15__tar.gz

{datex_studio_cli-0.4.14 → datex_studio_cli-0.4.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: datex-studio-cli
-Version: 0.4.14
+Version: 0.4.15
 Summary: CLI for Datex Studio low-code platform, designed for LLM-based AI agents
 Project-URL: Homepage, https://github.com/datex/datex-studio-cli
 Project-URL: Documentation, https://github.com/datex/datex-studio-cli

{datex_studio_cli-0.4.14 → datex_studio_cli-0.4.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "datex-studio-cli"
-version = "0.4.14"
+version = "0.4.15"
 description = "CLI for Datex Studio low-code platform, designed for LLM-based AI agents"
 readme = "README.md"
 license = "MIT"

{datex_studio_cli-0.4.14 → datex_studio_cli-0.4.15}/src/dxs/__init__.py

@@ -1,4 +1,4 @@
 """Datex Studio CLI - Command-line interface for Datex Studio platform."""
 
-__version__ = "0.4.14"
+__version__ = "0.4.15"
 __app_name__ = "dxs"

{datex_studio_cli-0.4.14 → datex_studio_cli-0.4.15}/src/dxs/commands/crm.py

@@ -525,6 +525,33 @@ _DESCRIPTION_WRAPPER = (
 
 _ENTITLEMENT_ACTIVE_STATE = 1
 
+_ANNOTATION_ENTITY_SET = "annotations"
+_PORTAL_COMMENT_ENTITY_SET = "adx_portalcomments"
+
+# The CRM rich-text editor's own markup. Notes and portal comments authored in
+# the UI all carry it, so a CLI-authored one renders like its neighbours rather
+# than as an unstyled string.
+_CK_WRAPPER = (
+    '<div class="ck-content" data-wrapper="true" dir="ltr" '
+    'style="--ck-image-style-spacing: 1.5em; --ck-inline-image-style-spacing: '
+    "calc(var(--ck-image-style-spacing) / 2); font-family: Segoe UI; "
+    'font-size: 11pt;">{body}</div>'
+)
+
+# Activity-party roles. 8 (regarding) and 9 (owner) are added by the platform.
+_PARTY_SENDER = 1
+_PARTY_RECIPIENT = 2
+
+# adx_portalcommentdirectioncode.
+_COMMENT_DIRECTION_OUTGOING = 2
+
+# Marking the comment sent is a second step. An activity is created in the Open
+# state, `statecode` is not writable on create, and "Sent" belongs to Completed
+# — so setting it in the create body fails the whole request with
+# "2 is not a valid status code for state code adx_portalcommentState.Open".
+_COMMENT_STATE_COMPLETED = 1
+_COMMENT_STATUS_SENT = 2
+
 
 def _is_guid(value: str) -> bool:
     """Whether a value is a bare GUID rather than a name to look up."""
@@ -549,6 +576,55 @@ def _wrap_description_html(text: str) -> str:
     )
 
 
+def _wrap_note_html(text: str) -> str:
+    """Convert plain text to the CRM editor's HTML for a note or comment body.
+
+    Blank-line-separated paragraphs become ``<p style="margin: 0;">`` siblings
+    inside one wrapper div; single newlines become ``<br>``. Quotes are left as
+    typed — see :func:`_wrap_description_html` for why.
+    """
+    from html import escape
+
+    paragraphs = [p for p in re.split(r"\n\s*\n", text.strip()) if p.strip()]
+    body = "".join(
+        f'<p style="margin: 0;">{escape(p.strip(), quote=False).replace(chr(10), "<br>")}</p>'
+        for p in paragraphs
+    )
+    return _CK_WRAPPER.format(body=body)
+
+
+def _read_body(text: str | None, text_file: "Path | None", flag: str) -> str:
+    """Take the body from an argument or a file, and insist it is not blank."""
+    from dxs.utils.errors import ValidationError
+
+    if text is not None and text_file is not None:
+        raise ValidationError(
+            message=f"Pass either {flag} text or --text-file, not both",
+            code="DXS-CRM-CASE-BODY",
+            suggestions=["The body has one source; the other would be silently dropped"],
+        )
+
+    body = text_file.read_text(encoding="utf-8") if text_file else text
+    if body is None or not body.strip():
+        raise ValidationError(
+            message="The body cannot be empty",
+            code="DXS-CRM-CASE-BODY",
+            suggestions=["Pass the text as an argument, or read it from --text-file"],
+        )
+    return body
+
+
+def _resolve_case_for_write(client: "DynamicsClient", ticket_number: str) -> dict[str, Any]:
+    """Resolve a ticket number to the one incident a write may land on.
+
+    ``resolve_ticket`` raises when a ticket number matches several cases, which
+    is what we want here: appending to an arbitrary one of them would be worse
+    than failing.
+    """
+    incident = client.resolve_ticket(ticket_number)
+    return client.get_incident(incident["incidentid"])
+
+
 def _resolve_account(client: "DynamicsClient", value: str) -> tuple[str, str]:
     """Resolve an account name or GUID to (account_id, account_name)."""
     from dxs.utils.errors import ValidationError
@@ -752,7 +828,8 @@ def crm() -> None:
     """Dynamics CRM / Dataverse commands.
 
     Query support cases, accounts, and activities - or run raw OData against
-    any Dataverse entity. Read-only apart from 'case create' and 'commit-ref'.
+    any Dataverse entity. Read-only apart from 'case create/note/comment' and
+    'commit-ref'.
 
     \b
     Setup (one-time):
@@ -761,7 +838,7 @@ def crm() -> None:
 
     \b
     Pick a command:
-        case        Support cases (incidents): search, get, create, query, types
+        case        Support cases: search, get, create, note, comment, types
         account     Accounts (companies): list, search, contacts, entitlements
         activity    Portal comments & emails - by date range or ticket
         metadata    Discover entities, fields, and relationships
@@ -800,11 +877,19 @@ def case() -> None:
 
     \b
     Subcommands:
-        search  Find cases by text, account, status, date, or type
-        get     Fetch cases by ticket number (+ activity / notes)
-        create  Open a new case (the only write here - try --dry-run first)
-        query   Custom OData over incidents (full field control)
-        types   List case-type picklist values
+        search   Find cases by text, account, status, date, or type
+        get      Fetch cases by ticket number (+ activity / notes)
+        create   Open a new case
+        note     Add an internal note (staff-only)
+        comment  Reply to the customer (they see it on the portal)
+        query    Custom OData over incidents (full field control)
+        types    List case-type picklist values
+
+    \b
+    note vs comment - the difference is who reads it:
+        note     -> annotation, internal to staff
+        comment  -> portal comment, visible to the customer
+    Writes support --dry-run; 'comment' also confirms before posting.
 
     \b
     Ticket numbers are NOT unique - 'get' returns a list; check
@@ -1328,6 +1413,258 @@ def case_create(
     ctx.output(single(item=item, semantic_key="case", created=True))
 
 
+@case.command("note")
+@click.argument("ticket_number")
+@click.argument("text", required=False, default=None)
+@click.option(
+    "--text-file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Read the note body from a file instead of the command line.",
+)
+@click.option("--subject", default=None, help="Optional note subject (usually left blank).")
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Show the note that would be created, without creating it.",
+)
+@click.pass_obj
+@require_auth
+@restrict_in_restricted_mode("writes to Dynamics CRM records")
+def case_note(
+    ctx: "DxsContext",
+    ticket_number: str,
+    text: str | None,
+    text_file: Path | None,
+    subject: str | None,
+    dry_run: bool,
+) -> None:
+    """Add an internal note to a case.
+
+    Writes an annotation — what the CRM Notes tab shows and what
+    'dxs crm case get --include-notes' reads back. It is internal to staff:
+    the customer does not see it on the support portal. To reply to the
+    customer, use 'dxs crm case comment' instead.
+
+    \b
+    Arguments:
+        TICKET_NUMBER  Case ticket number (e.g. C260303_0017)
+        TEXT           The note body (or use --text-file)
+
+    \b
+    Examples:
+        dxs crm case note C260303_0017 "Root cause is the material swap rule."
+        dxs crm case note C260303_0017 --text-file findings.md
+        dxs crm case note C260303_0017 "Checked the logs" --dry-run
+
+    \b
+    Ticket numbers are not unique. If this one matches more than one case the
+    command fails rather than picking one — pull the case list with
+    'dxs crm case get <ticket>' and note the right one by GUID.
+    """
+    body = _read_body(text, text_file, "the note")
+
+    client = DynamicsClient()
+
+    ctx.log(f"Resolving case {ticket_number}...")
+    incident = _resolve_case_for_write(client, ticket_number)
+    incident_id = incident["incidentid"]
+
+    payload: dict[str, Any] = {
+        "notetext": _wrap_note_html(body),
+        "isdocument": False,
+        "objectid_incident@odata.bind": f"/incidents({incident_id})",
+    }
+    if subject:
+        payload["subject"] = subject
+
+    item: dict[str, Any] = {
+        "ticketnumber": incident.get("ticketnumber"),
+        "case_title": incident.get("title"),
+        "incident_id": incident_id,
+        "visibility": "internal",
+    }
+
+    if dry_run:
+        ctx.output(single(item={**item, "dry_run": True, "record": payload}, semantic_key="note"))
+        return
+
+    ctx.log(f"Adding note to {incident.get('ticketnumber')}...")
+    note_id = client.create(f"/{_ANNOTATION_ENTITY_SET}", payload)
+
+    ctx.output(single(item={**item, "note_id": note_id, "created": True}, semantic_key="note"))
+
+
+@case.command("comment")
+@click.argument("ticket_number")
+@click.argument("text", required=False, default=None)
+@click.option(
+    "--text-file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Read the comment body from a file instead of the command line.",
+)
+@click.option(
+    "--to",
+    "to_contact",
+    default=None,
+    help="Recipient contact - name, email or GUID. Defaults to the case's primary contact.",
+)
+@click.option("--yes", is_flag=True, default=False, help="Skip the confirmation prompt.")
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Show the comment that would be posted, without posting it.",
+)
+@click.pass_obj
+@require_auth
+@restrict_in_restricted_mode("writes to Dynamics CRM records")
+def case_comment(
+    ctx: "DxsContext",
+    ticket_number: str,
+    text: str | None,
+    text_file: Path | None,
+    to_contact: str | None,
+    yes: bool,
+    dry_run: bool,
+) -> None:
+    """Reply to the customer on a case (visible to them).
+
+    Posts an outgoing portal comment — what the customer reads and replies to
+    on the support portal, and what 'dxs crm activity portalcomment' lists.
+    This is customer-facing, so it confirms before posting unless --yes is
+    given. For a staff-only note, use 'dxs crm case note' instead.
+
+    \b
+    Arguments:
+        TICKET_NUMBER  Case ticket number (e.g. C260303_0017)
+        TEXT           The comment body (or use --text-file)
+
+    \b
+    Examples:
+        dxs crm case comment C260303_0017 "We've identified the cause."
+        dxs crm case comment C260303_0017 --text-file reply.md --dry-run
+        dxs crm case comment C260303_0017 "Fixed in 2.4" --to kelly@example.com --yes
+
+    \b
+    The recipient defaults to the case's primary contact. Run --dry-run first
+    to see who that resolves to.
+    """
+    from dxs.utils.errors import ApiError, DxsError, ValidationError
+
+    body = _read_body(text, text_file, "the comment")
+
+    client = DynamicsClient()
+
+    ctx.log(f"Resolving case {ticket_number}...")
+    incident = _resolve_case_for_write(client, ticket_number)
+    incident_id = incident["incidentid"]
+
+    account_name = incident.get("_customerid_value@OData.Community.Display.V1.FormattedValue") or ""
+    contact_id: str | None
+    if to_contact:
+        account_id = incident.get("_customerid_value")
+        if not account_id:
+            raise ValidationError(
+                message=f"Case {ticket_number} has no customer account to look up contacts in",
+                code="DXS-CRM-CASE-RECIPIENT",
+                suggestions=["Pass --to as a contact GUID"],
+            )
+        contact_id, contact_name = _resolve_contact(client, account_id, account_name, to_contact)
+    else:
+        contact_id = incident.get("_primarycontactid_value")
+        contact_name = (
+            incident.get("_primarycontactid_value@OData.Community.Display.V1.FormattedValue") or ""
+        )
+        if not contact_id:
+            raise ValidationError(
+                message=f"Case {ticket_number} has no primary contact to reply to",
+                code="DXS-CRM-CASE-RECIPIENT",
+                suggestions=[
+                    "Name the recipient explicitly: --to <name|email>",
+                    f"List the account's contacts: dxs crm account contacts '{account_name}'",
+                ],
+            )
+
+    sender_id = client.whoami()
+
+    payload: dict[str, Any] = {
+        "description": _wrap_note_html(body),
+        "adx_portalcommentdirectioncode": _COMMENT_DIRECTION_OUTGOING,
+        "regardingobjectid_incident_adx_portalcomment@odata.bind": f"/incidents({incident_id})",
+        "adx_portalcomment_activity_parties": [
+            {
+                "partyid_systemuser@odata.bind": f"/systemusers({sender_id})",
+                "participationtypemask": _PARTY_SENDER,
+            },
+            {
+                "partyid_contact@odata.bind": f"/contacts({contact_id})",
+                "participationtypemask": _PARTY_RECIPIENT,
+            },
+        ],
+    }
+
+    item: dict[str, Any] = {
+        "ticketnumber": incident.get("ticketnumber"),
+        "case_title": incident.get("title"),
+        "incident_id": incident_id,
+        "recipient": {"id": contact_id, "name": contact_name},
+        "account": account_name,
+        "visibility": "customer",
+    }
+
+    if dry_run:
+        ctx.output(
+            single(item={**item, "dry_run": True, "record": payload}, semantic_key="comment")
+        )
+        return
+
+    if not yes:
+        # click.echo, not ctx.log: the preview is part of the prompt, and being
+        # asked to approve a customer-facing message without seeing it — which
+        # is what --quiet would otherwise do — is worse than not being asked.
+        preview = [
+            "This posts a reply the customer will see on the support portal.",
+            f"  Case:      {incident.get('ticketnumber')} ({account_name})",
+            f"  Recipient: {contact_name}",
+            "",
+            *(f"  | {line}" for line in body.strip().splitlines()),
+            "",
+        ]
+        click.echo("\n".join(preview), err=True)
+        click.confirm("Post this comment to the customer?", abort=True, err=True)
+
+    ctx.log(f"Posting comment on {incident.get('ticketnumber')}...")
+    comment_id = client.create(f"/{_PORTAL_COMMENT_ENTITY_SET}", payload)
+
+    # Second step, not decoration: a comment left Open is a draft the customer
+    # never sees, so a failure here is reported as a failure to send.
+    try:
+        client.patch(
+            f"/{_PORTAL_COMMENT_ENTITY_SET}({comment_id})",
+            {"statecode": _COMMENT_STATE_COMPLETED, "statuscode": _COMMENT_STATUS_SENT},
+        )
+    except DxsError as exc:
+        raise ApiError(
+            message=(
+                f"Comment saved as a draft on {incident.get('ticketnumber')} but could not "
+                f"be marked sent - the customer will not see it ({exc.message})"
+            ),
+            code="DXS-CRM-COMMENT-UNSENT",
+            details={"comment_id": comment_id, "incident_id": incident_id},
+            suggestions=[
+                "Mark it sent in CRM, or delete the draft and retry: "
+                f'dxs crm odata adx_portalcomments -f "activityid eq {comment_id}"',
+            ],
+        ) from exc
+
+    ctx.output(
+        single(item={**item, "comment_id": comment_id, "created": True}, semantic_key="comment")
+    )
+
+
 @case.command("get")
 @click.argument("ticket_number")
 @click.option(

{datex_studio_cli-0.4.14 → datex_studio_cli-0.4.15}/src/dxs/core/dynamics/client.py

@@ -896,7 +896,7 @@ class DynamicsClient:
     INCIDENT_SELECT = (
         "incidentid,ticketnumber,title,description,"
         "statecode,statuscode,createdon,modifiedon,"
-        "_customerid_value,_ownerid_value,"
+        "_customerid_value,_ownerid_value,_primarycontactid_value,"
         "casetypecode,prioritycode,severitycode,daa_immediatebusinessimpact,"
         "isescalated,escalatedon,resolveby,responseby,"
         "adx_resolution,adx_resolutiondate"
@@ -915,6 +915,15 @@ class DynamicsClient:
             )
         return ",".join(expand_parts)
 
+    def whoami(self) -> str:
+        """Return the calling user's systemuserid.
+
+        Needed to name the sender on an outgoing activity: the platform sets
+        ``ownerid`` on its own, but the sender activity party has to be built
+        explicitly.
+        """
+        return cast(str, self.get("/WhoAmI")["UserId"])
+
     def list_contacts_for_account(self, account_id: str) -> dict[str, Any]:
         """List the active contacts belonging to an account.