elseware-api-builder

Composable RTK Query infrastructure for applications that communicate with one or more REST backends.

The package separates reusable runtime concerns from solution-specific REST contracts and endpoints. Use the root entry point for UI-agnostic consumers and elseware-api-builder/react for generated React hooks and authentication components.

import {
  createMemoryTokenStorage,
  createTokenAuth,
} from "elseware-api-builder";
import { createReactApiRuntime } from "elseware-api-builder/react";

const runtime = createReactApiRuntime({
  definition,
  services: {
    core: {
      baseUrl: "http://localhost:1111",
      credentials: "include",
    },
  },
  auth: createTokenAuth({
    storage: createMemoryTokenStorage(),
    refresh: refreshProtocol,
  }),
});

For browser applications, restore the in-memory access token with a cookie-authenticated POST refresh request during application bootstrap. Do not transport access tokens in redirect URLs or persist them in browser storage.

Engineering documentation

The engineering guide index links the complete authentication and standardized routing documentation. The authentication workflow guide covers:

• component responsibilities and trust boundaries;
• login, redirect, bootstrap, refresh, retry, and logout sequences;
• React and multi-service runtime integration;
• backend cookie, JWT, Google login, and refresh-session contracts;
• single-flight refresh and cross-tab rotation races;
• production security controls, tests, deployment, and troubleshooting.

The routing guide covers typed manifests, access inheritance, route compilation, client integration, matching, scrolling, and verification.

Register the returned reducers and middleware in the application store, then install solution endpoint modules or inject application endpoints directly into runtime.services.

Endpoint packages and application services

Solution packages can publish endpoint descriptors without owning a runtime:

export const productEndpoints = defineEndpointModule("core", (runtime) =>
  runtime.services.core.injectEndpoints({
    endpoints: (builder) => ({
      getProducts: builder.query({
        query: () => "/api/v1/product",
      }),
    }),
    overrideExisting: "throw",
  }),
);

const productApi = runtime.install(productEndpoints);

Applications can add a backend before creating the Redux store:

const applicationDefinition = extendApiDefinition(solutionDefinition, {
  services: {
    search: {
      reducerPath: "searchApi",
      tagTypes: ["SearchResult"],
    },
  },
});

Every service receives its own RTK Query reducer and middleware. Authenticated services share a single session and refresh coordinator, so concurrent 401 responses across backends produce one refresh request. Requests can opt out with auth: false or reauth: false.

Internal organization

The source is organized by responsibility:

• definition: package, service, endpoint-module, and request declarations.
• auth: token-auth configuration and the runtime session.
• storage: browser and in-memory token persistence.
• transport: HTTP base queries, request policy, refresh coordination, and authenticated retry.
• runtime: service assembly, validation, endpoint installation, and Redux store bindings.
• react: the React-enabled runtime and reusable authentication components.
• testing: test-store helpers for packages and applications.

createApiRuntime and createReactApiRuntime are composition roots. Lower-level transport and session helpers remain internal so applications only depend on the small public API.

Entry points

• elseware-api-builder: definitions, runtime, auth, and storage with no React import.
• elseware-api-builder/react: React-enabled runtime, generated hooks, and generic authentication components.
• elseware-api-builder/testing: a minimal Redux test-store factory.
• elseware-api-builder/routing: typed React Router manifests, authentication boundaries, matching, UI metadata, and scroll behavior.

Release

Pull requests targeting main run the complete validation suite and verify that the package version has not already been published. A successful merge to main runs the same checks and publishes through GitHub's OIDC trusted publishing; no long-lived npm token is stored in GitHub. Because this source repository is private, npm provenance is disabled.

Configure npm Trusted Publishing for elseware-api-builder using repository elsewaretechnology/elseware-api-builder, workflow publish.yml, and the GitHub environment npm-production. Keep package.json and package-lock.json synchronized and bump the version in the release PR:

npm version patch --no-git-tag-version

The workflow fails when the exact version already exists on npm. If the repository becomes public, remove --provenance=false to enable provenance.

Run the complete release validation without publishing:

npm run validate

Publish the current version to the public npm registry:

npm run release

The release command uses npm's prepublishOnly lifecycle to run type checks, linting, tests, the production build, package linting, and a dry-run package check before publishing.

The coordinated workspace uses local file dependencies during development. After publication, application manifests should use elseware-api-builder@^1.0.0; solution API packages should declare the same published dependency instead of a local file path.