fhirsmith 0.14.1 → 0.15.0

package/packages/openapi.yaml

@@ -0,0 +1,603 @@
+# OpenAPI description of the FHIRsmith package server (/packages).
+#
+# This file is the contract for the public, read-only package API. It is maintained by
+# hand, and tests/packages/openapi.test.js keeps it honest: every route the router
+# registers must be described here or explicitly excluded, and the query parameter
+# names, lengths and patterns must match the validation rules in packages.js.
+#
+# Administrative endpoints (crawl, update-package) and operational pages (log, stats,
+# status) are deliberately not described. info.version is filled in from package.json
+# when the spec is served.
+
+openapi: 3.1.0
+info:
+  title: FHIRsmith Package Server
+  version: "0.0.0"
+  summary: Search and download FHIR NPM packages
+  description: |
+    A registry of FHIR packages, built by crawling the package feeds listed in the
+    FHIR package registry. It implements the parts of the npm registry protocol that
+    FHIR tooling uses (package documents and tarball downloads), plus FHIR-specific
+    search by canonical URL, FHIR version and dependency.
+
+    **Content negotiation.** Most endpoints return JSON. If the request's `Accept`
+    header contains `text/html`, they return a browsable HTML page instead. The JSON
+    form is the contract; the HTML form is for people and may change at any time.
+
+    **Query parameters are strict.** An unknown parameter, a repeated parameter, a
+    value that is too long, or one that does not match the documented pattern is
+    rejected with a 400 `Error` response rather than being ignored.
+  license:
+    name: BSD-3-Clause
+    url: https://opensource.org/license/bsd-3-clause
+externalDocs:
+  description: FHIR NPM package specification
+  url: https://hl7.org/fhir/packages.html
+servers:
+  - url: /packages
+tags:
+  - name: search
+    description: Find packages
+  - name: registry
+    description: npm-compatible package documents and downloads
+  - name: reports
+    description: Registry-wide reports
+
+paths:
+  /catalog:
+    get:
+      tags: [search]
+      operationId: searchCatalog
+      summary: Search packages
+      description: |
+        Returns the packages matching all of the supplied criteria. With no criteria,
+        returns every package.
+
+        Unless `name` contains a `#version`, each package appears once, described by
+        its current version, and `count` gives its total download count. When `name`
+        contains `#`, every matching version is returned and `count` is omitted.
+
+        Results are ordered by publication date unless `sort` is given.
+      parameters:
+        - $ref: '#/components/parameters/name'
+        - $ref: '#/components/parameters/dependson'
+        - $ref: '#/components/parameters/pkgcanonical'
+        - $ref: '#/components/parameters/canonical'
+        - $ref: '#/components/parameters/fhirversion'
+        - $ref: '#/components/parameters/dependency'
+        - $ref: '#/components/parameters/sort'
+        - $ref: '#/components/parameters/objWrapper'
+        - $ref: '#/components/parameters/prerelease'
+      responses:
+        '200':
+          description: The matching packages
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: array
+                    items: { $ref: '#/components/schemas/PackageSummary' }
+                  - $ref: '#/components/schemas/WrappedSearchResult'
+            text/html:
+              schema: { type: string }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '500': { $ref: '#/components/responses/ServerError' }
+
+  /-/v1/search:
+    get:
+      tags: [search]
+      operationId: searchV1
+      summary: Search packages (npm registry search API)
+      description: |
+        The npm registry search API, so `npm search --registry` works against this
+        server. It takes npm's `text`, `size` and `from` parameters as well as the FHIR
+        search parameters of `/catalog`, and returns npm's result shape.
+
+        Differences from the npm registry:
+
+        * `text` terms match the package id or description; every term must match.
+          npm qualifiers (`keywords:`, `author:`, `scope:`, `not:`, `is:` ...) are
+          ignored.
+        * There is no relevance ranking: `quality`, `popularity` and `maintenance` are
+          accepted and ignored, every `score` is 1, and results are in publication
+          order unless `sort` is given.
+        * Without `size`, every result is returned (npm defaults to 20, but npm's own
+          clients always send `size`).
+        * `keywords` and `maintainers` are always empty, and there is no `publisher`.
+      parameters:
+        - name: text
+          in: query
+          description: Space-separated search terms.
+          schema:
+            type: string
+            maxLength: 200
+            pattern: '^[a-zA-Z0-9._:@/#| -]*$'
+          example: ips
+        - name: size
+          in: query
+          description: Maximum number of results to return (at most 250).
+          schema:
+            type: string
+            maxLength: 3
+            pattern: '^\d{1,3}$'
+          example: '20'
+        - name: from
+          in: query
+          description: Offset of the first result to return.
+          schema:
+            type: string
+            default: '0'
+            maxLength: 6
+            pattern: '^\d{1,6}$'
+        - name: quality
+          in: query
+          description: npm ranking weight. Ignored.
+          schema: { type: string, maxLength: 10, pattern: '^(\d+(\.\d+)?)?$' }
+        - name: popularity
+          in: query
+          description: npm ranking weight. Ignored.
+          schema: { type: string, maxLength: 10, pattern: '^(\d+(\.\d+)?)?$' }
+        - name: maintenance
+          in: query
+          description: npm ranking weight. Ignored.
+          schema: { type: string, maxLength: 10, pattern: '^(\d+(\.\d+)?)?$' }
+        - $ref: '#/components/parameters/name'
+        - $ref: '#/components/parameters/dependson'
+        - $ref: '#/components/parameters/pkgcanonical'
+        - $ref: '#/components/parameters/canonical'
+        - $ref: '#/components/parameters/fhirversion'
+        - $ref: '#/components/parameters/dependency'
+        - $ref: '#/components/parameters/sort'
+        - $ref: '#/components/parameters/objWrapper'
+        - $ref: '#/components/parameters/prerelease'
+      responses:
+        '200':
+          description: The matching packages
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/NpmSearchResult' }
+            text/html:
+              schema: { type: string }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '500': { $ref: '#/components/responses/ServerError' }
+
+  /updates:
+    get:
+      tags: [search]
+      operationId: listUpdates
+      summary: Package versions published since a date
+      description: |
+        Lists every package version published on or after a date, most recent first.
+        The date is either relative (`daysValue` days ago, the default) or absolute
+        (`dateValue`).
+      parameters:
+        - name: dateType
+          in: query
+          description: Whether the cut-off is relative to today or an absolute date.
+          schema:
+            type: string
+            enum: [relative, absolute]
+            default: relative
+            maxLength: 10
+            pattern: '^(relative|absolute)?$'
+        - name: daysValue
+          in: query
+          description: With `dateType=relative`, how many days back to go.
+          schema:
+            type: string
+            default: '10'
+            maxLength: 3
+            pattern: '^\d{1,3}$'
+        - name: dateValue
+          in: query
+          description: With `dateType=absolute`, the cut-off date. Defaults to today.
+          schema:
+            type: string
+            format: date
+            maxLength: 10
+            pattern: '^\d{4}-\d{2}-\d{2}$'
+      responses:
+        '200':
+          description: The package versions published since the cut-off
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: '#/components/schemas/PackageUpdate' }
+            text/html:
+              schema: { type: string }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '500': { $ref: '#/components/responses/ServerError' }
+
+  /broken:
+    get:
+      tags: [reports]
+      operationId: listBrokenDependencies
+      summary: Package versions with unresolvable dependencies
+      description: |
+        Reports every package version that declares a dependency on a package
+        version this registry does not hold. Dependencies are matched on package id
+        and major.minor version, so a dependency on `1.1.0` is satisfied by `1.1.2`.
+      parameters:
+        - name: filter
+          in: query
+          description: Only report package versions whose `id#version` contains this text.
+          schema:
+            type: string
+            maxLength: 100
+            pattern: '^[a-zA-Z0-9._-]*$'
+      responses:
+        '200':
+          description: The broken dependencies, keyed by the package version that declares them
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/BrokenDependencies' }
+            text/html:
+              schema: { type: string }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '500': { $ref: '#/components/responses/ServerError' }
+
+  /{id}:
+    get:
+      tags: [registry]
+      operationId: getPackage
+      summary: Package document (npm registry format)
+      description: |
+        The npm registry document for a package: every version this registry holds,
+        with its metadata, dependencies and tarball URL. `dist-tags.latest` is the most
+        recently published version.
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: The package id, e.g. `hl7.fhir.r4.core`.
+          schema: { type: string }
+          example: hl7.fhir.uv.ips
+      responses:
+        '200':
+          description: The package document
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/PackageDocument' }
+            text/html:
+              schema: { type: string }
+        '404':
+          description: No package with this id is known
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+        '500': { $ref: '#/components/responses/ServerError' }
+
+  /{id}/{version}:
+    get:
+      tags: [registry]
+      operationId: downloadPackage
+      summary: Download a package tarball
+      description: |
+        Returns the package tarball (`.tgz`).
+
+        If no version matches exactly, the most recently published pre-release of that
+        version (`{version}-*`) is returned instead, so `1.0.0` will find `1.0.0-ballot`
+        when there is no `1.0.0`.
+
+        If the server is configured to serve packages from bucket storage, this
+        redirects to the tarball there.
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: |
+            The package id. A scoped id (`@scope/name`) must have its `/` encoded as `%2F`.
+          schema:
+            type: string
+            maxLength: 100
+            pattern: '^(@[a-z0-9._-]+\/)?[a-zA-Z0-9._-]+$'
+          example: hl7.fhir.uv.ips
+        - name: version
+          in: path
+          required: true
+          description: The package version.
+          schema:
+            type: string
+            maxLength: 50
+            pattern: '^[a-zA-Z0-9._-]+$'
+          example: 1.1.0
+      responses:
+        '200':
+          description: The package tarball
+          headers:
+            Content-Disposition:
+              description: '`attachment; filename="{id}#{version}.tgz"`'
+              schema: { type: string }
+          content:
+            application/tar+gzip:
+              schema:
+                type: string
+                contentEncoding: binary
+        '302':
+          description: Redirect to the tarball in bucket storage
+          headers:
+            Location:
+              schema: { type: string, format: uri }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '404':
+          description: No such package version is known
+          content:
+            text/plain:
+              schema: { type: string }
+        '500': { $ref: '#/components/responses/ServerError' }
+
+components:
+  parameters:
+    name:
+      name: name
+      in: query
+      description: |
+        Packages whose id contains this text. Append `#version` to search specific
+        versions (every version containing that text is then returned, not just the
+        current one). Matched with SQL `LIKE`, so `_` matches any single character.
+      schema:
+        type: string
+        maxLength: 100
+        pattern: '^[a-zA-Z0-9._#-]*$'
+      example: hl7.fhir.uv.ips
+    dependson:
+      name: dependson
+      in: query
+      description: |
+        Packages with a dependency whose `id@version` contains this text. `#` or `|`
+        may be used in place of `@`.
+      schema:
+        type: string
+        maxLength: 100
+        pattern: '^[a-zA-Z0-9._#|@-]*$'
+    pkgcanonical:
+      name: pkgcanonical
+      in: query
+      description: |
+        The package's canonical URL. Matched exactly, or as a prefix if the value ends
+        with `%`.
+      schema:
+        type: string
+        maxLength: 200
+        pattern: '^[a-zA-Z0-9._:/-]*%?$'
+      example: http://hl7.org/fhir/uv/ips
+    canonical:
+      name: canonical
+      in: query
+      description: Packages containing a resource whose canonical URL starts with this value.
+      schema:
+        type: string
+        maxLength: 200
+        pattern: '^[a-zA-Z0-9._:/-]*$'
+      example: http://hl7.org/fhir/uv/ips/StructureDefinition/Bundle-uv-ips
+    fhirversion:
+      name: fhirversion
+      in: query
+      description: |
+        Packages for this FHIR release: R2 (1.0.x), R2B (1.4.x), R3 (3.0.x), R4 (4.0.x),
+        R4B (4.3.x), R5 (5.0.x) or R6 (6.0.x, including ballots).
+      schema:
+        type: string
+        maxLength: 10
+        pattern: '^(R2|R2B|R3|R4|R4B|R5|R6)?$'
+        enum: [R2, R2B, R3, R4, R4B, R5, R6]
+    dependency:
+      name: dependency
+      in: query
+      description: |
+        Packages that depend on this package. Either `id` (any version), or
+        `id#version`, `id|version` or `id@version`; a version is matched as a prefix.
+      schema:
+        type: string
+        maxLength: 100
+        pattern: '^[a-zA-Z0-9._#|@-]*$'
+      example: hl7.fhir.r4.core#4.0.1
+    sort:
+      name: sort
+      in: query
+      description: |
+        Sort field; prefix with `-` for descending order. Versions sort semver-style,
+        with a pre-release (`1.0.0-ballot`) before its release. Without `sort`, results
+        are in publication order.
+      schema:
+        type: string
+        maxLength: 20
+        pattern: '^-?(name|version|date|count|fhirversion|kind|canonical)$'
+      example: -date
+    objWrapper:
+      name: objWrapper
+      in: query
+      description: |
+        `true` wraps the results as `{"objects": [{"package": ...}]}`, the core of the npm
+        search result shape. Retained for older clients; new clients wanting the npm
+        shape should use `/-/v1/search`.
+      schema:
+        type: string
+        maxLength: 10
+        pattern: '^(true|false)?$'
+        enum: ['true', 'false']
+    prerelease:
+      name: prerelease
+      in: query
+      description: |
+        Sent by the HL7 Java package client. Accepted for compatibility; it has no effect,
+        since searches already include pre-release versions.
+      schema:
+        type: string
+        maxLength: 5
+        pattern: '^(true|false)?$'
+        enum: ['true', 'false']
+
+  responses:
+    BadRequest:
+      description: A parameter was unknown, repeated, too long or badly formed
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/Error' }
+    ServerError:
+      description: The server failed to process the request
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/Error' }
+
+  schemas:
+    FhirVersion:
+      type: string
+      description: |
+        The FHIR version(s) the package is for, e.g. `4.0.1`. Packages for more than
+        one version list them separated by `, `.
+      example: 4.0.1
+    PackageKind:
+      type: string
+      enum: [fhir.core, fhir.ig, fhir.template]
+
+    PackageSummary:
+      type: object
+      description: A package version, as returned by search.
+      required: [name, version, fhirVersion, kind, url]
+      properties:
+        name: { type: string, description: Package id, example: hl7.fhir.uv.ips }
+        version: { type: string, example: 1.1.0 }
+        fhirVersion: { $ref: '#/components/schemas/FhirVersion' }
+        canonical: { type: string, format: uri, description: The package's canonical URL }
+        kind: { $ref: '#/components/schemas/PackageKind' }
+        url: { type: string, format: uri, description: Where to download the tarball }
+        date: { type: string, format: date-time, description: Publication date }
+        count:
+          type: integer
+          description: Total downloads of the package (all versions). Omitted for versioned searches.
+        description: { type: string }
+
+    WrappedSearchResult:
+      type: object
+      required: [objects]
+      properties:
+        objects:
+          type: array
+          items:
+            type: object
+            required: [package]
+            properties:
+              package: { $ref: '#/components/schemas/PackageSummary' }
+
+    NpmSearchResult:
+      type: object
+      description: The npm registry search result shape.
+      required: [objects, total, time]
+      properties:
+        objects:
+          type: array
+          items:
+            type: object
+            required: [package, score, searchScore]
+            properties:
+              package:
+                allOf:
+                  - $ref: '#/components/schemas/PackageSummary'
+                  - type: object
+                    required: [keywords, maintainers]
+                    properties:
+                      keywords: { type: array, items: { type: string }, maxItems: 0 }
+                      maintainers: { type: array, items: { type: object }, maxItems: 0 }
+              score:
+                type: object
+                properties:
+                  final: { type: number }
+                  detail:
+                    type: object
+                    properties:
+                      quality: { type: number }
+                      popularity: { type: number }
+                      maintenance: { type: number }
+              searchScore: { type: number }
+        total: { type: integer, description: Number of matches before size/from are applied }
+        time: { type: string, description: When the search ran }
+
+    PackageUpdate:
+      type: object
+      description: A package version published since the requested date.
+      required: [name, version, date, fhirVersion, kind, url]
+      properties:
+        name: { type: string }
+        version: { type: string }
+        date: { type: string, format: date-time }
+        fhirVersion: { $ref: '#/components/schemas/FhirVersion' }
+        canonical: { type: string, format: uri }
+        kind: { $ref: '#/components/schemas/PackageKind' }
+        url: { type: string, format: uri }
+        description: { type: string }
+
+    PackageDocument:
+      type: object
+      description: An npm registry package document.
+      required: [_id, name, dist-tags, versions]
+      properties:
+        _id: { type: string }
+        name: { type: string }
+        description: { type: string }
+        dist-tags:
+          type: object
+          required: [latest]
+          properties:
+            latest: { type: string, description: The most recently published version }
+        versions:
+          type: object
+          description: Every version this registry holds, keyed by version.
+          additionalProperties: { $ref: '#/components/schemas/PackageVersion' }
+
+    PackageVersion:
+      type: object
+      required: [name, version, date, fhirVersion, kind, count, url, dist]
+      properties:
+        name: { type: string }
+        _id: { type: string, description: '`{id}@{version}`' }
+        version: { type: string }
+        date: { type: string, format: date-time }
+        fhirVersion: { $ref: '#/components/schemas/FhirVersion' }
+        kind: { $ref: '#/components/schemas/PackageKind' }
+        count: { type: integer, description: Downloads of this version }
+        canonical: { type: string, format: uri }
+        url: { type: string, format: uri }
+        homepage: { type: string }
+        license: { type: string }
+        author:
+          type: object
+          properties:
+            name: { type: string }
+        description: { type: string }
+        dependencies:
+          type: object
+          description: Package id to version.
+          additionalProperties: { type: string }
+          example: { hl7.fhir.r4.core: 4.0.1 }
+        dist:
+          type: object
+          required: [tarball]
+          properties:
+            shasum: { type: string }
+            tarball: { type: string, format: uri }
+
+    BrokenDependencies:
+      type: object
+      description: |
+        Keys are `id#version` of the package versions with broken dependencies; each
+        value lists the unresolvable dependencies as `id@version`. `date` is when the
+        report was generated.
+      required: [date]
+      properties:
+        date: { type: string, format: date-time }
+      additionalProperties:
+        type: array
+        items: { type: string }
+      example:
+        date: '2026-10-04T00:00:00.000Z'
+        'example.fhir.ig#1.0.0': ['hl7.fhir.uv.missing@2.0.0']
+
+    Error:
+      type: object
+      required: [error]
+      properties:
+        error: { type: string }
+        message: { type: string }
+        parameter: { type: string, description: The offending parameter, for repeated parameters }

package/packages/packages-template.html

@@ -9,6 +9,7 @@
   <meta content="http://hl7.org/fhir" name="author"/>
   <meta charset="utf-8" http-equiv="X-UA-Compatible" content="IE=edge" />
 
+  <link rel="service-desc" type="application/json" href="/packages/openapi.json"/>
   <link rel="stylesheet" href="/fhir.css"/>
 
 
@@ -59,7 +60,8 @@
   <a href="/packages" style="color: gold">Packages Home</a>  &nbsp;|&nbsp;
   <a href="/packages/updates" style="color: gold">Updates</a>  &nbsp;|&nbsp;
   <a href="/packages/broken" style="color: gold">Broken</a>  &nbsp;|&nbsp;
-  <a href="/packages/log" style="color: gold">Crawler Log</a>  
+  <a href="/packages/log" style="color: gold">Crawler Log</a>  &nbsp;|&nbsp;
+  <a href="/packages/openapi" style="color: gold">API</a>
 		</div>  <!-- /container -->
 		</div>  <!-- /container -->
 </div>
@@ -92,7 +94,7 @@
 				<p>
                     <a href="http://www.hl7.org/fhir" style="color: gold" title="Fast Healthcare Interoperability Resources - Home Page"><img border="0" src="/icon-fhir-16.png" style="vertical-align: text-bottom"/> <b>FHIR</b></a> &copy; HL7.org 2011+.  &nbsp;|&nbsp;
                     <a href="https://github.com/HealthIntersections/FHIRsmith/blob/main/README.md" style="color: gold"><img border="0" src="/FHIRsmith16.png" style="vertical-align: text-bottom"/> FHIRsmith</a>  [%ver%]  &copy; HealthIntersections.com.au 2023+ &nbsp;|&nbsp;
-                    Package Registry last updated as of [%crawler-date%] &nbsp;|&nbsp; [%total-packages%] packages &nbsp;|
+                    Package Registry [%crawler-status%] &nbsp;|&nbsp; [%total-packages%] packages &nbsp;|
                     &nbsp; ([%ms%] ms)
                     [%sponsorMessage%]
         </p>