commune-cli 0.1.4__tar.gz → 0.1.6__tar.gz

{commune_cli-0.1.4 → commune_cli-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commune-cli
-Version: 0.1.4
+Version: 0.1.6
 Summary: Official CLI for the Commune email API — agent-native, pipe-friendly, covers every API surface.
 Project-URL: Homepage, https://commune.email
 Project-URL: Documentation, https://docs.commune.email

commune_cli-0.1.6/commune_cli/commands/credits.py

@@ -0,0 +1,104 @@
+"""commune credits — credit balance and bundle management."""
+
+from __future__ import annotations
+
+import typer
+
+from ..client import CommuneClient
+from ..errors import api_error, auth_required_error, network_error
+from ..output import print_list, print_record, print_success
+from ..state import AppState
+
+app = typer.Typer(help="Credit balance and available bundles.", no_args_is_help=True)
+
+
+@app.command("balance")
+def credits_balance(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Get current credit balance. GET /v1/credits."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get("/v1/credits")
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_record(r.json(), json_output=json_output or state.should_json(), title="Credit Balance")
+
+
+@app.command("bundles")
+def credits_bundles(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """List available credit bundles. GET /v1/credits/bundles."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get("/v1/credits/bundles")
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_list(
+        r.json(),
+        json_output=json_output or state.should_json(),
+        title="Credit Bundles",
+        columns=[
+            ("ID", "id"),
+            ("Credits", "credits"),
+            ("Price", "price"),
+            ("Description", "description"),
+        ],
+    )
+
+
+@app.command("checkout")
+def credits_checkout(
+    ctx: typer.Context,
+    bundle: str = typer.Argument(..., help="Bundle to purchase: starter, growth, or scale."),
+    return_url: str = typer.Option(None, "--return-url", help="URL to redirect to after payment (optional)."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Create a Stripe checkout session to purchase credits. POST /v1/credits/checkout."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    payload: dict = {"bundle": bundle}
+    if return_url:
+        payload["return_url"] = return_url
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.post("/v1/credits/checkout", json=payload)
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    data = r.json()
+    if json_output or state.should_json():
+        from ..output import print_json
+        print_json(data)
+        return
+
+    checkout_url = data.get("checkout_url") or data.get("checkoutUrl", "")
+    credits = data.get("credits", "")
+    price = data.get("price", "")
+    print_success(f"Checkout session created for [bold]{bundle}[/bold] bundle ({credits} credits, ${price}).")
+    typer.echo(f"\nOpen this URL in your browser to complete payment:\n{checkout_url}")

commune_cli-0.1.6/commune_cli/commands/phone_numbers.py

@@ -0,0 +1,201 @@
+"""commune phone-numbers — phone number management."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..client import CommuneClient
+from ..errors import api_error, auth_required_error, network_error
+from ..output import print_list, print_record, print_success
+from ..state import AppState
+
+app = typer.Typer(help="Phone number management: list, get, provision, release, settings.", no_args_is_help=True)
+
+
+@app.command("list")
+def phone_numbers_list(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """List all phone numbers in your organization. GET /v1/phone-numbers."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get("/v1/phone-numbers")
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_list(
+        r.json(),
+        json_output=json_output or state.should_json(),
+        title="Phone Numbers",
+        columns=[
+            ("ID", "id"),
+            ("Number", "phoneNumber"),
+            ("Friendly Name", "friendlyName"),
+            ("Status", "status"),
+            ("Created", "createdAt"),
+        ],
+    )
+
+
+@app.command("get")
+def phone_numbers_get(
+    ctx: typer.Context,
+    phone_number_id: str = typer.Argument(..., help="Phone number ID."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Get a specific phone number. GET /v1/phone-numbers/{phoneNumberId}."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get(f"/v1/phone-numbers/{phone_number_id}")
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_record(r.json(), json_output=json_output or state.should_json(), title="Phone Number")
+
+
+@app.command("available")
+def phone_numbers_available(
+    ctx: typer.Context,
+    type: Optional[str] = typer.Option("TollFree", "--type", help="Number type: TollFree or Local."),
+    country: Optional[str] = typer.Option("US", "--country", help="Two-letter country code."),
+    limit: Optional[int] = typer.Option(20, "--limit", help="Maximum results to return."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """List available phone numbers to purchase. GET /v1/phone-numbers/available."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get("/v1/phone-numbers/available", params={
+            "type": type,
+            "country": country,
+            "limit": limit,
+        })
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_list(
+        r.json(),
+        json_output=json_output or state.should_json(),
+        title="Available Phone Numbers",
+        columns=[
+            ("Number", "phoneNumber"),
+            ("Friendly Name", "friendlyName"),
+            ("Region", "region"),
+            ("Locality", "locality"),
+        ],
+    )
+
+
+@app.command("provision")
+def phone_numbers_provision(
+    ctx: typer.Context,
+    phone_number: Optional[str] = typer.Option(None, "--phone-number", help="Specific E.164 number to buy (e.g. +18005551234). Auto-selected if omitted."),
+    type: Optional[str] = typer.Option("tollfree", "--type", help="Number type: tollfree or local."),
+    country: Optional[str] = typer.Option("US", "--country", help="Two-letter country code."),
+    friendly_name: Optional[str] = typer.Option(None, "--friendly-name", help="Human-readable label for this number."),
+    area_code: Optional[str] = typer.Option(None, "--area-code", help="Preferred area code (local numbers only)."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Purchase/provision a phone number for SMS. POST /v1/phone-numbers."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    payload: dict = {"type": type, "country": country}
+    if phone_number:
+        payload["phone_number"] = phone_number
+    if friendly_name:
+        payload["friendly_name"] = friendly_name
+    if area_code:
+        payload["area_code"] = area_code
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.post("/v1/phone-numbers", json=payload)
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_record(r.json(), json_output=json_output or state.should_json(), title="Provisioned Phone Number")
+
+
+@app.command("release")
+def phone_numbers_release(
+    ctx: typer.Context,
+    phone_number_id: str = typer.Argument(..., help="Phone number ID to release."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Release a provisioned phone number. DELETE /v1/phone-numbers/{id}."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    if not yes:
+        typer.confirm(
+            f"Are you sure you want to release phone number {phone_number_id}? This cannot be undone.",
+            abort=True,
+        )
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.delete(f"/v1/phone-numbers/{phone_number_id}")
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    if json_output or state.should_json():
+        from ..output import print_json
+        print_json(r.json())
+        return
+
+    print_success(f"Phone number [bold]{phone_number_id}[/bold] released.")
+
+
+@app.command("settings")
+def phone_numbers_settings(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Get SMS quota settings for your organization. GET /v1/phone-settings."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get("/v1/phone-settings")
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_record(r.json(), json_output=json_output or state.should_json(), title="SMS Settings")

commune_cli-0.1.6/commune_cli/commands/sms.py

@@ -0,0 +1,187 @@
+"""commune sms — send SMS and manage conversations."""
+
+from __future__ import annotations
+
+from typing import Optional
+from urllib.parse import quote
+
+import typer
+
+from ..client import CommuneClient
+from ..errors import api_error, auth_required_error, network_error, validation_error
+from ..output import print_json, print_list, print_record, print_success
+from ..state import AppState
+
+app = typer.Typer(help="Send SMS and manage conversations.", no_args_is_help=True)
+
+
+@app.command("send")
+def sms_send(
+    ctx: typer.Context,
+    to: str = typer.Option(..., "--to", help="Recipient phone number in E.164 format (e.g. +1234567890)."),
+    body: str = typer.Option(..., "--body", help="SMS message body."),
+    phone_number_id: Optional[str] = typer.Option(
+        None,
+        "--phone-number-id",
+        help="Phone number ID to send from. Uses org default if omitted.",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Send an SMS message. POST /v1/sms/send."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    payload: dict = {"to": to, "body": body}
+    if phone_number_id:
+        payload["phone_number_id"] = phone_number_id
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.post("/v1/sms/send", json=payload)
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    data = r.json()
+    if json_output or state.should_json():
+        print_json(data)
+        return
+
+    msg_id = data.get("id") or data.get("messageId", "")
+    print_success(f"SMS sent. ID: [bold]{msg_id}[/bold]")
+
+
+@app.command("conversations")
+def sms_conversations(
+    ctx: typer.Context,
+    phone_number_id: Optional[str] = typer.Option(
+        None,
+        "--phone-number-id",
+        help="Filter by phone number ID.",
+    ),
+    limit: Optional[int] = typer.Option(20, "--limit", help="Maximum results to return."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """List SMS conversations. GET /v1/sms/conversations."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get("/v1/sms/conversations", params={
+            "phone_number_id": phone_number_id,
+            "limit": limit,
+        })
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_list(
+        r.json(),
+        json_output=json_output or state.should_json(),
+        title="SMS Conversations",
+        columns=[
+            ("Remote Number", "remoteNumber"),
+            ("Last Message", "lastMessage"),
+            ("Direction", "lastDirection"),
+            ("Updated", "updatedAt"),
+        ],
+    )
+
+
+@app.command("thread")
+def sms_thread(
+    ctx: typer.Context,
+    remote_number: str = typer.Argument(..., help="Remote phone number (E.164, e.g. +1234567890)."),
+    phone_number_id: str = typer.Option(
+        ...,
+        "--phone-number-id",
+        help="Phone number ID for the conversation.",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Get the message thread with a specific number. GET /v1/sms/conversations/{remoteNumber}."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    encoded = quote(remote_number, safe="")
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get(
+            f"/v1/sms/conversations/{encoded}",
+            params={"phone_number_id": phone_number_id},
+        )
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    data = r.json()
+    if json_output or state.should_json():
+        print_json(data)
+        return
+
+    messages = data if isinstance(data, list) else data.get("data", data)
+    print_list(
+        messages,
+        json_output=False,
+        title=f"Thread with {remote_number}",
+        columns=[
+            ("ID", "id"),
+            ("Direction", "direction"),
+            ("Body", "body"),
+            ("Sent At", "createdAt"),
+        ],
+    )
+
+
+@app.command("search")
+def sms_search(
+    ctx: typer.Context,
+    query: str = typer.Argument(..., help="Search query."),
+    phone_number_id: Optional[str] = typer.Option(
+        None,
+        "--phone-number-id",
+        help="Scope search to a specific phone number.",
+    ),
+    limit: Optional[int] = typer.Option(20, "--limit", help="Maximum results to return."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Search SMS messages. GET /v1/sms/search."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get("/v1/sms/search", params={
+            "q": query,
+            "phone_number_id": phone_number_id,
+            "limit": limit,
+        })
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_list(
+        r.json(),
+        json_output=json_output or state.should_json(),
+        title=f"SMS Search: {query}",
+        columns=[
+            ("ID", "id"),
+            ("From", "from"),
+            ("To", "to"),
+            ("Body", "body"),
+            ("Date", "createdAt"),
+        ],
+    )

{commune_cli-0.1.4 → commune_cli-0.1.6}/commune_cli/main.py

@@ -24,6 +24,9 @@ from .commands import (
     webhooks,
     dmarc,
     data,
+    phone_numbers,
+    sms,
+    credits,
 )
 
 app = typer.Typer(
@@ -49,6 +52,9 @@ app.add_typer(delivery.app,    name="delivery",     help="Delivery metrics, even
 app.add_typer(webhooks.app,    name="webhooks",     help="Webhook delivery log: list, retry, health.")
 app.add_typer(dmarc.app,       name="dmarc",        help="DMARC reports and summary.")
 app.add_typer(data.app,        name="data",         help="Data deletion requests (GDPR / destructive).")
+app.add_typer(phone_numbers.app, name="phone-numbers", help="Phone number management: list, get, settings.")
+app.add_typer(sms.app,           name="sms",           help="Send SMS and manage conversations.")
+app.add_typer(credits.app,       name="credits",       help="Credit balance and available bundles.")
 
 
 @app.callback(invoke_without_command=True)

{commune_cli-0.1.4 → commune_cli-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "commune-cli"
-version = "0.1.4"
+version = "0.1.6"
 description = "Official CLI for the Commune email API — agent-native, pipe-friendly, covers every API surface."
 readme = "README.md"
 requires-python = ">=3.9"