@uipath/integrationservice-tool 0.1.5

package/README.md

@@ -0,0 +1,435 @@
+# Integration Service Tool
+
+`uip` plugin for managing UiPath Integration Service connectors, connections, and operations.
+
+## Overview
+
+The Integration Service Tool provides a comprehensive CLI interface for:
+- **Connectors**: Browse and discover available integration connectors
+- **Connections**: Create and manage OAuth-authenticated connections
+- **Resources**: Discover, inspect, and execute operations on connector resources
+- **Activities**: List integration activities for workflows
+
+## Usage
+
+### Connectors
+
+List and explore available integration connectors:
+
+```bash
+# List all available connectors
+uip is connectors list
+
+# Get details for a specific connector
+uip is connectors get <connector-key>
+
+# Examples
+uip is connectors list --format json
+uip is connectors get uipath-zoho-desk
+uip is connectors get uipath-salesforce-sfdc
+```
+
+**Available Options:**
+- `-t, --tenant <name>` - Specify tenant (optional)
+- `--format <format>` - Output format: table, json, yaml, plain (default: table)
+
+---
+
+### Connections
+
+Manage connections to external services:
+
+```bash
+# List connections for a connector
+uip is connections list <connector-key> [--folder-key <key>]
+
+# Ping a connection to check if it's active
+uip is connections ping <connection-id>
+
+# Create a new connection (OAuth flow)
+uip is connections create <connector-key>
+
+# Re-authenticate an existing connection
+uip is connections edit <connection-id>
+
+# Examples
+uip is connections list uipath-outlook-365
+uip is connections list uipath-salesforce-sfdc --folder-key my-folder-key
+uip is connections ping 73ca047b-24dd-4789-a37e-e7afb67654cd
+uip is connections create uipath-doist-todoist
+uip is connections create uipath-zoho-desk --no-browser
+uip is connections edit 73ca047b-24dd-4789-a37e-e7afb67654cd
+```
+
+**Available Options:**
+- `--folder-key <key>` - Filter connections by folder key (optional, for list command only)
+- `-t, --tenant <name>` - Specify tenant (optional)
+- `--format <format>` - Output format: table, json, yaml, plain (default: table)
+- `--refresh` - Force re-fetch from API, ignoring cache (for list command only)
+- `--no-browser` - Don't auto-open browser (for create/edit commands only)
+
+**Connection States:**
+
+When listing connections, the output includes a `State` field. Only `Enabled` connections can be used for operations. If all connections are not enabled, the output will include a warning with instructions to fix them.
+
+| State | Description | Action |
+|-------|-------------|--------|
+| `Enabled` | Active and ready for operations | No action needed |
+| `Disabled` | Connection is disabled | Run `edit` to re-authenticate |
+| `Error` | Connection has an error | Run `edit` to re-authenticate or `create` a new one |
+
+**Connection Create Flow:**
+1. Initiates OAuth session
+2. Opens authentication URL in browser
+3. Polls session status every 5 seconds
+4. Shows connection details on success
+
+**Connection Ping:**
+
+Check if a connection is active before performing operations:
+
+```bash
+# Ping a connection to verify it's enabled
+uip is connections ping <connection-id>
+
+# Example
+uip is connections ping 73ca047b-24dd-4789-a37e-e7afb67654cd
+```
+
+If the connection is not enabled, the output will instruct you to run `edit` or `create` a new connection.
+
+**Connection Edit (Re-authenticate):**
+
+Re-authenticate an existing connection when it becomes disabled or expired:
+
+```bash
+# Re-authenticate a connection
+uip is connections edit <connection-id>
+
+# Without auto-opening browser
+uip is connections edit <connection-id> --no-browser
+
+# Example
+uip is connections edit 73ca047b-24dd-4789-a37e-e7afb67654cd
+```
+
+The edit flow is similar to create — it opens a browser for OAuth authentication and polls until complete.
+
+---
+
+### Activities
+
+List integration activities for use in workflows:
+
+```bash
+# List non-trigger activities for a connector
+uip is activities list <connector-key>
+
+# Examples
+uip is activities list uipath-zoho-desk
+uip is activities list uipath-salesforce-sfdc --format json
+```
+
+**Available Options:**
+- `-t, --tenant <name>` - Specify tenant (optional)
+- `--format <format>` - Output format: table, json, yaml, plain (default: table)
+
+**Note:** Only non-trigger activities are returned (filtered by `isTrigger: false`)
+
+---
+
+### Resources
+
+Discover, inspect, and execute operations on connector resources (objects).
+
+```
+uip is resources --help
+
+Commands:
+  list                          List available objects for a connector
+  describe                      Describe object fields and operations
+  execute                       Execute data operations on a connector
+```
+
+#### List Available Objects
+
+List all resource objects for a connector, optionally filtered by operation type.
+
+```bash
+# List all objects for a connector
+uip is resources list uipath-zoho-desk
+
+# Filter by operation type
+uip is resources list uipath-salesforce-sfdc --operation Create
+uip is resources list uipath-salesforce-sfdc --operation List --connection-id <id>
+```
+
+**Available Options:**
+- `--operation <operation>` - Filter by operation: List, Retrieve, Create, Update, Delete, Replace
+- `--connection-id <id>` - Connection/Instance ID (optional)
+- `-t, --tenant <name>` - Specify tenant (optional)
+- `--format <format>` - Output format: table, json, yaml, plain (default: table)
+
+#### Describe Object Metadata
+
+Retrieve field metadata for a specific resource object. Use `--operation` to filter and return only the fields relevant to a specific HTTP method.
+
+```bash
+# Get full metadata for an object
+uip is resources describe uipath-salesforce-sfdc Account
+uip is resources describe uipath-zoho-desk create_ticket --connection-id <id>
+
+# Get only Create (POST) fields in compact format
+uip is resources describe uipath-zoho-desk tickets --operation Create
+
+# Get only List (GET) fields in compact format
+uip is resources describe uipath-zoho-desk departments --operation List
+
+# Retrieve (GET by ID) fields
+uip is resources describe uipath-zoho-desk tickets --operation Retrieve
+
+# Combine with connection ID
+uip is resources describe uipath-salesforce-sfdc Account --connection-id <id> --operation List
+```
+
+**Available Options:**
+- `--operation <operation>` - Filter fields by operation: List, Retrieve, Create, Update, Delete, Replace
+- `--connection-id <id>` - Connection/Instance ID (optional)
+- `-t, --tenant <name>` - Specify tenant (optional)
+- `--format <format>` - Output format: table, json, yaml, plain (default: json)
+
+#### Execute Data Operations
+
+Execute CRUD operations against live data through a connection. The `execute` subgroup provides verb-based subcommands with a consistent signature:
+
+```
+uip is resources execute <verb> <connector-key> <object-name> --connection-id <id> [options]
+```
+
+```
+uip is resources execute --help
+
+Commands:
+  create   <connector-key> <object-name>   Create a new record
+  list     <connector-key> <object-name>   List all records
+  get      <connector-key> <object-name>   Get a record by ID
+  update   <connector-key> <object-name>   Update a record
+  replace  <connector-key> <object-name>   Replace a record
+  delete   <connector-key> <object-name>   Delete a record
+```
+
+**Create a record:**
+```bash
+uip is resources execute create uipath-zoho-desk tickets \
+  --connection-id <id> \
+  --body '{"subject":"New ticket","priority":"High"}'
+```
+
+**List all records:**
+```bash
+uip is resources execute list uipath-zoho-desk tickets \
+  --connection-id <id>
+
+# With query parameters
+uip is resources execute list uipath-zoho-desk tickets \
+  --connection-id <id> \
+  --query "limit=10&offset=0"
+```
+
+**Get a record by ID:**
+```bash
+uip is resources execute get uipath-zoho-desk tickets \
+  --connection-id <id> \
+  --query "id=123"
+```
+
+**Update a record:**
+```bash
+uip is resources execute update uipath-zoho-desk tickets \
+  --connection-id <id> \
+  --body '{"status":"closed"}' \
+  --query "id=123"
+```
+
+**Replace a record:**
+```bash
+uip is resources execute replace uipath-zoho-desk tickets \
+  --connection-id <id> \
+  --body '{"subject":"Replaced ticket","priority":"Low"}'
+```
+
+**Delete a record:**
+```bash
+uip is resources execute delete uipath-zoho-desk tickets \
+  --connection-id <id> \
+  --query "id=123"
+```
+
+**Available Options (all execute subcommands):**
+- `--connection-id <id>` - Connection/Instance ID (required)
+- `--body <json>` - Request body as JSON string (required for create, update, replace)
+- `--query <params>` - Query parameters as key=value pairs, separated by `&`
+- `-t, --tenant <name>` - Specify tenant (optional)
+- `--format <format>` - Output format: table, json, yaml, plain (default: json)
+
+---
+
+## Common Options
+
+All commands support these common options:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-t, --tenant <name>` | Specify tenant name | From login session |
+| `--format <format>` | Output format | `table` |
+| `-h, --help` | Show command help | - |
+
+**Available Formats:**
+- `table` - Formatted table output (default for most commands)
+- `json` - JSON output
+- `yaml` - YAML output
+- `plain` - Plain text output
+
+---
+
+## Examples
+
+### Complete Workflow Example
+
+```bash
+# 1. Find a connector
+uip is connectors list --format json | grep salesforce
+
+# 2. Get connector details
+uip is connectors get uipath-salesforce-sfdc
+
+# 3. List connections to get connection ID
+uip is connections list uipath-salesforce-sfdc
+
+# 4. If no connections exist, create one
+uip is connections create uipath-salesforce-sfdc
+
+# 5. Verify connection is enabled (skip if list already shows Enabled)
+uip is connections ping <connection-id>
+
+# 6. If connection is not enabled, re-authenticate
+uip is connections edit <connection-id>
+
+# 7. List available resources with connection-specific data
+uip is resources list uipath-salesforce-sfdc --connection-id <connection-id> --operation Create
+
+# 8. Describe the object to see required fields
+uip is resources describe uipath-salesforce-sfdc accounts --connection-id <connection-id> --operation Create
+
+# 9. Create a record
+uip is resources execute create uipath-salesforce-sfdc accounts \
+  --connection-id <connection-id> \
+  --body '{"Name":"Acme Corporation","Industry":"Technology"}'
+
+# 10. List records
+uip is resources execute list uipath-salesforce-sfdc accounts \
+  --connection-id <connection-id>
+
+# 11. List activities for workflow design
+uip is activities list uipath-salesforce-sfdc
+```
+
+### Multi-Environment Support
+
+```bash
+# Use with different environments
+uip is connectors list  # Uses default from login
+uip is connectors list -t production-tenant
+uip is connectors list -t staging-tenant
+```
+
+---
+
+## Authentication
+
+All commands require authentication via `uip login`:
+
+```bash
+# Login to UiPath
+uip login
+
+# Login to specific environment
+uip login --url https://alpha.uipath.com
+uip login --url https://cloud.uipath.com
+```
+
+The tool automatically uses the access token from your login session.
+
+---
+
+## MCP Server (AI Integration)
+
+**Claude can now invoke these commands automatically!**
+
+The uip MCP server exposes all Integration Service commands to Claude Desktop, enabling natural language automation:
+
+```json
+// ~/.config/claude/claude_desktop_config.json
+{
+  "mcpServers": {
+    "uipath-integration-service": {
+      "command": "uip",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+**Examples of what Claude can do:**
+- **"Send a message to slack channel test-slack"** - Claude finds the channel ID, gets required fields from metadata, and sends the message
+- **"Create a Salesforce account named 'Acme Corp'"** - Claude discovers the schema and creates the record
+- **"List all open tickets in Zoho Desk"** - Claude executes the query and formats results
+
+**How it works:**
+1. Claude discovers available connectors and operations
+2. Reads metadata to understand required fields
+3. Looks up IDs by names (channel names → channel IDs)
+4. Chooses default connections automatically
+5. Executes operations with proper formatting
+
+**📖 Full documentation:** See [MCP.md](./MCP.md) for setup, examples, and advanced workflows.
+
+---
+
+## API Endpoints
+
+The tool interacts with these Integration Service APIs:
+
+| Command | Endpoint |
+|---------|----------|
+| `connectors list` | `GET /connections_/api/v1/Connectors` |
+| `connectors get` | `GET /connections_/api/v1/Connectors/{key}` |
+| `connections list` | `GET /connections_/api/v1/Connectors/{key}/connections` |
+| `connections create` | `POST /connections_/api/v1/Connections` |
+| `connections ping` | `GET /connections_/api/v1/Connections/{id}/ping` |
+| `connections edit` | `POST /connections_/api/v1/Connections/{id}/auth` |
+| `activities list` | `GET /elements_/v3/element/elements/{key}/activities` |
+| `resources list` | `GET /elements_/v3/element/[instances/{id}/]elements/{key}/objects` |
+| `resources describe` | `GET /elements_/v3/element/[instances/{id}/]elements/{key}/objects/{name}/metadata` |
+| `resources execute *` | `{METHOD} /elements_/v3/element/instances/{id}/{objectName}` |
+
+---
+
+## Versions
+
+### integrationservice-tool 0.0.1
+
+**Features:**
+- List and get connectors
+- List connections (with folder filtering and status warnings)
+- Create connections (OAuth flow with browser opening)
+- Ping connections (verify connection is active)
+- Edit/re-authenticate connections (OAuth re-auth flow)
+- List and describe resources (filtered by operation, with metadata caching)
+- List activities (non-trigger only)
+- Execute CRUD operations on resources (create, list, get, update, replace, delete)
+- File-based metadata caching for token optimization
+- Multi-format output (table, json, yaml, plain)
+- Multi-environment support
+- Query parameters and request body support
+