@brownandroot/api 1.2.1 → 2.0.1

package/README.md

@@ -1,31 +1,33 @@
 # @brownandroot/api
 
-TypeScript client for the Brown & Root APIHub data service. Provides access to employee, business unit, cost code, pay type, work order, job type/job step, LLM chat, and document search data.
+Unified TypeScript API for Brown & Root APIHub data.
 
 ## Installation
 
 ```bash
-npm install @brownandroot/api
+bun add @brownandroot/api
 ```
 
----
+## One Import Path
 
-## Client-Side Cache API (recommended for SvelteKit)
+Use only:
 
-The package ships a browser-side API at `@brownandroot/api/cache` that wraps every remote function with an **IndexedDB stale-while-revalidate cache**. On the first call the data is fetched from the server; on every subsequent call the cached data is returned instantly. A background refresh runs automatically when the cached data is older than **4 hours**.
+```ts
+import { employees, workorders, clearCache } from '@brownandroot/api'
+```
 
-All list and dropdown functions accept an optional filter object — every entity field is available as an optional filter key. The `q` field performs a case-insensitive partial-text match across the entity's searchable text fields.
+No domain subpath imports are required.
 
-### Setup
+## Setup
 
-Add to your app's `.env`:
+Add to your app `.env`:
 
-```
+```bash
 APIHUB_URL=https://your-apihub-url.com
 APIHUB_API_KEY=your-api-key
 ```
 
-Enable remote functions in `svelte.config.js` (if not already):
+Enable SvelteKit remote functions if needed:
 
 ```js
 kit: {
@@ -35,511 +37,135 @@ kit: {
 }
 ```
 
-### Usage
-
-```svelte
-<script lang="ts">
-  import { getWorkordersDropdown, getEmployees, clearCache } from '@brownandroot/api/cache'
-
-  // First page load: fetches from server and caches in IndexedDB.
-  // Subsequent loads: returns from IndexedDB instantly, refreshes in background.
-  const workorders = $derived(await getWorkordersDropdown({ businessUnitId: 'BU001' }))
-
-  // Multiple filters compose freely
-  const employees = $derived(await getEmployees({
-    hbu: 'TX01',
-    payClass: 'H',
-    q: 'john',
-  }))
-
-  // After a mutation, clear the affected entity so the next read re-fetches
-  async function onCreate() {
-    await createWorkorder(formData)
-    clearCache('workorders')
-  }
-</script>
-```
-
-### Filter reference
-
-All filter fields are optional. Omit the filter object entirely to return all records.
-
-#### Workorders
-
-```typescript
-import { getWorkorders, getWorkordersDropdown } from '@brownandroot/api/cache'
-
-interface WorkorderFilters {
-	businessUnitId?: string // exact match
-	costCodeId?: string // exact match
-	isActive?: boolean // exact match
-	completed?: boolean // exact match
-	area?: string // exact match
-	parentWorkOrder?: string // exact match
-	q?: string // partial match on description or clientWorkOrderId
-}
-
-// Returns Workorder[]
-const all = await getWorkorders()
-const active = await getWorkorders({ isActive: true })
-const byBu = await getWorkorders({ businessUnitId: 'BU001', isActive: true })
-const search = await getWorkorders({ q: 'pipe' })
-
-// Returns { value, label }[] — always applies isActive: true by default
-const dropdown = await getWorkordersDropdown({ businessUnitId: 'BU001' })
-```
-
-#### Employees
-
-```typescript
-import { getEmployees, getEmployeesDropdown } from '@brownandroot/api/cache'
-
-interface EmployeeFilters {
-	businessUnitId?: string // exact match
-	hbu?: string // exact match on home business unit
-	supervisor?: string // exact match on supervisor employee ID
-	payClass?: string // exact match
-	jobType?: string // exact match
-	jobStep?: string // exact match
-	sector?: string // exact match
-	division?: string // exact match
-	q?: string // partial match on name or email
-}
-
-const byHbu = await getEmployees({ hbu: 'TX01' })
-const byName = await getEmployees({ q: 'john' })
-const dropdown = await getEmployeesDropdown({ businessUnitId: 'BU001' })
-```
-
-#### Cost Codes
-
-```typescript
-import { getCostcodes, getCostcodesDropdown } from '@brownandroot/api/cache'
-
-interface CostcodeFilters {
-	businessUnitId?: string // exact match
-	isActive?: boolean // exact match
-	entryFlag?: boolean // exact match
-	payTypeCode?: string // resolves pay type → objectAccount, filters by match
-	q?: string // partial match on description or jdeCostCode
-}
-
-const byBu = await getCostcodes({ businessUnitId: 'BU001' })
-const search = await getCostcodes({ q: 'labor' })
-
-// Dropdown applies isActive: true and entryFlag: true by default,
-// and also excludes expired cost codes
-const dropdown = await getCostcodesDropdown({ businessUnitId: 'BU001' })
-const dropdownByPayType = await getCostcodesDropdown({
-	businessUnitId: 'BU001',
-	payTypeCode: 'PT01',
-})
-```
-
-> **payTypeCode cross-reference:** When `payTypeCode` is set, the filter looks up that pay type's `objectAccount` from the (also cached) pay types list and only returns cost codes whose `objectAccount` matches. If the pay type has no `objectAccount`, all cost codes pass this filter.
-
-#### Pay Types
-
-```typescript
-import { getPaytypes, getPaytypesDropdown } from '@brownandroot/api/cache'
-
-interface PaytypeFilters {
-	payClass?: string // exact match
-	category?: string // exact match
-	type?: string // exact match
-	isActive?: boolean // exact match
-	perDiemPayType?: boolean // exact match
-	q?: string // partial match on description
-}
-
-const hourly = await getPaytypes({ payClass: 'H' })
-const dropdown = await getPaytypesDropdown({ isActive: true })
-// Dropdown returns { value, label, payClass }[]
-```
-
-#### Business Units
-
-```typescript
-import { getBusinessUnits, getBusinessUnitsDropdown } from '@brownandroot/api/cache'
-
-interface BusinessUnitFilters {
-	subsector?: string // exact match
-	isActive?: boolean // exact match
-	clientId?: string // exact match
-	q?: string // partial match on description or clientDescription
-}
-
-const active = await getBusinessUnits({ isActive: true })
-const dropdown = await getBusinessUnitsDropdown({ subsector: 'Gulf Coast' })
-```
-
-#### Job Type / Job Steps
-
-```typescript
-import { getJobtypejobsteps, getJobtypejobstepsDropdown } from '@brownandroot/api/cache'
-
-interface JobtypejobstepFilters {
-	jobType?: string // exact match
-	payclass?: string // exact match
-	isActive?: boolean // exact match
-	grp?: string // exact match
-	q?: string // partial match on description, jobType, or jobStep
-}
-
-const welders = await getJobtypejobsteps({ jobType: 'WE' })
-const dropdown = await getJobtypejobstepsDropdown({ isActive: true })
-```
-
-### Single-record lookups
-
-Single-record functions always fetch fresh from the server (no IndexedDB):
-
-```typescript
-import {
-	getEmployee,
-	getSupervisorChain,
-	getJdeFromEmail,
-	verifyIdentity,
-	getWorkorder,
-	getCostcode,
-	getPaytype,
-	getBusinessUnit,
-	getJobtypejobstep,
-} from '@brownandroot/api/cache'
-
-const emp = await getEmployee('12345')
-const chain = await getSupervisorChain('12345')
-const { jde, employee } = await getJdeFromEmail('john@example.com')
-const verified = await verifyIdentity({
-	first3FirstName: 'joh',
-	first3LastName: 'doe',
-	dob: '1985-03-15',
-	ssn4: '4321',
-})
-```
-
-### Cache management
-
-```typescript
-import { clearCache } from '@brownandroot/api/cache'
-
-clearCache() // clear all entities
-clearCache('workorders') // clear a specific entity
-clearCache('employees')
-clearCache('costcodes')
-clearCache('paytypes')
-clearCache('businessUnits')
-clearCache('jobtypejobsteps')
-```
-
-Call `clearCache(entity)` immediately after any mutation that changes that entity so the next read fetches fresh data.
+## Unified Domain Contract
 
----
+Each listable domain exposes the same shape:
 
-## Remote Functions (server-side)
+- `getAll(filters?)`
+- `dropdown(filters?)`
+- `get(id)` -> returns item or `null`
 
-For SvelteKit apps that need direct server-side access without the IndexedDB layer, the package also ships ready-to-use remote functions that run on the server and read credentials from environment variables automatically.
+Domains:
 
-```svelte
-<script lang="ts">
-  import { getEmployees } from '@brownandroot/api/employees'
-  import { getBusinessUnits } from '@brownandroot/api/businessUnits'
+- `employees`
+- `workorders`
+- `costcodes`
+- `paytypes`
+- `businessUnits`
+- `jobtypejobsteps`
+- `llm`
+- `rag`
 
-  // These always fetch from the server on every call
-  const employees = $derived(await getEmployees())
-  const businessUnits = $derived(await getBusinessUnits())
-</script>
-```
-
-Or compose with your own remote functions:
+## Caching Behavior
 
-```typescript
-import { query } from '$app/server'
-import { getSupervisorChain } from '@brownandroot/api/employees'
+- Browser/client: IndexedDB stale-while-revalidate cache for `getAll` and `dropdown`
+- Server/SSR: in-memory TTL cache for `getAll` and `dropdown`
+- Single-record `get(id)` reads are fresh and return `null` when not found
+- Read failures in SSR fail open by default in unified domain APIs:
+  - list reads return `[]`
+  - single reads return `null`
+  - chain/lookup helpers return safe empty defaults
 
-export const getMyManagers = query(async () => {
-	return (await getSupervisorChain('12345')).slice(0, 2)
-})
-```
+## Error Diagnostics
 
-**Available sub-paths:** `employees`, `businessUnits`, `costcodes`, `paytypes`, `workorders`, `jobtypejobsteps`, `llm`, `rag`
+The package now throws structured `ApiHubError` instances for request-layer failures.
 
-> `chatStream` is not available as a remote function — use `ApiHubClient` directly to proxy the SSE response.
+`ApiHubError` includes:
 
----
+- `status`
+- `path`
+- `url`
+- `responseBody`
+- `retriable`
+- `service`
 
-## ApiHubClient (direct usage)
+Request layer behavior:
 
-For non-SvelteKit environments or when you need full control (caching, streaming):
+- timeout with `AbortController` (default `10000ms`)
+- retries for idempotent GETs on `429/502/503/504` (default `retryCount: 2`)
+- optional `onError` callback via `ApiHubClient` options
 
-### Setup
+Dropdown defaults:
 
-```typescript
-import { ApiHubClient } from '@brownandroot/api'
+- Domains with `isActive` automatically default `isActive: true` for `dropdown(filters?)`
+- Caller can override by passing `isActive` explicitly
 
-const client = new ApiHubClient({
-	baseUrl: 'https://your-apihub-url.com',
-	apiKey: 'your-api-key',
-	cacheTtl: 5 * 60 * 1000, // optional, default 5 minutes (0 to disable)
-})
-```
+## Examples
 
----
+### Workorders
 
-## Employees
+```ts
+import { workorders } from '@brownandroot/api'
 
-### Fetching
-
-```typescript
-const employees = await client.getEmployees()
-const dropdown = await client.getEmployeesDropdown() // { value: employeeId, label: name }[]
-const employee = await client.getEmployee('12345') // throws if not found
-const employeePrivileged = await client.getEmployeePrivileged('12345') // includes hourlyRate and annualSalary
+const rows = await workorders.getAll({ businessUnitId: 'BU001' })
+const options = await workorders.dropdown({ businessUnitId: 'BU001' })
+const one = await workorders.get('WO001') // Workorder | null
 ```
 
-### Org hierarchy
-
-```typescript
-const chain = await client.getSupervisorChain('12345')
-```
+### Employees
 
-### Email → JDE lookup
+```ts
+import { employees } from '@brownandroot/api'
 
-```typescript
-const { jde, employee } = await client.getJdeFromEmail('john@example.com')
-// jde: string | null
-// employee: Employee | null
-```
+const crew = await employees.getAll({ hbu: 'TX01', q: 'john' })
+const list = await employees.dropdown({ businessUnitId: 'BU001' })
+const emp = await employees.get('12345')
 
-### Identity verification
-
-```typescript
-const employee = await client.verifyIdentity({
+const privileged = await employees.getPrivileged('12345')
+const chain = await employees.getSupervisorChain('12345')
+const jde = await employees.getJdeFromEmail('john@example.com')
+const verified = await employees.verifyIdentity({
 	first3FirstName: 'joh',
 	first3LastName: 'doe',
 	dob: '1985-03-15',
 	ssn4: '4321',
 })
-// Employee on match, null on no match
-// Throws on 400 (missing fields) or 503 (not configured server-side)
 ```
 
-### Employee fields
-
-```typescript
-interface Employee {
-  employeeId: string
-  name: string | null
-  email: string | null
-  personalEmail: string | null
-  clientEmail: string | null
-  workEmail: string | null
-  badgeNumber: string | null
-  nccerNumber: string | null
-  company: string | null
-  businessUnitId: string | null
-  hbu: string | null
-  departmentCode: string | null
-  division: string | null
-  sector: string | null
-  subsector: string | null
-  phone: string | null
-  employementStatus: string | null
-  employeePayStatus: string | null
-  recordType: string | null
-  jobType: string | null
-  jobStep: string | null
-  jobDescription: string | null
-  workSchedule: string | null
-  shift: string | null
-  payClass: string | null
-  payFrequency: string | null
-  payCycleCode: string | null
-  checkRouteCode: string | null
-  residentTaxArea: string | null
-  workTaxArea: string | null
-  benefitGroup: string | null
-  topFlexPtoDate: string | null
-  clientPtoDate: string | null
-  securityLevel: string | null
-  reportingLevel: string | null
-  supervisor: string | null
-  mentor: string | null
-  hireDate: string | null
-  termDate: string | null
-  adjustedServiceDate: string | null
-  identityHash: string | null
-  source: string | null
-  createdAt: string | null
-  updatedAtJulian: number | null
-  updatedAt: string | null
-}
+### LLM and RAG
 
-interface EmployeePrivileged extends Employee {
-  hourlyRate: string | null
-  annualSalary: string | null
-}
-
-getEmployees, getEmployee, employee searches, getJdeFromEmail, and verifyIdentity all return the public Employee shape (without compensation fields). Use getEmployeePrivileged when compensation fields are required.
-```
-
----
-
-## Business Units
-
-```typescript
-const units = await client.getBusinessUnits()
-const dropdown = await client.getBusinessUnitsDropdown() // { value, label }[]
-const unit = await client.getBusinessUnit('BU001')
-```
-
----
-
-## Cost Codes
-
-```typescript
-const codes = await client.getCostcodes()
-const dropdown = await client.getCostcodesDropdown() // { value, label }[]
-const code = await client.getCostcode('CC001')
-```
-
----
-
-## Pay Types
-
-```typescript
-const types = await client.getPaytypes()
-const dropdown = await client.getPaytypesDropdown() // { value, label, payClass }[]
-const type = await client.getPaytype('PT001')
-```
+```ts
+import { llm, rag } from '@brownandroot/api'
 
----
-
-## Work Orders
-
-```typescript
-const orders = await client.getWorkorders()
-const dropdown = await client.getWorkordersDropdown() // { value, label }[]
-const order = await client.getWorkorder('WO001')
-```
-
----
-
-## Job Type / Job Steps
-
-```typescript
-const items = await client.getJobtypejobsteps()
-const dropdown = await client.getJobtypejobstepsDropdown() // { value, label }[]
-const item = await client.getJobtypejobstep('JTJS001')
-```
-
----
-
-## LLM
-
-### Chat completion
-
-```typescript
-const result = await client.chat({
-	messages: [{ role: 'user', content: 'Summarize this document...' }],
+const logs = await llm.getLogs()
+const chat = await llm.chat({
+	messages: [{ role: 'user', content: 'Summarize this document.' }],
 	source: 'my-app',
 	user: 'jane.doe',
-	function: 'summarize',
-	temperature: 0.7,
-	maxTokens: 1000,
-})
-
-console.log(result.message.content)
-console.log(result.usage) // { tokensIn, tokensOut, totalTokens }
-```
-
-### Streaming chat
-
-```typescript
-const response = await client.chatStream({
-	messages: [{ role: 'user', content: 'Hello' }],
-	userContext: { name: 'Jane Doe', department: 'Engineering', roles: ['admin'] },
-	useRag: true,
-	source: 'my-app',
+	enableRag: true,
 })
-// Proxy to the browser, or read the SSE stream directly
-```
 
-### LLM logs
-
-```typescript
-const logs = await client.getLlmLogs() // newest first
+const docs = await rag.list()
+const results = await rag.search({ query: 'overtime policy', topK: 5 })
 ```
 
----
-
-## Documents (RAG)
+`llm.chat` RAG flags:
 
-```typescript
-const doc = await client.uploadDocument('report.pdf', base64Content, 'jane.doe')
-const docs = await client.listDocuments()
-const results = await client.searchDocuments('overtime policy', 5)
-// results: { chunkId, content, fileName, documentType, score }[]
-await client.deleteDocument(doc.id)
-```
+- `enableRag: true` tells the backend to enrich the chat prompt with retrieved document context before generating a response.
+- `enableRag: false` (or omitted) sends a normal chat request without forcing retrieval augmentation.
+- `enableRag` is the single supported parameter for toggling default tools/RAG retrieval.
 
----
+## Cache Management
 
-## Cache management (ApiHubClient)
+```ts
+import { clearCache } from '@brownandroot/api'
 
-```typescript
-client.clearCache() // clear everything
-client.clearCache('/employees') // clear a specific path
+clearCache()
+clearCache('workorders')
+clearCache('employees')
 ```
 
----
-
-## Types
-
-```typescript
-import type {
-	Employee,
-	BusinessUnit,
-	Costcode,
-	Paytype,
-	Workorder,
-	Jobtypejobstep,
-	LlmLog,
-	ChatMessage,
-	ChatRequest,
-	ChatResponse,
-	StreamChatRequest,
-	StreamChatUserContext,
-	DocumentRecord,
-	SearchResult,
-	ApiHubClientOptions,
-	DropdownOption,
-	PaytypeDropdownOption,
-} from '@brownandroot/api'
-
-// Filter interfaces (from cache module)
-import type {
-	EmployeeFilters,
-	WorkorderFilters,
-	CostcodeFilters,
-	PaytypeFilters,
-	BusinessUnitFilters,
-	JobtypejobstepFilters,
-} from '@brownandroot/api/cache'
-```
+Call `clearCache(entity)` after mutations so next reads fetch fresh data.
 
----
+## Advanced Direct Client
 
-## Error handling
+`ApiHubClient` is still available for advanced usage (streaming/proxy control/custom behavior):
 
-All methods throw an `Error` when the API returns a non-OK response.
+```ts
+import { ApiHubClient } from '@brownandroot/api'
 
-```typescript
-try {
-	const emp = await getEmployee('99999')
-} catch (err) {
-	console.error(err.message) // "Employee not found"
-}
+const client = new ApiHubClient({
+	baseUrl: process.env.APIHUB_URL!,
+	apiKey: process.env.APIHUB_API_KEY!,
+})
 ```
-
-`verifyIdentity` returns `null` when no employee matches the inputs, and only throws for request errors (400, 503, network failure).

package/dist/businessUnits.remote.d.ts

@@ -1,3 +1,3 @@
 export declare const getBusinessUnits: import("@sveltejs/kit").RemoteQueryFunction<void, import("./index.js").BusinessUnit[]>;
 export declare const getBusinessUnitsDropdown: import("@sveltejs/kit").RemoteQueryFunction<void, import("./index.js").DropdownOption[]>;
-export declare const getBusinessUnit: import("@sveltejs/kit").RemoteQueryFunction<string, import("./index.js").BusinessUnit>;
+export declare const getBusinessUnit: import("@sveltejs/kit").RemoteQueryFunction<string, import("./index.js").BusinessUnit | null>;

package/dist/businessUnits.remote.js

@@ -1,6 +1,21 @@
 import { query } from '$app/server';
 import { z } from 'zod';
 import { getClient } from './client.js';
+function isNotFoundError(error) {
+    if (!(error instanceof Error))
+        return false;
+    return /not found/i.test(error.message);
+}
+async function asNullable(fetcher) {
+    try {
+        return await fetcher();
+    }
+    catch (error) {
+        if (isNotFoundError(error))
+            return null;
+        throw error;
+    }
+}
 export const getBusinessUnits = query(async () => getClient().getBusinessUnits());
 export const getBusinessUnitsDropdown = query(async () => getClient().getBusinessUnitsDropdown());
-export const getBusinessUnit = query(z.string(), async (id) => getClient().getBusinessUnit(id));
+export const getBusinessUnit = query(z.string(), async (id) => asNullable(() => getClient().getBusinessUnit(id)));