docs(examples): add Edge Functions example (#1632)

## What

Adds an `edge_functions` example under `examples/`, following the same
structure as `database_crud` and `storage_transforms`. It demonstrates
invoking Supabase Edge Functions with `supabase.functions.invoke(...)`:

- **JSON body over POST**, reading the JSON response back
(`invoke('greet', body: {...})`).
- **GET with query parameters** instead of a body (`method:
HttpMethod.get, queryParameters: {...}`).
- **Custom headers** sent to the function and echoed back (`headers:
{...}`).
- **Plain text in and out**: a `String` body is sent as `text/plain` and
the `text/plain` response arrives as a `String` (`invoke('shout', body:
text)`).
- **Error handling**: a non-2xx response throws a `FunctionException`
whose `details` carry the response body (`invoke('word-count', ...)`).

## How it's structured

- All Edge Function access lives in `lib/functions_repository.dart`
(`FunctionsRepository`), kept separate from the UI so the calls are easy
to read and to drive from tests. Models with `factory fromJson` live in
`lib/models.dart`. The Material 3 UI in `lib/main.dart` stays thin.
- Three demo functions ship under `examples/supabase/functions/`:
`greet`, `shout` and `word-count`.
- The Edge Runtime is enabled in `examples/supabase/config.toml`;
`supabase start` serves the functions automatically. The demo functions
set `verify_jwt = false` so the example can call them with just the
publishable key, matching the other examples which run unauthenticated.
- The new package is registered in the workspace `pubspec.yaml` and
listed in `examples/README.md`.

## Testing

- `dart format .` and `flutter analyze` are clean.
- `integration_test/functions_test.dart` was run against the local stack
(`supabase start`) on web (Chrome 150) via `flutter drive`: **all tests
passed**. It covers the repository flow (JSON greeting over POST and
GET, plain-text transform, and a 400 validation error surfacing as a
`FunctionException`) plus a UI smoke test.

A stacked PR (#1633) adds a full end-to-end suite covering the entire
`functions.invoke` surface.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **New Features**
  - Added a Flutter example demonstrating Supabase Edge Functions.
- Added greeting, plain-text transformation, and word-count function
examples.
- Added support for POST requests, query parameters, custom headers, and
error handling.
- Enabled the example to run in the browser and against the local stack.

- **Documentation**
- Added setup, usage, project structure, and integration testing
instructions.

- **Tests**
- Added end-to-end coverage for function responses, validation errors,
and UI interactions.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: spydon

examples/README.md

@@ -6,6 +6,7 @@ all sharing a single local Supabase instance.
 | Example                                     | What it shows                                    |
 | ------------------------------------------- | ------------------------------------------------ |
 | [`database_crud`](database_crud)            | Database CRUD with PostgREST (`from(...)`)       |
+| [`edge_functions`](edge_functions)          | Invoking Edge Functions (`functions.invoke(...)`)|
 | [`passkeys`](passkeys)                      | Passkey (WebAuthn) sign in and management        |
 | [`storage_transforms`](storage_transforms) | Storage uploads, downloads and image transforms  |
 

examples/edge_functions/.gitignore

@@ -0,0 +1,6 @@
+.dart_tool/
+.flutter-plugins
+.flutter-plugins-dependencies
+build/
+pubspec.lock
+pubspec_overrides.yaml

examples/edge_functions/README.md

@@ -0,0 +1,68 @@
+# Edge Functions
+
+A small app that shows how to call Supabase Edge Functions with
+`supabase.functions.invoke(...)`:
+
+- **Invoke with a JSON body** over POST and read the JSON response back
+  (`invoke('greet', body: {...})`).
+- **Invoke over GET** with query parameters instead of a body
+  (`invoke('greet', method: HttpMethod.get, queryParameters: {...})`).
+- **Send custom headers** to the function (`headers: {...}`), echoed back in the
+  response.
+- **Send and receive plain text**: a `String` body is sent as `text/plain` and a
+  `text/plain` response comes back as a `String` (`invoke('shout', body: text)`).
+- **Handle errors**: a non-2xx response throws a `FunctionException` whose
+  `details` carry the response body (`invoke('word-count', ...)`).
+
+All Edge Function access is in
+[`lib/functions_repository.dart`](lib/functions_repository.dart), kept separate
+from the UI so the calls are easy to read and to drive from an integration test.
+
+To keep the focus on the Supabase calls, the screen uses plain `setState` rather
+than pulling in a state management package. A larger app would typically reach
+for a state management solution (for example Riverpod, Bloc or Provider) instead.
+
+The functions live in the shared Supabase config in
+[`../supabase`](../supabase): their code is under `functions/` (`greet`, `shout`
+and `word-count`), and the Edge Runtime is enabled in `config.toml`
+(`[edge_runtime]`). `supabase start` serves every function while the stack is
+running. The functions need no database tables or seed data.
+
+The demo functions set `verify_jwt = false` in `config.toml` so the example can
+call them with just the publishable (anon) key, matching the other examples,
+which run unauthenticated. A real app would leave JWT verification on and read
+the caller's user from the request.
+
+## Running
+
+From the `examples` directory, run the launcher and pick `edge_functions`:
+
+```bash
+./run.sh
+```
+
+Or run it directly against any project (with the functions deployed there):
+
+```bash
+flutter run \
+  --dart-define=SUPABASE_URL=https://YOUR_PROJECT.supabase.co \
+  --dart-define=SUPABASE_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
+```
+
+## Integration test
+
+[`integration_test/functions_test.dart`](integration_test/functions_test.dart)
+is an end-to-end test that runs against the local stack. It drives the flow
+through the repository (a JSON greeting over POST and GET, a plain-text
+transform, and a validation error that surfaces as a `FunctionException`) and
+drives the app widgets to greet through the UI.
+
+With the local stack running, pass the same defines the app uses and run it on a
+device (integration tests need one, so `-d macos`, an emulator or a real
+device):
+
+```bash
+flutter test integration_test/functions_test.dart -d macos \
+  --dart-define=SUPABASE_URL=http://localhost:54321 \
+  --dart-define=SUPABASE_PUBLISHABLE_KEY=YOUR_LOCAL_PUBLISHABLE_KEY
+```

examples/edge_functions/analysis_options.yaml

@@ -0,0 +1 @@
+include: package:supabase_lints/analysis_options_flutter.yaml

examples/edge_functions/integration_test/functions_test.dart

@@ -0,0 +1,103 @@
+import 'package:edge_functions_example/functions_repository.dart';
+import 'package:edge_functions_example/main.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:integration_test/integration_test.dart';
+import 'package:supabase_flutter/supabase_flutter.dart';
+
+const supabaseUrl = String.fromEnvironment('SUPABASE_URL');
+const supabasePublishableKey = String.fromEnvironment(
+  'SUPABASE_PUBLISHABLE_KEY',
+);
+
+/// End-to-end tests that drive the Edge Functions example against the local
+/// stack.
+///
+/// The first test exercises the core flow through the repository (a JSON
+/// greeting over POST and GET, a plain-text transform, and a validation error),
+/// asserting on what each function returns. The second drives the app widgets to
+/// confirm the greeting card is wired to the function. Edge Functions are
+/// stateless, so there is nothing to clean up between runs.
+void main() {
+  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+
+  late FunctionsRepository repository;
+
+  setUpAll(() async {
+    await Supabase.initialize(
+      url: supabaseUrl,
+      publishableKey: supabasePublishableKey,
+    );
+    repository = FunctionsRepository(Supabase.instance.client);
+  });
+
+  tearDownAll(() async {
+    await Supabase.instance.dispose();
+  });
+
+  testWidgets('invokes the example functions through the repository', (
+    tester,
+  ) async {
+    // POST with a JSON body: the function greets and echoes how it was called.
+    final posted = await repository.greet(name: 'Ada', excited: true);
+    expect(posted.message, 'Hello, Ada!!!');
+    expect(posted.method, 'POST');
+    expect(posted.source, 'flutter-app');
+
+    // GET with a query parameter reaches the same function a different way.
+    final fetched = await repository.greetViaQuery('Grace');
+    expect(fetched.message, 'Hello, Grace.');
+    expect(fetched.method, 'GET');
+
+    // A plain-text response comes back as a String.
+    final shouted = await repository.shout('edge functions');
+    expect(shouted, 'EDGE FUNCTIONS');
+
+    // A JSON response decodes into the model.
+    final count = await repository.countWords('one two three');
+    expect(count.words, 3);
+    expect(count.characters, 13);
+
+    // An empty input makes the function respond with a 400, which surfaces as a
+    // FunctionException carrying the JSON error body.
+    await expectLater(
+      repository.countWords(''),
+      throwsA(
+        isA<FunctionException>()
+            .having((error) => error.status, 'status', 400)
+            .having(
+              (error) => (error.details as Map)['error'],
+              'details.error',
+              isA<String>(),
+            ),
+      ),
+    );
+  });
+
+  testWidgets('greets through the UI', (tester) async {
+    await tester.pumpWidget(const EdgeFunctionsExampleApp());
+    await tester.pumpAndSettle();
+
+    // Tapping "Greet (POST)" invokes the function and shows its message.
+    await tester.tap(find.widgetWithText(FilledButton, 'Greet (POST)'));
+    await _pumpUntil(tester, find.textContaining('Hello, Ada'));
+    expect(find.textContaining('via POST'), findsOneWidget);
+  });
+}
+
+/// Pumps frames until [finder] matches at least one widget or [timeout] elapses.
+///
+/// Invoking a function goes over the network, so the UI can't be settled with
+/// `pumpAndSettle`; this polls the widget tree instead.
+Future<void> _pumpUntil(
+  WidgetTester tester,
+  Finder finder, {
+  Duration timeout = const Duration(seconds: 20),
+}) async {
+  final deadline = DateTime.now().add(timeout);
+  while (DateTime.now().isBefore(deadline)) {
+    await tester.pump(const Duration(milliseconds: 100));
+    if (finder.evaluate().isNotEmpty) return;
+  }
+  fail('Timed out waiting for: $finder');
+}

examples/edge_functions/lib/functions_repository.dart

@@ -0,0 +1,63 @@
+import 'package:supabase_flutter/supabase_flutter.dart';
+
+import 'models.dart';
+
+/// All Edge Function access for the example lives here, so the UI stays thin and
+/// every `supabase.functions.invoke(...)` call is easy to read and to exercise
+/// from an integration test.
+class FunctionsRepository {
+  FunctionsRepository(this._client);
+
+  final SupabaseClient _client;
+
+  FunctionsClient get _functions => _client.functions;
+
+  /// Invokes the `greet` function over POST with a JSON body and returns the
+  /// greeting it builds server-side.
+  ///
+  /// The custom `x-greeting-source` header is echoed back in the response, so
+  /// the example can show that headers set here reach the function. A JSON body
+  /// comes back decoded as a `Map`, which [Greeting.fromJson] turns into a model.
+  Future<Greeting> greet({required String name, bool excited = false}) async {
+    final response = await _functions.invoke(
+      'greet',
+      body: {'name': name, 'excited': excited},
+      headers: const {'x-greeting-source': 'flutter-app'},
+    );
+    return Greeting.fromJson(response.data as Map<String, dynamic>);
+  }
+
+  /// Invokes the same `greet` function over GET, passing the name as a query
+  /// parameter instead of a body.
+  Future<Greeting> greetViaQuery(String name) async {
+    final response = await _functions.invoke(
+      'greet',
+      method: HttpMethod.get,
+      queryParameters: {'name': name},
+    );
+    return Greeting.fromJson(response.data as Map<String, dynamic>);
+  }
+
+  /// Sends [text] to the `shout` function and returns the uppercased text it
+  /// responds with.
+  ///
+  /// A `String` body is sent as `text/plain`, and the function replies with
+  /// `text/plain` too, so `response.data` is a `String` rather than decoded JSON.
+  Future<String> shout(String text) async {
+    final response = await _functions.invoke('shout', body: text);
+    return response.data as String;
+  }
+
+  /// Invokes the `word-count` function, which validates its input.
+  ///
+  /// When [text] is empty the function replies with a 400 and a JSON error body,
+  /// which surfaces here as a [FunctionException] whose `details` hold that body.
+  /// The caller is expected to handle that exception.
+  Future<WordCount> countWords(String text) async {
+    final response = await _functions.invoke(
+      'word-count',
+      body: {'text': text},
+    );
+    return WordCount.fromJson(response.data as Map<String, dynamic>);
+  }
+}