@inquivent/research-ids 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @inquivent/research-ids
 
-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.
+DOI, arXiv and OpenAlex parsing and handoff URLs for the Inquivent products. Implements
+[handoff contract v1](../../contracts/handoff-v1/README.md) (V1 spec §6) and passes its test vectors.
+The contract files ship in `contract/`, so consumers test against the version they pin.
+
+```ts
+import { buildHandoffUrl, parseDoi, parseHandoffQuery } from "@inquivent/research-ids";
+
+parseDoi("https://doi.org/10.1038/NPHYS1170");
+// { ok: true, value: { doi: "10.1038/NPHYS1170", doi_key: "10.1038/nphys1170" } }
+
+buildHandoffUrl("https://axiomizer.inquivent.com", {
+  identifiers: { doi: "10.1038/nphys1170" },
+  intent: "explain",
+  from: "paperinsight",
+});
+// "https://axiomizer.inquivent.com/open?v=1&doi=10.1038%2Fnphys1170&intent=explain&from=paperinsight"
+
+parseHandoffQuery("v=1&arxiv=1706.03762v5&intent=explain");
+// { status: "ok", identifiers: { arxiv: {...} }, intent: "explain", from: null, section: null }
+```
+
+| Export | Purpose |
+|---|---|
+| `parseDoi`, `parseArxiv`, `parseOpenAlex`, `parseIdentifier` | Normalize an identifier (contract §1) |
+| `sameWork`, `sameDocument` | Matching rules (contract §1) |
+| `buildHandoffUrl` | The only way to build a handoff link (V1 spec §6.5). Throws `HandoffError` |
+| `parseHandoffQuery` | Read an incoming `/open` or availability query (contract §2.2) |
+| `@inquivent/research-ids/contract/*.json` | The test vectors, `/open` vectors and availability schema |

package/contract/README.md

@@ -0,0 +1,149 @@
+# Research handoff contract v1
+
+This is the normative detail behind V1 spec §6. It covers how products parse research identifiers, how
+they link to each other, and what the availability endpoint returns. Two implementations follow it:
+
+- `@inquivent/research-ids` in `packages/research-ids/` (TypeScript)
+- `inquivent-research-ids` in `python/research-ids/` (Python)
+
+Both MUST pass every case in [`test-vectors.json`](test-vectors.json). If an implementation and this
+document disagree, the vectors win. Change the vectors first, then both libraries, in the same PR.
+
+## 1. Identifiers
+
+Inputs are trimmed of surrounding whitespace first. Empty input is error `empty`. Input longer than
+300 characters after trimming is error `too_long`.
+
+### 1.1 DOI
+
+1. **Percent-decode once.** Every `%XX` sequence is decoded and the bytes are read as UTF-8. A `%` that
+   is not followed by two hex digits, or bytes that are not valid UTF-8, give error `bad_encoding`.
+   Callers that already decoded the value, such as a query-string parser, skip this step (§2.2).
+2. **Strip one prefix**, case-insensitively: `https://doi.org/`, `http://doi.org/`,
+   `https://dx.doi.org/`, `http://dx.doi.org/`, or `doi:` followed by optional spaces.
+3. **Validate** against `^10\.[0-9]{4,9}(\.[0-9]+)*/\S+$`. A failure gives `invalid_doi`.
+
+Stored fields:
+
+| Field | Value |
+|---|---|
+| `doi` | The result of the steps above, in its original case. Use it for display, citation and handoff URLs |
+| `doi_key` | `doi` with ASCII `A`–`Z` lowercased and every other character unchanged. DOI names are case-insensitive for ASCII only (DOI Handbook §2.4) |
+
+Same work: equal `doi_key`.
+
+### 1.2 arXiv
+
+1. **Strip one prefix**, case-insensitively: `arxiv:`, or `http(s)://(www.)arxiv.org/abs/`, or
+   `http(s)://(www.)arxiv.org/pdf/`. After a `/pdf/` prefix, a trailing `.pdf` is also removed.
+2. **Match one of the two styles**:
+
+   | Style | Pattern | Extra rules |
+   |---|---|---|
+   | New (April 2007 onward) | `YYMM.NNNN` or `YYMM.NNNNN`, then optional `vN` | `MM` is 01–12. Four digits only for 0704–1412, five digits only from 1501 |
+   | Old (1991 to March 2007) | `archive(.SC)/YYMMNNN`, then optional `vN` | `archive` is letters with an optional hyphen (`hep-th`, `math`). `SC` is a two-letter subject class. `YYMM` is 9108–9912 or 0001–0703 |
+
+   `N` in `vN` is an integer of at least 1 with no leading zero. Anything else gives `invalid_arxiv`.
+
+Stored fields:
+
+| Field | Value |
+|---|---|
+| `arxiv_base` | New style: `YYMM.NNNNN`. Old style: the archive in lowercase, `/`, then `YYMMNNN`. **The subject class is dropped.** arXiv does not treat it as part of the identifier, so `math.GT/0309136` and `math/0309136` are the same paper |
+| `arxiv_version` | The integer from `vN`, or `null` when no version was given |
+
+- **Same work:** equal `arxiv_base`.
+- **Same document:** equal `arxiv_base` and both versions given and equal. A missing version means
+  "whichever is latest", which can change, so it never matches as the same document.
+- **Never drop a given version (§6.2).** Format a stored value back with `arxiv_base` plus `v<version>`
+  when the version is not null.
+
+### 1.3 OpenAlex
+
+1. **Strip one prefix**, case-insensitively: `https://openalex.org/` or `http://openalex.org/`.
+2. **Validate** against `^[Ww][1-9][0-9]{0,14}$`. Only work IDs (`W…`) are accepted. Author, venue and
+   API URLs give `invalid_openalex`.
+
+Stored field: `openalex_id`, with the `W` uppercased. Same work: equal `openalex_id`.
+
+### 1.4 Error codes
+
+`empty`, `too_long`, `bad_encoding`, `invalid_doi`, `invalid_arxiv`, `invalid_openalex`.
+
+## 2. Handoff URL
+
+```
+https://<product-host>/open?v=1[&doi=…][&arxiv=…][&openalex=…]&intent=<intent>&from=<from>[&section=<slug>]
+```
+
+### 2.1 Building (`buildHandoffUrl` / `build_handoff_url`)
+
+The builder takes the base URL and raw identifier strings, and parses each one with §1. An invalid
+identifier is an error, never silently dropped. It needs at least one identifier (`missing_identifier`).
+
+| Rule | Value |
+|---|---|
+| `intent` | One of `explain`, `reproduce`, `summarize`, `view`. Anything else gives `invalid_intent` |
+| `from` | One of `paperinsight`, `axiomizer`, `dataxiom`, `inquivent`. Anything else gives `invalid_from` |
+| `section` | Optional slug matching `^[a-z0-9]+(-[a-z0-9]+)*$`, at most 64 characters. Anything else gives `invalid_section` |
+| Parameter order | `v`, `doi`, `arxiv`, `openalex`, `intent`, `from`, `section` |
+| Values sent | `doi`: the stored `doi`. `arxiv`: `arxiv_base` plus `v<version>` when known. `openalex`: `openalex_id` |
+| Encoding | Every byte outside `A–Z a–z 0–9 - . _ ~` is percent-encoded as UTF-8 with uppercase hex, and a space becomes `%20`. This equals JavaScript `encodeURIComponent` with `!'()*` also escaped, and Python `urllib.parse.quote(value, safe="")` |
+| Base URL | A trailing `/` is removed before `/open` is appended |
+
+When a work has both a DOI and an arXiv ID, send both (V1-I01).
+
+### 2.2 Receiving (`parseHandoffQuery` / `parse_handoff_query`)
+
+The query string is decoded with standard form decoding: `+` becomes a space and `%XX` is decoded.
+Identifier values are then parsed with §1 **without** the DOI percent-decoding step, so a value is
+never decoded twice. Repeated parameters use the first occurrence. An empty value counts as absent.
+
+| Condition | Result |
+|---|---|
+| `v` missing | `invalid`, error `missing_version` |
+| `v` present but not `1` | `invalid`, error `unsupported_version` |
+| No `doi`, `arxiv` or `openalex` | `invalid`, error `missing_identifier` |
+| Any identifier present but invalid | `invalid`, error `invalid_identifier` |
+| Otherwise | `ok` |
+
+When the result is `ok`, the other fields are resolved like this:
+
+| Field | Missing or unknown value | Invalid value |
+|---|---|---|
+| `intent` | `view` | n/a |
+| `from` | `null` | n/a |
+| `section` | `null` | `null`, never an error |
+
+### 2.3 Product responses (V1 spec §6.3)
+
+| Parse result | Response | `landing` event `outcome` |
+|---|---|---|
+| `ok`, and the product has content for the intent | 302 to the content | `matched` |
+| `ok`, no content | 200 fallback page | `fallback` |
+| `invalid` | 400 page listing the accepted formats | `invalid` |
+
+A well-formed request never returns 404 or 500. [`open-vectors.json`](open-vectors.json) lists the
+requests the ecosystem suite sends to each product.
+
+## 3. Availability endpoint
+
+`GET /api/handoff/v1/availability?doi=…` (or `arxiv=` or `openalex=`), validated by
+[`availability.schema.json`](availability.schema.json).
+
+| Case | Status and body |
+|---|---|
+| Content exists | 200 `{"v": 1, "available": true, "kind": "<kind>", "title": "…", "url": "https://…"}` |
+| No content | 200 `{"v": 1, "available": false}` |
+| No identifier or an invalid one | 400 `{"v": 1, "available": false, "error": "<code>"}`, with codes from §2.2 |
+| Over 60 requests per minute per IP | 429 with `Retry-After` |
+
+`kind` is `explanation` (Axiomizer), `study` (Dataxiom) or `summary` (PaperInsight).
+
+The endpoint returns these headers:
+
+- `Cache-Control: public, max-age=600`
+- `Access-Control-Allow-Origin`, echoing the request origin when it matches `https://*.inquivent.com`
+- `Vary: Origin`
+
+Callers query it server-side with an 800 ms timeout, and hide the button on any error.

package/contract/availability.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://inquivent.com/schemas/handoff-v1/availability.schema.json",
+  "title": "Handoff availability response (contract v1, README §3)",
+  "type": "object",
+  "required": ["v", "available"],
+  "properties": {
+    "v": { "const": 1 },
+    "available": { "type": "boolean" },
+    "kind": { "enum": ["explanation", "study", "summary"] },
+    "title": { "type": "string", "minLength": 1, "maxLength": 300 },
+    "url": { "type": "string", "format": "uri", "pattern": "^https://" },
+    "error": {
+      "enum": ["missing_identifier", "invalid_identifier"]
+    }
+  },
+  "additionalProperties": false,
+  "if": { "properties": { "available": { "const": true } } },
+  "then": { "required": ["kind", "title", "url"], "not": { "required": ["error"] } },
+  "else": { "not": { "anyOf": [{ "required": ["kind"] }, { "required": ["title"] }, { "required": ["url"] }] } }
+}

package/contract/open-vectors.json

@@ -0,0 +1,72 @@
+{
+  "contract": "inquivent-handoff",
+  "version": 1,
+  "description": "Requests the ecosystem suite sends to each product's /open endpoint (README \u00a72.3). 'matched' cases name content each product seeds (Axiomizer seed_demo, Dataxiom seed_heart_disease_study); update them when the seed data changes. PaperInsight stores only user-submitted papers, so it has no fixed matched case.",
+  "common": [
+    {
+      "id": "open-invalid-001",
+      "query": "doi=10.1000/182&intent=view&from=inquivent",
+      "status": 400,
+      "outcome": "invalid"
+    },
+    {
+      "id": "open-invalid-002",
+      "query": "v=1&doi=11.1/x&from=inquivent",
+      "status": 400,
+      "outcome": "invalid"
+    },
+    {
+      "id": "open-invalid-003",
+      "query": "v=1&intent=view",
+      "status": 400,
+      "outcome": "invalid"
+    },
+    {
+      "id": "open-fallback-001",
+      "query": "v=1&doi=10.5555%2Finquivent-handoff-fallback-test&intent=view&from=inquivent",
+      "status": 200,
+      "outcome": "fallback"
+    },
+    {
+      "id": "open-fallback-002",
+      "query": "v=1&arxiv=0704.0001v1&intent=dance&from=inquivent",
+      "status": 200,
+      "outcome": "fallback"
+    }
+  ],
+  "matched": {
+    "axiomizer": [
+      {
+        "id": "open-matched-axiomizer-001",
+        "query": "v=1&doi=10.1037%2Fh0055392&intent=explain&from=inquivent",
+        "status": 302,
+        "outcome": "matched",
+        "location_path": "/papers/fitts-law/"
+      },
+      {
+        "id": "open-matched-axiomizer-002",
+        "query": "v=1&doi=https%3A%2F%2Fdoi.org%2F10.1037%2FH0055392&intent=view&from=paperinsight",
+        "status": 302,
+        "outcome": "matched",
+        "location_path": "/papers/fitts-law/"
+      }
+    ],
+    "dataxiom": [
+      {
+        "id": "open-matched-dataxiom-001",
+        "query": "v=1&doi=10.1016%2F0002-9149%2889%2990524-9&intent=reproduce&from=axiomizer",
+        "status": 302,
+        "outcome": "matched",
+        "location_path": "/studies/heart-disease-risk-screening/"
+      },
+      {
+        "id": "open-matched-dataxiom-002",
+        "query": "v=1&doi=10.24432%2FC52P4X&intent=view&from=inquivent",
+        "status": 302,
+        "outcome": "matched",
+        "location_path": "/studies/heart-disease-risk-screening/"
+      }
+    ],
+    "paperinsight": []
+  }
+}