feat(module-services): add people api

.changeset/spicy-bottles-tease.md

@@ -0,0 +1,18 @@
+---
+'@equinor/fusion-framework-module-services': minor
+---
+
+Added person services
+
+> __for internal usage only!__
+
+- add function for fetching person details
+- add function for querying persons
+- add function for downloading person photo
+
+```ts
+const personApi = await modules.services.createPeopleClient();
+personApi.query('v2', 'json$', {search: '[email protected]'})
+personApi.get('v4', 'json$', {azureId: '1234'})
+personApi.photo('v2', 'blob$', {azureId: '123'})
+``

packages/modules/services/src/people/api-models.ts

@@ -0,0 +1,59 @@
+import { ApiVersion } from './static';
+
+// TODO
+type ApiPersonDetailEntity_vX = {
+    azureId: string;
+    name?: string;
+    pictureSrc?: string;
+    jobTitle?: string;
+    department?: string;
+    mail?: string;
+    company?: string;
+    mobilePhone?: string;
+    // TODO
+    accountType?: ApiPersonAccountType_vX;
+    officeLocation?: string;
+    // TODO
+    positions?: ApiPersonPosition_vX[];
+    // TODO
+    manager?: ApiPersonManager_vX;
+    managerAzureUniqueId?: string;
+};
+
+// TODO
+enum ApiPersonAccountType_vX {
+    Employee = 'Employee',
+    Consultant = 'Consultant',
+    Enterprise = 'Enterprise',
+    External = 'External',
+    ExternalHire = 'External Hire',
+}
+
+// TODO
+type ApiPersonPosition_vX = {
+    id: string;
+    name: string;
+    project: {
+        id: string;
+        name: string;
+    };
+};
+
+// TODO
+type ApiPersonManager_vX = {
+    azureUniqueId: string;
+    name?: string;
+    pictureSrc?: string;
+    department?: string;
+    // TODO
+    accountType?: ApiPersonAccountType_vX;
+};
+
+type ApiPersonDetailTypes = {
+    // TODO
+    [ApiVersion.v2]: ApiPersonDetailEntity_vX;
+    // TODO
+    [ApiVersion.v4]: ApiPersonDetailEntity_vX;
+};
+
+export type ApiPersonDetailType<T extends ApiVersion> = ApiPersonDetailTypes[T];

packages/modules/services/src/people/client.ts

@@ -0,0 +1,89 @@
+import { IHttpClient } from '@equinor/fusion-framework-module-http';
+
+import type { ClientDataMethod, ClientMethod } from '../types';
+import { ApiVersion } from './static';
+
+import {
+    client as getClient,
+    ApiResponse as GetPersonApiResponse,
+    ApiRequestFn as GetPersonApiRequestFn,
+    ApiResult as GetPersonResult,
+    SupportedApiVersion as SupportedGetPersonApiVersion,
+} from './person-details';
+
+import {
+    client as queryClient,
+    ApiResponse as QueryPersonApiResponse,
+    ApiRequestFn as QueryPersonApiRequestFn,
+    ApiResult as QueryPersonResult,
+    SupportedApiVersion as SupportedQueryApiVersion,
+} from './query';
+
+import {
+    client as photoClient,
+    ApiResponse as PhotoPersonApiResponse,
+    ApiRequestFn as PhotoPersonApiRequestFn,
+    ApiResult as PhotoPersonResult,
+    SupportedApiVersion as SupportedPhotoApiVersion,
+} from './person-photo';
+
+export class PeopleApiClient<
+    // TMethod extends keyof ClientMethod<unknown> = keyof ClientMethod<unknown>,
+    TClient extends IHttpClient = IHttpClient,
+> {
+    get Version(): typeof ApiVersion {
+        return ApiVersion;
+    }
+
+    constructor(protected _client: TClient) {}
+
+    /**
+     * Fetch person by id
+     */
+    public get<
+        TVersion extends SupportedGetPersonApiVersion,
+        TResult = GetPersonApiResponse<TVersion>,
+        TMethod extends keyof ClientMethod<TResult> = keyof ClientMethod<TResult>,
+    >(
+        version: TVersion,
+        method: TMethod,
+        ...args: Parameters<GetPersonApiRequestFn<TVersion, TMethod, TClient, TResult>>
+    ): GetPersonResult<TVersion, TMethod, TResult> {
+        const fn = getClient<TVersion, TMethod, TClient>(this._client, version, method);
+        return fn<TResult>(...args);
+    }
+
+    /**
+     * Query person service
+     */
+    public query<
+        TVersion extends SupportedQueryApiVersion,
+        TResult = QueryPersonApiResponse<TVersion>,
+        TMethod extends keyof ClientMethod<TResult> = keyof ClientMethod<TResult>,
+    >(
+        version: TVersion,
+        method: TMethod,
+        ...args: Parameters<QueryPersonApiRequestFn<TVersion, TMethod, TClient, TResult>>
+    ): QueryPersonResult<TVersion, TMethod, TResult> {
+        const fn = queryClient<TVersion, TMethod, TClient>(this._client, version, method);
+        return fn<TResult>(...args);
+    }
+
+    /**
+     * Photo person service
+     */
+    public photo<
+        TVersion extends SupportedPhotoApiVersion,
+        TResult extends Blob = PhotoPersonApiResponse<TVersion>,
+        TMethod extends keyof ClientDataMethod = keyof ClientDataMethod,
+    >(
+        version: TVersion,
+        method: TMethod,
+        ...args: Parameters<PhotoPersonApiRequestFn<TVersion, TMethod, TClient, TResult>>
+    ): PhotoPersonResult<TMethod> {
+        const fn = photoClient<TVersion, TMethod, TClient>(this._client, version, method);
+        return fn<TResult>(...args);
+    }
+}
+
+export default PeopleApiClient;

packages/modules/services/src/people/person-details/client.ts

@@ -0,0 +1,32 @@
+import { ClientRequestInit, IHttpClient } from '@equinor/fusion-framework-module-http/client';
+
+import { generateParameters } from './generate-parameters';
+
+import type { ClientMethod } from '../../types';
+import type { ApiResponse, ApiResult, ApiRequestArgs, SupportedApiVersion } from './types';
+
+/**
+ * Method for fetching context item from context service
+ * @param client - client for execution of request
+ * @param version - version of API to call
+ * @param method - client method to call
+ */
+export const client =
+    <
+        TVersion extends SupportedApiVersion,
+        TMethod extends keyof ClientMethod = keyof ClientMethod,
+        TClient extends IHttpClient = IHttpClient,
+    >(
+        client: TClient,
+        version: TVersion,
+        method: TMethod = 'json' as TMethod,
+    ) =>
+    <T = ApiResponse<TVersion>>(
+        args: ApiRequestArgs<TVersion>,
+        init?: ClientRequestInit<TClient, T>,
+    ): ApiResult<TVersion, TMethod, T> =>
+        client[method](
+            ...generateParameters<T, TVersion, TClient>(version, args, init),
+        ) as ApiResult<TVersion, TMethod, T>;
+
+export default client;

packages/modules/services/src/people/person-details/generate-endpoint.ts

@@ -0,0 +1,25 @@
+import { UnsupportedApiVersion } from '../../errors';
+import { ApiVersion } from '../static';
+
+import type { ApiRequestArgs, SupportedApiVersion } from './types';
+
+/**
+ * Method for generating endpoint for getting context by id
+ */
+export const generateEndpoint = <TVersion extends SupportedApiVersion>(
+    version: TVersion,
+    args: ApiRequestArgs<TVersion>,
+) => {
+    const apiVersion = ApiVersion[version as keyof typeof ApiVersion] ?? version;
+    switch (apiVersion) {
+        case ApiVersion.v4: {
+            const { azureId } = args;
+            const params = new URLSearchParams();
+            params.append('api-version', apiVersion);
+            return `/persons/${azureId}?${String(params)}`;
+        }
+        default: {
+            throw new UnsupportedApiVersion(version);
+        }
+    }
+};

packages/modules/services/src/people/person-details/generate-parameters.ts

@@ -0,0 +1,22 @@
+import type { ClientRequestInit, IHttpClient } from '@equinor/fusion-framework-module-http/client';
+
+import { generateEndpoint } from './generate-endpoint';
+
+import type { ApiClientArguments } from '../../types';
+import type { ApiRequestArgs, SupportedApiVersion } from './types';
+
+/** function for creating http client arguments  */
+export const generateParameters = <
+    TResult,
+    TVersion extends SupportedApiVersion,
+    TClient extends IHttpClient = IHttpClient,
+>(
+    version: TVersion,
+    args: ApiRequestArgs<TVersion>,
+    init?: ClientRequestInit<TClient, TResult>,
+): ApiClientArguments<TClient, TResult> => {
+    const path = generateEndpoint(version, args);
+    return [path, init];
+};
+
+export default generateParameters;

packages/modules/services/src/people/person-details/index.ts

@@ -0,0 +1,6 @@
+export { client, default } from './client';
+
+export { generateEndpoint } from './generate-endpoint';
+export { generateParameters } from './generate-parameters';
+
+export * from './types';

packages/modules/services/src/people/person-details/types.ts

@@ -0,0 +1,41 @@
+import { IHttpClient, ClientRequestInit } from '@equinor/fusion-framework-module-http/client';
+
+import { ApiVersion } from '../static';
+import { ApiPersonDetailType } from '../api-models';
+import { ClientMethod } from '../../types';
+
+export type SupportedApiVersion = Extract<keyof typeof ApiVersion, 'v4'>;
+
+type ApiRequestArgsMap = {
+    [ApiVersion.v4]: {
+        azureId: string;
+    };
+};
+
+export type ApiRequestArgs<T extends SupportedApiVersion> = T extends SupportedApiVersion
+    ? ApiRequestArgsMap[(typeof ApiVersion)[T]]
+    : never;
+
+type ApiResponseTypes = {
+    [ApiVersion.v4]: ApiPersonDetailType<ApiVersion.v4>;
+};
+
+export type ApiResponse<T extends SupportedApiVersion> = T extends SupportedApiVersion
+    ? ApiResponseTypes[(typeof ApiVersion)[T]]
+    : never;
+
+export type ApiRequestFn<
+    TVersion extends SupportedApiVersion,
+    TMethod extends keyof ClientMethod<unknown> = keyof ClientMethod<unknown>,
+    TClient extends IHttpClient = IHttpClient,
+    TResult = ApiResponse<TVersion>,
+> = (
+    args: ApiRequestArgs<TVersion>,
+    init?: ClientRequestInit<TClient, TResult>,
+) => ApiResult<TVersion, TMethod, TResult>;
+
+export type ApiResult<
+    TVersion extends SupportedApiVersion,
+    TMethod extends keyof ClientMethod<unknown> = keyof ClientMethod<unknown>,
+    TResult = ApiResponse<TVersion>,
+> = ClientMethod<TResult>[TMethod];

packages/modules/services/src/people/person-photo/client.ts

@@ -0,0 +1,32 @@
+import { ClientRequestInit, IHttpClient } from '@equinor/fusion-framework-module-http/client';
+
+import { generateParameters } from './generate-parameters';
+
+import type { ClientDataMethod } from '../../types';
+import type { ApiResponse, ApiRequestArgs, SupportedApiVersion } from './types';
+
+/**
+ * Method for fetching context item from context service
+ * @param client - client for execution of request
+ * @param version - version of API to call
+ * @param method - client method to call
+ */
+export const client =
+    <
+        TVersion extends SupportedApiVersion,
+        TMethod extends keyof ClientDataMethod = keyof ClientDataMethod,
+        TClient extends IHttpClient = IHttpClient,
+    >(
+        client: TClient,
+        version: TVersion,
+        method: TMethod = 'blob' as TMethod,
+    ) =>
+    <T extends Blob = ApiResponse<TVersion>>(
+        args: ApiRequestArgs<TVersion>,
+        init?: ClientRequestInit<TClient, T>,
+    ): ClientDataMethod[TMethod] =>
+        client[method](
+            ...generateParameters<T, TVersion, TClient>(version, args, init),
+        ) as ClientDataMethod[TMethod];
+
+export default client;

packages/modules/services/src/people/person-photo/generate-endpoint.ts

@@ -0,0 +1,25 @@
+import { UnsupportedApiVersion } from '../../errors';
+import { ApiVersion } from '../static';
+
+import type { ApiRequestArgs, SupportedApiVersion } from './types';
+
+/**
+ * Method for generating endpoint for getting context by id
+ */
+export const generateEndpoint = <TVersion extends SupportedApiVersion>(
+    version: TVersion,
+    args: ApiRequestArgs<TVersion>,
+) => {
+    const apiVersion = ApiVersion[version as keyof typeof ApiVersion] ?? version;
+    switch (apiVersion) {
+        case ApiVersion.v2: {
+            const { azureId } = args;
+            const params = new URLSearchParams();
+            params.append('api-version', apiVersion);
+            return `/persons/${azureId}?${String(params)}`;
+        }
+        default: {
+            throw new UnsupportedApiVersion(version);
+        }
+    }
+};

packages/modules/services/src/people/person-photo/generate-parameters.ts

@@ -0,0 +1,22 @@
+import type { ClientRequestInit, IHttpClient } from '@equinor/fusion-framework-module-http/client';
+
+import { generateEndpoint } from './generate-endpoint';
+
+import type { ApiClientArguments } from '../../types';
+import type { ApiRequestArgs, SupportedApiVersion } from './types';
+
+/** function for creating http client arguments  */
+export const generateParameters = <
+    TResult,
+    TVersion extends SupportedApiVersion,
+    TClient extends IHttpClient = IHttpClient,
+>(
+    version: TVersion,
+    args: ApiRequestArgs<TVersion>,
+    init?: ClientRequestInit<TClient, TResult>,
+): ApiClientArguments<TClient, TResult> => {
+    const path = generateEndpoint(version, args);
+    return [path, init];
+};
+
+export default generateParameters;

packages/modules/services/src/people/person-photo/index.ts

@@ -0,0 +1,6 @@
+export { client, default } from './client';
+
+export { generateEndpoint } from './generate-endpoint';
+export { generateParameters } from './generate-parameters';
+
+export * from './types';