Add list sales order items action to Returnless integration

.claude/zendesk-assignee-learnings.md

@@ -0,0 +1,165 @@
+# Zendesk Assignee Implementation Learnings
+
+## Project Summary
+Added assignee support to Zendesk update-ticket component allowing users to assign tickets to agents via ID or email.
+
+## Key Technical Implementation Details
+
+### 1. Zendesk API Integration
+- **API Fields Used**: `assignee_id` (integer) and `assignee_email` (string, write-only)
+- **API Endpoint**: PUT `/tickets/{ticketId}` 
+- **API Documentation**: https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#update-ticket
+
+### 2. Component Architecture Pattern
+```javascript
+// In zendesk.app.mjs - PropDefinitions
+assigneeId: {
+  type: "string",
+  label: "Assignee ID", 
+  description: "The ID of the agent to assign the ticket to",
+  optional: true,
+  async options({ prevContext }) {
+    // Dynamic loading with pagination
+    const { users, meta } = await this.listUsers({
+      params: {
+        role: "agent", // Filter for agents only
+      },
+    });
+    return {
+      options: users.map(({ id, name }) => ({
+        label: name,
+        value: id,
+      })),
+    };
+  },
+}
+
+// In update-ticket.mjs - Usage
+const ticketData = { /* existing fields */ };
+if (assigneeId) {
+  ticketData.assignee_id = assigneeId;
+}
+if (assigneeEmail) {
+  ticketData.assignee_email = assigneeEmail;
+}
+```
+
+### 3. Pipedream Component Best Practices
+- **Prop Definitions**: Centralize in app file, reference in components via `propDefinition`
+- **Backward Compatibility**: Always make new props optional
+- **Dynamic Options**: Use async options with pagination for large datasets
+- **API Field Mapping**: Use exact API field names (snake_case vs camelCase)
+- **User Feedback**: Enhance summary messages to reflect changes made
+
+## Git Workflow Learnings
+
+### Branch Management
+```bash
+# Create feature branch from master
+git checkout -b feature-name
+
+# Merge latest upstream changes
+git fetch upstream master
+git merge upstream/master
+
+# Handle conflicts and push
+git add . && git commit -m "Resolve conflicts"
+git push --force-with-lease origin feature-name
+```
+
+### PR Management with GitHub CLI
+```bash
+# Create PR with structured description
+gh pr create --title "Title" --body "$(cat <<'EOF'
+## Summary
+- Feature details
+
+## Changes Made
+- Technical details
+
+## Features
+✅ Feature highlights
+EOF
+)"
+```
+
+### Conflict Resolution Pattern
+- **Common Conflict**: Merge conflicts in ticket data construction
+- **Resolution Strategy**: Keep new functionality while preserving upstream changes
+- **Testing**: Always verify syntax with `node -c filename.mjs`
+
+## Zendesk Component Architecture
+
+### File Structure
+```
+components/zendesk/
+├── zendesk.app.mjs           # Main app file with propDefinitions
+├── actions/
+│   └── update-ticket/
+│       └── update-ticket.mjs # Component implementation
+└── common/
+    └── constants.mjs         # Shared constants
+```
+
+### PropDefinition Pattern
+1. Define in `zendesk.app.mjs` with async options for dropdowns
+2. Reference in components via `propDefinition: [app, "propName"]`
+3. Extract in component's `run()` method
+4. Use in API calls with proper field mapping
+
+### API Integration Pattern
+```javascript
+// 1. Build data object conditionally
+const ticketData = { /* base fields */ };
+if (conditionalField) {
+  ticketData.api_field_name = conditionalField;
+}
+
+// 2. Make API call
+const response = await this.updateTicket({
+  data: { ticket: ticketData }
+});
+
+// 3. Provide user feedback
+const summary = `Updated ticket ${response.ticket.id}`;
+step.export("$summary", summary);
+```
+
+## Component Enhancement Principles
+
+### 1. Feature Addition Checklist
+- [ ] Add propDefinitions to app file
+- [ ] Add props to component
+- [ ] Extract props in run() method  
+- [ ] Conditionally include in API payload
+- [ ] Update summary messages
+- [ ] Test syntax validation
+- [ ] Verify backward compatibility
+
+### 2. User Experience Considerations
+- **Optional Props**: Never break existing workflows
+- **Dynamic Loading**: Use pagination for large option sets
+- **Clear Labels**: Descriptive prop names and descriptions
+- **Feedback**: Update summaries to reflect actions taken
+- **Flexibility**: Support multiple input methods (ID vs email)
+
+## API Documentation Insights
+
+### Zendesk Ticket Object Properties
+- `assignee_id`: Integer, agent ID to assign ticket to
+- `assignee_email`: String (write-only), agent email for assignment
+- Both fields are optional and can be used together
+- API handles validation of agent existence and permissions
+
+### Pipedream Platform Patterns
+- Use `propDefinition` for reusable props
+- Implement pagination with `prevContext` and `afterCursor`
+- Filter API results at query time when possible (`role: "agent"`)
+- Follow camelCase for props, snake_case for API fields
+
+## Future Enhancement Opportunities
+1. **Group Assignment**: Add `group_id` support for team assignment
+2. **Assignment Rules**: Implement conditional assignment logic
+3. **Assignment History**: Track assignment changes in ticket comments
+4. **Validation**: Add email format validation for assigneeEmail
+5. **Auto-Assignment**: Rules-based assignment based on ticket properties

components/returnless/actions/list-sales-order-items/list-sales-order-items.mjs

@@ -0,0 +1,39 @@
+import returnless from "../../returnless.app.mjs";
+
+export default {
+  key: "returnless-list-sales-order-items",
+  name: "List Sales Order Items",
+  description: "Retrieve all items from a specific sales order with cursor-based pagination support. [See the documentation](https://docs.returnless.com/docs/api-rest-reference/6b3c26dad0434-list-all-items-of-a-sales-order)",
+  version: "0.0.1",
+  type: "action",
+  props: {
+    returnless,
+    orderId: {
+      propDefinition: [
+        returnless,
+        "orderId",
+      ],
+    },
+    maxResults: {
+      propDefinition: [
+        returnless,
+        "maxResults",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const salesOrderItems = await this.returnless.getPaginatedResources({
+      fn: this.returnless.listSalesOrderItems,
+      args: {
+        $,
+        orderId: this.orderId,
+      },
+      max: this.maxResults,
+    });
+
+    $.export("$summary", `Retrieved ${salesOrderItems.length} sales order item${salesOrderItems.length === 1
+      ? ""
+      : "s"} from order ${this.orderId}`);
+    return salesOrderItems;
+  },
+};

components/returnless/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipedream/returnless",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Pipedream Returnless Components",
   "main": "returnless.app.mjs",
   "keywords": [