cometapi-cli 0.3.0__tar.gz → 0.3.2__tar.gz

{cometapi_cli-0.3.0 → cometapi_cli-0.3.2}/AGENTS.md

@@ -353,6 +353,8 @@ These options apply to **every** command via the root Typer callback.
 | `--start` | — | `str` | `None` | Start date (`YYYY-MM-DD`, ISO 8601, or Unix timestamp) |
 | `--end` | — | `str` | `None` | End date (`YYYY-MM-DD`, ISO 8601, or Unix timestamp) |
 | `--group` | `-g` | `str` | `None` | Filter by API key group |
+| `--request-id` | — | `str` | `None` | Look up one request by `X-Cometapi-Request-Id` |
+| `--request-id-max-pages` | — | `int` | `10` | Fallback pages to scan when direct request-ID lookup is unavailable |
 | `--page` | `-p` | `int` | `1` | Page number |
 | `--limit` | `-l` | `int` | `20` | Results per page |
 | `--export` | — | flag | `false` | Export logs as server-side CSV to stdout |
@@ -375,6 +377,7 @@ Invalid `--type` values produce an error message with valid options and exit cod
 
 **Behavior:**
 - Without `--search` or `--export`: calls `client.list_logs(page=, page_size=, log_type=, model_name=, token_name=, start_timestamp=, end_timestamp=, group=)` — paginated, `data.items`.
+- With `--request-id`: first calls `client.list_logs(..., request_id=)` and verifies an exact match. If the backend ignores `request_id`, falls back to scanning up to `--request-id-max-pages` pages; timestamp-shaped CometAPI request IDs are narrowed to the inferred local request day unless `--start`/`--end` were provided.
 - With `--search`: calls `client.search_logs(keyword=)` — flat `data` list, ignores other filter flags.
 - With `--export`: calls `client.export_logs(...)` — writes server-side CSV bytes to stdout. Honors `--model`, `--token-name`, `--type`, `--start`, `--end`, `--group`. Pipe-friendly (no Rich formatting).
 

{cometapi_cli-0.3.0 → cometapi_cli-0.3.2}/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] — 2026-06-17
+
+### Fixed
+
+- `logs --request-id` now tries a direct request-ID lookup before falling back to paginated scanning. This avoids treating a precise lookup as an unbounded recent-log scan when the backend supports `request_id` filtering.
+- `logs --request-id` fallback now narrows timestamp-shaped CometAPI request IDs to their inferred local request day, reducing slow scans on large log histories.
+- Account-management requests now use bounded timeouts, so slow log pages fail promptly instead of appearing to hang for several minutes.
+- Missing request-ID messages now explain the direct lookup and bounded fallback scan instead of implying only that the entry is older than the search window.
+- Packaged installs now declare the CLI's direct `click` dependency instead of relying on Typer's transitive dependency metadata.
+
+### Added
+
+- `logs --request-id-max-pages` controls how many fallback pages are scanned when direct request-ID lookup is unavailable.
+
+## [0.3.1] — 2026-05-29
+
+### Fixed
+
+- `logs` now emits a consistent field set across all output formats. Previously `--json` dumped the raw API response (no computed `cost`, `other` left as a stringified blob, internal junk fields), while `table`/`yaml`/`markdown` showed a curated card.
+- `logs --request-id` detail duration now reflects true end-to-end latency (`other.total_ms`) instead of the coarse `use_time` seconds value.
+- `logs --request-id` cost now shows 6 decimal places (e.g. `$0.000384`) so sub-cent calls are no longer rounded to `$0.0004`.
+
+### Changed
+
+- `logs` JSON/YAML output is now a canonical, typed record (raw numbers, booleans, ISO 8601 time, computed `cost_usd`, exploded `other` fields, normalized `model_price`) with a stable schema; `table`/`markdown` render the same fields as formatted strings.
+
 ## [0.3.0] — 2026-05-26
 
 ### Added

{cometapi_cli-0.3.0 → cometapi_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cometapi-cli
-Version: 0.3.0
+Version: 0.3.2
 Summary: CometAPI CLI — official command-line interface for the CometAPI AI gateway
 Project-URL: Homepage, https://pypi.org/project/cometapi-cli/
 Project-URL: Documentation, https://apidoc.cometapi.com/libraries/cli/overview
@@ -21,6 +21,7 @@ Classifier: Topic :: Internet
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
+Requires-Dist: click>=8.0
 Requires-Dist: openai>=1.0.0
 Requires-Dist: prompt-toolkit>=3.0
 Requires-Dist: pyyaml>=6.0
@@ -144,6 +145,21 @@ cometapi run -h
 | `repl` | Start an interactive command shell | Depends on command used |
 | `config` | Show, set, unset, or locate local configuration | None |
 
+## Logs
+
+Use `cometapi logs` to inspect recent usage, export CSV, or look up one request by the
+`X-Cometapi-Request-Id` response header.
+
+```bash
+cometapi logs --limit 20
+cometapi logs --type consume --start 2026-06-01 --json
+cometapi logs --request-id 20260617165550885561292gJBlzjtp
+```
+
+`logs --request-id` first asks the backend for that exact request ID. If the installed
+backend does not support direct request-ID filtering yet, the CLI falls back to scanning
+a bounded number of log pages. Use `--request-id-max-pages` to widen that fallback scan.
+
 ## Models
 
 `cometapi models` uses the public model catalog by default and displays richer metadata than `/v1/models`.

{cometapi_cli-0.3.0 → cometapi_cli-0.3.2}/README.md

@@ -109,6 +109,21 @@ cometapi run -h
 | `repl` | Start an interactive command shell | Depends on command used |
 | `config` | Show, set, unset, or locate local configuration | None |
 
+## Logs
+
+Use `cometapi logs` to inspect recent usage, export CSV, or look up one request by the
+`X-Cometapi-Request-Id` response header.
+
+```bash
+cometapi logs --limit 20
+cometapi logs --type consume --start 2026-06-01 --json
+cometapi logs --request-id 20260617165550885561292gJBlzjtp
+```
+
+`logs --request-id` first asks the backend for that exact request ID. If the installed
+backend does not support direct request-ID filtering yet, the CLI falls back to scanning
+a bounded number of log pages. Use `--request-id-max-pages` to widen that fallback scan.
+
 ## Models
 
 `cometapi models` uses the public model catalog by default and displays richer metadata than `/v1/models`.

{cometapi_cli-0.3.0 → cometapi_cli-0.3.2}/docs/commands/logs.md

@@ -18,6 +18,7 @@ cometapi logs [OPTIONS]
 | `--end` | — | string | — | End date (see [Date Formats](#date-formats)) |
 | `--group` | `-g` | string | — | Filter by API key group |
 | `--request-id` | — | string | — | Look up cost by request ID (from `X-Cometapi-Request-Id` header) |
+| `--request-id-max-pages` | — | int | `10` | Fallback pages to scan when direct request-ID lookup is unavailable |
 | `--detail` | — | flag | `false` | Show extended columns (request ID, pricing ratios) |
 | `--page` | `-p` | int | `1` | Page number |
 | `--limit` | `-l` | int | `20` | Results per page |
@@ -102,7 +103,10 @@ Internal quota values are converted to USD:
 $1.00 USD = 500,000 quota units
 ```
 
-Cost is displayed with 4 decimal places (e.g., `$0.0014`).
+In the logs list, cost is displayed with 4 decimal places (e.g., `$0.0014`). The
+per-request detail view (`--request-id`) uses 6 decimal places (e.g., `$0.000384`)
+so sub-cent calls are not rounded away, and machine formats expose the raw
+`cost_usd` float.
 
 ## CSV Export
 
@@ -160,27 +164,95 @@ cometapi logs --request-id req-abc-123
 cometapi logs --request-id req-abc-123 --json
 ```
 
-Output shows a cost summary card:
+Lookup behavior:
 
+1. The CLI first asks the backend for `request_id=req-abc-123` and accepts only an exact
+   `request_id` match.
+2. If the backend does not return an exact match, the CLI falls back to scanning recent
+   log pages. Timestamp-shaped CometAPI request IDs are narrowed to the inferred local
+   request day unless you provide `--start` or `--end`.
+3. The fallback scan is bounded by `--request-id-max-pages` (default: `10`) so a slow log
+   endpoint does not appear to hang indefinitely.
+
+```bash
+# Widen fallback scanning when direct lookup is unavailable
+cometapi logs --request-id req-abc-123 --request-id-max-pages 25
 ```
-                   Request Cost
-┌──────────────┬──────────────────────────┐
-│ Field        │ Value                    │
-├──────────────┼──────────────────────────┤
-│ Request Id   │ req-abc-123              │
-│ Cost         │ $0.0034                  │
-│ Quota (raw)  │ 1,700                    │
-│ RPM          │ 1                        │
-│ TPM          │ 165                      │
-└──────────────┴──────────────────────────┘
+
+Output shows a request detail card:
+
 ```
+                         Request Detail
+┌───────────────────┬──────────────────────────────────────────┐
+│ Field             │ Value                                      │
+├───────────────────┼──────────────────────────────────────────┤
+│ Request ID        │ req-abc-123                                │
+│ Response ID       │ chatcmpl-xyz-789                           │
+│ Time              │ 2026-05-29 06:00:21                        │
+│ Model             │ gpt-5.4                                    │
+│ Token Name        │ Production Key                             │
+│ Type              │ consume                                    │
+│ Stream            │ No                                         │
+│ Prompt Tokens     │ 18                                         │
+│ Completion Tokens │ 13                                         │
+│ Cost (USD)        │ $0.000384                                  │
+│ Quota (raw)       │ 192                                        │
+│ Model Ratio       │ 2.5                                        │
+│ Completion Ratio  │ 6x                                         │
+│ Group Ratio       │ 0.8                                        │
+│ Model Price       │ default                                    │
+│ Duration          │ 3,128 ms                                   │
+│ Endpoint          │ /v1/chat/completions                       │
+└───────────────────┴──────────────────────────────────────────┘
+```
+
+### Unified output schema
+
+All formats expose the **same field set** — the difference is only presentation:
 
-JSON output returns the raw stat data:
+- `table` / `markdown` — human-friendly labels and formatted strings (`$0.000384`, `Yes`/`No`, `6x`, `3,128 ms`); optional fields are omitted when absent.
+- `json` / `yaml` / `csv` — the canonical record with **raw typed values** (numbers, booleans, ISO 8601 time) and a stable schema (`null` when a value is absent), suitable for scripting.
+
+```bash
+cometapi logs --request-id req-abc-123 -f json
+```
 
 ```json
-{"quota": 1700, "rpm": 1, "tpm": 165}
+{
+  "request_id": "req-abc-123",
+  "response_id": "chatcmpl-xyz-789",
+  "time": "2026-05-29T06:00:21+00:00",
+  "type": "consume",
+  "model": "gpt-5.4",
+  "token_name": "Production Key",
+  "username": "google_9550",
+  "user_id": 9550,
+  "ip": "203.0.113.7",
+  "stream": false,
+  "prompt_tokens": 18,
+  "completion_tokens": 13,
+  "cache_tokens": 0,
+  "cost_usd": 0.000384,
+  "quota": 192,
+  "model_ratio": 2.5,
+  "completion_ratio": 6,
+  "group_ratio": 0.8,
+  "model_price": null,
+  "cache_ratio": 0.1,
+  "duration_ms": 3128,
+  "first_token_ms": null,
+  "endpoint": "/v1/chat/completions"
+}
 ```
 
+Notes:
+
+- `cost_usd` is `quota / 500000`, rounded to 6 decimals (matches the backend). In the `table`/`markdown` card it is shown as `$0.000384` so sub-cent calls are not rounded away.
+- `duration_ms` uses the request's true end-to-end latency (`other.total_ms`); it falls back to the coarse `use_time` value only when `total_ms` is unavailable.
+- `model_price` is `null` when the backend uses ratio-based pricing (the `-1` sentinel); the `table`/`markdown` card renders this as `default`.
+- `time` is ISO 8601 UTC in machine formats; the card renders `YYYY-MM-DD HH:MM:SS`.
+- `ip` is the client IP recorded by the backend — treat it as sensitive when sharing logs.
+
 You can combine `--request-id` with filter options like `--type` and `--model` for additional precision. `--request-id` cannot be used with `--export`.
 
 > **Note:** The upstream provider's response ID (e.g., `chatcmpl-DSfol...` from OpenAI) is NOT stored

{cometapi_cli-0.3.0 → cometapi_cli-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cometapi-cli"
-version = "0.3.0"
+version = "0.3.2"
 description = "CometAPI CLI — official command-line interface for the CometAPI AI gateway"
 readme = "README.md"
 license = { text = "MIT" }
@@ -24,6 +24,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
+    "click>=8.0",
     "openai>=1.0.0",
     "typer>=0.12",
     "rich>=13.0",

{cometapi_cli-0.3.0 → cometapi_cli-0.3.2}/src/cometapi_cli/__init__.py

@@ -1,3 +1,3 @@
 """CometAPI CLI — professional terminal interface for CometAPI."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"

{cometapi_cli-0.3.0 → cometapi_cli-0.3.2}/src/cometapi_cli/client.py

@@ -9,6 +9,8 @@ import openai
 
 COMETAPI_BASE_URL = "https://api.cometapi.com/v1"
 COMETAPI_DASHBOARD_BASE = "https://api.cometapi.com"
+ACCOUNT_REQUEST_TIMEOUT = 30.0
+ACCOUNT_EXPORT_TIMEOUT = 120.0
 
 
 class CometClient(openai.OpenAI):
@@ -44,7 +46,14 @@ class CometClient(openai.OpenAI):
 
     # -- Account management (access-token auth) --------------------------------
 
-    def _account_request(self, method: str, path: str, *, params: dict | None = None) -> dict:
+    def _account_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict | None = None,
+        timeout: float = ACCOUNT_REQUEST_TIMEOUT,
+    ) -> dict:
         """Make an authenticated request to a CometAPI account endpoint."""
         if not self._access_token:
             raise openai.OpenAIError(
@@ -56,6 +65,7 @@ class CometClient(openai.OpenAI):
             f"{COMETAPI_DASHBOARD_BASE}{path}",
             headers={"Authorization": f"Bearer {self._access_token}"},
             params=params,
+            timeout=timeout,
         )
         response.raise_for_status()
         return response.json()
@@ -151,6 +161,7 @@ class CometClient(openai.OpenAI):
         start_timestamp: int | None = None,
         end_timestamp: int | None = None,
         group: str | None = None,
+        request_id: str | None = None,
     ) -> dict:
         """List the user's usage logs (requires access token)."""
         params: dict[str, Any] = {"p": page, "page_size": page_size}
@@ -166,6 +177,8 @@ class CometClient(openai.OpenAI):
             params["end_timestamp"] = end_timestamp
         if group:
             params["group"] = group
+        if request_id:
+            params["request_id"] = request_id
         return self._account_request("GET", "/api/log/self", params=params)
 
     def search_logs(self, keyword: str) -> dict:
@@ -235,6 +248,7 @@ class CometClient(openai.OpenAI):
             f"{COMETAPI_DASHBOARD_BASE}/api/log/self/export",
             headers={"Authorization": f"Bearer {self._access_token}"},
             params=params,
+            timeout=ACCOUNT_EXPORT_TIMEOUT,
         )
         response.raise_for_status()
         return response.content