@brownandroot/api 1.0.0 → 1.2.0

package/README.md

@@ -8,7 +8,271 @@ TypeScript client for the Brown & Root APIHub data service. Provides access to e
 npm install @brownandroot/api
 ```
 
-## Setup
+---
+
+## Client-Side Cache API (recommended for SvelteKit)
+
+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 and a background refresh keeps the cache warm.
+
+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.
+
+### Setup
+
+Add to your app's `.env`:
+
+```
+APIHUB_URL=https://your-apihub-url.com
+APIHUB_API_KEY=your-api-key
+```
+
+Enable remote functions in `svelte.config.js` (if not already):
+
+```js
+kit: {
+	experimental: {
+		remoteFunctions: true
+	}
+}
+```
+
+### 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.
+
+---
+
+## Remote Functions (server-side)
+
+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.
+
+```svelte
+<script lang="ts">
+  import { getEmployees } from '@brownandroot/api/employees'
+  import { getBusinessUnits } from '@brownandroot/api/businessUnits'
+
+  // 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:
+
+```typescript
+import { query } from '$app/server'
+import { getSupervisorChain } from '@brownandroot/api/employees'
+
+export const getMyManagers = query(async () => {
+	return (await getSupervisorChain('12345')).slice(0, 2)
+})
+```
+
+**Available sub-paths:** `employees`, `businessUnits`, `costcodes`, `paytypes`, `workorders`, `jobtypejobsteps`, `llm`, `rag`
+
+> `chatStream` is not available as a remote function — use `ApiHubClient` directly to proxy the SSE response.
+
+---
+
+## ApiHubClient (direct usage)
+
+For non-SvelteKit environments or when you need full control (caching, streaming):
+
+### Setup
 
 ```typescript
 import { ApiHubClient } from '@brownandroot/api'
@@ -27,36 +291,15 @@ const client = new ApiHubClient({
 ### Fetching
 
 ```typescript
-// All employees
 const employees = await client.getEmployees()
-
-// Dropdown format: { value: employeeId, label: name }[]
-const dropdown = await client.getEmployeesDropdown()
-
-// Single employee by ID — throws if not found
-const employee = await client.getEmployee('12345')
-```
-
-### Search
-
-```typescript
-// By name (case-insensitive partial match)
-const results = await client.searchByName('John')
-
-// By email (case-insensitive partial match)
-const results = await client.searchByEmail('john@example.com')
-
-// By home business unit (case-insensitive partial match)
-const results = await client.searchByHbu('TX01')
+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
 ```
 
 ### Org hierarchy
 
 ```typescript
-// All employees reporting directly to a supervisor
-const reports = await client.getBySupervisor('12345')
-
-// Full supervisor chain above an employee (excludes the employee themselves)
 const chain = await client.getSupervisorChain('12345')
 ```
 
@@ -70,21 +313,14 @@ const { jde, employee } = await client.getJdeFromEmail('john@example.com')
 
 ### Identity verification
 
-Verifies an employee's identity from name, date of birth, and last 4 of SSN alone — no employee ID needed. Returns the full employee record on a match.
-
 ```typescript
 const employee = await client.verifyIdentity({
-	first3FirstName: 'joh',    // first 3 chars of first name, case-insensitive
-	first3LastName: 'doe',     // first 3 chars of last name, case-insensitive
-	dob: '1985-03-15',         // YYYY-MM-DD
-	ssn4: '4321',              // last 4 digits of SSN
+	first3FirstName: 'joh',
+	first3LastName: 'doe',
+	dob: '1985-03-15',
+	ssn4: '4321',
 })
-
-if (employee) {
-	// identity confirmed — full Employee object returned
-} else {
-	// no employee matched these inputs
-}
+// Employee on match, null on no match
 // Throws on 400 (missing fields) or 503 (not configured server-side)
 ```
 
@@ -92,75 +328,59 @@ if (employee) {
 
 ```typescript
 interface Employee {
-	// Identity
-	employeeId: string
-	name: string | null
-	email: string | null
-	badgeNumber: string | null
-	nccerNumber: string | null
-
-	// Organization
-	company: string | null         // company code
-	businessUnitId: string | null
-	hbu: string | null             // home business unit
-	departmentCode: string | null
-	division: string | null
-	sector: string | null
-	subsector: string | null
-
-	// Contact
-	phone: string | null
-
-	// Employment
-	employementStatus: string | null
-	employeePayStatus: string | null
-	recordType: string | null
-
-	// Job
-	jobType: string | null
-	jobStep: string | null
-	jobDescription: string | null
-	workSchedule: string | null
-	shift: string | null
-
-	// Pay & compensation
-	payClass: string | null
-	payFrequency: string | null
-	payCycleCode: string | null
-	checkRouteCode: string | null
-	hourlyRate: string | null      // string — format as needed
-	annualSalary: string | null    // string — format as needed
-
-	// Tax
-	residentTaxArea: string | null
-	workTaxArea: string | null
-
-	// Benefits
-	benefitGroup: string | null
-
-	// PTO
-	topFlexPtoDate: string | null  // ISO timestamp
-	clientPtoDate: string | null   // ISO timestamp
-
-	// Security & reporting
-	securityLevel: string | null
-	reportingLevel: string | null
-
-	// Relationships
-	supervisor: string | null      // supervisor employee ID
-	mentor: string | null
-
-	// Dates
-	hireDate: string | null
-	termDate: string | null
-	adjustedServiceDate: string | null
-
-	// Metadata
-	source: string | null
-	createdAt: string | null
-	updatedAtJulian: number | null
-	updatedAt: string | null
+  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
+}
+
+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.
 ```
 
 ---
@@ -171,9 +391,6 @@ interface Employee {
 const units = await client.getBusinessUnits()
 const dropdown = await client.getBusinessUnitsDropdown() // { value, label }[]
 const unit = await client.getBusinessUnit('BU001')
-
-// Search by description (case-insensitive partial match)
-const results = await client.searchBusinessUnits('west')
 ```
 
 ---
@@ -184,15 +401,6 @@ const results = await client.searchBusinessUnits('west')
 const codes = await client.getCostcodes()
 const dropdown = await client.getCostcodesDropdown() // { value, label }[]
 const code = await client.getCostcode('CC001')
-
-// Filtered by business unit
-const buDropdown = await client.getCostcodesDropdownByBu('BU001')
-
-// Filtered by business unit and pay type
-const buPtDropdown = await client.getCostcodesDropdownByBuAndPayType('BU001', 'PT01')
-
-// Search by description or JDE cost code (case-insensitive partial match)
-const results = await client.searchCostcodes('labor')
 ```
 
 ---
@@ -203,9 +411,6 @@ const results = await client.searchCostcodes('labor')
 const types = await client.getPaytypes()
 const dropdown = await client.getPaytypesDropdown() // { value, label, payClass }[]
 const type = await client.getPaytype('PT001')
-
-// Search by description (case-insensitive partial match)
-const results = await client.searchPaytypes('regular')
 ```
 
 ---
@@ -216,12 +421,6 @@ const results = await client.searchPaytypes('regular')
 const orders = await client.getWorkorders()
 const dropdown = await client.getWorkordersDropdown() // { value, label }[]
 const order = await client.getWorkorder('WO001')
-
-// Filtered by business unit
-const buDropdown = await client.getWorkordersDropdownByBu('BU001')
-
-// Search by description or client work order ID (case-insensitive partial match)
-const results = await client.searchWorkorders('pipe')
 ```
 
 ---
@@ -243,11 +442,11 @@ const item = await client.getJobtypejobstep('JTJS001')
 ```typescript
 const result = await client.chat({
 	messages: [{ role: 'user', content: 'Summarize this document...' }],
-	source: 'my-app',    // your application name
-	user: 'jane.doe',    // user identifier for logging
-	function: 'summarize', // optional label for logging
-	temperature: 0.7,    // optional, default 0.7
-	maxTokens: 1000,     // optional
+	source: 'my-app',
+	user: 'jane.doe',
+	function: 'summarize',
+	temperature: 0.7,
+	maxTokens: 1000,
 })
 
 console.log(result.message.content)
@@ -256,17 +455,13 @@ console.log(result.usage) // { tokensIn, tokensOut, totalTokens }
 
 ### Streaming chat
 
-Returns a raw SSE `Response` for you to proxy or consume directly.
-
 ```typescript
 const response = await client.chatStream({
 	messages: [{ role: 'user', content: 'Hello' }],
 	userContext: { name: 'Jane Doe', department: 'Engineering', roles: ['admin'] },
-	useRag: true,    // optional, search document knowledge base
-	tools: ['...'],  // optional
+	useRag: true,
 	source: 'my-app',
 })
-
 // Proxy to the browser, or read the SSE stream directly
 ```
 
@@ -280,31 +475,20 @@ const logs = await client.getLlmLogs() // newest first
 
 ## Documents (RAG)
 
-Upload and search documents in the knowledge base.
-
 ```typescript
-// Upload a document (PDF or CSV)
 const doc = await client.uploadDocument('report.pdf', base64Content, 'jane.doe')
-
-// List all documents
 const docs = await client.listDocuments()
-
-// Search with a natural language query
 const results = await client.searchDocuments('overtime policy', 5)
 // results: { chunkId, content, fileName, documentType, score }[]
-
-// Delete a document and all its chunks
 await client.deleteDocument(doc.id)
 ```
 
 ---
 
-## Cache management
-
-All GET methods cache responses client-side for `cacheTtl` milliseconds (default 5 minutes). To invalidate:
+## Cache management (ApiHubClient)
 
 ```typescript
-client.clearCache()           // clear everything
+client.clearCache() // clear everything
 client.clearCache('/employees') // clear a specific path
 ```
 
@@ -332,20 +516,30 @@ import type {
 	DropdownOption,
 	PaytypeDropdownOption,
 } from '@brownandroot/api'
+
+// Filter interfaces (from cache module)
+import type {
+	EmployeeFilters,
+	WorkorderFilters,
+	CostcodeFilters,
+	PaytypeFilters,
+	BusinessUnitFilters,
+	JobtypejobstepFilters,
+} from '@brownandroot/api/cache'
 ```
 
 ---
 
 ## Error handling
 
-All methods throw an `Error` when the API returns a non-OK response. The error message contains the server's detail or the HTTP status.
+All methods throw an `Error` when the API returns a non-OK response.
 
 ```typescript
 try {
-	const emp = await client.getEmployee('99999')
+	const emp = await getEmployee('99999')
 } catch (err) {
 	console.error(err.message) // "Employee not found"
 }
 ```
 
-`verifyIdentity` is the exception — it returns `null` when no employee matches the inputs, and only throws for request errors (400, 503, network failure).
+`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,4 +1,3 @@
-export declare const getBusinessUnits: any;
-export declare const getBusinessUnitsDropdown: any;
-export declare const getBusinessUnit: any;
-export declare const searchBusinessUnits: any;
+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>;

package/dist/businessUnits.remote.js

@@ -4,4 +4,3 @@ import { getClient } from './client.js';
 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 searchBusinessUnits = query(z.string(), async (q) => getClient().searchBusinessUnits(q));