feat: add uploadFileAsync method for storing files in attachment fields

[DarkPhoenix2704]

No description provided.

[DarkPhoenix2704]

@claude Review

[github-actions]

✅ Build Status: Success!

• ✅ Build completed successfully
• 🚀 Ready for review

📝 Latest commit: 9f6bc01
⏰ Updated: 2025-10-22 07:03:33 UTC

[claude]

Claude finished @DarkPhoenix2704's task —— View job

---

Code Review Complete ✅

• Read repository guidelines (CLAUDE.md)
• Review modified documentation file (input.mdx)
• Review changelog entry
• Check for consistency with existing patterns
• Provide comprehensive feedback

---

Review Summary

This PR adds documentation for a new input.uploadFileAsync() method. The documentation is well-structured and follows existing patterns. I've identified a few minor issues and suggestions for improvement.

Findings

✅ Strengths

1. Consistent structure: The new method documentation follows the same pattern as existing methods (textAsync(), fileAsync(), etc.)
2. Comprehensive examples: Multiple practical examples show different use cases (basic upload, image filtering, spreadsheet filtering, database storage)
3. Type documentation: The NocoDbFile interface is clearly documented with comments
4. Changelog entry: Properly dated and well-written with clear bullet points
5. Image included: Screenshot shows the UI implementation

🔍 Issues & Suggestions

Minor Issues:

1. Line 17 (content/scripts/api-reference/input.mdx): Minor inconsistency in formatting

   • Current: - Upload and parse files for data processing (\fileAsync`)`
   • Current: - Upload files for attachments and storage (\uploadFileAsync`)`
   • These two lines have different structures. The second one could be more descriptive like "Upload files as raw file objects for..."

2. Lines 226-270 (content/scripts/api-reference/input.mdx): Missing information

   • The documentation doesn't mention whether multiple files can be uploaded simultaneously (though the return type NocoDbFile[] suggests it)
   • Consider adding a note about whether there are any file size limits or upload constraints
   • The label parameter is described as required (string), but for input.fileAsync() on line 168, the label is optional (string, optional). Is this intentional?

3. Line 11 (content/scripts/changelog.mdx): Date inconsistency

   • The changelog shows "October 22, 2025" but we're working with "October 22, 2025" according to the environment. This appears correct, but just flagging for awareness.

Documentation Enhancement Suggestions:

1. Clarify the difference between fileAsync() and uploadFileAsync():

   • While line 13-14 mentions the distinction ("parse files" vs "attachments and storage"), it could be clearer
   • Consider adding a note or callout box in the uploadFileAsync() section explicitly stating when to use which method
   • Example: "Use fileAsync() when you need to parse and process file contents (CSV, JSON, etc.). Use uploadFileAsync() when you need to store files as attachments without parsing."

2. Multiple file upload capability:

   • Line 201 states "upload one or more files" but this could be more explicit
   • Consider adding an example showing multiple file selection or clarify in the parameters if there's a way to enable/disable multiple selection

3. Error handling:

   • The examples don't show error handling (e.g., what happens if the user cancels the upload?)
   • Consider adding a note or example showing how to handle cancellation or errors

Code Example Review:

Lines 227-235 (Basic file upload example):

// Prompt user to upload any file
const files = await input.uploadFileAsync("Please upload your document");

console.log(`Uploaded ${files.length} file(s)`);
files.forEach(file => {
  console.log(`File: ${file.title}, Size: ${file.size} bytes`);
});

✅ Clean and simple

Lines 263-269 (Store in database example):

const files = await input.uploadFileAsync("Upload product images");

await table.createRecordAsync({
  'AttachmentField': files,
});

⚠️ This example could show error handling or demonstrate what happens with the returned record ID

Changelog Review:

Lines 11-18 (content/scripts/changelog.mdx):

• ✅ Clear and well-structured
• ✅ Good use of bullet points
• ✅ Includes an example
• ✅ Explains the distinction from fileAsync()

Recommendations

Required Changes: None - the documentation is functional and correct

Suggested Improvements:

1. Clarify whether the label parameter should be optional (like fileAsync()) or required
2. Add a brief note about multiple file selection capability
3. Consider adding a callout box distinguishing fileAsync() vs uploadFileAsync() usage
4. Add a simple error/cancellation handling example

Overall Assessment

Approval: ✅ Approve with minor suggestions

The documentation is well-written, comprehensive, and follows established patterns. The additions are valuable and clearly explain the new functionality. The suggested improvements are optional and would enhance clarity but are not blockers.

---

Job Run • Branch: new-file-input