@aturi.to/waypoints 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,262 @@
+type WaypointType = 'post' | 'profile' | 'list' | 'record' | 'unknown';
+/**
+ * Keys identifying which "data family" a waypoint belongs to for auto-redirect
+ * purposes. Two waypoints can only be the endpoints of an auto-redirect when
+ * they share at least one family key (i.e. they render the same underlying
+ * atproto collections). Display groupings live in `WAYPOINT_CATEGORIES_DATA`
+ * and are independent of this.
+ */
+type RedirectCompatFamily = 'bluesky-social' | 'standard-site' | 'tangled' | 'margin' | 'grain' | 'pinksky' | 'semble' | 'streamplace' | 'popfeed' | 'sifa' | 'blento';
+type WaypointData = {
+    id: string;
+    name: string;
+    description: string | ((collection?: string, type?: WaypointType) => string);
+    getUrl: (handle: string, collection?: string, rkey?: string, did?: string) => string | null;
+    supportedTypes: WaypointType[];
+    category: string;
+    /**
+     * Data families this waypoint participates in. Auto-redirect rules are only
+     * emitted between waypoints that share at least one family. An empty array
+     * means the waypoint can never be an auto-redirect source *or* destination
+     * (dev tools / generic record viewers land here by design).
+     */
+    redirectCompat: RedirectCompatFamily[];
+    /**
+     * NSID prefixes that signal this waypoint is meaningfully usable for the
+     * target repo. When set, the extension can call describeRepo on the target
+     * DID and check whether any of the user's collections start with one of
+     * these prefixes — if none do, the waypoint is flagged as "no records
+     * found" in the popup and demoted in smart recommendations.
+     *
+     * Use trailing-dot prefixes for whole namespaces (e.g. `'sh.tangled.'`)
+     * or full NSIDs for single-collection apps. Atmosphere apps typically
+     * declare a reversed-domain prefix (`semble.so` → `so.semble.`) so the
+     * popup can flag accounts that haven't published any of that app's
+     * records. Omit the field entirely for generic explorers (PDSls,
+     * atp.tools, Aturi) — those stay in the "unknown" / no-opinion state.
+     */
+    expectedCollections?: string[];
+};
+type CompatFamilyMeta = {
+    id: RedirectCompatFamily;
+    name: string;
+    description: string;
+};
+/**
+ * Registry of compat families. `description` is shown in the options UI so the
+ * user understands what each "Favorite for X" controls.
+ */
+declare const COMPAT_FAMILIES: Record<RedirectCompatFamily, CompatFamilyMeta>;
+declare const COMPAT_FAMILY_ORDER: RedirectCompatFamily[];
+type WaypointCategoryData = {
+    id: string;
+    name: string;
+    description?: string;
+    defaultWaypointId: string;
+    subcategories?: WaypointCategoryData[];
+};
+type CategorizedWaypointsData = {
+    category: WaypointCategoryData;
+    waypoints: WaypointData[];
+};
+declare const WAYPOINT_DESTINATIONS_DATA: Record<string, WaypointData>;
+declare const WAYPOINT_ORDER: string[];
+declare function getWaypointDataForType(type: WaypointType): WaypointData[];
+declare function getWaypointCountData(): number;
+declare const WAYPOINT_CATEGORIES_DATA: Record<string, WaypointCategoryData>;
+declare const CATEGORY_ORDER: string[];
+declare function getCategorizedWaypointsData(type: WaypointType): CategorizedWaypointsData[];
+declare function getRecommendedWaypointsData(type: WaypointType, collection?: string): {
+    waypoints: WaypointData[];
+    label: string;
+};
+declare function getFeaturedWaypointData(type: WaypointType, collection?: string): WaypointData | null;
+/**
+ * Result of comparing a waypoint's `expectedCollections` against the set of
+ * NSIDs found in the target repo.
+ *
+ *   - 'present'  — the user has at least one record under a matching prefix.
+ *   - 'absent'   — the waypoint declared collections but none are in the repo.
+ *   - 'unknown'  — the waypoint didn't declare any expectations, or we
+ *                  haven't scanned the repo yet (e.g. scan disabled, no DID).
+ */
+type WaypointActivity = 'present' | 'absent' | 'unknown';
+/**
+ * Classify a waypoint against the set of collection NSIDs known to exist on
+ * the target repo. Prefix-matches each entry in `expectedCollections` against
+ * `repoCollections`. Returns 'unknown' when the waypoint has no declared
+ * expectations or the caller passed `null` for `repoCollections` (i.e. scan
+ * disabled or still in flight).
+ */
+declare function waypointActivity(waypoint: Pick<WaypointData, 'expectedCollections'>, repoCollections: ReadonlySet<string> | null): WaypointActivity;
+
+type ParsedURI = {
+    type: 'post' | 'profile' | 'list' | 'record' | 'unknown';
+    uri: string;
+    handle: string;
+    did?: string;
+    collection?: string;
+    rkey?: string;
+    error?: string;
+};
+/**
+ * Parse URL path segments into structured AT URI data
+ * Examples:
+ * - /alice.bsky.social -> profile
+ * - /alice.bsky.social/app.bsky.feed.post/3k7qw... -> post
+ * - /did:plc:xxx/app.bsky.graph.list/abc -> list
+ */
+declare function parseURI(handle: string, collection?: string, rkey?: string): ParsedURI;
+/**
+ * Resolve a handle to a DID using the Bluesky API
+ */
+declare function resolveHandle(handle: string): Promise<string | null>;
+/**
+ * Get display name from handle or DID
+ */
+declare function getDisplayName(handle: string, did?: string): string;
+
+type SourceApp = 'bluesky' | 'bluepy' | 'blacksky' | 'reddwarf' | 'witchsky' | 'catsky' | 'deer' | 'anisota' | 'pinksky' | 'leaflet' | 'tangled' | 'margin' | 'pdsls' | 'atptools' | 'semble' | 'streamplace' | 'grain' | 'popfeed' | 'sifa' | 'blento' | 'offprint' | 'pckt' | 'headDetected';
+type ReverseMatch = {
+    source: SourceApp;
+    parsed: ParsedURI;
+};
+/**
+ * Reverse-match any supported Aturi waypoint site URL back into a structured
+ * ParsedURI (handle/collection/rkey). Returns `null` if the URL isn't on a
+ * supported site or isn't a shape we recognize.
+ */
+declare function matchSupportedUrl(url: URL): ReverseMatch | null;
+/**
+ * Parse an AT URI string (e.g. "at://did:plc:abc123/collection/rkey") into
+ * its components. Used by head-based detection when an AT URI is found in
+ * a <link> tag's href attribute.
+ */
+declare function parseAtUri(uri: string): ReverseMatch | null;
+/**
+ * All host names we know how to reverse-parse. Used by the popup + background
+ * worker to decide if a tab is "relevant" before doing more expensive work.
+ */
+declare const SUPPORTED_HOSTS: string[];
+
+type ResolvedWaypoint = {
+    id: string;
+    name: string;
+    category: string;
+    url: string;
+};
+type ResolvedRecommendation = {
+    ids: string[];
+    label: string;
+};
+type ResolveResult = {
+    parsed: ParsedURI;
+    source: SourceApp;
+    did: string | null;
+    didResolved: boolean;
+    waypoints: ResolvedWaypoint[];
+    recommended: ResolvedRecommendation;
+};
+/**
+ * Waypoints whose `getUrl` only produces a useful destination when a DID is
+ * available. These are filtered out unless a DID is known. Mirrors the hosted
+ * aturi.to/api/resolve route exactly.
+ */
+declare const DID_REQUIRED_WAYPOINTS: ReadonlySet<string>;
+type BuildWaypointsOptions = {
+    /** DID to pass to each waypoint's getUrl. Falls back to `parsed.did`. */
+    did?: string;
+    /** Waypoint id to omit (e.g. the source app the user is already on). */
+    excludeSourceId?: string;
+};
+/**
+ * Turn a parsed AT URI into the list of waypoints that can render it plus the
+ * recommended set, applying the DID-required filter and dropping waypoints
+ * whose getUrl returns null. This is the framework-agnostic core of the
+ * hosted resolve endpoint.
+ */
+declare function buildWaypointsForParsed(parsed: ParsedURI, options?: BuildWaypointsOptions): {
+    waypoints: ResolvedWaypoint[];
+    recommended: ResolvedRecommendation;
+};
+/**
+ * Resolve an AT URI string (e.g. "at://did:plc:abc/app.bsky.feed.post/rkey")
+ * directly into its waypoints. Returns null if the string isn't a valid AT URI.
+ */
+declare function resolveAtUri(uri: string): ResolveResult | null;
+type ResolveUrlOptions = {
+    /**
+     * When the URL pattern isn't recognized, fetch the page and look for a
+     * `<link href="at://…">` in <head>. Off by default to keep the resolver
+     * isomorphic (no network unless explicitly requested).
+     */
+    fetchHead?: boolean;
+    /** Timeout for the optional head probe. Defaults to 4000ms. */
+    fetchHeadTimeoutMs?: number;
+    /**
+     * Resolve a handle to a DID so DID-only waypoints (pdsls, atptools, margin,
+     * grain, popfeed) are included. Pass `resolveHandle` from this package, or
+     * your own implementation.
+     */
+    resolveHandle?: (handle: string) => Promise<string | null>;
+};
+/**
+ * Resolve a pasted/shared page URL back into the AT URI it represents and the
+ * waypoints that can render it. Uses local URL-pattern matching by default;
+ * optionally falls back to a `<head>` link probe and/or handle→DID resolution.
+ *
+ * The source app's own waypoint is omitted from the result (you're already
+ * there), mirroring the extension popup and hosted endpoint.
+ */
+declare function resolveUrl(url: string | URL, options?: ResolveUrlOptions): Promise<ResolveResult | null>;
+type ResolveApiInput = {
+    url?: string;
+    atUri?: string;
+    /** Set false to skip the server-side <head> probe. */
+    headDetect?: boolean;
+};
+type ResolveApiParsed = {
+    type: WaypointType;
+    uri: string;
+    handle: string;
+    did: string | null;
+    collection: string | null;
+    rkey: string | null;
+};
+type ResolveApiSuccess = {
+    ok: true;
+    inputKind: 'atUri' | 'url';
+    detectedVia: 'atUri' | 'urlPattern' | 'headLink' | null;
+    source: SourceApp;
+    isKnownHost: boolean;
+    parsed: ResolveApiParsed;
+    didResolved: boolean;
+    recommended: ResolvedRecommendation;
+    waypoints: ResolvedWaypoint[];
+};
+type ResolveApiFailure = {
+    ok: false;
+    input?: string | null;
+    inputKind?: 'atUri' | 'url';
+    isKnownHost?: boolean;
+    reason?: string;
+    message?: string;
+    error?: string;
+};
+type ResolveApiResponse = ResolveApiSuccess | ResolveApiFailure;
+type ResolveViaApiOptions = {
+    /** Defaults to the hosted endpoint, https://aturi.to/api/resolve. */
+    endpoint?: string;
+    /** Custom fetch implementation (e.g. a polyfill or instrumented client). */
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+};
+/**
+ * Typed client for the hosted resolve endpoint. Use this when you want the
+ * server to do the work — notably the <head> link probe, which needs to fetch
+ * the target page (something you may not want to do from the browser for CORS
+ * reasons). Returns the same response shape the route emits.
+ */
+declare function resolveViaApi(input: ResolveApiInput, options?: ResolveViaApiOptions): Promise<ResolveApiResponse>;
+
+export { type BuildWaypointsOptions, CATEGORY_ORDER, COMPAT_FAMILIES, COMPAT_FAMILY_ORDER, type CategorizedWaypointsData, type CompatFamilyMeta, DID_REQUIRED_WAYPOINTS, type ParsedURI, type RedirectCompatFamily, type ResolveApiFailure, type ResolveApiInput, type ResolveApiParsed, type ResolveApiResponse, type ResolveApiSuccess, type ResolveResult, type ResolveUrlOptions, type ResolveViaApiOptions, type ResolvedRecommendation, type ResolvedWaypoint, type ReverseMatch, SUPPORTED_HOSTS, type SourceApp, WAYPOINT_CATEGORIES_DATA, WAYPOINT_DESTINATIONS_DATA, WAYPOINT_ORDER, type WaypointActivity, type WaypointCategoryData, type WaypointData, type WaypointType, buildWaypointsForParsed, getCategorizedWaypointsData, getDisplayName, getFeaturedWaypointData, getRecommendedWaypointsData, getWaypointCountData, getWaypointDataForType, matchSupportedUrl, parseAtUri, parseURI, resolveAtUri, resolveHandle, resolveUrl, resolveViaApi, waypointActivity };