From 79ebfa5c1a8b00df724edabe1102d05dce9e2b89 Mon Sep 17 00:00:00 2001
From: jar-stripe <jar@stripe.com>
Date: Thu, 10 Oct 2024 11:08:45 -0700
Subject: [PATCH] Cleaned up examples and added documentation (#1470)

---
 examples/README.md                            |  9 +++--
 examples/example_template.rb                  | 36 +++++++++++++++++++
 examples/meter_event_stream.rb                | 10 ++++++
 examples/new_example.rb                       | 24 -------------
 ...andler.rb => thinevent_webhook_handler.rb} | 11 ++++++
 5 files changed, 64 insertions(+), 26 deletions(-)
 create mode 100644 examples/example_template.rb
 delete mode 100644 examples/new_example.rb
 rename examples/{stripe_webhook_handler.rb => thinevent_webhook_handler.rb} (60%)

diff --git a/examples/README.md b/examples/README.md
index d0c3af87..e652a0bd 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -3,9 +3,14 @@
 From the examples folder, run:
 `RUBYLIB=../lib ruby your_example.rb`
 
+e.g.
+
+`RUBYLIB=../lib ruby thinevent_webhook_handler.rb`
+
 ## Adding a new example
 
 1. Clone new_example.rb
 2. Implement your example
-3. Run it (as per above)
-4. 👍
+3. Fill out the file comment. Include a description and key steps that are being demonstrated.
+4. Run it (as per above)
+5. 👍
diff --git a/examples/example_template.rb b/examples/example_template.rb
new file mode 100644
index 00000000..2342a3c4
--- /dev/null
+++ b/examples/example_template.rb
@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# example_template.py - This is a template for defining new examples.  It is not intended to be used directly.
+#
+# <describe what this example does>
+#
+# In this example, we:
+#   - <key step 1>
+#   - <key step 2
+#   - ...
+#
+# <describe assumptions about the user's stripe account, environment, or configuration;
+# or things to watch out for when running>
+
+require "stripe"
+require "date"
+
+class ExampleTemplate
+  attr_accessor :api_key
+
+  def initialize(api_key)
+    @api_key = api_key
+  end
+
+  def do_something_great
+    puts "Hello World"
+    # client = Stripe::StripeClient.new(api_key)
+    # client.v1
+  end
+end
+
+# Send meter events
+api_key = "{{API_KEY}}"
+
+example = ExampleTemplate.new(api_key)
+example.do_something_great
diff --git a/examples/meter_event_stream.rb b/examples/meter_event_stream.rb
index 3f75ad4f..45484b85 100644
--- a/examples/meter_event_stream.rb
+++ b/examples/meter_event_stream.rb
@@ -1,5 +1,15 @@
 # frozen_string_literal: true
 
+# meter_event_stream.py - use the high-throughput meter event stream to report create billing meter events.
+#
+# In this example, we:
+#   - create a meter event session and store the session's authentication token
+#   - define an event with a payload
+#   - use the meter_event_stream service accessor in StripeClient to create an event stream that reports this event
+#
+# This example expects a billing meter with an event_name of 'alpaca_ai_tokens'.  If you have
+# a different meter event name, you can change it before running this example.
+
 require "stripe"
 require "date"
 
diff --git a/examples/new_example.rb b/examples/new_example.rb
deleted file mode 100644
index a358995f..00000000
--- a/examples/new_example.rb
+++ /dev/null
@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-require "stripe"
-require "date"
-
-class NewExample
-  attr_accessor :api_key
-
-  def initialize(api_key)
-    @api_key = api_key
-  end
-
-  def do_something_great
-    puts "Hello World"
-    # client = Stripe::StripeClient.new(api_key)
-    # client.v1
-  end
-end
-
-# Send meter events
-api_key = "{{API_KEY}}"
-
-example = NewExample.new(api_key)
-example.do_something_great
diff --git a/examples/stripe_webhook_handler.rb b/examples/thinevent_webhook_handler.rb
similarity index 60%
rename from examples/stripe_webhook_handler.rb
rename to examples/thinevent_webhook_handler.rb
index 94269ebf..cc0594ff 100644
--- a/examples/stripe_webhook_handler.rb
+++ b/examples/thinevent_webhook_handler.rb
@@ -1,6 +1,17 @@
 # frozen_string_literal: true
 # typed: false
 
+# thinevent_webhook_handler.rb - receive and process thin events like the
+# v1.billing.meter.error_report_triggered event.
+#
+# In this example, we:
+#     - create a StripeClient called client
+#     - use client.parse_thin_event to parse the received thin event webhook body
+#     - call client.v2.core.events.retrieve to retrieve the full event object
+#     - if it is a V1BillingMeterErrorReportTriggeredEvent event type, call
+#       event.fetchRelatedObject to retrieve the Billing Meter object associated
+#       with the event.
+
 require "stripe"
 require "sinatra"