feat(examples): add comprehensive API examples

examples/README.md

@@ -0,0 +1,75 @@
+# 1Password Rust SDK Examples
+
+## Prerequisites
+
+- A [1Password Service Account](https://developer.1password.com/docs/service-accounts/) token, or the 1Password desktop app installed and running
+- A vault ID to use for item operations (the service account must have full CRUD permissions on this vault)
+- `ssh-keygen` available on PATH (used to generate SSH keys for the SSH key example)
+
+## Examples
+
+### `service_account.rs` — Minimal service account auth
+
+Authenticates with a service account token and resolves a single secret.
+
+```sh
+export OP_SERVICE_ACCOUNT_TOKEN="ops_..."
+export OP_SECRET_REF="op://vault/item/field"  # optional, defaults to op://vault/item/field
+cargo run --example service_account
+```
+
+### `example.rs` — Comprehensive API usage
+
+Demonstrates the full SDK surface using a service account:
+
+- **Secrets**: resolve single and batch references, validate references
+- **Passwords**: generate PIN, memorable, and random passwords
+- **Items**: create with fields/sections/tags/websites, list with filters, update, archive, delete
+- **Batch operations**: create, get, and delete multiple items at once
+- **Item sharing**: get account policy, validate recipients, create share link
+- **SSH keys**: create an SSH key item (generates an Ed25519 key at runtime)
+- **Documents**: create a document item, replace its content, read it back
+- **File fields**: attach a file to an item, read it, delete the file field
+- **Vaults**: create, list, get overview, get with accessors, update, delete
+
+```sh
+export OP_SERVICE_ACCOUNT_TOKEN="ops_..."
+export OP_VAULT_ID="..."
+export OP_SHARE_RECIPIENT="user@example.com"  # optional, for item sharing demo
+cargo run --example example
+```
+
+### `desktop_app.rs` — Desktop app integration
+
+Demonstrates the same operations using the 1Password desktop app for authentication, plus group permission management (grant, update, revoke).
+
+```sh
+export OP_ACCOUNT="my.1password.com"
+export OP_VAULT_ID="..."
+export OP_GROUP_ID="..."  # optional, for group permissions demo
+cargo run --example desktop_app --features desktop
+```
+
+## Operations Covered
+
+| Operation | `example.rs` | `desktop_app.rs` |
+|---|:-:|:-:|
+| Authenticate (service account) | ✓ | |
+| Authenticate (desktop app) | | ✓ |
+| Resolve secrets | ✓ | ✓ |
+| Resolve all (batch) | ✓ | |
+| Validate secret reference | ✓ | |
+| Generate passwords | ✓ | |
+| Create item (fields, sections, tags, websites) | ✓ | |
+| List items (with filters) | ✓ | ✓ |
+| Update item | ✓ | |
+| Archive item | ✓ | |
+| Delete item | ✓ | |
+| Batch create/get/delete | ✓ | ✓ |
+| Share item | ✓ | |
+| SSH key item | ✓ | |
+| Document item (create, replace, read) | ✓ | |
+| File field (attach, read, delete) | ✓ | |
+| List vaults | ✓ | ✓ |
+| Vault CRUD | ✓ | ✓ |
+| Group permissions (grant, update, revoke) | | ✓ |

examples/desktop_app.rs

@@ -1,24 +1,247 @@
 #[cfg(feature = "desktop")]
 fn main() {
-    use onepassword_sdk::{Client, SecretsApi};
+    use onepassword_sdk::{
+        Client, GroupAccess, GroupGetParams, GroupVaultAccess, GroupsApi, ItemCategory,
+        ItemCreateParams, ItemsApi, SdkError, SecretsApi, VaultCreateParams, VaultGetParams,
+        VaultUpdateParams, VaultsApi, permissions,
+    };
 
     let account = std::env::var("OP_ACCOUNT")
         .expect("Set OP_ACCOUNT to your 1Password sign-in address (e.g. my.1password.com)");
-    let secret_ref = std::env::var("OP_SECRET_REF")
-        .unwrap_or_else(|_| "op://MyVault/Example/username".to_string());
+    let vault_id =
+        std::env::var("OP_VAULT_ID").expect("Set OP_VAULT_ID to a vault ID in your account");
+    let group_id = std::env::var("OP_GROUP_ID").ok();
 
     let client = Client::builder()
         .desktop_app_integration(&account)
-        .integration_info("1Password Rust SDK Example", "v0.1.0")
+        .integration_info("1Password Rust SDK Example", "v1.0.0")
         .build()
-        .expect("Failed to create client");
+        .expect("Failed to create client — is 1Password desktop app running?");
 
-    let secret = client
+    // --- Resolve a secret ---
+    let secret_ref = std::env::var("OP_SECRET_REF")
+        .unwrap_or_else(|_| "op://MyVault/Example/username".to_string());
+    client
         .secrets()
         .resolve(&secret_ref)
         .expect("Failed to resolve secret");
+    println!("Secret resolved successfully");
+
+    // --- List vaults ---
+    let vaults = client.vaults().list(None).expect("Failed to list vaults");
+    println!("\nVaults ({}):", vaults.len());
+    for vault in &vaults {
+        println!("  - {} ({:?})", vault.title, vault.vault_type);
+    }
+
+    // --- List items ---
+    let items = client
+        .items()
+        .list(&vault_id, &[])
+        .expect("Failed to list items");
+    println!("\nItems in vault ({}):", items.len());
+    for item in items.iter().take(5) {
+        println!("  - {} ({:?})", item.title, item.category);
+    }
+
+    // --- Vault CRUD ---
+    vault_operations(&client);
+
+    // --- Batch item operations ---
+    batch_item_operations(&client, &vault_id);
+
+    // --- Group permissions ---
+    group_permission_operations(&client, &group_id).expect("Group permission operations failed");
+
+    println!("\nAll desktop app examples completed successfully.");
+
+    fn vault_operations(client: &Client) {
+        println!("\n=== Vault Operations ===");
+
+        let vault = client
+            .vaults()
+            .create(VaultCreateParams {
+                title: "Desktop SDK Example Vault".to_string(),
+                description: Some("Created via desktop app integration".to_string()),
+                allow_admins_access: Some(true),
+            })
+            .expect("Failed to create vault");
+        println!("Created vault: {} ({})", vault.title, vault.id);
+
+        let overview = client
+            .vaults()
+            .get_overview(&vault.id)
+            .expect("Failed to get vault overview");
+        println!(
+            "Vault: {} — {} items",
+            overview.title, overview.active_item_count
+        );
+
+        let full = client
+            .vaults()
+            .get(
+                &vault.id,
+                VaultGetParams {
+                    accessors: Some(true),
+                },
+            )
+            .expect("Failed to get vault details");
+        println!(
+            "Vault accessors: {}",
+            full.access.as_ref().map_or(0, |a| a.len())
+        );
+
+        let updated = client
+            .vaults()
+            .update(
+                &vault.id,
+                VaultUpdateParams {
+                    title: Some("Desktop SDK Example Vault (Updated)".to_string()),
+                    description: None,
+                },
+            )
+            .expect("Failed to update vault");
+        println!("Updated vault: {}", updated.title);
+
+        client
+            .vaults()
+            .delete(&vault.id)
+            .expect("Failed to delete vault");
+        println!("Deleted vault: {}", vault.id);
+    }
+
+    fn batch_item_operations(client: &Client, vault_id: &str) {
+        println!("\n=== Batch Item Operations ===");
+
+        let params: Vec<ItemCreateParams> = (1..=3)
+            .map(|i| ItemCreateParams {
+                category: ItemCategory::SecureNote,
+                vault_id: vault_id.to_string(),
+                title: format!("Desktop Batch Note {i}"),
+                fields: None,
+                sections: None,
+                notes: Some(format!("Batch note #{i} via desktop app")),
+                tags: Some(vec!["desktop-batch".to_string()]),
+                websites: None,
+                files: None,
+                document: None,
+            })
+            .collect();
+
+        let response = client
+            .items()
+            .create_all(vault_id, &params)
+            .expect("Failed to batch create items");
+
+        let mut created_ids = Vec::new();
+        for resp in &response.individual_responses {
+            match (&resp.content, &resp.error) {
+                (Some(item), _) => {
+                    println!("  Created: {} ({})", item.title, item.id);
+                    created_ids.push(item.id.clone());
+                }
+                (_, Some(err)) => println!("  Error: {err:?}"),
+                _ => {}
+            }
+        }
+
+        let get_response = client
+            .items()
+            .get_all(vault_id, &created_ids)
+            .expect("Failed to batch get items");
+        for resp in &get_response.individual_responses {
+            match (&resp.content, &resp.error) {
+                (Some(item), _) => println!("  Got: {} (v{})", item.title, item.version),
+                (_, Some(err)) => println!("  Error: {err:?}"),
+                _ => {}
+            }
+        }
+
+        let delete_response = client
+            .items()
+            .delete_all(vault_id, &created_ids)
+            .expect("Failed to batch delete items");
+        for (id, resp) in &delete_response.individual_responses {
+            if let Some(err) = &resp.error {
+                println!("  Failed to delete {id}: {err:?}");
+            }
+        }
+        println!("Batch deleted {} items", created_ids.len());
+    }
+
+    fn group_permission_operations(
+        client: &Client,
+        group_id: &Option<String>,
+    ) -> Result<(), SdkError> {
+        println!("\n=== Group Permission Operations ===");
+
+        let group_id = match group_id {
+            Some(id) => id,
+            None => {
+                println!("Skipping group permissions (set OP_GROUP_ID to test)");
+                return Ok(());
+            }
+        };
+
+        // Get group info
+        let group = client.groups().get(
+            group_id,
+            GroupGetParams {
+                vault_permissions: Some(true),
+            },
+        )?;
+        println!("Group: {} ({:?})", group.title, group.group_type);
+
+        // Create a temporary vault for the permissions demo
+        let temp_vault = client.vaults().create(VaultCreateParams {
+            title: "SDK Permissions Demo (temp)".to_string(),
+            description: Some("Temporary vault for group permissions demo".to_string()),
+            allow_admins_access: Some(true),
+        })?;
+        let temp_vault_id = temp_vault.id.clone();
+        println!(
+            "Created temp vault: {} ({})",
+            temp_vault.title, temp_vault_id
+        );
+
+        let result = (|| -> Result<(), SdkError> {
+            // Grant read + reveal permissions to the group on the temp vault
+            client.vaults().grant_group_permissions(
+                &temp_vault_id,
+                &[GroupAccess {
+                    group_id: group_id.to_string(),
+                    permissions: permissions::READ_ITEMS | permissions::REVEAL_ITEM_PASSWORD,
+                }],
+            )?;
+            println!("Granted read permissions to group on vault");
+
+            // Update to also allow creating items
+            client
+                .vaults()
+                .update_group_permissions(&[GroupVaultAccess {
+                    vault_id: temp_vault_id.clone(),
+                    group_id: group_id.to_string(),
+                    permissions: permissions::READ_ITEMS
+                        | permissions::REVEAL_ITEM_PASSWORD
+                        | permissions::CREATE_ITEMS,
+                }])?;
+            println!("Updated group permissions to include create");
+
+            // Revoke all permissions
+            client
+                .vaults()
+                .revoke_group_permissions(&temp_vault_id, group_id)?;
+            println!("Revoked group permissions");
+
+            Ok(())
+        })();
+
+        // Always clean up the temp vault (best-effort)
+        let _ = client.vaults().delete(&temp_vault_id);
+        println!("Deleted temp vault: {temp_vault_id}");
 
-    println!("Secret length: {}", secret.len());
+        result
+    }
 }
 
 #[cfg(not(feature = "desktop"))]