hookstride-cli 0.2.1__tar.gz → 0.3.1__tar.gz

hookstride_cli-0.3.1/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.5
+Name: hookstride-cli
+Version: 0.3.1
+Summary: Manage Hookstride projects and destinations, inspect webhook activity and billing.
+License: Proprietary
+Requires-Python: >=3.11
+Requires-Dist: click<9,>=8.1
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: prompt-toolkit<4,>=3.0.52
+Requires-Dist: rich<15,>=14
+Requires-Dist: typer<1,>=0.20
+Description-Content-Type: text/markdown
+
+# Hookstride CLI
+
+Hookstride CLI lets you manage projects and webhook destinations, inspect delivery activity, and view billing records. It includes an interactive console with the same selected-project commands.
+
+Version 0.3.1 adds signed test-event sending with an existing project's delivery API key, and optional delivery-status polling. Project and destination management remain available; billing and credential changes, delivery replay, and destructive operations remain unavailable.
+
+## Installation
+
+
+Requires Python 3.11 or later.
+
+```bash
+uv tool install hookstride-cli
+```
+
+Alternatively, use `pipx install hookstride-cli`.
+
+```bash
+hookstride --version
+hookstride status
+hookstride console
+```
+
+Upgrade an existing installation with `uv tool upgrade hookstride-cli`.
+
+## Authentication
+
+Authenticated commands require a **Control API token** (`whrctl_`), available from your Hookstride dashboard. Project delivery API keys (`whrk_`) do not grant CLI access.
+
+In an interactive console, run `auth login` and enter the token at the hidden prompt:
+
+```bash
+hookstride console
+```
+
+For one-off commands, set `HOOKSTRIDE_CONTROL_TOKEN` in your shell without entering it on the command line:
+
+```bash
+read -rs "HOOKSTRIDE_CONTROL_TOKEN?Control token: "
+echo
+export HOOKSTRIDE_CONTROL_TOKEN
+hookstride auth status
+```
+
+The `read` example above works in **zsh**. In Bash, use `read -rs -p "Control token: " HOOKSTRIDE_CONTROL_TOKEN` followed by `echo` and `export HOOKSTRIDE_CONTROL_TOKEN`.
+
+Tokens entered through `auth login` are retained only for the interactive console session. The CLI does not write tokens to its settings file.
+
+## Commands
+
+```bash
+hookstride status
+hookstride auth status
+hookstride projects list
+hookstride projects use PROJECT_UUID
+hookstride projects create --account ACCOUNT_UUID --name "Staging" --slug staging
+hookstride projects update PROJECT_UUID --name "Production EU"
+
+hookstride destinations list
+hookstride destinations create --name "Webhook receiver" --url "https://app.example.com/webhooks/hookstride"
+hookstride destinations update DESTINATION_UUID --url "https://api.example.com/webhooks/hookstride"
+hookstride destinations update DESTINATION_UUID --pause
+hookstride destinations update DESTINATION_UUID --resume
+hookstride keys list
+hookstride events list --status failed
+hookstride events show EVENT_UUID
+hookstride events send DESTINATION_UUID --type webhook.test --wait
+hookstride stats
+
+hookstride incoming sources
+hookstride incoming routes
+hookstride incoming bindings
+hookstride incoming registration-keys
+
+hookstride billing status
+hookstride billing history
+hookstride config show
+```
+
+Replace the example UUIDs with identifiers from your account. Find your workspace's `account_id` with `hookstride --json projects list`; that ID is required for project creation. Project creation and renaming require an admin/owner role. Destination changes require developer access or higher.
+
+Commands that operate on a project use the selected project. You can override the selection for an individual command:
+
+```bash
+hookstride --project PROJECT_UUID events list
+```
+
+### Interactive console
+
+```bash
+hookstride console
+```
+
+Use `help` to view commands, Tab for completion, and `exit` or Ctrl+D to leave. The console also supports `show projects`, `show events`, `show destinations`, `use PROJECT_UUID`, `back`, and `set env dev|production`. The same `projects create/update`, `destinations create/update`, and `events send` commands work inside the console. Commands with customer-provided names and URLs are not saved to console history.
+
+### JSON output
+
+Use `--json` before a command to retrieve structured data for scripts:
+
+```bash
+hookstride --json projects list
+hookstride --project PROJECT_UUID --json events list --status failed
+hookstride --env production --json billing history
+```
+
+Errors go to standard error; unsuccessful requests return a nonzero exit code. When creating a destination, the server returns a signing secret **once**. Save it securely immediately. Both terminal output and `--json` deliberately include that one-time secret, so avoid piping creation output into logs or public CI artifacts.
+
+### Send a test event
+
+Use an existing active destination from `hookstride destinations list`.
+The command securely prompts for a project delivery API key (`whrk_`). It cannot use a
+Control API token (`whrctl_`); these credentials have different permissions.
+
+```bash
+hookstride --env production projects use PROJECT_UUID
+hookstride --env production events send DESTINATION_UUID --wait
+hookstride --env production events show EVENT_UUID
+```
+
+The event type defaults to `webhook.test`, with a harmless JSON payload:
+`{"message":"Hookstride CLI delivery test","source":"cli"}`.
+To send a different JSON object without placing its contents in shell history:
+
+```bash
+hookstride --env production events send DESTINATION_UUID --type demo.delivery --payload-file ./demo-payload.json --wait
+```
+
+To avoid the hidden prompt, set `HOOKSTRIDE_PRODUCTION_API_KEY` or
+`HOOKSTRIDE_DEV_API_KEY` for the matching environment only.
+Never add keys to CLI arguments, commit them to Git, or paste them into a public CI log.
+The CLI does not save delivery keys or their prompts in its configuration or history.
+The `--wait` flag polls for a terminal status and exits nonzero if delivery fails.
+A non-delivered event can be examined using `events show` with the usual Control token.
+
+## Environments and local settings
+
+The CLI connects to the production API by default: `https://api.hookstride.com`.
+A new release must be published to PyPI before existing installations receive this change.
+
+To inspect the development API explicitly, select it:
+
+```bash
+hookstride --env dev console
+```
+
+Development requests use `https://api-dev.hookstride.com`. Use a Control API token issued for the selected environment. A custom HTTPS API origin can be supplied with `--api-url`.
+
+Project selections are stored separately by environment in `~/.config/hookstride/settings.json`. This file contains project identifiers, **not authentication tokens**. Console tokens and command history remain in memory and are discarded at exit.
+
+## Documentation
+
+Documentation: https://hookstride.com

hookstride_cli-0.3.1/README.md

@@ -0,0 +1,152 @@
+# Hookstride CLI
+
+Hookstride CLI lets you manage projects and webhook destinations, inspect delivery activity, and view billing records. It includes an interactive console with the same selected-project commands.
+
+Version 0.3.1 adds signed test-event sending with an existing project's delivery API key, and optional delivery-status polling. Project and destination management remain available; billing and credential changes, delivery replay, and destructive operations remain unavailable.
+
+## Installation
+
+
+Requires Python 3.11 or later.
+
+```bash
+uv tool install hookstride-cli
+```
+
+Alternatively, use `pipx install hookstride-cli`.
+
+```bash
+hookstride --version
+hookstride status
+hookstride console
+```
+
+Upgrade an existing installation with `uv tool upgrade hookstride-cli`.
+
+## Authentication
+
+Authenticated commands require a **Control API token** (`whrctl_`), available from your Hookstride dashboard. Project delivery API keys (`whrk_`) do not grant CLI access.
+
+In an interactive console, run `auth login` and enter the token at the hidden prompt:
+
+```bash
+hookstride console
+```
+
+For one-off commands, set `HOOKSTRIDE_CONTROL_TOKEN` in your shell without entering it on the command line:
+
+```bash
+read -rs "HOOKSTRIDE_CONTROL_TOKEN?Control token: "
+echo
+export HOOKSTRIDE_CONTROL_TOKEN
+hookstride auth status
+```
+
+The `read` example above works in **zsh**. In Bash, use `read -rs -p "Control token: " HOOKSTRIDE_CONTROL_TOKEN` followed by `echo` and `export HOOKSTRIDE_CONTROL_TOKEN`.
+
+Tokens entered through `auth login` are retained only for the interactive console session. The CLI does not write tokens to its settings file.
+
+## Commands
+
+```bash
+hookstride status
+hookstride auth status
+hookstride projects list
+hookstride projects use PROJECT_UUID
+hookstride projects create --account ACCOUNT_UUID --name "Staging" --slug staging
+hookstride projects update PROJECT_UUID --name "Production EU"
+
+hookstride destinations list
+hookstride destinations create --name "Webhook receiver" --url "https://app.example.com/webhooks/hookstride"
+hookstride destinations update DESTINATION_UUID --url "https://api.example.com/webhooks/hookstride"
+hookstride destinations update DESTINATION_UUID --pause
+hookstride destinations update DESTINATION_UUID --resume
+hookstride keys list
+hookstride events list --status failed
+hookstride events show EVENT_UUID
+hookstride events send DESTINATION_UUID --type webhook.test --wait
+hookstride stats
+
+hookstride incoming sources
+hookstride incoming routes
+hookstride incoming bindings
+hookstride incoming registration-keys
+
+hookstride billing status
+hookstride billing history
+hookstride config show
+```
+
+Replace the example UUIDs with identifiers from your account. Find your workspace's `account_id` with `hookstride --json projects list`; that ID is required for project creation. Project creation and renaming require an admin/owner role. Destination changes require developer access or higher.
+
+Commands that operate on a project use the selected project. You can override the selection for an individual command:
+
+```bash
+hookstride --project PROJECT_UUID events list
+```
+
+### Interactive console
+
+```bash
+hookstride console
+```
+
+Use `help` to view commands, Tab for completion, and `exit` or Ctrl+D to leave. The console also supports `show projects`, `show events`, `show destinations`, `use PROJECT_UUID`, `back`, and `set env dev|production`. The same `projects create/update`, `destinations create/update`, and `events send` commands work inside the console. Commands with customer-provided names and URLs are not saved to console history.
+
+### JSON output
+
+Use `--json` before a command to retrieve structured data for scripts:
+
+```bash
+hookstride --json projects list
+hookstride --project PROJECT_UUID --json events list --status failed
+hookstride --env production --json billing history
+```
+
+Errors go to standard error; unsuccessful requests return a nonzero exit code. When creating a destination, the server returns a signing secret **once**. Save it securely immediately. Both terminal output and `--json` deliberately include that one-time secret, so avoid piping creation output into logs or public CI artifacts.
+
+### Send a test event
+
+Use an existing active destination from `hookstride destinations list`.
+The command securely prompts for a project delivery API key (`whrk_`). It cannot use a
+Control API token (`whrctl_`); these credentials have different permissions.
+
+```bash
+hookstride --env production projects use PROJECT_UUID
+hookstride --env production events send DESTINATION_UUID --wait
+hookstride --env production events show EVENT_UUID
+```
+
+The event type defaults to `webhook.test`, with a harmless JSON payload:
+`{"message":"Hookstride CLI delivery test","source":"cli"}`.
+To send a different JSON object without placing its contents in shell history:
+
+```bash
+hookstride --env production events send DESTINATION_UUID --type demo.delivery --payload-file ./demo-payload.json --wait
+```
+
+To avoid the hidden prompt, set `HOOKSTRIDE_PRODUCTION_API_KEY` or
+`HOOKSTRIDE_DEV_API_KEY` for the matching environment only.
+Never add keys to CLI arguments, commit them to Git, or paste them into a public CI log.
+The CLI does not save delivery keys or their prompts in its configuration or history.
+The `--wait` flag polls for a terminal status and exits nonzero if delivery fails.
+A non-delivered event can be examined using `events show` with the usual Control token.
+
+## Environments and local settings
+
+The CLI connects to the production API by default: `https://api.hookstride.com`.
+A new release must be published to PyPI before existing installations receive this change.
+
+To inspect the development API explicitly, select it:
+
+```bash
+hookstride --env dev console
+```
+
+Development requests use `https://api-dev.hookstride.com`. Use a Control API token issued for the selected environment. A custom HTTPS API origin can be supplied with `--api-url`.
+
+Project selections are stored separately by environment in `~/.config/hookstride/settings.json`. This file contains project identifiers, **not authentication tokens**. Console tokens and command history remain in memory and are discarded at exit.
+
+## Documentation
+
+Documentation: https://hookstride.com

{hookstride_cli-0.2.1 → hookstride_cli-0.3.1}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hookstride-cli"
-version = "0.2.1"
-description = "Command-line access to Hookstride projects, webhook activity, and billing."
+version = "0.3.1"
+description = "Manage Hookstride projects and destinations, inspect webhook activity and billing."
 readme = "README.md"
 requires-python = ">=3.11"
 license = { text = "Proprietary" }

{hookstride_cli-0.2.1 → hookstride_cli-0.3.1}/src/hookstride_cli/__init__.py

@@ -1,3 +1,3 @@
 """Hookstride developer CLI."""
 
-__version__ = "0.2.1"
+__version__ = "0.3.1"

{hookstride_cli-0.2.1 → hookstride_cli-0.3.1}/src/hookstride_cli/console.py

@@ -1,8 +1,7 @@
-"""Interactive, read-only Hookstride console.
+"""Interactive Hookstride console with allowlisted project and destination writes.
 
-The console intentionally does not execute shell commands. It uses the same
-project-scoped Control API commands as the CLI, keeps tokens only in memory,
-and stores no history on disk.
+The console never executes shell commands, retains tokens only in memory,
+and stores no command history on disk.
 """
 
 from __future__ import annotations
@@ -25,20 +24,20 @@ from typer.main import get_command
 from . import main as cli
 
 # Only these typed commands may execute through the console.
-# Future write actions must be explicitly reviewed, not implicitly unlocked.
-READ_COMMANDS: dict[str, set[str]] = {
+# Write actions are intentionally allowlisted, never automatically unlocked.
+ALLOWED_COMMANDS: dict[str, set[str]] = {
     "auth": {"status"},
-    "projects": {"list", "use"},
-    "destinations": {"list"},
+    "projects": {"list", "use", "create", "update"},
+    "destinations": {"list", "create", "update"},
     "keys": {"list"},
-    "events": {"list", "show"},
+    "events": {"list", "show", "send"},
     "billing": {"status", "history"},
     "incoming": {"sources", "routes", "bindings", "registration-keys"},
     "config": {"show"},
 }
 ROOT_COMMANDS = {"status", "stats"}
 
-# Aliases that feel like a familiar operator console, but remain read-only.
+# Aliases that feel like a familiar operator console.
 SHOW_TARGETS: dict[str, tuple[str, ...] | None] = {
     "options": None,
     "projects": ("projects", "list"),
@@ -70,8 +69,10 @@ SAFE_HISTORY_COMMANDS = frozenset(
 COMMAND_COMPLETIONS = sorted(
     {
         *SAFE_HISTORY_COMMANDS,
-        "use ", "projects use ", "events show ", "events list --status ",
+        "use ", "projects use ", "events show ", "events send ", "events list --status ",
         "events list --origin ", "events list --page ", "set project ",
+        "projects create --name ", "projects update ",
+        "destinations create --name ", "destinations update ",
         "set env ", "json ", "show ", "auth ",
     }
 )
@@ -194,6 +195,8 @@ class HookstrideConsole:
             "[bold]help[/bold]                  Show console help\n"
             "[bold]show options[/bold]          Display environment, project and authentication\n"
             "[bold]show projects[/bold]         List accessible projects\n"
+            "[bold]projects create --name N --account UUID[/bold]   Create a project\n"
+            "[bold]projects update UUID --name N[/bold]     Rename a project\n"
             "[bold]use UUID[/bold]              Select a project (also saves preference)\n"
             "[bold]back[/bold]                  Leave the active project context\n"
             "[bold]set env dev[/bold]           Switch to development API\n"
@@ -202,9 +205,12 @@ class HookstrideConsole:
             "[bold]auth logout[/bold]           Clear the current environment's session token\n"
             "[bold]auth status[/bold]           Validate current token\n"
             "[bold]show destinations[/bold]     Inspect outgoing webhooks\n"
+            "[bold]destinations create --name N --url HTTPS_URL[/bold]   Add receiver\n"
+            "[bold]destinations update UUID --pause[/bold]   Pause a receiver\n"
             "[bold]show events[/bold]           View recent events\n"
             "[bold]events list --status failed[/bold]   Filter delivery history\n"
             "[bold]events show UUID[/bold]      Inspect a delivery and attempts\n"
+            "[bold]events send DEST_UUID --wait[/bold]    Send one signed delivery test\n"
             "[bold]show billing[/bold]          View plan and credits\n"
             "[bold]show payments[/bold]         View payment history\n"
             "[bold]show sources[/bold]          Inspect incoming sources\n"
@@ -223,7 +229,6 @@ class HookstrideConsole:
             ["API", self.session.origin],
             ["Project", project],
             ["Authenticated token", "configured" if self._current_token() else "missing"],
-            ["Mode", "read-only"],
         ]
         cli._table(_FakeContext(self.session), "Session options", ["Setting", "Value"], rows)
 
@@ -294,7 +299,7 @@ class HookstrideConsole:
         self._write("[green]✓[/green] Signed out for this console environment.")
 
     def _execute_cli(self, args: list[str], *, json_output: bool = False) -> None:
-        """Invoke existing read-only Click/Typer commands, never a shell."""
+        """Invoke explicitly allowed Click/Typer commands, never a shell."""
         if not _allowed_cli(args):
             raise cli.CLIError("Unknown or unavailable command. Type 'help'.")
         group = args[0]
@@ -303,6 +308,8 @@ class HookstrideConsole:
             raise cli.CLIError("No project selected. Run 'show projects' then 'use UUID'.")
         if _requires_token(group, action) and not self._current_token():
             raise cli.CLIError("No management token for this environment. Run 'auth login'.")
+        if args[:2] == ["events", "show"] and len(args) == 2:
+            raise cli.CLIError("Usage: events show EVENT_UUID.")
         options = ["--env", self.environment, "--api-url", self.session.origin]
         if self.project:
             options += ["--project", self.project]
@@ -316,11 +323,19 @@ class HookstrideConsole:
                     standalone_mode=False,
                 )
         except click.exceptions.Exit as exc:
-            # 'status' already displayed a red Offline panel. Do not add an
-            # unrelated error when returning to the interactive prompt.
+            # The nested CLI must never terminate the interactive console.
+            if exc.exit_code == 0:
+                return
+            # 'status' already displayed a red Offline panel.
             if group == "status" and not json_output and exc.exit_code == 1:
                 return
             raise cli.CLIError("Invalid command arguments. Type 'help'.") from None
+        except SystemExit as exc:
+            # Some Typer/Click error paths raise SystemExit instead of Exit.
+            # Do not let them unwind run() and clear in-memory authentication.
+            if exc.code in (0, None):
+                return
+            raise cli.CLIError("Invalid command arguments. Type 'help'.") from None
         except (click.ClickException, click.Abort):
             # Click errors can quote user-provided arguments; don't echo them.
             raise cli.CLIError("Invalid command arguments. Type 'help'.") from None
@@ -382,7 +397,7 @@ class HookstrideConsole:
 
     def run(self) -> None:
         self._write(
-            "\n[bold cyan]HOOKSTRIDE[/bold cyan] [dim]CONSOLE v0.2[/dim]\n"
+            f"\n[bold cyan]HOOKSTRIDE[/bold cyan] [dim]CONSOLE v{cli.VERSION}[/dim]\n"
             "[dim]Type 'help' for commands, 'auth login' for a token, "
             "or 'exit' to quit.[/dim]\n"
         )
@@ -431,8 +446,8 @@ def _allowed_cli(parts: list[str]) -> bool:
         return len(parts) == 1
     return (
         len(parts) >= 2
-        and parts[0] in READ_COMMANDS
-        and parts[1] in READ_COMMANDS[parts[0]]
+        and parts[0] in ALLOWED_COMMANDS
+        and parts[1] in ALLOWED_COMMANDS[parts[0]]
     )
 
 
@@ -443,7 +458,8 @@ def _requires_project(group: str, action: str | None) -> bool:
 
 
 def _requires_token(group: str, action: str | None) -> bool:
-    return group != "status" and not (group == "config" and action == "show")
+    return (group != "status" and not (group == "config" and action == "show")
+            and not (group == "events" and action == "send"))
 
 
 def run_console(session: cli.Session) -> None: