flow_chat 0.9.0 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/ci.yml +29 -0
  3. data/.github/workflows/pages.yml +43 -0
  4. data/.gitignore +4 -1
  5. data/CHANGELOG.md +49 -0
  6. data/README.md +166 -295
  7. data/Rakefile +12 -1
  8. data/SECURITY.md +1 -1
  9. data/docs/architecture.md +52 -479
  10. data/docs/async-background-processing.md +31 -265
  11. data/docs/configuration.md +106 -613
  12. data/docs/factory-pattern.md +27 -324
  13. data/docs/gateway-context-variables.md +140 -143
  14. data/docs/gateway-development.md +86 -650
  15. data/docs/getting-started.md +40 -379
  16. data/docs/instrumentation.md +88 -279
  17. data/docs/platforms/instagram.md +278 -0
  18. data/docs/platforms/messenger.md +205 -0
  19. data/docs/platforms/telegram.md +47 -951
  20. data/docs/platforms/ussd.md +38 -653
  21. data/docs/platforms/whatsapp.md +73 -1321
  22. data/docs/superpowers/plans/2026-07-09-inbound-media-support.md +732 -0
  23. data/docs/superpowers/plans/2026-07-09-inbound-media-support.md.tasks.json +58 -0
  24. data/docs/superpowers/plans/2026-08-10-messenger-instagram.md +4064 -0
  25. data/docs/superpowers/plans/2026-08-10-messenger-instagram.md.tasks.json +226 -0
  26. data/docs/superpowers/plans/2026-08-16-unified-choice-resolution.md +972 -0
  27. data/docs/superpowers/plans/2026-08-16-unified-choice-resolution.md.tasks.json +88 -0
  28. data/docs/superpowers/specs/2026-07-09-inbound-media-support-design.md +195 -0
  29. data/docs/superpowers/specs/2026-08-10-messenger-instagram-design.md +391 -0
  30. data/docs/testing.md +26 -297
  31. data/examples/http_controller.rb +12 -10
  32. data/examples/intercom_configuration_example.rb +19 -24
  33. data/examples/intercom_controller.rb +8 -20
  34. data/examples/multi_tenant_whatsapp_controller.rb +61 -166
  35. data/examples/simulator_controller.rb +0 -1
  36. data/examples/ussd_controller.rb +86 -158
  37. data/examples/whatsapp_controller.rb +16 -15
  38. data/examples/whatsapp_media_examples.rb +27 -79
  39. data/flow_chat.gemspec +22 -2
  40. data/gemfiles/rails_main.gemfile +18 -0
  41. data/lib/flow_chat/app.rb +129 -11
  42. data/lib/flow_chat/async_job.rb +10 -0
  43. data/lib/flow_chat/choice_titles.rb +95 -0
  44. data/lib/flow_chat/config.rb +124 -1
  45. data/lib/flow_chat/delivery_error.rb +9 -0
  46. data/lib/flow_chat/gateway_async_support.rb +19 -1
  47. data/lib/flow_chat/http/configuration_error.rb +9 -0
  48. data/lib/flow_chat/http/gateway/simple.rb +24 -4
  49. data/lib/flow_chat/http/middleware/choice_mapper.rb +94 -0
  50. data/lib/flow_chat/input.rb +86 -0
  51. data/lib/flow_chat/instagram/client.rb +32 -0
  52. data/lib/flow_chat/instagram/configuration.rb +147 -0
  53. data/lib/flow_chat/instagram/configuration_error.rb +7 -0
  54. data/lib/flow_chat/instagram/gateway/send_api.rb +63 -0
  55. data/lib/flow_chat/instagram/middleware/choice_mapper.rb +22 -0
  56. data/lib/flow_chat/instagram/renderer.rb +23 -0
  57. data/lib/flow_chat/instrumentation/metrics_collector.rb +6 -1
  58. data/lib/flow_chat/instrumentation.rb +160 -1
  59. data/lib/flow_chat/intercom/client.rb +34 -28
  60. data/lib/flow_chat/intercom/configuration.rb +2 -49
  61. data/lib/flow_chat/intercom/configuration_error.rb +9 -0
  62. data/lib/flow_chat/intercom/gateway/intercom_api.rb +81 -57
  63. data/lib/flow_chat/intercom/middleware/choice_mapper.rb +101 -0
  64. data/lib/flow_chat/intercom/renderer.rb +57 -5
  65. data/lib/flow_chat/media.rb +121 -0
  66. data/lib/flow_chat/messenger/client.rb +264 -0
  67. data/lib/flow_chat/messenger/configuration.rb +103 -0
  68. data/lib/flow_chat/messenger/configuration_error.rb +9 -0
  69. data/lib/flow_chat/messenger/gateway/send_api.rb +42 -0
  70. data/lib/flow_chat/messenger/middleware/choice_mapper.rb +185 -0
  71. data/lib/flow_chat/messenger/renderer.rb +150 -0
  72. data/lib/flow_chat/meta/challenge.rb +24 -0
  73. data/lib/flow_chat/meta/choice_ladder.rb +37 -0
  74. data/lib/flow_chat/meta/configuration_error.rb +7 -0
  75. data/lib/flow_chat/meta/gateway_identity.rb +38 -0
  76. data/lib/flow_chat/meta/messaging_gateway.rb +471 -0
  77. data/lib/flow_chat/meta/signature.rb +30 -0
  78. data/lib/flow_chat/meta/signature_validation.rb +66 -0
  79. data/lib/flow_chat/meta/webhook_verification.rb +43 -0
  80. data/lib/flow_chat/named_configuration.rb +65 -0
  81. data/lib/flow_chat/prompt.rb +13 -16
  82. data/lib/flow_chat/renderers/markdown_support.rb +109 -0
  83. data/lib/flow_chat/security.rb +76 -0
  84. data/lib/flow_chat/session/middleware.rb +11 -2
  85. data/lib/flow_chat/simulator/controller.rb +31 -15
  86. data/lib/flow_chat/simulator/views/simulator.html.erb +184 -20
  87. data/lib/flow_chat/telegram/client.rb +47 -4
  88. data/lib/flow_chat/telegram/configuration.rb +2 -42
  89. data/lib/flow_chat/telegram/configuration_error.rb +9 -0
  90. data/lib/flow_chat/telegram/gateway/bot_api.rb +46 -28
  91. data/lib/flow_chat/telegram/middleware/choice_mapper.rb +77 -16
  92. data/lib/flow_chat/telegram/renderer.rb +10 -2
  93. data/lib/flow_chat/text_truncator.rb +75 -0
  94. data/lib/flow_chat/ussd/middleware/choice_mapper.rb +10 -0
  95. data/lib/flow_chat/version.rb +1 -1
  96. data/lib/flow_chat/whatsapp/client.rb +14 -7
  97. data/lib/flow_chat/whatsapp/configuration.rb +12 -51
  98. data/lib/flow_chat/whatsapp/configuration_error.rb +9 -0
  99. data/lib/flow_chat/whatsapp/gateway/cloud_api.rb +259 -203
  100. data/lib/flow_chat/whatsapp/middleware/choice_mapper.rb +144 -57
  101. data/lib/flow_chat/whatsapp/renderer.rb +121 -60
  102. data/lib/flow_chat.rb +0 -10
  103. data/lib/tasks/release.rake +11 -1
  104. data/site/.nojekyll +0 -0
  105. data/site/.og-card.html +89 -0
  106. data/site/favicon.svg +6 -0
  107. data/site/index.html +209 -0
  108. data/site/og.png +0 -0
  109. metadata +60 -11
  110. data/lib/flow_chat/whatsapp/id_generator.rb +0 -124
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 8cfb138af20136fca40bdc0d7b054e8144ab92e2089c6c446e8c06f5104600f9
4
- data.tar.gz: c4ae6902cffe3bcada4c3efe7b72f544fa9ec246570fa72df1b27c977c4f52db
3
+ metadata.gz: 6ae06aa071a9ac6f07a9b2555e4e35dcaf98512962625b45426865484d989f7c
4
+ data.tar.gz: 583ef52a86cd6462dd3d0bb5e6b1cf76267ea3bbfcd0d9b33b2d7ceffa065e9e
5
5
  SHA512:
6
- metadata.gz: f1e719da60370142efbd2b1a44cbb24236e67291340f9015ddd38411b8180cc2f3216d5e56a50464e23a4657d5184ec80ae85225b86e20f1e6673fcc607c1941
7
- data.tar.gz: ac3fda919d3fe2bfc939be1454b3e4a4edaf8d4c8d18869244c1492a0bc593d186e0ed5fae626ef035a6905e83433d0197560ceac6bc5bce2a87ffcaa53a3ddd
6
+ metadata.gz: 22a819e0db8e6784933ff311b48aa3d9f62eb38aa456df985ee2b4d5c7d8fb683bc866efebe3643294b3ef49c1f5b041b1c6bd77a514e2f9dd63d913cc4e8a3a
7
+ data.tar.gz: bc2057d4d6aed38010c635fa56d91f756d5ecbbfc527d5b21ff2c4d04457b5672367321d00499d8e7a37c374352891ce15c14210c94738ef52114ff2676fdb1d
@@ -28,6 +28,35 @@ jobs:
28
28
  - name: Build gem
29
29
  run: bundle exec gem build *.gemspec
30
30
 
31
+ # Watches unreleased Rails, because flow_chat's activesupport and actionpack
32
+ # dependencies are deliberately unbounded above (see flow_chat.gemspec).
33
+ #
34
+ # Allowed to fail. A red run here means Rails main changed something this gem
35
+ # relies on, and is a prompt to look rather than a broken build - the point is
36
+ # to find out while the change is still unreleased, instead of from a bug
37
+ # report the week the major ships.
38
+ rails-main:
39
+ runs-on: ubuntu-latest
40
+ continue-on-error: true
41
+ env:
42
+ BUNDLE_GEMFILE: gemfiles/rails_main.gemfile
43
+
44
+ steps:
45
+ - uses: actions/checkout@v4
46
+
47
+ # Newest stable, deliberately ahead of the matrix above. Rails main already
48
+ # requires Ruby >= 3.3 (via ractor-dispatch) and that floor keeps rising, so
49
+ # pinning this job to the minimum would fail it for a Ruby version rather
50
+ # than for the API change it exists to catch.
51
+ - name: Set up Ruby
52
+ uses: ruby/setup-ruby@v1
53
+ with:
54
+ ruby-version: '3.4'
55
+ bundler-cache: true
56
+
57
+ - name: Run tests against rails main
58
+ run: bundle exec rake test
59
+
31
60
  lint:
32
61
  runs-on: ubuntu-latest
33
62
  steps:
@@ -0,0 +1,43 @@
1
+ name: Deploy landing page to Pages
2
+
3
+ on:
4
+ # Runs on pushes to the default branch that touch the site.
5
+ push:
6
+ branches: [master]
7
+ paths:
8
+ - "site/**"
9
+ - ".github/workflows/pages.yml"
10
+
11
+ # Allows running this workflow manually from the Actions tab.
12
+ workflow_dispatch:
13
+
14
+ # Grant GITHUB_TOKEN the permissions required to deploy to GitHub Pages.
15
+ permissions:
16
+ contents: read
17
+ pages: write
18
+ id-token: write
19
+
20
+ # Allow one concurrent deployment; don't cancel an in-progress production deploy.
21
+ concurrency:
22
+ group: pages
23
+ cancel-in-progress: false
24
+
25
+ # No build step: the page is a single static file. Upload site/ and deploy it.
26
+ jobs:
27
+ deploy:
28
+ environment:
29
+ name: github-pages
30
+ url: ${{ steps.deployment.outputs.page_url }}
31
+ runs-on: ubuntu-latest
32
+ steps:
33
+ - name: Checkout
34
+ uses: actions/checkout@v4
35
+ - name: Setup Pages
36
+ uses: actions/configure-pages@v4
37
+ - name: Upload artifact
38
+ uses: actions/upload-pages-artifact@v3
39
+ with:
40
+ path: site
41
+ - name: Deploy to GitHub Pages
42
+ id: deployment
43
+ uses: actions/deploy-pages@v4
data/.gitignore CHANGED
@@ -12,4 +12,7 @@
12
12
 
13
13
  # Ignore Gemfile.lock for our gem
14
14
  /Gemfile.lock
15
- .DS_Store
15
+ .DS_Store
16
+ # Resolved fresh on every CI run, so the rails-main job sees the latest main
17
+ # rather than a pinned revision.
18
+ gemfiles/*.lock
data/CHANGELOG.md CHANGED
@@ -2,6 +2,55 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [0.10.1] - 2026-08-17
6
+
7
+ ### Bug Fixes
8
+
9
+ - Publish side events when no foreground pass ran
10
+
11
+ ### Documentation
12
+
13
+ - Record #9 in the 0.10.0 release notes
14
+
15
+ ### Miscellaneous Tasks
16
+
17
+ - State the Ruby floor, and watch unreleased Rails instead of capping ([#10](https://github.com/radioactive-labs/flow_chat/issues/10))
18
+ - Prepend the changelog instead of regenerating it
19
+
20
+ ## [0.10.0] - 2026-08-17
21
+
22
+ > **Note.** [#9](https://github.com/radioactive-labs/flow_chat/pull/9) was squash-merged with a non-conventional title, so git-cliff did not pick it up when this section was generated. It is the largest change in the release and is listed by hand below. Releases now prepend rather than regenerate, so this survives.
23
+
24
+ ### Behaviour changes
25
+
26
+ - **Intercom resolves numbers only.** The renderer already prints a number beside every option and asks for one; matching typed labels as well is what allowed two options reading the same to collapse onto a single mapping entry. Typing the words now falls through to the flow's own validation.
27
+ - **HTTP matches replies exactly**, with no case or whitespace folding. A web client echoes back the string it was handed, so nothing drifts in transit. A client that lowercases its reply will stop resolving.
28
+
29
+ ### Bug Fixes
30
+
31
+ - Correct runtime-breaking session and API misuse
32
+ - Use the full SHA256 for hashed identifiers
33
+ - Use a 128-bit (32-char) hashed identifier
34
+ - Give api.error a contract other than its prose ([#5](https://github.com/radioactive-labs/flow_chat/issues/5))
35
+
36
+ ### Documentation
37
+
38
+ - [**breaking**] Revamp README and all docs, add GitHub Pages landing page ([#3](https://github.com/radioactive-labs/flow_chat/issues/3))
39
+ - Explain how session boundaries build the session id
40
+
41
+ ### Features
42
+
43
+ - Add Facebook Messenger and Instagram DM gateways, unify choice resolution, and fix delivery instrumentation ([#9](https://github.com/radioactive-labs/flow_chat/pull/9))
44
+ - Map choices on Intercom and HTTP ([#4](https://github.com/radioactive-labs/flow_chat/issues/4))
45
+ - Let a flow declare that it consumed the turn ([#6](https://github.com/radioactive-labs/flow_chat/issues/6))
46
+ - Report a reply the platform would not take ([#7](https://github.com/radioactive-labs/flow_chat/issues/7))
47
+ - Dispatch webhooks on their field, and handle coexistence ([#8](https://github.com/radioactive-labs/flow_chat/issues/8))
48
+
49
+ ### Refactoring
50
+
51
+ - Fix outdated APIs, dedupe, and harden
52
+ - Drop dead first_message? branch in Intercom flow
53
+
5
54
  ## [0.9.0] - 2026-07-09
6
55
 
7
56
  ### Features