Skip to main content

heardock_core 0.1.0 copy "heardock_core: ^0.1.0" to clipboard
heardock_core: ^0.1.0 copied to clipboard

Headless Heardock client for Flutter: context capture, idempotent submission, and an offline queue with no UI attached. Bring your own feedback form.

heardock_core #

Headless in-app feedback for Flutter. Configure once, submit from your own form, and get context capture, idempotency, and an offline queue without a single widget in your tree.

Alpha (0.1.0). This is the headless half of the Flutter SDK; the bundled bottom sheet lives in heardock_flutter.

Why this package exists #

heardock_flutter ships a Material 3 sheet. That is the fastest path, but it also means Heardock chooses the layout, copy, and interaction. If your app has its own design system, a Cupertino-first UI, or a full-screen feedback flow, use this package and keep every pixel.

You want Use
A working feedback sheet in one line heardock_flutter
Your own form, Heardock only transports heardock_core
The sheet, themed to match heardock_flutter + HeardockTheme

Both packages share the same config, payload, error codes, and offline queue, so you can start with the sheet and swap in a custom form later without changing the backend.

Install #

flutter pub add heardock_core

Configure (once) #

import 'package:flutter/material.dart';
import 'package:heardock_core/heardock_core.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized(); // plugins read device info

  HeardockCore.configure(
    HeardockConfig(
      publicKey: 'hd_pub_ab12cd34',
      // baseUrl: 'http://localhost:3000', // local Next.js app
      collect: const CollectOptions(device: true, locale: true, screen: true),
    ),
  );

  runApp(const MyApp());
}

The publishable key (hd_pub_…) is safe to embed in a client. Never use a secret key in an app.

Submit from your own form #

Future<void> send(String message) async {
  try {
    final result = await HeardockCore.submit(
      message: message,
      category: FeedbackCategory.bug,
      email: 'bob@example.com', // optional
      metadata: {'plan': 'pro'},
    );

    if (result.queued) {
      // Saved on the device; the SDK retries with backoff.
      showBanner('We’ll send this when you’re back online.');
    } else {
      showBanner('Thanks — reference ${result.displayReference}');
    }
  } on ArgumentError {
    // Empty message. Validate before calling if you want inline errors.
  } on HeardockException catch (error) {
    final copy = HeardockStrings.resolve('zh-CN').errorFor(error);
    showBanner(copy);
  }
}

HeardockException.message is developer-facing and may be English-only. HeardockStrings.errorFor maps invalid_key, rate_limited, 4xx validation, and everything else to localized, user-facing copy (English + Simplified Chinese built in).

Read your threads #

Each install gets a device token (stored locally) that can read back the notes it submitted:

final threads = await HeardockCore.threads();
final thread = await HeardockCore.thread('fb_01J…');
await HeardockCore.markSeen('fb_01J…'); // clears the unread flag

await HeardockCore.deleteThread('fb_01J…'); // hides it from this device; the team keeps it
  • The first threads() call registers the device server-side (empty list), so a fresh install is not an error.
  • Notes still in the offline queue are returned first as pending threads (FeedbackThread.pending), sorted newest first; thread(id) resolves those local ids without a request.
  • Offline, threads() still returns those pending notes; with nothing queued it throws a network_error. There is no history cache by design.
  • The token, seen marks, and the offline queue persist. On top of that the SDK keeps a read-only snapshot of the list and threads in SharedPreferences (persistHistory, on by default), so a cold start paints the last known history before the network answers. The snapshot is bound to the device token and public key, expires after HeardockCore.persistTtl (7 days), is capped at 50 threads / 512 KB, and never leaves the device. Set HeardockConfig(persistHistory: false) to keep message content out of local storage, and call clearPersistedCache() to wipe it.
  • threads() sets FeedbackThread.unread by comparing last_reply_at with the local seen mark.
  • List and thread responses are cached in memory for 5 minutes (HeardockCore.cacheTtl). Pass refresh: true to threads() / thread() to force a network read, clearCache() to drop memory, or clearPersistedCache() to delete the on-device snapshot too. A cached thread beats an error screen when a refresh fails.
  • revalidatedThread(id) is the detail-page loader: it returns the cached copy when it is younger than revalidateAfter (30s), otherwise fetches once and shares that request with concurrent callers. A failed revalidation returns the cached copy instead of throwing.
  • deleteThread(id) is a soft delete at the API level: the note disappears from this device's reads, while the server keeps the note and every team reply for the inbox. Queued notes are removed from the device queue instead, without a request.
  • Users cannot reply; the team's messages are read-only. A new note is the only way to add something.
  • Pull when the feedback page opens / on refresh. There is no push.

Show what will be attached #

final context = await HeardockCore.captureContext();
// context.appVersion, buildNumber, platform, osVersion, deviceModel, locale,
// screen — null when a probe was unavailable or switched off.

Pass a snapshot back into submit when the form opened before the user typed:

final snapshot = await HeardockCore.captureContext();
// ... user writes ...
await HeardockCore.submit(message: text, context: snapshot);

Page context and identity #

// Call on every route change; falls back to null when you do not.
HeardockCore.setContext(page: '/settings/export', metadata: {'plan': 'pro'});

// Opt-in identity; nothing is collected implicitly.
HeardockCore.identify(id: 'u_123', email: 'bob@example.com', name: 'Bob');
HeardockCore.clearIdentity();
HeardockCore.clearContext();

captureContext() and submit() without an explicit screen use the page set through setContext. Unlike Heardock.show, the headless API cannot guess the current ModalRoute — set it yourself if the screen matters.

Offline queue #

final waiting = await HeardockCore.pendingCount(); // badge your entry point

final report = await HeardockCore.flushQueue();
// report.sent, report.dropped, report.pending
  • Network errors, timeouts, 429, and 5xx are queued (max 20 items).
  • 4xx validation/auth errors throw instead of queueing — retrying will not help.
  • Backoff: 1s → 5s → 30s → 2m → 10m, five attempts, then dropped.
  • The queue is drained on configure, on flushQueue(), and when the bundled sheet opens. There is no background scheduler; call flushQueue() from your own app lifecycle hook if you need one.
  • Idempotency keys make retries safe: a retry cannot duplicate a note.

API #

Member Purpose
configure(HeardockConfig) Set key, base URL, collection switches, timeout, queue cap
identify(...) / clearIdentity() Optional user id / email / name
setContext(...) / clearContext() Current page and metadata
captureContext({screen, metadata}) Snapshot without submitting
submit({message, category, email, metadata, context}) Send, or queue on retryable failure
flushQueue() Retry now; returns QueueFlushReport
pendingCount() Notes waiting on the device
threads({refresh}) Notes submitted by this install, with unread flags; queued notes appear first as pending
thread(id, {refresh}) One thread with its team messages (or the local copy for a queued note)
deleteThread(id) Hide the note from this device (server keeps it for the team); queued copies are dropped locally
revalidatedThread(id) Cached thread, revalidated at most once per revalidateAfter (30s), single-flight
cachedThread(id) / clearCache() Read or drop the in-memory thread cache
markSeen(id) Clear the local unread flag
isConfigured / config / user / page / metadata Read-only state

What is collected #

Field Source Toggle
app_version, build_number package_info_plus always on
platform dart:io (ios, android, …) always on
os_version, device device_info_plus CollectOptions.device
locale PlatformDispatcher.locale CollectOptions.locale
screen setContext / captureContext CollectOptions.screen
user id / email / name identify() / submit(email:) opt-in
metadata setContext / submit opt-in

No contacts, photos, clipboard, or advertising IDs. Feedback is plain text; attachments are not in 0.1.0.

Local development #

This package has no path dependencies of its own. heardock_flutter and its example app resolve it locally through their pubspec_overrides.yaml files; published releases resolve heardock_core from pub.dev.

# from the repo root
pnpm install && pnpm dev

cd packages/sdk-core
flutter test

Demo key hd_pub_demo_fieldnote, inbox at http://localhost:3000/inbox?token=dev.

Not in 0.1.0 #

  • File / screenshot attachments.
  • Background retry scheduling (no workmanager dependency).
  • A hosted fallback URL for WebView.
  • Swift and Web clients.
0
likes
150
points
40
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

Headless Heardock client for Flutter: context capture, idempotent submission, and an offline queue with no UI attached. Bring your own feedback form.

Homepage
Repository (GitHub)
View/report issues

License

MIT (license)

Dependencies

device_info_plus, flutter, http, package_info_plus, shared_preferences

More

Packages that depend on heardock_core