@lokalise/expert-api-s2s-client 1.0.1

package/README.md

@@ -0,0 +1,3 @@
+# Lokalise Expert API Client for Service-to-Service communication
+
+FIXME: describe why it is here, not a separate repo, not a Harmony package, not combined with packages/backend-plugins/populate-expert-user/clients/BackendExpertHttpClient, not combined with Lokalise Node.js API client

package/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "@lokalise/expert-api-s2s-client",
+    "version": "1.0.1",
+    "files": [
+        "src"
+    ],
+    "type": "module",
+    "main": "./dist/index.js",
+    "exports": {
+        ".": "./dist/index.js",
+        "./package.json": "./package.json"
+    },
+    "scripts": {
+        "build": "npm run clean && tsc --project tsconfig.build.json",
+        "clean": "rimraf dist",
+        "lint": "biome check . && tsc",
+        "lint:fix": "biome check --write",
+        "test": "vitest run --coverage",
+        "package-version": "echo $npm_package_version",
+        "prepublishOnly": "npm run build",
+        "postversion": "biome check --write package.json"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@lokalise/backend-expert-http-client": "*",
+        "@lokalise/backend-http-client": "^7.0.0",
+        "@lokalise/fastify-extras": "^29.0.0",
+        "@lokalise/node-api": "^14.2.0",
+        "@lokalise/common-api-schemas": "^1.1.0",
+        "@lokalise/workspaces-api-schemas": "^1.1.0",
+        "openid-client": "^6.3.4",
+        "zod": "^3.25.76"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.0.0",
+        "@lokalise/biome-config": "^3.0.0",
+        "@lokalise/tsconfig": "^1.3.0",
+        "@vitest/coverage-v8": "^3.0.9",
+        "mockttp": "^4.1.0",
+        "rimraf": "^6.0.1",
+        "typescript": "5.9.2",
+        "vitest": "^3.2.4"
+    },
+    "peerDependencies": {
+        "mockttp": "^4.1.0"
+    }
+}

package/src/ExpertApiS2SClient.ts

@@ -0,0 +1,77 @@
+import type { RequestContext } from '@lokalise/fastify-extras'
+import type { ProjectStatistics } from '@lokalise/node-api'
+import type { GetExpertProjectData } from '@lokalise/workspaces-api-schemas'
+
+/**
+ * Represents the Projects API response type.
+ *
+ * This type extends the original `Project` object with additional fields.
+ * Some of these fields are currently mocked and not part of the actual API response,
+ * while others exist in the API but are not declared in the Node.js SDK types.
+ *
+ * We're using a direct type declaration instead of a Zod schema because we plan
+ * to eventually remove the internal API client in favor of the public Node.js SDK.
+ * Since the SDK types are not based on Zod, this approach ensures a smoother transition.
+ */
+export type GetProjectResponseExtendedVariant = Omit<GetExpertProjectData, 'statistics'> & {
+  base_project_language_uuid: string
+  // Redefining statistics to add missing properties in languages field, which are not present in the original Project type.
+  statistics: Omit<ProjectStatistics, 'languages'> & {
+    languages: ProjectLanguageExtendedVariant[]
+  }
+}
+
+type ProjectLanguageExtendedVariant = {
+  language_id: number
+  language_iso: string
+  progress: number
+  words_to_do: number
+  project_language_id: number
+  project_language_uuid: string
+}
+
+export type GetProjectLanguagesResponse = {
+  projectId: string
+  workspaceId: string
+  baseLanguageId: string
+  languages: ProjectLanguage[]
+}
+
+type ProjectLanguage = {
+  id: string
+  locale: string
+  isBaseLanguage: boolean
+}
+
+export type UserResponse = {
+  id: number
+  uuid: string
+  email: string
+  fullname: string
+}
+
+/**
+ * Server-to-server client interface for interacting with the Expert API.
+ *
+ * This interface abstracts the internal implementation details of API access,
+ * which may change over time. It serves as a temporary solution and is intended
+ * to be replaced by the official public Node.js SDK in the future.
+ */
+export interface ExpertApiS2SClient {
+  getProject(
+    projectId: string,
+    requestContext?: RequestContext,
+  ): Promise<GetProjectResponseExtendedVariant | null>
+
+  getTeamProjects(
+    teamId: string,
+    requestContext?: RequestContext,
+  ): AsyncGenerator<GetProjectResponseExtendedVariant>
+
+  getProjectLanguages(
+    projectId: string,
+    requestContext?: RequestContext,
+  ): Promise<GetProjectLanguagesResponse>
+
+  getUser(userId: string, requestContext?: RequestContext): Promise<UserResponse>
+}

package/src/ExpertPublicApiClient.spec.ts

@@ -0,0 +1,445 @@
+import { randomUUID } from 'node:crypto'
+import { constants as httpConstants } from 'node:http2'
+import { ResponseStatusError } from '@lokalise/backend-http-client'
+import type { GetExpertUserBasicData } from '@lokalise/workspaces-api-schemas'
+import { getLocal } from 'mockttp'
+import { describe } from 'vitest'
+import { ZodError } from 'zod/v4'
+import EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE from '../test/fixtures/expertOauth2TokenResponse.json' with {
+  type: 'json',
+}
+import EXPERT_OAUTH2_TOKEN_RESPONSE_WITHOUT_EXPIRY_SAMPLE from '../test/fixtures/expertOauth2TokenResponseWithoutExpiry.json' with {
+  type: 'json',
+}
+import EXPERT_REST_API_GET_BASIC_USER_DATA_RESPONSE_SAMPLE from '../test/fixtures/expertPublicApiGetBasicUserData.json' with {
+  type: 'json',
+}
+import EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE from '../test/fixtures/expertPublicApiGetProjectResponse.json' with {
+  type: 'json',
+}
+import EXPERT_REST_API_GET_PROJECTS_RESPONSE_SAMPLE_1 from '../test/fixtures/expertPublicApiGetProjectsResponse_MultiPage_1.json' with {
+  type: 'json',
+}
+import EXPERT_REST_API_GET_PROJECTS_RESPONSE_SAMPLE_2 from '../test/fixtures/expertPublicApiGetProjectsResponse_MultiPage_2.json' with {
+  type: 'json',
+}
+import { FAKE_REQUEST_CONTEXT } from '../test/requestContextMocks.ts'
+import type { GetProjectLanguagesResponse } from './ExpertApiS2SClient.ts'
+import { ExpertPublicApiClient } from './ExpertPublicApiClient.ts'
+
+const FAKE_OAUTH2_CLIENT_ID = 'dummy-client-id'
+const FAKE_OAUTH2_CLIENT_SECRET = 'dummy-client-secret'
+
+describe('ExpertPublicApiClient', () => {
+  const mockttp = getLocal()
+  let client: ExpertPublicApiClient
+
+  beforeEach(async () => {
+    await mockttp.start()
+    client = new ExpertPublicApiClient(mockttp.url, {
+      serverUrl: mockttp.url,
+      clientId: FAKE_OAUTH2_CLIENT_ID,
+      clientSecret: FAKE_OAUTH2_CLIENT_SECRET,
+      allowInsecureRequests: true,
+    })
+  })
+
+  afterEach(async () => {
+    await mockttp.stop()
+    vi.useRealTimers()
+  })
+
+  describe('getProject', () => {
+    it('obtains a token, performs request with it and returns data when API responds with valid response', async () => {
+      // Given
+      const projectUuid = EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE.uuid
+      const accessToken = EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE.access_token
+
+      await mockttp
+        .forPost('/oauth2/token')
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE)
+
+      await mockttp
+        .forGet(`/api2/projects/${projectUuid}`)
+        .withHeaders({
+          Authorization: `Bearer ${accessToken}`,
+        })
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE)
+
+      // When
+      const result = await client.getProject(projectUuid, FAKE_REQUEST_CONTEXT)
+
+      // Then
+      expect(result).toEqual(EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE)
+    })
+    it('reuses the token for the next request if it is still valid', async () => {
+      // Given
+      const projectUuid = EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE.uuid
+
+      const tokenEndpointMock = await mockttp
+        .forPost('/oauth2/token')
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE)
+
+      await mockttp
+        .forGet(`/api2/projects/${projectUuid}`)
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE)
+
+      // When
+      // We are requesting API subsequently.
+      await client.getProject(projectUuid, FAKE_REQUEST_CONTEXT)
+      await client.getProject(projectUuid, FAKE_REQUEST_CONTEXT)
+
+      // Then
+      // We should see there was only one request to the token endpoint.
+      await expect(tokenEndpointMock.getSeenRequests()).resolves.toHaveLength(1)
+    })
+    it('requests for a new token when previous one expired', async () => {
+      // Given
+      const projectUuid = EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE.uuid
+
+      const tokenEndpointMock = await mockttp
+        .forPost('/oauth2/token')
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE)
+
+      await mockttp
+        .forGet(`/api2/projects/${projectUuid}`)
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE)
+
+      // When
+      await client.getProject(projectUuid, FAKE_REQUEST_CONTEXT)
+
+      // Fast-forward time to simulate token expiration.
+      vi.setSystemTime(Date.now() + (3600 + 1) * 1000) // 1 second after expiration
+
+      // Request again, should trigger new token request.
+      await client.getProject(projectUuid, FAKE_REQUEST_CONTEXT)
+
+      // Then
+      // Should see two requests to the token endpoint.
+      await expect(tokenEndpointMock.getSeenRequests()).resolves.toHaveLength(2)
+    })
+    it('supports tokens without expiry date', async () => {
+      // Given
+      const projectUuid = EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE.uuid
+
+      const tokenEndpointMock = await mockttp
+        .forPost('/oauth2/token')
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_OAUTH2_TOKEN_RESPONSE_WITHOUT_EXPIRY_SAMPLE)
+
+      await mockttp
+        .forGet(`/api2/projects/${projectUuid}`)
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE)
+
+      // When
+      await client.getProject(projectUuid, FAKE_REQUEST_CONTEXT)
+
+      // Fast-forward time to simulate token expiration.
+      vi.setSystemTime(Date.now() + (3600 + 1) * 1000) // 1 second after expiration
+
+      // Request again, still should not trigger new token request.
+      await client.getProject(projectUuid, FAKE_REQUEST_CONTEXT)
+
+      // Then
+      // We should see there was only one request to the token endpoint.
+      await expect(tokenEndpointMock.getSeenRequests()).resolves.toHaveLength(1)
+    })
+
+    it('throws an error if project response if not passing validation', async () => {
+      const projectUuid = EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE.uuid
+
+      await mockttp
+        .forPost('/oauth2/token')
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_OAUTH2_TOKEN_RESPONSE_WITHOUT_EXPIRY_SAMPLE)
+
+      await mockttp
+        .forGet(`/api2/projects/${projectUuid}`)
+        .thenJson(httpConstants.HTTP_STATUS_OK, { data: 'nonsense' })
+
+      await expect(client.getProject(projectUuid, FAKE_REQUEST_CONTEXT)).rejects.toThrow(ZodError)
+    })
+
+    it('throws an error if request fails', async () => {
+      const projectUuid = EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE.uuid
+
+      await mockttp
+        .forPost('/oauth2/token')
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_OAUTH2_TOKEN_RESPONSE_WITHOUT_EXPIRY_SAMPLE)
+
+      await mockttp
+        .forGet(`/api2/projects/${projectUuid}`)
+        .thenJson(httpConstants.HTTP_STATUS_UNAUTHORIZED, { error: 'Access denied' })
+
+      await expect(client.getProject(projectUuid, FAKE_REQUEST_CONTEXT)).rejects.toThrow(
+        ResponseStatusError,
+      )
+    })
+
+    it('returns null if project is not found', async () => {
+      // Given
+      const projectUuid = EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE.uuid
+
+      await mockttp
+        .forPost('/oauth2/token')
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_OAUTH2_TOKEN_RESPONSE_WITHOUT_EXPIRY_SAMPLE)
+
+      await mockttp
+        .forGet(`/api2/projects/${projectUuid}`)
+        .thenJson(httpConstants.HTTP_STATUS_NOT_FOUND, { error: 'Project not found' })
+
+      // When
+      const result = await client.getProject(projectUuid, FAKE_REQUEST_CONTEXT)
+
+      // Then
+      expect(result).toEqual(null)
+    })
+  })
+
+  describe('getTeamProjects', () => {
+    it('obtains a token, loops through the multiple pages or results until data is collected', async () => {
+      // Given
+      const teamUuid = randomUUID()
+      const accessToken = EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE.access_token
+
+      await mockttp
+        .forPost('/oauth2/token')
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE)
+
+      // First page response
+      await mockttp
+        .forGet('/api2/projects')
+        .withQuery({
+          filter_team_id: teamUuid,
+          page: 1,
+        })
+        .withHeaders({
+          Authorization: `Bearer ${accessToken}`,
+        })
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_REST_API_GET_PROJECTS_RESPONSE_SAMPLE_1, {
+          'x-pagination-total-count': '2',
+          'x-pagination-page-count': '2',
+          'x-pagination-limit': '1',
+          'x-pagination-page': '1',
+        })
+
+      // Second page response
+      await mockttp
+        .forGet('/api2/projects')
+        .withQuery({
+          filter_team_id: teamUuid,
+          page: 2,
+        })
+        .withHeaders({
+          Authorization: `Bearer ${accessToken}`,
+        })
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_REST_API_GET_PROJECTS_RESPONSE_SAMPLE_2, {
+          'x-pagination-total-count': '2',
+          'x-pagination-page-count': '2',
+          'x-pagination-limit': '1',
+          'x-pagination-page': '2',
+        })
+
+      // When
+      const result = []
+      for await (const project of client.getTeamProjects(teamUuid, FAKE_REQUEST_CONTEXT)) {
+        result.push(project)
+      }
+
+      // Then
+      expect(result).toEqual([
+        EXPERT_REST_API_GET_PROJECTS_RESPONSE_SAMPLE_1.projects[0],
+        EXPERT_REST_API_GET_PROJECTS_RESPONSE_SAMPLE_2.projects[0],
+      ])
+    })
+    it('stops looping in case of a wrong response', async () => {
+      const teamUuid = randomUUID()
+      const accessToken = EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE.access_token
+
+      await mockttp
+        .forPost('/oauth2/token')
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE)
+
+      // First page response
+      await mockttp
+        .forGet('/api2/projects')
+        .withQuery({
+          filter_team_id: teamUuid,
+          page: 1,
+        })
+        .withHeaders({
+          Authorization: `Bearer ${accessToken}`,
+        })
+        .thenJson(
+          httpConstants.HTTP_STATUS_OK,
+          { data: 'nonsense' },
+          {
+            'x-pagination-total-count': '2',
+            'x-pagination-page-count': '2',
+            'x-pagination-limit': '1',
+            'x-pagination-page': '1',
+          },
+        )
+
+      const result = []
+      for await (const project of client.getTeamProjects(teamUuid, FAKE_REQUEST_CONTEXT)) {
+        result.push(project)
+      }
+
+      expect(result).toEqual([])
+    })
+    it('stops fetching projects when maxPages is reached', async () => {
+      // Given
+      const teamUuid = randomUUID()
+      const accessToken = EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE.access_token
+
+      await mockttp
+        .forPost('/oauth2/token')
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE)
+
+      await mockttp
+        .forGet('/api2/projects')
+        .withQuery({
+          filter_team_id: teamUuid,
+          page: 1,
+        })
+        .withHeaders({
+          Authorization: `Bearer ${accessToken}`,
+        })
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_REST_API_GET_PROJECTS_RESPONSE_SAMPLE_1, {
+          'x-pagination-total-count': '100500',
+          'x-pagination-page-count': '1000',
+          'x-pagination-limit': '100',
+          'x-pagination-page': '1',
+        })
+
+      const maxPages = 1
+      const loggerSpy = vi.spyOn(FAKE_REQUEST_CONTEXT.logger, 'warn')
+
+      const result = []
+      for await (const project of client.getTeamProjects(
+        teamUuid,
+        FAKE_REQUEST_CONTEXT,
+        maxPages,
+      )) {
+        result.push(project)
+      }
+
+      expect(result).toEqual([EXPERT_REST_API_GET_PROJECTS_RESPONSE_SAMPLE_1.projects[0]])
+
+      expect(loggerSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          teamId: teamUuid,
+          maxPages,
+          totalPages: 1000,
+        }),
+        expect.stringContaining('Reached maximum number of pages while fetching projects for team'),
+      )
+    })
+  })
+
+  describe('getProjectLanguages', () => {
+    it('obtains a token, performs request with it and returns mapped languages extracted from the response', async () => {
+      // Given
+      const projectUuid = EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE.uuid
+      const accessToken = EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE.access_token
+
+      await mockttp
+        .forPost('/oauth2/token')
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE)
+
+      await mockttp
+        .forGet(`/api2/projects/${projectUuid}`)
+        .withHeaders({
+          Authorization: `Bearer ${accessToken}`,
+        })
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE)
+
+      // When
+      const result = await client.getProjectLanguages(projectUuid, FAKE_REQUEST_CONTEXT)
+
+      // Then
+      expect(result).toEqual({
+        projectId: projectUuid,
+        workspaceId: '1cc09f87-b8d7-425c-97e1-16e42d8644ed',
+        baseLanguageId: '0195aaf1-ef28-7359-be22-8b02918b6b7d',
+        languages: [
+          {
+            id: '0195aaf1-ef28-7359-be22-8b02918b6b7d',
+            locale: 'en',
+            isBaseLanguage: true,
+          },
+          {
+            id: '0195aaf1-ef28-7359-be22-8b02921d367e',
+            locale: 'lv',
+            isBaseLanguage: false,
+          },
+        ],
+      } satisfies GetProjectLanguagesResponse)
+    })
+
+    it('throws an error if project is not found', async () => {
+      // Given
+      const projectUuid = EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE.uuid
+
+      await mockttp
+        .forPost('/oauth2/token')
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE)
+
+      await mockttp
+        .forGet(`/api2/projects/${projectUuid}`)
+        .thenJson(httpConstants.HTTP_STATUS_NOT_FOUND, { error: 'Project not found' })
+
+      // When + Then
+      await expect(client.getProjectLanguages(projectUuid, FAKE_REQUEST_CONTEXT)).rejects.toThrow(
+        new Error(`Project not found: ${projectUuid}`),
+      )
+    })
+  })
+
+  describe('getUser', () => {
+    it('obtains a token, performs request with it and returns user basic info from the response', async () => {
+      // Given
+      const userId = EXPERT_REST_API_GET_BASIC_USER_DATA_RESPONSE_SAMPLE.id
+      const accessToken = EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE.access_token
+
+      await mockttp
+        .forPost('/oauth2/token')
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE)
+
+      await mockttp
+        .forGet(`/api2/users/${userId}`)
+        .withHeaders({
+          Authorization: `Bearer ${accessToken}`,
+        })
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_REST_API_GET_BASIC_USER_DATA_RESPONSE_SAMPLE)
+
+      // When
+      const result = await client.getUser(`${userId}`, FAKE_REQUEST_CONTEXT)
+
+      // Then
+      expect(result).toEqual({
+        id: userId,
+        uuid: '01982dac-13dc-7a72-9e42-f43f67c5342d',
+        email: 'test@lokalise.com',
+        fullname: 'Test User',
+      } satisfies GetExpertUserBasicData)
+    })
+
+    it('throws an error if project is not found', async () => {
+      // Given
+      const userId = EXPERT_REST_API_GET_BASIC_USER_DATA_RESPONSE_SAMPLE.id
+
+      await mockttp
+        .forPost('/oauth2/token')
+        .thenJson(httpConstants.HTTP_STATUS_OK, EXPERT_OAUTH2_TOKEN_RESPONSE_SAMPLE)
+
+      await mockttp
+        .forGet(`/api2/users/${userId}`)
+        .thenJson(httpConstants.HTTP_STATUS_NOT_FOUND, { error: 'Project not found' })
+
+      // When + Then
+      await expect(client.getUser(`${userId}`, FAKE_REQUEST_CONTEXT)).rejects.toThrow(
+        new Error(`User not found: ${userId}`),
+      )
+    })
+  })
+})

package/src/ExpertPublicApiClient.ts

@@ -0,0 +1,207 @@
+import { BackendExpertHttpClient } from '@lokalise/backend-expert-http-client'
+import type { RequestContext } from '@lokalise/fastify-extras'
+import type { GetExpertProjectData } from '@lokalise/workspaces-api-schemas'
+import { allowInsecureRequests, Configuration, clientCredentialsGrant } from 'openid-client'
+import type {
+  ExpertApiS2SClient,
+  GetProjectLanguagesResponse,
+  GetProjectResponseExtendedVariant,
+  UserResponse,
+} from './ExpertApiS2SClient.ts'
+
+type OAuth2ClientConfiguration = {
+  serverUrl: string
+  clientId: string
+  clientSecret: string
+  allowInsecureRequests?: boolean
+}
+
+const PROJECT_LIST_MAX_PAGES = 10
+
+/**
+ * Public API based S2S client implementation that is aware of OAuth Client credentials authentication.
+ * Uses Node.js SDK for public API part and OpenID client for authentication part.
+ */
+export class ExpertPublicApiClient implements ExpertApiS2SClient {
+  private readonly oauth2ClientConfiguration: OAuth2ClientConfiguration
+
+  /* OpenID client configuration is static and can be safely re-used, we want to instantiate it only once and will keep here for re-using. */
+  private openIdClientConfiguration?: Configuration
+
+  private accessToken: string | null
+
+  /* Lokalise API client depends on the access token so we need to re-create it each time we obtain a new token. */
+  private lokaliseApiClient: BackendExpertHttpClient
+
+  /* Access token we obtain is valid for a limited time, we need to keep track of it and re-obtain when it expires. */
+  private lastObtainedApiTokenExpiresAt?: Date
+
+  constructor(apiBaseUrl: string, oauth2ClientConfiguration: OAuth2ClientConfiguration) {
+    this.lokaliseApiClient = new BackendExpertHttpClient(apiBaseUrl)
+    this.accessToken = null
+    this.oauth2ClientConfiguration = oauth2ClientConfiguration
+  }
+
+  async getProject(
+    projectId: string,
+    requestContext?: RequestContext,
+  ): Promise<GetProjectResponseExtendedVariant | null> {
+    await this.refreshAuthenticationToken(requestContext)
+    const project = await this.lokaliseApiClient.getProject(
+      projectId,
+      this.accessToken,
+      requestContext,
+    )
+
+    if (!project) {
+      return null
+    }
+
+    return ExpertPublicApiClient.assertProjectResponseExtendedVariant(project)
+  }
+
+  async *getTeamProjects(
+    teamId: string,
+    requestContext?: RequestContext,
+    maxPages = PROJECT_LIST_MAX_PAGES,
+  ): AsyncGenerator<GetProjectResponseExtendedVariant> {
+    await this.refreshAuthenticationToken(requestContext)
+
+    let page = 1
+    let hasNextPage = true
+
+    while (hasNextPage) {
+      const projectsList = await this.lokaliseApiClient.getTeamProjects(
+        teamId,
+        page,
+        this.accessToken,
+        requestContext,
+      )
+      if (projectsList == null) {
+        break
+      }
+      page++
+      hasNextPage = projectsList.hasNextPage()
+
+      for (const project of projectsList.items) {
+        yield ExpertPublicApiClient.assertProjectResponseExtendedVariant(project)
+      }
+
+      // The check below is primarily to ensure we will never go into an infinite loop because of some bug in the SDK/API.
+      if (page > maxPages) {
+        requestContext?.logger.warn(
+          {
+            teamId,
+            maxPages,
+            totalPages: projectsList.totalPages,
+          },
+          'Reached maximum number of pages while fetching projects for team, stopping the loop',
+        )
+        break
+      }
+    }
+  }
+
+  private async refreshAuthenticationToken(requestContext?: RequestContext): Promise<void> {
+    if (
+      this.accessToken === null ||
+      (this.lastObtainedApiTokenExpiresAt !== undefined &&
+        this.lastObtainedApiTokenExpiresAt < new Date())
+    ) {
+      const { accessToken, expiresAt } = await this.obtainNewAccessToken(requestContext)
+      this.accessToken = accessToken
+      this.lastObtainedApiTokenExpiresAt = expiresAt
+    }
+  }
+
+  async getProjectLanguages(
+    projectId: string,
+    requestContext?: RequestContext,
+  ): Promise<GetProjectLanguagesResponse> {
+    const project = await this.getProject(projectId, requestContext)
+
+    if (!project) {
+      throw new Error(`Project not found: ${projectId}`)
+    }
+
+    const baseLanguageId = project.base_project_language_uuid
+    return {
+      // biome-ignore lint/style/noNonNullAssertion: TODO: uuid should be always defined here, but is marked as optional in type
+      projectId: project.uuid!,
+      workspaceId: project.team_uuid,
+      baseLanguageId: project.base_project_language_uuid,
+      languages: project.statistics.languages.map((l) => ({
+        id: l.project_language_uuid,
+        locale: l.language_iso.replace('_', '-'),
+        isBaseLanguage: l.project_language_uuid === baseLanguageId,
+      })),
+    }
+  }
+
+  async getUser(userId: string, requestContext?: RequestContext): Promise<UserResponse> {
+    await this.refreshAuthenticationToken(requestContext)
+    const user = await this.lokaliseApiClient.getBasicUserData(
+      userId,
+      this.accessToken,
+      requestContext,
+    )
+
+    if (!user) {
+      throw new Error(`User not found: ${userId}`)
+    }
+
+    return {
+      id: user.id,
+      uuid: user.uuid,
+      email: user.email,
+      fullname: user.fullname,
+    }
+  }
+
+  private async obtainNewAccessToken(requestContext?: RequestContext) {
+    const config = this.getOrCreateOpenIdClientConfiguration(requestContext)
+
+    const { access_token: accessToken, expires_in: expiresIn } = await clientCredentialsGrant(
+      config,
+      { scope: 'service_to_service' },
+    )
+    return {
+      accessToken,
+      expiresAt: expiresIn ? new Date(Date.now() + expiresIn * 1000) : undefined,
+    }
+  }
+
+  private getOrCreateOpenIdClientConfiguration(requestContext?: RequestContext) {
+    if (!this.openIdClientConfiguration) {
+      const config = new Configuration(
+        {
+          issuer: 'lokalise-expert', //
+          token_endpoint: `${this.oauth2ClientConfiguration.serverUrl}/oauth2/token`,
+        },
+        this.oauth2ClientConfiguration.clientId,
+        this.oauth2ClientConfiguration.clientSecret,
+      )
+
+      if (this.oauth2ClientConfiguration.allowInsecureRequests) {
+        requestContext?.logger.warn(
+          'DEVELOPMENT MODE! Insecure requests are allowed for Expert OAuth2 client',
+        )
+        allowInsecureRequests(config)
+      }
+
+      this.openIdClientConfiguration = config
+    }
+
+    return this.openIdClientConfiguration
+  }
+
+  private static assertProjectResponseExtendedVariant(
+    project: GetExpertProjectData,
+  ): GetProjectResponseExtendedVariant {
+    /**
+     * TODO: actual response is compatible with GetProjectResponseExtendedVariant, but the type is not
+     * Remove once addressed in the Node SDK
+     */
+    return project as GetProjectResponseExtendedVariant
+  }
+}

package/src/autopilotProjectUtils.spec.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest'
+import EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE from '../test/fixtures/expertPublicApiGetProjectResponse.json' with {
+  type: 'json',
+}
+import { mapExpertGetProjectResponseToAutopilotProject } from './autopilotProjectUtils.ts'
+
+describe('mapExpertGetProjectResponseToAutopilotProject', () => {
+  it('maps a valid expert project response to Autopilot project', () => {
+    const autopilotProject = mapExpertGetProjectResponseToAutopilotProject(
+      EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE,
+    )
+
+    expect(autopilotProject).toEqual({
+      baseContentLanguageId: '0195aaf1-ef28-7359-be22-8b02918b6b7d',
+      createdAt: '2025-03-18T20:28:57.000Z',
+      deletedAt: null,
+      description: '',
+      externalId: '8803108167d9d789431338.69025157',
+      id: '0195aaf1-f03a-701d-b5d4-28fbd011baae',
+      name: 'Sample Project',
+      reviewType: 'REVIEW_UNCONFIDENT',
+      status: 'ACTIVE',
+      updatedAt: null,
+      workspaceId: '1cc09f87-b8d7-425c-97e1-16e42d8644ed',
+    })
+  })
+  it('throws an error if the expert project is missing UUID', () => {
+    expect(() =>
+      mapExpertGetProjectResponseToAutopilotProject({
+        ...EXPERT_REST_API_GET_PROJECT_RESPONSE_SAMPLE,
+        uuid: null,
+      }),
+    ).toThrow(
+      'Expert project 8803108167d9d789431338.69025157 is missing UUID and cannot be mapped to an Autopilot project',
+    )
+  })
+})

package/src/autopilotProjectUtils.ts

@@ -0,0 +1,34 @@
+import { ReviewTypeEnum } from '@lokalise/common-api-schemas'
+import type { Project as AutopilotProject } from '@lokalise/workspaces-api-schemas'
+import { ProjectStatusEnum } from '@lokalise/workspaces-api-schemas'
+import type { GetProjectResponseExtendedVariant } from './ExpertApiS2SClient.ts'
+
+/**
+ * Although this is something that is not directly used by clients from this package, this mapping is likely to be needed in multiple services.
+ * It is therefore placed here to avoid code duplication.
+ */
+export function mapExpertGetProjectResponseToAutopilotProject(
+  expertResponse: GetProjectResponseExtendedVariant,
+): AutopilotProject {
+  // Although UUID is optional in Expert API responses, Autopilot requires it.
+  // It is expected to be present for newly created projects,therefore should be safe enforcing this explicitly here.
+  if (!expertResponse.uuid) {
+    throw new Error(
+      `Expert project ${expertResponse.project_id} is missing UUID and cannot be mapped to an Autopilot project`,
+    )
+  }
+
+  return {
+    id: expertResponse.uuid,
+    externalId: expertResponse.project_id,
+    workspaceId: expertResponse.team_uuid,
+    description: expertResponse.description,
+    name: expertResponse.name,
+    baseContentLanguageId: expertResponse.base_project_language_uuid,
+    status: ProjectStatusEnum.ACTIVE, // Expert projects lack explicit status. Defaulting to ACTIVE. (FIXME: reference to a task to address it properly)
+    reviewType: ReviewTypeEnum.REVIEW_UNCONFIDENT, // Expert projects lack review type, using a hardcoded one. TODO: to be addressed in https://lokalise.atlassian.net/browse/EXP-254
+    createdAt: new Date(expertResponse.created_at_timestamp * 1000).toISOString(),
+    updatedAt: null, // Expert API doesn't provide a last updated timestamp.
+    deletedAt: null, // No deleted projects are visible through API, null is appropriate. (TODO: Consider whether deletedAt should be internal repository detail, discuss hiding the value with relevant stakeholders (FIXME: task reference))
+  }
+}

package/src/clientFactory.spec.ts

@@ -0,0 +1,31 @@
+import { buildClient } from './clientFactory.ts'
+import { ExpertPublicApiClient } from './ExpertPublicApiClient.ts'
+
+describe('clientFactory', () => {
+  describe('buildClient', () => {
+    it('creates a public client', () => {
+      const client = buildClient({
+        baseUrl: 'https://api.example.org',
+        oauth2: {
+          serverUrl: 'https://oauth.example.com',
+          clientId: 'client-id',
+          clientSecret: 'client-secret',
+        },
+      })
+
+      expect(client).toBeInstanceOf(ExpertPublicApiClient)
+    })
+    it('creates a public client without internal API configuration', () => {
+      const client = buildClient({
+        baseUrl: 'https://api.example.org',
+        oauth2: {
+          serverUrl: 'https://oauth.example.com',
+          clientId: 'client-id',
+          clientSecret: 'client-secret',
+        },
+      })
+
+      expect(client).toBeInstanceOf(ExpertPublicApiClient)
+    })
+  })
+})

package/src/clientFactory.ts

@@ -0,0 +1,21 @@
+import type { ExpertApiS2SClient } from './ExpertApiS2SClient.ts'
+import { ExpertPublicApiClient } from './ExpertPublicApiClient.ts'
+
+export type ExpertApiS2SClientConfiguration = {
+  baseUrl: string
+  oauth2: {
+    serverUrl: string
+    clientId: string
+    clientSecret: string
+    allowInsecureRequests?: boolean
+  }
+}
+
+export function buildClient(config: ExpertApiS2SClientConfiguration): ExpertApiS2SClient {
+  return new ExpertPublicApiClient(config.baseUrl, {
+    serverUrl: config.oauth2.serverUrl,
+    clientId: config.oauth2.clientId,
+    clientSecret: config.oauth2.clientSecret,
+    allowInsecureRequests: config.oauth2.allowInsecureRequests,
+  })
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { mapExpertGetProjectResponseToAutopilotProject } from './autopilotProjectUtils.ts'
+export { buildClient, type ExpertApiS2SClientConfiguration } from './clientFactory.ts'
+export type {
+  ExpertApiS2SClient,
+  GetProjectLanguagesResponse,
+  GetProjectResponseExtendedVariant,
+  UserResponse,
+} from './ExpertApiS2SClient.ts'
+export { ExpertPublicApiClient } from './ExpertPublicApiClient.ts'