neris-api

A typescript-based NERIS API client based on its OpenAPI definition

• draws from openapi specs for NERIS API as well as client code available from neris's github repo
• NERIS is National Emergency Response Information System
• NERIS's github repo
• we based our code on NERIS's nodeJS client
• NERIS Framework

Usage

• FIRST: npm install neris-api --save-dev
• Sample #1:

// ACCESS NERIS API
import { createNerisClient } from 'neris-api';

// SET THESE BEFORE CALLING NERIS APIs:
const useSandbox = true;
const nerisAPIUrl = useSandbox ? "https://api-test.neris.fsri.org/v1" 
    : "https://api.neris.fsri.org/v1";
const authClientId = "your-integration-generated-client-id-here";
const authClientSecret "your-integration-generated-client-secret-here";

// fire dept id whose data your app will access:
const neris_id_entity = 'FD12345678'; 

// Create access to NERIS
const client = createNerisClient({
    baseUrl: nerisAPIUrl,
    auth: {
        _type: 'client_credentials',
        client_id: authClientId,
        client_secret: authClientSecret
    }
});

// Typical use of the API
const { data, error } = await client.GET(`/incident`, { 
    params: { query: { neris_id_entity } }, });
error ? console.log('ERROR:', error) 
    : console.log(JSON.stringify(data, null, 2));

• Sample #2 (node script):

#!/usr/bin/env npx tsx

import { createNerisClient } from 'neris-api'

import { readFileSync as read } from 'node:fs';
const log = (...args: any[]) => console.log(...args);
const getCfg = (filename: string) => JSON.parse(read(filename
            .replace('~', process.env.HOME!), `utf8`));

// IMPORTANT: MUST BE SET BEFORE CALLING NERIS APIs:
const { nerisAPIUrl, authClientId, authClientSecret } 
        = getCfg(`~/.your-config-file-here`);

// get fire dept id as command line arg
const [execPath, scriptPath, neris_id_entity] = process.argv;

if (neris_id_entity) {
    const client = createNerisClient({
        baseUrl: nerisAPIUrl,
        auth: {
            _type: 'client_credentials',
            client_id: authClientId,
            client_secret: authClientSecret
        }
    });

    const { data, error } = await client.GET(`/incident`, {
        params: { query: { neris_id_entity } },
    });

    error ? log('ERROR:', error) : log(JSON.stringify(data, null, 2));
}
else {
    log('required entity ID arg missing');
}

Build Process

• api-src is downloaded (on build) from its github repo
  • skipping .test files (e.g. auth.test.ts, client.test.ts)
• NERIS openAPI definitions are downloaded on each build
  • BUT NOT CURRENTLY USED because there's an error building with them (as of Dec 15 2025)
  • I corrected for that error (sort-of: I removed the offending section, a quite minimal bit) and saved this "corrected" version in the neris-openapi/defs folder

References

• Client souce files based on ULFSRI's published code:
  • ULFSRI: Underwriter Laboratories - Fire Safety Research Institute
  • NERIS: National Emergency Response Information System
  • NERIS Github site
• NERIS OpenAPI definitions
  • Production - json
  • Production - yaml
  • Test - json
  • Test - yaml
  • both Production & Test are same EXCEPT for servers property
    • but servers property is NOT used in generating typescript-definitions
    • ...so PRODUCTION & TEST definitions are functionally the same for our purposes
    • servers property currently NOT used anywhere as per this link

Important links for OpenAPI

• openapi
• openapi for typescript
• openapi-fetch createClient & options

TODO: add more details on process and usage

• must run BUILD step before can TEST api
• expects a CONFIG object (e.g. from a json file) file to contain NERIS Integration Authentication Settings BEFORE calling createNerisClient
  • for testing, we saved ours in ~/.rrvfc file as follows:

  {
      "fdId": "FD12345678", // our own fd for safekeeping
      "nerisAPIUrl": "https://api-test.neris.fsri.org/v1",
      "authClientId": "your-authentication-client-ID-here!",
      "authClientSecret": "your-authentication-client-secret-here!"
  }

To Create An Integration (NERIS-speak for an app that can access NERIS DB)

• GOTO: https://test.neris.fsri.org/admin/integrations?entity=FD12345678 (with your actual fire dept ID)

  • NOTE: link above seems to be NOT BE EXPLICITLY on dashboard (so must be MANUALLY pointed to: i.e. .../integrations?...)
  • NOTE: link above includes test. prefix but there is ALSO one for when you're ready for production (minus the test. prefix obvioulsy)

• THEN: click Create Integration

• THEN: NAME IT (e.g. "RRVFC NERIS Helper")

• THEN: COPY Client ID/Secret and SAVE IT SOMEWHERE (but NOT on a git/npm-repo!)

  • this is the ONLY TIME YOUR SECRET WILL BE VISIBLE

• fdId is your CLIENT's Fire Dept (entity) ID that allows YOUR integration to access their data:

  • client does so by ENROLLING your integration (e.g. RRVFC Neris Helper) in their dashboard
  • their dashboard link: https://neris.fsri.org/admin/enrollments?entity=FD12345678
    • where entity (above) is their fdId
  • A dept MUST enroll an integration before that the integration is allowed to access its (dept) data
    • they do so using YOUR integration's generated authClientId (from above)
      • DO NOT GIVE THEM YOUR CLIENT SECRET: that's just for YOUR code to use when making API calls about their data

NERIS Admin Links

• DASHBOARD
• DASHBOARD-TEST (while in dev-mode)