@aturi.to/waypoints

Aturi's curated catalog of Atmosphere (AT Protocol) clients — "waypoints" — plus the logic to turn an AT URI into per-client "Open in…" links, recommend the best client for a record type, and reverse-resolve a pasted URL back into an AT URI.

Zero runtime dependencies. Works in the browser, Node 18+, and edge runtimes. Ships ESM + CJS with full type definitions.

For a drop-in React picker UI, see @aturi.to/waypoints-react.

Beta — early release. This is a 0.x package that hasn't been thoroughly tested in production yet. Expect rough edges, and possible breaking changes between minor versions while the API settles. Bug reports and feedback are very welcome at github.com/atpota-to/aturi/issues.

Install

npm install @aturi.to/waypoints

Quick start

import { resolveAtUri, resolveUrl, buildWaypointsForParsed } from '@aturi.to/waypoints';

// AT URI -> waypoints
const result = resolveAtUri('at://did:plc:abc/app.bsky.feed.post/3k7');
result?.waypoints; // [{ id: 'anisota', name: 'Anisota', category, url }, ...]
result?.recommended; // { ids: ['bluesky', 'anisota', ...], label: 'Recommended for Posts' }

// Pasted page URL -> waypoints (offline pattern match)
const fromUrl = await resolveUrl('https://bsky.app/profile/alice.bsky.social/post/3k7');

What's included

• Catalog: WAYPOINT_DESTINATIONS_DATA, WAYPOINT_ORDER, WAYPOINT_CATEGORIES_DATA, COMPAT_FAMILIES, and the WaypointData / WaypointType types.
• Link builders & recommendations: getWaypointDataForType, getCategorizedWaypointsData, getRecommendedWaypointsData, getFeaturedWaypointData, waypointActivity.
• AT URI parsing: parseURI, resolveHandle, getDisplayName.
• Reverse resolution: matchSupportedUrl, parseAtUri, SUPPORTED_HOSTS.
• High-level resolvers (resolve.ts):
  • buildWaypointsForParsed(parsed, { did?, excludeSourceId? })
  • resolveAtUri(uri)
  • resolveUrl(url, { fetchHead?, resolveHandle? })
  • resolveViaApi(input, { endpoint? }) — typed client for the hosted aturi.to/api/resolve endpoint.

DID-only waypoints

A handful of destinations (pdsls, atptools, margin, grain, popfeed) only produce useful URLs when a DID is known. They're filtered out unless a DID is available — pass one in, or supply a resolveHandle to resolveUrl.

Hosted vs. local resolution

resolveUrl matches URL patterns locally (no network). The optional fetchHead flag and resolveViaApi let you fall back to fetching the page and probing for a <link href="at://…"> — useful for sites without a recognizable URL shape. resolveViaApi is the right choice from a browser, where fetching arbitrary pages is blocked by CORS.

A note on drift

The four canonical logic/icon files (waypoints.data.ts, uriParser.ts, reverseParsers.ts, and the React icon catalog) are the single source of truth inside the aturi.to app under src/. This package ships copies so it can build standalone, kept in lockstep by a sync script:

npm run sync        # copy the canonical files into the packages
npm run sync:check  # exit non-zero if any copy is stale (wire into CI/pre-publish)

If you change waypoint data or parsing logic in the app, re-run npm run sync.

License

MIT © atpotato, LLC. (The Aturi app itself is GPL-3.0; these packages are dual-licensed MIT by the copyright holder to remove the adoption barrier.)