snaplii-cli 0.4.0__tar.gz

snaplii_cli-0.4.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.env
+*.egg
+.DS_Store

snaplii_cli-0.4.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: snaplii-cli
+Version: 0.4.0
+Summary: Browse, purchase, and manage gift cards through Snaplii — safe payments for AI agents
+Project-URL: Homepage, https://github.com/SnapPayInc/ai-passport
+Project-URL: Repository, https://github.com/SnapPayInc/ai-passport
+Author-email: Snaplii Inc <charles.zhang@snaplii.com>
+License: Apache-2.0
+Keywords: ai-agent,cli,gift-cards,payments,snaplii
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.9
+Requires-Dist: click<9,>=8.1
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: keyring>=25.0
+Provides-Extra: dev
+Requires-Dist: pytest-httpx<1,>=0.35; extra == 'dev'
+Requires-Dist: pytest<9,>=8.0; extra == 'dev'

snaplii_cli-0.4.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "snaplii-cli"
+version = "0.4.0"
+description = "Browse, purchase, and manage gift cards through Snaplii — safe payments for AI agents"
+requires-python = ">=3.9"
+license = {text = "Apache-2.0"}
+authors = [{name = "Snaplii Inc", email = "charles.zhang@snaplii.com"}]
+keywords = ["snaplii", "gift-cards", "ai-agent", "payments", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+    "click>=8.1,<9",
+    "httpx>=0.27,<1",
+    "keyring>=25.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/SnapPayInc/ai-passport"
+Repository = "https://github.com/SnapPayInc/ai-passport"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0,<9",
+    "pytest-httpx>=0.35,<1",
+]
+
+[project.scripts]
+snaplii = "snaplii.cli:_cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/snaplii"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

snaplii_cli-0.4.0/src/snaplii/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

snaplii_cli-0.4.0/src/snaplii/__main__.py

@@ -0,0 +1,3 @@
+from snaplii.cli import main
+
+main()

snaplii_cli-0.4.0/src/snaplii/cli.py

@@ -0,0 +1,67 @@
+import sys
+
+import click
+
+from snaplii.client import GatewayClient
+from snaplii.commands.apikey import apikey_group
+from snaplii.commands.browse import browse_group
+from snaplii.commands.config import config_group
+from snaplii.commands.giftcard import giftcard_group
+from snaplii.commands.init import init_cmd
+from snaplii.commands.purchase import purchase_cmd
+from snaplii.commands.smart import smart_group
+from snaplii.config_store import ConfigStore
+from snaplii.exceptions import SnapliiCliError
+from snaplii.output import print_error
+
+_DEFAULT_BASE_URL = "https://aipayment.snaplii.com"
+
+
+@click.group()
+@click.option(
+    "--base-url",
+    envvar="SNAPLII_BASE_URL",
+    default=None,
+    help="Gateway base URL (overrides config)",
+)
+@click.pass_context
+def main(ctx, base_url):
+    """Snaplii Agent Gateway CLI.
+
+    Browse gift card brands, manage your cards, purchase new ones,
+    and manage API keys.
+    """
+    ctx.ensure_object(dict)
+    store = ConfigStore()
+    resolved_url = base_url or store.get("base_url", _DEFAULT_BASE_URL)
+    ctx.obj["config_store"] = store
+    ctx.obj["client"] = GatewayClient(resolved_url, store)
+
+
+main.add_command(init_cmd)
+main.add_command(browse_group)
+main.add_command(giftcard_group)
+main.add_command(purchase_cmd)
+main.add_command(apikey_group)
+main.add_command(smart_group)
+main.add_command(config_group)
+
+
+@main.command("help")
+@click.pass_context
+def help_cmd(ctx):
+    """Show full CLI documentation."""
+    click.echo(ctx.parent.get_help())
+
+
+def _cli():
+    try:
+        main(standalone_mode=False)
+    except click.exceptions.Exit:
+        pass
+    except click.UsageError as e:
+        print_error({"error": "Usage error", "message": str(e)})
+        sys.exit(1)
+    except SnapliiCliError as e:
+        print_error(e.to_dict())
+        sys.exit(1)

snaplii_cli-0.4.0/src/snaplii/client.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import httpx
+
+from snaplii.config_store import ConfigStore
+from snaplii.exceptions import ConfigError, GatewayApiError, GatewayConnectionError
+
+
+class GatewayClient:
+    def __init__(self, base_url: str, config_store: ConfigStore):
+        self._base_url = base_url.rstrip("/")
+        self._config = config_store
+        self._http = httpx.Client(timeout=30.0)
+
+    # ── Auth ──────────────────────────────────────────────────────
+
+    def login(self, agent_id: str, api_key: str) -> dict:
+        resp = self._post("/v2/auth/token", json={
+            "agent_id": agent_id,
+            "api_key": api_key,
+        })
+        token = resp.get("access_token")
+        expires_in = resp.get("expires_in", 3600)
+        if token:
+            self._config.cache_token(token, expires_in)
+        return resp
+
+    # ── User cards ────────────────────────────────────────────────
+
+    def list_user_cards(self, status: str = "ACTIVE", page: int = 1, page_size: int = 20) -> dict:
+        return self._get("/v2/cards", params={
+            "status": status,
+            "page": str(page),
+            "pageSize": str(page_size),
+        })
+
+    def get_card_detail(self, card_no: str) -> dict:
+        return self._get(f"/v2/cards/{card_no}")
+
+    # ── Card browsing ─────────────────────────────────────────────
+
+    def get_all_card_tags(self, channel: str = "HOME_PAGE", location_prov: str = "ON") -> dict:
+        resp = self._get("/v2/card-brands", params={
+            "channel": channel,
+            "locationProv": location_prov,
+        })
+        # Gateway returns list directly; normalize to {"data": [...]}
+        if isinstance(resp, list):
+            return {"data": resp}
+        return resp
+
+    def get_card_brand_by_id(self, card_brand_id: str) -> dict:
+        resp = self._get(f"/v2/card-brands/{card_brand_id}", params={
+            "showDetail": "true",
+        })
+        # Gateway returns detail directly; normalize to {"data": {...}}
+        if isinstance(resp, dict) and "data" not in resp and "cardBrandId" in resp:
+            return {"data": resp}
+        return resp
+
+    # ── Purchase ──────────────────────────────────────────────────
+
+    def create_order_and_pay(
+        self,
+        item_id: str,
+        price: str,
+        payment_method: str = "SNAPLII_CASH",
+        payment_token: str | None = None,
+        location_prov: str = "ON",
+    ) -> dict:
+        payment_ctx = {
+            "specifiedPrimaryPaymentMethod": payment_method,
+            "voucherOption": "BEST_FIT",
+            "cashbackOption": "USE",
+        }
+        if payment_token:
+            payment_ctx["specifiedPrimaryPaymentToken"] = payment_token
+        return self._post("/v2/purchase", json={
+            "orderInfo": {
+                "orderType": "GIFT_CARD",
+                "item": {"itemId": item_id, "price": price},
+                "orderContext": {"giftOrder": "false"},
+                "businessChannel": "APP",
+            },
+            "paymentContext": payment_ctx,
+            "delivery": {"type": "WALLET", "immediateSend": "true"},
+            "locationProv": location_prov,
+        })
+
+    # ── API key management ────────────────────────────────────────
+
+    def create_api_key(self, name: str, scope: str, consumption_limit: float | None = None) -> dict:
+        params = {"name": name, "scope": scope}
+        if consumption_limit is not None:
+            params["consumptionLimit"] = str(consumption_limit)
+        return self._post("/v2/apikeys", params=params)
+
+    def list_api_keys(self) -> dict:
+        return self._get("/v2/apikeys")
+
+    def delete_api_key(self, key_id: str) -> dict:
+        return self._delete(f"/v2/apikeys/{key_id}")
+
+    # ── Internal ──────────────────────────────────────────────────
+
+    def _ensure_token(self) -> str:
+        token = self._config.get_cached_token()
+        if token:
+            return token
+        agent_id = self._config.get("agent_id")
+        api_key = self._config.get("api_key")
+        if agent_id and api_key:
+            self.login(agent_id, api_key)
+            token = self._config.get_cached_token()
+            if token:
+                return token
+        raise ConfigError(
+            "No valid token. Run 'snaplii init --agent-id ID --api-key KEY' to authenticate."
+        )
+
+    def _get(self, path: str, params: dict | None = None) -> dict:
+        token = self._ensure_token()
+        url = self._base_url + path
+        headers = {"Authorization": f"Bearer {token}"}
+        try:
+            resp = self._http.get(url, params=params, headers=headers)
+        except httpx.ConnectError as e:
+            raise GatewayConnectionError(url, e)
+        return self._parse_response(resp, path)
+
+    def _post(self, path: str, json: dict | None = None, params: dict | None = None) -> dict:
+        url = self._base_url + path
+        headers = {}
+        if path != "/v2/auth/token":
+            token = self._ensure_token()
+            headers = {"Authorization": f"Bearer {token}"}
+        try:
+            resp = self._http.post(url, json=json, params=params, headers=headers)
+        except httpx.ConnectError as e:
+            raise GatewayConnectionError(url, e)
+        return self._parse_response(resp, path)
+
+    def _delete(self, path: str) -> dict:
+        token = self._ensure_token()
+        url = self._base_url + path
+        headers = {"Authorization": f"Bearer {token}"}
+        try:
+            resp = self._http.delete(url, headers=headers)
+        except httpx.ConnectError as e:
+            raise GatewayConnectionError(url, e)
+        return self._parse_response(resp, path)
+
+    # Human-readable error messages for common error codes
+    _ERROR_MESSAGES = {
+        "MACP6005": "Payment failed. This usually means insufficient Snaplii Cash balance. Please top up your Snaplii Cash and try again.",
+        "MACP6006": "Service call failed. The downstream gift card service is temporarily unavailable. Please try again later.",
+        "MCAP9999": "Session expired. Please run 'snaplii init' to re-authenticate.",
+        "MCA20101": "Invalid API key format or request parameters.",
+        "MCA20102": "This API key has been deactivated.",
+        "MCA20103": "An API key with this name already exists. Please choose a different name.",
+        "MCA20104": "API key limit reached. Delete an existing key before creating a new one.",
+        "MCA20105": "API key not found.",
+        "MCA20106": "This API key does not belong to your account.",
+        "APP_VERSION_NOT_SUPPORT": "App version too low. Minimum version 4.8.0 required.",
+        "USR_NOT_EXIST": "User not found in session. Please re-authenticate.",
+        "ORDER_STATUS_INCORRECT": "Order status error. The order may not exist or is not in a payable state.",
+        "ORDER_CREATION_FAILED": "Order creation failed. You may have reached a spending limit.",
+        "AUTH_VERIFY_FAILED": "Authentication verification failed.",
+    }
+
+    @classmethod
+    def _parse_response(cls, resp: httpx.Response, path: str):
+        try:
+            body = resp.json()
+        except Exception:
+            body = {"raw": resp.text}
+        if resp.is_success:
+            if isinstance(body, dict):
+                rsp_code = body.get("rspMsgCd", "")
+                if rsp_code and not rsp_code.endswith("00000"):
+                    friendly = cls._ERROR_MESSAGES.get(rsp_code)
+                    if friendly:
+                        body["friendly_message"] = friendly
+                    raise GatewayApiError(resp.status_code, body, path)
+            return body
+        if not isinstance(body, dict):
+            body = {"raw": body}
+        raise GatewayApiError(resp.status_code, body, path)

snaplii_cli-0.4.0/src/snaplii/commands/apikey.py

@@ -0,0 +1,42 @@
+import click
+
+from snaplii.client import GatewayClient
+from snaplii.output import print_json
+
+
+@click.group("apikey")
+@click.pass_context
+def apikey_group(ctx):
+    """API key management (create, list, delete)."""
+    pass
+
+
+@apikey_group.command("list")
+@click.pass_context
+def apikey_list(ctx):
+    """List all your API keys."""
+    client: GatewayClient = ctx.obj["client"]
+    resp = client.list_api_keys()
+    print_json(resp)
+
+
+@apikey_group.command("create")
+@click.option("--name", required=True, help="API key name")
+@click.option("--scope", default="PAY_READ", help="Scope: PAY_READ or PAY_WRITE")
+@click.option("--limit", default=None, type=float, help="Consumption limit in dollars")
+@click.pass_context
+def apikey_create(ctx, name, scope, limit):
+    """Create a new API key."""
+    client: GatewayClient = ctx.obj["client"]
+    resp = client.create_api_key(name, scope, limit)
+    print_json(resp)
+
+
+@apikey_group.command("delete")
+@click.option("--key-id", required=True, help="API key ID to delete")
+@click.pass_context
+def apikey_delete(ctx, key_id):
+    """Delete an API key."""
+    client: GatewayClient = ctx.obj["client"]
+    resp = client.delete_api_key(key_id)
+    print_json(resp)

snaplii_cli-0.4.0/src/snaplii/commands/browse.py

@@ -0,0 +1,32 @@
+import click
+
+from snaplii.client import GatewayClient
+from snaplii.output import print_json
+
+
+@click.group("browse")
+@click.pass_context
+def browse_group(ctx):
+    """Browse available gift card brands and categories."""
+    pass
+
+
+@browse_group.command("tags")
+@click.option("--channel", default="HOME_PAGE", help="Channel: HOME_PAGE or SEND_GIFT")
+@click.option("--prov", default="ON", help="Province code (ON, QC, BC, etc.)")
+@click.pass_context
+def browse_tags(ctx, channel, prov):
+    """List all card categories (tags) with brand summaries."""
+    client: GatewayClient = ctx.obj["client"]
+    resp = client.get_all_card_tags(channel=channel, location_prov=prov)
+    print_json(resp)
+
+
+@browse_group.command("brand")
+@click.option("--id", "brand_id", required=True, help="Card brand ID (e.g. CB0000000000135)")
+@click.pass_context
+def browse_brand(ctx, brand_id):
+    """Get card brand details including available denominations."""
+    client: GatewayClient = ctx.obj["client"]
+    resp = client.get_card_brand_by_id(brand_id)
+    print_json(resp)

snaplii_cli-0.4.0/src/snaplii/commands/card_brands.py

@@ -0,0 +1,30 @@
+import click
+
+from snaplii.client import GatewayClient
+from snaplii.output import print_json
+
+
+@click.group("card-brands")
+@click.pass_context
+def card_brands_group(ctx):
+    """Card brand operations (list, get)."""
+    pass
+
+
+@card_brands_group.command("list")
+@click.pass_context
+def card_brands_list(ctx):
+    """List all available card brands (brandId + name)."""
+    client: GatewayClient = ctx.obj["client"]
+    resp = client.list_card_brands()
+    print_json(resp)
+
+
+@card_brands_group.command("get")
+@click.option("--id", "card_brand_id", required=True, help="Card brand ID")
+@click.pass_context
+def card_brands_get(ctx, card_brand_id):
+    """Get card brand details by ID."""
+    client: GatewayClient = ctx.obj["client"]
+    resp = client.get_card_brand(card_brand_id)
+    print_json(resp)

snaplii_cli-0.4.0/src/snaplii/commands/config.py

@@ -0,0 +1,44 @@
+import click
+
+from snaplii.config_store import ConfigStore
+from snaplii.output import print_json
+
+
+@click.group("config")
+@click.pass_context
+def config_group(ctx):
+    """Manage CLI configuration (base URL, credentials)."""
+    pass
+
+
+@config_group.command("set")
+@click.option("--base-url", required=True, help="Gateway base URL (e.g. http://localhost:8080)")
+@click.pass_context
+def config_set(ctx, base_url):
+    """Set the gateway base URL."""
+    store: ConfigStore = ctx.obj["config_store"]
+    store.set("base_url", base_url)
+    print_json({"status": "ok", "updated": ["base_url"]})
+
+
+@config_group.command("show")
+@click.pass_context
+def config_show(ctx):
+    """Display current configuration."""
+    store: ConfigStore = ctx.obj["config_store"]
+    data = store.load()
+    if "api_key" in data and data["api_key"]:
+        key = data["api_key"]
+        data["api_key"] = key[:8] + "..." if len(key) > 8 else "***"
+    if "access_token" in data and data["access_token"]:
+        data["access_token"] = data["access_token"][:20] + "..."
+    print_json(data)
+
+
+@config_group.command("clear")
+@click.pass_context
+def config_clear(ctx):
+    """Delete configuration file."""
+    store: ConfigStore = ctx.obj["config_store"]
+    store.clear()
+    print_json({"status": "ok", "message": "Configuration cleared"})

snaplii_cli-0.4.0/src/snaplii/commands/giftcard.py

@@ -0,0 +1,33 @@
+import click
+
+from snaplii.client import GatewayClient
+from snaplii.output import print_json
+
+
+@click.group("giftcard")
+@click.pass_context
+def giftcard_group(ctx):
+    """Gift card operations (list owned cards, view details)."""
+    pass
+
+
+@giftcard_group.command("list")
+@click.option("--status", default="ACTIVE", help="Card status: ACTIVE or INACTIVE")
+@click.option("--page", default=1, type=int, help="Page number")
+@click.option("--page-size", default=20, type=int, help="Page size")
+@click.pass_context
+def giftcard_list(ctx, status, page, page_size):
+    """List your gift cards."""
+    client: GatewayClient = ctx.obj["client"]
+    resp = client.list_user_cards(status=status, page=page, page_size=page_size)
+    print_json(resp)
+
+
+@giftcard_group.command("detail")
+@click.option("--card-no", required=True, help="Card number")
+@click.pass_context
+def giftcard_detail(ctx, card_no):
+    """Get details of a specific gift card (including redemption code)."""
+    client: GatewayClient = ctx.obj["client"]
+    resp = client.get_card_detail(card_no)
+    print_json(resp)

snaplii_cli-0.4.0/src/snaplii/commands/init.py

@@ -0,0 +1,18 @@
+import click
+
+from snaplii.client import GatewayClient
+from snaplii.output import print_json
+
+
+@click.command("init")
+@click.option("--agent-id", required=True, help="Agent ID for session isolation")
+@click.option("--api-key", required=True, help="API key (snp_sk_live_...)")
+@click.pass_context
+def init_cmd(ctx, agent_id, api_key):
+    """Login with agent ID + API key and store credentials."""
+    client: GatewayClient = ctx.obj["client"]
+    store = ctx.obj["config_store"]
+
+    store.set_many({"agent_id": agent_id, "api_key": api_key})
+    resp = client.login(agent_id, api_key)
+    print_json(resp)

snaplii_cli-0.4.0/src/snaplii/commands/purchase.py

@@ -0,0 +1,24 @@
+import click
+
+from snaplii.client import GatewayClient
+from snaplii.output import print_json
+
+
+@click.command("purchase")
+@click.option("--item-id", required=True, help="Item ID (e.g. CB0000000000135-CT0000000000897)")
+@click.option("--price", required=True, help="Price in dollars (e.g. 50)")
+@click.option("--payment-method", default="SNAPLII_CASH", help="Payment method (SNAPLII_CASH, SNAPLII_CREDIT, SNAPLII_DEBIT)")
+@click.option("--payment-token", default=None, help="Payment token (auto-derived by gateway if omitted)")
+@click.option("--prov", default="ON", help="Province code")
+@click.pass_context
+def purchase_cmd(ctx, item_id, price, payment_method, payment_token, prov):
+    """Create an order and pay for a gift card."""
+    client: GatewayClient = ctx.obj["client"]
+    resp = client.create_order_and_pay(
+        item_id=item_id,
+        price=price,
+        payment_method=payment_method,
+        payment_token=payment_token,
+        location_prov=prov,
+    )
+    print_json(resp)

snaplii_cli-0.4.0/src/snaplii/commands/smart.py

@@ -0,0 +1,81 @@
+import click
+
+from snaplii.client import GatewayClient
+from snaplii.output import print_json
+
+
+@click.group("smart")
+@click.pass_context
+def smart_group(ctx):
+    """Smart features: cashback calculator, dashboard."""
+    pass
+
+
+@smart_group.command("cashback")
+@click.option("--brand-id", required=True, help="Card brand ID")
+@click.option("--amount", required=True, type=float, help="Purchase amount in dollars")
+@click.pass_context
+def cashback_cmd(ctx, brand_id, amount):
+    """Calculate cashback savings for a specific brand and amount."""
+    client: GatewayClient = ctx.obj["client"]
+    detail = client.get_card_brand_by_id(brand_id)
+    # Gateway returns detail directly; prod wraps in "data"
+    brand_data = detail.get("data", detail) if isinstance(detail.get("data"), dict) else detail
+    cards = brand_data.get("cards", [])
+
+    best_match = None
+    for c in cards:
+        fv = c.get("faceValueRules", {})
+        if fv.get("type") == "FIXED" and float(fv.get("priceStart", 0)) == amount:
+            best_match = c
+            break
+        elif fv.get("type") == "VARIABLE":
+            start = float(fv.get("priceStart", 0))
+            end = float(fv.get("priceEnd", 0))
+            if start <= amount <= end:
+                best_match = c
+
+    if best_match:
+        discount_pct = float(best_match.get("discount", 0) or 0)
+        savings = amount * discount_pct / 100
+        print_json({
+            "brand_id": brand_id,
+            "amount": amount,
+            "cashback_percent": f"{discount_pct}%",
+            "you_save": f"${savings:.2f}",
+            "effective_cost": f"${amount - savings:.2f}",
+            "item_id": f"{brand_id}-{best_match.get('cardTemplateId', '')}",
+        })
+    else:
+        print_json({"error": f"No matching denomination for ${amount}"})
+
+
+@smart_group.command("dashboard")
+@click.pass_context
+def dashboard_cmd(ctx):
+    """Show a summary dashboard of all your gift cards."""
+    client: GatewayClient = ctx.obj["client"]
+    resp = client.list_user_cards(status="ACTIVE", page=1, page_size=100)
+    cards = resp.get("data", [])
+
+    total_value = 0
+    brands = {}
+    for card in cards:
+        face_value = float(card.get("faceValue", 0))
+        total_value += face_value
+        brand_id = card.get("cardBrandId", "unknown")
+        brand_name = card.get("cardTemplate", {}).get("desc", {}).get("name", brand_id)
+        if brands.get(brand_id):
+            brands[brand_id]["count"] += 1
+            brands[brand_id]["total"] += face_value
+        else:
+            brands[brand_id] = {"name": brand_name, "count": 1, "total": face_value}
+
+    print_json({
+        "total_cards": len(cards),
+        "total_face_value": f"${total_value:.2f}",
+        "brands": [
+            {"brand": info["name"], "cards": info["count"], "total_value": f"${info['total']:.2f}"}
+            for info in sorted(brands.values(), key=lambda x: x["total"], reverse=True)
+        ],
+    })

snaplii_cli-0.4.0/src/snaplii/config_store.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+
+_TOKEN_SAFETY_MARGIN = 30  # seconds before expiry to trigger refresh
+
+
+class ConfigStore:
+    def __init__(self, path: Path | None = None):
+        self._path = path or Path.home() / ".snaplii" / "config.json"
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    def load(self) -> dict:
+        if not self._path.exists():
+            return {}
+        return json.loads(self._path.read_text())
+
+    def save(self, data: dict) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._path.write_text(json.dumps(data, indent=2) + "\n")
+        os.chmod(self._path, 0o600)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.load().get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        data = self.load()
+        data[key] = value
+        self.save(data)
+
+    def set_many(self, updates: dict) -> None:
+        data = self.load()
+        data.update(updates)
+        self.save(data)
+
+    def clear(self) -> None:
+        if self._path.exists():
+            self._path.unlink()
+
+    def get_cached_token(self) -> str | None:
+        data = self.load()
+        token = data.get("access_token")
+        expires_at = data.get("token_expires_at")
+        if not token or not expires_at:
+            return None
+        if time.time() >= expires_at - _TOKEN_SAFETY_MARGIN:
+            return None
+        return token
+
+    def cache_token(self, access_token: str, expires_in: int) -> None:
+        self.set_many({
+            "access_token": access_token,
+            "token_expires_at": time.time() + expires_in,
+        })
+

snaplii_cli-0.4.0/src/snaplii/exceptions.py

@@ -0,0 +1,41 @@
+class SnapliiCliError(Exception):
+    pass
+
+
+class GatewayApiError(SnapliiCliError):
+    def __init__(self, status_code: int, body: dict, endpoint: str):
+        self.status_code = status_code
+        self.body = body
+        self.endpoint = endpoint
+        super().__init__(f"API error {status_code} on {endpoint}")
+
+    def to_dict(self) -> dict:
+        friendly = self.body.get("friendly_message")
+        return {
+            "error": friendly or "API error",
+            "error_code": self.body.get("rspMsgCd", ""),
+            "endpoint": self.endpoint,
+        }
+
+
+class GatewayConnectionError(SnapliiCliError):
+    def __init__(self, url: str, cause: Exception):
+        self.url = url
+        self.cause = cause
+        super().__init__(f"Connection failed: {url}")
+
+    def to_dict(self) -> dict:
+        return {
+            "error": "Connection failed",
+            "url": self.url,
+            "cause": str(self.cause),
+        }
+
+
+class ConfigError(SnapliiCliError):
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(message)
+
+    def to_dict(self) -> dict:
+        return {"error": "Configuration error", "message": self.message}

snaplii_cli-0.4.0/src/snaplii/output.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import json
+import sys
+
+
+def print_json(data: dict | list) -> None:
+    print(json.dumps(data, indent=2))
+
+
+def print_error(err_dict: dict) -> None:
+    print(json.dumps(err_dict, indent=2), file=sys.stderr)