global-support-standard 0.2.0__py3-none-any.whl
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.
- global_support_standard-0.2.0.dist-info/METADATA +261 -0
- global_support_standard-0.2.0.dist-info/RECORD +28 -0
- global_support_standard-0.2.0.dist-info/WHEEL +5 -0
- global_support_standard-0.2.0.dist-info/entry_points.txt +4 -0
- global_support_standard-0.2.0.dist-info/licenses/LICENSE +9 -0
- global_support_standard-0.2.0.dist-info/top_level.txt +4 -0
- gss_cli/__init__.py +1 -0
- gss_cli/main.py +266 -0
- gss_core/__init__.py +3 -0
- gss_core/envelope.py +18 -0
- gss_core/errors.py +22 -0
- gss_core/models.py +111 -0
- gss_core/security.py +24 -0
- gss_provider/__init__.py +3 -0
- gss_provider/app.py +452 -0
- gss_provider/audit.py +41 -0
- gss_provider/auth.py +60 -0
- gss_provider/contracts.py +61 -0
- gss_provider/mock_adapter.py +77 -0
- gss_provider/mock_data.py +104 -0
- gss_provider/protocol_engine.py +66 -0
- gss_provider/protocols/delivery-not-received.yaml +36 -0
- gss_provider/settings.py +44 -0
- gss_webshop_shopify/__init__.py +3 -0
- gss_webshop_shopify/app.py +500 -0
- gss_webshop_shopify/runtime.py +76 -0
- gss_webshop_shopify/settings.py +37 -0
- gss_webshop_shopify/shopify_client.py +98 -0
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: global-support-standard
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: GSS Python MVP: provider API + CLI consumer
|
|
5
|
+
Author: Michel Norbruis
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/MichelN89/global-support-standard
|
|
8
|
+
Project-URL: Repository, https://github.com/MichelN89/global-support-standard
|
|
9
|
+
Project-URL: Issues, https://github.com/MichelN89/global-support-standard/issues
|
|
10
|
+
Project-URL: Documentation, https://github.com/MichelN89/global-support-standard/tree/main/docs
|
|
11
|
+
Project-URL: Changelog, https://github.com/MichelN89/global-support-standard/blob/main/CHANGELOG.md
|
|
12
|
+
Keywords: gss,customer-support,ecommerce,api,cli,fastapi
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Framework :: FastAPI
|
|
19
|
+
Requires-Python: >=3.11
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: fastapi>=0.115.0
|
|
23
|
+
Requires-Dist: uvicorn>=0.30.0
|
|
24
|
+
Requires-Dist: typer>=0.12.0
|
|
25
|
+
Requires-Dist: httpx>=0.27.0
|
|
26
|
+
Requires-Dist: pydantic>=2.8.0
|
|
27
|
+
Requires-Dist: PyYAML>=6.0.1
|
|
28
|
+
Provides-Extra: dev
|
|
29
|
+
Requires-Dist: pytest>=8.2.0; extra == "dev"
|
|
30
|
+
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
|
|
31
|
+
Requires-Dist: build>=1.2.0; extra == "dev"
|
|
32
|
+
Requires-Dist: twine>=5.1.0; extra == "dev"
|
|
33
|
+
Requires-Dist: ruff>=0.6.0; extra == "dev"
|
|
34
|
+
Dynamic: license-file
|
|
35
|
+
|
|
36
|
+
# Global Support Standard (GSS)
|
|
37
|
+
|
|
38
|
+
Open protocol for machine-readable e-commerce support.
|
|
39
|
+
|
|
40
|
+
[](https://github.com/MichelN89/global-support-standard/actions/workflows/ci.yml)
|
|
41
|
+
[](LICENSE)
|
|
42
|
+
[](pyproject.toml)
|
|
43
|
+
|
|
44
|
+
GSS lets any app, AI agent, or device resolve customer support requests directly with a shop using a consistent command model:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
gss <shop> <domain> <action> [--flags]
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
This repository includes a Python MVP implementation of the protocol and supporting project docs.
|
|
51
|
+
|
|
52
|
+
## Why GSS
|
|
53
|
+
|
|
54
|
+
Most support requests are policy execution, not free-form conversation:
|
|
55
|
+
|
|
56
|
+
- "Where is my package?"
|
|
57
|
+
- "Can I return this item?"
|
|
58
|
+
- "Why is my refund delayed?"
|
|
59
|
+
- "Can you show my account audit trail?"
|
|
60
|
+
|
|
61
|
+
Today these flows are reimplemented per shop and routed through human agents. GSS standardizes these operations so support can be:
|
|
62
|
+
|
|
63
|
+
- Faster (seconds, not days)
|
|
64
|
+
- Consistent across shops
|
|
65
|
+
- Safer for automation (action levels, confirmation tokens, auditability)
|
|
66
|
+
- Consumer-agnostic (AI, mobile app, browser extension, device)
|
|
67
|
+
|
|
68
|
+
## Repository At A Glance
|
|
69
|
+
|
|
70
|
+
| Area | Purpose |
|
|
71
|
+
|---|---|
|
|
72
|
+
| `src/gss_provider` | FastAPI provider server (shop-facing implementation) |
|
|
73
|
+
| `src/gss_cli` | Typer CLI consumer (`gss` command) |
|
|
74
|
+
| `src/gss_core` | Shared models, envelope helpers, and error contracts |
|
|
75
|
+
| `protocols/` | Protocol format docs and runnable YAML examples |
|
|
76
|
+
| `providers/mock_shop` | Example consumer-policy configuration |
|
|
77
|
+
| `sdk/typescript` | TypeScript SDK scaffold (non-blocking roadmap) |
|
|
78
|
+
| `spec/` | Protocol/spec narrative and architecture references |
|
|
79
|
+
| `docs/` | Getting-started docs for shops and consumers |
|
|
80
|
+
| `tests/` | API and CLI integration tests |
|
|
81
|
+
|
|
82
|
+
## MVP Scope (Implemented)
|
|
83
|
+
|
|
84
|
+
This codebase currently ships an end-to-end MVP:
|
|
85
|
+
|
|
86
|
+
- Provider API with standardized response envelope
|
|
87
|
+
- CLI with `gss <shop> <domain> <action>` routing
|
|
88
|
+
- Mock shop adapter/data layer
|
|
89
|
+
- Protocol engine (YAML rules + context enrichment)
|
|
90
|
+
- Security baseline:
|
|
91
|
+
- Customer auth token flow
|
|
92
|
+
- Required `GSS-Consumer-*` headers
|
|
93
|
+
- Two-step request execution (`returns initiate` -> `returns confirm`)
|
|
94
|
+
- Append-only audit log records
|
|
95
|
+
- Stateless core boundary:
|
|
96
|
+
- Framework defines contracts and orchestration
|
|
97
|
+
- Shops own persistence/secret storage in adapter implementations
|
|
98
|
+
|
|
99
|
+
## Architecture
|
|
100
|
+
|
|
101
|
+
```mermaid
|
|
102
|
+
flowchart LR
|
|
103
|
+
consumerClient[Client app/AI/device] -->|gss commands| cli[gss CLI]
|
|
104
|
+
cli -->|HTTP + GSS headers| provider[gss_provider FastAPI]
|
|
105
|
+
provider --> describe[DescribeService]
|
|
106
|
+
provider --> domains[Domain Services]
|
|
107
|
+
provider --> protocols[Protocol Engine]
|
|
108
|
+
provider --> auth[Auth Context]
|
|
109
|
+
provider --> audit[Audit Logger]
|
|
110
|
+
domains --> adapter[Mock Shop Data]
|
|
111
|
+
protocols --> yaml[Protocol YAML files]
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Quickstart
|
|
115
|
+
|
|
116
|
+
### 1) Install
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
python -m venv .venv
|
|
120
|
+
source .venv/bin/activate
|
|
121
|
+
pip install -e ".[dev]"
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### 2) Start provider
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
gss-provider
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Default endpoint: `http://127.0.0.1:8000/v1`
|
|
131
|
+
|
|
132
|
+
### 3) Run consumer flow
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
gss mockshop.local describe
|
|
136
|
+
gss mockshop.local auth login --method api_key --customer-id CUST-001
|
|
137
|
+
gss mockshop.local orders list
|
|
138
|
+
gss mockshop.local orders get --id ORD-1001
|
|
139
|
+
gss mockshop.local shipping track --order-id ORD-1001
|
|
140
|
+
gss mockshop.local protocols get --trigger delivery-not-received --context '{"order_id":"ORD-1002","days_since_expected":1}'
|
|
141
|
+
gss mockshop.local returns initiate --order-id ORD-1001 --item-id ITEM-1 --reason defective
|
|
142
|
+
gss mockshop.local returns confirm --token <confirmation_token>
|
|
143
|
+
gss mockshop.local account audit-log
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Optional token behavior:
|
|
147
|
+
- default: CLI stores token locally in `~/.gss/tokens.json`
|
|
148
|
+
- disable local storage: `GSS_STORE_TOKENS=0`
|
|
149
|
+
- provide token explicitly: `GSS_CUSTOMER_TOKEN=<token>`
|
|
150
|
+
|
|
151
|
+
### Shopify webshop project (inside this repo)
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
gss-shopify-provider
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
See `webshop/shopify-test-store/README.md` for setup against your test store.
|
|
158
|
+
The Shopify demo includes an agent-first auth flow (`auth verify-customer` -> `auth issue-token`) in addition to legacy dev login.
|
|
159
|
+
|
|
160
|
+
## HTTP Endpoints (MVP)
|
|
161
|
+
|
|
162
|
+
### Discovery
|
|
163
|
+
- `GET /v1/describe`
|
|
164
|
+
- `GET /v1/{domain}/describe`
|
|
165
|
+
|
|
166
|
+
### Auth
|
|
167
|
+
- `POST /v1/auth/login`
|
|
168
|
+
|
|
169
|
+
### Domains
|
|
170
|
+
- `GET /v1/orders`
|
|
171
|
+
- `GET /v1/orders/{order_id}`
|
|
172
|
+
- `GET /v1/shipping/track/{order_id}`
|
|
173
|
+
- `POST /v1/returns/check-eligibility`
|
|
174
|
+
- `POST /v1/returns/initiate`
|
|
175
|
+
- `POST /v1/returns/confirm`
|
|
176
|
+
- `POST /v1/protocols/get`
|
|
177
|
+
- `GET /v1/account/audit-log`
|
|
178
|
+
|
|
179
|
+
## Security Model Highlights
|
|
180
|
+
|
|
181
|
+
- Every protected request requires:
|
|
182
|
+
- `Authorization: Bearer <token>`
|
|
183
|
+
- `GSS-Consumer-Id`
|
|
184
|
+
- `GSS-Consumer-Type`
|
|
185
|
+
- `GSS-Version`
|
|
186
|
+
- `request` actions are two-step by design (issue confirmation token, then confirm)
|
|
187
|
+
- Authorization is customer-scoped and domain actions enforce ownership checks
|
|
188
|
+
- Request/action events are recorded to the audit log
|
|
189
|
+
- Trust signaling:
|
|
190
|
+
- `describe` includes compliance metadata (`level`, `certified`, `test_suite_version`)
|
|
191
|
+
- CLI warns when a shop is uncertified or missing compliance metadata
|
|
192
|
+
|
|
193
|
+
## Production Minimum Config
|
|
194
|
+
|
|
195
|
+
For production deployments, minimum baseline should include:
|
|
196
|
+
|
|
197
|
+
- Auth + headers on protected calls:
|
|
198
|
+
- `Authorization: Bearer <token>`
|
|
199
|
+
- `GSS-Consumer-Id`
|
|
200
|
+
- `GSS-Consumer-Type`
|
|
201
|
+
- `GSS-Version`
|
|
202
|
+
- Token policy:
|
|
203
|
+
- short-lived access tokens (recommended 5-60 minutes)
|
|
204
|
+
- least-privilege scopes per domain/action level
|
|
205
|
+
- optional binding to consumer identity (`GSS-Consumer-Id`)
|
|
206
|
+
- Data guardrails:
|
|
207
|
+
- validate identifiers server-side
|
|
208
|
+
- enforce customer ownership checks before returning payloads
|
|
209
|
+
- fail closed (`VALIDATION_ERROR`/`FORBIDDEN`)
|
|
210
|
+
- Action controls:
|
|
211
|
+
- `request` actions with two-step confirmation
|
|
212
|
+
- `critical` actions with out-of-band verification
|
|
213
|
+
- Governance and CI:
|
|
214
|
+
- branch protection on `main`
|
|
215
|
+
- required checks: lint, tests matrix, coverage, package-check, dependency-audit
|
|
216
|
+
- CODEOWNERS and PR template enabled
|
|
217
|
+
|
|
218
|
+
## Trust Boundary
|
|
219
|
+
|
|
220
|
+
GSS defines protocol contracts and package logic. Shop implementations own operational security and persistence (token systems, session stores, audit infrastructure).
|
|
221
|
+
See `docs/compliance-and-trust.md` for full guidance.
|
|
222
|
+
|
|
223
|
+
## Testing
|
|
224
|
+
|
|
225
|
+
```bash
|
|
226
|
+
pytest
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Current test coverage includes:
|
|
230
|
+
|
|
231
|
+
- happy-path API flows
|
|
232
|
+
- forbidden cross-customer order access
|
|
233
|
+
- missing header rejection
|
|
234
|
+
- protocol enrichment behavior
|
|
235
|
+
- CLI integration for login, listing orders, and two-step returns
|
|
236
|
+
|
|
237
|
+
## Documentation
|
|
238
|
+
|
|
239
|
+
- Spec overview: `spec/overview.md`
|
|
240
|
+
- Architecture deep dive: `docs/architecture.md`
|
|
241
|
+
- API request examples: `docs/api-examples.md`
|
|
242
|
+
- Compliance/trust boundary: `docs/compliance-and-trust.md`
|
|
243
|
+
- Authorization model: `docs/authorization-model.md`
|
|
244
|
+
- Agent delegation model: `docs/agent-delegation-model.md`
|
|
245
|
+
- Multi-language roadmap: `docs/multi-language-roadmap.md`
|
|
246
|
+
- Repository governance: `docs/repository-governance.md`
|
|
247
|
+
- Registry security spec: `docs/registry-security.md`
|
|
248
|
+
- Registry conformance checklist: `docs/registry-conformance-checklist.md`
|
|
249
|
+
- Conformance schema: `schemas/conformance/agent-delegation-checklist.json`
|
|
250
|
+
- Shopify webshop project: `webshop/shopify-test-store/README.md`
|
|
251
|
+
- Shop onboarding: `docs/getting-started-shops.md`
|
|
252
|
+
- Consumer onboarding: `docs/getting-started-consumers.md`
|
|
253
|
+
- Protocol format: `protocols/FORMAT.md`
|
|
254
|
+
|
|
255
|
+
## Contributing
|
|
256
|
+
|
|
257
|
+
See `CONTRIBUTING.md` for contribution expectations.
|
|
258
|
+
|
|
259
|
+
## License
|
|
260
|
+
|
|
261
|
+
This project is licensed under the terms in `LICENSE`.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
global_support_standard-0.2.0.dist-info/licenses/LICENSE,sha256=WASbL-8kNr3N-fkwMkZ91la7PYlX955SpJJG4W9KCsc,834
|
|
2
|
+
gss_cli/__init__.py,sha256=da1PTClDMl-IBkrSvq6JC1lnS-K_BASzCvxVhNxN5Ls,13
|
|
3
|
+
gss_cli/main.py,sha256=bTQYCs9NR18E1m0fn3o0CTe72aOM-SjHP5Az48ovPpA,8768
|
|
4
|
+
gss_core/__init__.py,sha256=VPaVhIK0UlRsU6cFivTPtOT4A5eygeghTOE7JGGrdZs,99
|
|
5
|
+
gss_core/envelope.py,sha256=C2bfLoi2W2D0wiyc3GNxIa2CabmkTzxr4xb-lJYU2ao,593
|
|
6
|
+
gss_core/errors.py,sha256=ZOtNiXnajbfQlz3sZOSzc4UgB1Sl_NRUOk-U4-GMnTQ,460
|
|
7
|
+
gss_core/models.py,sha256=d13SZVqfqF9Una3Elavy3bjb0GiGqNQtoiO476mr1Xc,2351
|
|
8
|
+
gss_core/security.py,sha256=bVHliL-aFvmhqkLKG2sOemiG3Fi5ac2lV0oaWh7rjtE,720
|
|
9
|
+
gss_provider/__init__.py,sha256=jArxVms_ZS6eug_h3jSt4pbNpU0XFAAkZ_qbrA9Xrk8,40
|
|
10
|
+
gss_provider/app.py,sha256=TfqOIh9thpN9BPwywy95MthIkE1vYlcMKE_MCstz74Q,19097
|
|
11
|
+
gss_provider/audit.py,sha256=MPvwfV3jKabxNT9pR5ysXx2mktF3zxQZC3XbFbPMqcQ,1144
|
|
12
|
+
gss_provider/auth.py,sha256=nO2RJd73VZL0DrXvjH-jk3eP1aQ4D-CSZcJHBO3h8m4,1904
|
|
13
|
+
gss_provider/contracts.py,sha256=nMbTkZ-jUQ-vkFKfNgEZWsUPSvElsAQ43DSDAjgSujc,1407
|
|
14
|
+
gss_provider/mock_adapter.py,sha256=UdTCR1FqyF2lhIXVhn6OmRXwK8ZJ-FEeXsKudIzC5eA,2706
|
|
15
|
+
gss_provider/mock_data.py,sha256=9I9rCpODu8xawzvUYpmR8XZNT9oufUzRQSaGU8B-vBQ,3552
|
|
16
|
+
gss_provider/protocol_engine.py,sha256=pPaTY6aYjbUMgeL_JCCLAaW3PXx1SdT0Rnrr96y0jJ8,2799
|
|
17
|
+
gss_provider/settings.py,sha256=1tiH7gts4uOptiZCuBm9bQlZ0Hz5ef8kvtT7mKyEJzc,1632
|
|
18
|
+
gss_provider/protocols/delivery-not-received.yaml,sha256=pSSmOrvlWqOat-5hrrbAt5Bj669cWkaS7iczVzfUkYE,1089
|
|
19
|
+
gss_webshop_shopify/__init__.py,sha256=jArxVms_ZS6eug_h3jSt4pbNpU0XFAAkZ_qbrA9Xrk8,40
|
|
20
|
+
gss_webshop_shopify/app.py,sha256=A6X28XB58vZ8RGSxy-Tvz8Sr3k2TSVAAGW_M9WlgTok,20638
|
|
21
|
+
gss_webshop_shopify/runtime.py,sha256=jPXvv6e2npwCSrfbCrzAsvA_1ogvIc9NLBbB_ys03tk,2749
|
|
22
|
+
gss_webshop_shopify/settings.py,sha256=LE0plWNaoVUd8NUObymJJ2p43tJAODiJluzqBA-hBHY,1313
|
|
23
|
+
gss_webshop_shopify/shopify_client.py,sha256=h9DQDhYnk8Bn0q-FECdQJ2zqjlSMR50avMmID8YMkeI,3510
|
|
24
|
+
global_support_standard-0.2.0.dist-info/METADATA,sha256=6fMrO0Gm_lu2oSI0QY1dVPrahw0i8iBkh_EDr9FB1aA,9000
|
|
25
|
+
global_support_standard-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
|
|
26
|
+
global_support_standard-0.2.0.dist-info/entry_points.txt,sha256=HJ5mZQcj7_oJm5sRp3sA9d3WdYLBGQa0xK3qeJhUw0s,128
|
|
27
|
+
global_support_standard-0.2.0.dist-info/top_level.txt,sha256=fig0kguescMThBQcrN02Zj_n7HKQnaHQSn_oK40lnkk,50
|
|
28
|
+
global_support_standard-0.2.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Global Support Standard Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
6
|
+
|
|
7
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
gss_cli/__init__.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__all__ = []
|
gss_cli/main.py
ADDED
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
import os
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
import httpx
|
|
9
|
+
import typer
|
|
10
|
+
|
|
11
|
+
app = typer.Typer(add_completion=False, no_args_is_help=True)
|
|
12
|
+
TOKEN_PATH = Path.home() / ".gss" / "tokens.json"
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def _shop_env_key(shop: str) -> str:
|
|
16
|
+
normalized = "".join(c if c.isalnum() else "_" for c in shop).upper()
|
|
17
|
+
return f"GSS_SHOP_{normalized}_ENDPOINT"
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def _resolve_endpoint(shop: str) -> str:
|
|
21
|
+
return os.getenv(_shop_env_key(shop), os.getenv("GSS_DEFAULT_ENDPOINT", "http://127.0.0.1:8000/v1"))
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _load_tokens() -> dict[str, str]:
|
|
25
|
+
if os.getenv("GSS_STORE_TOKENS", "1").lower() in {"0", "false", "no"}:
|
|
26
|
+
return {}
|
|
27
|
+
if not TOKEN_PATH.exists():
|
|
28
|
+
return {}
|
|
29
|
+
return json.loads(TOKEN_PATH.read_text())
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _save_tokens(tokens: dict[str, str]) -> None:
|
|
33
|
+
if os.getenv("GSS_STORE_TOKENS", "1").lower() in {"0", "false", "no"}:
|
|
34
|
+
return
|
|
35
|
+
TOKEN_PATH.parent.mkdir(parents=True, exist_ok=True)
|
|
36
|
+
TOKEN_PATH.write_text(json.dumps(tokens, indent=2))
|
|
37
|
+
os.chmod(TOKEN_PATH, 0o600)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def _token_for(shop: str) -> str | None:
|
|
41
|
+
inline_token = os.getenv("GSS_CUSTOMER_TOKEN")
|
|
42
|
+
if inline_token:
|
|
43
|
+
return inline_token
|
|
44
|
+
return _load_tokens().get(shop)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _parse_flags(args: list[str]) -> tuple[list[str], dict[str, Any]]:
|
|
48
|
+
positionals: list[str] = []
|
|
49
|
+
flags: dict[str, Any] = {}
|
|
50
|
+
i = 0
|
|
51
|
+
while i < len(args):
|
|
52
|
+
arg = args[i]
|
|
53
|
+
if arg.startswith("--"):
|
|
54
|
+
key = arg[2:].replace("-", "_")
|
|
55
|
+
if i + 1 < len(args) and not args[i + 1].startswith("--"):
|
|
56
|
+
value: Any = args[i + 1]
|
|
57
|
+
i += 1
|
|
58
|
+
else:
|
|
59
|
+
value = True
|
|
60
|
+
flags[key] = value
|
|
61
|
+
else:
|
|
62
|
+
positionals.append(arg)
|
|
63
|
+
i += 1
|
|
64
|
+
return positionals, flags
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def _headers(shop: str) -> dict[str, str]:
|
|
68
|
+
token = _token_for(shop)
|
|
69
|
+
if not token:
|
|
70
|
+
raise typer.BadParameter(f"No auth token for {shop}. Run: gss {shop} auth login --method api_key")
|
|
71
|
+
return {
|
|
72
|
+
"Authorization": f"Bearer {token}",
|
|
73
|
+
"GSS-Consumer-Id": os.getenv("GSS_CONSUMER_ID", "support-squad-ai"),
|
|
74
|
+
"GSS-Consumer-Type": os.getenv("GSS_CONSUMER_TYPE", "ai_agent"),
|
|
75
|
+
"GSS-Version": "1.0",
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def _request(
|
|
80
|
+
*,
|
|
81
|
+
method: str,
|
|
82
|
+
endpoint: str,
|
|
83
|
+
path: str,
|
|
84
|
+
headers: dict[str, str] | None = None,
|
|
85
|
+
params: dict[str, Any] | None = None,
|
|
86
|
+
body: dict[str, Any] | None = None,
|
|
87
|
+
) -> dict[str, Any]:
|
|
88
|
+
with httpx.Client(timeout=20.0) as client:
|
|
89
|
+
response = client.request(method, f"{endpoint}{path}", headers=headers, params=params, json=body)
|
|
90
|
+
data = response.json()
|
|
91
|
+
if response.status_code >= 400:
|
|
92
|
+
msg = data.get("error", {}).get("message", "Request failed")
|
|
93
|
+
raise typer.BadParameter(msg)
|
|
94
|
+
return data
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def _emit(value: dict[str, Any]) -> None:
|
|
98
|
+
typer.echo(json.dumps(value, indent=2))
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _warn_if_uncertified(describe_payload: dict[str, Any]) -> None:
|
|
102
|
+
data = describe_payload.get("data", {})
|
|
103
|
+
compliance = data.get("compliance")
|
|
104
|
+
if not isinstance(compliance, dict):
|
|
105
|
+
typer.echo(
|
|
106
|
+
"Warning: shop does not expose compliance metadata. Trust level unknown.",
|
|
107
|
+
err=True,
|
|
108
|
+
)
|
|
109
|
+
return
|
|
110
|
+
if not compliance.get("certified", False):
|
|
111
|
+
level = compliance.get("level", "unknown")
|
|
112
|
+
suite = compliance.get("test_suite_version", "unverified")
|
|
113
|
+
typer.echo(
|
|
114
|
+
f"Warning: shop is not GSS certified (level={level}, suite={suite}).",
|
|
115
|
+
err=True,
|
|
116
|
+
)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
@app.command(
|
|
120
|
+
context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
|
|
121
|
+
add_help_option=True,
|
|
122
|
+
)
|
|
123
|
+
def main(ctx: typer.Context, shop: str, parts: list[str] = typer.Argument(...)) -> None:
|
|
124
|
+
endpoint = _resolve_endpoint(shop)
|
|
125
|
+
positionals, flags = _parse_flags(parts + list(ctx.args))
|
|
126
|
+
|
|
127
|
+
if not positionals:
|
|
128
|
+
raise typer.BadParameter("Expected command pattern: gss <shop> <domain> <action>")
|
|
129
|
+
|
|
130
|
+
if positionals[0] == "describe":
|
|
131
|
+
describe_payload = _request(method="GET", endpoint=endpoint, path="/describe")
|
|
132
|
+
_warn_if_uncertified(describe_payload)
|
|
133
|
+
_emit(describe_payload)
|
|
134
|
+
return
|
|
135
|
+
|
|
136
|
+
domain = positionals[0]
|
|
137
|
+
action = positionals[1] if len(positionals) > 1 else "describe"
|
|
138
|
+
|
|
139
|
+
if domain == "auth" and action == "login":
|
|
140
|
+
method = flags.get("method", "api_key")
|
|
141
|
+
customer_id = flags.get("customer_id", "CUST-001")
|
|
142
|
+
res = _request(
|
|
143
|
+
method="POST",
|
|
144
|
+
endpoint=endpoint,
|
|
145
|
+
path="/auth/login",
|
|
146
|
+
body={"method": method, "customer_id": customer_id},
|
|
147
|
+
)
|
|
148
|
+
token = res["data"]["access_token"]
|
|
149
|
+
if os.getenv("GSS_STORE_TOKENS", "1").lower() in {"0", "false", "no"}:
|
|
150
|
+
typer.echo("Token storage disabled. Export GSS_CUSTOMER_TOKEN for subsequent commands.", err=True)
|
|
151
|
+
else:
|
|
152
|
+
tokens = _load_tokens()
|
|
153
|
+
tokens[shop] = token
|
|
154
|
+
_save_tokens(tokens)
|
|
155
|
+
_emit(res)
|
|
156
|
+
return
|
|
157
|
+
|
|
158
|
+
if domain == "auth" and action == "verify-customer":
|
|
159
|
+
body: dict[str, Any] = {}
|
|
160
|
+
if "order_id" in flags:
|
|
161
|
+
body["order_id"] = flags["order_id"]
|
|
162
|
+
if "email" in flags:
|
|
163
|
+
body["email"] = flags["email"]
|
|
164
|
+
if "phone" in flags:
|
|
165
|
+
body["phone"] = flags["phone"]
|
|
166
|
+
_emit(
|
|
167
|
+
_request(
|
|
168
|
+
method="POST",
|
|
169
|
+
endpoint=endpoint,
|
|
170
|
+
path="/auth/verify-customer",
|
|
171
|
+
body=body,
|
|
172
|
+
)
|
|
173
|
+
)
|
|
174
|
+
return
|
|
175
|
+
|
|
176
|
+
if domain == "auth" and action == "issue-token":
|
|
177
|
+
method = flags.get("method", "api_key")
|
|
178
|
+
res = _request(
|
|
179
|
+
method="POST",
|
|
180
|
+
endpoint=endpoint,
|
|
181
|
+
path="/auth/issue-token",
|
|
182
|
+
body={"verification_id": flags["verification_id"], "method": method},
|
|
183
|
+
)
|
|
184
|
+
token = res["data"]["access_token"]
|
|
185
|
+
if os.getenv("GSS_STORE_TOKENS", "1").lower() in {"0", "false", "no"}:
|
|
186
|
+
typer.echo("Token storage disabled. Export GSS_CUSTOMER_TOKEN for subsequent commands.", err=True)
|
|
187
|
+
else:
|
|
188
|
+
tokens = _load_tokens()
|
|
189
|
+
tokens[shop] = token
|
|
190
|
+
_save_tokens(tokens)
|
|
191
|
+
_emit(res)
|
|
192
|
+
return
|
|
193
|
+
|
|
194
|
+
if action == "describe":
|
|
195
|
+
_emit(_request(method="GET", endpoint=endpoint, path=f"/{domain}/describe"))
|
|
196
|
+
return
|
|
197
|
+
|
|
198
|
+
headers = _headers(shop)
|
|
199
|
+
|
|
200
|
+
if domain == "orders" and action == "list":
|
|
201
|
+
_emit(_request(method="GET", endpoint=endpoint, path="/orders", headers=headers, params=flags))
|
|
202
|
+
return
|
|
203
|
+
if domain == "orders" and action == "get":
|
|
204
|
+
_emit(_request(method="GET", endpoint=endpoint, path=f"/orders/{flags['id']}", headers=headers))
|
|
205
|
+
return
|
|
206
|
+
if domain == "shipping" and action == "track":
|
|
207
|
+
_emit(_request(method="GET", endpoint=endpoint, path=f"/shipping/track/{flags['order_id']}", headers=headers))
|
|
208
|
+
return
|
|
209
|
+
if domain == "returns" and action == "check-eligibility":
|
|
210
|
+
_emit(
|
|
211
|
+
_request(
|
|
212
|
+
method="POST",
|
|
213
|
+
endpoint=endpoint,
|
|
214
|
+
path="/returns/check-eligibility",
|
|
215
|
+
headers=headers,
|
|
216
|
+
body={"order_id": flags["order_id"], "item_id": flags["item_id"]},
|
|
217
|
+
)
|
|
218
|
+
)
|
|
219
|
+
return
|
|
220
|
+
if domain == "returns" and action == "initiate":
|
|
221
|
+
_emit(
|
|
222
|
+
_request(
|
|
223
|
+
method="POST",
|
|
224
|
+
endpoint=endpoint,
|
|
225
|
+
path="/returns/initiate",
|
|
226
|
+
headers=headers,
|
|
227
|
+
body={
|
|
228
|
+
"order_id": flags["order_id"],
|
|
229
|
+
"item_id": flags["item_id"],
|
|
230
|
+
"reason": flags["reason"],
|
|
231
|
+
},
|
|
232
|
+
)
|
|
233
|
+
)
|
|
234
|
+
return
|
|
235
|
+
if domain == "returns" and action == "confirm":
|
|
236
|
+
_emit(
|
|
237
|
+
_request(
|
|
238
|
+
method="POST",
|
|
239
|
+
endpoint=endpoint,
|
|
240
|
+
path="/returns/confirm",
|
|
241
|
+
headers=headers,
|
|
242
|
+
body={"token": flags["token"]},
|
|
243
|
+
)
|
|
244
|
+
)
|
|
245
|
+
return
|
|
246
|
+
if domain == "protocols" and action == "get":
|
|
247
|
+
context = flags.get("context", "{}")
|
|
248
|
+
_emit(
|
|
249
|
+
_request(
|
|
250
|
+
method="POST",
|
|
251
|
+
endpoint=endpoint,
|
|
252
|
+
path="/protocols/get",
|
|
253
|
+
headers=headers,
|
|
254
|
+
body={"trigger": flags["trigger"], "context": json.loads(context)},
|
|
255
|
+
)
|
|
256
|
+
)
|
|
257
|
+
return
|
|
258
|
+
if domain == "account" and action == "audit-log":
|
|
259
|
+
_emit(_request(method="GET", endpoint=endpoint, path="/account/audit-log", headers=headers))
|
|
260
|
+
return
|
|
261
|
+
|
|
262
|
+
raise typer.BadParameter(f"Unknown command path: {' '.join(positionals)}")
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
def run() -> None:
|
|
266
|
+
app()
|
gss_core/__init__.py
ADDED
gss_core/envelope.py
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from typing import Any
|
|
4
|
+
|
|
5
|
+
from .models import ErrorPayload, ResponseEnvelope
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def ok(data: Any, request_id: str) -> dict[str, Any]:
|
|
9
|
+
return ResponseEnvelope(status="ok", data=data, error=None, meta={"request_id": request_id}).model_dump()
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def fail(code: str, message: str, request_id: str, details: dict[str, Any] | None = None) -> dict[str, Any]:
|
|
13
|
+
return ResponseEnvelope(
|
|
14
|
+
status="error",
|
|
15
|
+
data=None,
|
|
16
|
+
error=ErrorPayload(code=code, message=message, details=details),
|
|
17
|
+
meta={"request_id": request_id},
|
|
18
|
+
).model_dump()
|
gss_core/errors.py
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
from typing import Any
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
@dataclass
|
|
8
|
+
class GssError(Exception):
|
|
9
|
+
code: str
|
|
10
|
+
message: str
|
|
11
|
+
status_code: int = 400
|
|
12
|
+
details: dict[str, Any] | None = None
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def err(
|
|
16
|
+
code: str,
|
|
17
|
+
message: str,
|
|
18
|
+
*,
|
|
19
|
+
status_code: int = 400,
|
|
20
|
+
details: dict[str, Any] | None = None,
|
|
21
|
+
) -> GssError:
|
|
22
|
+
return GssError(code=code, message=message, status_code=status_code, details=details)
|