anncsu-sdk 0.0.1.dev28__tar.gz → 0.0.1.dev30__tar.gz

anncsu_sdk-0.0.1.dev28/README.md → anncsu_sdk-0.0.1.dev30/PKG-INFO

@@ -1,3 +1,19 @@
+Metadata-Version: 2.4
+Name: anncsu-sdk
+Version: 0.0.1.dev30
+Summary: ANNCSU Software Development Kit for API consumption
+Author-email: Francesco Bartoli <francesco.bartoli@geobeyond.it>
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: authlib>=1.3.0
+Requires-Dist: httpcore>=1.0.9
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.15.0
+Description-Content-Type: text/markdown
+
 # anncsu-sdk
 ANNCSU Software Development Kit for API consumption
 
@@ -37,6 +53,7 @@ ANNCSU REST API: API dei servizi REST di ANNCSU su PDND
   * [Resource Management](#resource-management)
   * [Debugging](#debugging)
   * [Architecture](#architecture)
+  * [Command Line Interface](#command-line-interface)
 * [Development](#development)
   * [Maturity](#maturity)
   * [Contributions](#contributions)
@@ -908,6 +925,35 @@ This architecture allows adding new ANNCSU API specifications (e.g., aggiornamen
 For more details, see [Refactoring Documentation](./docs/refactoring/REFACTORING_SUMMARY.md).
 <!-- End Architecture [architecture] -->
 
+<!-- Start Command Line Interface [cli] -->
+## Command Line Interface
+
+The SDK includes a command-line interface (`anncsu`) for managing PDND authentication and performing common operations without writing code.
+
+### Quick Start
+
+```bash
+# Configure PDND credentials
+anncsu config set --kid YOUR_KEY_ID --issuer YOUR_CLIENT_ID
+
+# Login and obtain access token
+anncsu auth login
+
+# Check authentication status
+anncsu auth status
+```
+
+### Key Features
+
+- **Authentication Management**: Generate client assertions, obtain and refresh access tokens
+- **Configuration**: Manage PDND credentials via CLI or environment variables
+- **Standalone Utilities**: Create assertions independently for integration with other tools
+
+### Documentation
+
+For complete CLI documentation including all commands, options, and examples, see **[docs/CLI.md](docs/CLI.md)**.
+<!-- End Command Line Interface [cli] -->
+
 # Development
 
 ## Maturity

anncsu_sdk-0.0.1.dev28/PKG-INFO → anncsu_sdk-0.0.1.dev30/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.4
-Name: anncsu-sdk
-Version: 0.0.1.dev28
-Summary: ANNCSU Software Development Kit for API consumption
-Author-email: Francesco Bartoli <francesco.bartoli@geobeyond.it>
-License-File: LICENSE
-Requires-Python: >=3.12
-Requires-Dist: authlib>=1.3.0
-Requires-Dist: httpcore>=1.0.9
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: pydantic-settings>=2.12.0
-Requires-Dist: pydantic>=2.12.5
-Description-Content-Type: text/markdown
-
 # anncsu-sdk
 ANNCSU Software Development Kit for API consumption
 
@@ -51,6 +37,7 @@ ANNCSU REST API: API dei servizi REST di ANNCSU su PDND
   * [Resource Management](#resource-management)
   * [Debugging](#debugging)
   * [Architecture](#architecture)
+  * [Command Line Interface](#command-line-interface)
 * [Development](#development)
   * [Maturity](#maturity)
   * [Contributions](#contributions)
@@ -922,6 +909,35 @@ This architecture allows adding new ANNCSU API specifications (e.g., aggiornamen
 For more details, see [Refactoring Documentation](./docs/refactoring/REFACTORING_SUMMARY.md).
 <!-- End Architecture [architecture] -->
 
+<!-- Start Command Line Interface [cli] -->
+## Command Line Interface
+
+The SDK includes a command-line interface (`anncsu`) for managing PDND authentication and performing common operations without writing code.
+
+### Quick Start
+
+```bash
+# Configure PDND credentials
+anncsu config set --kid YOUR_KEY_ID --issuer YOUR_CLIENT_ID
+
+# Login and obtain access token
+anncsu auth login
+
+# Check authentication status
+anncsu auth status
+```
+
+### Key Features
+
+- **Authentication Management**: Generate client assertions, obtain and refresh access tokens
+- **Configuration**: Manage PDND credentials via CLI or environment variables
+- **Standalone Utilities**: Create assertions independently for integration with other tools
+
+### Documentation
+
+For complete CLI documentation including all commands, options, and examples, see **[docs/CLI.md](docs/CLI.md)**.
+<!-- End Command Line Interface [cli] -->
+
 # Development
 
 ## Maturity

anncsu_sdk-0.0.1.dev30/docs/CLI.md

@@ -0,0 +1,422 @@
+# ANNCSU CLI
+
+Command-line interface for PDND authentication and ANNCSU API interaction.
+
+## Installation
+
+The CLI is included with the ANNCSU SDK:
+
+```bash
+pip install anncsu-sdk
+```
+
+Or with uv:
+
+```bash
+uv add anncsu-sdk
+```
+
+## Quick Start
+
+```bash
+# 1. Initialize configuration in ~/.anncsu/.env
+anncsu config init
+
+# 2. Edit ~/.anncsu/.env with your PDND credentials
+nano ~/.anncsu/.env
+
+# 3. Validate configuration
+anncsu config validate
+
+# 4. Login (generates assertion + obtains token + saves session)
+anncsu auth login
+
+# 5. Check status (loads from ~/.anncsu/session.json)
+anncsu auth status
+
+# 6. Use token in API calls (auto-refreshes if expired)
+curl -H "Authorization: Bearer $(anncsu auth token)" https://api.example.com
+```
+
+## Commands
+
+### `anncsu config` - Configuration Management
+
+Manage PDND configuration stored in `.env` file.
+
+#### `anncsu config init`
+
+Generate a template `.env` file with all required variables:
+
+```bash
+anncsu config init
+```
+
+Output:
+```
+Created .env.template with the following variables:
+- PDND_KID
+- PDND_ISSUER
+- PDND_SUBJECT
+- PDND_AUDIENCE
+- PDND_PURPOSE_ID
+- PDND_KEY_PATH (or PDND_PRIVATE_KEY)
+- PDND_TOKEN_ENDPOINT
+```
+
+#### `anncsu config show`
+
+Display current configuration (with masked sensitive values):
+
+```bash
+anncsu config show
+```
+
+Output:
+```
+┌─────────────────────────────────────────┐
+│ PDND Configuration                      │
+├─────────────────────────────────────────┤
+│ KID:           abc123...                │
+│ Issuer:        a1b2c3d4-e5f6-...        │
+│ Subject:       a1b2c3d4-e5f6-...        │
+│ Audience:      https://auth.uat...      │
+│ Purpose ID:    12345678-90ab-...        │
+│ Key Path:      ./private_key.pem ✅     │
+│ Token Endpoint: https://auth.uat...     │
+│ Validity:      43200 minutes (30 days)  │
+└─────────────────────────────────────────┘
+```
+
+#### `anncsu config validate`
+
+Validate that `.env` file is correctly configured:
+
+```bash
+anncsu config validate
+```
+
+Output (success):
+```
+✅ Configuration valid!
+   - All required fields present
+   - Key file exists and is readable
+   - Audience URL is valid HTTPS
+```
+
+Output (error):
+```
+❌ Configuration errors:
+   - PDND_KID: Missing required field
+   - PDND_KEY_PATH: File not found: ./private_key.pem
+```
+
+---
+
+### `anncsu assertion` - Client Assertion Management
+
+Generate and inspect PDND client assertions (JWT).
+
+#### `anncsu assertion create`
+
+Generate a new client assertion and print it:
+
+```bash
+anncsu assertion create
+```
+
+Output:
+```
+eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFiYzEyMyJ9.eyJpc3MiOiJhMWIyYzNkNC...
+```
+
+Options:
+- `--output FILE` - Save assertion to file instead of stdout
+- `--json` - Output as JSON with metadata
+
+#### `anncsu assertion info`
+
+Display information about the current/cached assertion:
+
+```bash
+anncsu assertion info
+```
+
+Output:
+```
+┌─────────────────────────────────────────┐
+│ Client Assertion Info                   │
+├─────────────────────────────────────────┤
+│ Algorithm:   RS256                      │
+│ Type:        JWT                        │
+│ Key ID:      abc123...                  │
+├─────────────────────────────────────────┤
+│ Issuer:      a1b2c3d4-e5f6-...          │
+│ Subject:     a1b2c3d4-e5f6-...          │
+│ Audience:    https://auth.uat...        │
+│ Purpose ID:  12345678-90ab-...          │
+├─────────────────────────────────────────┤
+│ Issued At:   2026-01-18 10:30:00        │
+│ Expires At:  2026-02-17 10:30:00        │
+│ TTL:         29 days, 23 hours          │
+│ Status:      ✅ Valid                   │
+└─────────────────────────────────────────┘
+```
+
+---
+
+### `anncsu auth` - Authentication
+
+Authenticate with PDND and manage access tokens.
+
+#### `anncsu auth login`
+
+Perform full authentication flow (assertion + token exchange):
+
+```bash
+anncsu auth login
+```
+
+Output:
+```
+✅ Login successful!
+
+┌─────────────────────────────────────────┐
+│ Client Assertion                        │
+├─────────────────────────────────────────┤
+│ TTL:         29 days, 23 hours          │
+│ Expires:     2026-02-17 10:30:00        │
+├─────────────────────────────────────────┤
+│ Access Token                            │
+├─────────────────────────────────────────┤
+│ TTL:         600 seconds                │
+│ Expires:     2026-01-18 10:40:00        │
+└─────────────────────────────────────────┘
+```
+
+Options:
+- `--token-endpoint URL` - Override token endpoint from .env
+- `--quiet` - Suppress output, only show errors
+
+#### `anncsu auth status`
+
+Show current authentication status:
+
+```bash
+anncsu auth status
+```
+
+Output (authenticated):
+```
+┌─────────────────────────────────────────┐
+│ Authentication Status                   │
+├─────────────────────────────────────────┤
+│ Client Assertion                        │
+│   Status:    ✅ Valid                   │
+│   TTL:       29 days, 23 hours          │
+│   Expires:   2026-02-17 10:30:00        │
+├─────────────────────────────────────────┤
+│ Access Token                            │
+│   Status:    ✅ Valid                   │
+│   TTL:       542 seconds                │
+│   Expires:   2026-01-18 10:39:02        │
+└─────────────────────────────────────────┘
+```
+
+Output (not authenticated):
+```
+❌ Not authenticated. Run 'anncsu auth login' first.
+```
+
+#### `anncsu auth refresh`
+
+Force refresh of the access token:
+
+```bash
+anncsu auth refresh
+```
+
+Output:
+```
+✅ Token refreshed!
+   TTL: 600 seconds
+   Expires: 2026-01-18 10:50:00
+```
+
+#### `anncsu auth token`
+
+Print the current access token (useful for piping):
+
+```bash
+anncsu auth token
+```
+
+Output:
+```
+eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9.eyJpc3MiOiJodHRwczovL2F1dGgudWF0...
+```
+
+Usage with curl:
+```bash
+curl -H "Authorization: Bearer $(anncsu auth token)" \
+  https://modipa-val.agenziaentrate.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-consultazione/v1/esisteodonimo?codcom=H501
+```
+
+---
+
+## Environment Variables
+
+The CLI reads configuration from environment variables (with `PDND_` prefix) or a `.env` file:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PDND_KID` | Yes | Key ID (kid) header parameter |
+| `PDND_ISSUER` | Yes | Issuer (iss) claim - your client_id |
+| `PDND_SUBJECT` | Yes | Subject (sub) claim - your client_id |
+| `PDND_AUDIENCE` | Yes | Audience (aud) - PDND client-assertion endpoint |
+| `PDND_PURPOSE_ID` | Yes | Purpose ID for the PDND request |
+| `PDND_KEY_PATH` | One required | Path to RSA private key file |
+| `PDND_PRIVATE_KEY` | One required | RSA private key content (alternative to KEY_PATH) |
+| `PDND_TOKEN_ENDPOINT` | Yes | PDND token endpoint URL |
+| `PDND_ALG` | No | Algorithm (default: RS256) |
+| `PDND_TYP` | No | Token type (default: JWT) |
+| `PDND_VALIDITY_MINUTES` | No | Assertion validity in minutes (default: 43200 = 30 days) |
+
+### Example `.env` file
+
+```env
+# PDND Configuration
+PDND_KID=your-key-id
+PDND_ISSUER=your-client-id
+PDND_SUBJECT=your-client-id
+PDND_AUDIENCE=https://auth.uat.interop.pagopa.it/client-assertion
+PDND_PURPOSE_ID=your-purpose-id
+PDND_KEY_PATH=./private_key.pem
+PDND_TOKEN_ENDPOINT=https://auth.uat.interop.pagopa.it/token.oauth2
+
+# Optional
+PDND_VALIDITY_MINUTES=43200
+```
+
+---
+
+## Session Persistence
+
+The CLI automatically persists authentication tokens between sessions in `~/.anncsu/session.json`.
+
+### Session File Location
+
+| Platform | Path |
+|----------|------|
+| Linux/macOS | `~/.anncsu/session.json` |
+| Windows | `%USERPROFILE%\.anncsu\session.json` |
+
+### Session File Format
+
+```json
+{
+  "client_assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9...",
+  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
+  "token_endpoint": "https://auth.uat.interop.pagopa.it/token.oauth2"
+}
+```
+
+### How It Works
+
+1. **Login** (`anncsu auth login`): Saves tokens to session file
+2. **Status** (`anncsu auth status`): Loads and displays tokens from session
+3. **Token** (`anncsu auth token`): Loads token, auto-refreshes if expired
+4. **Logout** (`anncsu auth logout`): Deletes session file
+
+### Automatic Token Refresh
+
+When you run `anncsu auth token`, the CLI automatically:
+- Loads the session from file
+- Checks if the access token is expired or expiring soon (< 60 seconds)
+- If expired, requests a new access token using the client assertion
+- If the client assertion is also expired (< 1 day remaining), generates a new one
+- Saves the updated session to file
+
+### Multi-Environment Support
+
+The session file stores the `token_endpoint` URL. If you switch between environments (e.g., UAT to PROD), the CLI will not load a session for a different endpoint, preventing accidental credential mixing.
+
+```bash
+# UAT environment - saves session with UAT endpoint
+anncsu auth login --token-endpoint https://auth.uat.interop.pagopa.it/token.oauth2
+
+# PROD environment - creates new session (different endpoint)
+anncsu auth login --token-endpoint https://auth.interop.pagopa.it/token.oauth2
+
+# Status shows only tokens for current endpoint
+anncsu auth status --token-endpoint https://auth.uat.interop.pagopa.it/token.oauth2
+```
+
+### Clear Session
+
+To remove all cached tokens:
+
+```bash
+anncsu auth logout
+```
+
+This deletes `~/.anncsu/session.json` and clears in-memory tokens.
+
+---
+
+## Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | Success |
+| 1 | Configuration error |
+| 2 | Authentication error |
+| 3 | Network error |
+| 4 | Token expired |
+
+---
+
+## Examples
+
+### Script Integration
+
+```bash
+#!/bin/bash
+# Script that uses ANNCSU CLI for authentication
+
+# Login and check status
+anncsu auth login --quiet || exit 1
+
+# Get token for API calls
+TOKEN=$(anncsu auth token)
+
+# Make API call
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "https://modipa-val.agenziaentrate.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-consultazione/v1/elencoodonimi?codcom=H501&denomparz=$(echo -n 'ROMA' | base64)"
+```
+
+### CI/CD Pipeline
+
+```yaml
+# GitHub Actions example
+- name: ANNCSU Authentication
+  env:
+    PDND_KID: ${{ secrets.PDND_KID }}
+    PDND_ISSUER: ${{ secrets.PDND_ISSUER }}
+    PDND_SUBJECT: ${{ secrets.PDND_SUBJECT }}
+    PDND_AUDIENCE: ${{ secrets.PDND_AUDIENCE }}
+    PDND_PURPOSE_ID: ${{ secrets.PDND_PURPOSE_ID }}
+    PDND_PRIVATE_KEY: ${{ secrets.PDND_PRIVATE_KEY }}
+    PDND_TOKEN_ENDPOINT: ${{ secrets.PDND_TOKEN_ENDPOINT }}
+  run: |
+    anncsu auth login
+    anncsu auth status
+```
+
+---
+
+## See Also
+
+- [Security Documentation](./SECURITY.md) - PDND authentication details
+- [SDK Usage](../README.md) - Programmatic SDK usage
+- [PDNDAuthManager](./conversation_log.md#session-19) - Authentication manager internals

anncsu_sdk-0.0.1.dev30/docs/speakeasy.md

@@ -0,0 +1,73 @@
+# Speakeasy SDK Generation
+
+This guide documents the workflow for generating and regenerating the SDK with Speakeasy.
+
+## Prerequisites
+
+- [Speakeasy CLI](https://www.speakeasy.com/docs/speakeasy-cli/getting-started) installed
+- OpenAPI specification file in `oas/dev/`
+
+## Generation Workflow
+
+### 1. Generate SDK with Speakeasy
+
+```bash
+speakeasy generate sdk \
+  --lang python \
+  --out . \
+  --schema oas/dev/Specifica\ API\ -\ ANNCSU\ –\ Consultazione\ per\ le\ PA.yaml
+```
+
+### 2. Run post-generation script
+
+After each Speakeasy generation, run the post-generation script to update the package structure:
+
+```bash
+uv run python scripts/post_speakeasy_generation.py
+```
+
+This script:
+- Removes duplicated infrastructure files from API packages
+- Updates imports to use shared modules in `anncsu.common.sdk`
+
+### 3. Verify with tests
+
+```bash
+uv run pytest tests/ -q
+```
+
+## Post-Generation Script Options
+
+```bash
+# Process pa/ package (default)
+uv run python scripts/post_speakeasy_generation.py
+
+# Process a specific package
+uv run python scripts/post_speakeasy_generation.py --package pa
+
+# Process all API packages
+uv run python scripts/post_speakeasy_generation.py --all
+
+# Dry run (preview changes without applying)
+uv run python scripts/post_speakeasy_generation.py --dry-run
+
+# Show help
+uv run python scripts/post_speakeasy_generation.py --help
+```
+
+## Adding a New API Package
+
+When adding a new API package (e.g., `odonimi` for Aggiornamento odonimi):
+
+1. Generate the package with Speakeasy using the appropriate OpenAPI spec
+2. Run the post-generation script:
+   ```bash
+   uv run python scripts/post_speakeasy_generation.py --package odonimi
+   ```
+3. Add the package to the list in `scripts/post_speakeasy_generation.py` for future `--all` runs
+
+## Important Notes
+
+> **WARNING**: The `common/sdk/` directory contains shared infrastructure that is NOT regenerated by Speakeasy. Do not delete it during regeneration.
+
+> **NOTE**: Always run the post-generation script after each Speakeasy regeneration to maintain the correct package structure.

{anncsu_sdk-0.0.1.dev28 → anncsu_sdk-0.0.1.dev30}/pyproject.toml

@@ -13,7 +13,12 @@ dependencies = [
     "pydantic >=2.12.5",
     "authlib>=1.3.0",
     "pydantic-settings>=2.12.0",
+    "typer>=0.15.0",
+    "rich>=13.0.0",
 ]
+
+[project.scripts]
+anncsu = "anncsu.cli:app"
 [dependency-groups]
 dev = [
     "pytest>=9.0.0",