nexthink_api 0.1.1__py3-none-any.whl

docs/Campaigns.md

@@ -0,0 +1,36 @@
+# Campaigns
+
+Campaigns exposes Nexthink campaign triggering through
+`NexthinkClient.campaigns`.
+
+Triggering a campaign sends it to real users. Keep an explicit operator
+confirmation in scripts that run outside tests.
+
+## Trigger a campaign
+
+```python
+from nexthink_api import NexthinkClient, NxtRegionName
+from nexthink_api.Campaigns import NxtCampaignTriggerRequest
+
+client = NexthinkClient(
+    instance="example",
+    region=NxtRegionName.eu,
+    client_id="client-id",
+    client_secret="client-secret",
+)
+
+request = NxtCampaignTriggerRequest(
+    campaignNqlId="#campaign_nql_id",
+    userSid=["S-1-5-21-..."],
+    expiresInMinutes=60,
+    parameters={"language": "fr"},
+)
+
+result = client.campaigns.trigger(request)
+```
+
+`userSid` accepts between 1 and 10000 user SIDs. `expiresInMinutes` must be
+between 1 and 525600. `parameters` accepts up to 30 entries when provided.
+
+See [Campaigns object models](object-models/Campaigns.md) for the request and
+response classes used by this domain.

docs/DataManagement.md

@@ -0,0 +1,108 @@
+# Data Management
+
+The Data Management API schedules device deletions from the Nexthink inventory.
+
+Use `NexthinkClient.data_management.delete_devices()` with one to 100 devices. The API is
+asynchronous: a `202 ACCEPTED` response means the deletion batch was queued, not
+that devices have already been removed. Inspect each returned device status to
+confirm whether a device was scheduled, rejected as invalid, or failed.
+
+## Batch Limit And Asynchronous Behavior
+
+Each request must contain at least one device and at most 100 devices. Split
+larger deletion sets into multiple batches before calling `delete_devices()`.
+
+Deletion scheduling is asynchronous. A successful `202 ACCEPTED` response only
+confirms that the API accepted the batch for processing. It does not confirm
+that inventory deletion has already completed.
+
+## Schedule Device Deletions
+
+```python
+from nexthink_api import (
+    NexthinkClient,
+    NxtDeviceEntry,
+    NxtRegionName,
+    NxtUidValidationMode,
+)
+
+client = NexthinkClient(
+    instance="tenant-name",
+    region=NxtRegionName.eu,
+    client_id="client-id",
+    client_secret="client-secret",
+)
+
+response = client.data_management.delete_devices(
+    # Maximum 100 devices per request. Split larger inputs into batches.
+    devices=[
+        NxtDeviceEntry(
+            uid="00000000-0000-0000-0000-000000000000",
+            name="DEVICE-1",
+        ),
+    ],
+    request_id="11111111-1111-1111-1111-111111111111",
+    uid_validation=NxtUidValidationMode.WARN,
+)
+
+for device in response.devices:
+    # The API is asynchronous: SCHEDULED means queued, not already deleted.
+    print(device.uid, device.name, device.status)
+```
+
+## UID Validation
+
+`delete_devices()` validates UID format before the request. The default mode is
+`NxtUidValidationMode.WARN`.
+
+| Mode | Behavior |
+| --- | --- |
+| `STRICT` | Raises `ValueError` before the API call if any UID is malformed. |
+| `WARN` | Logs malformed UIDs and still sends the request. |
+| `PERMISSIVE` | Sends the request without local UID warnings. |
+
+`WARN` and `PERMISSIVE` allow the API to return per-device `INVALID` statuses,
+which is useful when testing or preserving server-side behavior.
+
+## Correlation Header
+
+Pass `request_id` to send an optional `x-request-id` header for support
+correlation:
+
+```python
+client.data_management.delete_devices(
+    devices=[NxtDeviceEntry(uid="00000000-0000-0000-0000-000000000000", name="DEVICE-1")],
+    request_id="11111111-1111-1111-1111-111111111111",
+)
+```
+
+The request header is applied only to that call and does not mutate the client's
+stored headers.
+
+When the API returns an `x-request-id` response header, Data Management success
+and error responses expose it as `response.request_id`.
+
+## Responses
+
+Successful scheduling returns `NxtDeviceDeletionResponse`:
+
+```python
+if response.status == "ACCEPTED":
+    for device in response.devices:
+        if device.status == "SCHEDULED":
+            print(f"{device.name} queued for deletion")
+```
+
+Documented device statuses are:
+
+| Status | Meaning |
+| --- | --- |
+| `SCHEDULED` | Device deletion was queued. |
+| `INVALID` | Device entry was rejected, for example because the UID is malformed. |
+| `FAILED` | Device could not be scheduled for deletion. |
+
+Documented error responses are represented by `NxtDataManagementErrorResponse`.
+`401` responses are represented by `NxtInvalidTokenRequest`.
+
+See [Data Management object models](object-models/DataManagement.md) for the
+request and response classes used by this domain.

docs/Enrichment.md

@@ -0,0 +1,67 @@
+# Enrichment
+
+Enrichment writes custom fields to Nexthink objects through
+`NexthinkClient.enrichment`.
+
+## Run Enrichment
+
+```python
+from nexthink_api import (
+    NexthinkClient,
+    NxtEnrichment,
+    NxtEnrichmentRequest,
+    NxtField,
+    NxtFieldName,
+    NxtIdentification,
+    NxtIdentificationName,
+    NxtRegionName,
+)
+
+client = NexthinkClient(
+    instance="tenant-name",
+    region=NxtRegionName.eu,
+    client_id="client-id",
+    client_secret="client-secret",
+)
+
+request = NxtEnrichmentRequest(
+    domain="automation",
+    enrichments=[
+        NxtEnrichment(
+            identification=[
+                NxtIdentification(
+                    name=NxtIdentificationName.DEVICE_DEVICE_NAME,
+                    value="DEVICE-1",
+                )
+            ],
+            fields=[
+                NxtField(
+                    name=NxtFieldName.CUSTOM_DEVICE,
+                    value="patched",
+                    custom_value="maintenance_status",
+                )
+            ],
+        )
+    ],
+)
+
+response = client.enrichment.run(request)
+```
+
+## Request Limits
+
+`NxtEnrichmentRequest.enrichments` accepts between 1 and
+`MAX_ENRICHMENTS_PER_REQUEST` objects. The constant is exported by the package
+so applications can check or split their payload before creating the request.
+
+```python
+from nexthink_api import MAX_ENRICHMENTS_PER_REQUEST
+
+if len(enrichments) > MAX_ENRICHMENTS_PER_REQUEST:
+    raise ValueError(
+        f"Enrichment request contains more than {MAX_ENRICHMENTS_PER_REQUEST} objects"
+    )
+```
+
+See [Enrichment object models](object-models/Enrichment.md) for the request and
+response classes used by this domain.

docs/Nql.md

@@ -0,0 +1,34 @@
+# NQL
+
+NQL executes saved query IDs and starts exports through `NexthinkClient.nql`.
+
+## Execute a query
+
+```python
+from nexthink_api import NexthinkClient, NxtNqlApiExecuteRequest, NxtRegionName
+
+client = NexthinkClient(
+    instance="tenant-name",
+    region=NxtRegionName.eu,
+    client_id="client-id",
+    client_secret="client-secret",
+)
+
+request = NxtNqlApiExecuteRequest(queryId="#query_nql_id")
+response = client.nql.execute(request, version="v2")
+```
+
+## Export and download
+
+```python
+export = client.nql.export(request)
+status = client.nql.wait(export, timeout=300)
+download_response = client.nql.download(status)
+dataframe = client.nql.download_dataframe(status)
+```
+
+`execute()` supports `version="v1"` and `version="v2"`. New code should use
+`v2` unless a tenant-specific constraint requires the historical endpoint.
+
+See [NQL object models](object-models/Nql.md) for the request and response
+classes used by this domain.

docs/RemoteActions.md

@@ -0,0 +1,52 @@
+# Remote Actions
+
+Remote Actions exposes Nexthink remote action catalog lookup and execution
+through `NexthinkClient.remote_actions`.
+
+The execution endpoint has a side effect on target devices. Keep an explicit
+operator confirmation in scripts that trigger a real action.
+
+## List and inspect actions
+
+```python
+from nexthink_api import NexthinkClient, NxtRegionName
+
+client = NexthinkClient(
+    instance="example",
+    region=NxtRegionName.eu,
+    client_id="client-id",
+    client_secret="client-secret",
+)
+
+actions = client.remote_actions.list()
+details = client.remote_actions.get("#remote_action_nql_id")
+```
+
+## Execute a remote action
+
+```python
+from nexthink_api.RemoteActions import (
+    NxtRemoteActionExecutionRequest,
+    NxtRemoteActionTriggerInfoRequest,
+)
+
+request = NxtRemoteActionExecutionRequest(
+    remoteActionId="#remote_action_nql_id",
+    devices=["collector-uid"],
+    params={"argumentName": "argumentValue"},
+    expiresInMinutes=60,
+    triggerInfo=NxtRemoteActionTriggerInfoRequest(
+        externalSource="automation",
+        reason="maintenance",
+        externalReference="ticket-123",
+    ),
+)
+
+result = client.remote_actions.execute(request)
+```
+
+`devices` accepts between 1 and 10000 collector IDs. `expiresInMinutes` must be
+between 60 and 10080 when provided.
+
+See [Remote Actions object models](object-models/RemoteActions.md) for the
+request and response classes used by this domain.

docs/Spark.md

@@ -0,0 +1,62 @@
+# Spark
+
+Spark exposes conversation handoff through `NexthinkClient.spark`.
+
+The handoff endpoint requires a target user principal name in the request
+headers. The client takes it as an explicit argument so scripts do not hide
+which user context is used.
+
+## Hand off a text message
+
+```python
+from nexthink_api import NexthinkClient, NxtRegionName
+from nexthink_api.Spark import (
+    NxtSparkHandoffConversationMessageRequest,
+    NxtSparkMessageDTO,
+    NxtSparkTextPartDTO,
+)
+
+client = NexthinkClient(
+    instance="example",
+    region=NxtRegionName.eu,
+    client_id="client-id",
+    client_secret="client-secret",
+)
+
+request = NxtSparkHandoffConversationMessageRequest(
+    message=NxtSparkMessageDTO(
+        parts=[NxtSparkTextPartDTO(text="Summarize the current device health.")]
+    ),
+    metadata={"source": "automation"},
+)
+
+result = client.spark.handoff(
+    request,
+    user_principal_name="user@example.com",
+    timezone="Europe/Paris",
+)
+```
+
+`user_principal_name` is required. `timezone` is optional and is sent as the
+Spark `Timezone` header when provided.
+
+## Include file content
+
+```python
+from nexthink_api.Spark import NxtSparkFilePartByContent
+
+request = NxtSparkHandoffConversationMessageRequest(
+    message=NxtSparkMessageDTO(
+        parts=[
+            NxtSparkTextPartDTO(text="Analyze this CSV."),
+            NxtSparkFilePartByContent(
+                fileContent="base64-encoded-content",
+                mimeType="text/csv",
+            ),
+        ]
+    )
+)
+```
+
+See [Spark object models](object-models/Spark.md) for the request and response
+classes used by this domain.

docs/Workflows.md

@@ -0,0 +1,81 @@
+# Workflows
+
+Workflows exposes Nexthink workflow metadata lookup and execution through
+`NexthinkClient.workflows`.
+
+Workflow execution has a side effect on users or devices. Keep explicit
+confirmation in scripts that execute a real workflow.
+
+## List and inspect workflows
+
+```python
+from nexthink_api import NexthinkClient, NxtRegionName
+from nexthink_api.Workflows import NxtWorkflowDependency, NxtWorkflowTriggerMethod
+
+client = NexthinkClient(
+    instance="example",
+    region=NxtRegionName.eu,
+    client_id="client-id",
+    client_secret="client-secret",
+)
+
+workflows = client.workflows.list(
+    dependency=NxtWorkflowDependency.USER,
+    trigger_method=NxtWorkflowTriggerMethod.API,
+    fetch_only_active_workflows=True,
+)
+details = client.workflows.get("#workflow_nql_id")
+```
+
+## Execute with Workflows v1
+
+Use v1 when you already have Nexthink collector IDs for devices or SIDs for
+users.
+
+```python
+from nexthink_api.Workflows import NxtWorkflowExecutionRequest
+
+request = NxtWorkflowExecutionRequest(
+    workflowId="#workflow_nql_id",
+    devices=["collector-uid"],
+    params={"inputName": "inputValue"},
+)
+
+result = client.workflows.execute(request, source="automation")
+```
+
+## Execute with Workflows v2 external identifiers
+
+Use v2 when the caller naturally has external identifiers such as UPNs, device
+names, device UIDs, or collector UIDs.
+
+```python
+from nexthink_api.Workflows import (
+    NxtWorkflowExternalIdsExecutionRequest,
+    NxtWorkflowUserData,
+)
+
+request = NxtWorkflowExternalIdsExecutionRequest(
+    workflowId="#workflow_nql_id",
+    users=[NxtWorkflowUserData(upn="user@example.com")],
+    params={"inputName": "inputValue"},
+)
+
+result = client.workflows.execute_with_external_ids(request, source="automation")
+```
+
+Both execution request types require at least one device or user target. Target
+lists accept up to 10000 entries.
+
+## Trigger a thinklet
+
+```python
+result = client.workflows.trigger_thinklet(
+    workflow_uuid="workflow-uuid",
+    execution_uuid="execution-uuid",
+    source="automation",
+)
+```
+
+See [Workflows object models](object-models/Workflows.md) for the request and
+response classes used by this domain.

docs/examples.md

@@ -0,0 +1,161 @@
+# Python Nexthink
+
+This Python library provides a small client for the
+[Nexthink API](https://docs.nexthink.com/api).
+
+## Installation
+
+```bash
+pip install nexthink_api
+# or
+uv add nexthink_api
+```
+
+## Source And Documentation
+
+- [Repository source](https://github.com/ltaupiac/nexthink_api)
+- [Online documentation](https://ltaupiac.github.io/nexthink_api/)
+- [Official Nexthink API documentation](https://docs.nexthink.com/api)
+
+## Quickstart
+
+The recommended entrypoint for new code is `NexthinkClient`. The historical
+`NxtApiClient` remains available as a compatibility facade.
+
+The examples below assume these environment variables are set:
+
+```bash
+export nexthink_tenant="your-tenant-name"
+export nexthink_region="eu"
+export client_id="your-client-id"
+export client_secret="your-client-secret"
+```
+
+When running behind a corporate proxy with TLS inspection, for example Zscaler,
+call `enable_truststore()` before creating the client. This enables the
+operating system trust store for Nexthink HTTP calls without permanently
+patching Python SSL for the whole process.
+
+```python
+import os
+
+from nexthink_api import NexthinkClient, NxtRegionName, enable_truststore
+
+enable_truststore()
+
+client = NexthinkClient(
+    os.environ["nexthink_tenant"],
+    NxtRegionName(os.getenv("nexthink_region", NxtRegionName.eu.value)),
+    client_id=os.environ["client_id"],
+    client_secret=os.environ["client_secret"],
+)
+```
+
+### NQL Execute
+
+The NQL query must already exist in Nexthink Administration as an API query.
+
+```python
+import os
+
+from nexthink_api import NxtNqlApiExecuteRequest
+
+request = NxtNqlApiExecuteRequest(
+    queryId=os.environ["nexthink_nql_query_id"],
+)
+
+response = client.nql.execute(request, version="v2")
+print(response.rows)
+print(response.data)
+```
+
+### Enrichment
+
+This example updates one custom device field for one device identified by name.
+
+```python
+import os
+from datetime import datetime
+
+from nexthink_api import (
+    MAX_ENRICHMENTS_PER_REQUEST,
+    NxtEnrichment,
+    NxtEnrichmentRequest,
+    NxtField,
+    NxtFieldName,
+    NxtIdentification,
+    NxtIdentificationName,
+)
+
+identification = NxtIdentification(
+    name=NxtIdentificationName.DEVICE_DEVICE_NAME,
+    value=os.environ["nexthink_enrichment_device_name"],
+)
+field = NxtField(
+    name=NxtFieldName.CUSTOM_DEVICE,
+    custom_value="nexthink_api_example",
+    value=datetime.now().isoformat(),
+)
+enrichments = [NxtEnrichment(identification=[identification], fields=[field])]
+
+if len(enrichments) > MAX_ENRICHMENTS_PER_REQUEST:
+    raise ValueError("Too many enrichment objects for one request")
+
+request = NxtEnrichmentRequest(
+    domain=os.getenv("nexthink_enrichment_domain", "nexthink_api_example"),
+    enrichments=enrichments,
+)
+
+response = client.enrichment.run(request)
+print(response)
+```
+
+### Data Management Device Deletion
+
+The Data Management deletion API is asynchronous and destructive. Keep an
+explicit confirmation in scripts and validate identifiers before calling it.
+
+```python
+import os
+
+from nexthink_api import NxtDeviceEntry, NxtUidValidationMode
+
+if os.getenv("confirm_data_management_delete") != "yes":
+    raise SystemExit("Set confirm_data_management_delete=yes before deleting devices.")
+
+devices = [
+    NxtDeviceEntry(
+        uid=os.environ["nexthink_device_uid"],
+        name=os.environ["nexthink_device_name"],
+    )
+]
+
+response = client.data_management.delete_devices(
+    devices=devices,
+    request_id=os.environ["nexthink_request_id"],
+    uid_validation=NxtUidValidationMode.WARN,
+)
+print(response)
+```
+
+## Examples
+
+Runnable examples are available in `examples/`:
+
+```bash
+uv run python examples/nql_query_example.py
+uv run python examples/enrichment_example.py
+uv run python examples/data_management_device_deletion_example.py
+uv run python examples/remote_actions_example.py
+uv run python examples/campaigns_example.py
+uv run python examples/workflows_example.py
+uv run python examples/spark_handoff_example.py
+```
+
+## API Classes
+
+Most request and response classes are Pydantic models. Use:
+
+- `model_dump()` to serialize to a dictionary.
+- `model_dump_json()` to serialize to JSON.
+- `model_validate(data)` to build a model from serialized data.

docs/extra.css

@@ -0,0 +1,4 @@
+ div.doc.doc-object.doc-class, div.doc.doc-object.doc-function { 
+  border-top: 1px solid #cc4333;
+}
+

docs/index.md

@@ -0,0 +1,56 @@
+# nexthink_api
+
+Python client for the [Nexthink API](https://docs.nexthink.com/api).
+
+## Documentation Sources
+
+The official Nexthink API documentation is the upstream reference:
+
+- [Nexthink API documentation](https://docs.nexthink.com/api)
+- [Nexthink API sitemap](https://docs.nexthink.com/api/sitemap.md)
+- [Nexthink API LLM snapshot](https://docs.nexthink.com/api/llms-full.txt)
+
+Runtime behavior does not depend on downloading YAML files from the Nexthink
+documentation site. The package contract is defined by the Python models,
+domain clients, tests, and the local `SpecRegistry`.
+
+## Public Client
+
+Use `NexthinkClient` for new code:
+
+```python
+from nexthink_api import NexthinkClient, NxtRegionName
+
+client = NexthinkClient(
+    "tenant-name",
+    NxtRegionName.eu,
+    client_id="client-id",
+    client_secret="client-secret",
+)
+```
+
+The historical `NxtApiClient` remains available as a compatibility facade.
+
+## Supported Domains
+
+- Enrichment
+- NQL
+- Data Management
+- Remote Actions
+- Campaigns
+- Workflows
+- Spark
+
+## Corporate Proxy TLS Inspection
+
+When running behind a corporate proxy with TLS inspection, for example Zscaler,
+call `enable_truststore()` before creating the client:
+
+```python
+from nexthink_api import enable_truststore
+
+enable_truststore()
+```
+
+This enables the operating system trust store for Nexthink HTTP calls without
+permanently patching Python SSL for the whole process.