extole-specification

OpenAPI 3 specifications, Postman collections, and TypeScript types for Extole evaluatable expression contexts.

npm install @extole/specification

const management = require('@extole/specification/openapi/management.json');
const managementExpert = require('@extole/specification/openapi/management-expert.json');
const integrationServer = require('@extole/specification/openapi/integration-server-to-extole.json');
const integrationConsumer = require('@extole/specification/openapi/integration-consumer-to-extole.json');

import management from '@extole/specification/openapi/management.json' with { type: 'json' };
import managementExpert from '@extole/specification/openapi/management-expert.json' with { type: 'json' };
import integrationServer from '@extole/specification/openapi/integration-server-to-extole.json' with { type: 'json' };
import integrationConsumer from '@extole/specification/openapi/integration-consumer-to-extole.json' with { type: 'json' };

const managementCollection = require('@extole/specification/postman/management.json');

Many Extole configuration fields accept evaluatable values — static literals, Handlebars templates, or JavaScript functions that run at buildtime (when a campaign or component is saved) or runtime (when a step, trigger, or webhook executes). The OpenAPI bundles describe each field's allowed formats; JavaScript evaluatables receive a context object whose methods and properties are defined by these types.

This repository publishes TypeScript declaration files (.d.ts) under openapi/expression-context/ that document those contexts. They are published alongside the OpenAPI bundles above and updated when the API specs change.

Finding the right context: open the request schema for the API field you are configuring, locate the evaluatable oneOf branch you need (handlebars@buildtime, javascript@runtime, etc.), and follow its externalDocs link to the matching .d.ts file. Walk the extends chain in that file to see every method available on context.

Using the types locally: clone or browse this repo, or reference the GitHub URLs embedded in the OpenAPI specs. Point your editor or TypeScript tooling at openapi/expression-context/ for autocomplete when authoring JavaScript evaluatables. Handlebars evaluatables use variable names only ({{variableName}}) — the .d.ts files apply to JavaScript branches that call context methods.

• GitHub Pages: extole.github.io/extole-specification (Swagger UI; enable GitHub Pages in repo settings if this 404s)
• Postman: Extole API workspace — public workspace with the four API bundles, kept in sync by CI
• ReadMe: Extole API reference documentation

npm ci
npm run build    # regenerate Postman collections from OpenAPI
npm run lint     # Spectral lint

The Publish to Postman workflow (publish-to-postman.yml) keeps the Extole API workspace in sync with main. It regenerates Postman collections from OpenAPI, publishes them via the Postman API, and runs verification checks.

export POSTMAN_API_KEY=<your-postman-api-key>
npm run publish:postman
npm run verify:postman

Collection and workspace UIDs are stored in postman/.postman-publish.json so publishes are idempotent.

The workspace is already public — the overview URL resolves without a Postman login.

Visibility cannot be set through the Postman REST API on all plan tiers, so it is flipped by hand in the Postman web app. To repeat it for a new workspace:

1. Enable the team public profile: Team settings → turn on Public profile (otherwise postman.com/<team> shows "Profile cannot be found").
2. Set workspace visibility to Public: Open the workspace → Settings → Workspace type → Public → Save. (May require Community Manager approval on Team/Enterprise plans.)
3. Verify anonymously: open the workspace URL in an incognito window — the collections should load without login, with Fork / Run in Postman visible.
4. Optional polish: rename team extole-4017592 → extole for a cleaner URL (postman.com/extole/extole-api/...), add logo/description, and submit the workspace to the Postman API Network so search?q=Extole surfaces it.

postman/.postman-publish.json records "type": "team", which keeps the visibility checks in npm run verify:postman as warnings. Setting it to "public" promotes them to hard assertions — only do that once https://www.postman.com/_api/collection/<uid> returns 200 anonymously for the published collections, which it does not today.

Release Please (release-please.yml) bumps version and publishes @extole/specification to npm on merge to main.

Follow-up required before first publish:

1. Create the @extole npm organization (or confirm it exists) at npmjs.com.
2. Add an automation token as the NPM_TOKEN repository secret on extole/extole-specification.
3. Enable GitHub Pages for this repo (Settings → Pages → GitHub Actions).

Until NPM_TOKEN is configured, release-please will still open version-bump PRs but the publish job will fail at npm publish.

MIT