Metadata-Version: 2.5
Name: render-lab-tasks-zendesk
Version: 0.1.0
Summary: zendesk tasks for Render Workflows
Project-URL: Repository, https://github.com/render-lab/render-tasks-python
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: httpx<0.29,>=0.28
Requires-Dist: render-lab-tasks-core<0.2,>=0.1.1
Requires-Dist: render-lab-triggers<0.2,>=0.1.0
Requires-Dist: render==1.0.1
Description-Content-Type: text/markdown

# render-lab-tasks-zendesk

Unreleased Python port: **11 registered tasks** from
[render-lab/render-tasks](https://github.com/render-lab/render-tasks/tree/45f9c2d44bd28e01ae9813e0d2ff56ee6c533816/packages/tasks-zendesk).
Python 3.12+, Render SDK 1.0.1. Requires core 0.1.1 or later.

From the repository root:

```sh
uv sync --all-packages --locked
```

Import `render_lab_tasks_zendesk.tasks` to register tasks. The package root is inert.
Compose the exported `app` with `Workflows.from_workflows`; call tasks through
`ctx.run`. Every operation also exports `*_impl(ctx, input, *, deps=None)` for
injection. `Client(http, env)` accepts a caller-owned HTTPX client, and
`Deps(zendesk=client)` injects it. Default dependencies open and close the HTTP
client per invocation; credentials are read lazily at use. No HTTP retries or
background vendor polling occur; `retry.py` owns the durable retry policies.

## Task surface

| Registered task | Python export |
| --- | --- |
| `zendesk.awaitJob` | `await_job` |
| `zendesk.createTicket` | `create_ticket` |
| `zendesk.getJobStatus` | `get_job_status` |
| `zendesk.getTicket` | `get_ticket` |
| `zendesk.incrementalExportTickets` | `incremental_export_tickets` |
| `zendesk.listTicketComments` | `list_ticket_comments` |
| `zendesk.replyToTicket` | `reply_to_ticket` |
| `zendesk.searchTickets` | `search_tickets` |
| `zendesk.startBulkUpdate` | `start_bulk_update` |
| `zendesk.updateTicket` | `update_ticket` |
| `zendesk.verifyWebhook` | `verify_webhook` |

Typed JSON inputs and results are in `types.py`. Task names and JSON field names
match the pinned source; Python function names use snake_case.

## Environment

| Variable | Requirement |
| --- | --- |
| `ZENDESK_SUBDOMAIN` | Required for REST calls. |
| `ZENDESK_OAUTH_TOKEN` | Preferred REST bearer token. |
| `ZENDESK_EMAIL` | Required with ZENDESK_API_TOKEN when no OAuth token is set. |
| `ZENDESK_API_TOKEN` | Basic-auth fallback with ZENDESK_EMAIL. |
| `ZENDESK_WEBHOOK_SECRET` | Required only for verify_webhook; no REST credentials needed. |

## Behavior and limits

Writes preserve safe_update and the caller’s updated_stamp. A 409 from update_ticket raises ZendeskUpdateConflictError with ticketId; re-fetch and decide whether to replay the change. The pinned durable retry policy still retries task errors, so this error class alone does not bypass Render retries. Bulk updates cap at 100 tickets, pages at 100 records, and returned page arrays at 3.5 MB. Signature checks use HMAC-SHA256 over timestamp + rawBody, constant-time comparison, and a default 300-second age limit. Jobs, cursor search support, and real webhook timestamps need live verification.

## Verification

All registered tasks have hermetic contract fixtures executed independently against
the pinned TS implementation. SDK-backed tasks also have explicit HTTP request
fixtures. See `tests/test_batch3_contracts.py` and `tests/test_batch3_edges.py`.
These are not live vendor results.

Vendor webhooks subpaths and other registration-free TS exports are outside this
batch unless explicitly listed above. Full registered-task coverage does not
imply all supporting exports are ported.

Pending scopes, test resources, replay, and hosted checks are in the
[live-testing backlog](https://github.com/render-lab/render-tasks-python/issues/1)
and [verification tracker](../../docs/verification-tracker.md).

## Webhook adapter

`render_lab_tasks_zendesk.webhooks.zendesk_adapter(on_event, ...)` returns a
registration-free adapter for `render_lab_triggers`. The callback receives the
verified event and returns `{"task": "namespace.task", "args": [event]}` or `None`.
The signing credential `ZENDESK_WEBHOOK_SECRET` is read inside verification unless
provided explicitly. Importing this module does not register tasks. Signature
checks use the raw body; live delivery remains in the testing backlog.

## Installation

```sh
pip install render-lab-tasks-zendesk==0.1.0
```
