@mongoui/skills 0.1.8 → 0.2.0

package/skills/glink-hotel-api/scripts/glink_signed_request.py

@@ -1,199 +1,199 @@
-#!/usr/bin/env python3
-"""Generate or send signed requests for the Glink open-platform gateway.
-
-Examples:
-  python scripts/glink_signed_request.py ^
-    --method POST ^
-    --path /region/businesses ^
-    --body-json "{\"language\":\"zh-CN\",\"cityCode\":\"1\"}" ^
-    --app-key open_app_xxx ^
-    --app-secret sk_xxx
-
-  python scripts/glink_signed_request.py ^
-    --method POST ^
-    --path /search/creditBalance ^
-    --body-json "{}" ^
-    --app-key open_app_xxx ^
-    --app-secret sk_xxx ^
-    --send
-"""
-
-from __future__ import annotations
-
-import argparse
-import hashlib
-import hmac
-import json
-import os
-import sys
-import time
-import urllib.parse
-import urllib.request
-import uuid
-from pathlib import Path
-
-GATEWAY_PREFIX = "/openapi/v1/glink"
-
-
-def sha256_hex(data: bytes) -> str:
-    return hashlib.sha256(data).hexdigest()
-
-
-def normalize_path(path: str) -> str:
-    if not path.startswith("/"):
-        path = f"/{path}"
-    if path == GATEWAY_PREFIX or path.startswith(f"{GATEWAY_PREFIX}/"):
-        return path
-    return f"{GATEWAY_PREFIX}{path}"
-
-
-def parse_query_items(items: list[str]) -> list[tuple[str, str]]:
-    pairs: list[tuple[str, str]] = []
-    for item in items:
-        if "=" not in item:
-            raise ValueError(f"invalid query item: {item!r}; expected key=value")
-        key, value = item.split("=", 1)
-        pairs.append((key, value))
-    return pairs
-
-
-def canonical_query(pairs: list[tuple[str, str]]) -> str:
-    ordered = sorted(pairs, key=lambda item: (item[0], item[1]))
-    return "&".join(
-        f"{urllib.parse.quote(key, safe='~-._')}={urllib.parse.quote(value, safe='~-._')}"
-        for key, value in ordered
-    )
-
-
-def build_sign_payload(
-    method: str,
-    path: str,
-    query_string: str,
-    body_bytes: bytes,
-    timestamp: str,
-    nonce: str,
-    app_key: str,
-) -> str:
-    return "\n".join(
-        [
-            method.upper(),
-            path,
-            query_string,
-            sha256_hex(body_bytes),
-            timestamp,
-            nonce,
-            app_key,
-        ]
-    )
-
-
-def sign(secret: str, payload: str) -> str:
-    return hmac.new(secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).hexdigest()
-
-
-def load_body(args: argparse.Namespace) -> bytes:
-    if args.body_file:
-        return Path(args.body_file).read_bytes()
-    if args.body_json is None:
-        return b""
-    parsed = json.loads(args.body_json)
-    return json.dumps(parsed, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
-
-
-def build_url(base_url: str, path: str, query_string: str) -> str:
-    base = base_url.rstrip("/")
-    url = f"{base}{path}"
-    if query_string:
-        url = f"{url}?{query_string}"
-    return url
-
-
-def build_headers(app_key: str, timestamp: str, nonce: str, signature: str, has_body: bool) -> dict[str, str]:
-    headers = {
-        "Accept": "application/json",
-        "X-OP-App-Key": app_key,
-        "X-OP-Timestamp": timestamp,
-        "X-OP-Nonce": nonce,
-        "X-OP-Sign": signature,
-    }
-    if has_body:
-        headers["Content-Type"] = "application/json"
-    return headers
-
-
-def send_request(method: str, url: str, headers: dict[str, str], body_bytes: bytes, timeout: float) -> tuple[int, str]:
-    request = urllib.request.Request(url=url, data=body_bytes or None, headers=headers, method=method.upper())
-    try:
-        with urllib.request.urlopen(request, timeout=timeout) as response:
-            return response.status, response.read().decode("utf-8", errors="replace")
-    except urllib.error.HTTPError as exc:
-        return exc.code, exc.read().decode("utf-8", errors="replace")
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description="Generate or send a signed Glink open-platform request.")
-    parser.add_argument("--base-url", default=os.getenv("OPEN_PLATFORM_BASE_URL", "http://127.0.0.1:8671"))
-    parser.add_argument("--method", required=True)
-    parser.add_argument("--path", required=True, help="Short interface path, such as /search/destination; full gateway paths are also accepted")
-    parser.add_argument("--query", action="append", default=[], help="Repeatable key=value query parameter")
-    parser.add_argument("--body-json", help="JSON string request body")
-    parser.add_argument("--body-file", help="Path to a raw request body file")
-    parser.add_argument("--app-key", default=os.getenv("OPEN_PLATFORM_APP_KEY") or os.getenv("OPEN_PLATFORM_OPEN_APP_ID"))
-    parser.add_argument("--app-secret", default=os.getenv("OPEN_PLATFORM_APP_SECRET") or os.getenv("OPEN_PLATFORM_OPEN_SECRET"))
-    parser.add_argument("--timestamp", default=str(int(time.time())))
-    parser.add_argument("--nonce", default=uuid.uuid4().hex)
-    parser.add_argument("--send", action="store_true")
-    parser.add_argument("--timeout", type=float, default=15.0)
-    args = parser.parse_args()
-
-    if not args.app_key or not args.app_secret:
-        print("app key and app secret are required", file=sys.stderr)
-        return 2
-
-    try:
-        query_pairs = parse_query_items(args.query)
-        body_bytes = load_body(args)
-        runtime_path = normalize_path(args.path)
-    except Exception as exc:
-        print(str(exc), file=sys.stderr)
-        return 2
-
-    query_string = canonical_query(query_pairs)
-    payload = build_sign_payload(
-        method=args.method,
-        path=runtime_path,
-        query_string=query_string,
-        body_bytes=body_bytes,
-        timestamp=args.timestamp,
-        nonce=args.nonce,
-        app_key=args.app_key,
-    )
-    signature = sign(args.app_secret, payload)
-    headers = build_headers(args.app_key, args.timestamp, args.nonce, signature, bool(body_bytes))
-    url = build_url(args.base_url, runtime_path, query_string)
-
-    print("URL:")
-    print(url)
-    print()
-    print("Canonical String:")
-    print(payload)
-    print()
-    print("Headers:")
-    print(json.dumps(headers, ensure_ascii=False, indent=2))
-    if body_bytes:
-        print()
-        print("Body:")
-        print(body_bytes.decode("utf-8", errors="replace"))
-
-    if not args.send:
-        return 0
-
-    status, response_text = send_request(args.method, url, headers, body_bytes, args.timeout)
-    print()
-    print(f"HTTP {status}")
-    print(response_text)
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+#!/usr/bin/env python3
+"""Generate or send signed requests for the Glink open-platform gateway.
+
+Examples:
+  python scripts/glink_signed_request.py ^
+    --method POST ^
+    --path /region/businesses ^
+    --body-json "{\"language\":\"zh-CN\",\"cityCode\":\"1\"}" ^
+    --app-key open_app_xxx ^
+    --app-secret sk_xxx
+
+  python scripts/glink_signed_request.py ^
+    --method POST ^
+    --path /search/creditBalance ^
+    --body-json "{}" ^
+    --app-key open_app_xxx ^
+    --app-secret sk_xxx ^
+    --send
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import hmac
+import json
+import os
+import sys
+import time
+import urllib.parse
+import urllib.request
+import uuid
+from pathlib import Path
+
+GATEWAY_PREFIX = "/openapi/v1/glink"
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def normalize_path(path: str) -> str:
+    if not path.startswith("/"):
+        path = f"/{path}"
+    if path == GATEWAY_PREFIX or path.startswith(f"{GATEWAY_PREFIX}/"):
+        return path
+    return f"{GATEWAY_PREFIX}{path}"
+
+
+def parse_query_items(items: list[str]) -> list[tuple[str, str]]:
+    pairs: list[tuple[str, str]] = []
+    for item in items:
+        if "=" not in item:
+            raise ValueError(f"invalid query item: {item!r}; expected key=value")
+        key, value = item.split("=", 1)
+        pairs.append((key, value))
+    return pairs
+
+
+def canonical_query(pairs: list[tuple[str, str]]) -> str:
+    ordered = sorted(pairs, key=lambda item: (item[0], item[1]))
+    return "&".join(
+        f"{urllib.parse.quote(key, safe='~-._')}={urllib.parse.quote(value, safe='~-._')}"
+        for key, value in ordered
+    )
+
+
+def build_sign_payload(
+    method: str,
+    path: str,
+    query_string: str,
+    body_bytes: bytes,
+    timestamp: str,
+    nonce: str,
+    app_key: str,
+) -> str:
+    return "\n".join(
+        [
+            method.upper(),
+            path,
+            query_string,
+            sha256_hex(body_bytes),
+            timestamp,
+            nonce,
+            app_key,
+        ]
+    )
+
+
+def sign(secret: str, payload: str) -> str:
+    return hmac.new(secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+def load_body(args: argparse.Namespace) -> bytes:
+    if args.body_file:
+        return Path(args.body_file).read_bytes()
+    if args.body_json is None:
+        return b""
+    parsed = json.loads(args.body_json)
+    return json.dumps(parsed, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+
+
+def build_url(base_url: str, path: str, query_string: str) -> str:
+    base = base_url.rstrip("/")
+    url = f"{base}{path}"
+    if query_string:
+        url = f"{url}?{query_string}"
+    return url
+
+
+def build_headers(app_key: str, timestamp: str, nonce: str, signature: str, has_body: bool) -> dict[str, str]:
+    headers = {
+        "Accept": "application/json",
+        "X-OP-App-Key": app_key,
+        "X-OP-Timestamp": timestamp,
+        "X-OP-Nonce": nonce,
+        "X-OP-Sign": signature,
+    }
+    if has_body:
+        headers["Content-Type"] = "application/json"
+    return headers
+
+
+def send_request(method: str, url: str, headers: dict[str, str], body_bytes: bytes, timeout: float) -> tuple[int, str]:
+    request = urllib.request.Request(url=url, data=body_bytes or None, headers=headers, method=method.upper())
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return response.status, response.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as exc:
+        return exc.code, exc.read().decode("utf-8", errors="replace")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate or send a signed Glink open-platform request.")
+    parser.add_argument("--base-url", default=os.getenv("OPEN_PLATFORM_BASE_URL", "http://127.0.0.1:8671"))
+    parser.add_argument("--method", required=True)
+    parser.add_argument("--path", required=True, help="Short interface path, such as /search/destination; full gateway paths are also accepted")
+    parser.add_argument("--query", action="append", default=[], help="Repeatable key=value query parameter")
+    parser.add_argument("--body-json", help="JSON string request body")
+    parser.add_argument("--body-file", help="Path to a raw request body file")
+    parser.add_argument("--app-key", default=os.getenv("OPEN_PLATFORM_APP_KEY") or os.getenv("OPEN_PLATFORM_OPEN_APP_ID"))
+    parser.add_argument("--app-secret", default=os.getenv("OPEN_PLATFORM_APP_SECRET") or os.getenv("OPEN_PLATFORM_OPEN_SECRET"))
+    parser.add_argument("--timestamp", default=str(int(time.time())))
+    parser.add_argument("--nonce", default=uuid.uuid4().hex)
+    parser.add_argument("--send", action="store_true")
+    parser.add_argument("--timeout", type=float, default=15.0)
+    args = parser.parse_args()
+
+    if not args.app_key or not args.app_secret:
+        print("app key and app secret are required", file=sys.stderr)
+        return 2
+
+    try:
+        query_pairs = parse_query_items(args.query)
+        body_bytes = load_body(args)
+        runtime_path = normalize_path(args.path)
+    except Exception as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+    query_string = canonical_query(query_pairs)
+    payload = build_sign_payload(
+        method=args.method,
+        path=runtime_path,
+        query_string=query_string,
+        body_bytes=body_bytes,
+        timestamp=args.timestamp,
+        nonce=args.nonce,
+        app_key=args.app_key,
+    )
+    signature = sign(args.app_secret, payload)
+    headers = build_headers(args.app_key, args.timestamp, args.nonce, signature, bool(body_bytes))
+    url = build_url(args.base_url, runtime_path, query_string)
+
+    print("URL:")
+    print(url)
+    print()
+    print("Canonical String:")
+    print(payload)
+    print()
+    print("Headers:")
+    print(json.dumps(headers, ensure_ascii=False, indent=2))
+    if body_bytes:
+        print()
+        print("Body:")
+        print(body_bytes.decode("utf-8", errors="replace"))
+
+    if not args.send:
+        return 0
+
+    status, response_text = send_request(args.method, url, headers, body_bytes, args.timeout)
+    print()
+    print(f"HTTP {status}")
+    print(response_text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/tmc-api/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: tmc-api
+description: Work with the TMC white-label OpenAPI exposed through the Open Platform runtime gateway. Use when Codex needs to read, verify, explain, test, document, or implement against `docs/swagger/tmc-api.json`; choose exact TMC endpoints; include complete request/response fields and types; generate customer-facing TMC onboarding, organization, employee, traveler, approval, travel policy, flight, hotel, payment, attachment, certificate, webhook, and aftersale workflows; or debug Open Platform signing, `token`, sandbox, and production TMC calls.
+---
+
+# TMC API
+
+## Quick Start
+
+Use this skill when the task is about TMC white-label OpenAPI integration, customer-facing workflow explanation, interface field lookup, signed requests, or implementation against the Open Platform TMC gateway.
+
+Start from the smallest reference that answers the request:
+
+- Read `references/endpoint-index.md` for the complete 94-operation endpoint map.
+- Read `references/endpoint-details.md` when the answer must include exact request parameters, request body fields, response fields, nested types, examples, or webhook payload fields.
+- Read `references/api-workflows.md` when the user asks for customer process, interaction flow, or test-case-aligned business coverage. It maps the extracted 224 Listify test cases to concrete interfaces.
+- Read `references/auth-and-calling.md` for Open Platform signature rules, runtime path prefixing, token handling, and call validation.
+- Use `scripts/tmc_signed_request.py` to generate headers, inspect the canonical signing string, or send a signed local/sandbox request.
+
+## Source Of Truth
+
+- Current English swagger: `open-platform-go/docs/swagger/tmc-api.en-US.json`.
+- Simplified Chinese swagger: `open-platform-go/docs/swagger/tmc-api.json`; use it only when the user specifically needs Chinese wording.
+- Customer-facing short paths omit `/openapi/v1/tmc`, for example `/flight/search`.
+- Signing and actual gateway calls must use the full runtime path, for example `/openapi/v1/tmc/flight/search`.
+- The Listify test-case page is Chinese flow evidence, not an interface specification. Preserve source case IDs for traceability, but explain customer workflows in English unless the user asks for Chinese.
+
+## Working Rules
+
+Follow this workflow:
+
+1. Confirm whether the user needs customer documentation, exact field tables, code changes, signed request debugging, or live/local API calls.
+2. Choose the flow area first: identity/org/employee/traveler, approval, travel policy, flight booking, flight aftersale, hotel booking, hotel aftersale, payment, attachments, certificates, or webhook callbacks.
+3. Use `references/api-workflows.md` to connect the business scenario or test case to concrete endpoint paths.
+4. Use `references/endpoint-details.md` for all payload details; do not invent request or response fields.
+5. For signed calls, use `/openapi/v1/tmc` in the canonical path and include `X-OP-App-Key`, `X-OP-Timestamp`, `X-OP-Nonce`, and `X-OP-Sign`.
+6. Call `/auth/token` with `externalUserId` first, then pass the returned TMC `token` header on business APIs.
+7. Evaluate both HTTP status and response envelope `code`; non-zero business `code` is a business failure even when HTTP is 200.
+
+## Common Flow Skeletons
+
+- Identity and enterprise context: `/auth/token` -> `/departments` -> `/employees` or `/employees/{userId}`.
+- Organization and staff setup: `/departments` -> `/email-domains` -> `/employees` -> `/employees/{userId}` -> certificate APIs when needed.
+- Traveler setup: `/guests/add` -> `/guests` -> `/guests/{id}` -> guest certificate APIs.
+- Approval setup: `/approval-policies` -> `/approval-policies/page` -> `/approval-policies/{policyId}` -> `/approvals/page` -> `/approvals/{approvalNo}` -> `/approvals/audit` or `/approvals/resubmit`.
+- Travel policy setup: hotel and flight policy CRUD/page/enable APIs -> `/travel-policies/users/{employeeId}`.
+- Flight booking: dictionary APIs -> `/booking-users/list` -> `/flight/search` -> `/flight/cabin` -> `/flight/verify` -> `/flight/order/init` -> `/flight/order/policy-check` -> `/flight/order` -> `/payments/payOrder` -> `/flight/orders/{orderCode}`.
+- Flight aftersale: `/flight/aftersale/capability` -> refund or change remaining-query APIs -> apply/detail/confirm-or-cancel APIs.
+- Hotel booking: `/hotel/locations` -> `/hotel/search/filters` -> `/hotel/search` -> `/hotel/{hotelId}` -> `/hotel/products/search` -> `/hotel/check-booking` -> `/hotel/order/policy-check` -> `/hotel/order` -> `/payments/payOrder` -> `/hotel/orders/{orderCode}`.
+- Hotel early checkout: `/hotel/early-checkout/can-apply` -> `/hotel/early-checkout/apply` -> `/hotel/early-checkout/detail`.
+- Attachments: `/attachments/upload` and `/attachments/download`.
+- Webhooks: read the webhook section in `references/endpoint-details.md`; treat callbacks as customer interaction surface even though they are not part of the 94 request operations.
+
+## Output Expectations
+
+When answering with this skill:
+
+- Use concrete method + path pairs, not only abstract process names.
+- Include field names, types, required flags, and nested structures from `endpoint-details.md` when the user asks for parameters.
+- Mention whether a path is a customer-facing short path or a signed runtime path when auth/signing is relevant.
+- Keep test-case-derived process descriptions tied to exact interfaces.
+- State the source used when swagger, local code, and extracted test cases disagree.
+- Never expose or invent credentials, app secrets, tokens, or tenant data.

package/skills/tmc-api/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TMC API Integration"
+  short_description: "TMC white-label OpenAPI auth, fields, workflows, and debugging"
+  default_prompt: "Use $tmc-api to explain or implement TMC OpenAPI authentication, endpoint selection, request/response fields, and customer workflows."