A Dart/Flutter client for the tailcompany-wp-proxy
service — a small, read-only HTTP proxy in front of The Tail Company's
WooCommerce Store API and WordPress blog API.
The library gives you typed models, a ThumbHash decoder, structured errors, and full control over the underlying Dio instance.
- Pure Dart, so it works in Flutter and on the server. No Flutter SDK needed.
- Bring your own
Dio(interceptors, custom adapter, caching, logging) or let the client create one for you. - Decodes the base64 ThumbHash placeholder every product and post carries.
From pub (once published):
dependencies:
tail_company_wp_proxy: ^0.1.0Or directly from source, using a path or git dependency:
dependencies:
tail_company_wp_proxy:
path: ../TailCompanyWpProxyLibraryimport 'package:tail_company_wp_proxy/tail_company_wp_proxy.dart';
final client = TailCompanyWpProxyClient(baseUrl: 'http://localhost:3000');
final products = await client.getProducts(count: 5);
for (final product in products) {
print('${product.name} — ${product.permalink}');
}
final posts = await client.getBlogPosts();
for (final post in posts) {
print('${post.dateRaw} ${post.name}');
}
client.close(); // closes the Dio only if the client created itThe proxy is read-only and unauthenticated, so no credentials are needed.
Pass any configured Dio to take over transport concerns. The client uses it
as-is and never closes it:
import 'package:dio/dio.dart';
import 'package:tail_company_wp_proxy/tail_company_wp_proxy.dart';
final dio = Dio(BaseOptions(baseUrl: 'http://localhost:3000/'))
..interceptors.add(LogInterceptor());
final client = TailCompanyWpProxyClient(dio: dio);If you pass both dio and baseUrl, baseUrl overrides the instance's own
base URL. If you pass a Dio with no base URL and no baseUrl, the client
defaults to http://localhost:3000.
| Method | Endpoint | Returns |
|---|---|---|
getProducts({int? count}) |
GET /products |
List<Product> |
getProductsResponse({int? count}) |
GET /products |
ProxyResponse<List<Product>> |
getBlogPosts() |
GET /blog |
List<BlogPost> |
getBlogPostsResponse() |
GET /blog |
ProxyResponse<List<BlogPost>> |
getInfo() |
GET / |
ProxyInfo |
getHealth() |
GET /health |
HealthStatus |
isHealthy() |
GET /health |
bool (never throws) |
Products are returned on-sale first and re-randomised on every request. count
is clamped by the proxy to its configured maximum.
The ...Response variants wrap the data with the proxy's cache metadata:
final response = await client.getProductsResponse(count: 3);
switch (response.cacheSource) {
case CacheSource.cache: // fresh in-memory hit
case CacheSource.upstream:
case CacheSource.refresh:
case CacheSource.stale: // expired copy served because upstream is down
case CacheSource.unknown:
}Product: id, name, onSale, isInStock, permalink, thumbnail,
thumbhash, plus permalinkUri, thumbnailUri, and thumbhashBytes
convenience getters.
BlogPost: id, name, dateRaw, date (parsed, may be null), url,
thumbnail, thumbhash, plus urlUri, thumbnailUri, and thumbhashBytes.
Every product and post carries a base64 ThumbHash placeholder for an instant blurred preview while the real image loads. Decode it to raw RGBA, or read just the average colour for a solid background:
final hash = product.thumbhashBytes;
if (hash != null) {
final image = thumbHashToRgba(hash); // width, height, rgba
final average = thumbHashToAverageRgba(hash); // r, g, b, a in 0..1
final ratio = thumbHashToApproximateAspectRatio(hash);
}decodeThumbhashBase64(String?) is also exported for raw base64 values.
Every failure is a TailCompanyWpProxyException (or a subclass):
| Type | When |
|---|---|
ProxyConnectionException |
The proxy could not be reached at all. |
ProxyBadRequestException |
400 — the request was rejected. |
ProxyNotFoundException |
404 — unknown route. |
ProxyMethodNotAllowedException |
405 — wrong HTTP method. |
ProxyUnavailableException |
502 — the proxy could not reach upstream. |
ProxyUnexpectedResponseException |
Any other status, or an undecodable body. |
Each exception exposes message, statusCode, the proxy's machine-readable
code (for example upstream_unavailable), and the uri.
dart pub get
dart analyze
dart testMIT. The ThumbHash decoder in lib/src/thumbhash.dart is a Dart port of the
reference implementation at https://github.com/evanw/thumbhash, which is MIT
licensed.