Updated at mer 11 feb 2026, 15:53:09, CET

Author: francescobianco

Makefile

@@ -57,7 +57,7 @@ oas-download:
 			echo "  WARNING: failed to download $$url — check the URL in oas/urls.txt" >&2; \
 			errors=$$((errors + 1)); \
 		fi; \
-	done < oas/00-oas-list.txt; \
+	done < oas/00-list.txt; \
 	echo ""; \
 	if [ $$errors -gt 0 ]; then \
 		echo "Done with $$errors warning(s). Fix the URLs above in oas/urls.txt and re-run."; \
@@ -77,3 +77,13 @@ release:
 
 install:
 	@cargo install --path .
+
+## =======
+## Testing
+## =======
+
+test:
+	@cargo test
+
+test-commands:
+	@bash tests/commands-test.sh

USAGE.md

@@ -0,0 +1,132 @@
+# openapi CLI - Usage Guide
+
+## Configuration
+
+The CLI requires API tokens set as environment variables:
+
+```bash
+export OPENAPI_TOKEN="your-production-token"
+export OPENAPI_SANDBOX_TOKEN="your-sandbox-token"   # optional
+```
+
+Check your configuration status:
+
+```bash
+openapi info
+```
+
+## Sandbox Mode
+
+Use the `-S` (or `--sandbox`) flag to run against sandbox environments:
+
+```bash
+openapi -S sms send --to "+391234567890" --message "Test"
+```
+
+## Scope Aliases
+
+When creating tokens with `openapi token create --scopes`, you can use **scope aliases** instead of writing full scope strings.
+
+### How it works
+
+Each API service is mapped to an alias name. When you use an alias, it automatically expands to all available scopes for that service.
+
+| Alias | Service | Domain |
+|---|---|---|
+| `ai` | AI language models | ai.openapi.com |
+| `automotive` | Automotive data | automotive.openapi.com |
+| `cadastre` | Italian cadastral data | catasto.openapi.it |
+| `certified-email` | PEC / Legalmail | pec.openapi.it |
+| `chamber-of-commerce` | Chamber of Commerce | visurecamerali.openapi.it |
+| `company` | Company data | company.openapi.com |
+| `docuengine` | Official documents | docuengine.openapi.com |
+| `domains` | .it domain management | domains.altravia.com |
+| `esignature` | Electronic signature | esignature.openapi.com |
+| `exchange-rate` | Currency exchange rates | exchange.altravia.com |
+| `geocoding` | Geocoding | geocoding.openapi.it |
+| `invoice` | Electronic invoicing | invoice.openapi.com |
+| `massive-rem` | Massive REM | ws.pecmassiva.com |
+| `paying-bills` | Bills payment | ws.pagasubito.it |
+| `pdf` | HTML to PDF | pdf.openapi.it |
+| `postal-service` | Postal mail | ws.ufficiopostale.com |
+| `real-estate` | Real estate valuation | realestate.openapi.com |
+| `risk` | Risk reports and scoring | risk.openapi.com |
+| `sdi` | SDI electronic invoicing | sdi.openapi.it |
+| `sms` | SMS messaging | sms.openapi.com |
+| `time-stamping` | Time stamping | ws.marchetemporali.com |
+| `token` | OAuth token management | oauth.openapi.it |
+| `trust` | Trust verification | trust.openapi.com |
+| `visengine` | Official documents | visengine2.altravia.com |
+| `zip-codes` | Zip codes and municipalities | cap.openapi.it |
+
+### Examples
+
+Create a token with all SMS scopes:
+
+```bash
+openapi token create --scopes "sms"
+```
+
+Create a token with all SMS and Company scopes:
+
+```bash
+openapi token create --scopes "sms,company"
+```
+
+### Method filtering
+
+Prefix an alias with an HTTP method to include only scopes for that method:
+
+```bash
+# Only POST scopes for SMS
+openapi token create --scopes "post:sms"
+
+# Only GET scopes for company
+openapi token create --scopes "get:company"
+
+# Mix methods and full aliases
+openapi token create --scopes "post:sms,get:company,geocoding"
+```
+
+Supported method prefixes: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
+
+### Case insensitive
+
+Aliases and method prefixes are **case insensitive**:
+
+```bash
+openapi token create --scopes "SMS"
+openapi token create --scopes "Post:Sms"
+openapi token create --scopes "POST:SMS"
+```
+
+All of the above are equivalent.
+
+### Literal scopes
+
+If a term does not match any alias, it is passed through as a literal scope:
+
+```bash
+# Mix aliases and literal scopes
+openapi token create --scopes "sms,GET:imprese.openapi.it/base"
+```
+
+## Token Management
+
+```bash
+# List active tokens
+openapi token list
+
+# List all available scopes
+openapi token scopes
+
+# Check credit
+openapi token credit
+
+# Revoke a token
+openapi token revoke --token "token-id"
+```
+
+## Commands
+
+Run `openapi --help` to see all available commands, or `openapi <command> --help` for subcommand details.

oas/00-oas-list.txt oas/00-list.txtoas/00-oas-list.txt renamed to oas/00-list.txt

@@ -15,7 +15,7 @@ impl ApiClient {
         headers.insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
         headers.insert(
             AUTHORIZATION,
-            HeaderValue::from_str(&format!("Bearer {}", config.api_key))?,
+            HeaderValue::from_str(&format!("Bearer {}", config.token))?,
         );
 
         let http = reqwest::Client::builder()
@@ -29,7 +29,7 @@ impl ApiClient {
     }
 
     /// Pick the right base URL depending on sandbox mode
-    pub fn base_url(&self, production: &str, sandbox: &str) -> &str {
+    pub fn base_url<'a>(&self, production: &'a str, sandbox: &'a str) -> &'a str {
         if self.sandbox { sandbox } else { production }
     }
 
@@ -53,16 +53,6 @@ impl ApiClient {
         Ok(body)
     }
 
-    pub async fn put(&self, url: &str, body: &Value) -> Result<Value> {
-        let resp = self.http.put(url).json(body).send().await?;
-        let status = resp.status();
-        let body: Value = resp.json().await?;
-        if !status.is_success() {
-            anyhow::bail!("API error ({}): {}", status, body);
-        }
-        Ok(body)
-    }
-
     pub async fn delete(&self, url: &str) -> Result<Value> {
         let resp = self.http.delete(url).send().await?;
         let status = resp.status();

src/client.rs

@@ -1,51 +1,123 @@
 use anyhow::Result;
+use reqwest::header::{HeaderValue, AUTHORIZATION, CONTENT_TYPE};
+use serde_json::Value;
 
-pub fn execute() -> Result<()> {
+use crate::scopes;
+
+pub async fn execute() -> Result<()> {
     println!("openapi-cli v{}", env!("CARGO_PKG_VERSION"));
     println!();
 
-    let username = std::env::var("OPENAPI_USERNAME").ok();
-    let key = std::env::var("OPENAPI_KEY").ok();
-    let sandbox_key = std::env::var("OPENAPI_SANDBOX_KEY").ok();
+    let token = std::env::var("OPENAPI_TOKEN").ok();
+    let sandbox_token = std::env::var("OPENAPI_SANDBOX_TOKEN").ok();
 
-    let has_username = username.as_ref().is_some_and(|v| !v.is_empty());
-    let has_key = key.as_ref().is_some_and(|v| !v.is_empty());
-    let has_sandbox_key = sandbox_key.as_ref().is_some_and(|v| !v.is_empty());
+    let has_token = token.as_ref().is_some_and(|v| !v.is_empty());
+    let has_sandbox_token = sandbox_token.as_ref().is_some_and(|v| !v.is_empty());
 
     // Show variable status
     println!("Environment variables:");
-    print_var_status("OPENAPI_USERNAME", has_username, &username);
-    print_var_status("OPENAPI_KEY", has_key, &key);
-    print_var_status("OPENAPI_SANDBOX_KEY", has_sandbox_key, &sandbox_key);
+    print_var_status("OPENAPI_TOKEN", has_token, &token);
+    print_var_status("OPENAPI_SANDBOX_TOKEN", has_sandbox_token, &sandbox_token);
     println!();
 
     // Readiness assessment
-    if has_username && has_key && has_sandbox_key {
+    if has_token && has_sandbox_token {
         println!("Status: READY");
         println!("  Production and sandbox environments are both available.");
-    } else if has_username && has_key {
+    } else if has_token {
         println!("Status: READY (production only)");
         println!("  Production environment is available.");
-        println!("  Set OPENAPI_SANDBOX_KEY to enable sandbox mode (-S).");
-    } else if has_username && has_sandbox_key {
+        println!("  Set OPENAPI_SANDBOX_TOKEN to enable sandbox mode (-S).");
+    } else if has_sandbox_token {
         println!("Status: SANDBOX ONLY");
         println!("  Only the sandbox environment is available (use -S flag).");
-        println!("  Set OPENAPI_KEY to enable production mode.");
+        println!("  Set OPENAPI_TOKEN to enable production mode.");
     } else {
         println!("Status: NOT CONFIGURED");
         println!("  The CLI cannot operate. Set the required environment variables:");
-        if !has_username {
-            println!("    export OPENAPI_USERNAME=\"your-username\"");
+        println!("    export OPENAPI_TOKEN=\"your-api-token\"");
+        println!("    export OPENAPI_SANDBOX_TOKEN=\"your-sandbox-token\"  (optional)");
+    }
+
+    // Show token scopes if tokens are available
+    if has_token {
+        println!();
+        println!("Production token scopes:");
+        match fetch_token_scopes(token.as_ref().unwrap(), false).await {
+            Ok(token_scopes) if token_scopes.is_empty() => {
+                println!("  (no scopes)");
+            }
+            Ok(token_scopes) => {
+                print!("{}", scopes::group_scopes_by_service(&token_scopes, false));
+            }
+            Err(e) => {
+                println!("  Unable to retrieve ({})", e);
+            }
         }
-        if !has_key && !has_sandbox_key {
-            println!("    export OPENAPI_KEY=\"your-api-key\"");
-            println!("    export OPENAPI_SANDBOX_KEY=\"your-sandbox-key\"  (optional)");
+    }
+
+    if has_sandbox_token {
+        println!();
+        println!("Sandbox token scopes:");
+        match fetch_token_scopes(sandbox_token.as_ref().unwrap(), true).await {
+            Ok(token_scopes) if token_scopes.is_empty() => {
+                println!("  (no scopes)");
+            }
+            Ok(token_scopes) => {
+                print!("{}", scopes::group_scopes_by_service(&token_scopes, true));
+            }
+            Err(e) => {
+                println!("  Unable to retrieve ({})", e);
+            }
         }
     }
 
     Ok(())
 }
 
+async fn fetch_token_scopes(token: &str, sandbox: bool) -> Result<Vec<String>> {
+    let base = if sandbox {
+        "https://test.oauth.openapi.it"
+    } else {
+        "https://oauth.openapi.it"
+    };
+    let url = format!("{}/token/{}", base, token);
+
+    let mut headers = reqwest::header::HeaderMap::new();
+    headers.insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
+    headers.insert(
+        AUTHORIZATION,
+        HeaderValue::from_str(&format!("Bearer {}", token))?,
+    );
+
+    let client = reqwest::Client::builder()
+        .default_headers(headers)
+        .build()?;
+
+    let resp = client.get(&url).send().await?;
+    let status = resp.status();
+    let body: Value = resp.json().await?;
+
+    if !status.is_success() {
+        let msg = body["message"].as_str().unwrap_or("unknown error");
+        anyhow::bail!("{}", msg);
+    }
+
+    // Response: { "data": [{ "scopes": [...], "token": "...", "expire": ... }], "success": true }
+    let scopes = body["data"]
+        .as_array()
+        .and_then(|arr| arr.first())
+        .and_then(|entry| entry["scopes"].as_array())
+        .map(|arr| {
+            arr.iter()
+                .filter_map(|v| v.as_str().map(String::from))
+                .collect()
+        })
+        .unwrap_or_default();
+
+    Ok(scopes)
+}
+
 fn print_var_status(name: &str, is_set: bool, value: &Option<String>) {
     if is_set {
         let v = value.as_ref().unwrap();
@@ -54,8 +126,8 @@ fn print_var_status(name: &str, is_set: bool, value: &Option<String>) {
         } else {
             "*".repeat(v.len())
         };
-        println!("  {:<25} SET ({})", name, masked);
+        println!("  {:<30} SET ({})", name, masked);
     } else {
-        println!("  {:<25} NOT SET", name);
+        println!("  {:<30} NOT SET", name);
     }
 }