@inquivent/research-ids 0.0.0-stage → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Research identifiers and handoff URLs, per contracts/handoff-v1/README.md (V1 spec §6).
+ * The Python package inquivent-research-ids implements the same contract; both must pass
+ * contracts/handoff-v1/test-vectors.json.
+ */
+export type Scheme = "doi" | "arxiv" | "openalex";
+export interface Doi {
+    doi: string;
+    doi_key: string;
+}
+export interface Arxiv {
+    arxiv_base: string;
+    arxiv_version: number | null;
+}
+export interface OpenAlex {
+    openalex_id: string;
+}
+export type IdentifierError = "empty" | "too_long" | "bad_encoding" | "invalid_doi" | "invalid_arxiv" | "invalid_openalex";
+export type ParseResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: IdentifierError;
+};
+export interface Identifiers {
+    doi?: Doi;
+    arxiv?: Arxiv;
+    openalex?: OpenAlex;
+}
+export declare const INTENTS: readonly ["explain", "reproduce", "summarize", "view"];
+export type Intent = (typeof INTENTS)[number];
+export declare const SOURCES: readonly ["paperinsight", "axiomizer", "dataxiom", "inquivent"];
+export type Source = (typeof SOURCES)[number];
+/** README §2.1: unreserved characters stay, everything else is %XX with uppercase hex. */
+export declare function encodeComponent(value: string): string;
+export declare function parseDoi(input: string, options?: {
+    decode?: boolean;
+}): ParseResult<Doi>;
+export declare function parseArxiv(input: string): ParseResult<Arxiv>;
+export declare function formatArxiv(value: Arxiv): string;
+export declare function parseOpenAlex(input: string): ParseResult<OpenAlex>;
+export declare function parseIdentifier(scheme: "doi", input: string): ParseResult<Doi>;
+export declare function parseIdentifier(scheme: "arxiv", input: string): ParseResult<Arxiv>;
+export declare function parseIdentifier(scheme: "openalex", input: string): ParseResult<OpenAlex>;
+export declare function parseIdentifier(scheme: Scheme, input: string): ParseResult<Doi | Arxiv | OpenAlex>;
+export declare function sameWork(a: Doi, b: Doi): boolean;
+export declare function sameWork(a: Arxiv, b: Arxiv): boolean;
+export declare function sameWork(a: OpenAlex, b: OpenAlex): boolean;
+/** Same arXiv document: same work and both versions given and equal (README §1.2). */
+export declare function sameDocument(a: Arxiv, b: Arxiv): boolean;
+export type BuildError = "missing_identifier" | "invalid_identifier" | "invalid_intent" | "invalid_from" | "invalid_section";
+export declare class HandoffError extends Error {
+    readonly code: BuildError;
+    constructor(code: BuildError);
+}
+export interface BuildHandoffInput {
+    /** Raw identifier strings, parsed with README §1. */
+    identifiers: {
+        doi?: string | null;
+        arxiv?: string | null;
+        openalex?: string | null;
+    };
+    intent: Intent;
+    from: Source;
+    section?: string | null;
+}
+/** Builds a handoff URL (README §2.1). Throws HandoffError on any invalid input. */
+export declare function buildHandoffUrl(baseUrl: string, input: BuildHandoffInput): string;
+export type QueryError = "missing_version" | "unsupported_version" | "missing_identifier" | "invalid_identifier";
+export type HandoffQuery = {
+    status: "ok";
+    identifiers: Identifiers;
+    intent: Intent;
+    from: Source | null;
+    section: string | null;
+} | {
+    status: "invalid";
+    error: QueryError;
+};
+/** Parses an incoming /open (or availability) query (README §2.2). */
+export declare function parseHandoffQuery(query: string | URLSearchParams): HandoffQuery;

package/dist/index.js

@@ -0,0 +1,253 @@
+/**
+ * Research identifiers and handoff URLs, per contracts/handoff-v1/README.md (V1 spec §6).
+ * The Python package inquivent-research-ids implements the same contract; both must pass
+ * contracts/handoff-v1/test-vectors.json.
+ */
+export const INTENTS = ["explain", "reproduce", "summarize", "view"];
+export const SOURCES = ["paperinsight", "axiomizer", "dataxiom", "inquivent"];
+const MAX_LENGTH = 300;
+/** Whitespace, defined explicitly so that the Python implementation can match it exactly. */
+const WS = "\\t\\n\\v\\f\\r \\u0085\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff";
+const TRIM_RE = new RegExp(`^[${WS}]+|[${WS}]+$`, "g");
+const SECTION_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+// ------------------------------------------------------------------ helpers
+function asciiLower(value) {
+    return value.replace(/[A-Z]/g, (c) => c.toLowerCase());
+}
+/** README §1.1 step 1: decode every %XX once; malformed escapes or invalid UTF-8 are errors. */
+function percentDecodeOnce(value) {
+    if (!value.includes("%"))
+        return value;
+    if (/%(?![0-9A-Fa-f]{2})/.test(value))
+        return null;
+    const bytes = [];
+    const encoder = new TextEncoder();
+    for (let i = 0; i < value.length;) {
+        if (value[i] === "%") {
+            bytes.push(parseInt(value.slice(i + 1, i + 3), 16));
+            i += 3;
+        }
+        else {
+            const cp = value.codePointAt(i);
+            const ch = String.fromCodePoint(cp);
+            bytes.push(...encoder.encode(ch));
+            i += ch.length;
+        }
+    }
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(new Uint8Array(bytes));
+    }
+    catch {
+        return null;
+    }
+}
+function precheck(input) {
+    const value = input.replace(TRIM_RE, "");
+    if (value === "")
+        return { ok: false, error: "empty" };
+    if ([...value].length > MAX_LENGTH)
+        return { ok: false, error: "too_long" };
+    return { ok: true, value };
+}
+/** README §2.1: unreserved characters stay, everything else is %XX with uppercase hex. */
+export function encodeComponent(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());
+}
+// ------------------------------------------------------------------ DOI
+const DOI_PREFIX = new RegExp(`^(?:https?://(?:dx\\.)?doi\\.org/|doi:[${WS}]*)`, "i");
+const DOI_RE = new RegExp(`^10\\.[0-9]{4,9}(?:\\.[0-9]+)*/[^${WS}]+$`, "u");
+export function parseDoi(input, options = {}) {
+    const pre = precheck(input);
+    if (!pre.ok)
+        return pre;
+    let value = pre.value;
+    if (options.decode !== false) {
+        const decoded = percentDecodeOnce(value);
+        if (decoded === null)
+            return { ok: false, error: "bad_encoding" };
+        value = decoded;
+    }
+    value = value.replace(DOI_PREFIX, "");
+    if (!DOI_RE.test(value))
+        return { ok: false, error: "invalid_doi" };
+    return { ok: true, value: { doi: value, doi_key: asciiLower(value) } };
+}
+// ------------------------------------------------------------------ arXiv
+const ARXIV_PREFIX = /^(?:arxiv:|https?:\/\/(?:www\.)?arxiv\.org\/(abs|pdf)\/)/i;
+const ARXIV_NEW = /^(\d{2})(\d{2})\.(\d{4,5})(?:v([1-9]\d*))?$/;
+const ARXIV_OLD = /^([a-z]+(?:-[a-z]+)?)(?:\.[a-z]{2})?\/(\d{2})(\d{2})(\d{3})(?:v([1-9]\d*))?$/i;
+export function parseArxiv(input) {
+    const pre = precheck(input);
+    if (!pre.ok)
+        return pre;
+    let value = pre.value;
+    const prefix = ARXIV_PREFIX.exec(value);
+    if (prefix) {
+        value = value.slice(prefix[0].length);
+        if (prefix[1]?.toLowerCase() === "pdf")
+            value = value.replace(/\.pdf$/i, "");
+    }
+    const invalid = { ok: false, error: "invalid_arxiv" };
+    const modern = ARXIV_NEW.exec(value);
+    if (modern) {
+        const [, yy, mm, number, version] = modern;
+        const yymm = Number(yy + mm);
+        const month = Number(mm);
+        if (month < 1 || month > 12)
+            return invalid;
+        if (number.length === 4 && !(yymm >= 704 && yymm <= 1412))
+            return invalid;
+        if (number.length === 5 && yymm < 1501)
+            return invalid;
+        return {
+            ok: true,
+            value: { arxiv_base: `${yy}${mm}.${number}`, arxiv_version: version ? Number(version) : null },
+        };
+    }
+    const legacy = ARXIV_OLD.exec(value);
+    if (legacy) {
+        const [, archive, yy, mm, number, version] = legacy;
+        const month = Number(mm);
+        const year = Number(yy);
+        if (month < 1 || month > 12)
+            return invalid;
+        const yymm = year * 100 + month;
+        const inRange = (year >= 91 && yymm >= 9108) || (year <= 7 && yymm <= 703);
+        if (!inRange)
+            return invalid;
+        return {
+            ok: true,
+            value: {
+                arxiv_base: `${archive.toLowerCase()}/${yy}${mm}${number}`,
+                arxiv_version: version ? Number(version) : null,
+            },
+        };
+    }
+    return invalid;
+}
+export function formatArxiv(value) {
+    return value.arxiv_version === null ? value.arxiv_base : `${value.arxiv_base}v${value.arxiv_version}`;
+}
+// ------------------------------------------------------------------ OpenAlex
+const OPENALEX_PREFIX = /^https?:\/\/openalex\.org\//i;
+const OPENALEX_RE = /^[Ww]([1-9][0-9]{0,14})$/;
+export function parseOpenAlex(input) {
+    const pre = precheck(input);
+    if (!pre.ok)
+        return pre;
+    const match = OPENALEX_RE.exec(pre.value.replace(OPENALEX_PREFIX, ""));
+    if (!match)
+        return { ok: false, error: "invalid_openalex" };
+    return { ok: true, value: { openalex_id: `W${match[1]}` } };
+}
+export function parseIdentifier(scheme, input) {
+    if (scheme === "doi")
+        return parseDoi(input);
+    if (scheme === "arxiv")
+        return parseArxiv(input);
+    return parseOpenAlex(input);
+}
+export function sameWork(a, b) {
+    if ("doi_key" in a && "doi_key" in b)
+        return a.doi_key === b.doi_key;
+    if ("arxiv_base" in a && "arxiv_base" in b)
+        return a.arxiv_base === b.arxiv_base;
+    if ("openalex_id" in a && "openalex_id" in b)
+        return a.openalex_id === b.openalex_id;
+    return false;
+}
+/** Same arXiv document: same work and both versions given and equal (README §1.2). */
+export function sameDocument(a, b) {
+    return (a.arxiv_base === b.arxiv_base &&
+        a.arxiv_version !== null &&
+        a.arxiv_version === b.arxiv_version);
+}
+export class HandoffError extends Error {
+    code;
+    constructor(code) {
+        super(`handoff: ${code}`);
+        this.code = code;
+        this.name = "HandoffError";
+    }
+}
+/** Builds a handoff URL (README §2.1). Throws HandoffError on any invalid input. */
+export function buildHandoffUrl(baseUrl, input) {
+    const { identifiers } = input;
+    if (!identifiers.doi && !identifiers.arxiv && !identifiers.openalex) {
+        throw new HandoffError("missing_identifier");
+    }
+    if (!INTENTS.includes(input.intent))
+        throw new HandoffError("invalid_intent");
+    if (!SOURCES.includes(input.from))
+        throw new HandoffError("invalid_from");
+    const section = input.section ?? null;
+    if (section !== null && (section.length > 64 || !SECTION_RE.test(section))) {
+        throw new HandoffError("invalid_section");
+    }
+    const params = [["v", "1"]];
+    if (identifiers.doi) {
+        const doi = parseDoi(identifiers.doi);
+        if (!doi.ok)
+            throw new HandoffError("invalid_identifier");
+        params.push(["doi", doi.value.doi]);
+    }
+    if (identifiers.arxiv) {
+        const arxiv = parseArxiv(identifiers.arxiv);
+        if (!arxiv.ok)
+            throw new HandoffError("invalid_identifier");
+        params.push(["arxiv", formatArxiv(arxiv.value)]);
+    }
+    if (identifiers.openalex) {
+        const openalex = parseOpenAlex(identifiers.openalex);
+        if (!openalex.ok)
+            throw new HandoffError("invalid_identifier");
+        params.push(["openalex", openalex.value.openalex_id]);
+    }
+    params.push(["intent", input.intent], ["from", input.from]);
+    if (section !== null)
+        params.push(["section", section]);
+    const query = params.map(([k, v]) => `${k}=${encodeComponent(v)}`).join("&");
+    return `${baseUrl.replace(/\/$/, "")}/open?${query}`;
+}
+/** Parses an incoming /open (or availability) query (README §2.2). */
+export function parseHandoffQuery(query) {
+    const params = typeof query === "string" ? new URLSearchParams(query.replace(/^\?/, "")) : query;
+    const get = (key) => {
+        const value = params.get(key);
+        return value === null || value === "" ? null : value;
+    };
+    const version = get("v");
+    if (version === null)
+        return { status: "invalid", error: "missing_version" };
+    if (version !== "1")
+        return { status: "invalid", error: "unsupported_version" };
+    const raw = { doi: get("doi"), arxiv: get("arxiv"), openalex: get("openalex") };
+    if (!raw.doi && !raw.arxiv && !raw.openalex)
+        return { status: "invalid", error: "missing_identifier" };
+    const identifiers = {};
+    if (raw.doi) {
+        const doi = parseDoi(raw.doi, { decode: false });
+        if (!doi.ok)
+            return { status: "invalid", error: "invalid_identifier" };
+        identifiers.doi = doi.value;
+    }
+    if (raw.arxiv) {
+        const arxiv = parseArxiv(raw.arxiv);
+        if (!arxiv.ok)
+            return { status: "invalid", error: "invalid_identifier" };
+        identifiers.arxiv = arxiv.value;
+    }
+    if (raw.openalex) {
+        const openalex = parseOpenAlex(raw.openalex);
+        if (!openalex.ok)
+            return { status: "invalid", error: "invalid_identifier" };
+        identifiers.openalex = openalex.value;
+    }
+    const intentRaw = get("intent");
+    const intent = INTENTS.includes(intentRaw ?? "") ? intentRaw : "view";
+    const fromRaw = get("from");
+    const from = SOURCES.includes(fromRaw ?? "") ? fromRaw : null;
+    const sectionRaw = get("section");
+    const section = sectionRaw !== null && sectionRaw.length <= 64 && SECTION_RE.test(sectionRaw) ? sectionRaw : null;
+    return { status: "ok", identifiers, intent, from, section };
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@inquivent/research-ids",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "DOI, arXiv and OpenAlex parsing and handoff URLs for the Inquivent products (handoff contract v1).",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/inquivent/shared.git",
+    "directory": "packages/research-ids"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./contract/*": "./contract/*"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "contract",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node -e \"const fs=require('fs');fs.mkdirSync('contract',{recursive:true});for(const f of ['test-vectors.json','open-vectors.json','availability.schema.json','README.md'])fs.copyFileSync('../../contracts/handoff-v1/'+f,'contract/'+f)\"",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
+  }
+}