@alexisapp/leave-core 0.0.1-beta.1

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@alexisapp/leave-core",
+  "version": "0.0.1-beta.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "react-native": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./queries": {
+      "react-native": "./src/queries/index.ts",
+      "types": "./dist/queries/index.d.ts",
+      "import": "./dist/queries/index.mjs"
+    },
+    "./mutations": {
+      "react-native": "./src/mutations/index.ts",
+      "types": "./dist/mutations/index.d.ts",
+      "import": "./dist/mutations/index.mjs"
+    },
+    "./forms": {
+      "react-native": "./src/forms/index.ts",
+      "types": "./dist/forms/index.d.ts",
+      "import": "./dist/forms/index.mjs"
+    },
+    "./domain": {
+      "react-native": "./src/domain/index.ts",
+      "types": "./dist/domain/index.d.ts",
+      "import": "./dist/domain/index.mjs"
+    },
+    "./i18n": {
+      "react-native": "./src/i18n/index.ts",
+      "types": "./dist/i18n/index.d.ts",
+      "import": "./dist/i18n/index.mjs"
+    },
+    "./components": {
+      "react-native": "./src/components/index.ts",
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.mjs"
+    },
+    "./stores": {
+      "react-native": "./src/stores/index.ts",
+      "types": "./dist/stores/index.d.ts",
+      "import": "./dist/stores/index.mjs"
+    },
+    "./hooks": {
+      "react-native": "./src/hooks/index.ts",
+      "types": "./dist/hooks/index.d.ts",
+      "import": "./dist/hooks/index.mjs"
+    },
+    "./utils": {
+      "react-native": "./src/utils/index.ts",
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "codegen": "pnpm codegen:gateway && pnpm codegen:hr-core",
+    "codegen:gateway": "graphql-codegen --config src/graphql/codegen-gateway.ts",
+    "codegen:hr-core": "graphql-codegen --config src/graphql/codegen-hr-core.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@graphql-codegen/cli": "^6.0.0",
+    "@graphql-codegen/client-preset": "^4.0.0",
+    "@types/react": "^19.1.0",
+    "@parcel/watcher": "^2.5.0",
+    "@tanstack/react-query": "^5.90.21",
+    "react-error-boundary": "^5.0.0",
+    "tsup": "^8.0.0",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-error-boundary": "^5.0.0",
+    "zod": "^4.0.0"
+  },
+  "dependencies": {
+    "@graphql-typed-document-node/core": "^3.2.0",
+    "graphql": "^16.0.0",
+    "i18next": "^23.0.0",
+    "ky": "^1.0.0"
+  }
+}

package/src/client/createKyInstance.ts

@@ -0,0 +1,34 @@
+import ky, { type KyInstance } from 'ky';
+import type { ClientConfig } from './types';
+
+/**
+ * Creates a configured ky instance for GraphQL requests.
+ * No prefixUrl — full URLs are passed per-request by execute.gateway() / execute.hrCore().
+ * Auth: devToken takes precedence over getToken (§4 Auth Token Flow).
+ */
+export function createKyInstance(config: ClientConfig): KyInstance {
+  return ky.create({
+    hooks: {
+      beforeRequest: [
+        async (request) => {
+          // Dev override: hardcoded Alexis token, skip getToken()
+          if (config.devToken) {
+            request.headers.set('Authorization', `Bearer ${config.devToken}`);
+            return;
+          }
+
+          // Mobile prod: Auth0 JWT via host's getToken()
+          // Web prod: no getToken — shell BFF proxy handles auth transparently
+          if (config.getToken) {
+            const token = await config.getToken();
+            if (token) {
+              request.headers.set('Authorization', `Bearer ${token}`);
+            }
+          }
+        },
+      ],
+    },
+    timeout: 30000,
+    retry: { limit: 2, statusCodes: [408, 429, 500, 502, 503, 504] },
+  });
+}

package/src/client/execute.ts

@@ -0,0 +1,153 @@
+import { classifyError } from '../errors/classifyError';
+import { AuthError } from '../errors/AuthError';
+import { GraphQLError } from '../errors/GraphQLError';
+import { getKyInstance, getClientConfig } from './initializeClient';
+import type { TypedDocumentString as GatewayDocumentString } from '../graphql/generated-gateway/graphql';
+import type { TypedDocumentString as HrCoreDocumentString } from '../graphql/generated-hr-core/graphql';
+
+// ---------- Shared types ----------
+
+interface ExecuteBaseProps<TQuery, TVariables> {
+  url: string;
+  query: TQuery;
+  variables: TVariables extends Record<string, never> ? unknown : TVariables | undefined;
+  signal?: AbortSignal | undefined;
+}
+
+interface ExecuteProps<TQuery, TVariables> {
+  query: TQuery;
+  variables: TVariables extends Record<string, never> ? unknown : TVariables | undefined;
+  signal?: AbortSignal | undefined;
+}
+
+type ExecuteGatewayProps<TResult, TVariables> = ExecuteProps<
+  GatewayDocumentString<TResult, TVariables>,
+  TVariables
+>;
+
+type ExecuteHrCoreProps<TResult, TVariables> = ExecuteProps<
+  HrCoreDocumentString<TResult, TVariables>,
+  TVariables
+>;
+
+// ---------- Core request ----------
+
+async function executeBase<TQuery, TVariables, TResult>({
+  url,
+  query,
+  variables,
+  signal,
+}: ExecuteBaseProps<TQuery, TVariables>): Promise<TResult> {
+  const kyInstance = getKyInstance();
+  if (!kyInstance) {
+    throw new Error('GraphQL client not initialized. Call initializeClient() first.');
+  }
+
+  const response = await kyInstance
+    .post(url, {
+      json: { query, variables },
+      ...(signal != null && { signal }),
+    })
+    .json<{
+      data: TResult;
+      errors?: Array<{
+        message: string;
+        extensions?: Record<string, unknown>;
+      }>;
+    }>();
+
+  if (response.errors?.length) {
+    throw new GraphQLError(response.errors);
+  }
+
+  return response.data;
+}
+
+// ---------- Endpoint helpers ----------
+
+const GATEWAY_PATH = '/v2/graphql';
+const HR_CORE_PATH = '/graphql';
+
+function getGatewayUrl(): string {
+  const config = getClientConfig();
+  if (!config) {
+    throw new Error('GraphQL client not initialized. Call initializeClient() first.');
+  }
+  const base = config.gatewayEndpoint ?? config.endpoint;
+  return `${base}${GATEWAY_PATH}`;
+}
+
+function getHrCoreUrl(): string {
+  const config = getClientConfig();
+  if (!config) {
+    throw new Error('GraphQL client not initialized. Call initializeClient() first.');
+  }
+  return `${config.endpoint}${HR_CORE_PATH}`;
+}
+
+async function executeWithErrorHandling<TResult>(fn: () => Promise<TResult>): Promise<TResult> {
+  try {
+    return await fn();
+  } catch (error: unknown) {
+    const classified = classifyError(error);
+
+    // Auth errors (401, 403): no retry. Token freshness is the host BFF's responsibility.
+    // Mobile: calls onAuthError() → host navigates to login.
+    // Web: onAuthError is not set (no-op) — shell handles 401 redirect globally.
+    if (classified instanceof AuthError) {
+      const config = getClientConfig();
+      config?.onAuthError?.();
+      throw classified;
+    }
+
+    throw classified;
+  }
+}
+
+// ---------- Public executors ----------
+
+const executeGateway = async <TResult, TVariables>({
+  query,
+  variables,
+  signal,
+}: ExecuteGatewayProps<TResult, TVariables>): Promise<TResult> => {
+  const url = getGatewayUrl();
+  return executeWithErrorHandling(() =>
+    executeBase<GatewayDocumentString<TResult, TVariables>, TVariables, TResult>({
+      url,
+      query,
+      variables,
+      signal,
+    })
+  );
+};
+
+const executeHrCore = async <TResult, TVariables>({
+  query,
+  variables,
+  signal,
+}: ExecuteHrCoreProps<TResult, TVariables>): Promise<TResult> => {
+  const url = getHrCoreUrl();
+  return executeWithErrorHandling(() =>
+    executeBase<HrCoreDocumentString<TResult, TVariables>, TVariables, TResult>({
+      url,
+      query,
+      variables,
+      signal,
+    })
+  );
+};
+
+/**
+ * Typed GraphQL executors. Classifies all errors at this boundary (§12).
+ * Auth errors (401/403): zero retry, immediate onAuthError() callback (§4).
+ *
+ * - execute.gateway() — new leave service (default for most operations)
+ * - execute.hrCore()  — legacy HR Core (employee/policy lookups)
+ */
+export const execute = {
+  gateway: executeGateway,
+  hrCore: executeHrCore,
+} as const;
+
+export type { ExecuteGatewayProps, ExecuteHrCoreProps };

package/src/client/index.ts

@@ -0,0 +1,4 @@
+export { initializeClient } from './initializeClient';
+export { resetClient } from './resetClient';
+export { execute } from './execute';
+export type { ClientConfig } from './types';

package/src/client/initializeClient.ts

@@ -0,0 +1,48 @@
+import type { KyInstance } from 'ky';
+import type { ClientConfig } from './types';
+import { createKyInstance } from './createKyInstance';
+
+/**
+ * SINGLETON SCOPE CONSTRAINT (ADR-011):
+ * kyInstance and clientConfig are module-scoped. In a Module Federation context with shared
+ * singletons, every MF remote that imports @leave/core shares these variables. If two remotes
+ * call initializeClient() with different configs, the second call would silently overwrite.
+ *
+ * Runtime guard: initializeClient() throws if kyInstance already exists and resetClient()
+ * was not called first. This turns silent corruption into a loud error.
+ */
+let kyInstance: KyInstance | null = null;
+let clientConfig: ClientConfig | null = null;
+
+/**
+ * Creates a fresh ky instance. Throws if called twice without resetClient().
+ * Called in useEffect with resetClient() in cleanup.
+ */
+export function initializeClient(config: ClientConfig): void {
+  if (kyInstance !== null) {
+    throw new Error(
+      '[LeavePackage] initializeClient() called but client already exists. ' +
+        'Call resetClient() first. If this error appears in production, it likely means ' +
+        'two MF remotes are consuming @leave/core simultaneously — see ADR-011.'
+    );
+  }
+
+  clientConfig = config;
+  kyInstance = createKyInstance(config);
+}
+
+/** Returns current ky instance, or null if not initialized. Internal use only. */
+export function getKyInstance(): KyInstance | null {
+  return kyInstance;
+}
+
+/** Returns current client config, or null if not initialized. Internal use only. */
+export function getClientConfig(): ClientConfig | null {
+  return clientConfig;
+}
+
+/** Resets module-scoped singleton. Called by resetClient(). */
+export function _resetInternal(): void {
+  kyInstance = null;
+  clientConfig = null;
+}

package/src/client/resetClient.ts

@@ -0,0 +1,10 @@
+import { _resetInternal } from './initializeClient';
+
+/**
+ * Resets module-scoped singleton. Used in:
+ * - useEffect cleanup on unmount (prevents stale closure on MF remount)
+ * - afterEach() in tests (prevents cross-test state pollution)
+ */
+export function resetClient(): void {
+  _resetInternal();
+}

package/src/client/types.ts

@@ -0,0 +1,12 @@
+export interface ClientConfig {
+  /** Base proxy URL. Core appends /v2/graphql (gateway) and /graphql (hrCore) internally. */
+  endpoint: string;
+  /** Override base URL for gateway only (local dev with split services). Falls back to `endpoint`. */
+  gatewayEndpoint?: string | undefined;
+  /** Mobile only — returns Auth0 JWT. Web BFF handles auth transparently. */
+  getToken?: (() => Promise<string | null>) | undefined;
+  /** Mobile only — called on 401/403 before throwing. Shell handles 401 redirect on web. */
+  onAuthError?: (() => void) | undefined;
+  /** Hardcoded Alexis token for dev. Platform reads from env, core never touches process.env. */
+  devToken?: string | undefined;
+}

package/src/components/AsyncBoundary.tsx

@@ -0,0 +1,29 @@
+import { QueryErrorResetBoundary } from '@tanstack/react-query';
+import { type JSX, type ReactNode, Suspense } from 'react';
+import { ErrorBoundary, type ErrorBoundaryProps } from 'react-error-boundary';
+
+interface AsyncBoundaryProps {
+  suspenseFallback?: ReactNode;
+  errorBoundaryProps: ErrorBoundaryProps;
+  children?: ReactNode;
+}
+
+export const AsyncBoundary = ({
+  suspenseFallback,
+  errorBoundaryProps,
+  children,
+}: AsyncBoundaryProps): JSX.Element => (
+  <QueryErrorResetBoundary>
+    {({ reset }) => (
+      <ErrorBoundary
+        {...errorBoundaryProps}
+        onReset={(...args) => {
+          reset();
+          errorBoundaryProps.onReset?.(...args);
+        }}
+      >
+        <Suspense fallback={suspenseFallback}>{children}</Suspense>
+      </ErrorBoundary>
+    )}
+  </QueryErrorResetBoundary>
+);

package/src/components/index.ts

@@ -0,0 +1 @@
+export { AsyncBoundary } from './AsyncBoundary';

package/src/domain/index.ts

@@ -0,0 +1,2 @@
+// TODO: domain logic — permissions, rules, transformers, constants
+export {};

package/src/errors/AuthError.ts

@@ -0,0 +1,12 @@
+import { LeaveError } from './LeaveError';
+
+/**
+ * Authentication/authorization error — 401 or 403.
+ * Never retried. Immediately escalated via onAuthError() callback.
+ */
+export class AuthError extends LeaveError {
+  constructor(public readonly statusCode: 401 | 403) {
+    super('AUTH_ERROR', statusCode === 401 ? 'Session expired' : 'Access denied');
+    this.name = 'AuthError';
+  }
+}

package/src/errors/DomainError.ts

@@ -0,0 +1,15 @@
+import { LeaveError } from './LeaveError';
+
+/**
+ * Business rule violation returned by the server
+ * (e.g., insufficient leave balance, blackout period).
+ */
+export class DomainError extends LeaveError {
+  constructor(
+    public readonly domainCode: string,
+    message: string
+  ) {
+    super('DOMAIN_ERROR', message);
+    this.name = 'DomainError';
+  }
+}

package/src/errors/GraphQLError.ts

@@ -0,0 +1,16 @@
+import { LeaveError } from './LeaveError';
+
+/**
+ * Server returned errors[] in the GraphQL response body.
+ */
+export class GraphQLError extends LeaveError {
+  constructor(
+    public readonly errors: Array<{
+      message: string;
+      extensions?: Record<string, unknown>;
+    }>
+  ) {
+    super('GRAPHQL_ERROR', errors[0]?.message ?? 'Unknown server error');
+    this.name = 'GraphQLError';
+  }
+}

package/src/errors/LeaveError.ts

@@ -0,0 +1,13 @@
+/**
+ * Base error class for all leave management errors.
+ * All domain-specific errors extend this class.
+ */
+export class LeaveError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string
+  ) {
+    super(message);
+    this.name = 'LeaveError';
+  }
+}

package/src/errors/NetworkError.ts

@@ -0,0 +1,12 @@
+import { LeaveError } from './LeaveError';
+
+/**
+ * Fetch failed, timeout, or no connectivity.
+ * Also used for non-auth HTTP errors that reach classifyError after ky retries are exhausted.
+ */
+export class NetworkError extends LeaveError {
+  constructor(public readonly cause: unknown) {
+    super('NETWORK_ERROR', 'Unable to reach the server');
+    this.name = 'NetworkError';
+  }
+}

package/src/errors/classifyError.ts

@@ -0,0 +1,46 @@
+import { HTTPError } from 'ky';
+import { LeaveError } from './LeaveError';
+import { AuthError } from './AuthError';
+import { NetworkError } from './NetworkError';
+
+/**
+ * Classifies an unknown error into a LeaveError subclass.
+ * Idempotent — if the error is already a LeaveError, passes through unchanged.
+ *
+ * Classification order:
+ * 1. LeaveError passthrough (idempotent)
+ * 2. AbortError → ABORT_ERROR (no-op in UI — no toast, no error boundary)
+ * 3. ky HTTPError 401/403 → AuthError
+ * 4. ky HTTPError other → NetworkError (retries already exhausted by ky)
+ * 5. TypeError → NetworkError (fetch throws TypeError on DNS failure, CORS, network-down)
+ * 6. Fallback → UNKNOWN_ERROR
+ */
+export function classifyError(error: unknown): LeaveError {
+  // 1. Idempotent passthrough
+  if (error instanceof LeaveError) {
+    return error;
+  }
+
+  // 2. AbortError — host unmounted mid-request (§12b)
+  if (error instanceof DOMException && error.name === 'AbortError') {
+    return new LeaveError('ABORT_ERROR', 'Request aborted');
+  }
+
+  // 3–4. ky HTTPError
+  if (error instanceof HTTPError) {
+    const status = error.response.status;
+    if (status === 401 || status === 403) {
+      return new AuthError(status);
+    }
+    return new NetworkError(error);
+  }
+
+  // 5. TypeError — fetch failed (DNS, CORS, network-down)
+  if (error instanceof TypeError) {
+    return new NetworkError(error);
+  }
+
+  // 6. Fallback
+  const message = error instanceof Error ? error.message : 'An unexpected error occurred';
+  return new LeaveError('UNKNOWN_ERROR', message);
+}

package/src/errors/errorMessages.ts

@@ -0,0 +1,69 @@
+import { HTTPError } from 'ky';
+import { AuthError } from './AuthError';
+import { DomainError } from './DomainError';
+import { NetworkError } from './NetworkError';
+import { GraphQLError } from './GraphQLError';
+import { getLeaveI18n } from '../i18n';
+
+export enum ErrorCode {
+  UNEXPECTED_ERROR = 'UNEXPECTED_ERROR',
+  CONNECTION_FAILURE = 'CONNECTION_FAILURE',
+  BAD_REQUEST = 'BAD_REQUEST',
+  NOT_FOUND = 'NOT_FOUND',
+  SYSTEM_FAILURE = 'SYSTEM_FAILURE',
+  UNAUTHORIZED = 'UNAUTHORIZED',
+  FORBIDDEN = 'FORBIDDEN',
+}
+
+const httpStatusToErrorCode: Record<number, ErrorCode> = {
+  400: ErrorCode.BAD_REQUEST,
+  401: ErrorCode.UNAUTHORIZED,
+  403: ErrorCode.FORBIDDEN,
+  404: ErrorCode.NOT_FOUND,
+};
+
+export function getErrorCode(error: unknown): ErrorCode {
+  if (error instanceof AuthError) {
+    return error.statusCode === 401 ? ErrorCode.UNAUTHORIZED : ErrorCode.FORBIDDEN;
+  }
+  if (error instanceof NetworkError) {
+    return ErrorCode.CONNECTION_FAILURE;
+  }
+  if (error instanceof GraphQLError) {
+    return ErrorCode.SYSTEM_FAILURE;
+  }
+  // ky HTTPError (has response property with status)
+  if (error instanceof Error && 'response' in error) {
+    const status = (error as { response?: { status?: number } }).response?.status;
+    if (status != null) {
+      const mapped = httpStatusToErrorCode[status];
+      if (mapped != null) return mapped;
+      if (status >= 500) return ErrorCode.SYSTEM_FAILURE;
+    }
+  }
+  return ErrorCode.UNEXPECTED_ERROR;
+}
+
+export function isHttpError(error: unknown): error is HTTPError {
+  return error instanceof HTTPError;
+}
+
+export function isRetryable(error: unknown): boolean {
+  if (error instanceof NetworkError) return true;
+  if (error instanceof GraphQLError) return true;
+  if (error instanceof AuthError) return false;
+  if (error instanceof DomainError) return false;
+  if (error instanceof HTTPError) {
+    return error.response.status >= 500;
+  }
+  return false;
+}
+
+export function getErrorMessage(error: unknown): { title: string; description: string } {
+  const code = getErrorCode(error);
+  const t = getLeaveI18n().t;
+  return {
+    title: t(`errors.${code}.title`),
+    description: t(`errors.${code}.description`),
+  };
+}

package/src/errors/index.ts

@@ -0,0 +1,13 @@
+export { LeaveError } from './LeaveError';
+export { AuthError } from './AuthError';
+export { GraphQLError } from './GraphQLError';
+export { NetworkError } from './NetworkError';
+export { DomainError } from './DomainError';
+export { classifyError } from './classifyError';
+export {
+  ErrorCode,
+  getErrorCode,
+  isHttpError,
+  isRetryable,
+  getErrorMessage,
+} from './errorMessages';

package/src/forms/index.ts

@@ -0,0 +1,2 @@
+// TODO: Zod form schemas and formOptions() configurations
+export {};

package/src/graphql/codegen-gateway.ts

@@ -0,0 +1,26 @@
+import type { CodegenConfig } from '@graphql-codegen/cli';
+
+const config: CodegenConfig = {
+  overwrite: true,
+  schema: 'https://api-2.dev-alexishr.io/v2/graphql',
+  documents: ['./src/graphql/operations/gateway/**/*.graphql'],
+  ignoreNoDocuments: false,
+  generates: {
+    './src/graphql/generated-gateway/': {
+      preset: 'client',
+      config: {
+        documentMode: 'string',
+        strictScalars: true,
+        scalars: {
+          ID: { input: 'string', output: 'string' },
+          DateTime: 'string',
+          JSON: 'Record<string, unknown>',
+          JSONObject: 'Record<string, unknown>',
+        },
+      },
+    },
+  },
+  hooks: { afterOneFileWrite: ['prettier --write'] },
+};
+
+export default config;

package/src/graphql/codegen-hr-core.ts

@@ -0,0 +1,31 @@
+import type { CodegenConfig } from '@graphql-codegen/cli';
+
+const config: CodegenConfig = {
+  overwrite: true,
+  schema: 'https://api-2.dev-alexishr.io/graphql',
+  documents: ['./src/graphql/operations/hr-core/**/*.graphql'],
+  ignoreNoDocuments: false,
+  generates: {
+    './src/graphql/generated-hr-core/': {
+      preset: 'client',
+      config: {
+        documentMode: 'string',
+        strictScalars: true,
+        scalars: {
+          ID: { input: 'string', output: 'string' },
+          DateTime: 'string',
+          JSON: 'Record<string, unknown>',
+          JSONObject: 'Record<string, unknown>',
+          ObjectId: 'string',
+          Email: 'string',
+          Date: 'string',
+          Object: 'Record<string, unknown>',
+          Upload: 'File',
+        },
+      },
+    },
+  },
+  hooks: { afterOneFileWrite: ['prettier --write'] },
+};
+
+export default config;