@presencelearning/api-client

Generated TypeScript API client using Hey-API.

Current version: 0.11.0. Generated with @hey-api/openapi-ts 0.90.9.

Install

npm install @presencelearning/api-client

Requirements

Node.js >= 20.0.0
Zod 3.23+ or 4.x
Angular 19+ (optional, for provideApiClient)

provideApiClient() is currently implemented with APP_INITIALIZER, which Angular deprecated in v19 in favour of provideAppInitializer. Expect a deprecation warning until that is migrated.

TypeScript Configuration

This package supports both modern and legacy TypeScript module resolution:

moduleResolution: "bundler" (recommended) — Subpath imports work automatically
moduleResolution: "node" (legacy) — Subpath imports work via typesVersions

No path aliases needed in either case.

Regenerating clients

The following commands are run from packages/api-client inside this monorepo — they are not consumer-facing.

Generate Clients

# Generate all clients
npm run generate

# Generate specific API
npm run generate:workplace:v1
npm run generate:workplace:v2
npm run generate:workplace:v3
npm run generate:workplace:test
npm run generate:auth:v1
npm run generate:platform:v1
npm run generate:platform:v2
npm run generate:platform:v3

Available Clients

| API | Import Path | | -------------- | ------------------------------------------------------------------------------------------------------------------------- | | Workplace v1 | @presencelearning/api-client/workplace/v1 | | Workplace v2 | @presencelearning/api-client/workplace/v2 | | Workplace v3 | @presencelearning/api-client/workplace/v3 | | Workplace test | @presencelearning/api-client/workplace/test | | Auth v1 | @presencelearning/api-client/auth/v1 | | Platform v1 | @presencelearning/api-client/platform/v1 | | Platform v2 | @presencelearning/api-client/platform/v2 | | Platform v3 | @presencelearning/api-client/platform/v3 | | Root | @presencelearning/api-client — configureClients, ConfigureClientsOptions, AuthCallback, plus namespace re-exports | | Angular | @presencelearning/api-client/angular — provideApiClient |

Adding More APIs

Copy an existing config:

cp openapi-ts.workplace-v1.config.ts openapi-ts.platform-v1.config.ts

Edit input/output paths in the new config

Add script to package.json:

"generate:platform:v1": "openapi-ts -f openapi-ts.platform-v1.config.ts"

Add to parallel generate script:

"generate": "npm-run-all --parallel generate:workplace:* generate:auth:* generate:platform:*"

Add export to package.json exports field

Configuration Options

See openapi-ts.workplace-v1.config.ts for documented options. Key settings:

input: OpenAPI schema URL or file path
output.path: Where to write generated files
plugins: TypeScript, client, SDK, and Zod configuration

Usage in Apps

Angular Apps (Recommended)

When the auth token comes from DI, configure the clients inside an app initializer. That is the only place you get both an injection context and a callback that can close over the resolved store:

import { ApplicationConfig, inject, provideAppInitializer } from '@angular/core';
import { configureClients } from '@presencelearning/api-client';

export const appConfig: ApplicationConfig = {
  providers: [
    provideAppInitializer(() => {
      const authStore = inject(AuthStore);
      configureClients({
        baseUrls: {
          auth: environment.apps.auth.url,
          workplace: environment.apps.apiWorkplace.url,
          platform: environment.apps.platform.url,
        },
        auth: () => authStore.getCurrentToken() ?? undefined,
      });
    }),
  ],
};

inject() must run in the initializer body, not in the auth callback — the callback is invoked per HTTP request, outside any injection context, so inject() there throws NG0203. AuthCallback returns string | undefined | Promise<string | undefined>, so coerce a null token with ?? undefined.

If your token does not come from DI, provideApiClient() from the /angular subpath is a shorthand for the same app-initializer wiring:

import { ApplicationConfig } from '@angular/core';
import { provideApiClient } from '@presencelearning/api-client/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideApiClient({
      baseUrls: {
        auth: environment.apps.auth.url,
        workplace: environment.apps.apiWorkplace.url,
        platform: environment.apps.platform.url,
      },
      auth: () => tokenStore.token,
    }),
  ],
};

provideApiClient() receives a plain config object evaluated where you call it, so it cannot resolve DI dependencies itself — use the initializer form above when it needs to.

Then use SDK functions in your components:

import { v1SchoolStaffProviderUsersRetrieve } from '@presencelearning/api-client/workplace/v1';

// SDK functions resolve to a result envelope, not the entity
const { data, error } = await v1SchoolStaffProviderUsersRetrieve({ path: { uuid } });

Every SDK function resolves to { data, error, request, response }. Path parameter names come from the OpenAPI spec — most Workplace resources are keyed by uuid.

Using with Angular Signals and resource() (Experimental)

The SDK returns Promises, which work seamlessly with Angular’s resource() API:

import { Component, input, resource } from '@angular/core';
import { v1SchoolStaffProviderUsersRetrieve } from '@presencelearning/api-client/workplace/v1';

@Component({
  template: `
    @if (user.hasValue()) {
      <user-profile [user]="user.value()" />
    } @else if (user.isLoading()) {
      <loading-spinner />
    } @else if (user.error()) {
      <error-message [error]="user.error()" />
    }
  `,
})
export class UserComponent {
  userId = input.required<string>();

  user = resource({
    params: () => ({ uuid: this.userId() }),
    loader: ({ params }) => v1SchoolStaffProviderUsersRetrieve({ path: { uuid: params.uuid } }),
  });
}

resource()’s first field was renamed from request to params in Angular 19.2. On earlier versions use request/{ request }.

Non-Angular Apps

Use configureClients() once at app startup to configure all API clients:

import { configureClients } from '@presencelearning/api-client';

configureClients({
  baseUrls: {
    auth: 'http://localhost:9000',
    workplace: 'http://localhost:8000',
    platform: 'http://localhost:8020',
  },
  auth: () => authStore.getCurrentToken(),
});

Then use SDK functions directly — they use the configured clients automatically:

import { someEndpoint } from '@presencelearning/api-client/workplace/v1';

const response = await someEndpoint({ path: { id: '123' } });

Namespace imports

The root entry point also re-exports each generated client as a namespace, which avoids long import lists:

import { workplaceV1, platformV2 } from '@presencelearning/api-client';

const { data } = await workplaceV1.v1ActivitiesList({});

Available namespaces: workplaceV1, workplaceV2, workplaceV3, workplaceTest, authV1, platformV1, platformV2, platformV3.

Reconfiguring clients

The generated modules do not re-export their underlying client instances, and there is no public client factory, so configureClients() is the only supported way to set base URLs and auth. It is safe to call again to repoint the clients — for example when switching environments in a dev tool:

import { configureClients } from '@presencelearning/api-client';

configureClients({
  baseUrls: {
    auth: 'https://auth.staging.presence.com',
    workplace: 'https://workplace.staging.presence.com',
    platform: 'https://platform.staging.presence.com',
  },
  auth: () => tokenStore.token,
});

There is currently no per-request base URL or auth override in the public API.

Hey-API references

Source: packages/api-client