shrtnr: URL Shortener SDK for Dart and Flutter

Dart client for creating short links, managing URLs, and reading click analytics from a shrtnr instance. Works on the Dart VM, Flutter (mobile, desktop, web), and anywhere package:http runs.

Install

dart pub add shrtnr

or for Flutter:

flutter pub add shrtnr

Quick Start

import 'package:shrtnr/shrtnr.dart';

final client = ShrtnrClient(
  baseUrl: 'https://your-shrtnr.example.com',
  auth: const ApiKeyAuth(apiKey: 'sk_your_api_key'),
);

// Shorten a URL
final link = await client.createLink(
  const CreateLinkOptions(
    url: 'https://example.com/long-page',
    label: 'Campaign landing page',
  ),
);

print(link.id);           // 1
print(link.slugs.first);  // primary slug

What This SDK Covers

This package wraps the public link-management API:

Shorten URLs (create short links)
Add, disable, enable, and remove custom slugs
List, read, update, disable, enable, and delete links
List links by owner identity
Read click analytics (referrer, country, device, browser)
Group links into bundles and read combined engagement stats
Check service health

Administrative operations (API key management, settings, dashboard stats) are not part of this package. Those are accessible through the admin UI.

API Reference

`createLink`

Shorten a URL. Returns a Link with a random slug.

final link = await client.createLink(
  CreateLinkOptions(
    url: 'https://example.com',
    label: 'My link to the example page',
    expiresAt: DateTime.now().toUtc().add(const Duration(days: 1)),
  ),
);

To add a custom slug, call addCustomSlug after creation:

final link = await client.createLink(
  const CreateLinkOptions(url: 'https://example.com'),
);
final slug = await client.addCustomSlug(link.id, 'my-campaign');

`listLinks`

List all short links.

final links = await client.listLinks();

`getLink`

Get a single link by ID, including its slugs and click count.

final link = await client.getLink(123);

`getLinkBySlug`

Get a single link by its short URL slug (including custom slugs).

final link = await client.getLinkBySlug('my-custom-slug');

`updateLink`

Update a link's URL, label, or expiry. Pass clearLabel: true or clearExpiresAt: true to explicitly null a field on the server.

final updated = await client.updateLink(
  123,
  const UpdateLinkOptions(
    label: 'Updated label',
    clearExpiresAt: true,
  ),
);

`disableLink`

Disable a link so it stops redirecting.

final disabled = await client.disableLink(123);

`enableLink`

Re-enable a previously disabled link.

final link = await client.enableLink(123);

`deleteLink`

Permanently delete a link. Only succeeds if the link has zero clicks: disable it instead if it has traffic.

await client.deleteLink(123);

`listLinksByOwner`

List all links created by a specific identity (typically an email address).

final links = await client.listLinksByOwner('user@example.com');

`addCustomSlug`

Add a custom short URL slug to an existing link. Throws ShrtnrException with status 409 if the slug already exists, or 400 for invalid format.

final slug = await client.addCustomSlug(123, 'campaign');

`disableSlug`

Disable a custom slug without affecting the parent link or its other slugs.

await client.disableSlug(123, 'campaign');

`enableSlug`

Re-enable a disabled custom slug.

await client.enableSlug(123, 'campaign');

`removeSlug`

Permanently remove a custom slug. Only succeeds if the slug has zero clicks.

await client.removeSlug(123, 'campaign');

`getLinkQR`

Fetch the QR code SVG for a link as a string. Optionally specify which slug to encode.

final svg = await client.getLinkQR(123);
final svgForSlug = await client.getLinkQR(123, slug: 'my-campaign');

`getLinkAnalytics`

Read click analytics for a link: referrer, country, device type, and browser breakdown. Defaults to all-time. Pass an optional range to scope results to a window.

final lifetime = await client.getLinkAnalytics(123);
final last7d = await client.getLinkAnalytics(123, range: '7d');
print(lifetime.totalClicks);
print(lifetime.countries);

`health`

Check service health and version.

final health = await client.health();
print(health.version);

`createBundle`

Create a bundle to group related links. Returns the new Bundle.

final bundle = await client.createBundle(
  const CreateBundleOptions(
    name: 'Spring campaign',
    description: 'Email, social, and paid drops',
    icon: 'sparkles',
    accent: BundleAccent.purple,
  ),
);

`listBundles`

List bundles with summary stats: lifetime click total, 30-day sparkline, and top links. Archived bundles are hidden by default.

final bundles = await client.listBundles();
final withArchived = await client.listBundles(archived: true);

`getBundle`

Fetch a single bundle's metadata by ID.

final bundle = await client.getBundle(42);

`updateBundle`

Rename a bundle or change its description, icon, or accent. Pass clearDescription: true or clearIcon: true to explicitly null a field on the server.

final updated = await client.updateBundle(
  42,
  const UpdateBundleOptions(
    name: 'Spring 2026 campaign',
    accent: BundleAccent.green,
  ),
);

`deleteBundle`

Permanently delete a bundle. Member links are preserved, only the grouping is discarded.

await client.deleteBundle(42);

`archiveBundle`

Archive a bundle so it drops out of the default listBundles response. Member links keep working.

await client.archiveBundle(42);

`unarchiveBundle`

Restore a previously archived bundle.

await client.unarchiveBundle(42);

`getBundleAnalytics`

Read combined analytics across every link in the bundle: per-link breakdown, countries, devices, browsers. Defaults to all-time; pass range to scope to a window.

final lifetime = await client.getBundleAnalytics(42);
final last7d = await client.getBundleAnalytics(42, range: '7d');
print(lifetime.totalClicks);
print(lifetime.perLink);

`listBundleLinks`

List every link currently in a bundle.

final links = await client.listBundleLinks(42);

`addLinkToBundle`

Attach a link to a bundle. Idempotent: re-adding an existing member is a no-op.

await client.addLinkToBundle(42, 123);

`removeLinkFromBundle`

Detach a link from a bundle. The link itself stays, only the membership is removed.

await client.removeLinkFromBundle(42, 123);

`listBundlesForLink`

List every bundle a given link belongs to.

final bundles = await client.listBundlesForLink(123);

Error Handling

Non-2xx responses throw ShrtnrException with the status code, message, and raw response body.

import 'package:shrtnr/shrtnr.dart';

try {
  await client.getLink(99999);
} on ShrtnrException catch (e) {
  print(e.statusCode); // 404
  print(e.message);    // "Link not found"
  print(e.body);
}

Custom slug collisions and format errors from addCustomSlug throw ShrtnrException (status 409 or 400). Handle them per-call.

Differences from the TypeScript SDK

The Dart SDK mirrors the TypeScript SDK method-for-method. A few surfaces differ where Dart idioms diverge:

Constructor takes named parameters (baseUrl:, auth:) instead of a single config object.
Error type is named ShrtnrException (Dart reserves Error for programmer errors).
Timestamp fields (createdAt, expiresAt, disabledAt, health timestamp) are DateTime in UTC rather than raw Unix seconds.
isCustom and isPrimary are bool rather than 0 | 1.
UpdateLinkOptions uses clearLabel / clearExpiresAt flags to distinguish "leave unchanged" from "clear on server", since Dart's null-default pattern collapses them otherwise.

License

Apache-2.0. See the root LICENSE file.