# @totemorg/agent > Totem agent Latest version **1.14.0** (published 2024-07-02) · ISC license · 0 weekly downloads ## Install ```sh npm install @totemorg/agent pnpm add @totemorg/agent yarn add @totemorg/agent bun add @totemorg/agent ``` ## Health **Score 20/100 (F)** — status: abandoned. Positive: esm support; no vulnerabilities. Warnings: low downloads; no types. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 1.14.0 | | Published | 2024-07-02 | | First published | 2023-11-03 | | Weekly downloads | 0 | | License | ISC | | TypeScript types | none | | Module format | ESM + CommonJS | | Dependencies | 3 | | Unpacked size | 2.9 MB | | Known vulnerabilities | 0 | | Install scripts | no | | Maintainers | totem4, totem3, totem2, totem1 | ## Links - npm: https://www.npmjs.com/package/@totemorg/agent - npm.io page: https://npm.io/package/@totemorg/agent ## Dependencies (3) - [enums](https://npm.io/package/enums.md) ^1.0.3 - [toobusy-js](https://npm.io/package/toobusy-js.md) ^0.5.1 - [@totemorg/enums](https://npm.io/package/@totemorg/enums.md) ^3.26.0 ## Recent versions - 1.14.0 (latest) — 2024-07-02 - 1.13.0 — 2024-05-27 - 1.12.0 — 2024-05-27 - 1.11.0 — 2024-05-27 - 1.10.0 — 2024-05-25 - 1.9.0 — 2024-05-24 - 1.6.0 — 2023-11-04 - 1.5.0 — 2023-11-03 - 1.4.0 — 2023-11-03 - 1.3.0 — 2023-11-03 ## README # [AGENT](https://www.npmjs.com/package/@totemorg/enums) Provides methods to attach agents, to regulate jobs, and to fetch data. ### Install npm install @totemorg/agent npm update ### Start npm run start # Start/unit-test ### Manage npm run verminor # Roll minor version npm run vermajor # Roll major version npm run redoc # Regen documentation npm run pubminor # republish as minor version npm run pubmajor # republish as major version ## Usage Acquire and optionally configure **AGENT** as follows: import { $ } from "@totemorg/agent"); See Program Reference for usage details. ## Program Reference
Open/Close ## agent Attach agents to endpoints. Regulate job workflows. Fetch data, file, graph, and json stores. This module documented IAW [jsdoc](https://jsdoc.app/). From a *remote agent* node (a [@totemorg/agent](https://github.com/totemorg/agent)-deprived node), get/revise the [agent registration template](http://github.com/totem-man/agent/raw/master/register.cjs), or get/revise a [agent service template](http://localhost:8080/attach?agents=test) from your local [@totemorg/totem](https://github.com/totemorg/agent) to register agents with the *agent cloud*. From a *native agent* nodes (a [@totemorg/agent](https://github.com/totemorg/agent)-ready node), agents directly attach themselves to the *agent cloud* using the [agent attach template](http://github.com/totem-man/agent/raw/master/attach.cjs). **Requires**: module:[http](https://nodejs.org/docs/latest/api/), module:[https](https://nodejs.org/docs/latest/api/), module:[os](https://nodejs.org/docs/latest/api/), module:[vm](https://nodejs.org/docs/latest/api/), module:[enums](https://github.com/totemorg/enums) * [agent](#module_agent) * _static_ * [.attachAgents(opts, agents, cb)](#module_agent.attachAgents) ⇒ * [~getGraph(req, res)](#module_agent.attachAgents..getGraph) * [~getJson(req, res)](#module_agent.attachAgents..getJson) * [~getFile(req, res)](#module_agent.attachAgents..getFile) * [~getAgent(spec, agents)](#module_agent.attachAgents..getAgent) * [.regulateJob(spec, ctx, cb)](#module_agent.regulateJob) * [.fetchData(ref, data, ack)](#module_agent.fetchData) * [.LexisNexis()](#module_agent.LexisNexis) * _inner_ * [~quickLinks](#module_agent..quickLinks) * [~maxRetry](#module_agent..maxRetry) * [~certs](#module_agent..certs) ### agent.attachAgents(opts, agents, cb) ⇒ Attach `agents` to the *agent cloud*, where each `agent(req,res)` specifies its endpoint as follows: NAME: agent // handle notebook/data requests "/AREA": agent // handle file requests ".TYPE": agent // handle conversion requests "/": agent // default handler for file requests ".": agent // default handler for type conversions NAME_MACHINE: agent // handle requests via a MACHINE = py|cv|m|jx|db| ... _IGNORE: agent // ignored "#EVENT": agent // handle notebook EVENT = charge|run requests GET|PUT|POST|DELETE: agent // handle CRUD data requests The supplied `agents` hash is automatically extended with "/json", "/graph", and "/file" reader agents. When a request arrives to a *agent server* , `attachAgents` first + attempts to resolve the request to the *master agent*, then (if SQL-equipped) + attempts to resolve the request to a *remote agent*, then + attempts to resolve the request to a *notebook agent*, then + defaults to a CRUD agent based on the request type. The following options `opts` can be provided when attaching `agents`: + `cores` number of servers (workers) attached to the agents. + `port` number that servers listen on. + `CORS` flag to support Cross-Origin-Scripting. + `multipart` flag to permit multipart files in request bodies. + `never = file cacheing exemption hash { AREA: 1, PATH: 1, ... }`. + `mimes` mime hash sets the mime header for requested TYPE. + `https` options hash when creating a HTTPS server. + `map = area remapping hash {AREA: "/MappedPath", ...}`. + `access(req)` method to validate client request req. + `proxy(cert,headers)` method to adjust cert from http headers. + `init(server,agents)` method to initialize the *agent server* after listener attached. + `busy()` method to block DOS attacks. Machines* require additional modules: + py,cv,m requires [@totemorg/agent](https://github.com/totemorg/agent) + jx requires [@totemorg/man](https://github.com/totemorg/man) + db requires [@totemorg/enums](https://github.com/totemorg/enums) to support installed [python](), [opencv](), [matlab](), [mathjx](), [mysql db](https://dev.mysql.com/downloads/mysql/), and [neo4j db](https://neo4j.com/download/). Each `agent(req,res)` is provided a `res` response method accepting a: string object array error function and a `req` request containing: cookie: "...." // client cookie string agent: "..." // client browser info ipAddress: "..." // client ip address referer: "http://site" // url during a cross-site request method: "GET|PUT|POST|DELETE" // http request method now: date // date stamp when request started post: "..." // raw body text url : "/query" // requested url path reqSocket: socket // socket to retrieve client cert, post etc resSocket: socket // method to create socket to accept response cert: {...} // full client cert path: "/[area/...]name.type" // full node path area: "name" // file area being requested table: "name" // name of dataset/table being requested type: "type" // type descriptor query: {...} // raw keys from url where: {...} // sql-ized query keys from url body: {...} // body keys from request flags: {...} // flag keys from url index: {...} // sql-ized index keys from url To attach your nodejs-ready machine to the *agent cloud*: curl "http://totem/attach" | node [- ?|option=value|list|file.js] where `option` overrides the default port,cores,agents,etc. **Kind**: static method of [agent](#module_agent) **Returns**: macs Context of machines required by the agents | Param | Type | Description | | --- | --- | --- | | opts | Object | Service options | | agents | function \| Object | Hash of (req,res)-agents | | cb | function | Optional callback(agent) to process resolved agent | * [.attachAgents(opts, agents, cb)](#module_agent.attachAgents) ⇒ * [~getGraph(req, res)](#module_agent.attachAgents..getGraph) * [~getJson(req, res)](#module_agent.attachAgents..getJson) * [~getFile(req, res)](#module_agent.attachAgents..getFile) * [~getAgent(spec, agents)](#module_agent.attachAgents..getAgent) #### attachAgents~getGraph(req, res) Graph reader agent returns neo4j graph at the requested `path` = /AGENT/GRAPH?QUERY **Kind**: inner method of [attachAgents](#module_agent.attachAgents) | Param | Type | Description | | --- | --- | --- | | req | Object | totem session request | | res | function | totem session response | #### attachAgents~getJson(req, res) Json reader Agent returns json store at the requested `path` = /AGENT/TABLE/STORE$EXPRESSION. **Kind**: inner method of [attachAgents](#module_agent.attachAgents) | Param | Type | Description | | --- | --- | --- | | req | Object | totem session request | | res | function | totem session response | #### attachAgents~getFile(req, res) File reader agent returns file at the requested `path` = /AREA/FILE **Kind**: inner method of [attachAgents](#module_agent.attachAgents) | Param | Type | Description | | --- | --- | --- | | req | Object | totem session request | | res | function | totem session response | #### attachAgents~getAgent(spec, agents) Return agent from the `agents` hash with the given {type,area,method,table} spec. **Kind**: inner method of [attachAgents](#module_agent.attachAgents) | Param | Type | Description | | --- | --- | --- | | spec | Object | {type,area,method,table} to derive agent | | agents | Object | hash of agents | ### agent.regulateJob(spec, ctx, cb) Regulate callback to `cb(spec,ctx)` on events defined by an event `spec`: spec = "STEP / ONSTEPS / OFFSTEPS / START / END" || [spec, ...] where each `subspec` is of the form subspec = NUMBER | NUMBER [s|m|h|d|y] | dd-mm-yr The context `ctx` can define: ctx.queue = "task queue" to share job status ctx.batch = NUMBER of records returned in callback cb(t,recs) ctx.client = "client name" to chage this request ctx.source = "sql table" record source ctx.fields = "field, ..." source fields ctx.priority = NUMBER of seconds to monitor signoff-status if required by client **Kind**: static method of [agent](#module_agent) | Param | Type | Description | | --- | --- | --- | | spec | String | Job regulation spec "STEP / ONSTEPS / OFFSTEPS / START / END" || [spec, ...] | | ctx | Object | Job context | | cb | function | Job callback(t,ctx) | ### agent.fetchData(ref, data, ack) Fetch data from a specified `ref` url PROTOCOL://HOST/FILE ? QUERY where PROTOCOL is + http(s) = http (https) protocol + curl(s) = curl (curls uses certs/fetch.pfx to authenticate) + wget(s) = wget (wgets uses certs/fetch.pfx to authenticate) + mask = http access via rotated proxies + lexnex = Lexis-Nexis oauth access to documents + mysql = mysql database + neo4j = neo4j database + csv = csv file + stream = stream file + json = json file + jpg = image file + list = list file + null = null file + file = file/folder + SITEREF = shortcut name File paths may also contain wild-* cards. The callback name (GET || PUT || POST || DELETE || JSON) determines the request method. Optional QUERY keys: batch = NUMBER of records to fetch offset = NUMBER of records to offset fetch select ="FIELD, ..." to fetch keys = [...] header keys in csv source comma = "delim" for csv source newline = "delim" for csv source **Kind**: static method of [agent](#module_agent) | Param | Type | Description | | --- | --- | --- | | ref | String | source URL | | data | function \| object | or ack callback(results||null) | | ack | function | callback(results||null) | **Example** ```js fetchData( ref, text => { // get request }) ``` **Example** ```js fetchData( ref, function json(ctx) { // get request with json ctx }) ``` **Example** ```js fetchData( ref, [ ... ], function post(stat) { // post request with data hash list }) ``` **Example** ```js fetchData( ref, { ... }, function put(stat) { // put request with data hash }) ``` **Example** ```js fetchData( ref, null, function deete(stat) { // delete request }) ``` ### agent.LexisNexis() Start `N` Lexis-Nexis scrapes residing at the endpoint `endpt` + random counter when `R` is non-zero. **Kind**: static method of [agent](#module_agent) ### agent~quickLinks Fetch quick SITEREFs https://www.programmableweb.com/search/military ACLED https://www.programmableweb.com/api/acled-rest-api-v25 ACCT teliy40602@plexfirm.com / ACLEDsnivel1 API https://developer.acleddata.com/rehd/cms/views/acled_api/documents/API-User-Guide.pdf SITE https://developer.acleddata.com/ The Armed Conflict Location & Event Data Project (ACLED) is a real-time data and and crisis analysis and mapping project on political violence and protest across the world. ACLED's mission is to produce dis-aggregated, locally informed data and analysis globally in real time. An ACLED REST API enables users to retrieve data about actors, actor type, country, region and get data in JSON, XML, CSV or text. Filter data by date, area, pagination, etc. Animetrics FIMS https://www.programmableweb.com/api/animetrics-fims-cloud-rest-api http://animetrics.com/fims-cloud Aimed at the law enforcement, security and military intelligence industries, Animetrics' FaceR Identity Management Solution (FIMS) allows organizations to bring mobile security and video surveillance facial-biometrics applications into the field for use in real time. FIMS Cloud is used to centralize and access a user's cloud based photographic stores using facial recognition. FIMS Cloud organizes, searches and centralizes access to photographic stores using 1:many web service based verification engine. Access to the service is provided via a RESTful API. Public documentation is not available. Navlost WXT Weather Tesseract https://www.programmableweb.com/api/navlost-wxt-weather-tesseract The WXT Weather Service provides atmospheric weather information through a REST architecture, HTTP requests, and JSON formats. It integrates METAR/TAF information, sun, and moon calculations, targeting aviation and energy applications. Advanced features include: -Upper atmosphere information (e.g., research, aviation, rocketry, military) -Automated, push-type notification of arbitrary weather-related events (alert service) -Calculation of arbitrary results derived from weather forecast information via a server-side scripting language. The default response type is application/json, although other formats may be supported. At the present time, there is partial support for comma-separated value (CSV) responses. https://wxt.navlost.eu/api/v1/ https://wxt.navlost.eu/doc/api/ **Kind**: inner constant of [agent](#module_agent) ### agent~maxRetry Fetch wget/curl maxRetry **Kind**: inner constant of [agent](#module_agent) ### agent~certs Fetch certs **Kind**: inner constant of [agent](#module_agent)
## Contacting, Contributing, Following Feel free to * submit and status [TOTEM issues](http://totem.hopto.org/issues.view) * contribute to [TOTEM notebooks](http://totem.hopto.org/shares/notebooks/) * revise [TOTEM requirements](http://totem.hopto.org/reqts.view) * browse [TOTEM holdings](http://totem.hopto.org/) * or follow [TOTEM milestones](http://totem.hopto.org/milestones.view) * * * © 2012 ACMESDS --- _Source: https://npm.io/package/@totemorg/agent · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._