@graphty/graph-io 0.3.47 → 0.3.49

package/src/sources/ids.ts

@@ -0,0 +1,80 @@
+/**
+ * The public names of network sources: one constant per built-in source id, and the reserved
+ * `_source.` attribute names. Nothing else in graph-io spells them, so a rename is one edit here.
+ *
+ * Experimental: the ids and the `_source.` namespace await the owner's final word (design
+ * section 22, items 4 and 5).
+ */
+
+/**
+ * The NDEx source (www.ndexbio.org). Experimental.
+ * @category Network sources
+ */
+export const NDEX_SOURCE_ID = "ndex";
+
+/**
+ * The generic Cypher source, for any openCypher server. Experimental.
+ * @category Network sources
+ */
+export const CYPHER_SOURCE_ID = "cypher";
+
+/**
+ * The Neo4j preset of the Cypher source. Experimental.
+ * @category Network sources
+ */
+export const NEO4J_SOURCE_ID = "neo4j";
+
+/**
+ * The Amazon Neptune preset of the Cypher source. Experimental.
+ * @category Network sources
+ */
+export const NEPTUNE_SOURCE_ID = "neptune";
+
+/**
+ * The generic REST mapping source. Experimental.
+ * @category Network sources
+ */
+export const REST_SOURCE_ID = "rest";
+
+/**
+ * The OpenAlex preset of the REST mapping source. Experimental.
+ * @category Network sources
+ */
+export const OPENALEX_SOURCE_ID = "openalex";
+
+/**
+ * The SPARQL source, for any SPARQL 1.1 endpoint. Experimental.
+ * @category Network sources
+ */
+export const SPARQL_SOURCE_ID = "sparql";
+
+/**
+ * The prefix of the reserved attribute namespace sources and graphty-element write facts under.
+ * @category Network sources
+ */
+export const SOURCE_ATTR_PREFIX = "_source.";
+
+/**
+ * Node attribute: true on a stub, a node known only by its id until it is hydrated or expanded.
+ * @category Network sources
+ */
+export const SOURCE_STUB_ATTR = "_source.stub";
+
+/**
+ * Node attribute: the entity a stub node is (a REST mapping's entity name).
+ * @category Network sources
+ */
+export const SOURCE_ENTITY_ATTR = "_source.entity";
+
+/**
+ * Node attribute: the node's degree at the source, when the source returns it at no extra cost
+ * (the Cypher source's degree hint).
+ * @category Network sources
+ */
+export const SOURCE_DEGREE_ATTR = "_source.degree";
+
+/**
+ * The prefix of `ImportGraphResult.format` for a load from a source: `"source:<id>"`.
+ * @category Network sources
+ */
+export const SOURCE_FORMAT_PREFIX = "source:";

package/src/sources/ndex/client.ts

@@ -0,0 +1,102 @@
+/**
+ * What every NDEx call shares: the checks on the endpoint and the network UUID, and a fetch that
+ * classifies NDEx's failures.
+ */
+
+import { failOn } from "../fail.js";
+import { type SourceContext } from "../types.js";
+
+/** An NDEx network UUID. */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** The query parameter NDEx reads a link-share access key from. */
+export const ACCESS_KEY_QUERY = "accesskey";
+
+/** The statuses whose JSON body (NDEx's errorCode) is read; every other failure is classified by status alone. */
+const READ_STATUSES = [401, 403, 404] as const;
+
+/**
+ * Refuse an access key in the endpoint: it belongs in a credential, which is never logged.
+ * @param ctx - the context
+ */
+export function checkEndpoint(ctx: SourceContext): void {
+    if (ctx.endpoint?.searchParams.has(ACCESS_KEY_QUERY) === true) {
+        failOn(ctx.report, "E_SOURCE_PARAM", "an access key goes in a credential, never in the endpoint", {
+            name: "endpoint",
+            reason: "credentials-in-url",
+        });
+    }
+}
+
+/**
+ * Check a call's endpoint and network UUID.
+ * @param uuid - the network UUID
+ * @param ctx - the context
+ * @returns the UUID, lowercase and URL-safe
+ */
+export function checkedUuid(uuid: unknown, ctx: SourceContext): string {
+    checkEndpoint(ctx);
+    const value = String(uuid);
+    if (/accesskey/i.test(value)) {
+        failOn(ctx.report, "E_SOURCE_PARAM", "an access key goes in a credential, never in the uuid", {
+            name: "uuid",
+            reason: "credentials-in-url",
+        });
+    }
+    if (!UUID.test(value)) {
+        failOn(ctx.report, "E_SOURCE_PARAM", "the uuid is not a network UUID", { name: "uuid", reason: "format" });
+    }
+    return value.toLowerCase();
+}
+
+/**
+ * Fetch from NDEx, turning a 401, 403 or 404 into its coded error with NDEx's own errorCode.
+ * @param ctx - the context
+ * @param path - the path, relative to the endpoint
+ * @param uuid - the network the request is about, for E_SOURCE_NOT_FOUND
+ * @param init - the request init
+ * @returns the response, status 2xx
+ */
+export async function ndexFetch(
+    ctx: SourceContext,
+    path: string,
+    uuid: string | null,
+    init: RequestInit & { readonly idempotent?: boolean } = {},
+): Promise<Response> {
+    const response = await ctx.fetch(path, { ...init, allowStatus: READ_STATUSES });
+    if (response.ok) {
+        return response;
+    }
+    const url = new URL(path, ctx.endpoint ?? undefined);
+    const serverCode = await errorCode(response);
+    const { status } = response;
+    if (status === 401) {
+        failOn(ctx.report, "E_SOURCE_AUTH", `NDEx answered ${String(status)}`, {
+            origin: url.origin,
+            status,
+            scheme: response.headers.get("www-authenticate")?.split(/\s/)[0] ?? null,
+            serverCode,
+        });
+    }
+    if (status === 403) {
+        failOn(ctx.report, "E_SOURCE_FORBIDDEN", "NDEx answered 403", { status, serverCode });
+    }
+    return failOn(ctx.report, "E_SOURCE_NOT_FOUND", "NDEx has no such network", {
+        what: uuid === null ? "url" : "network",
+        value: uuid ?? `${url.origin}${url.pathname}`,
+    });
+}
+
+/**
+ * NDEx's own error code from a JSON error body, never its message or stack trace.
+ * @param response - the failed response
+ * @returns the code, or null
+ */
+async function errorCode(response: Response): Promise<string | null> {
+    try {
+        const body = (await response.json()) as { errorCode?: unknown };
+        return typeof body.errorCode === "string" ? body.errorCode.slice(0, 100) : null;
+    } catch {
+        return null;
+    }
+}

package/src/sources/ndex/descriptor.ts

@@ -0,0 +1,64 @@
+/**
+ * The NDEx source's descriptor: catalog data, available without loading the source's code.
+ */
+
+import { type SourceDescriptor, type SourceSample } from "../types.js";
+
+/**
+ * One public NDEx network offered as a sample.
+ * @param id - the sample id
+ * @param plainName - its name
+ * @param uuid - the network UUID
+ * @param nodes - its node count
+ * @param edges - its edge count
+ * @returns the sample
+ */
+function sample(id: string, plainName: string, uuid: string, nodes: number, edges: number): SourceSample {
+    return { id, plainName, params: { uuid }, counts: { nodes, edges } };
+}
+
+/**
+ * The descriptor of the `ndex` source. Experimental.
+ * @category Network sources
+ */
+export const NDEX_DESCRIPTOR: SourceDescriptor = Object.freeze({
+    plainName: "NDEx",
+    kind: "repository",
+    version: 1,
+    defaultEndpoint: "https://www.ndexbio.org/",
+    auth: ["basic", "bearer", "api-key"],
+    authRequired: "optional",
+    rateLimit: { requests: 50, perMs: 1000, concurrent: 4 },
+    params: [
+        { name: "uuid", plainName: "Network UUID", type: "string", required: true },
+        {
+            name: "format",
+            plainName: "Format",
+            type: "enum",
+            default: "cx2",
+            advanced: true,
+            values: [
+                { value: "cx2", label: "CX2" },
+                { value: "cx", label: "CX" },
+            ],
+        },
+        { name: "idAttribute", plainName: "Id attribute", type: "string", advanced: true },
+    ],
+    features: ["probe", "list", "expand", "validate"],
+    samples: [
+        sample("ndex-wp5483", "WikiPathways WP5483", "86719f5b-1439-11f0-9806-005056ae3c32", 57, 34),
+        sample("ndex-nci-pid", "NCI PID cancer signaling", "640e2cef-795d-11e8-a4bf-0ac135e8bacf", 2794, 25296),
+        sample("ndex-huri", "HuRI human interactome", "73bc2c06-5fb2-11e9-9f06-0ac135e8bacf", 8275, 52569),
+        sample("ndex-signor", "Signor", "523fff27-afe8-11e9-8bb4-0ac135e8bacf", 10339, 33381),
+        sample("ndex-dgidb", "DGIdb drugs and target genes", "7e5e64ff-f6cf-11ea-99da-0ac135e8bacf", 12100, 32814),
+        sample(
+            "ndex-wikipathways-landscape",
+            "WikiPathways landscape",
+            "2b3ed6af-5031-11eb-9e72-0ac135e8bacf",
+            32077,
+            74109,
+        ),
+        // 3.3 million edges and a 690 MB download: offered for neighborhoods, and as a maxBytes test
+        { ...sample("ndex-pcnet", "PCNet 2.2", "8b4b54fa-e87d-11ee-9621-005056ae23aa", 18558, 3323928), whole: false },
+    ],
+});

package/src/sources/ndex/expand.ts

@@ -0,0 +1,100 @@
+/**
+ * The NDEx source's expand: NDEx's neighborhood query (`POST /v2/search/network/{uuid}/query`),
+ * which answers CX1, read by the CX importer. Seeds are node ids, sent as `nodeIds`; NDEx's CX1
+ * answer keeps the ids of the CX2 download (checked on 2026-10-17), so an expansion merges into a
+ * loaded network by id. With `idAttribute`, seeds are values of that node attribute instead,
+ * matched by NDEx's node search.
+ */
+
+import { type GraphSink } from "@graphty/graph-format";
+
+import { cxImporter } from "../../formats/cx/importer.js";
+import { type ImportReport } from "../../types.js";
+import { failOn } from "../fail.js";
+import { type ExpandRequest, type SourceContext } from "../types.js";
+import { checkedUuid, ndexFetch } from "./client.js";
+import { type NdexParams } from "./params.js";
+
+/** The deepest neighborhood asked for, as for every built-in source. */
+const MAX_DEPTH = 10;
+
+/**
+ * Quote a value for NDEx's search syntax.
+ * @param value - the value
+ * @returns the quoted term
+ */
+function term(value: string): string {
+    const escaped = value.replaceAll(/["\\]/g, String.raw`\$&`);
+    return `"${escaped}"`;
+}
+
+/**
+ * The query body: the seeds as node ids, or as values of `idAttribute`.
+ * @param request - the expand request
+ * @param ctx - the context
+ * @returns the body NDEx's query takes
+ */
+function queryBody(request: ExpandRequest<NdexParams>, ctx: SourceContext): Record<string, unknown> {
+    const { ids } = request;
+    const { idAttribute } = request.params;
+    const depth = request.depth ?? 1;
+    if (!Number.isInteger(depth) || depth < 1 || depth > MAX_DEPTH) {
+        failOn(ctx.report, "E_SOURCE_PARAM", "depth is an integer from 1 to 10", { name: "depth", reason: "range" });
+    }
+    if (ids.length === 0) {
+        failOn(ctx.report, "E_SOURCE_PARAM", "an expansion needs at least one id", { name: "ids", reason: "required" });
+    }
+    const limit = request.limit === undefined ? {} : { edgeLimit: request.limit, errorWhenLimitIsOver: false };
+    if (idAttribute !== undefined) {
+        if (!/^[A-Za-z_][\w.]*$/.test(idAttribute)) {
+            failOn(ctx.report, "E_SOURCE_PARAM", "idAttribute is not an attribute name", {
+                name: "idAttribute",
+                reason: "identifier",
+            });
+        }
+        const searchString = ids.map((id) => `${idAttribute}:${term(String(id))}`).join(" ");
+        return { searchString, searchDepth: depth, ...limit };
+    }
+    const nodeIds = ids.map(Number);
+    if (nodeIds.some((n) => !Number.isSafeInteger(n))) {
+        failOn(ctx.report, "E_SOURCE_PARAM", "NDEx node ids are integers; set idAttribute to seed by name", {
+            name: "ids",
+            reason: "type",
+        });
+    }
+    return { searchString: "", searchDepth: depth, nodeIds, ...limit };
+}
+
+/**
+ * Fetch the neighborhood of some nodes of an NDEx network into a sink.
+ * @param request - the seeds, depth and limit; `limit` caps the edges NDEx returns
+ * @param sink - where to write
+ * @param ctx - the context
+ * @returns the report
+ */
+export async function expandNdex(
+    request: ExpandRequest<NdexParams>,
+    sink: GraphSink,
+    ctx: SourceContext,
+): Promise<ImportReport> {
+    const uuid = checkedUuid(request.params.uuid, ctx);
+    if (request.direction !== undefined && request.direction !== "both") {
+        failOn(ctx.report, "E_SOURCE_UNSUPPORTED", "NDEx expands in both directions only", {
+            feature: "direction",
+            needs: "both",
+        });
+    }
+    if ((request.relationshipTypes ?? []).length > 0) {
+        failOn(ctx.report, "E_SOURCE_UNSUPPORTED", "NDEx cannot filter an expansion by relationship type", {
+            feature: "relationshipTypes",
+        });
+    }
+    const response = await ndexFetch(ctx, `v2/search/network/${uuid}/query`, uuid, {
+        method: "POST",
+        idempotent: true,
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify(queryBody(request, ctx)),
+    });
+    ctx.report.include(await cxImporter.import(response.body ?? "", sink, { signal: ctx.signal }));
+    return ctx.finish();
+}

package/src/sources/ndex/index.ts

@@ -0,0 +1,235 @@
+/**
+ * `@graphty/graph-io/sources/ndex`: the NDEx source (design section 12.1). Experimental.
+ *
+ * - load: the network's summary first (counts, download size, modification time), checked against
+ *   the caps before a byte of the network is read; then the CX2 (or CX) download, streamed into
+ *   the CX2 (or CX) importer.
+ * - probe: the summary. list: NDEx's v2 network search. validate: the summary's modificationTime.
+ * - expand: NDEx's neighborhood query (`expand.ts`).
+ *
+ * Errors are classified by status; a body is read only from a 401, 403 or 404 (NDEx's own
+ * `errorCode`, passed through as `serverCode`), so a 500 with a Java stack trace never reaches a
+ * report.
+ * @module @graphty/graph-io/sources/ndex
+ */
+
+import { defineSource } from "../define.js";
+import { failOn } from "../fail.js";
+import { NDEX_SOURCE_ID } from "../ids.js";
+import {
+    type GraphSource,
+    type SourceContext,
+    type SourceFreshness,
+    type SourceListing,
+    type SourceListQuery,
+    type SourceProbe,
+    type SourceValidators,
+} from "../types.js";
+import { checkedUuid, checkEndpoint, ndexFetch } from "./client.js";
+import { NDEX_DESCRIPTOR } from "./descriptor.js";
+import { expandNdex } from "./expand.js";
+import { type NdexParams } from "./params.js";
+
+export { NDEX_DESCRIPTOR } from "./descriptor.js";
+export { type NdexParams } from "./params.js";
+export { type NdexShareLink, parseShareUrl } from "./share-url.js";
+
+/** The fields of a network summary this source reads. */
+interface NdexSummary {
+    readonly nodeCount?: number;
+    readonly edgeCount?: number;
+    readonly cxFileSize?: number;
+    readonly cx2FileSize?: number;
+    readonly modificationTime?: number;
+    readonly creationTime?: number;
+    readonly visibility?: string;
+    readonly properties?: Readonly<Record<string, { readonly v?: unknown } | undefined>>;
+}
+
+/** One network of a v2 search answer. */
+interface NdexSearchHit {
+    readonly externalId?: string;
+    readonly name?: string;
+    readonly nodeCount?: number;
+    readonly edgeCount?: number;
+    readonly modificationTime?: number;
+}
+
+/**
+ * Read a network's summary.
+ * @param uuid - the checked UUID
+ * @param ctx - the context
+ * @returns the summary and the bytes it took
+ */
+async function readSummary(uuid: string, ctx: SourceContext): Promise<{ summary: NdexSummary; bytes: number }> {
+    const response = await ndexFetch(ctx, `v3/networks/${uuid}/summary`, uuid, {
+        headers: { Accept: "application/json" },
+    });
+    const text = await response.text();
+    try {
+        return { summary: JSON.parse(text) as NdexSummary, bytes: new TextEncoder().encode(text).byteLength };
+    } catch {
+        return failOn(ctx.report, "E_SOURCE_RESPONSE", "the NDEx summary is not JSON", {
+            expected: "json",
+            contentType: response.headers.get("content-type"),
+        });
+    }
+}
+
+/**
+ * An NDEx time (epoch milliseconds) as an ISO string.
+ * @param ms - the time
+ * @returns the ISO string, or undefined
+ */
+function iso(ms: number | undefined): string | undefined {
+    return typeof ms === "number" && Number.isFinite(ms) ? new Date(ms).toISOString() : undefined;
+}
+
+/**
+ * The download size the summary gives for a format.
+ * @param summary - the summary
+ * @param format - "cx2" or "cx"
+ * @returns the size in bytes, or undefined
+ */
+function sizeOf(summary: NdexSummary, format: string): number | undefined {
+    return format === "cx" ? summary.cxFileSize : summary.cx2FileSize;
+}
+
+/**
+ * Stop the load before its first byte when the summary says a cap would cut it: a network file cut
+ * short is not a graph, so this is E_SOURCE_LIMIT under either `onLimit`.
+ * @param summary - the summary
+ * @param format - the download format
+ * @param ctx - the context
+ */
+function checkCaps(summary: NdexSummary, format: string, ctx: SourceContext): void {
+    const caps: [string, number | undefined, number | undefined][] = [
+        ["maxNodes", summary.nodeCount, ctx.limits.maxNodes],
+        ["maxEdges", summary.edgeCount, ctx.limits.maxEdges],
+        ["maxBytes", sizeOf(summary, format), ctx.limits.maxBytes],
+    ];
+    for (const [limit, value, cap] of caps) {
+        if (value !== undefined && cap !== undefined && value > cap) {
+            failOn(ctx.report, "E_SOURCE_LIMIT", `the network's ${limit} of ${String(value)} is over the cap`, {
+                limit,
+                value,
+            });
+        }
+    }
+}
+
+/**
+ * The graph facts a summary adds: when it changed, and who may use it.
+ * @param summary - the summary
+ * @returns the facts
+ */
+function metaOf(summary: NdexSummary): Record<string, string> {
+    const meta: Record<string, string> = {};
+    const modified = iso(summary.modificationTime);
+    if (modified !== undefined) {
+        meta.modified = modified;
+    }
+    if (typeof summary.visibility === "string") {
+        meta.visibility = summary.visibility;
+    }
+    for (const key of ["rights", "rightsHolder"]) {
+        const value = summary.properties?.[key]?.v;
+        if (typeof value === "string") {
+            meta[key] = value;
+        }
+    }
+    return meta;
+}
+
+/**
+ * The validators of a summary.
+ * @param summary - the summary
+ * @returns `{ modified }` when NDEx gave a modification time
+ */
+function validatorsOf(summary: NdexSummary): SourceValidators {
+    const modified = iso(summary.modificationTime);
+    return modified === undefined ? {} : { modified };
+}
+
+/**
+ * The NDEx source. Experimental.
+ * @category Network sources
+ */
+export const ndexSource: GraphSource<NdexParams> = defineSource<NdexParams>({
+    id: NDEX_SOURCE_ID,
+    descriptor: NDEX_DESCRIPTOR,
+    async file(params, ctx) {
+        const uuid = checkedUuid(params.uuid, ctx);
+        const format = params.format ?? "cx2";
+        const { summary, bytes } = await readSummary(uuid, ctx);
+        checkCaps(summary, format, ctx);
+        const size = sizeOf(summary, format);
+        // progress counts every byte read, the summary's included
+        ctx.progress(bytes, size === undefined ? undefined : bytes + size, "bytes");
+        // records the validators in report.source; the file path keeps them
+        ctx.finish({ validators: validatorsOf(summary) });
+        const path = format === "cx" ? `v2/network/${uuid}` : `v3/networks/${uuid}`;
+        const body = await ndexFetch(ctx, path, uuid);
+        return { body, format, meta: metaOf(summary) };
+    },
+    async probe(params, ctx): Promise<SourceProbe> {
+        const uuid = checkedUuid(params.uuid, ctx);
+        const { summary } = await readSummary(uuid, ctx);
+        return {
+            ok: true,
+            counts: {
+                nodes: summary.nodeCount,
+                edges: summary.edgeCount,
+                bytes: sizeOf(summary, params.format ?? "cx2"),
+            },
+        };
+    },
+    async list(query: SourceListQuery<NdexParams>, ctx): Promise<SourceListing> {
+        checkEndpoint(ctx);
+        const start = Number(query.cursor?.start ?? 0);
+        const size = query.size ?? 25;
+        const body = await ctx.fetchJson<{ networks?: unknown; numFound?: unknown }>(
+            `v2/search/network?start=${String(start)}&size=${String(size)}`,
+            {
+                method: "POST",
+                idempotent: true,
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ searchString: query.search ?? "" }),
+            },
+        );
+        const networks = Array.isArray(body.networks)
+            ? (body.networks as readonly NdexSearchHit[])
+            : failOn(ctx.report, "E_SOURCE_RESPONSE", "the NDEx search answer has no networks", {
+                  expected: "ndex-search",
+                  contentType: "application/json",
+              });
+        const { numFound } = body;
+        const items = networks.flatMap((n) =>
+            typeof n.externalId === "string"
+                ? [
+                      {
+                          params: { uuid: n.externalId },
+                          name: n.name ?? n.externalId,
+                          nodeCount: n.nodeCount,
+                          edgeCount: n.edgeCount,
+                          modified: iso(n.modificationTime),
+                      },
+                  ]
+                : [],
+        );
+        const total = typeof numFound === "number" ? numFound : undefined;
+        const more = total === undefined ? networks.length === size : start + networks.length < total;
+        return { items, next: more && networks.length > 0 ? { start: start + networks.length } : null, total };
+    },
+    async validate(params, seen, ctx): Promise<SourceFreshness> {
+        const uuid = checkedUuid(params.uuid, ctx);
+        const validators = validatorsOf((await readSummary(uuid, ctx)).summary);
+        if (seen.modified === undefined || validators.modified === undefined) {
+            return { status: "unverifiable", validators };
+        }
+        return seen.modified === validators.modified
+            ? { status: "current", via: "modified", validators }
+            : { status: "changed", via: "modified", changedAt: validators.modified, validators };
+    },
+    expand: expandNdex,
+});

package/src/sources/ndex/params.ts

@@ -0,0 +1,17 @@
+/**
+ * The parameters of the NDEx source (design section 12.1). Experimental. The NDEx work may add
+ * optional fields only.
+ */
+
+/**
+ * What to load from NDEx. Experimental.
+ * @category Network sources
+ */
+export interface NdexParams {
+    /** The network's UUID ("86719f5b-1439-11f0-9806-005056ae3c32"). */
+    readonly uuid: string;
+    /** The download format. @defaultValue "cx2" */
+    readonly format?: "cx2" | "cx" | undefined;
+    /** The node attribute that identifies a node across NDEx's two id spaces (for expand): "name", "represents". */
+    readonly idAttribute?: string | undefined;
+}

package/src/sources/ndex/share-url.ts

@@ -0,0 +1,84 @@
+/**
+ * NDEx share links: a network's page or API URL, possibly carrying a link-share access key.
+ */
+
+import { credentials } from "../credentials.js";
+import { failAlone } from "../fail.js";
+import { NDEX_SOURCE_ID } from "../ids.js";
+import { type Credential } from "../types.js";
+import { ACCESS_KEY_QUERY } from "./client.js";
+
+/** A network UUID anywhere in a URL's path or hash. */
+const UUID_IN_URL = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+
+/**
+ * What a share link says: the network, the NDEx server, and the access key as a credential.
+ * Experimental.
+ * @category Network sources
+ */
+export interface NdexShareLink {
+    /** The params to load the network with. */
+    readonly params: {
+        /** The network's NDEx id. */
+        readonly uuid: string;
+    };
+    /** The NDEx server the link points at ("https://www.ndexbio.org/"). */
+    readonly endpoint: string;
+    /** The link's access key, sent only to that server; absent when the link has none. */
+    readonly credential?: Credential | undefined;
+}
+
+/**
+ * Read an NDEx share link (`https://www.ndexbio.org/viewer/networks/<uuid>?accesskey=<key>`, the
+ * older `#/network/<uuid>` form, or an API URL). The access key leaves the URL and becomes a
+ * credential bound to the link's server, so it is never logged or stored with the params.
+ * Rejects with `E_SOURCE_PARAM` (`name: "url"`): `reason: "format"` when the text is not a URL
+ * naming a network, `"credentials-in-url"` when it carries a user name or password. Experimental.
+ * @param url - the link
+ * @returns the params, endpoint and credential to load it with
+ * @example
+ * ```ts
+ * const link = parseShareUrl(sharedUrl);
+ * const { snapshot } = await loadFromSource("ndex", link.params, {
+ *     endpoint: link.endpoint,
+ *     credential: link.credential,
+ * });
+ * ```
+ * @category Network sources
+ */
+export function parseShareUrl(url: string | URL): NdexShareLink {
+    let parsed: URL;
+    try {
+        parsed = new URL(url);
+    } catch {
+        return refuse("format");
+    }
+    if (parsed.username !== "" || parsed.password !== "") {
+        return refuse("credentials-in-url");
+    }
+    // the older viewer keeps the network and its key in the hash
+    const hash = new URL(parsed.hash.replace(/^#/, ""), "https://hash.invalid/");
+    const uuid = UUID_IN_URL.exec(`${parsed.pathname} ${hash.pathname}`)?.[0];
+    if (uuid === undefined || (parsed.protocol !== "https:" && parsed.protocol !== "http:")) {
+        return refuse("format");
+    }
+    // the bare host redirects to www without CORS headers, so a page cannot follow it
+    const host = parsed.host.toLowerCase() === "ndexbio.org" ? "www.ndexbio.org" : parsed.host;
+    const endpoint = `${parsed.protocol}//${host}/`;
+    const key = parsed.searchParams.get(ACCESS_KEY_QUERY) ?? hash.searchParams.get(ACCESS_KEY_QUERY);
+    const params = { uuid: uuid.toLowerCase() };
+    if (key === null || key === "") {
+        return { params, endpoint };
+    }
+    const credential = credentials.apiKey({ query: ACCESS_KEY_QUERY }, key, { origins: [new URL(endpoint).origin] });
+    return { params, endpoint, credential };
+}
+
+/**
+ * Reject a share link.
+ * @param reason - why
+ * @returns never
+ */
+function refuse(reason: "format" | "credentials-in-url"): never {
+    return failAlone("E_SOURCE_PARAM", "not an NDEx share link", { name: "url", reason }, `source:${NDEX_SOURCE_ID}`);
+}