shortcut/nextcloud-integration
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Nextcloud integration tools

Browse Source 
- CLI tools: nextcloud-client, nextcloud-contacts, nextcloud-calendar, nextcloud-mail
- Build script with compile-time credentials
- Skills for all four tools
- Email tool supports IMAP/SMTP with attachment download
This commit is contained in:
WLTBAgent
2026-02-20 17:24:13 +00:00
parent 8d932b1c15
commit 705f41a872
20 changed files with 5043 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

299
skills/nextcloud-contacts/SKILL.md Normal file
View File

@@ -0,0 +1,299 @@
# Nextcloud Contacts Skill
**Purpose:** Manage contacts and address books on Nextcloud servers using the nextcloud-contacts CLI tool.
## Overview
This skill provides contact operations for Nextcloud using the nextcloud-contacts Go binary. The CLI tool handles all CardDAV operations and vCard parsing.
## Prerequisites
- Go compiler (for building CLI tool)
- Nextcloud server URL
- Nextcloud username
- Nextcloud password (for app token retrieval)
- Contacts app enabled on Nextcloud
## Bootstrap Process
**This skill will automatically build all three Nextcloud CLI tools with your app token and then immediately forget all credentials.**
**Step 1: The skill will ask for:**
- Nextcloud server URL (e.g., https://teamworkapps.com)
- Nextcloud username (e.g., wltbagent@shortcutsolutions.net)
- Nextcloud password (your normal login credentials)
**Step 2: The skill will:**
1. **Authenticate to Nextcloud** using your username and password
2. **Retrieve or generate an app token** from Nextcloud settings
3. **Build** all three CLI tools (files, contacts, calendar) with the app token
4. **Verify** that all three binaries were created
5. **Immediately forget** all credentials (username, password, and app token are never stored)
**Step 3: You're ready!**
- Use any tool without passing credentials (app token is embedded at compile time)
- Example: `nextcloud-list-books` (no --url, --user, --token needed)
- Example: `nextcloud-create-contact --name "John" --email "john@example.com"`
**Security Note:**
- **All credentials** (username, password, and app token) are only used during the bootstrap process
- **App token is retrieved automatically** - you don't need to find it manually
- **Credentials are never stored permanently** in any file or environment
- **The app token is embedded** in the compiled binary at build time
- **The compiled binary stays** on your local system only
- **Do not distribute** built binaries outside your trusted environment
## Configuration
All credentials are embedded at compile time via Go ldflags. No runtime configuration needed.
### Build-Time Configuration (Automatic)
The skill will handle this automatically during bootstrap:
```bash
cd projects/nextcloud-integration/tools/go/nextcloud-contacts
go build -ldflags="-X 'main.BuildServerURL=https://teamworkapps.com' \
-X 'main.BuildUsername=wltbagent@shortcutsolutions.net' \
-X 'main.BuildToken=YOUR_APP_TOKEN'" \
-o ~/bin/nextcloud-contacts .
```
### Runtime Configuration (Fallback)
If not set at build time, the tool will check these environment variables:
```bash
export NEXTCLOUD_URL="https://cloud.example.com"
export NEXTCLOUD_USER="your-username"
export NEXTCLOUD_TOKEN="your-app-token"
```
### Command-Line Flags (Fallback)
Override credentials for specific commands using:
- `--url`
- `--user`
- `--token`
**Priority:** Build-time ldflags > Environment variables > Command-line flags
## Tool Reference
All tools can be used without passing credentials.
### `nextcloud-list-books` - List all address books
```bash
nextcloud-list-books
```
**Example:**
```bash
# List all address books
nextcloud-list-books
```
**Output:**
```
Address Books:
--------------
Name: Contacts
Path: contacts
ETag:
Name: Recently contacted
Path: z-app-generated--contactsinteraction--recent
ETag:
```
### `nextcloud-list-contacts` - List contacts in an address book
```bash
# List contacts in default book
nextcloud-list-contacts
# List contacts in specific book
nextcloud-list-contacts --book "work-contacts"
```
**Example:**
```bash
# List contacts
nextcloud-list-contacts
```
**Output:**
```
Contacts in 'contacts':
--------------
UID: 1770849610657274975
ETag: "037658b635c2523a8cf70085e81e4f69"
```
### `nextcloud-get-contact` - Retrieve a specific contact
```bash
# Get contact by UID
nextcloud-get-contact --uid "1770849610657274975"
```
**Example:**
```bash
# Get contact
nextcloud-get-contact --uid "contact-uid"
```
**Output:**
```
Contact: 1770849610657274975
--------------
BEGIN:VCARD
VERSION:3.0
UID:1770849610657274975
FN:John Doe
EMAIL;TYPE=INTERNET:john@example.com
TEL;TYPE=VOICE:555-1234
END:VCARD
```
### `nextcloud-create-contact` - Create a new contact
```bash
# Create contact with fields
nextcloud-create-contact \
--name "John Doe" \
--email "john@example.com" \
--phone "555-1234"
# Create contact from vCard file
nextcloud-create-contact --vcard /path/to/contact.vcf
```
**Example:**
```bash
# Create a contact
nextcloud-create-contact --name "John Doe" --email "john@example.com" --phone "555-1234"
```
**Output:**
```
Contact created successfully
```
### `nextcloud-delete-contact` - Delete a contact
```bash
# Delete contact by UID
nextcloud-delete-contact --uid "1770849610657274975"
```
**Example:**
```bash
# Delete a contact
nextcloud-delete-contact --uid "contact-uid"
```
**Output:**
```
Contact deleted: 1770849610657274975
```
## Use Cases
### 1. Contact Management Workflow
```bash
# Create a new contact
nextcloud-create-contact --name "Jane Smith" --email "jane@example.com" --phone "555-5678"
# Verify contact was created
nextcloud-list-contacts | grep "Jane"
# Retrieve contact details
nextcloud-get-contact --uid "$(nextcloud-list-contacts | grep 'Jane' | awk '{print $2}')"
```
### 2. Bulk Contact Import
```bash
# Import contacts from vCard files
for vcard in contacts/*.vcf; do
nextcloud-create-contact --vcard "$vcard"
done
```
### 3. Contact Search Workflow
```bash
# Search for contact by UID pattern
nextcloud-list-contacts | grep "pattern"
# Get detailed contact info
nextcloud-get-contact --uid "found-uid"
```
### 4. Contact Cleanup
```bash
# List all contacts
nextcloud-list-contacts
# Delete specific contacts
nextcloud-delete-contact --uid "old-contact-uid"
# Verify deletion
nextcloud-list-contacts
```
## vCard Format
The CLI tool generates vCard 3.0 format contacts:
```vcf
BEGIN:VCARD
VERSION:3.0
UID:<timestamp>
FN:<formatted-name>
EMAIL;TYPE=INTERNET:<email>
TEL;TYPE=VOICE:<phone>
ORG:<company>
TITLE:<title>
END:VCARD
```
## Error Handling
The nextcloud-contacts binary provides clear error messages:
| Error | Meaning | Action |
|-------|---------|--------|
| Error: credentials not set at build time | Need to re-bootstrap | Ask skill to re-run bootstrap |
| Error: UID is required for get-contact operation | Missing UID | Provide contact UID |
| Error: contact name is required | Missing name | Provide --name flag |
| unexpected status: 404 | Contact not found | Verify UID and address book |
| unexpected status: 401 | Unauthorized | App token expired, re-bootstrap |
| get contact failed with status: xxx | Read error | Check contact exists |
## Best Practices
1. No runtime configuration needed (credentials embedded)
2. Store UIDs when creating contacts for later retrieval
3. Verify operations by listing after create/delete
4. Handle vCard format when importing from files
5. Use display names not paths when referring to address books
## Dependencies
- `~/bin/nextcloud-contacts` - Go binary for CardDAV operations
- No external XML parsing needed (handled by Go)
- vCard files use standard RFC 6350 format
## Related Skills
- **nextcloud-files** - For storing contact photos as files
- **nextcloud-calendar** - For linking contacts to calendar events
---
*OpenClaw skill wrapper for nextcloud-contacts Go binary with automatic app token retrieval*