Foundations TS Definitions

Auto-generated TypeScript type definitions for the Reapit Foundations API Platform.

This package scrapes the Swagger/OpenAPI documents published by the Foundations platform APIs on a weekly schedule, converts them to TypeScript .d.ts interfaces, and publishes the result to npm as @reapit/foundations-ts-definitions.

For higher-level documentation see the Foundations documentation site.

Table of contents

• Foundations TS Definitions
  • Table of contents
  • Installation
  • Usage
  • What's in the package
  • How it works
    • Source endpoints
    • Authentication
    • Reapit APP Setup
    • Fetch sequence
  • Build pipeline
  • GitHub workflows
  • Local development
    • Testing authentication locally
    • Project layout
  • Release process
  • License

Installation

yarn add @reapit/foundations-ts-definitions
# or
npm install @reapit/foundations-ts-definitions

Usage

All generated namespaces and hand-written schemas are re-exported from the package root:

import type {
  Platform,
  Marketplace,
  Payments,
  Organisations,
} from '@reapit/foundations-ts-definitions'

type Contact = Platform.ContactModel

The package ships both CommonJS (dist/index.js) and ES module (dist/index.mjs) builds, plus a bundled dist/index.d.ts.

What's in the package

The exported surface is a union of:

| Source | Origin | Location | | --- | --- | --- | | Platform namespace | Fetched from Foundations swagger | src/types/platform-schema.ts (generated) | | Marketplace namespace | Fetched from Marketplace swagger | src/types/marketplace-schema.ts (generated) | | Payments namespace | Fetched from Payments swagger | src/types/payments-schema.ts (generated) | | Organisations namespace | Fetched from Organisations swagger | src/types/organisations-schema.ts (generated) | | Traffic event schema | Hand-written | src/traffic-schema/marketplace-traffic-event-schema.ts | | Deployment schema | Hand-written | src/deployment-schema/index.ts | | API key schema | Hand-written | src/api-key-schema/index.ts | | Marketplace CMS schema | Hand-written | src/marketplace-cms/index.ts | | Webhook schema | Hand-written | src/webhook-schema/index.ts |

Generated files under src/types/ are regenerated on every scheduled run; hand-written schemas are committed and maintained by contributors.

How it works

At a high level, a cron job runs the fetch script, which pulls Swagger JSON from each platform API, converts it to TypeScript via sw2dts, formats the output with Prettier and writes one file per namespace into src/types/. An aggregated barrel index.ts is then written that re-exports everything (generated + hand-written) so the whole package compiles as a single entry.

flowchart LR
    subgraph Remote["Foundations Platform APIs"]
        A1[Platform swagger]
        A2[Marketplace swagger]
        A3[Payments swagger]
        A4[Organisations swagger]
    end

    subgraph Fetch["src/scripts/fetch-definitions.js"]
        B1[fetch JSON]
        B2[sw2dts convert]
        B3[prettier format]
        B4[write .ts file]
    end

    subgraph Repo["src/"]
        C1[(types/*.ts generated)]
        C2[(index.ts barrel)]
        C3[hand-written schemas]
    end

    A1 & A2 & A3 & A4 --> B1 --> B2 --> B3 --> B4 --> C1
    C3 --> C2
    C1 --> C2
    C2 --> D[tsup build]
    D --> E[(dist/ cjs + esm + dts)]
    E --> F((npm: @reapit/foundations-ts-definitions))

Source endpoints

The fetcher is configured in src/scripts/fetch-definitions.js:

| Namespace | Endpoint | | --- | --- | | Platform | https://reapit-swagger-dev.s3.eu-west-2.amazonaws.com/foundations_swagger.json (S3 fallback while the /docs endpoint is down) | | Marketplace | ${PLATFORM_API_BASE_URL}/marketplace/swagger/v1.0/swagger.json | | Payments | ${PLATFORM_API_BASE_URL}/payments/swagger/latest/swagger.json | | Organisations | ${PLATFORM_API_BASE_URL}/organisations/swagger/v1.0/swagger.json |

PLATFORM_API_BASE_URL is defined in src/scripts/constants.js and currently points at https://platform.dev.paas.reapit.cloud.

Authentication

Some platform-hosted swagger endpoints require a Bearer token. The fetch script obtains one automatically via the OAuth2 client_credentials grant against the Reapit Connect token endpoint before fetching definitions.

| Variable | Purpose | | --- | --- | | CONNECT_CLIENT_ID | OAuth2 client ID for the Connect token endpoint | | CONNECT_CLIENT_SECRET | OAuth2 client secret |

These are stored as GitHub repository secrets and injected by the definitions-update.yml workflow.

Local development: If neither variable is set, the script logs a warning and falls back to unauthenticated requests. This is fine for endpoints that don't require auth (e.g. the Platform S3 swagger), but authenticated endpoints will fail. To test locally with auth, export the variables in your shell:

CONNECT_CLIENT_ID=xxx CONNECT_CLIENT_SECRET=yyy yarn start

Reapit APP Setup

reapit-ltd-foundations-ts-definition-party-time is the name of the app that used from https://developers.dev.paas.reapit.cloud with the CONNECT_CLIENT_ID and CONNECT_CLIENT_SECRET variables.

Fetch sequence

sequenceDiagram
    participant Cron as GitHub Actions cron
    participant Script as fetch-definitions.js
    participant API as Platform Swagger endpoint
    participant FS as src/types/
    participant PR as peter-evans/create-pull-request

    Cron->>Script: yarn start
    Script->>FS: rimraf + mkdir src/types
    loop For each schema
        Script->>API: GET swagger.json
        API-->>Script: OpenAPI document
        Script->>Script: sw2dts.convert(namespace)
        Script->>Script: prettier format
        Script->>FS: append export to <ns>-schema.ts
    end
    Script->>FS: write index.ts barrel
    Cron->>PR: open "chore: Update TS Definitions" PR

Build pipeline

Bundling is handled by tsup - see tsup.config.ts:

• Entry: src/index.ts
• Formats: cjs + esm
• Target: node18
• clean: true, minify: true, dts: true

yarn build produces:

dist/
├── index.js     # CommonJS
├── index.mjs    # ESM
└── index.d.ts   # Bundled types

Only the dist/ folder is published to npm (see files in package.json).

GitHub workflows

Under .github/workflows:

flowchart TD
    PR[Pull Request opened/synchronized] --> BuildPR[build-pr.yml: yarn build]
    PR --> CheckPR[check-pr.yml: yarn typecheck]
    PR --> LintPR[lint-pr.yml / pr-lint.yml]

    Cron{{Monday 00:00 UTC cron}} --> Update[definitions-update.yml]
    Update --> Fetch[yarn start - regenerate types]
    Fetch --> OpenPR[create-pull-request action]
    OpenPR --> PR

    Merge[Release published on GitHub] --> Release[release-prod.yml]
    Release --> Publish[npm publish --tag latest]

    Delete[Release deleted on GitHub] --> Rollback[rollback-prod.yml]
    Rollback --> Retag[npm tag latest -> previous version]

| Workflow | Trigger | Purpose | | --- | --- | --- | | build-pr.yml | PR opened/synchronized | yarn build | | check-pr.yml | PR opened/synchronized | yarn typecheck | | lint-pr.yml, pr-lint.yml | PR opened/synchronized | Lint checks | | definitions-update.yml | Cron 0 0 * * 1 | Re-fetch swagger, open PR with regenerated types | | release-prod.yml | GitHub Release published | Build and npm publish --tag latest | | rollback-prod.yml | GitHub Release deleted | Repoint latest npm dist-tag to previous version |

All jobs run on the self-hosted runner group rpt-gbl-linux-x64 with Node 22.

Local development

Requirements: Node 22+, Yarn 4 (Berry - pinned via packageManager in package.json).

# Install deps
yarn

# Regenerate types from upstream swagger (writes src/types/*.ts)
yarn start

# Typecheck without emitting
yarn typecheck

# Build the package into dist/
yarn build

# Lint
yarn lint

# Test auth and probe swagger endpoints
yarn test:auth

yarn start hits live Reapit platform endpoints. Any changes in the upstream swagger will appear as diffs under src/types/.

Testing authentication locally

A diagnostic script is provided to verify credentials and endpoint availability without running the full fetch pipeline:

yarn test:auth

The script runs four steps:

1. Env var check — verifies CONNECT_CLIENT_ID and CONNECT_CLIENT_SECRET are set
2. OAuth2 token — attempts client_credentials auth against Connect; auto-retries with application/x-www-form-urlencoded if JSON fails
3. Authenticated endpoints — probes all three authenticated swagger endpoints (Marketplace, Payments, Organisations)
4. Unauthenticated endpoint — probes the Platform S3 fallback swagger

Successful swagger responses are saved to ./tempSwaggers/ for local inspection (this directory is git-ignored).

Credentials can be provided via a .env file in the project root:

CONNECT_CLIENT_ID=your_client_id
CONNECT_CLIENT_SECRET=your_client_secret

The script loads .env automatically — no extra dependencies required.

Project layout

src/
├── index.ts                        # Public entry, re-exports everything
├── api-key-schema/                 # Hand-written
├── deployment-schema/              # Hand-written
├── marketplace-cms/                # Hand-written
├── traffic-schema/                 # Hand-written
├── webhook-schema/                 # Hand-written
├── types/                          # GENERATED - do not edit by hand
│   ├── index.ts
│   ├── platform-schema.ts
│   ├── marketplace-schema.ts
│   ├── payments-schema.ts
│   └── organisations-schema.ts
└── scripts/                        # Node scripts used by `yarn start`
    ├── constants.js
    ├── fetch-definitions.js
    ├── create-index-file.js
    ├── format-code.js
    ├── handle-cronjob.js
    └── ...

Release process

1. The weekly cron job opens a chore: Update TS Definitions PR if the generated types have changed.
2. A human reviews and merges the PR.
3. A maintainer cuts a GitHub Release (semver tag).
4. release-prod.yml fires, builds the package and publishes to npm under the latest dist-tag.
5. If a release is ever deleted, rollback-prod.yml re-points latest to the previous tagged version on npm.

License

MIT - see package.json.