Skip to content

About

Shared files between app and backend

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

tail_app_wp_proxy

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.

Install

From pub (once published):

dependencies:
  tail_company_wp_proxy: ^0.1.0

Or directly from source, using a path or git dependency:

dependencies:
  tail_company_wp_proxy:
    path: ../TailCompanyWpProxyLibrary

Quick start

import '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 it

The proxy is read-only and unauthenticated, so no credentials are needed.

Supplying a custom Dio

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.

API

TailCompanyWpProxyClient

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:
}

Models

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.

ThumbHash placeholders

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.

Errors

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.

Development

dart pub get
dart analyze
dart test

License

MIT. 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.

About

Shared files between app and backend

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages