@alexisapp/leave-core 0.0.1-beta.1

package/README.md

@@ -0,0 +1,260 @@
+# @leave/core
+
+Platform-agnostic core package for the leave management feature. Contains the GraphQL client, error handling, query/mutation factories, form schemas, domain logic, i18n, and stores.
+
+This is a leaf package — it has zero platform dependencies (`react-native`, `react-dom` are forbidden).
+
+## Setup
+
+```bash
+pnpm install
+pnpm build       # tsup — produces dist/ with ESM (.mjs) + declarations (.d.ts)
+pnpm clean       # rm -rf dist
+pnpm typecheck   # tsc --noEmit
+pnpm lint        # eslint src/
+```
+
+## Build
+
+`pnpm build` runs tsup which produces ESM output (`.mjs`) and TypeScript declarations (`.d.ts`) for all subpath exports into `dist/`.
+
+Dual-resolution strategy:
+
+- **Metro (React Native):** resolves the `react-native` condition → raw `.ts` in `src/` — Metro transpiles at build time
+- **Vite (Web):** resolves the `import` condition → pre-built `.mjs` in `dist/`
+
+## Public API
+
+### Client Lifecycle
+
+```typescript
+import { initializeClient, resetClient, execute } from '@leave/core';
+import type { ClientConfig, GraphQLEndpoints } from '@leave/core';
+```
+
+#### `initializeClient(config: ClientConfig): void`
+
+Creates a module-scoped ky instance configured for GraphQL requests. Must be called before any `execute` call. Throws if called twice without `resetClient()` first (singleton guard — see ADR-011).
+
+#### `resetClient(): void`
+
+Resets the module-scoped singleton to `null`. Call in `useEffect` cleanup on unmount (prevents stale closure on MF remount) and in `afterEach()` in tests.
+
+#### `execute.gateway<TResult, TVariables>({ query, variables, signal? }): Promise<TResult>`
+
+Sends a GraphQL request to the gateway service (new leave operations). `query` is a `TypedDocumentString` from `generated-gateway/` — `TResult` and `TVariables` are inferred from it. Classifies all errors at this boundary. Auth errors (401/403) trigger `onAuthError()` callback, then throw — zero retry.
+
+```typescript
+// Types are inferred from the document — no manual generics needed
+const data = await execute.gateway({
+  query: ListLeaveSelfCertifiedDocument,
+  variables: { filters: { ... } },
+  signal,
+});
+```
+
+#### `execute.hrCore<TResult, TVariables>({ query, variables, signal? }): Promise<TResult>`
+
+Same as `execute.gateway` but targets HR Core service (legacy employee/policy lookups). `query` is a `TypedDocumentString` from `generated-hr-core/`.
+
+### Types
+
+#### `ClientConfig`
+
+| Property      | Type                            | Required | Description                                               |
+| ------------- | ------------------------------- | -------- | --------------------------------------------------------- |
+| `endpoints`   | `GraphQLEndpoints`              | Yes      | Fully resolved GraphQL endpoint URLs                      |
+| `getToken`    | `() => Promise<string \| null>` | No       | Mobile only — returns Auth0 JWT                           |
+| `onAuthError` | `() => void`                    | No       | Mobile only — called on 401/403 before throwing           |
+| `devToken`    | `string`                        | No       | Hardcoded token for dev. Takes precedence over `getToken` |
+
+#### `GraphQLEndpoints`
+
+| Property  | Type     | Description                          |
+| --------- | -------- | ------------------------------------ |
+| `gateway` | `string` | Full URL for gateway GraphQL service |
+| `hrCore`  | `string` | Full URL for HR Core GraphQL service |
+
+### Error Classes
+
+| Class          | Code            | Description                                         |
+| -------------- | --------------- | --------------------------------------------------- |
+| `LeaveError`   | varies          | Base class. All domain errors extend this.          |
+| `AuthError`    | `AUTH_ERROR`    | 401/403. Never retried. Triggers `onAuthError()`.   |
+| `GraphQLError` | `GRAPHQL_ERROR` | Server returned `errors[]` in the GraphQL response. |
+| `NetworkError` | `NETWORK_ERROR` | Fetch failed, timeout, no connectivity.             |
+| `DomainError`  | `DOMAIN_ERROR`  | Business rule violation from server.                |
+
+All errors are classified via `classifyError()` at the `execute` boundary — consumers catch typed `LeaveError` subclasses. Classification is idempotent (passing a `LeaveError` through returns it unchanged). `AbortError` (host unmounts mid-request) is classified as `ABORT_ERROR` — a no-op in the UI (no toast, no error boundary).
+
+### Error Code Mapping
+
+`ErrorCode` enum and `getErrorCode(error)` provide consumer-facing error classification for UI messages:
+
+```typescript
+import { ErrorCode, getErrorCode } from '@leave/core';
+
+const code = getErrorCode(error); // e.g. ErrorCode.CONNECTION_FAILURE
+```
+
+Platforms use `getErrorCode()` to map errors to i18n-keyed display messages. Core provides the enum and classification; platforms provide the translations.
+
+### Error Helpers
+
+```typescript
+import { isRetryable, isHttpError, getErrorMessage } from '@leave/core';
+```
+
+- `isRetryable(error: unknown): boolean` — `true` for `NetworkError`, `GraphQLError`, 5xx HTTP; `false` for `AuthError`, `DomainError`
+- `isHttpError(error: unknown): error is HTTPError` — type guard for ky's `HTTPError`
+- `getErrorMessage(error: unknown): { title: string; description: string }` — returns i18n-localized error title and description using `ErrorCode` mapping
+
+### AsyncBoundary
+
+```typescript
+import { AsyncBoundary } from '@leave/core/components';
+```
+
+Composable boundary combining `QueryErrorResetBoundary` + `ErrorBoundary` (`react-error-boundary`) + `Suspense`. Platform packages provide their own `fallbackRender`.
+
+```typescript
+<AsyncBoundary
+  suspenseFallback={<LoadingSpinner />}
+  errorBoundaryProps={{
+    fallbackRender: ({ error, resetErrorBoundary }) => (
+      <MyErrorFallback error={error} onRetry={resetErrorBoundary} />
+    ),
+  }}
+>
+  <MyDataComponent />
+</AsyncBoundary>
+```
+
+The `onReset` handler automatically calls `QueryErrorResetBoundary.reset()` so TanStack Query retries failed queries on retry.
+
+## GraphQL Codegen
+
+Two separate GraphQL services require two codegen configs:
+
+| Service     | Endpoint      | Codegen Config       | Generated Output     | Entities                                             |
+| ----------- | ------------- | -------------------- | -------------------- | ---------------------------------------------------- |
+| **Gateway** | `/v2/graphql` | `codegen-gateway.ts` | `generated-gateway/` | LeaveSelfCertified, LeaveChange, SelfCertifiedPolicy |
+| **HR Core** | `/graphql`    | `codegen-hr-core.ts` | `generated-hr-core/` | Leave, Employee, Policy, LeaveBalance                |
+
+### Commands
+
+```bash
+pnpm codegen            # Run both configs sequentially
+pnpm codegen:gateway    # Generate gateway types only
+pnpm codegen:hr-core    # Generate HR Core types only
+```
+
+### Schema Source
+
+Schemas are introspected from remote API endpoints at codegen time — no local schema files are stored in the repo. This matches the salary-review-ui pattern.
+
+- Gateway: `https://api-2.dev-alexishr.io/v2/graphql`
+- HR Core: `https://api-2.dev-alexishr.io/graphql`
+
+To force a fresh introspection (e.g. after API schema changes): `turbo codegen --force`
+
+### Operation Structure
+
+```
+src/graphql/operations/
+├── gateway/                    # Operations for execute.gateway()
+│   ├── leave-self-certified/   # queries.graphql, mutations.graphql
+│   ├── leave-change/           # queries.graphql, mutations.graphql
+│   └── self-certified-policy/  # queries.graphql
+└── hr-core/                    # Operations for execute.hrCore()
+    ├── leave/                  # queries.graphql, mutations.graphql
+    ├── policy/                 # queries.graphql
+    └── employee/               # queries.graphql
+```
+
+### Generated Output
+
+`generated-gateway/` and `generated-hr-core/` — **never edit these files manually**. They are overwritten by codegen.
+
+Uses `documentMode: 'string'` because `execute()` takes `document: string` (not AST). All document constants are `TypedDocumentString` instances that serialize to string.
+
+### Endpoint-to-Domain Mapping
+
+| Operation                                       | Executor          | Why                                   |
+| ----------------------------------------------- | ----------------- | ------------------------------------- |
+| getLeave, listLeave, createLeave, updateLeave   | `execute.hrCore`  | Standard leave CRUD in HR Core        |
+| getEmployeeVacationBalance, listVacationBalance | `execute.hrCore`  | Balance data in HR Core               |
+| getEmployee                                     | `execute.hrCore`  | Employee data in HR Core              |
+| getLeavePolicy, listLeavePolicies               | `execute.hrCore`  | Leave policies in HR Core             |
+| getLeaveSelfCertified, create/update            | `execute.gateway` | New self-certified service on gateway |
+| getLeaveChange, leaveChangeCreate               | `execute.gateway` | New change-request service on gateway |
+| getLeaveSelfCertifiedPolicy                     | `execute.gateway` | Self-certified policy on gateway      |
+
+## Query Factories
+
+Import from `@leave/core/queries`. Pattern matches salary-review-ui (`officesQueries`, `employeesQueries`).
+
+Four factories with cascading keys and embedded `queryOptions` (ADR-014):
+
+| Factory           | Root key (`all`) | Domains covered                                           |
+| ----------------- | ---------------- | --------------------------------------------------------- |
+| `leaveQueries`    | `['leave']`      | Leave CRUD, balance, approvals, self-certified, time bank |
+| `policyQueries`   | `['policy']`     | Leave policies, self-certified policies, leave types      |
+| `employeeQueries` | `['employee']`   | Employee, employment, work week, holidays                 |
+| `settingsQueries` | `['settings']`   | Time-off settings                                         |
+
+Each factory uses a cascading key hierarchy — every level spreads the parent:
+
+```typescript
+import { leaveQueries } from '@leave/core/queries';
+
+// Key-only levels (for invalidation targeting)
+leaveQueries.all              // ['leave']
+leaveQueries.lists()          // [...all, 'list']
+leaveQueries.details()        // [...all, 'detail']
+
+// Leaf levels return queryOptions() with embedded queryFn
+leaveQueries.list(variables?) // queryOptions({ queryKey: [...lists(), variables], queryFn: ... })
+leaveQueries.detail(id)       // queryOptions({ queryKey: [...details(), id], queryFn: ... })
+
+// Usage with TanStack Query
+const { data } = useQuery(leaveQueries.list({ filters: { status: 'PENDING' } }));
+const { data } = useQuery(leaveQueries.detail(leaveId));
+
+// Nuclear invalidation — wipes all leave queries
+queryClient.invalidateQueries({ queryKey: leaveQueries.all });
+```
+
+All `queryFn` implementations pass `{ signal }` to `execute` for request cancellation on component unmount.
+
+## Subpath Exports
+
+| Subpath        | Purpose                                                                     |
+| -------------- | --------------------------------------------------------------------------- |
+| `@leave/core`  | Client lifecycle (`initializeClient`, `resetClient`, `execute`)             |
+| `./queries`    | TanStack Query `queryOptions` factories                                     |
+| `./mutations`  | Mutation wrappers (callback-based)                                          |
+| `./forms`      | TanStack Form + Zod form schemas                                            |
+| `./domain`     | Business rules, permissions, types                                          |
+| `./i18n`       | i18next instance + locale resources                                         |
+| `./components` | `AsyncBoundary` (react-error-boundary + Suspense + QueryErrorResetBoundary) |
+| `./stores`     | Zustand stores                                                              |
+
+Metro (React Native) resolves raw `.ts` via the `react-native` condition. Bundler/Node resolves compiled `dist/`.
+
+## Peer Dependencies
+
+| Package                 | Range                  |
+| ----------------------- | ---------------------- |
+| `react`                 | `^18.0.0 \|\| ^19.0.0` |
+| `@tanstack/react-query` | `^5.0.0`               |
+| `react-error-boundary`  | `^5.0.0`               |
+| `zod`                   | `^4.0.0`               |
+
+## Dependencies
+
+| Package   | Range     | Purpose                      |
+| --------- | --------- | ---------------------------- |
+| `ky`      | `^1.0.0`  | HTTP client (timeout, retry) |
+| `i18next` | `^23.0.0` | Internationalization         |
+| `graphql` | `^16.0.0` | GraphQL utilities            |