@partner-ecosystem/node

Node SDK for the Partner Ecosystem. Initialise it once at application start-up, then use its middlewares (e.g. JWKS-based auth) and actions (server-to-server API calls).

Install

npm install @partner-ecosystem/node

express is a peer dependency (only needed if you use the middlewares).

Initialise

import { init } from '@partner-ecosystem/node';

export const partner = init({
  apiUrl: process.env.PARTNER_API_URL!,        // e.g. https://api.example.com
  projectId: process.env.PARTNER_PROJECT_ID!,
  projectSecret: process.env.PARTNER_PROJECT_SECRET!,
});

| Option | Required | Default | Description | | --------------- | -------- | --------------------------- | -------------------------------------------------------- | | apiUrl | yes | — | Base URL of the Partner Ecosystem API. | | projectId | yes | — | Public project identifier (also default token aud). | | projectSecret | yes | — | Secret used to authenticate action calls. | | jwksPath | no | /.well-known/jwks.json | JWKS endpoint relative to apiUrl. | | issuer | no | (unchecked) | Expected iss claim of incoming tokens. | | audience | no | projectId | Expected aud claim of incoming tokens. | | jwks | no | — | cacheMaxAge / cooldownDuration / timeoutDuration. |

Middlewares

auth() — JWKS bearer-token authentication

Verifies the Authorization: Bearer <jwt> header. The token's kid selects the public key from <apiUrl>/.well-known/jwks.json; on success the decoded payload is attached as req.user and the request continues to the next handler.

import express from 'express';
import { partner } from './partner';

const app = express();

// Global
app.use(partner.middlewares.auth());

// Per-route
app.get('/me', partner.middlewares.auth(), (req, res) => {
  res.json({ user: req.user });
});

// Optional auth (sets req.user when a valid token is present, never 401s)
app.get('/feed', partner.middlewares.auth({ optional: true }), handler);

On a missing or invalid token the middleware responds 401 with { error, message } (unless optional: true).

req.user is typed via AuthUser. Add your own claims with declaration merging:

declare module '@partner-ecosystem/node' {
  interface AuthUser {
    orgId: string;
    roles: string[];
  }
}

Actions

Server-to-server calls authenticated with the project credentials. Results are delivered through a node-style callback (error, result).

partner.actions.ping((err, result) => {
  if (err) return console.error('partner API unreachable', err);
  console.log('partner API ok:', result?.ok);
});

Development

npm install
npm run build       # compile to dist/ (+ .d.ts)
npm run typecheck   # type-check without emitting