Tracelet Supabase Adapter

The official Supabase adapter for Tracelet.

_{⚡ Set up Tracelet with AI. Clicking the badge opens Tracelet and copies a ready-made prompt — paste it into your AI coding assistant (Cursor, Claude Code, Kiro, Copilot Chat…) and it interviews you, then installs and configures Tracelet with the Supabase adapter in your Flutter app.}

This adapter seamlessly connects Tracelet's battery-efficient native HTTP sync engine directly to your Supabase project. It automatically configures Tracelet to push locations to a Postgres RPC function or Edge Function, and manages background auth token (JWT) refresh natively.

🚀 Features

• Direct Postgres Sync — Sync locations straight into your Supabase database via an RPC function, bypassing middleman servers.
• Edge Function Support — Alternatively, route locations through a Supabase Edge Function for custom processing before insertion.
• Auto Token Refresh — Automatically detects 401 Unauthorized errors in the background and refreshes the Supabase Auth session natively, even when the Flutter app is terminated.
• Batch Syncing — Fully compatible with Tracelet's robust HTTP batch engine (exponential backoff, offline queues, Wi-Fi-only sync).
• Enterprise Tested — 100% test coverage using Mocktail and Dependency Injection.

📦 Getting Started

1. Set up Supabase in your Flutter app using supabase_flutter.
2. Initialize Tracelet using TraceletSupabase.

import 'package:supabase_flutter/supabase_flutter.dart';
import 'package:tracelet_supabase/tracelet_supabase.dart';
import 'package:tracelet/tracelet.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await Supabase.initialize(
    url: 'https://xyz.supabase.co',
    anonKey: 'your_anon_key',
  );

  // 1. Configure the auto-token refresher
  await TraceletSupabase.configureTokenRefresh(anonKey: 'your_anon_key');

  // 2. Build the HTTP Config pointing to your Supabase RPC
  final httpConfig = TraceletSupabase.buildHttpConfig(
    supabaseUrl: 'https://xyz.supabase.co',
    anonKey: 'your_anon_key',
    rpcFunction: 'insert_tracelet_locations',
  );

  // 3. Start Tracelet
  await Tracelet.ready(Config(
    http: httpConfig,
  ));
}

🛠 Customizing the Payload (Route Context)

If you want to inject custom data (like a driver_id or trip_id) into every location point dynamically, use the Tracelet.setRouteContext() API in Dart:

await Tracelet.setRouteContext(RouteContext(
  taskId: 'order_123',
  custom: {'trip_id': 'trip_456'},
));

The route context data travels with the location row through the SQLite queue and is included natively in the Supabase REST payload.

🤝 Contributing

See the root CONTRIBUTING.md for guidelines.

📄 License

Apache 2.0 — see LICENSE for details.