n8n-nodes-steyi-ss 1.0.0 → 1.0.1

package/README.md

@@ -1,34 +1,88 @@
 # n8n-nodes-steyi-ss
 
-An n8n community node for integrating with the Smartsheet API.
+An n8n community node for integrating with the Smartsheet API. This comprehensive node provides full access to Smartsheet's API capabilities including sheets, rows, columns, webhooks, reports, and administrative functions.
 
 ## Features
 
-This node provides the following operations:
+This node provides extensive operations across multiple Smartsheet resources:
 
 ### Sheet Operations
-- **List Sheets** - Get a list of all sheets in your Smartsheet account
-- **Get Sheet** - Retrieve detailed information about a specific sheet
-- **Create Sheet** - Create a new sheet
+- **List Sheets** - Get a list of all sheets in your Smartsheet account (with pagination support)
+- **Get Sheet** - Retrieve detailed information about a specific sheet with optional include parameters (attachments, discussions, format, etc.)
+- **Create Sheet** - Create a new sheet with custom columns, optionally in a workspace or folder
 - **Update Sheet** - Update a sheet name
 - **Delete Sheet** - Delete a sheet
 
 ### Row Operations
-- **Add Row** - Add a new row to a sheet (with optional discussions, comments, and attachments)
-- **Update Row** - Update an existing row in a sheet (with optional discussions, comments, and attachments)
+- **Add Row** - Add a new row to a sheet with:
+  - Cell data (supports all column types including multi-contact lists and multi-picklists)
+  - Location options (Top, Bottom, or as child of a parent row)
+  - Discussions (add to existing or create new)
+  - Attachments (file uploads or links, with proof support)
+- **Update Row** - Update an existing row with the same options as Add Row
 - **Delete Row** - Delete a row from a sheet
+- **Get Row** - Get details of a specific row with include/exclude parameters
+- **Get Row (Mapped)** - Get a row with cells mapped by column title or column ID, including all original response data
+
+**Special Row Features:**
+- **Multi-Contact List Support** - Automatically formats comma-separated email lists for `MULTI_CONTACT_LIST` columns
+- **Multi-Picklist Support** - Handles `MULTI_PICKLIST` columns with proper formatting
+- **Attachment Types** - Support for both file uploads (binary data) and link attachments
+- **Proof Attachments** - Special attachment type for row proofs
+- **Discussion Management** - Add comments to existing discussions or create new discussions
+- **Location Control** - Specify row placement (top, bottom, or as child of parent row)
 
 ### Column Operations
-- **Get Columns** - Get all columns from a sheet
+- **Get Columns** - Get all columns from a sheet with column metadata
+- **Update Column** - Update column properties:
+  - Title
+  - Index (position)
+  - Column type (TEXT_NUMBER, DATE, CHECKBOX, CONTACT_LIST, MULTI_CONTACT_LIST, PICKLIST, MULTI_PICKLIST, DURATION, PREDECESSOR, etc.)
+  - Options (for PICKLIST and MULTI_PICKLIST types)
 
 ### Webhook Operations
 - **List Webhooks** - List all webhooks in your account
-- **Create Webhook** - Create a new webhook for a sheet
+- **Create Webhook** - Create a new webhook for a sheet:
+  - Auto-generates callback URL from `WEBHOOK_URL` environment variable
+  - Customizable webhook name
+  - Event selection (all events or specific events like `sheet.rowCreated`, `sheet.rowUpdated`, etc.)
 - **Update Webhook** - Update webhook settings (name, enabled status, events)
 - **Delete Webhook** - Delete a webhook
 
+### Report Operations
+- **List Reports** - Get a list of all reports in your account
+- **Get Report** - Retrieve detailed information about a specific report with include/exclude parameters
+
+### Admin Operations
+
+#### User Management
+- **List Users** - Get a list of all users in your account
+- **Get User** - Get details of a specific user (by ID or from dropdown)
+- **Add User** - Add a new user with:
+  - Email (required)
+  - First name and last name
+  - Admin privileges
+  - Licensed sheet creator status
+- **Update User** - Update user properties
+- **Delete User** - Delete a user
+
+#### Group Management
+- **List Groups** - Get a list of all groups in your account
+- **Get Group** - Get details of a specific group (by ID or from dropdown)
+- **Create Group** - Create a new group with name and description
+- **Update Group** - Update group name and description
+- **Delete Group** - Delete a group
+
+#### Group Member Management
+- **List Group Members** - Get all members of a group
+- **Add Group Members** - Add members to a group by email address (supports any email, not just existing contacts)
+- **Remove Group Member** - Remove a member from a group
+
 ### Webhook Trigger
-- **Smartsheet Trigger** - A trigger node that starts workflows when Smartsheet events occur
+- **Steyi Smartsheet Trigger** - A trigger node that starts workflows when Smartsheet events occur:
+  - Automatically creates and manages webhooks
+  - Supports sheet-level events
+  - Handles webhook challenge/verification
 
 ## Installation
 
@@ -58,22 +112,12 @@ npm install n8n-nodes-steyi-ss
    # Then restart n8n
    ```
 
-For detailed deployment instructions, see [DEPLOYMENT.md](./DEPLOYMENT.md).
-4. Link the node to your n8n installation:
-   ```bash
-   npm link
-   ```
-5. In your n8n installation directory, link the node:
-   ```bash
-   npm link n8n-nodes-steyi-ss
-   ```
-
 ## Configuration
 
 ### Credentials
 
 1. Go to your n8n credentials settings
-2. Add a new "Smartsheet API" credential
+2. Add a new "Steyi Smartsheet API" credential
 3. Enter your Smartsheet API access token
 
 To get your API token:
@@ -83,67 +127,271 @@ To get your API token:
 
 ## Usage
 
-### List Sheets
+### Dynamic Dropdowns
 
-Use this operation to retrieve all sheets in your account. No additional parameters are required.
+The node provides dynamic dropdowns for:
+- **Sheets** - Automatically loads all available sheets
+- **Columns** - Loads columns for the selected sheet
+- **Users** - Lists all users in your account
+- **Groups** - Lists all groups in your account
+- **Group Members** - Lists members of the selected group
+- **Workspaces** - Lists available workspaces for sheet creation
+- **Folders** - Lists folders within a selected workspace
+- **Webhooks** - Lists existing webhooks by name
+- **Discussions** - Lists existing discussions for a row
 
-### Get Sheet
+All dropdowns support manual ID entry via expressions if needed.
 
-Retrieve detailed information about a specific sheet:
-- **Sheet ID**: The ID of the sheet you want to retrieve
-- **Include** (optional): Additional fields to include (attachments, discussions, format, etc.)
+### Sheet Operations
 
-### Get Columns
+#### List Sheets
+Retrieves all sheets in your account. Supports pagination to fetch all sheets.
 
-Get all columns from a specific sheet:
-- **Sheet ID**: The ID of the sheet
+#### Get Sheet
+Retrieve detailed information about a specific sheet:
+- **Sheet ID**: Select from dropdown or enter manually
+- **Include** (optional): Additional fields to include:
+  - `attachments` - Sheet attachments
+  - `cellLinks` - Cell links
+  - `discussions` - Sheet discussions
+  - `format` - Formatting information
+  - `objectValue` - Object values
+  - `rowAttachments` - Row attachments
+  - `rowPermalink` - Row permalinks
+  - `source` - Source information
+
+#### Create Sheet
+Create a new sheet:
+- **Sheet Name**: Name for the new sheet
+- **Workspace** (optional): Select a workspace to create the sheet in
+- **Folder** (optional): Select a folder within the workspace
+- **Columns**: Define columns with:
+  - Title
+  - Type (TEXT_NUMBER, DATE, CHECKBOX, CONTACT_LIST, MULTI_CONTACT_LIST, PICKLIST, MULTI_PICKLIST, DURATION, PREDECESSOR, etc.)
+  - Primary column flag
+  - Options (for PICKLIST and MULTI_PICKLIST types)
+
+#### Update Sheet
+Update a sheet name:
+- **Sheet ID**: Select from dropdown or enter manually
+- **Name**: New name for the sheet
+
+#### Delete Sheet
+Delete a sheet:
+- **Sheet ID**: Select from dropdown or enter manually
 
-### Add Row
+### Row Operations
 
+#### Add Row
 Add a new row to a sheet:
-- **Sheet ID**: The ID of the sheet
+- **Sheet ID**: Select from dropdown or enter manually
 - **Cells**: Array of cells with Column ID and Value
-- **To Top** (optional): Whether to add the row to the top of the sheet
-
-### Update Row
-
-Update an existing row:
-- **Sheet ID**: The ID of the sheet
+- **Special Options** (optional): Enable additional features:
+  - **Location**: Control row placement
+    - `Top` - Add to top of sheet
+    - `Bottom` - Add to bottom of sheet
+    - `Use Parent Row` - Add as child of parent row (requires Parent Row ID)
+  - **Discussions**: Add discussions to the row
+    - Add to existing discussion or create new
+    - Comment text
+  - **Attachments**: Add attachments to the row
+    - File upload (binary data) or link
+    - Attachment category (Regular Attachment or Proof)
+    - Custom filename
+
+**Multi-Contact List Formatting:**
+When adding or updating rows with `MULTI_CONTACT_LIST` columns, you can provide:
+- Comma-separated email string: `"email1@example.com, email2@example.com"`
+- JSON array: `["email1@example.com", "email2@example.com"]`
+
+The node automatically formats these for the Smartsheet API.
+
+**Multi-Picklist Formatting:**
+For `MULTI_PICKLIST` columns, provide:
+- Comma-separated options: `"Option 1, Option 2"`
+- JSON array: `["Option 1", "Option 2"]`
+
+#### Update Row
+Update an existing row with the same options as Add Row:
+- **Sheet ID**: Select from dropdown or enter manually
 - **Row ID**: The ID of the row to update
-- **Cells**: Array of cells with Column ID and Value to update
-
-### Delete Row
+- **Cells**: Updated cell values
+- **Special Options**: Same as Add Row
 
+#### Delete Row
 Delete a row from a sheet:
-- **Sheet ID**: The ID of the sheet
+- **Sheet ID**: Select from dropdown or enter manually
 - **Row ID**: The ID of the row to delete
 
+#### Get Row
+Get details of a specific row:
+- **Sheet ID**: Select from dropdown or enter manually
+- **Row ID**: The ID of the row
+- **Include** (optional): Fields to include (same options as Get Sheet)
+- **Exclude** (optional): Fields to exclude
+
+#### Get Row (Mapped)
+Get a row with cells mapped by column:
+- **Sheet ID**: Select from dropdown or enter manually
+- **Row ID**: The ID of the row
+- **Mapping Type**: 
+  - `By Column Title` - Map cells by column title (default)
+  - `By Column ID` - Map cells by column ID (still includes column title)
+- **Include** (optional): Fields to include
+- **Exclude** (optional): Fields to exclude
+
+Returns a `mapped` object with cell values keyed by column title/ID, plus all original response data.
+
+### Column Operations
+
+#### Get Columns
+Get all columns from a sheet:
+- **Sheet ID**: Select from dropdown or enter manually
+
+Returns column metadata including ID, title, type, index, and options.
+
+#### Update Column
+Update column properties:
+- **Sheet ID**: Select from dropdown or enter manually
+- **Column ID**: Select from dropdown or enter manually
+- **Title** (optional): New column title
+- **Index** (optional): New column position
+- **Column Type**: Column type (TEXT_NUMBER, DATE, CHECKBOX, CONTACT_LIST, MULTI_CONTACT_LIST, PICKLIST, MULTI_PICKLIST, DURATION, PREDECESSOR, etc.)
+- **Options** (for PICKLIST/MULTI_PICKLIST): Array of option values
+
 ### Webhook Operations
 
 #### List Webhooks
 List all webhooks in your account. No additional parameters required.
 
 #### Create Webhook
-Create a new webhook for a sheet:
-- **Sheet ID**: The ID of the sheet to monitor
-- **Callback URL**: The publicly accessible URL that Smartsheet will call (see note below)
-- **Webhook Name** (optional): Name for the webhook
-- **Events**: Events to subscribe to (default: all events)
+Create a new webhook:
+- **Sheet ID**: Select from dropdown or enter manually
+- **Callback URL** (optional): Auto-generates from `WEBHOOK_URL` environment variable if not provided
+- **Webhook Name** (optional): Custom name for the webhook
+- **Events**: Events to subscribe to:
+  - `*.*` - All events (default)
+  - `sheet.rowCreated` - Row created
+  - `sheet.rowUpdated` - Row updated
+  - `sheet.rowDeleted` - Row deleted
+  - `sheet.created` - Sheet created
+  - `sheet.updated` - Sheet updated
+  - `sheet.deleted` - Sheet deleted
 
 #### Update Webhook
 Update an existing webhook:
-- **Webhook ID**: The ID of the webhook to update
-- **Update Fields**: Fields to update (name, enabled status, events)
+- **Webhook ID**: Select from dropdown or enter manually
+- **Update Fields**:
+  - Name
+  - Enabled status
+  - Events
 
 #### Delete Webhook
 Delete a webhook:
-- **Webhook ID**: The ID of the webhook to delete
+- **Webhook ID**: Select from dropdown or enter manually
+
+### Report Operations
+
+#### List Reports
+Get a list of all reports in your account. Supports pagination.
+
+#### Get Report
+Retrieve detailed information about a specific report:
+- **Report ID**: Select from dropdown or enter manually
+- **Include** (optional): Fields to include (same options as Get Sheet)
+- **Exclude** (optional): Fields to exclude
+
+### Admin Operations
+
+#### User Management
+
+**List Users**
+Get a list of all users in your account.
+
+**Get User**
+Get details of a specific user:
+- **User Input Method**: Select from dropdown or enter ID manually
+- **User ID**: User ID (if using manual entry)
+
+**Add User**
+Add a new user:
+- **Email**: User email address (required)
+- **First Name** (optional): User's first name
+- **Last Name** (optional): User's last name
+- **Admin**: Grant admin privileges
+- **Licensed Sheet Creator**: Grant licensed sheet creator status
+
+**Update User**
+Update user properties:
+- **User Input Method**: Select from dropdown or enter ID manually
+- **User ID**: User ID (if using manual entry)
+- **First Name** (optional): Updated first name
+- **Last Name** (optional): Updated last name
+- **Admin**: Update admin status
+- **Licensed Sheet Creator**: Update licensed sheet creator status
+
+**Delete User**
+Delete a user:
+- **User Input Method**: Select from dropdown or enter ID manually
+- **User ID**: User ID (if using manual entry)
+
+#### Group Management
+
+**List Groups**
+Get a list of all groups in your account.
+
+**Get Group**
+Get details of a specific group:
+- **Group Input Method**: Select from dropdown or enter ID manually
+- **Group ID**: Group ID (if using manual entry)
+
+**Create Group**
+Create a new group:
+- **Group Name**: Name for the group
+- **Description** (optional): Group description
+
+**Update Group**
+Update group properties:
+- **Group Input Method**: Select from dropdown or enter ID manually
+- **Group ID**: Group ID (if using manual entry)
+- **Group Name** (optional): Updated group name
+- **Description** (optional): Updated description
+
+**Delete Group**
+Delete a group:
+- **Group Input Method**: Select from dropdown or enter ID manually
+- **Group ID**: Group ID (if using manual entry)
+
+#### Group Member Management
+
+**List Group Members**
+Get all members of a group:
+- **Group Input Method**: Select from dropdown or enter ID manually
+- **Group ID**: Group ID (if using manual entry)
+
+**Add Group Members**
+Add members to a group:
+- **Group Input Method**: Select from dropdown or enter ID manually
+- **Group ID**: Group ID (if using manual entry)
+- **Members**: Array of email addresses (supports any email, not just existing contacts)
+
+**Remove Group Member**
+Remove a member from a group:
+- **Group Input Method**: Select from dropdown or enter ID manually
+- **Group ID**: Group ID (if using manual entry)
+- **Member User ID**: User ID of the member to remove
 
 ### Webhook Trigger
 
 The Smartsheet Trigger node allows workflows to start automatically when Smartsheet events occur:
 - **Type**: Type of webhook (currently supports Sheet)
-- **Sheet ID**: The ID of the sheet to monitor
+- **Sheet ID**: Select from dropdown or enter manually
+
+The trigger automatically:
+- Creates a webhook for the specified sheet
+- Handles webhook verification challenges
+- Manages webhook lifecycle (creation, updates, deletion)
+- Subscribes to all sheet events (`*.*`)
 
 **Important Note about Webhooks and Localhost:**
 
@@ -161,6 +409,37 @@ Smartsheet webhooks require a publicly accessible URL. If you're running n8n on
 
 For the trigger node, n8n automatically generates the webhook URL, but it must be publicly accessible for Smartsheet to reach it.
 
+## Advanced Features
+
+### Multi-Contact List Support
+The node automatically handles `MULTI_CONTACT_LIST` columns by:
+- Parsing comma-separated email strings
+- Formatting as proper Smartsheet API `objectValue` structure
+- Supporting `strict: false` mode for flexible updates
+
+### Multi-Picklist Support
+The node handles `MULTI_PICKLIST` columns by:
+- Parsing comma-separated option strings
+- Formatting as proper Smartsheet API `objectValue` structure
+- Validating against column options
+
+### Attachment Handling
+- **File Uploads**: Supports binary data from n8n's binary data system
+- **Link Attachments**: Supports URL-based attachments
+- **Proof Attachments**: Special endpoint for row proofs
+- **Custom Filenames**: Override default binary filename with custom name
+
+### Discussion Management
+- **Add to Existing**: Add comments to existing discussions
+- **Create New**: Create new discussions with initial comment
+- **Automatic Loading**: Fetches existing discussions for easy selection
+
+### Location Control
+When adding or updating rows, control placement:
+- **Top**: Add to top of sheet
+- **Bottom**: Add to bottom of sheet
+- **Parent Row**: Add as child of specified parent row
+
 ## API Documentation
 
 For more information about the Smartsheet API, visit:
@@ -189,4 +468,3 @@ npm run format
 ## License
 
 MIT
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-nodes-steyi-ss",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "n8n node for Smartsheet API integration",
   "keywords": [
     "n8n-node-package",
@@ -34,9 +34,9 @@
       "dist/nodes/SteyiSmartsheet/SteyiSmartsheet.node.js",
       "dist/nodes/SteyiSmartsheet/SteyiSmartsheetTrigger.node.js"
     ],
-      "credentials": [
-        "dist/credentials/SteyiSmartsheetCreds.credentials.js"
-      ]
+    "credentials": [
+      "dist/credentials/SteyiSmartsheetCreds.credentials.js"
+    ]
   },
   "devDependencies": {
     "@typescript-eslint/parser": "^5.45.0",
@@ -53,4 +53,3 @@
     "n8n-workflow": "*"
   }
 }
-