@aturi.to/waypoints 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dame.art
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @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`](../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](https://github.com/atpota-to/aturi/issues).
+
+## Install
+
+```sh
+npm install @aturi.to/waypoints
+```
+
+## Quick start
+
+```ts
+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`](https://github.com/atpota-to/aturi) app under `src/`.
+This package ships **copies** so it can build standalone, kept in lockstep by a
+sync script:
+
+```sh
+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 © dame.art. (The Aturi app itself is GPL-3.0; these packages are
+dual-licensed MIT by the copyright holder to remove the adoption barrier.)