erghi-sdk 1.0.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.
- erghi_sdk-1.0.0/LICENSE +21 -0
- erghi_sdk-1.0.0/PKG-INFO +421 -0
- erghi_sdk-1.0.0/README.md +384 -0
- erghi_sdk-1.0.0/erghi/__init__.py +43 -0
- erghi_sdk-1.0.0/erghi/client.py +526 -0
- erghi_sdk-1.0.0/erghi/errors.py +73 -0
- erghi_sdk-1.0.0/erghi/hmac.py +76 -0
- erghi_sdk-1.0.0/erghi/types.py +140 -0
- erghi_sdk-1.0.0/erghi_sdk.egg-info/PKG-INFO +421 -0
- erghi_sdk-1.0.0/erghi_sdk.egg-info/SOURCES.txt +15 -0
- erghi_sdk-1.0.0/erghi_sdk.egg-info/dependency_links.txt +1 -0
- erghi_sdk-1.0.0/erghi_sdk.egg-info/requires.txt +13 -0
- erghi_sdk-1.0.0/erghi_sdk.egg-info/top_level.txt +1 -0
- erghi_sdk-1.0.0/pyproject.toml +71 -0
- erghi_sdk-1.0.0/setup.cfg +4 -0
- erghi_sdk-1.0.0/tests/test_client_realtime.py +210 -0
- erghi_sdk-1.0.0/tests/test_hmac.py +64 -0
erghi_sdk-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Erghi Platform
|
|
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.
|
erghi_sdk-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,421 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: erghi-sdk
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Official Python SDK for the Erghi customer-support platform
|
|
5
|
+
Author-email: Erghi Team <sdk@erghi.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://erghi.com
|
|
8
|
+
Project-URL: Documentation, https://erghi.com/docs/sdk/python
|
|
9
|
+
Project-URL: Repository, https://github.com/ErghiPlatform/erghi-sdks
|
|
10
|
+
Project-URL: Issues, https://github.com/ErghiPlatform/erghi-sdks/issues
|
|
11
|
+
Keywords: ai,chat,chatbot,sdk,websocket,real-time
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
21
|
+
Requires-Python: >=3.9
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
License-File: LICENSE
|
|
24
|
+
Requires-Dist: httpx>=0.27.0
|
|
25
|
+
Requires-Dist: websockets>=12.0
|
|
26
|
+
Requires-Dist: pydantic>=2.10.0
|
|
27
|
+
Requires-Dist: python-dateutil>=2.9.0
|
|
28
|
+
Requires-Dist: email-validator>=2.0.0
|
|
29
|
+
Provides-Extra: dev
|
|
30
|
+
Requires-Dist: pytest>=8.3.0; extra == "dev"
|
|
31
|
+
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
|
|
32
|
+
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
|
|
33
|
+
Requires-Dist: black>=24.10.0; extra == "dev"
|
|
34
|
+
Requires-Dist: ruff>=0.8.0; extra == "dev"
|
|
35
|
+
Requires-Dist: mypy>=1.13.0; extra == "dev"
|
|
36
|
+
Dynamic: license-file
|
|
37
|
+
|
|
38
|
+
# Erghi Python SDK
|
|
39
|
+
|
|
40
|
+
Official Python SDK for the [Erghi Platform](https://erghi.ai).
|
|
41
|
+
|
|
42
|
+
## Installation
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
pip install erghi-sdk
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Quick Start
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
import asyncio
|
|
52
|
+
from erghi import ErghiClient, RegisterRequest, LoginRequest
|
|
53
|
+
|
|
54
|
+
async def main():
|
|
55
|
+
# Initialize the client
|
|
56
|
+
async with ErghiClient(
|
|
57
|
+
api_url="https://api.erghi.ai",
|
|
58
|
+
api_key="your-api-key",
|
|
59
|
+
workspace_id="your-workspace-id",
|
|
60
|
+
) as client:
|
|
61
|
+
# Register a new user
|
|
62
|
+
auth_response = await client.auth.register(
|
|
63
|
+
RegisterRequest(
|
|
64
|
+
email="user@example.com",
|
|
65
|
+
password="SecurePassword123!",
|
|
66
|
+
first_name="John",
|
|
67
|
+
last_name="Doe",
|
|
68
|
+
)
|
|
69
|
+
)
|
|
70
|
+
|
|
71
|
+
# Login
|
|
72
|
+
login_response = await client.auth.login(
|
|
73
|
+
LoginRequest(
|
|
74
|
+
email="user@example.com",
|
|
75
|
+
password="SecurePassword123!",
|
|
76
|
+
)
|
|
77
|
+
)
|
|
78
|
+
|
|
79
|
+
# Get current user
|
|
80
|
+
user = await client.auth.me()
|
|
81
|
+
print(f"Current user: {user.email}")
|
|
82
|
+
|
|
83
|
+
# Create a conversation
|
|
84
|
+
conversation = await client.chat.create_conversation(
|
|
85
|
+
widget_id="widget-id",
|
|
86
|
+
metadata={"page": "https://example.com"},
|
|
87
|
+
)
|
|
88
|
+
|
|
89
|
+
# Send a message
|
|
90
|
+
message = await client.chat.send_message(
|
|
91
|
+
conversation_id=conversation.id,
|
|
92
|
+
content="Hello, I need help!",
|
|
93
|
+
)
|
|
94
|
+
|
|
95
|
+
# Connect to WebSocket for real-time updates
|
|
96
|
+
await client.connect()
|
|
97
|
+
|
|
98
|
+
# Register event handlers
|
|
99
|
+
client.on("message.received", lambda data: print(f"New message: {data}"))
|
|
100
|
+
client.on("user.typing", lambda data: print(f"User typing: {data}"))
|
|
101
|
+
|
|
102
|
+
# Keep connection alive
|
|
103
|
+
await asyncio.sleep(3600)
|
|
104
|
+
|
|
105
|
+
if __name__ == "__main__":
|
|
106
|
+
asyncio.run(main())
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Authentication
|
|
110
|
+
|
|
111
|
+
### Register
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
from erghi import RegisterRequest
|
|
115
|
+
|
|
116
|
+
auth_response = await client.auth.register(
|
|
117
|
+
RegisterRequest(
|
|
118
|
+
email="user@example.com",
|
|
119
|
+
password="SecurePassword123!",
|
|
120
|
+
first_name="John",
|
|
121
|
+
last_name="Doe",
|
|
122
|
+
)
|
|
123
|
+
)
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Login
|
|
127
|
+
|
|
128
|
+
```python
|
|
129
|
+
from erghi import LoginRequest
|
|
130
|
+
|
|
131
|
+
auth_response = await client.auth.login(
|
|
132
|
+
LoginRequest(
|
|
133
|
+
email="user@example.com",
|
|
134
|
+
password="SecurePassword123!",
|
|
135
|
+
)
|
|
136
|
+
)
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### Refresh Token
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
auth_response = await client.auth.refresh("refresh-token")
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Logout
|
|
146
|
+
|
|
147
|
+
```python
|
|
148
|
+
await client.auth.logout()
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Chat Operations
|
|
152
|
+
|
|
153
|
+
### Create Conversation
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
conversation = await client.chat.create_conversation(
|
|
157
|
+
widget_id="widget-id",
|
|
158
|
+
metadata={"custom_data": "value"},
|
|
159
|
+
)
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### Send Message
|
|
163
|
+
|
|
164
|
+
```python
|
|
165
|
+
message = await client.chat.send_message(
|
|
166
|
+
conversation_id="conversation-id",
|
|
167
|
+
content="Hello!",
|
|
168
|
+
)
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### Send Message with Attachments
|
|
172
|
+
|
|
173
|
+
```python
|
|
174
|
+
with open("document.pdf", "rb") as f:
|
|
175
|
+
message = await client.chat.send_message(
|
|
176
|
+
conversation_id="conversation-id",
|
|
177
|
+
content="Here is the file",
|
|
178
|
+
attachments=[f],
|
|
179
|
+
)
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Get Messages
|
|
183
|
+
|
|
184
|
+
```python
|
|
185
|
+
from erghi.types import PaginationParams
|
|
186
|
+
|
|
187
|
+
response = await client.chat.get_messages(
|
|
188
|
+
conversation_id="conversation-id",
|
|
189
|
+
params=PaginationParams(
|
|
190
|
+
page=1,
|
|
191
|
+
limit=50,
|
|
192
|
+
sort="createdAt",
|
|
193
|
+
order="desc",
|
|
194
|
+
),
|
|
195
|
+
)
|
|
196
|
+
|
|
197
|
+
print(f"Total messages: {response.total}")
|
|
198
|
+
for message in response.data:
|
|
199
|
+
print(f"{message.sender}: {message.content}")
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## WebSocket Real-time Events
|
|
203
|
+
|
|
204
|
+
```python
|
|
205
|
+
# Connect to WebSocket
|
|
206
|
+
await client.connect()
|
|
207
|
+
|
|
208
|
+
# Listen for new messages
|
|
209
|
+
def on_message(message):
|
|
210
|
+
print(f"New message: {message}")
|
|
211
|
+
|
|
212
|
+
client.on("message.received", on_message)
|
|
213
|
+
|
|
214
|
+
# Listen for typing indicators
|
|
215
|
+
client.on("user.typing", lambda data: print(f"User typing: {data}"))
|
|
216
|
+
|
|
217
|
+
# Listen for conversation assignment
|
|
218
|
+
client.on("conversation.assigned", lambda data: print(f"Assigned: {data}"))
|
|
219
|
+
|
|
220
|
+
# Send typing indicator
|
|
221
|
+
await client.chat.send_typing("conversation-id")
|
|
222
|
+
|
|
223
|
+
# Disconnect
|
|
224
|
+
await client.disconnect()
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
## Workspace Management
|
|
228
|
+
|
|
229
|
+
```python
|
|
230
|
+
# List workspaces
|
|
231
|
+
workspaces = await client.workspace.list()
|
|
232
|
+
|
|
233
|
+
# Create workspace
|
|
234
|
+
workspace = await client.workspace.create(
|
|
235
|
+
name="My Company",
|
|
236
|
+
slug="my-company",
|
|
237
|
+
)
|
|
238
|
+
|
|
239
|
+
# Switch workspace
|
|
240
|
+
client.workspace.switch_workspace("workspace-id")
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
## Identity Verification & Webhooks (Server-Side)
|
|
244
|
+
|
|
245
|
+
`generate_identity_hash` and `verify_webhook_signature` are stateless module-level functions —
|
|
246
|
+
they don't need an `ErghiClient` instance. Only call them from your backend; never ship your
|
|
247
|
+
widget secret key or webhook secret to the browser.
|
|
248
|
+
|
|
249
|
+
```python
|
|
250
|
+
from erghi import generate_identity_hash, verify_webhook_signature
|
|
251
|
+
|
|
252
|
+
# On your server, after the user logs in:
|
|
253
|
+
identity_hash = generate_identity_hash(
|
|
254
|
+
visitor_id=str(current_user.id),
|
|
255
|
+
secret_key=settings.ERGHI_WIDGET_SECRET,
|
|
256
|
+
)
|
|
257
|
+
# Send `identity_hash` and `current_user.id` to your frontend for use with the widget.
|
|
258
|
+
|
|
259
|
+
# In your webhook handler (use the raw body, not the parsed JSON):
|
|
260
|
+
def handle_webhook(request):
|
|
261
|
+
signature = request.headers.get("X-Erghi-Signature", "")
|
|
262
|
+
if not verify_webhook_signature(request.body.decode("utf-8"), signature, settings.ERGHI_WEBHOOK_SECRET):
|
|
263
|
+
return HttpResponseUnauthorized("Invalid signature")
|
|
264
|
+
|
|
265
|
+
event = json.loads(request.body)
|
|
266
|
+
# ... handle event
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
## Error Handling
|
|
270
|
+
|
|
271
|
+
```python
|
|
272
|
+
from erghi import (
|
|
273
|
+
AuthenticationError,
|
|
274
|
+
ValidationError,
|
|
275
|
+
RateLimitError,
|
|
276
|
+
NetworkError,
|
|
277
|
+
NotFoundError,
|
|
278
|
+
)
|
|
279
|
+
|
|
280
|
+
try:
|
|
281
|
+
await client.auth.login(
|
|
282
|
+
LoginRequest(email="invalid", password="wrong")
|
|
283
|
+
)
|
|
284
|
+
except AuthenticationError as e:
|
|
285
|
+
print(f"Login failed: {e.message}")
|
|
286
|
+
except ValidationError as e:
|
|
287
|
+
print(f"Validation errors: {e.details}")
|
|
288
|
+
except RateLimitError as e:
|
|
289
|
+
print(f"Rate limited. Retry after {e.retry_after}s")
|
|
290
|
+
except NetworkError as e:
|
|
291
|
+
print(f"Network error: {e.message}")
|
|
292
|
+
except NotFoundError:
|
|
293
|
+
print("Resource not found")
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
## Type Safety
|
|
297
|
+
|
|
298
|
+
The SDK is fully typed with Pydantic models:
|
|
299
|
+
|
|
300
|
+
```python
|
|
301
|
+
from erghi.types import User, Message, Conversation, AuthResponse
|
|
302
|
+
|
|
303
|
+
user: User = await client.auth.me()
|
|
304
|
+
messages: PaginatedResponse = await client.chat.get_messages("conv-id")
|
|
305
|
+
|
|
306
|
+
# Type checking with mypy
|
|
307
|
+
reveal_type(user) # Revealed type is "User"
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
## Configuration
|
|
311
|
+
|
|
312
|
+
```python
|
|
313
|
+
client = ErghiClient(
|
|
314
|
+
# API base URL (default: http://localhost:5000)
|
|
315
|
+
api_url="https://api.erghi.ai",
|
|
316
|
+
|
|
317
|
+
# WebSocket URL (default: ws://localhost:5002)
|
|
318
|
+
ws_url="wss://ws.erghi.ai",
|
|
319
|
+
|
|
320
|
+
# API Key for authentication
|
|
321
|
+
api_key="your-api-key",
|
|
322
|
+
|
|
323
|
+
# Access token (JWT)
|
|
324
|
+
access_token="your-access-token",
|
|
325
|
+
|
|
326
|
+
# Workspace ID
|
|
327
|
+
workspace_id="your-workspace-id",
|
|
328
|
+
|
|
329
|
+
# Request timeout in seconds (default: 30.0)
|
|
330
|
+
timeout=30.0,
|
|
331
|
+
|
|
332
|
+
# Enable debug logging (default: False)
|
|
333
|
+
debug=True,
|
|
334
|
+
)
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
## Context Manager
|
|
338
|
+
|
|
339
|
+
Use the client as an async context manager for automatic cleanup:
|
|
340
|
+
|
|
341
|
+
```python
|
|
342
|
+
async with ErghiClient(api_url="https://api.erghi.ai") as client:
|
|
343
|
+
user = await client.auth.me()
|
|
344
|
+
# Connections automatically closed on exit
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
## Advanced Usage
|
|
348
|
+
|
|
349
|
+
### Custom Event Handlers
|
|
350
|
+
|
|
351
|
+
```python
|
|
352
|
+
class MyEventHandler:
|
|
353
|
+
async def handle_message(self, data):
|
|
354
|
+
print(f"Message: {data}")
|
|
355
|
+
# Process message asynchronously
|
|
356
|
+
await self.process_message(data)
|
|
357
|
+
|
|
358
|
+
async def process_message(self, data):
|
|
359
|
+
# Custom processing logic
|
|
360
|
+
pass
|
|
361
|
+
|
|
362
|
+
handler = MyEventHandler()
|
|
363
|
+
client.on("message.received", handler.handle_message)
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
### Concurrent Operations
|
|
367
|
+
|
|
368
|
+
```python
|
|
369
|
+
import asyncio
|
|
370
|
+
|
|
371
|
+
# Run multiple operations concurrently
|
|
372
|
+
results = await asyncio.gather(
|
|
373
|
+
client.chat.get_conversation("conv-1"),
|
|
374
|
+
client.chat.get_conversation("conv-2"),
|
|
375
|
+
client.chat.get_messages("conv-1"),
|
|
376
|
+
)
|
|
377
|
+
|
|
378
|
+
conversation1, conversation2, messages = results
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
## Development
|
|
382
|
+
|
|
383
|
+
### Install development dependencies
|
|
384
|
+
|
|
385
|
+
```bash
|
|
386
|
+
pip install -e ".[dev]"
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
### Run tests
|
|
390
|
+
|
|
391
|
+
```bash
|
|
392
|
+
pytest
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
### Run tests with coverage
|
|
396
|
+
|
|
397
|
+
```bash
|
|
398
|
+
pytest --cov=erghi --cov-report=html
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
### Format code
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
black erghi tests
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
### Lint code
|
|
408
|
+
|
|
409
|
+
```bash
|
|
410
|
+
ruff check erghi tests
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
### Type checking
|
|
414
|
+
|
|
415
|
+
```bash
|
|
416
|
+
mypy erghi
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
## License
|
|
420
|
+
|
|
421
|
+
MIT
|