feat(llc): implement attachment uploader

docs_code_snippets/01_01_quickstart.dart

@@ -42,10 +42,9 @@ Future<void> socialMediaFeed() async {
 
   // Add a comment to activity
   await timeline.addComment(
-    request: AddCommentRequest(
+    request: ActivityAddCommentRequest(
       comment: 'Great post!',
-      objectId: 'activity_123',
-      objectType: 'activity',
+      activityId: 'activity_123',
     ),
   );
 
@@ -54,6 +53,7 @@ Future<void> socialMediaFeed() async {
     activityId: 'activity_123',
     fid: FeedId(group: 'timeline', id: 'john'),
   );
+
   await activity.addCommentReaction(
     commentId: 'commentId',
     request: AddCommentReactionRequest(type: 'like'),

docs_code_snippets/03_01_activities.dart

@@ -25,7 +25,11 @@ Future<void> imageAndVideo() async {
   final imageActivity = await feed.addActivity(
     request: const FeedAddActivityRequest(
       attachments: [
-        Attachment(imageUrl: 'https://example.com/image.jpg', type: 'image'),
+        Attachment(
+          imageUrl: 'https://example.com/image.jpg',
+          type: 'image',
+          custom: {'width': 600, 'height': 400},
+        ),
       ],
       text: 'look at NYC',
       type: 'post',
@@ -41,10 +45,12 @@ Future<void> stories() async {
         const Attachment(
           imageUrl: 'https://example.com/image1.jpg',
           type: 'image',
+          custom: {'width': 600, 'height': 400},
         ),
         const Attachment(
           assetUrl: 'https://example.com/video1.mp4',
           type: 'video',
+          custom: {'width': 1920, 'height': 1080, 'duration': 12},
         ),
       ],
       expiresAt: tomorrow.toIso8601String(),
@@ -69,6 +75,7 @@ Future<void> addManyActivities() async {
       type: 'post',
     ),
   ];
+
   final upsertedActivities = await client.upsertActivities(
     activities: activities,
   );
@@ -83,11 +90,14 @@ Future<void> updatingAndDeletingActivities() async {
       custom: {'custom': 'custom'},
     ),
   );
+
   // Delete an activity
+  await feed.deleteActivity(
+    id: '123',
+    // Soft delete sets deleted at but retains the data, hard delete fully removes it
+    hardDelete: false,
+  );
 
-  const hardDelete =
-      false; // Soft delete sets deleted at but retains the data, hard delete fully removes it
-  await feed.deleteActivity(id: '123', hardDelete: hardDelete);
   // Batch delete activities
   await client.deleteActivities(
     request: const DeleteActivitiesRequest(

docs_code_snippets/03_03_file_uploads.dart

@@ -1,3 +1,195 @@
-// ignore_for_file: file_names
+// ignore_for_file: unused_local_variable, file_names, avoid_redundant_argument_values
 
-// TODO
+import 'package:stream_feeds/stream_feeds.dart';
+
+late StreamFeedsClient client;
+late Feed feed;
+late Activity activity;
+late StreamAttachmentUploader attachmentUploader;
+late List<Attachment> uploadedAttachments;
+
+Future<void> howToUploadAFileOrImageStep1() async {
+  // Create an instance of AttachmentFile with the file path
+  //
+  // Note: On web, use `AttachmentFile.fromData`. Or if you are working with
+  // plugins which provide XFile then use `AttachmentFile.fromXFile`.
+  final file = AttachmentFile('path/to/file');
+
+  // Create a StreamAttachment with the file and type (image, video, file)
+  final streamAttachment = StreamAttachment(
+    file: file,
+    type: AttachmentType.image,
+    custom: {'width': 600, 'height': 400},
+  );
+
+  // Upload the attachment
+  final result = await attachmentUploader.upload(
+    streamAttachment,
+    // Optionally track upload progress
+    onProgress: (progress) {
+      // Handle progress updates
+    },
+  );
+
+  // Map the result to an Attachment model to send with an activity
+  final uploadedAttachment = result.getOrThrow();
+  final attachmentReadyToBeSent = Attachment(
+    imageUrl: uploadedAttachment.remoteUrl,
+    assetUrl: uploadedAttachment.remoteUrl,
+    thumbUrl: uploadedAttachment.thumbnailUrl,
+    custom: {...?uploadedAttachment.custom},
+  );
+}
+
+Future<void> howToUploadAFileOrImageStep2() async {
+  // Add an activity with the uploaded attachment
+  final activity = await feed.addActivity(
+    request: FeedAddActivityRequest(
+      attachments: uploadedAttachments,
+      text: 'look at NYC',
+      type: 'post',
+    ),
+  );
+}
+
+Future<void> howToUploadAFileOrImageStep3() async {
+  // Create a list of attachments to upload
+  final attachmentUploads = <StreamAttachment>[];
+
+  // Add an activity with the attachment needing upload
+  final activity = await feed.addActivity(
+    request: FeedAddActivityRequest(
+      attachmentUploads: attachmentUploads,
+      text: 'look at NYC',
+      type: 'post',
+    ),
+  );
+}
+
+Future<void> howToUploadAFileOrImageStep4() async {
+  // Create a list of attachments to upload
+  final attachmentUploads = <StreamAttachment>[];
+
+  // Add a comment with the attachment needing upload
+  final comment = await activity.addComment(
+    request: ActivityAddCommentRequest(
+      attachmentUploads: attachmentUploads,
+      activityId: activity.activityId,
+      comment: 'look at NYC',
+    ),
+  );
+}
+
+Future<void> howToDeleteAFileOrImage() async {
+  // Delete an image from the CDN
+  await client.deleteImage(url: 'https://mycdn.com/image.png');
+
+  // Delete a file from the CDN
+  await client.deleteFile(url: 'https://mycdn.com/file.pdf');
+}
+
+// Your custom implementation of CdnClient
+class CustomCDN implements CdnClient {
+  @override
+  Future<Result<UploadedFile>> uploadFile(
+    AttachmentFile file, {
+    ProgressCallback? onProgress,
+    CancelToken? cancelToken,
+  }) {
+    // Use your own CDN upload logic here.
+    // For example, you might upload the file to AWS S3, Google Cloud Storage, etc.
+    // After uploading, return a Result<UploadedFile> with the file URLs.
+    //
+    // Note: Make sure to handle progress updates and cancellation if needed.
+    return uploadToYourOwnCdn(
+      file,
+      onProgress: onProgress,
+      cancelToken: cancelToken,
+    );
+  }
+
+  @override
+  Future<Result<UploadedFile>> uploadImage(
+    AttachmentFile image, {
+    ProgressCallback? onProgress,
+    CancelToken? cancelToken,
+  }) {
+    // Use your own CDN upload logic here.
+    // For example, you might upload the image to AWS S3, Google Cloud Storage, etc.
+    // After uploading, return a Result<UploadedFile> with the image URLs.
+    //
+    // Note: Make sure to handle progress updates and cancellation if needed.
+    return uploadToYourOwnCdn(
+      image,
+      onProgress: onProgress,
+      cancelToken: cancelToken,
+    );
+  }
+
+  @override
+  Future<Result<void>> deleteFile(
+    String url, {
+    CancelToken? cancelToken,
+  }) {
+    // Use your own CDN deletion logic here.
+    // For example, you might delete the file from AWS S3, Google Cloud Storage, etc.
+    // After deleting, return a Result<void> indicating success or failure.
+    //
+    // Note: Make sure to handle cancellation if needed.
+    return deleteFromYourOwnCdn(
+      url,
+      cancelToken: cancelToken,
+    );
+  }
+
+  @override
+  Future<Result<void>> deleteImage(
+    String url, {
+    CancelToken? cancelToken,
+  }) {
+    // Use your own CDN deletion logic here.
+    // For example, you might delete the image from AWS S3, Google Cloud Storage, etc.
+    // After deleting, return a Result<void> indicating success or failure.
+    //
+    // Note: Make sure to handle cancellation if needed.
+    return deleteFromYourOwnCdn(
+      url,
+      cancelToken: cancelToken,
+    );
+  }
+}
+
+Future<void> usingYourOwnCdn() async {
+  // Create a config with your custom CDN client
+  final config = FeedsConfig(cdnClient: CustomCDN());
+
+  // Initialize the StreamFeedsClient with the custom config
+  final client = StreamFeedsClient(
+    apiKey: 'your_api_key',
+    user: const User(id: 'user_id'),
+    config: config,
+  );
+}
+
+// region Helper methods to simulate your own CDN logic
+
+Future<Result<UploadedFile>> uploadToYourOwnCdn(
+  AttachmentFile file, {
+  ProgressCallback? onProgress,
+  CancelToken? cancelToken,
+}) {
+  // Implement your file upload logic here
+  // Return a Result<UploadedFile> indicating success or failure
+  throw UnimplementedError();
+}
+
+Future<Result<void>> deleteFromYourOwnCdn(
+  String url, {
+  CancelToken? cancelToken,
+}) {
+  // Implement your file deletion logic here
+  // Return a Result<void> indicating success or failure
+  throw UnimplementedError();
+}
+
+// endregion

docs_code_snippets/04_01_feeds.dart

@@ -19,6 +19,7 @@ Future<void> creatingAFeed() async {
       visibility: FeedVisibility.public,
     ),
   );
+
   final feed2 = client.feedFromQuery(query);
   await feed2.getOrCreate();
 }
@@ -29,31 +30,37 @@ Future<void> readingAFeed() async {
   final feedData = feed.state.feed;
   final activities = feed.state.activities;
   final members = feed.state.members;
-  // Always dispose the feed when you are done with it
+
+  // Note: Always dispose the feed when you are done with it
   feed.dispose();
 }
 
 Future<void> readingAFeedMoreOptions() async {
   final query = FeedQuery(
     fid: const FeedId(group: 'user', id: 'john'),
-    activityFilter: Filter.in_(ActivitiesFilterField.filterTags, const [
-      'green',
-    ]), // filter activities with filter tag green
+    // filter activities with filter tag green
+    activityFilter: Filter.in_(
+      ActivitiesFilterField.filterTags,
+      const ['green'],
+    ),
     activityLimit: 10,
-    externalRanking: {'user_score': 0.8}, // additional data used for ranking
+    // additional data used for ranking
+    externalRanking: {'user_score': 0.8},
     followerLimit: 10,
     followingLimit: 10,
     memberLimit: 10,
-    view:
-        'myview', // overwrite the default ranking or aggregation logic for this feed. good for split testing
-    watch: true, // receive web-socket events with real-time updates
+    // overwrite the default ranking or aggregation logic for this feed. good for split testing
+    view: 'myview',
+    // receive web-socket events with real-time updates
+    watch: true,
   );
 
   final feed = client.feedFromQuery(query);
   await feed.getOrCreate();
   final activities = feed.state.activities;
   final feedData = feed.state.feed;
-  // Always dispose the feed when you are done with it
+
+  // Note: Always dispose the feed when you are done with it
   feed.dispose();
 }
 
@@ -64,6 +71,7 @@ Future<void> feedPagination() async {
       activityLimit: 10,
     ),
   );
+
   // Page 1
   await feed.getOrCreate();
   final activities = feed.state.activities; // First 10 activities
@@ -97,16 +105,19 @@ Future<void> filteringExamples() async {
       type: 'activity',
     ),
   ]);
+
   // Now read the feed, this will fetch activity 1 and 2
   final query = FeedQuery(
     fid: feedId,
     activityFilter: Filter.in_(ActivitiesFilterField.filterTags, const [
       'blue',
     ]),
   );
+
   final feed = client.feedFromQuery(query);
   await feed.getOrCreate();
-  final activities = feed.state.activities; // contains first and second
+  // contains first and second
+  final activities = feed.state.activities;
 }
 
 Future<void> moreComplexFilterExamples() async {
@@ -124,6 +135,7 @@ Future<void> moreComplexFilterExamples() async {
       ]),
     ]),
   );
+
   await feed.getOrCreate();
   final activities = feed.state.activities;
 }
@@ -191,6 +203,7 @@ Future<void> queryMyFeeds() async {
     limit: 10,
     watch: true,
   );
+
   final feedList = client.feedList(query);
 
   // Page 1
@@ -217,14 +230,17 @@ Future<void> queryFeedsByNameOrVisibility() async {
       Filter.query(FeedsFilterField.name, 'Sports'),
     ]),
   );
+
   final sportsFeedList = client.feedList(sportsQuery);
   final sportsFeeds = await sportsFeedList.get();
+
   final techQuery = FeedsQuery(
     filter: Filter.and([
       Filter.equal(FeedsFilterField.visibility, 'public'),
       Filter.autoComplete(FeedsFilterField.description, 'tech'),
     ]),
   );
+
   final techFeedList = client.feedList(techQuery);
   final techFeeds = await techFeedList.get();
 }
@@ -236,6 +252,7 @@ Future<void> queryFeedsByCreatorName() async {
       Filter.query(FeedsFilterField.createdByName, 'Thompson'),
     ]),
   );
+
   final feedList = client.feedList(query);
   final feeds = await feedList.get();
 }