A Seneca.js plugin

@seneca/provider

| | This open source module is sponsored and supported by Voxgig. | |---|---|

Shared utilities for Seneca provider plugins — the plugins that wrap third-party APIs such as GitHub, Trello or Stripe.

This module does two things:

• Holds provider keys and serves them over sys:provider messages, so credentials live in one place instead of in every integration.
• Builds provider plugins, exposing remote API resources as Seneca entities under a provider/<name>/<entity> canon, with URL building, JSON handling, error wrapping, retry and token refresh provided for you.

Requires Node.js 24 or later.

Install

$ npm install @seneca/provider

seneca, seneca-entity and seneca-promisify are peer dependencies; @seneca/env is optional and enables environment variable references in key values.

$ npm install seneca seneca-entity seneca-promisify

Quick Example

Register the plugin, declaring the keys your providers need:

Seneca({ legacy: false })
  .use('promisify')
  .use('entity')
  .use('provider', {
    provider: {
      github: {
        keys: {
          main: { value: process.env.GITHUB_TOKEN },
        }
      }
    }
  })

Then build a provider plugin on top of it. This one exposes GitHub repositories as the entity provider/repohome/readme:

function RepohomeProvider() {
  const seneca = this
  const entityBuilder = seneca.export('provider/entityBuilder')

  const { makeUrl, getJSON } = seneca.export('provider/makeUtils')({
    name: 'repohome',
    url: 'https://api.github.com/repos/senecajs/',
  })

  entityBuilder(seneca, {
    provider: { name: 'repohome' },
    entity: {
      readme: {
        cmd: {
          load: {
            action: async function (entize, msg) {
              const res = await getJSON(makeUrl(msg.q.id))
              const load = entize(res)
              load.id = msg.q.id
              return load
            }
          }
        }
      }
    }
  })
}

Remote data is now reachable through the ordinary entity API:

const repo = await seneca.entity('provider/repohome/readme')
  .load$('seneca-provider')

console.log(repo.full_name)   // senecajs/seneca-provider

Documentation

• Tutorial — build a working provider plugin from scratch, step by step. Start here.
• Guide — recipes: managing keys, retries, token refresh, query parameters, writes, error handling, testing.
• API reference — every export, message and helper function.
• Options reference — every option, with defaults.
• Concepts — the design and its trade-offs.
• Developing — building, testing and releasing this repository.

More Examples

See test/ for more usage examples.

Motivation

Every integration with a third-party API repeats the same work: building URLs, attaching credentials, parsing JSON, deciding what counts as an error, retrying flaky calls, refreshing expired tokens. Written separately for each API, that code drifts, and each integration ends up handling failure a little differently.

This plugin factors out the parts that do not vary, and models remote resources as Seneca entities so that calling code does not need to know whether data is local or remote.

See Concepts for the reasoning in full.

Support

If you're using this module and need help, you can:

• Post a github issue
• Tweet to @senecajs
• Ask on the Gitter

API

Options

• provider — map of provider name to { keys: { <name>: { value } } }. Default {}.
• entity.pin — extra pattern properties merged into every generated entity message. Default { sys: 'entity' }.

Full details in the options reference.

Action Patterns

• get:key,sys:provider
• get:keymap,sys:provider
• list:provider,sys:provider

Action Descriptions

« get:key,sys:provider »

No description provided.

« get:keymap,sys:provider »

No description provided.

« list:provider,sys:provider »

No description provided.

Message parameters and responses are documented in the API reference.

Provider Plugins

• @seneca/apimatic-provider - Apimatic API.
• @seneca/branchio-provider - Branchio API.
• @seneca/checklyhq-provider - Checkly API.
• @seneca/customerio-provider - Customerio API.
• @seneca/eventbrite-provider - Eventbrite API.
• @seneca/evervault-provider - Evervault API.
• @seneca/gcal-provider - Google Calendar API.
• @seneca/github-provider - GitHub API.
• @seneca/gitlab-provider - GitLab API.
• @seneca/hubspot-provider - HubSpot API.
• @seneca/meetup-provider - Meetup API.
• @seneca/mixpanel-provider - Mixpanel API.
• @seneca/nordigen-provider - Nordigen API.
• @seneca/notion-provider - Notion.so API.
• @seneca/orbit-provider - Orbit API.
• @seneca/salesforce-provider - SalesForce API.
• @seneca/stytch-provider - Stytch API.
• @seneca/tangocard-provider - Tangocard API.
• @seneca/trello-provider - Trello API.
• @seneca/typeform-provider - Typeform API.
• @seneca/vercel-provider - Vercel API.
• @seneca/webflow-provider - Webflow API.
• @seneca/zoom-provider - Zoom API.

Contributing

The Senecajs org encourages open participation. If you feel you can help in any way, be it with documentation, examples, extra testing, or new features please get in touch.

The SenecaJS org encourages participation. If you feel you can help in any way, be it with bug reporting, documentation, examples, extra testing, or new features, feel free to create an issue, or better yet - submit a Pull Request. For more information on contribution, please see our Contributing Guide.

To work on this repository — layout, build, test and release — see doc/develop.md.

Background

Check out the SenecaJS roadmap here!