chore: add basic topics example and readmes

examples/README.md

@@ -0,0 +1,5 @@
+# Running the Examples
+
+For each example, you will need to provide a Momento API key, which you can generate from the [Momento Web Console](https://console.gomomento.com/api-keys).
+
+Each subfolder has more specific instructions, but you can run examples in Dart files using `dart run <filename>` and start example Flutter apps using `flutter run -d <device_id>`.

examples/flutter_chat_app/README.md

@@ -1,15 +1,21 @@
-## Momento Topics Demo Chat App using Flutter
+# Momento Topics Demo Chat App using Flutter
 
-1. Install Flutter: https://docs.flutter.dev/get-started/install 
+## Prerequisites
 
-2. Provide your Momento API key in [`lib/main.dart`](./lib/main.dart) at this line:
+- [Installed Dart](https://dart.dev/get-dart)
+- [Installed Flutter](https://docs.flutter.dev/get-started/install)
+- Momento API key, which you can generate from the [Momento Web Console](https://console.gomomento.com/api-keys)
+
+## Running the Flutter Demo App
+
+1. Provide your Momento API key in [`lib/main.dart`](./lib/main.dart) at this line:
     ```
     static const String _momentoApiKey = "your-api-key-here";
     ```
 
-3. Run in [VSCode](https://docs.flutter.dev/tools/vs-code) or [Android Studio or IntelliJ](https://docs.flutter.dev/tools/android-studio). If using the command line, you can run using a command like: `flutter run -d macos`
+2. Run in [VSCode](https://docs.flutter.dev/tools/vs-code) or [Android Studio or IntelliJ](https://docs.flutter.dev/tools/android-studio). If using the command line, you can run using a command like: `flutter run -d <device_id>`. You can use `flutter devices` to see all connected devices and their IDs.
 
-## Resources
+## Flutter Resources
 
 - [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
 - [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)

examples/topics/README.md

@@ -0,0 +1,28 @@
+# Topics Examples
+
+## Prerequisites
+
+- [Installed Dart](https://dart.dev/get-dart)
+- Momento API key, which you can generate from the [Momento Web Console](https://console.gomomento.com/api-keys)
+
+## Basic Example
+
+A very basic example of a Topics subscriber can be run using:
+
+```
+MOMENTO_API_KEY="your-api-key" dart run basic_subscriber.dart
+```
+
+A very basic example of a Topics publisher can be run using:
+
+```
+MOMENTO_API_KEY="your-api-key" dart run basic_publisher.dart
+```
+
+## Advanced Example
+
+The advanced example shows how you can unsubscribe from a topic (i.e. cancel a stream of messages) as well as how you can enable logging at a desired logging level.
+
+```
+MOMENTO_API_KEY="your-api-key" dart run advanced.dart
+```

examples/topics.dart → examples/topics/advanced.dart

@@ -17,9 +17,9 @@ void main() async {
   // start publishing messages in 2 seconds
   Timer(const Duration(seconds: 2), () async {
     // publish 10 messages spaced 1 second apart
-    for (final _ in Iterable.generate(10)) {
+    for (final i in Iterable.generate(10)) {
       var result =
-          await topicClient.publish("cache", "topic", StringValue("hi"));
+          await topicClient.publish("cache", "topic", StringValue("hi $i"));
       switch (result) {
         case TopicPublishSuccess():
           print("Successful publish!");
@@ -30,34 +30,33 @@ void main() async {
     }
   });
 
-  var sub = topicClient.subscribe("cache", "topic");
-  switch (sub) {
-    case TopicSubscription():
-      print("Successful subscription!");
+  var subscription = topicClient.subscribe("cache", "topic");
+  var messageStream = switch (subscription) {
+    TopicSubscription() => subscription.stream,
+    TopicSubscribeError() => throw Exception(
+        "Subscribe error: ${subscription.errorCode} ${subscription.message}"),
+  };
 
-      // cancel subscription 10 seconds from now
-      Timer(const Duration(seconds: 10), () {
-        print("Cancelling subscription!");
-        sub.unsubscribe();
-      });
+  // cancel subscription 15 seconds from now
+  Timer(const Duration(seconds: 15), () {
+    print("Cancelling subscription!");
+    subscription.unsubscribe();
+  });
 
-      try {
-        await for (final msg in sub.stream) {
-          switch (msg) {
-            case TopicSubscriptionItemBinary():
-              print("Binary value: ${msg.value}");
-            case TopicSubscriptionItemText():
-              print("String value: ${msg.value}");
-            case TopicSubscriptionItemError():
-              print("Error receiving message: ${msg.errorCode}");
-          }
-        }
-      } catch (e) {
-        print("Runtime type: ${e.runtimeType}");
-        print("Error with await for loop: $e");
+  try {
+    await for (final msg in messageStream) {
+      switch (msg) {
+        case TopicSubscriptionItemBinary():
+          print("Binary value: ${msg.value}");
+        case TopicSubscriptionItemText():
+          print("String value: ${msg.value}");
+        case TopicSubscriptionItemError():
+          print("Error receiving message: ${msg.errorCode}");
       }
-    case TopicSubscribeError():
-      print("Subscribe error: ${sub.errorCode} ${sub.message}");
+    }
+  } catch (e) {
+    print("Runtime type: ${e.runtimeType}");
+    print("Error with await for loop: $e");
   }
 
   // unsubscribing should not affect the topic client's ability

examples/topics/basic_publisher.dart

@@ -0,0 +1,25 @@
+import 'dart:io';
+import 'package:client_sdk_dart/client_sdk_dart.dart';
+
+void main() async {
+  var topicClient = TopicClient(
+      CredentialProvider.fromEnvironmentVariable("MOMENTO_API_KEY"),
+      MobileTopicConfiguration.latest());
+
+  // publish 10 messages spaced 1 second apart
+  for (final i in Iterable.generate(10)) {
+    var result =
+        await topicClient.publish("cache", "topic", StringValue("hi $i"));
+    switch (result) {
+      case TopicPublishSuccess():
+        print("Successful publish!");
+      case TopicPublishError():
+        print("Publish error: ${result.errorCode} ${result.message}");
+    }
+    sleep(Duration(seconds: 1));
+  }
+
+  topicClient.close();
+  print("Closed Momento Topics publisher");
+  exit(0);
+}

examples/topics/basic_subscriber.dart

@@ -0,0 +1,42 @@
+import 'dart:async';
+import 'dart:io';
+import 'package:client_sdk_dart/client_sdk_dart.dart';
+
+void main() async {
+  var topicClient = TopicClient(
+      CredentialProvider.fromEnvironmentVariable("MOMENTO_API_KEY"),
+      MobileTopicConfiguration.latest());
+
+  var subscription = topicClient.subscribe("cache", "topic");
+  var messageStream = switch (subscription) {
+    TopicSubscription() => subscription.stream,
+    TopicSubscribeError() => throw Exception(
+        "Subscribe error: ${subscription.errorCode} ${subscription.message}"),
+  };
+
+  // cancel subscription 15 seconds from now
+  Timer(const Duration(seconds: 15), () {
+    print("Cancelling subscription!");
+    subscription.unsubscribe();
+  });
+
+  try {
+    await for (final msg in messageStream) {
+      switch (msg) {
+        case TopicSubscriptionItemBinary():
+          print("Binary value: ${msg.value}");
+        case TopicSubscriptionItemText():
+          print("String value: ${msg.value}");
+        case TopicSubscriptionItemError():
+          print("Error receiving message: ${msg.errorCode}");
+      }
+    }
+  } catch (e) {
+    print("Runtime type: ${e.runtimeType}");
+    print("Error with await for loop: $e");
+  }
+
+  topicClient.close();
+  print("Closed Momento Topics subscriber");
+  exit(0);
+}