dex-connector-helpscout 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- dex_connector_helpscout-0.1.0/.gitignore +16 -0
- dex_connector_helpscout-0.1.0/LICENSE +21 -0
- dex_connector_helpscout-0.1.0/PKG-INFO +61 -0
- dex_connector_helpscout-0.1.0/README.md +48 -0
- dex_connector_helpscout-0.1.0/examples/conversation_search/README.md +13 -0
- dex_connector_helpscout-0.1.0/examples/conversation_search/__init__.py +3 -0
- dex_connector_helpscout-0.1.0/examples/conversation_search/flow.py +75 -0
- dex_connector_helpscout-0.1.0/examples/conversation_search/input.example.json +1 -0
- dex_connector_helpscout-0.1.0/examples/conversation_search/worker.py +51 -0
- dex_connector_helpscout-0.1.0/integration/conversation_search.py +81 -0
- dex_connector_helpscout-0.1.0/pyproject.toml +41 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/__init__.py +18 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/_generated/__init__.py +2 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/_generated/config.py +27 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/_generated/connection.py +202 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/_generated/definitions.py +113 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/_generated/mock.py +338 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/_generated/models.py +366 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/_generated/refresh.py +9 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/_generated/steps.py +296 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/_generated/timestamps.py +60 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/client.py +328 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/connection.py +12 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/decode.py +203 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/dex-connector.json +201 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/helpscoutmock/__init__.py +6 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/json_values.py +23 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/models.py +5 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/operations.py +1012 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/py.typed +0 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/query_values.py +16 -0
- dex_connector_helpscout-0.1.0/src/dex_connectors/helpscout/steps.py +5 -0
- dex_connector_helpscout-0.1.0/tests/refresh_agreement_cases.json +277 -0
- dex_connector_helpscout-0.1.0/tests/test_client.py +103 -0
- dex_connector_helpscout-0.1.0/tests/test_conformance.py +44 -0
- dex_connector_helpscout-0.1.0/tests/test_json_values.py +15 -0
- dex_connector_helpscout-0.1.0/tests/test_query_values.py +36 -0
- dex_connector_helpscout-0.1.0/tests/test_refresh_agreement.py +278 -0
- dex_connector_helpscout-0.1.0/uv.lock +934 -0
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
.DS_Store
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
node_modules/
|
|
5
|
+
dist/
|
|
6
|
+
sdkpython/dist/dex_connectors_sdk-0.1.0-py3-none-any.whl
|
|
7
|
+
/.bin/dexcli
|
|
8
|
+
/.bin/dex-server-zd
|
|
9
|
+
/sdkpython/.dexcli-data/
|
|
10
|
+
site/.catalog.yaml
|
|
11
|
+
coverage/
|
|
12
|
+
*.out
|
|
13
|
+
*.test
|
|
14
|
+
go.work
|
|
15
|
+
go.work.sum
|
|
16
|
+
.idea/
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Super Durable
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: dex-connector-helpscout
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Dex-native Help Scout Inbox connector
|
|
5
|
+
Project-URL: Source, https://github.com/superdurable/dex-connectors-library/tree/main/connectors/helpscout/python
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Requires-Python: >=3.11
|
|
9
|
+
Requires-Dist: dex-connectors-sdk==0.7.0
|
|
10
|
+
Requires-Dist: dex-python-sdk>=1.28.0
|
|
11
|
+
Requires-Dist: httpx>=0.27
|
|
12
|
+
Description-Content-Type: text/markdown
|
|
13
|
+
|
|
14
|
+
# Help Scout Python connector
|
|
15
|
+
|
|
16
|
+
`dex-connector-helpscout` provides Dex-native Queries for Help Scout Inbox conversation search, conversation detail, and customer lookup, plus Mutations for replies, notes, and conversation updates. The Python package implements the five listed operations. The `conversationEvent` webhook Trigger remains Go-only.
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
uv add dex-connector-helpscout==0.1.0
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
This package requires `dex-connectors-sdk==0.5.0` and `dex-python-sdk>=1.28.0`.
|
|
25
|
+
|
|
26
|
+
## Configure a connection
|
|
27
|
+
|
|
28
|
+
In Dex Web **Connections**, create a `helpscout` connection named `helpscout`. Sign in at [Help Scout](https://secure.helpscout.net/), open your avatar, then **Your Profile > My Apps**, and create an app. Copy its App ID into `app_id` and its secret App Secret into `app_secret`. Leave `access_token` blank: the generated client credentials driver requests and renews it using Help Scout's token endpoint. Help Scout apps have no scopes. The Free plan has no API access. The app acts with its owner's inbox permissions.
|
|
29
|
+
|
|
30
|
+
The optional `webhook_secret` is for Go's webhook Trigger and is unused by this Python operations package. Leave `maxResponseBytes` and `webhookMaxBodyBytes` blank for manifest defaults. `maxResponseBytes` limits successful API response bodies in bytes; increase it only for large conversation and thread pages. `webhookMaxBodyBytes` applies to the Go webhook endpoint and does not change Python operation requests.
|
|
31
|
+
|
|
32
|
+
`new_project_connection(project, "helpscout")` loads the manifest settings and generated private or shared credential decoders. It resolves credentials at call time, uses the generated refresh driver, and retries once after a provider 401 if the host can refresh. The connection and secrets stay outside Flow input, results, and Attributes. Close the connection after Worker shutdown.
|
|
33
|
+
|
|
34
|
+
## Run the example Flow
|
|
35
|
+
|
|
36
|
+
[`examples/conversation_search/worker.py`](examples/conversation_search/worker.py) is the Worker entrypoint. It loads the named Dex Web connection and registers `HelpScoutConversationSearch`. From this package directory:
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
uv run python -m examples.conversation_search.worker
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Start the Flow with [`input.example.json`](examples/conversation_search/input.example.json). It returns one page and stores it in Flow persistence. The example wires only `searched`, so optional failure branches fail the Flow. Its static Step annotations include the group and explanation for Flow Definition Graph generation.
|
|
43
|
+
|
|
44
|
+
## Operation contract
|
|
45
|
+
|
|
46
|
+
`searchConversations` combines inbox, status, tag, customer email, modification time, and page filters. `getConversation` reads one conversation and the newest thread page, and selects `merged` for Help Scout's redirect to another conversation. `findCustomerByEmail` returns all matches on its first page, up to 50; no match selects `notFound`.
|
|
47
|
+
|
|
48
|
+
`replyToConversation` uses Dex's durable single-dispatch checkpoint. It sends a reply or internal note at most once after an ambiguous outcome and selects `uncertain` when the provider may have accepted it without a confirmable thread ID. A confirmed ID is read back on retry. `updateConversation` compares the current state, sends absolute status, assignee, and tag writes only when needed, and reads the final state back. Repeat attempts converge on the requested values.
|
|
49
|
+
|
|
50
|
+
Every operation uses the generated Step factory and its stable branch IDs. Only the required happy-path branch should be wired by default. The provider can return new conversation status strings, which results preserve unchanged. Treat provider text and HTML as untrusted before rendering.
|
|
51
|
+
|
|
52
|
+
## Verify locally
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
uv sync
|
|
56
|
+
uv run pytest tests -q
|
|
57
|
+
uv run ruff check src tests examples integration
|
|
58
|
+
uv run mypy src/dex_connectors/helpscout
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The package suite replays the Go-recorded provider requests and outcomes and the generated OAuth refresh agreement. For the real Dex Worker and Client test, start `dexcli dev` on unused ports, set `DEX_FLOW_SERVICE_ADDRESS` to its gRPC address, then run `uv run pytest integration/conversation_search.py -q`. The provider stand-ins use an OS-selected transport address; no live Help Scout authorization was available during this port, so real provider token minting and Inbox calls remain unverified.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Help Scout Python connector
|
|
2
|
+
|
|
3
|
+
`dex-connector-helpscout` provides Dex-native Queries for Help Scout Inbox conversation search, conversation detail, and customer lookup, plus Mutations for replies, notes, and conversation updates. The Python package implements the five listed operations. The `conversationEvent` webhook Trigger remains Go-only.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
uv add dex-connector-helpscout==0.1.0
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
This package requires `dex-connectors-sdk==0.5.0` and `dex-python-sdk>=1.28.0`.
|
|
12
|
+
|
|
13
|
+
## Configure a connection
|
|
14
|
+
|
|
15
|
+
In Dex Web **Connections**, create a `helpscout` connection named `helpscout`. Sign in at [Help Scout](https://secure.helpscout.net/), open your avatar, then **Your Profile > My Apps**, and create an app. Copy its App ID into `app_id` and its secret App Secret into `app_secret`. Leave `access_token` blank: the generated client credentials driver requests and renews it using Help Scout's token endpoint. Help Scout apps have no scopes. The Free plan has no API access. The app acts with its owner's inbox permissions.
|
|
16
|
+
|
|
17
|
+
The optional `webhook_secret` is for Go's webhook Trigger and is unused by this Python operations package. Leave `maxResponseBytes` and `webhookMaxBodyBytes` blank for manifest defaults. `maxResponseBytes` limits successful API response bodies in bytes; increase it only for large conversation and thread pages. `webhookMaxBodyBytes` applies to the Go webhook endpoint and does not change Python operation requests.
|
|
18
|
+
|
|
19
|
+
`new_project_connection(project, "helpscout")` loads the manifest settings and generated private or shared credential decoders. It resolves credentials at call time, uses the generated refresh driver, and retries once after a provider 401 if the host can refresh. The connection and secrets stay outside Flow input, results, and Attributes. Close the connection after Worker shutdown.
|
|
20
|
+
|
|
21
|
+
## Run the example Flow
|
|
22
|
+
|
|
23
|
+
[`examples/conversation_search/worker.py`](examples/conversation_search/worker.py) is the Worker entrypoint. It loads the named Dex Web connection and registers `HelpScoutConversationSearch`. From this package directory:
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
uv run python -m examples.conversation_search.worker
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Start the Flow with [`input.example.json`](examples/conversation_search/input.example.json). It returns one page and stores it in Flow persistence. The example wires only `searched`, so optional failure branches fail the Flow. Its static Step annotations include the group and explanation for Flow Definition Graph generation.
|
|
30
|
+
|
|
31
|
+
## Operation contract
|
|
32
|
+
|
|
33
|
+
`searchConversations` combines inbox, status, tag, customer email, modification time, and page filters. `getConversation` reads one conversation and the newest thread page, and selects `merged` for Help Scout's redirect to another conversation. `findCustomerByEmail` returns all matches on its first page, up to 50; no match selects `notFound`.
|
|
34
|
+
|
|
35
|
+
`replyToConversation` uses Dex's durable single-dispatch checkpoint. It sends a reply or internal note at most once after an ambiguous outcome and selects `uncertain` when the provider may have accepted it without a confirmable thread ID. A confirmed ID is read back on retry. `updateConversation` compares the current state, sends absolute status, assignee, and tag writes only when needed, and reads the final state back. Repeat attempts converge on the requested values.
|
|
36
|
+
|
|
37
|
+
Every operation uses the generated Step factory and its stable branch IDs. Only the required happy-path branch should be wired by default. The provider can return new conversation status strings, which results preserve unchanged. Treat provider text and HTML as untrusted before rendering.
|
|
38
|
+
|
|
39
|
+
## Verify locally
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
uv sync
|
|
43
|
+
uv run pytest tests -q
|
|
44
|
+
uv run ruff check src tests examples integration
|
|
45
|
+
uv run mypy src/dex_connectors/helpscout
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
The package suite replays the Go-recorded provider requests and outcomes and the generated OAuth refresh agreement. For the real Dex Worker and Client test, start `dexcli dev` on unused ports, set `DEX_FLOW_SERVICE_ADDRESS` to its gRPC address, then run `uv run pytest integration/conversation_search.py -q`. The provider stand-ins use an OS-selected transport address; no live Help Scout authorization was available during this port, so real provider token minting and Inbox calls remain unverified.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Help Scout conversation search example
|
|
2
|
+
|
|
3
|
+
Run `uv run python -m examples.conversation_search.worker` from `connectors/helpscout/python/` after creating a `helpscout` connection in Dex Web. The static connection name is `helpscout`. Start the `HelpScoutConversationSearch` Flow with a `SearchConversationsInput`, for example the checked-in [`input.example.json`](input.example.json). The Flow stores and returns one page of conversations. Its only wired branch is `searched`; an optional branch fails the Flow when selected.
|
|
4
|
+
|
|
5
|
+
The checked-in `integration/conversation_search.py` runs this same Flow against a real local Dex Worker and Client with generated provider mocks. Start `dexcli dev` on unused ports, set `DEX_FLOW_SERVICE_ADDRESS` to its gRPC address, then run `uv run pytest integration/conversation_search.py -q`.
|
|
6
|
+
|
|
7
|
+
Generate and validate the strict Flow Definition Graph 2.0 from this package directory with:
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
dexcli visualize ./examples/conversation_search/flow.py \
|
|
11
|
+
--python .venv/bin/python --schema-version 2.0 --lint app \
|
|
12
|
+
--json --out /tmp/helpscout-python-fdg
|
|
13
|
+
```
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Copyright (c) 2026 Super Durable
|
|
2
|
+
# SPDX-License-Identifier: MIT
|
|
3
|
+
"""Search one page of Help Scout conversations in a Dex Flow."""
|
|
4
|
+
|
|
5
|
+
import dex
|
|
6
|
+
from dex_connectors.sdk import QueryResult
|
|
7
|
+
|
|
8
|
+
from dex_connectors.helpscout import Connection, SearchConversationsInput, SearchConversationsOutput
|
|
9
|
+
from dex_connectors.helpscout.steps import new_search_conversations_step
|
|
10
|
+
|
|
11
|
+
CONNECTION_NAME = "helpscout"
|
|
12
|
+
FLOW_TYPE = "HelpScoutConversationSearch"
|
|
13
|
+
_RESULT = dex.Attribute("helpscout-conversation-search-result", SearchConversationsOutput)
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
# dex:group group-id:conversation-search group-label:"Conversation search"
|
|
17
|
+
# dex:explanation text:"Pass the requested conversation filters into the Help Scout search operation."
|
|
18
|
+
class _StartSearch(dex.Step[SearchConversationsInput]):
|
|
19
|
+
def get_step_type(self) -> str:
|
|
20
|
+
"""Return the stable starter Step type."""
|
|
21
|
+
return "StartConversationSearch"
|
|
22
|
+
|
|
23
|
+
def execute(self, context: dex.Context, input: SearchConversationsInput) -> dex.StepDecision:
|
|
24
|
+
"""Route the caller's filters into the provider Query Step."""
|
|
25
|
+
return dex.go_to(dex.StepRef("SearchHelpScoutConversations"), input)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
# dex:group group-id:conversation-search group-label:"Conversation search"
|
|
29
|
+
# dex:explanation text:"Store the returned conversation page and complete the Flow."
|
|
30
|
+
class _SearchComplete(dex.Step[QueryResult[SearchConversationsOutput]]):
|
|
31
|
+
def get_step_type(self) -> str:
|
|
32
|
+
"""Return the stable completion Step type."""
|
|
33
|
+
return "CompleteConversationSearch"
|
|
34
|
+
|
|
35
|
+
def execute(
|
|
36
|
+
self, context: dex.Context, input: QueryResult[SearchConversationsOutput]
|
|
37
|
+
) -> dex.StepDecision:
|
|
38
|
+
"""Persist the provider page before successful completion."""
|
|
39
|
+
_RESULT.set(context, input.value)
|
|
40
|
+
return dex.graceful_complete(input.value)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class ConversationSearchFlow(dex.Flow[SearchConversationsInput]):
|
|
44
|
+
"""Run a one-page Help Scout conversation search through one static connection."""
|
|
45
|
+
|
|
46
|
+
def __init__(self, connection: Connection) -> None:
|
|
47
|
+
if connection.reference.name != CONNECTION_NAME:
|
|
48
|
+
raise ValueError("conversation search requires the static helpscout connection")
|
|
49
|
+
self._start = _StartSearch()
|
|
50
|
+
self._complete = _SearchComplete()
|
|
51
|
+
self._search = new_search_conversations_step(
|
|
52
|
+
step_type="SearchHelpScoutConversations",
|
|
53
|
+
step_input_type=SearchConversationsInput,
|
|
54
|
+
annotations={
|
|
55
|
+
"groupId": "helpscout",
|
|
56
|
+
"groupLabel": "Help Scout",
|
|
57
|
+
"explanation": "Search one Help Scout Inbox conversation page with the supplied filters.",
|
|
58
|
+
},
|
|
59
|
+
connection=connection,
|
|
60
|
+
connection_name=CONNECTION_NAME,
|
|
61
|
+
map_to_operation_input=lambda request: request,
|
|
62
|
+
searched=self._complete,
|
|
63
|
+
)
|
|
64
|
+
|
|
65
|
+
def get_flow_type(self) -> str:
|
|
66
|
+
"""Return the stable Dex Flow identity."""
|
|
67
|
+
return "HelpScoutConversationSearch"
|
|
68
|
+
|
|
69
|
+
def get_steps(self) -> dex.StepList[SearchConversationsInput]:
|
|
70
|
+
"""Register the start, provider, and completion Steps."""
|
|
71
|
+
return dex.StepList.start_step(self._start).other_steps(self._search, self._complete)
|
|
72
|
+
|
|
73
|
+
def get_persistence_schema(self) -> dex.PersistenceSchema:
|
|
74
|
+
"""Register the stored page with Flow persistence."""
|
|
75
|
+
return dex.PersistenceSchema.of(_RESULT)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"mailboxId":123,"status":"active","page":1}
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Copyright (c) 2026 Super Durable
|
|
2
|
+
# SPDX-License-Identifier: MIT
|
|
3
|
+
"""Worker entrypoint for the Help Scout conversation search example."""
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import os
|
|
7
|
+
import tempfile
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
|
|
10
|
+
import dex
|
|
11
|
+
from dex_connectors.sdk.projectconfig import load_from_environment
|
|
12
|
+
|
|
13
|
+
from dex_connectors.helpscout import new_project_connection
|
|
14
|
+
|
|
15
|
+
from .flow import CONNECTION_NAME, ConversationSearchFlow
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
async def run_worker() -> None:
|
|
19
|
+
"""Load the Dex Web connection and serve the search Flow."""
|
|
20
|
+
project = await load_from_environment()
|
|
21
|
+
connection = None
|
|
22
|
+
cache = None
|
|
23
|
+
try:
|
|
24
|
+
connection = new_project_connection(project, CONNECTION_NAME)
|
|
25
|
+
registry = dex.Registry([ConversationSearchFlow(connection)], allow_async_handlers=True)
|
|
26
|
+
cache_dir = os.environ.get(
|
|
27
|
+
"DEX_BLOB_CACHE_DIR", str(Path(tempfile.gettempdir()) / "dex-helpscout-search-blobs")
|
|
28
|
+
)
|
|
29
|
+
cache = dex.open_blob_cache(dex.BlobCacheConfig(cache_dir, 1 << 30))
|
|
30
|
+
worker = dex.AsyncWorker(
|
|
31
|
+
registry,
|
|
32
|
+
cache,
|
|
33
|
+
dex.WorkerOptions(server_address=os.environ.get("DEX_FLOW_SERVICE_ADDRESS", "localhost:8801")),
|
|
34
|
+
)
|
|
35
|
+
async with worker:
|
|
36
|
+
await worker.start()
|
|
37
|
+
finally:
|
|
38
|
+
if connection is not None:
|
|
39
|
+
await connection.aclose()
|
|
40
|
+
if cache is not None:
|
|
41
|
+
cache.close()
|
|
42
|
+
await project.close()
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def main() -> None:
|
|
46
|
+
"""Run until the Dex Worker stops."""
|
|
47
|
+
asyncio.run(run_worker())
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
if __name__ == "__main__":
|
|
51
|
+
main()
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Copyright (c) 2026 Super Durable
|
|
2
|
+
# SPDX-License-Identifier: MIT
|
|
3
|
+
"""Run the Help Scout example through a real local Dex Worker and Client."""
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import os
|
|
7
|
+
from datetime import timedelta
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from uuid import uuid4
|
|
10
|
+
|
|
11
|
+
import dex
|
|
12
|
+
import pytest
|
|
13
|
+
from dex_connectors.sdk import Failure, FailureKind
|
|
14
|
+
|
|
15
|
+
from dex_connectors.helpscout import SearchConversationsInput, SearchConversationsOutput
|
|
16
|
+
from dex_connectors.helpscout.helpscoutmock import (
|
|
17
|
+
Mock,
|
|
18
|
+
search_conversations_provider_rejected_failure,
|
|
19
|
+
search_conversations_retry,
|
|
20
|
+
search_conversations_searched_default_answer,
|
|
21
|
+
)
|
|
22
|
+
from examples.conversation_search.flow import ConversationSearchFlow
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
@pytest.mark.asyncio
|
|
26
|
+
async def test_conversation_search_real_dex_worker(tmp_path: Path) -> None:
|
|
27
|
+
"""Exercise success, retry, and an unwired optional branch in Dex."""
|
|
28
|
+
address = os.environ["DEX_FLOW_SERVICE_ADDRESS"]
|
|
29
|
+
mock = Mock()
|
|
30
|
+
flow = ConversationSearchFlow(mock.connection())
|
|
31
|
+
registry = dex.Registry([flow], allow_async_handlers=True)
|
|
32
|
+
cache = dex.open_blob_cache(dex.BlobCacheConfig(str(tmp_path / "blobs"), 64 * 1024 * 1024))
|
|
33
|
+
worker = dex.AsyncWorker(registry, cache, dex.WorkerOptions(server_address=address))
|
|
34
|
+
worker_task = asyncio.create_task(worker.start())
|
|
35
|
+
try:
|
|
36
|
+
await worker.wait_pull_registered(timeout=30)
|
|
37
|
+
async with dex.AsyncClient(registry, cache, dex.ClientOptions(server_address=address)) as client:
|
|
38
|
+
success_id = f"helpscout-search-success-{uuid4()}"
|
|
39
|
+
await client.start_flow(flow, success_id, SearchConversationsInput(mailbox_id=123))
|
|
40
|
+
success = await client.wait_for_flow(success_id, timedelta(seconds=30))
|
|
41
|
+
assert success.status == dex.FlowStatus.COMPLETED
|
|
42
|
+
pages = [
|
|
43
|
+
item.decode(SearchConversationsOutput)
|
|
44
|
+
for item in success.completions
|
|
45
|
+
if item.step_type == "CompleteConversationSearch"
|
|
46
|
+
]
|
|
47
|
+
assert len(pages) == 1 and pages[0].conversations
|
|
48
|
+
|
|
49
|
+
retry_id = f"helpscout-search-retry-{uuid4()}"
|
|
50
|
+
mock.search_conversations_script.for_flow(retry_id).respond(
|
|
51
|
+
search_conversations_retry(
|
|
52
|
+
Failure(FailureKind.AVAILABILITY, "helpscout", "searchConversations", "temporary outage")
|
|
53
|
+
),
|
|
54
|
+
search_conversations_searched_default_answer(),
|
|
55
|
+
)
|
|
56
|
+
await client.start_flow(flow, retry_id, SearchConversationsInput(mailbox_id=123))
|
|
57
|
+
retried = await client.wait_for_flow(retry_id, timedelta(seconds=30))
|
|
58
|
+
assert retried.status == dex.FlowStatus.COMPLETED
|
|
59
|
+
calls = [call for call in mock.search_conversations_script.calls() if call.flow_id == retry_id]
|
|
60
|
+
assert len(calls) == 2 and calls[0].retry
|
|
61
|
+
assert calls[0].call_id == calls[1].call_id
|
|
62
|
+
|
|
63
|
+
rejected_id = f"helpscout-search-rejected-{uuid4()}"
|
|
64
|
+
mock.search_conversations_script.for_flow(rejected_id).respond(
|
|
65
|
+
search_conversations_provider_rejected_failure()
|
|
66
|
+
)
|
|
67
|
+
await client.start_flow(flow, rejected_id, SearchConversationsInput(mailbox_id=123))
|
|
68
|
+
rejected = await client.wait_for_flow(rejected_id, timedelta(seconds=30))
|
|
69
|
+
assert rejected.status == dex.FlowStatus.FAILED
|
|
70
|
+
assert rejected.error_message is not None and "providerRejected" in rejected.error_message
|
|
71
|
+
assert (
|
|
72
|
+
len(
|
|
73
|
+
[call for call in mock.search_conversations_script.calls() if call.flow_id == rejected_id]
|
|
74
|
+
)
|
|
75
|
+
== 1
|
|
76
|
+
)
|
|
77
|
+
mock.search_conversations_script.assert_no_failures()
|
|
78
|
+
finally:
|
|
79
|
+
await worker.stop()
|
|
80
|
+
await worker_task
|
|
81
|
+
cache.close()
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "dex-connector-helpscout"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Dex-native Help Scout Inbox connector"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
dependencies = ["dex-connectors-sdk==0.7.0", "dex-python-sdk>=1.28.0", "httpx>=0.27"]
|
|
14
|
+
|
|
15
|
+
[project.urls]
|
|
16
|
+
Source = "https://github.com/superdurable/dex-connectors-library/tree/main/connectors/helpscout/python"
|
|
17
|
+
|
|
18
|
+
[dependency-groups]
|
|
19
|
+
dev = ["pytest>=8", "pytest-asyncio>=0.24", "mypy>=1.13", "ruff>=0.7", "PyYAML>=6", "types-PyYAML>=6"]
|
|
20
|
+
|
|
21
|
+
[tool.hatch.build.targets.wheel]
|
|
22
|
+
packages = ["src/dex_connectors"]
|
|
23
|
+
|
|
24
|
+
[tool.pytest.ini_options]
|
|
25
|
+
testpaths = ["tests"]
|
|
26
|
+
pythonpath = [".", "src"]
|
|
27
|
+
asyncio_mode = "auto"
|
|
28
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
29
|
+
|
|
30
|
+
[tool.mypy]
|
|
31
|
+
python_version = "3.11"
|
|
32
|
+
strict = true
|
|
33
|
+
mypy_path = "src"
|
|
34
|
+
explicit_package_bases = true
|
|
35
|
+
|
|
36
|
+
[tool.ruff]
|
|
37
|
+
target-version = "py311"
|
|
38
|
+
line-length = 110
|
|
39
|
+
|
|
40
|
+
[tool.ruff.lint]
|
|
41
|
+
select = ["E", "F", "I", "UP", "B"]
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Copyright (c) 2026 Super Durable
|
|
2
|
+
# SPDX-License-Identifier: MIT
|
|
3
|
+
"""Dex-native Help Scout Inbox operations."""
|
|
4
|
+
|
|
5
|
+
from .client import Client, Config, Credentials
|
|
6
|
+
from .connection import Connection, new_connection, new_connection_with_operations, new_project_connection
|
|
7
|
+
from .models import * # noqa: F403
|
|
8
|
+
from .steps import * # noqa: F403
|
|
9
|
+
|
|
10
|
+
__all__ = [
|
|
11
|
+
"Client",
|
|
12
|
+
"Config",
|
|
13
|
+
"Credentials",
|
|
14
|
+
"Connection",
|
|
15
|
+
"new_connection",
|
|
16
|
+
"new_connection_with_operations",
|
|
17
|
+
"new_project_connection",
|
|
18
|
+
]
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Copyright (c) 2026 Super Durable
|
|
2
|
+
# SPDX-License-Identifier: MIT
|
|
3
|
+
# ruff: noqa
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
|
|
7
|
+
from dex_connectors.sdk import SecretString
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
@dataclass(frozen=True, slots=True)
|
|
11
|
+
class Config:
|
|
12
|
+
|
|
13
|
+
max_response_bytes: int = 4194304
|
|
14
|
+
webhook_max_body_bytes: int = 4194304
|
|
15
|
+
|
|
16
|
+
setattr(Config, '__module__', 'dex_connectors.helpscout.client')
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
@dataclass(frozen=True, slots=True)
|
|
20
|
+
class Credentials:
|
|
21
|
+
|
|
22
|
+
app_id: str
|
|
23
|
+
app_secret: SecretString
|
|
24
|
+
access_token: SecretString
|
|
25
|
+
webhook_secret: SecretString
|
|
26
|
+
|
|
27
|
+
setattr(Credentials, '__module__', 'dex_connectors.helpscout.client')
|