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.
@@ -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
+ [![CI](https://github.com/MichelN89/global-support-standard/actions/workflows/ci.yml/badge.svg)](https://github.com/MichelN89/global-support-standard/actions/workflows/ci.yml)
41
+ [![License](https://img.shields.io/github/license/MichelN89/global-support-standard)](LICENSE)
42
+ [![Python](https://img.shields.io/badge/python-3.11%2B-blue)](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,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (82.0.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,4 @@
1
+ [console_scripts]
2
+ gss = gss_cli.main:run
3
+ gss-provider = gss_provider.app:run
4
+ gss-shopify-provider = gss_webshop_shopify.app:run
@@ -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.
@@ -0,0 +1,4 @@
1
+ gss_cli
2
+ gss_core
3
+ gss_provider
4
+ gss_webshop_shopify
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
@@ -0,0 +1,3 @@
1
+ from .models import ErrorPayload, ResponseEnvelope
2
+
3
+ __all__ = ["ResponseEnvelope", "ErrorPayload"]
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)