type: change ResourceDescriptor and Link interfaces

docs/manual/context.md

@@ -435,20 +435,33 @@ The returned WebFinger document contains links to various resources associated
 with the account, such as profile pages, ActivityPub actor URIs, and more:
 
 ~~~~ typescript twoslash
-import { type Context } from "@fedify/fedify";
+import { type Context, isLink, isOStatusSubscribeLink } from "@fedify/fedify";
 const ctx = null as unknown as Context<void>;
 // ---cut-before---
 const webfingerData = await ctx.lookupWebFinger("acct:fedify@hollo.social");
 
 // Find the ActivityPub actor URI
-const activityPubActorLink = webfingerData?.links?.find(link =>
-  link.rel === "self" && link.type === "application/activity+json"
+const activityPubActorLink = webfingerData?.links?.find(
+  isLink.withCondition((link) =>
+    link.rel === "self" &&
+    link.type === "application/activity+json"
+  ),
 );
 
 if (activityPubActorLink?.href) {
   const actor = await ctx.lookupObject(activityPubActorLink.href);
   // Work with the actor...
 }
+
+// Get subscription template URI
+const activityPubSubscribeLink = webfingerData?.links?.find((link) =>
+  isOStatusSubscribeLink(link)
+);
+
+if (activityPubSubscribeLink?.template) {
+  // Work with remote follow URI...
+}
+
 ~~~~
 
 > [!NOTE]

packages/fedify/src/mod.ts

@@ -48,4 +48,9 @@ export * from "./nodeinfo/mod.ts";
 export * from "./runtime/mod.ts";
 export * from "./sig/mod.ts";
 export * from "./vocab/mod.ts";
-export { lookupWebFinger, type ResourceDescriptor } from "./webfinger/mod.ts";
+export {
+  isLink,
+  isOStatusSubscribeLink,
+  lookupWebFinger,
+  type ResourceDescriptor,
+} from "./webfinger/mod.ts";

packages/fedify/src/nodeinfo/client.ts

@@ -3,7 +3,7 @@ import {
   getUserAgent,
   type GetUserAgentOptions,
 } from "../runtime/docloader.ts";
-import type { ResourceDescriptor } from "../webfinger/jrd.ts";
+import { isLink, type ResourceDescriptor } from "../webfinger/jrd.ts";
 import { parseSemVer, type SemVer } from "./semver.ts";
 import type {
   InboundService,
@@ -113,15 +113,17 @@ export async function getNodeInfo(
         return undefined;
       }
       const wellKnownRd = await wellKnownResponse.json() as ResourceDescriptor;
-      const link = wellKnownRd?.links?.find((link) =>
-        link != null &&
-        "rel" in link &&
-        (link.rel === "http://nodeinfo.diaspora.software/ns/schema/2.0" ||
-          link.rel === "http://nodeinfo.diaspora.software/ns/schema/2.1") &&
-        "href" in link &&
-        link.href != null
+      const link = wellKnownRd?.links?.find(
+        isLink.withCondition((link) =>
+          link != null &&
+          "rel" in link &&
+          (link.rel === "http://nodeinfo.diaspora.software/ns/schema/2.0" ||
+            link.rel === "http://nodeinfo.diaspora.software/ns/schema/2.1") &&
+          "href" in link &&
+          link.href != null
+        ),
       );
-      if (link == null) {
+      if (link == null || link.href == null) {
         logger.error(
           "Failed to find a NodeInfo document link from {url}: {resourceDescriptor}",
           { url: wellKnownUrl.href, resourceDescriptor: wellKnownRd },

packages/fedify/src/vocab/lookup.ts

@@ -7,6 +7,7 @@ import {
   getDocumentLoader,
   type GetUserAgentOptions,
 } from "../runtime/docloader.ts";
+import { isOStatusSubscribeLink } from "../webfinger/jrd.ts";
 import { lookupWebFinger } from "../webfinger/lookup.ts";
 import { toAcctUrl } from "./handle.ts";
 import { getTypeId } from "./type.ts";
@@ -158,10 +159,12 @@ async function lookupObjectInternal(
     if (jrd?.links == null) return null;
     for (const l of jrd.links) {
       if (
+        isOStatusSubscribeLink(l) ||
         l.type !== "application/activity+json" &&
           !l.type?.match(
             /application\/ld\+json;\s*profile="https:\/\/www.w3.org\/ns\/activitystreams"/,
-          ) || l.rel !== "self"
+          ) ||
+        l.rel !== "self" || l.href == null
       ) continue;
       try {
         const remoteDoc = await documentLoader(l.href, {

packages/fedify/src/webfinger/jrd.ts

@@ -21,7 +21,7 @@ export interface ResourceDescriptor {
   /**
    * Links to other resources.
    */
-  links?: Link[];
+  links?: Array<Link | OStatusSubscribeLink>;
 }
 
 /**
@@ -44,7 +44,7 @@ export interface Link {
   /**
    * A URI pointing to the target resource.
    */
-  href: string;
+  href?: string;
 
   /**
    * Human-readable titles describing the link relation.  If the language is
@@ -57,3 +57,52 @@ export interface Link {
    */
   properties?: Record<string, string>;
 }
+
+/**
+ * References a link. See also
+ * [OStatus 1.0 Draft 2](https://www.w3.org/community/ostatus/wiki/images/9/93/OStatus_1.0_Draft_2.pdf)
+ */
+export interface OStatusSubscribeLink {
+  rel: "http://ostatus.org/schema/1.0/subscribe";
+  /**
+   * A URI template (RFC 6570) that can be used to construct URIs by
+   * substituting variables. Used primarily for subscription endpoints
+   * where parameters like account URIs need to be dynamically inserted.
+   */
+  template: string;
+}
+
+export function isOStatusSubscribeLink(
+  link: Link | OStatusSubscribeLink,
+): link is OStatusSubscribeLink {
+  if (
+    "template" in link &&
+    link.rel === "http://ostatus.org/schema/1.0/subscribe" &&
+    typeof link.template === "string"
+  ) return true;
+  return false;
+}
+
+isOStatusSubscribeLink.withCondition = (
+  condition: (link: OStatusSubscribeLink) => boolean,
+) =>
+(link: Link | OStatusSubscribeLink): link is OStatusSubscribeLink => {
+  return isOStatusSubscribeLink(link) && condition(link);
+};
+
+export function isLink(
+  link: Link | OStatusSubscribeLink,
+): link is Link {
+  if (
+    "rel" in link &&
+    typeof link.rel === "string"
+  ) return true;
+  return false;
+}
+
+isLink.withCondition = (
+  condition: (link: Link) => boolean,
+) =>
+(link: Link | Link): link is Link => {
+  return isLink(link) && condition(link);
+};