sophhub 0.4.45 → 0.4.47

package/skills/sophnet-invoice-assistant/src/references/error-cases.md

@@ -0,0 +1,16 @@
+# Error Cases
+
+## 登录态缺失
+
+- `AUTH_CONTEXT_MISSING`
+- 提示：当前 Sophnet 登录态缺失，请重新登录后再试。
+
+## 个人组织缺失
+
+- `PERSONAL_ORG_NOT_FOUND`
+- 提示：当前账号下未找到可用的个人组织，暂时无法代你提交发票申请。
+
+## 真实接口未接入
+
+- `API_NOT_IMPLEMENTED`
+- 提示：当前 skill 仅完成骨架搭建，尚未接入真实 Sophnet 发票接口。

package/skills/sophnet-invoice-assistant/src/scripts/__init__.py

@@ -0,0 +1 @@
+"""sophnet-invoice-assistant skill scripts package."""

package/skills/sophnet-invoice-assistant/src/scripts/auth_context.py

@@ -0,0 +1,74 @@
+"""Read Sophnet auth context from runtime environment."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from dto import AuthContext
+
+DEFAULT_JWT_PATHS = (
+    "/home/node/.openclaw/jwt.json",
+    "~/.openclaw/jwt.json",
+)
+
+
+def _normalize_api_base_url(raw_value):
+    value = (raw_value or "").strip()
+    if not value:
+        return "https://www.sophnet.com/api"
+    value = value.rstrip("/")
+    if value.endswith("/api"):
+        return value
+    return value + "/api"
+
+
+def _normalize_access_token(raw_value):
+    value = (raw_value or "").strip()
+    if not value:
+        return None
+    if value.lower().startswith("bearer "):
+        value = value[7:].strip()
+    return value or None
+
+
+def _candidate_jwt_paths():
+    custom_path = (os.environ.get("OPENCLAW_JWT_PATH") or "").strip()
+    if custom_path:
+        yield Path(custom_path).expanduser()
+
+    for raw_path in DEFAULT_JWT_PATHS:
+        yield Path(raw_path).expanduser()
+
+
+def _load_access_token_from_jwt():
+    for path in _candidate_jwt_paths():
+        try:
+            with path.open("r", encoding="utf-8") as fp:
+                payload = json.load(fp)
+        except (OSError, ValueError):
+            continue
+        if not isinstance(payload, dict):
+            continue
+        token = _normalize_access_token(payload.get("web_jwt"))
+        if token:
+            return token
+    return None
+
+
+def _resolve_access_token():
+    explicit_token = _normalize_access_token(os.environ.get("SOPHNET_ACCESS_TOKEN"))
+    if explicit_token:
+        return explicit_token
+    return _load_access_token_from_jwt()
+
+
+def load_auth_context():
+    return AuthContext(
+        api_base_url=_normalize_api_base_url(
+            os.environ.get("SOPHNET_API_BASE_URL") or os.environ.get("SOPHNET_BASE_URL")
+        ),
+        access_token=_resolve_access_token(),
+        cookie=os.environ.get("SOPHNET_COOKIE"),
+    )

package/skills/sophnet-invoice-assistant/src/scripts/cli.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""CLI entry for sophnet-invoice-assistant."""
+
+from __future__ import annotations
+
+import argparse
+
+from auth_context import load_auth_context
+from download_flow import run_download
+from dto import ActionRequest
+from invoice_client import InvoiceClient
+from output import emit_result, failure
+from prepare_flow import run_prepare
+from status_flow import run_status
+from submit_flow import run_submit
+from template_flow import run_template_delete, run_template_list, run_template_save
+from update_flow import run_update
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Sophnet personal invoice assistant skeleton")
+    parser.add_argument(
+        "--action",
+        required=True,
+        choices=["prepare", "submit", "update", "status", "download", "template_list", "template_save", "template_delete"],
+        help="Action to perform",
+    )
+    parser.add_argument(
+        "--user-request",
+        required=True,
+        help="Original user request text",
+    )
+    parser.add_argument(
+        "--org-id",
+        help="Known personal org id",
+    )
+    parser.add_argument(
+        "--application-no",
+        help="Known invoice application number",
+    )
+    parser.add_argument(
+        "--template-id",
+        help="Known invoice template id",
+    )
+    parser.add_argument(
+        "--confirm",
+        default="false",
+        choices=["true", "false"],
+        help="Whether user already confirmed the submit action",
+    )
+    parser.add_argument("--buyer-type", choices=["INDIVIDUAL", "ENTERPRISE"])
+    parser.add_argument("--title")
+    parser.add_argument("--tax-no")
+    parser.add_argument("--address-phone")
+    parser.add_argument("--bank-account")
+    parser.add_argument("--invoice-type", choices=["NORMAL", "SPECIAL"])
+    parser.add_argument(
+        "--recharge-trans-nos",
+        help="Comma-separated recharge transNo list",
+    )
+    parser.add_argument(
+        "--issuing-mode",
+        choices=["AGGREGATED", "SEPARATE"],
+        help="Required when multiple recharge records are selected",
+    )
+    parser.add_argument(
+        "--save-as-template",
+        default="false",
+        choices=["true", "false"],
+    )
+    parser.add_argument("--template-name")
+    parser.add_argument(
+        "--use-latest-template",
+        default="false",
+        choices=["true", "false"],
+    )
+    return parser.parse_args()
+
+
+def build_request(args):
+    return ActionRequest(
+        action=args.action,
+        user_request=args.user_request,
+        org_id=args.org_id,
+        application_no=args.application_no,
+        template_id=args.template_id,
+        confirm=args.confirm == "true",
+        buyer_type=args.buyer_type,
+        title=args.title,
+        tax_no=args.tax_no,
+        address_phone=args.address_phone,
+        bank_account=args.bank_account,
+        invoice_type=args.invoice_type,
+        recharge_trans_nos=args.recharge_trans_nos,
+        issuing_mode=args.issuing_mode,
+        save_as_template=args.save_as_template == "true",
+        template_name=args.template_name,
+        use_latest_template=args.use_latest_template == "true",
+    )
+
+
+def dispatch(request, auth_context, client):
+    if request.action == "prepare":
+        return run_prepare(request, auth_context, client)
+    if request.action == "submit":
+        return run_submit(request, auth_context, client)
+    if request.action == "status":
+        return run_status(request, auth_context, client)
+    if request.action == "download":
+        return run_download(request, auth_context, client)
+    if request.action == "update":
+        return run_update(request, auth_context, client)
+    if request.action == "template_list":
+        return run_template_list(request, auth_context, client)
+    if request.action == "template_save":
+        return run_template_save(request, auth_context, client)
+    if request.action == "template_delete":
+        return run_template_delete(request, auth_context, client)
+    return failure(
+        action=request.action,
+        error_code="UNKNOWN_ACTION",
+        error_message="Unknown action: {0}".format(request.action),
+    )
+
+
+def main():
+    args = parse_args()
+    request = build_request(args)
+    auth_context = load_auth_context()
+    client = InvoiceClient(auth_context)
+    result = dispatch(request, auth_context, client)
+    emit_result(result)
+
+
+if __name__ == "__main__":
+    main()

package/skills/sophnet-invoice-assistant/src/scripts/download_flow.py

@@ -0,0 +1,89 @@
+"""Issued invoice download skeleton."""
+
+from __future__ import annotations
+
+from invoice_client import InvoiceClientError
+from output import build_result, failure, need_confirmation
+
+
+def _candidate_summary(items):
+    values = []
+    for item in items[:5]:
+        values.append(
+            "{0}({1})".format(
+                item.get("applicationNo") or "",
+                item.get("title") or item.get("status") or "unknown",
+            )
+        )
+    return "Multiple issued invoices were found. Specify an application number before downloading: {0}".format(", ".join(values))
+
+
+def run_download(request, auth_context, client):
+    if not auth_context.is_authenticated:
+        return failure(
+            action=request.action,
+            error_code="AUTH_CONTEXT_MISSING",
+            error_message="Current Sophnet auth context is missing. Please log in again.",
+        )
+
+    try:
+        org = client.get_current_personal_org(request.org_id)
+        target_application_no = request.application_no
+        if not target_application_no:
+            page = client.list_invoice_applications(
+                org.get("id"),
+                params={"pageNum": 1, "pageSize": 10, "status": "ISSUED"},
+            )
+            items = page.get("list") or [] if isinstance(page, dict) else []
+            if not items:
+                return failure(
+                    action=request.action,
+                    error_code="NO_ISSUED_APPLICATION_FOUND",
+                    error_message="No issued invoice is currently available for download under the personal org.",
+                    extra={"ORG_ID": str(org.get("id"))},
+                )
+            if len(items) > 1:
+                return need_confirmation(
+                    action=request.action,
+                    summary=_candidate_summary(items),
+                    message="Multiple downloadable invoices were found. Please specify an application number.",
+                    extra={
+                        "ORG_ID": str(org.get("id")),
+                        "CANDIDATE_APPLICATION_NOS": ",".join(
+                            [str(item.get("applicationNo") or "") for item in items[:10]]
+                        ),
+                    },
+                )
+            target_application_no = items[0].get("applicationNo")
+
+        if not target_application_no:
+            return failure(
+                action=request.action,
+                error_code="APPLICATION_NO_REQUIRED",
+                error_message="The invoice application number is required before downloading.",
+            )
+
+        file_info = client.download_invoice_file(org.get("id"), target_application_no)
+    except InvoiceClientError as exc:
+        return failure(
+            action=request.action,
+            error_code=exc.code,
+            error_message=exc.message,
+        )
+
+    return build_result(
+        status="succeeded",
+        action=request.action,
+        message="Invoice download details were retrieved successfully.",
+        extra={
+            "ORG_ID": str(org.get("id")),
+            "ORG_NAME": org.get("name") or "",
+            "APPLICATION_NO": file_info.get("applicationNo") or str(target_application_no),
+            "FILE_NAME": file_info.get("fileName") or "",
+            "CONTENT_TYPE": file_info.get("contentType") or "",
+            "FILE_SIZE": str(file_info.get("fileSize") or ""),
+            "PREVIEW_URL": file_info.get("previewUrl") or "",
+            "DOWNLOAD_URL": file_info.get("downloadUrl") or "",
+            "EXPIRES_IN": str(file_info.get("expiresIn") or ""),
+        },
+    )

package/skills/sophnet-invoice-assistant/src/scripts/dto.py

@@ -0,0 +1,46 @@
+"""Data transfer objects for the invoice assistant skeleton."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+
+@dataclass
+class ActionRequest(object):
+    action: str
+    user_request: str
+    org_id: Optional[str] = None
+    application_no: Optional[str] = None
+    template_id: Optional[str] = None
+    confirm: bool = False
+    buyer_type: Optional[str] = None
+    title: Optional[str] = None
+    tax_no: Optional[str] = None
+    address_phone: Optional[str] = None
+    bank_account: Optional[str] = None
+    invoice_type: Optional[str] = None
+    recharge_trans_nos: Optional[str] = None
+    issuing_mode: Optional[str] = None
+    save_as_template: bool = False
+    template_name: Optional[str] = None
+    use_latest_template: bool = False
+
+
+@dataclass
+class AuthContext(object):
+    api_base_url: str
+    access_token: Optional[str]
+    cookie: Optional[str]
+
+    @property
+    def is_authenticated(self) -> bool:
+        return bool(self.access_token or self.cookie)
+
+
+@dataclass
+class ActionResult(object):
+    status: str
+    action: str
+    message: str
+    extra: Optional[Dict[str, str]] = None

package/skills/sophnet-invoice-assistant/src/scripts/invoice_client.py

@@ -0,0 +1,164 @@
+"""Sophnet invoice API client."""
+
+from __future__ import annotations
+
+import requests
+
+
+class InvoiceClientError(RuntimeError):
+    def __init__(self, code, message):
+        super(InvoiceClientError, self).__init__(message)
+        self.code = code
+        self.message = message
+
+
+class InvoiceClient(object):
+    def __init__(self, auth_context):
+        self.auth_context = auth_context
+        self.base_url = auth_context.api_base_url.rstrip("/")
+        self.timeout = 30
+
+    def _headers(self):
+        headers = {
+            "Accept": "application/json",
+        }
+        if self.auth_context.access_token:
+            headers["Authorization"] = "Bearer {0}".format(self.auth_context.access_token.strip())
+        if self.auth_context.cookie:
+            headers["Cookie"] = self.auth_context.cookie.strip()
+        return headers
+
+    def _unwrap_result(self, payload):
+        if not isinstance(payload, dict):
+            return payload
+        status = payload.get("status")
+        if status not in (None, 0):
+            message = payload.get("message") or "Sophnet API returned an error"
+            raise InvoiceClientError("SOPHNET_API_ERROR", message)
+        return payload.get("result")
+
+    def _request(self, method, path, params=None, json_body=None):
+        url = "{0}{1}".format(self.base_url, path)
+        try:
+            response = requests.request(
+                method=method,
+                url=url,
+                headers=self._headers(),
+                params=params,
+                json=json_body,
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise InvoiceClientError("NETWORK_ERROR", "Failed to request Sophnet: {0}".format(exc))
+
+        if response.status_code in (401, 403):
+            raise InvoiceClientError("AUTH_EXPIRED", "Current Sophnet auth has expired. Please log in again.")
+
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = None
+
+        if not response.ok:
+            if isinstance(payload, dict):
+                message = payload.get("message") or payload.get("error") or response.text
+            else:
+                message = response.text
+            raise InvoiceClientError(
+                "HTTP_{0}".format(response.status_code),
+                "Sophnet API request failed: {0}".format((message or "").strip()[:300]),
+            )
+
+        return self._unwrap_result(payload)
+
+    def list_joined_orgs(self):
+        result = self._request(
+            "GET",
+            "/orgs/joined-org",
+            params={"pageNum": 1, "pageSize": 9999},
+        )
+        if not isinstance(result, dict):
+            raise InvoiceClientError("UNEXPECTED_RESPONSE", "joined-org returned an unexpected response shape.")
+        return result
+
+    def get_current_personal_org(self, explicit_org_id=None):
+        page = self.list_joined_orgs()
+        org_list = page.get("list") or []
+        if explicit_org_id is not None:
+            for org in org_list:
+                if str(org.get("id")) == str(explicit_org_id):
+                    if org.get("isSpecificOrg") is True:
+                        return org
+                    raise InvoiceClientError(
+                        "PERSONAL_ORG_REQUIRED",
+                        "The specified org is not a personal org. This skill only supports personal invoice flows.",
+                    )
+            raise InvoiceClientError("ORG_NOT_FOUND", "The specified personal org was not found.")
+
+        for org in org_list:
+            if org.get("isSpecificOrg") is True:
+                return org
+
+        raise InvoiceClientError("PERSONAL_ORG_NOT_FOUND", "No available personal org was found for the current account.")
+
+    def list_invoice_templates(self, org_id):
+        return self._request("GET", "/orgs/{0}/invoices/templates".format(org_id))
+
+    def save_invoice_template(self, org_id, payload):
+        return self._request(
+            "POST",
+            "/orgs/{0}/invoices/templates".format(org_id),
+            json_body=payload,
+        )
+
+    def delete_invoice_template(self, org_id, template_id):
+        return self._request(
+            "DELETE",
+            "/orgs/{0}/invoices/templates/{1}".format(org_id, template_id),
+        )
+
+    def list_invoiceable_recharge_records(self, org_id, params=None):
+        return self._request(
+            "GET",
+            "/orgs/{0}/invoices/recharge-records".format(org_id),
+            params=params or {"pageNum": 1, "pageSize": 20},
+        )
+
+    def create_invoice_application(self, org_id, payload):
+        return self._request(
+            "POST",
+            "/orgs/{0}/invoices/applications".format(org_id),
+            json_body=payload,
+        )
+
+    def update_invoice_application(self, org_id, application_no, payload):
+        return self._request(
+            "PUT",
+            "/orgs/{0}/invoices/applications/{1}".format(org_id, application_no),
+            json_body=payload,
+        )
+
+    def list_invoice_applications(self, org_id, params=None):
+        return self._request(
+            "GET",
+            "/orgs/{0}/invoices/applications".format(org_id),
+            params=params or {},
+        )
+
+    def get_invoice_application(self, org_id, application_no):
+        page = self.list_invoice_applications(
+            org_id,
+            params={"pageNum": 1, "pageSize": 1, "applicationNo": application_no},
+        )
+        if not isinstance(page, dict):
+            raise InvoiceClientError("UNEXPECTED_RESPONSE", "Invoice list API returned an unexpected response shape.")
+        items = page.get("list") or []
+        if not items:
+            raise InvoiceClientError("APPLICATION_NOT_FOUND", "The target invoice application was not found.")
+        return items[0]
+
+    def download_invoice_file(self, org_id, application_no):
+        return self._request(
+            "GET",
+            "/orgs/{0}/invoices/applications/{1}/download".format(org_id, application_no),
+        )

package/skills/sophnet-invoice-assistant/src/scripts/output.py

@@ -0,0 +1,63 @@
+"""Structured output helpers for the invoice assistant skeleton."""
+
+from __future__ import annotations
+
+import json
+
+from dto import ActionResult
+
+
+def build_result(status, action, message, extra=None):
+    return ActionResult(status=status, action=action, message=message, extra=extra or {})
+
+
+def emit_result(result):
+    payload = {
+        "STATUS": result.status,
+        "ACTION": result.action,
+        "MESSAGE": result.message,
+    }
+    payload.update(result.extra or {})
+
+    for key, value in payload.items():
+        if value is None:
+            continue
+        if isinstance(value, (dict, list, tuple)):
+            value = json.dumps(value, ensure_ascii=False)
+        print("{0}={1}".format(key, value))
+
+
+def failure(action, error_code, error_message, extra=None):
+    data = {"ERROR_CODE": error_code, "ERROR_MESSAGE": error_message}
+    if extra:
+        data.update(extra)
+    return build_result(
+        status="failed",
+        action=action,
+        message=error_message,
+        extra=data,
+    )
+
+
+def not_implemented(action, message):
+    return build_result(
+        status="not_implemented",
+        action=action,
+        message=message,
+        extra={"ERROR_CODE": "API_NOT_IMPLEMENTED"},
+    )
+
+
+def need_confirmation(action, summary, message, extra=None):
+    data = {
+        "CONFIRM_REQUIRED": "true",
+        "CONFIRM_SUMMARY": summary,
+    }
+    if extra:
+        data.update(extra)
+    return build_result(
+        status="need_confirmation",
+        action=action,
+        message=message,
+        extra=data,
+    )

package/skills/sophnet-invoice-assistant/src/scripts/prepare_flow.py

@@ -0,0 +1,58 @@
+"""Prepare context for invoice actions."""
+
+from __future__ import annotations
+
+from invoice_client import InvoiceClientError
+from output import build_result, failure
+from submit_flow import INVOICE_ELIGIBLE_START_DATE, _filter_eligible_records
+
+
+def run_prepare(request, auth_context, client):
+    if not auth_context.is_authenticated:
+        return failure(
+            action=request.action,
+            error_code="AUTH_CONTEXT_MISSING",
+            error_message="Current Sophnet auth context is missing. Please log in again.",
+        )
+
+    try:
+        org = client.get_current_personal_org(request.org_id)
+        templates = client.list_invoice_templates(org.get("id")) or []
+        records_page = client.list_invoiceable_recharge_records(
+            org.get("id"),
+            params={"pageNum": 1, "pageSize": 20, "invoiceableOnly": "true"},
+        )
+        applications_page = client.list_invoice_applications(
+            org.get("id"),
+            params={"pageNum": 1, "pageSize": 10},
+        )
+    except InvoiceClientError as exc:
+        return failure(
+            action=request.action,
+            error_code=exc.code,
+            error_message=exc.message,
+        )
+
+    records = records_page.get("list") or [] if isinstance(records_page, dict) else []
+    eligible_records, ineligible_records = _filter_eligible_records(records)
+    applications = applications_page.get("list") or [] if isinstance(applications_page, dict) else []
+
+    return build_result(
+        status="succeeded",
+        action=request.action,
+        message="Resolved the current personal org and loaded invoice context.",
+        extra={
+            "ORG_ID": str(org.get("id")),
+            "ORG_NAME": org.get("name") or "",
+            "IS_SPECIFIC_ORG": str(bool(org.get("isSpecificOrg"))).lower(),
+            "TEMPLATE_COUNT": str(len(templates)),
+            "AVAILABLE_RECHARGE_RECORD_COUNT": str(len(eligible_records)),
+            "INELIGIBLE_RECHARGE_RECORD_COUNT": str(len(ineligible_records)),
+            "INVOICE_ELIGIBLE_START_DATE": INVOICE_ELIGIBLE_START_DATE,
+            "APPLICATION_COUNT": str(len(applications)),
+            "TEMPLATES": templates[:10],
+            "AVAILABLE_RECHARGE_RECORDS": eligible_records[:10],
+            "INELIGIBLE_RECHARGE_RECORDS": ineligible_records[:10],
+            "RECENT_APPLICATIONS": applications[:10],
+        },
+    )