@x12i/api-hub-rdap 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @x12i/api-hub-rdap
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+RDAP domain lookup client for the x12i API hub
+
+ESM package for Node.js 24 or newer. Import the public name:
+
+```js
+import * as rdap from '@x12i/api-hub-rdap';
+```
+
+The whole set is also available from [`@x12i/api-hub`](https://www.npmjs.com/package/@x12i/api-hub).

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { BOOTSTRAP_URL, eventDate, fetchRdap, loadServers, parseBootstrap, serverFor, vcard, vcardText, withRole, type RdapDomain, type RdapEntity, type RdapLink, type RdapServers, } from './rdap.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { BOOTSTRAP_URL, eventDate, fetchRdap, loadServers, parseBootstrap, serverFor, vcard, vcardText, withRole, } from "./rdap.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/rdap/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,SAAS,EACT,SAAS,EACT,WAAW,EACX,cAAc,EACd,SAAS,EACT,KAAK,EACL,SAAS,EACT,QAAQ,GAKT,MAAM,WAAW,CAAC","sourcesContent":["export {\n  BOOTSTRAP_URL,\n  eventDate,\n  fetchRdap,\n  loadServers,\n  parseBootstrap,\n  serverFor,\n  vcard,\n  vcardText,\n  withRole,\n  type RdapDomain,\n  type RdapEntity,\n  type RdapLink,\n  type RdapServers,\n} from './rdap.ts';\n"]}

package/dist/rdap.d.ts

@@ -0,0 +1,57 @@
+import { type Ctx } from '@x12i/api-hub-core';
+export declare const BOOTSTRAP_URL = "https://data.iana.org/rdap/dns.json";
+interface Bootstrap {
+    services: [string[], string[]][];
+}
+/** TLD to RDAP base URL (https preferred, trailing slash). */
+export type RdapServers = Record<string, string>;
+export declare function parseBootstrap(doc: Bootstrap): RdapServers;
+/** RDAP base for the longest matching suffix of the domain, or undefined when the TLD has no RDAP service. */
+export declare function serverFor(servers: RdapServers, domain: string): string | undefined;
+/** The IANA bootstrap for domain names, cached for 24 hours and shared by every capability that uses RDAP. */
+export declare function loadServers(ctx: Ctx): Promise<RdapServers>;
+/** Fetches one RDAP object; null when the server says it does not exist. */
+export declare function fetchRdap(url: string, ctx: Ctx): Promise<RdapDomain | null>;
+type VcardProp = [string, Record<string, unknown>, string, unknown];
+export interface RdapEntity {
+    roles?: string[];
+    handle?: string;
+    publicIds?: {
+        type: string;
+        identifier: string;
+    }[];
+    vcardArray?: ['vcard', VcardProp[]];
+    entities?: RdapEntity[];
+    links?: RdapLink[];
+    remarks?: {
+        title?: string;
+    }[];
+}
+export interface RdapLink {
+    rel?: string;
+    href?: string;
+    type?: string;
+}
+export interface RdapDomain {
+    objectClassName: string;
+    handle?: string;
+    ldhName?: string;
+    status?: string[];
+    events?: {
+        eventAction: string;
+        eventDate: string;
+    }[];
+    entities?: RdapEntity[];
+    nameservers?: {
+        ldhName?: string;
+    }[];
+    secureDNS?: {
+        delegationSigned?: boolean;
+    };
+    links?: RdapLink[];
+}
+export declare function vcard(entity: RdapEntity | undefined, prop: string): VcardProp | undefined;
+export declare function vcardText(entity: RdapEntity | undefined, prop: string): string | null;
+export declare function withRole(entities: RdapEntity[] | undefined, role: string): RdapEntity | undefined;
+export declare function eventDate(doc: RdapDomain | null, ...actions: string[]): string | null;
+export {};

package/dist/rdap.js

@@ -0,0 +1,75 @@
+import { HubError } from '@x12i/api-hub-core';
+export const BOOTSTRAP_URL = 'https://data.iana.org/rdap/dns.json';
+const RDAP_ACCEPT = 'application/rdap+json, application/json;q=0.8';
+export function parseBootstrap(doc) {
+    if (!Array.isArray(doc?.services))
+        throw new HubError('upstream_unavailable', 'The IANA RDAP bootstrap could not be parsed');
+    const servers = {};
+    for (const [tlds, urls] of doc.services) {
+        const url = urls.find((u) => u.startsWith('https://')) ?? urls[0];
+        if (!url)
+            continue;
+        for (const tld of tlds)
+            servers[tld.toLowerCase()] = url.endsWith('/') ? url : `${url}/`;
+    }
+    return servers;
+}
+/** RDAP base for the longest matching suffix of the domain, or undefined when the TLD has no RDAP service. */
+export function serverFor(servers, domain) {
+    const labels = domain.split('.');
+    for (let i = 1; i < labels.length; i++) {
+        const hit = servers[labels.slice(i).join('.')];
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+/** The IANA bootstrap for domain names, cached for 24 hours and shared by every capability that uses RDAP. */
+export async function loadServers(ctx) {
+    return ctx.cache.wrap('rdap:iana-bootstrap', '24h', async () => {
+        const res = await ctx.fetch(BOOTSTRAP_URL, { maxBytes: 1024 * 1024, timeoutMs: 10_000, signal: ctx.signal });
+        if (res.status !== 200)
+            throw new HubError('upstream_unavailable', 'The IANA RDAP bootstrap is unavailable', { status: res.status });
+        return parseBootstrap(res.json());
+    });
+}
+/** Fetches one RDAP object; null when the server says it does not exist. */
+export async function fetchRdap(url, ctx) {
+    const res = await ctx.fetch(url, { headers: { accept: RDAP_ACCEPT }, maxBytes: 512 * 1024, timeoutMs: 10_000, signal: ctx.signal });
+    if (res.status === 404)
+        return null;
+    if (res.status === 429)
+        throw new HubError('upstream_unavailable', 'The RDAP server is rate limiting requests; try again later', { status: 429 });
+    if (res.status !== 200)
+        throw new HubError('upstream_unavailable', 'The RDAP server returned an error', { status: res.status });
+    let doc;
+    try {
+        doc = res.json();
+    }
+    catch {
+        throw new HubError('upstream_unavailable', 'The RDAP server returned a malformed response');
+    }
+    if (doc?.objectClassName !== 'domain')
+        throw new HubError('upstream_unavailable', 'The RDAP server returned an unexpected object');
+    return doc;
+}
+export function vcard(entity, prop) {
+    return entity?.vcardArray?.[1]?.find((p) => p[0] === prop);
+}
+export function vcardText(entity, prop) {
+    const value = vcard(entity, prop)?.[3];
+    const text = Array.isArray(value) ? value.filter(Boolean).join(' ') : typeof value === 'string' ? value : '';
+    return text.trim() || null;
+}
+export function withRole(entities, role) {
+    return entities?.find((e) => e.roles?.includes(role));
+}
+export function eventDate(doc, ...actions) {
+    for (const action of actions) {
+        const date = doc?.events?.find((e) => e.eventAction === action)?.eventDate;
+        if (date && !Number.isNaN(Date.parse(date)))
+            return new Date(date).toISOString();
+    }
+    return null;
+}
+//# sourceMappingURL=rdap.js.map

package/dist/rdap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rdap.js","sourceRoot":"","sources":["../../../../../packages/rdap/src/rdap.ts"],"names":[],"mappings":"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","sourcesContent":["import { HubError, type Ctx } from '@x12i/api-hub-core';\n\nexport const BOOTSTRAP_URL = 'https://data.iana.org/rdap/dns.json';\nconst RDAP_ACCEPT = 'application/rdap+json, application/json;q=0.8';\n\ninterface Bootstrap {\n  services: [string[], string[]][];\n}\n\n/** TLD to RDAP base URL (https preferred, trailing slash). */\nexport type RdapServers = Record<string, string>;\n\nexport function parseBootstrap(doc: Bootstrap): RdapServers {\n  if (!Array.isArray(doc?.services)) throw new HubError('upstream_unavailable', 'The IANA RDAP bootstrap could not be parsed');\n  const servers: RdapServers = {};\n  for (const [tlds, urls] of doc.services) {\n    const url = urls.find((u) => u.startsWith('https://')) ?? urls[0];\n    if (!url) continue;\n    for (const tld of tlds) servers[tld.toLowerCase()] = url.endsWith('/') ? url : `${url}/`;\n  }\n  return servers;\n}\n\n/** RDAP base for the longest matching suffix of the domain, or undefined when the TLD has no RDAP service. */\nexport function serverFor(servers: RdapServers, domain: string): string | undefined {\n  const labels = domain.split('.');\n  for (let i = 1; i < labels.length; i++) {\n    const hit = servers[labels.slice(i).join('.')];\n    if (hit) return hit;\n  }\n  return undefined;\n}\n\n/** The IANA bootstrap for domain names, cached for 24 hours and shared by every capability that uses RDAP. */\nexport async function loadServers(ctx: Ctx): Promise<RdapServers> {\n  return ctx.cache.wrap('rdap:iana-bootstrap', '24h', async () => {\n    const res = await ctx.fetch(BOOTSTRAP_URL, { maxBytes: 1024 * 1024, timeoutMs: 10_000, signal: ctx.signal });\n    if (res.status !== 200) throw new HubError('upstream_unavailable', 'The IANA RDAP bootstrap is unavailable', { status: res.status });\n    return parseBootstrap(res.json<Bootstrap>());\n  });\n}\n\n/** Fetches one RDAP object; null when the server says it does not exist. */\nexport async function fetchRdap(url: string, ctx: Ctx): Promise<RdapDomain | null> {\n  const res = await ctx.fetch(url, { headers: { accept: RDAP_ACCEPT }, maxBytes: 512 * 1024, timeoutMs: 10_000, signal: ctx.signal });\n  if (res.status === 404) return null;\n  if (res.status === 429) throw new HubError('upstream_unavailable', 'The RDAP server is rate limiting requests; try again later', { status: 429 });\n  if (res.status !== 200) throw new HubError('upstream_unavailable', 'The RDAP server returned an error', { status: res.status });\n  let doc: RdapDomain;\n  try {\n    doc = res.json<RdapDomain>();\n  } catch {\n    throw new HubError('upstream_unavailable', 'The RDAP server returned a malformed response');\n  }\n  if (doc?.objectClassName !== 'domain') throw new HubError('upstream_unavailable', 'The RDAP server returned an unexpected object');\n  return doc;\n}\n\n// Subset of RFC 9083 that the lookup reads.\ntype VcardProp = [string, Record<string, unknown>, string, unknown];\nexport interface RdapEntity {\n  roles?: string[];\n  handle?: string;\n  publicIds?: { type: string; identifier: string }[];\n  vcardArray?: ['vcard', VcardProp[]];\n  entities?: RdapEntity[];\n  links?: RdapLink[];\n  remarks?: { title?: string }[];\n}\nexport interface RdapLink {\n  rel?: string;\n  href?: string;\n  type?: string;\n}\nexport interface RdapDomain {\n  objectClassName: string;\n  handle?: string;\n  ldhName?: string;\n  status?: string[];\n  events?: { eventAction: string; eventDate: string }[];\n  entities?: RdapEntity[];\n  nameservers?: { ldhName?: string }[];\n  secureDNS?: { delegationSigned?: boolean };\n  links?: RdapLink[];\n}\n\nexport function vcard(entity: RdapEntity | undefined, prop: string): VcardProp | undefined {\n  return entity?.vcardArray?.[1]?.find((p) => p[0] === prop);\n}\n\nexport function vcardText(entity: RdapEntity | undefined, prop: string): string | null {\n  const value = vcard(entity, prop)?.[3];\n  const text = Array.isArray(value) ? value.filter(Boolean).join(' ') : typeof value === 'string' ? value : '';\n  return text.trim() || null;\n}\n\nexport function withRole(entities: RdapEntity[] | undefined, role: string): RdapEntity | undefined {\n  return entities?.find((e) => e.roles?.includes(role));\n}\n\nexport function eventDate(doc: RdapDomain | null, ...actions: string[]): string | null {\n  for (const action of actions) {\n    const date = doc?.events?.find((e) => e.eventAction === action)?.eventDate;\n    if (date && !Number.isNaN(Date.parse(date))) return new Date(date).toISOString();\n  }\n  return null;\n}\n"]}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@x12i/api-hub-rdap",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "RDAP domain lookup client for the x12i API hub",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/x12i/apis-hub.git",
+    "directory": "packages/rdap"
+  },
+  "bugs": {
+    "url": "https://github.com/x12i/apis-hub/issues"
+  },
+  "homepage": "https://github.com/x12i/apis-hub",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@x12i/api-hub-core": "0.1.0"
+  }
+}