heardock_core 0.1.0
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 inheardock_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
pendingthreads (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 anetwork_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 afterHeardockCore.persistTtl(7 days), is capped at 50 threads / 512 KB, and never leaves the device. SetHeardockConfig(persistHistory: false)to keep message content out of local storage, and callclearPersistedCache()to wipe it. threads()setsFeedbackThread.unreadby comparinglast_reply_atwith the local seen mark.- List and thread responses are cached in memory for 5 minutes
(
HeardockCore.cacheTtl). Passrefresh: truetothreads()/thread()to force a network read,clearCache()to drop memory, orclearPersistedCache()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 thanrevalidateAfter(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, onflushQueue(), and when the bundled sheet opens. There is no background scheduler; callflushQueue()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.