karrio-cli 2025.5rc3__py3-none-any.whl

karrio_cli/resources/connections.py

@@ -0,0 +1,207 @@
+import typer
+import karrio_cli.common.utils as utils
+import typing
+
+app = typer.Typer()
+
+@app.command("list")
+def list_connections(
+    carrier_name: typing.Optional[str] = None,
+    system_only: bool = typer.Option(False, "--system-only", help="Filter for system connections only"),
+    limit: int = typer.Option(20, help="Number of results to return per page"),
+    offset: int = typer.Option(0, help="The initial index from which to return the results"),
+    pretty: bool = typer.Option(False, "--pretty", "-p", help="Pretty print the output"),
+    line_numbers: bool = typer.Option(False, "--line-numbers", "-n", help="Show line numbers in pretty print"),
+):
+    """
+    List all carrier connections with optional filters and pagination.
+
+    Examples:
+    ```terminal
+    # Get all connections and display as a table
+    kcli connections list | jq -r ".results[] | [.id, .carrier_name, .test_mode] | @tsv" | column -t -s $"\t"
+    ```
+
+    ```terminal
+    # Get connections for a specific carrier
+    kcli connections list --carrier-name ups | jq ".results[] | {id, carrier_name, test_mode}"
+    ```
+
+    Example Output:
+    ```json
+    {
+      "count": 2,
+      "next": null,
+      "previous": null,
+      "results": [
+        {
+          "id": "conn_123456789",
+          "carrier_name": "ups",
+          "test_mode": true,
+          "active": true,
+          "capabilities": ["rating", "shipping", "tracking"],
+          "metadata": {}
+        }
+      ]
+    }
+    ```
+    """
+    params = {
+        "carrier_name": carrier_name,
+        "system_only": system_only,
+        "limit": limit,
+        "offset": offset,
+    }
+    params = {k: v for k, v in params.items() if v is not None}
+    utils.make_get_request(
+        "v1/connections", params=params, pretty_print=pretty, line_numbers=line_numbers
+    )
+
+@app.command("retrieve")
+def retrieve_connection(
+    connection_id: str,
+    pretty: bool = typer.Option(False, "--pretty", "-p", help="Pretty print the output"),
+    line_numbers: bool = typer.Option(False, "--line-numbers", "-n", help="Show line numbers in pretty print"),
+):
+    """
+    Retrieve a carrier connection by ID.
+
+    Example:
+    ```terminal
+    kcli connections retrieve conn_123456789 | jq "{id, carrier_name, test_mode, active}"
+    ```
+
+    Example Output:
+    ```json
+    {
+      "id": "conn_123456789",
+      "carrier_name": "ups",
+      "test_mode": true,
+      "active": true,
+      "capabilities": ["rating", "shipping", "tracking"],
+      "credentials": {
+        "api_key": "YOUR_API_KEY",
+        "password": "YOUR_PASSWORD",
+        "account_number": "YOUR_ACCOUNT"
+      },
+      "metadata": {}
+    }
+    ```
+    """
+    utils.make_get_request(
+        f"v1/connections/{connection_id}", pretty_print=pretty, line_numbers=line_numbers
+    )
+
+@app.command("create")
+def create_connection(
+    property: typing.List[str] = typer.Option(
+        [], "--property", "-d", help="Set nested properties (e.g. -d carrier_name=ups -d credentials[api_key]=xxx)"
+    ),
+    pretty: bool = typer.Option(False, "--pretty", "-p", help="Pretty print the output"),
+    line_numbers: bool = typer.Option(False, "--line-numbers", "-n", help="Show line numbers in pretty print"),
+):
+    """
+    Create a new carrier connection.
+
+    Example:
+    ```terminal
+    kcli connections create \\
+        -d carrier_name=ups \\
+        -d test_mode=true \\
+        -d credentials[api_key]=YOUR_API_KEY \\
+        -d credentials[password]=YOUR_PASSWORD \\
+        -d credentials[account_number]=YOUR_ACCOUNT | jq "{id, carrier_name, test_mode}"
+    ```
+
+    Example Output:
+    ```json
+    {
+      "id": "conn_123456789",
+      "carrier_name": "ups",
+      "test_mode": true,
+      "active": true,
+      "capabilities": ["rating", "shipping", "tracking"],
+      "credentials": {
+        "api_key": "YOUR_API_KEY",
+        "password": "YOUR_PASSWORD",
+        "account_number": "YOUR_ACCOUNT"
+      }
+    }
+    ```
+    """
+    try:
+        payload = utils.parse_nested_properties(property)
+    except ValueError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+    utils.make_post_request(
+        "v1/connections", payload=payload, pretty_print=pretty, line_numbers=line_numbers
+    )
+
+@app.command("update")
+def update_connection(
+    connection_id: str,
+    property: typing.List[str] = typer.Option(
+        [], "--property", "-d", help="Set nested properties (e.g. -d credentials[api_key]=newvalue)"
+    ),
+    pretty: bool = typer.Option(False, "--pretty", "-p", help="Pretty print the output"),
+    line_numbers: bool = typer.Option(False, "--line-numbers", "-n", help="Show line numbers in pretty print"),
+):
+    """
+    Update a carrier connection by ID.
+
+    Example:
+    ```terminal
+    kcli connections update conn_123456789 \\
+        -d test_mode=false \\
+        -d credentials[api_key]=NEW_API_KEY | jq "{id, carrier_name, test_mode}"
+    ```
+
+    Example Output:
+    ```json
+    {
+      "id": "conn_123456789",
+      "carrier_name": "ups",
+      "test_mode": false,
+      "active": true,
+      "credentials": {
+        "api_key": "NEW_API_KEY",
+        "password": "YOUR_PASSWORD",
+        "account_number": "YOUR_ACCOUNT"
+      }
+    }
+    ```
+    """
+    try:
+        payload = utils.parse_nested_properties(property)
+    except ValueError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+    utils.make_patch_request(
+        f"v1/connections/{connection_id}", payload=payload, pretty_print=pretty, line_numbers=line_numbers
+    )
+
+@app.command("delete")
+def delete_connection(
+    connection_id: str,
+    pretty: bool = typer.Option(False, "--pretty", "-p", help="Pretty print the output"),
+    line_numbers: bool = typer.Option(False, "--line-numbers", "-n", help="Show line numbers in pretty print"),
+):
+    """
+    Delete a carrier connection by ID.
+
+    Example:
+    ```terminal
+    kcli connections delete conn_123456789 | jq "{message: \"Connection deleted successfully\"}"
+    ```
+
+    Example Output:
+    ```json
+    {
+      "message": "Connection deleted successfully"
+    }
+    ```
+    """
+    utils.make_delete_request(
+        f"v1/connections/{connection_id}", pretty_print=pretty, line_numbers=line_numbers
+    )

karrio_cli/resources/events.py

@@ -0,0 +1,151 @@
+import typer
+import karrio_cli.common.utils as utils
+import typing
+import datetime
+
+app = typer.Typer()
+
+
+@app.command("list")
+def list_events(
+    type: typing.Optional[str] = typer.Option(
+        None,
+        help="Event type (e.g. shipment_created, order_created, tracker_created)",
+        autocompletion=lambda: [
+            "all",
+            "batch_completed",
+            "batch_failed",
+            "batch_queued",
+            "batch_running",
+            "order_cancelled",
+            "order_created",
+            "order_delivered",
+            "order_fulfilled",
+            "order_updated",
+            "shipment_cancelled",
+            "shipment_delivery_failed",
+            "shipment_fulfilled",
+            "shipment_needs_attention",
+            "shipment_out_for_delivery",
+            "shipment_purchased",
+            "tracker_created",
+            "tracker_updated",
+        ]
+    ),
+    created_after: typing.Optional[datetime.datetime] = None,
+    created_before: typing.Optional[datetime.datetime] = None,
+    limit: int = typer.Option(20, help="Number of results to return per page"),
+    offset: int = typer.Option(
+        0, help="The initial index from which to return the results"
+    ),
+    pretty: bool = typer.Option(
+        False, "--pretty", "-p", help="Pretty print the output"
+    ),
+    line_numbers: bool = typer.Option(
+        False, "--line-numbers", "-n", help="Show line numbers in pretty print"
+    ),
+):
+    """
+    List all events with optional filters and pagination.
+
+    Examples:
+    ```terminal
+    # Get all events and display as a table
+    kcli events list --limit 10 | jq -r ".events.edges[].node | [.id, .type, .created_at] | @tsv" | column -t -s $"\t"
+    ```
+
+    ```terminal
+    # Get events of a specific type
+    kcli events list --type shipment_purchased --limit 5 | jq ".events.edges[].node | {id, type, created_at, data}"
+    ```
+
+    Example Output:
+    ```json
+    {
+      "events": {
+        "edges": [
+          {
+            "node": {
+              "id": "evt_123456789",
+              "type": "shipment_purchased",
+              "data": {
+                "shipment_id": "shp_123456789",
+                "status": "purchased"
+              },
+              "test_mode": false,
+              "pending_webhooks": 0,
+              "created_at": "2024-03-20T10:30:00Z"
+            }
+          }
+        ],
+        "page_info": {
+          "count": 1,
+          "has_next_page": false,
+          "has_previous_page": false,
+          "start_cursor": "YXJyYXljb25uZWN0aW9uOjA=",
+          "end_cursor": "YXJyYXljb25uZWN0aW9uOjA="
+        }
+      }
+    }
+    ```
+    """
+    params = {
+        "type": [type] if type else None,
+        "created_after": created_after.isoformat() if created_after else None,
+        "created_before": created_before.isoformat() if created_before else None,
+        "first": limit,
+        "offset": offset,
+    }
+
+    # Remove None values from params
+    params = {k: v for k, v in params.items() if v is not None}
+
+    utils.make_graphql_request(
+        "get_events",
+        {"filter": params},
+        pretty_print=pretty,
+        line_numbers=line_numbers
+    )
+
+
+@app.command("retrieve")
+def retrieve_event(
+    event_id: str,
+    pretty: bool = typer.Option(
+        False, "--pretty", "-p", help="Pretty print the output"
+    ),
+    line_numbers: bool = typer.Option(
+        False, "--line-numbers", "-n", help="Show line numbers in pretty print"
+    ),
+):
+    """
+    Retrieve an event by ID.
+
+    Example:
+    ```terminal
+    kcli events retrieve evt_123456789 | jq "{id, type, created_at, data}"
+    ```
+
+    Example Output:
+    ```json
+    {
+      "event": {
+        "id": "evt_123456789",
+        "type": "shipment_purchased",
+        "data": {
+          "shipment_id": "shp_123456789",
+          "status": "purchased"
+        },
+        "test_mode": false,
+        "pending_webhooks": 0,
+        "created_at": "2024-03-20T10:30:00Z"
+      }
+    }
+    ```
+    """
+    utils.make_graphql_request(
+        "get_event",
+        {"id": event_id},
+        pretty_print=pretty,
+        line_numbers=line_numbers
+    )

karrio_cli/resources/logs.py

@@ -0,0 +1,151 @@
+import typer
+import karrio_cli.common.utils as utils
+import typing
+import datetime
+
+app = typer.Typer()
+
+
+@app.command("list")
+def list_logs(
+    entity_id: typing.Optional[str] = None,
+    method: typing.Optional[str] = None,
+    status_code: typing.Optional[str] = None,
+    created_after: typing.Optional[datetime.datetime] = None,
+    created_before: typing.Optional[datetime.datetime] = None,
+    limit: int = typer.Option(20, help="Number of results to return per page"),
+    offset: int = typer.Option(
+        0, help="The initial index from which to return the results"
+    ),
+    pretty: bool = typer.Option(
+        False, "--pretty", "-p", help="Pretty print the output"
+    ),
+    line_numbers: bool = typer.Option(
+        False, "--line-numbers", "-n", help="Show line numbers in pretty print"
+    ),
+):
+    """
+    List all logs with optional filters and pagination.
+
+    Examples:
+    ```terminal
+    # Get all logs and display as a table
+    kcli logs list --limit 10 | jq -r ".logs.edges[].node | [.id, .method, .status_code, .path] | @tsv" | column -t -s $"\t"
+    ```
+
+    ```terminal
+    # Get logs for a specific entity
+    kcli logs list --entity-id shp_123456789 --limit 5 | jq ".logs.edges[].node | {id, method, status_code, path}"
+    ```
+
+    Example Output:
+    ```json
+    {
+      "logs": {
+        "edges": [
+          {
+            "node": {
+              "id": "123",
+              "method": "POST",
+              "status_code": 200,
+              "path": "/v1/shipments",
+              "request": {
+                "headers": {},
+                "body": {}
+              },
+              "response": {
+                "headers": {},
+                "body": {}
+              },
+              "response_ms": 245,
+              "requested_at": "2024-03-20T10:30:00Z"
+            }
+          }
+        ],
+        "pageInfo": {
+          "hasNextPage": true,
+          "hasPreviousPage": false,
+          "startCursor": "YXJyYXljb25uZWN0aW9uOjA=",
+          "endCursor": "YXJyYXljb25uZWN0aW9uOjk="
+        }
+      }
+    }
+    ```
+    """
+    params = {
+        "entity_id": entity_id,
+        "method": method,
+        "status_code": status_code,
+        "created_after": created_after.isoformat() if created_after else None,
+        "created_before": created_before.isoformat() if created_before else None,
+        "first": limit,
+        "offset": offset,
+    }
+
+    # Remove None values from params
+    params = {k: v for k, v in params.items() if v is not None}
+
+    utils.make_graphql_request(
+        "get_logs",
+        {"filter": params},
+        pretty_print=pretty,
+        line_numbers=line_numbers
+    )
+
+
+@app.command("retrieve")
+def retrieve_log(
+    log_id: str,
+    pretty: bool = typer.Option(
+        False, "--pretty", "-p", help="Pretty print the output"
+    ),
+    line_numbers: bool = typer.Option(
+        False, "--line-numbers", "-n", help="Show line numbers in pretty print"
+    ),
+):
+    """
+    Retrieve a log by ID.
+
+    Example:
+    ```terminal
+    kcli logs retrieve 123 | jq "{id, method, status_code, path, response_ms, requested_at}"
+    ```
+
+    Example Output:
+    ```json
+    {
+      "log": {
+        "id": "123",
+        "method": "POST",
+        "status_code": 200,
+        "path": "/v1/shipments",
+        "request": {
+          "headers": {
+            "Content-Type": "application/json",
+            "Authorization": "Token <redacted>"
+          },
+          "body": {
+            "shipment_id": "shp_123456789"
+          }
+        },
+        "response": {
+          "headers": {
+            "Content-Type": "application/json"
+          },
+          "body": {
+            "id": "shp_123456789",
+            "status": "created"
+          }
+        },
+        "response_ms": 245,
+        "requested_at": "2024-03-20T10:30:00Z"
+      }
+    }
+    ```
+    """
+    utils.make_graphql_request(
+        "get_log",
+        {"id": int(log_id)},
+        pretty_print=pretty,
+        line_numbers=line_numbers
+    )

karrio_cli/resources/orders.py

@@ -0,0 +1,144 @@
+import typer
+import karrio_cli.common.utils as utils
+import typing
+import datetime
+
+app = typer.Typer()
+
+
+@app.command("list")
+def list_orders(
+    created_after: typing.Optional[datetime.datetime] = None,
+    created_before: typing.Optional[datetime.datetime] = None,
+    status: typing.Optional[str] = None,
+    reference: typing.Optional[str] = None,
+    metadata_key: typing.Optional[str] = None,
+    metadata_value: typing.Optional[str] = None,
+    limit: int = typer.Option(20, help="Number of results to return per page"),
+    offset: int = typer.Option(
+        0, help="The initial index from which to return the results"
+    ),
+    pretty: bool = typer.Option(
+        False, "--pretty", "-p", help="Pretty print the output"
+    ),
+    line_numbers: bool = typer.Option(
+        False, "--line-numbers", "-n", help="Show line numbers in pretty print"
+    ),
+):
+    """
+    List all orders with optional filters and pagination.
+
+    Examples:
+    ```terminal
+    # Get all orders and display as a table
+    kcli orders list --limit 15 | jq -r ".results[] | [.id, .status, .created_at, .total_charge.amount] | @tsv" | column -t -s $"\t"
+    ```
+
+    ```terminal
+    # Get pending orders and extract specific fields
+    kcli orders list --status pending --limit 5 | jq ".results[] | {id, status, created: .created_at, total: .total_charge.amount}"
+    ```
+
+    Example Output:
+    ```json
+    {
+      "count": 15,
+      "next": "/v1/orders?limit=15&offset=15",
+      "previous": null,
+      "results": [
+        {
+          "id": "ord_123456789",
+          "status": "pending",
+          "created_at": "2024-03-20T10:30:00Z",
+          "total_charge": {
+            "amount": 25.50,
+            "currency": "USD"
+          },
+          "line_items": [],
+          "metadata": {}
+        }
+      ]
+    }
+    ```
+    """
+    params = {
+        "created_after": created_after.isoformat() if created_after else None,
+        "created_before": created_before.isoformat() if created_before else None,
+        "status": status,
+        "reference": reference,
+        "metadata_key": metadata_key,
+        "metadata_value": metadata_value,
+        "limit": limit,
+        "offset": offset,
+    }
+
+    # Remove None values from params
+    params = {k: v for k, v in params.items() if v is not None}
+
+    utils.make_get_request(
+        "v1/orders", params=params, pretty_print=pretty, line_numbers=line_numbers
+    )
+
+
+@app.command("retrieve")
+def retrieve_order(
+    order_id: str,
+    pretty: bool = typer.Option(
+        False, "--pretty", "-p", help="Pretty print the output"
+    ),
+    line_numbers: bool = typer.Option(
+        False, "--line-numbers", "-n", help="Show line numbers in pretty print"
+    ),
+):
+    """
+    Retrieve an order by ID.
+
+    Example:
+    ```terminal
+    kcli orders retrieve ord_987654321 | jq "{id, status, created: .created_at, total: .total_charge.amount, items: .line_items | length}"
+    ```
+    """
+    utils.make_get_request(
+        f"v1/orders/{order_id}", pretty_print=pretty, line_numbers=line_numbers
+    )
+
+
+@app.command("cancel")
+def cancel_order(
+    order_id: str,
+    property: typing.List[str] = typer.Option(
+        [],
+        "--property",
+        "-d",
+        help="Set nested properties (e.g. -d reason=customer_request)",
+    ),
+    pretty: bool = typer.Option(
+        False, "--pretty", "-p", help="Pretty print the output"
+    ),
+    line_numbers: bool = typer.Option(
+        False, "--line-numbers", "-n", help="Show line numbers in pretty print"
+    ),
+):
+    """
+    Cancel an order.
+
+    Example:
+    ```terminal
+    kcli orders cancel ord_987654321 -d reason=customer_request | jq "{id, status, cancel_reason: .cancellation.reason}"
+    ```
+    """
+    payload = {}
+
+    try:
+        nested_properties = utils.parse_nested_properties(property)
+        payload.update(nested_properties)
+    except ValueError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+    utils.make_post_request(
+        f"v1/orders/{order_id}/cancel",
+        payload=payload,
+        pretty_print=pretty,
+        line_numbers=line_numbers,
+    )