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.
@@ -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.
@@ -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