@rytass/bpm-core-client 0.3.0 → 0.5.0

package/src/lib/graphql-client.ts

@@ -0,0 +1,128 @@
+import {
+  readBPMClientConfig,
+  readBPMConfiguredHeaders,
+  resolveBPMFetch,
+} from './client-config';
+
+const LOCAL_GRAPHQL_ENDPOINT = 'http://localhost:17603/graphql';
+const SAME_ORIGIN_GRAPHQL_ENDPOINT = '/graphql';
+
+interface GraphQlError {
+  readonly message: string;
+}
+
+interface GraphQlResponse<TData> {
+  readonly data?: TData;
+  readonly errors?: readonly GraphQlError[];
+}
+
+/**
+ * Sends a single GraphQL operation to the BPM host and returns the typed data.
+ *
+ * Uses the standard Fetch API with `credentials: 'include'`, so any
+ * HTTP-only session cookie issued by the host's `POST /auth/login` endpoint
+ * flows back automatically on subsequent calls.
+ *
+ * The endpoint URL is resolved by {@link readGraphQlEndpoint} — set
+ * `NEXT_PUBLIC_API_URL` to override the default localhost / same-origin
+ * resolution.
+ *
+ * Throws an `Error` when the HTTP response is non-2xx, when the GraphQL
+ * payload carries an `errors` array, or when the response has no `data`
+ * field.
+ *
+ * @typeParam TData - Shape of the `data` field for the operation.
+ * @param query - GraphQL operation document (query or mutation source).
+ * @param variables - Variables passed to the GraphQL operation.
+ *
+ * @example
+ * ```ts
+ * interface PingData { readonly memberCount: number; }
+ * const data = await requestGraphQl<PingData>('query Ping { memberCount }');
+ * console.log(data.memberCount);
+ * ```
+ */
+export async function requestGraphQl<TData>(
+  query: string,
+  variables?: Readonly<Record<string, unknown>>,
+): Promise<TData> {
+  const fetchImpl = resolveBPMFetch();
+  const response = await fetchImpl(readGraphQlEndpoint(), {
+    body: JSON.stringify({ query, variables }),
+    credentials: 'include',
+    headers: buildGraphQlHeaders(),
+    method: 'POST',
+  });
+
+  if (!response.ok) {
+    throw new Error(`GraphQL request failed with HTTP ${response.status}`);
+  }
+
+  const payload = (await response.json()) as GraphQlResponse<TData>;
+
+  if (payload.errors?.length) {
+    throw new Error(payload.errors.map((error) => error.message).join('; '));
+  }
+
+  if (!payload.data) {
+    throw new Error('GraphQL response did not include data');
+  }
+
+  return payload.data;
+}
+
+/**
+ * Resolves the GraphQL endpoint URL used by {@link requestGraphQl}.
+ *
+ * Resolution order:
+ * 1. `process.env.NEXT_PUBLIC_API_URL` if non-empty.
+ * 2. `http://localhost:17603/graphql` when the browser is on
+ *    `localhost` / `127.0.0.1`.
+ * 3. Same-origin `/graphql` for any other hostname (and for non-browser
+ *    runtimes such as Node SSR).
+ */
+export function readGraphQlEndpoint(): string {
+  const configured = readBPMClientConfig().baseUrl?.trim();
+  if (configured) {
+    return configured.endsWith('/graphql')
+      ? configured
+      : `${configured.replace(/\/$/, '')}/graphql`;
+  }
+  return (
+    readOptionalPublicEnvValue(process.env.NEXT_PUBLIC_API_URL) ??
+    resolveDefaultGraphQlEndpoint(readBrowserHostname())
+  );
+}
+
+/**
+ * Pure helper used by {@link readGraphQlEndpoint}.
+ *
+ * Exposed mainly for tests and for hosts that want to derive their own
+ * endpoint URLs without coupling to environment variables.
+ */
+export function resolveDefaultGraphQlEndpoint(
+  hostname: string | null,
+): string {
+  return isLocalHost(hostname)
+    ? LOCAL_GRAPHQL_ENDPOINT
+    : SAME_ORIGIN_GRAPHQL_ENDPOINT;
+}
+
+function buildGraphQlHeaders(): Readonly<Record<string, string>> {
+  return {
+    ...readBPMConfiguredHeaders(),
+    'Content-Type': 'application/json',
+  };
+}
+
+function readOptionalPublicEnvValue(value: string | undefined): string | null {
+  return value?.trim() || null;
+}
+
+function readBrowserHostname(): string | null {
+  return typeof window === 'undefined' ? null : window.location.hostname;
+}
+
+function isLocalHost(hostname: string | null): boolean {
+  return hostname === 'localhost' || hostname === '127.0.0.1';
+}

package/src/lib/member-api.ts

@@ -0,0 +1,129 @@
+import { requestGraphQl } from './graphql-client';
+
+/**
+ * Member profile record exposed by the BPM identity GraphQL surface.
+ *
+ * `customFieldsJson` is a stringified JSON blob — BPM does not impose a
+ * schema on host-side member metadata. Consumers parse it according to
+ * their own host conventions.
+ */
+export interface MemberProfileRecord {
+  readonly customFieldsJson: string;
+  readonly email: string;
+  readonly memberId: string;
+  readonly name: string;
+}
+
+/**
+ * A paginated slice of the host member directory, returned by
+ * {@link listMemberDirectoryPage}.
+ */
+export interface MemberDirectoryPage {
+  readonly members: readonly MemberProfileRecord[];
+  readonly totalCount: number;
+}
+
+interface MembersQueryData {
+  readonly members: readonly MemberProfileRecord[];
+}
+
+interface SearchMembersQueryData {
+  readonly searchMembers: readonly MemberProfileRecord[];
+}
+
+interface MemberDirectoryPageQueryData extends SearchMembersQueryData {
+  readonly memberCount: number;
+}
+
+/**
+ * Resolves a set of `memberId`s into full member profile records by hitting
+ * BPM's `members(memberIds: [String!]!)` GraphQL query, which in turn calls
+ * the host-provided `BPMMemberResolver.resolveMany`.
+ *
+ * Returns an empty array when given an empty input — does not make a
+ * network call in that case.
+ */
+export async function resolveMembers(
+  memberIds: readonly string[],
+): Promise<readonly MemberProfileRecord[]> {
+  if (!memberIds.length) {
+    return [];
+  }
+
+  const data = await requestGraphQl<MembersQueryData>(
+    `query AdminMembers($memberIds: [String!]!) {
+      members(memberIds: $memberIds) {
+        customFieldsJson
+        email
+        memberId
+        name
+      }
+    }`,
+    { memberIds },
+  );
+
+  return data.members;
+}
+
+/**
+ * Free-text search over the host's member directory through BPM's
+ * `searchMembers(searchText: String!)` query. The matching strategy is
+ * defined by the host's `BPMMemberResolver.search` implementation.
+ */
+export async function searchMembers(
+  searchText: string,
+): Promise<readonly MemberProfileRecord[]> {
+  const data = await requestGraphQl<SearchMembersQueryData>(
+    `query AdminSearchMembers($searchText: String!) {
+      searchMembers(searchText: $searchText) {
+        customFieldsJson
+        email
+        memberId
+        name
+      }
+    }`,
+    { searchText },
+  );
+
+  return data.searchMembers;
+}
+
+/**
+ * Reads a single page of the member directory (search + total count in a
+ * single GraphQL roundtrip).
+ *
+ * @param page - 1-based page index.
+ * @param pageSize - Items per page.
+ * @param searchText - Optional free-text filter; empty string returns all.
+ */
+export async function listMemberDirectoryPage({
+  page,
+  pageSize,
+  searchText = '',
+}: {
+  readonly page: number;
+  readonly pageSize: number;
+  readonly searchText?: string;
+}): Promise<MemberDirectoryPage> {
+  const data = await requestGraphQl<MemberDirectoryPageQueryData>(
+    `query AdminMemberDirectoryPage(
+      $page: Int
+      $pageSize: Int
+      $searchText: String!
+    ) {
+      searchMembers(page: $page, pageSize: $pageSize, searchText: $searchText) {
+        customFieldsJson
+        email
+        memberId
+        name
+      }
+      memberCount(searchText: $searchText)
+    }`,
+    { page, pageSize, searchText },
+  );
+
+  return {
+    members: data.searchMembers,
+    totalCount: data.memberCount,
+  };
+}

package/src/lib/organization/organization-api.spec.ts

@@ -0,0 +1,90 @@
+import { createOrgUnit, deleteOrgUnit } from './organization-api';
+
+interface CapturedRequest {
+  readonly query: string;
+  readonly variables?: Readonly<Record<string, unknown>>;
+}
+
+function installFetchMock<TData>(payload: TData): {
+  readonly capture: () => CapturedRequest;
+  readonly restore: () => void;
+} {
+  const originalFetch = global.fetch;
+  const fetchMock = jest.fn<
+    Promise<Response>,
+    [RequestInfo | URL, RequestInit?]
+  >();
+  fetchMock.mockImplementation(
+    async () =>
+      new Response(JSON.stringify({ data: payload }), {
+        headers: { 'Content-Type': 'application/json' },
+        status: 200,
+      }),
+  );
+  (global as { fetch: typeof fetch }).fetch =
+    fetchMock as unknown as typeof fetch;
+
+  return {
+    capture: (): CapturedRequest => {
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      const init = fetchMock.mock.calls[0]?.[1];
+      return JSON.parse(String(init?.body ?? '{}')) as CapturedRequest;
+    },
+    restore: (): void => {
+      (global as { fetch: typeof fetch }).fetch = originalFetch;
+    },
+  };
+}
+
+describe('@rytass/bpm-core-client/organization', () => {
+  describe('createOrgUnit', () => {
+    it('forwards the input under the GraphQL "input" variable', async (): Promise<void> => {
+      const input = {
+        code: 'ENG',
+        metadataJson: '{}',
+        name: 'Engineering',
+        parentId: null,
+        type: 'DEPARTMENT' as const,
+      };
+      const harness = installFetchMock({
+        createOrgUnit: {
+          code: 'ENG',
+          createdAt: '2026-05-26T00:00:00.000Z',
+          deletedAt: null,
+          id: 'unit-1',
+          name: 'Engineering',
+          parentId: null,
+          path: 'unit-1',
+          type: 'DEPARTMENT',
+          updatedAt: '2026-05-26T00:00:00.000Z',
+        },
+      });
+      try {
+        const result = await createOrgUnit(input);
+        const request = harness.capture();
+
+        expect(request.query).toContain('mutation AdminCreateOrgUnit');
+        expect(request.variables).toEqual({ input });
+        expect(result.id).toBe('unit-1');
+      } finally {
+        harness.restore();
+      }
+    });
+  });
+
+  describe('deleteOrgUnit', () => {
+    it('passes the id and returns the boolean payload', async (): Promise<void> => {
+      const harness = installFetchMock({ deleteOrgUnit: true });
+      try {
+        const result = await deleteOrgUnit('unit-1');
+        const request = harness.capture();
+
+        expect(request.query).toContain('deleteOrgUnit');
+        expect(request.variables).toEqual({ id: 'unit-1' });
+        expect(result).toBe(true);
+      } finally {
+        harness.restore();
+      }
+    });
+  });
+});