@brownandroot/api 0.14.0 → 0.15.0

package/README.md

@@ -1,6 +1,6 @@
 # @brownandroot/api
 
-TypeScript client for the Brown & Root APIHub data service. Provides read-only access to company data (employees, business units, cost codes, pay types, work orders, job type/job steps) and an LLM chat endpoint powered by Azure AI Foundry.
+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.
 
 ## Installation
 
@@ -16,25 +16,156 @@ import { ApiHubClient } from '@brownandroot/api'
 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)
 })
 ```
 
-## Usage
+---
 
-### Employees
+## Employees
+
+### Fetching
 
 ```typescript
+// All employees
 const employees = await client.getEmployees()
-const dropdown = await client.getEmployeesDropdown() // { value, label }[]
+
+// 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')
+```
+
+### 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')
+```
+
+### Email → JDE lookup
+
+```typescript
 const { jde, employee } = await client.getJdeFromEmail('john@example.com')
+// jde: string | null
+// employee: Employee | null
+```
+
+### 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
+})
+
+if (employee) {
+	// identity confirmed — full Employee object returned
+} else {
+	// no employee matched these inputs
+}
+// Throws on 400 (missing fields) or 503 (not configured server-side)
+```
+
+### Employee fields
+
+```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
+}
 ```
 
-### Business Units
+---
+
+## Business Units
 
 ```typescript
 const units = await client.getBusinessUnits()
@@ -42,15 +173,25 @@ const dropdown = await client.getBusinessUnitsDropdown() // { value, label }[]
 const unit = await client.getBusinessUnit('BU001')
 ```
 
-### Cost Codes
+---
+
+## Cost Codes
 
 ```typescript
 const codes = await client.getCostcodes()
 const dropdown = await client.getCostcodesDropdown() // { value, label }[]
 const code = await client.getCostcode('CC001')
+
+// Filtered by business unit
+const dropdown = await client.getCostcodesDropdownByBu('BU001')
+
+// Filtered by business unit and pay type
+const dropdown = await client.getCostcodesDropdownByBuAndPayType('BU001', 'PT01')
 ```
 
-### Pay Types
+---
+
+## Pay Types
 
 ```typescript
 const types = await client.getPaytypes()
@@ -58,15 +199,22 @@ const dropdown = await client.getPaytypesDropdown() // { value, label, payClass
 const type = await client.getPaytype('PT001')
 ```
 
-### Work Orders
+---
+
+## Work Orders
 
 ```typescript
 const orders = await client.getWorkorders()
 const dropdown = await client.getWorkordersDropdown() // { value, label }[]
 const order = await client.getWorkorder('WO001')
+
+// Filtered by business unit
+const dropdown = await client.getWorkordersDropdownByBu('BU001')
 ```
 
-### Job Type / Job Steps
+---
+
+## Job Type / Job Steps
 
 ```typescript
 const items = await client.getJobtypejobsteps()
@@ -74,26 +222,83 @@ const dropdown = await client.getJobtypejobstepsDropdown() // { value, label }[]
 const item = await client.getJobtypejobstep('JTJS001')
 ```
 
-### LLM
+---
 
-```typescript
-// List logs
-const logs = await client.getLlmLogs()
+## LLM
+
+### Chat completion
 
-// Chat completion
+```typescript
 const result = await client.chat({
 	messages: [{ role: 'user', content: 'Summarize this document...' }],
-	source: 'my-app',
-	user: 'jane.doe',
-	function: 'summarize',
+	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
 })
+
 console.log(result.message.content)
 console.log(result.usage) // { tokensIn, tokensOut, totalTokens }
 ```
 
-## Types
+### Streaming chat
 
-The package exports interfaces for all resource types:
+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
+	source: 'my-app',
+})
+
+// Proxy to the browser, or read the SSE stream directly
+```
+
+### LLM logs
+
+```typescript
+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:
+
+```typescript
+client.clearCache()           // clear everything
+client.clearCache('/employees') // clear a specific path
+```
+
+---
+
+## Types
 
 ```typescript
 import type {
@@ -107,15 +312,21 @@ import type {
 	ChatMessage,
 	ChatRequest,
 	ChatResponse,
+	StreamChatRequest,
+	StreamChatUserContext,
+	DocumentRecord,
+	SearchResult,
 	ApiHubClientOptions,
 	DropdownOption,
 	PaytypeDropdownOption,
 } from '@brownandroot/api'
 ```
 
-## Error Handling
+---
 
-Methods throw an `Error` when the API returns a non-OK response. The error message contains the server's error detail or the HTTP status code.
+## 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.
 
 ```typescript
 try {
@@ -124,3 +335,5 @@ try {
 	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).

package/dist/index.d.ts

@@ -231,17 +231,16 @@ export declare class ApiHubClient {
     /** Search employees by home business unit (case-insensitive partial match) */
     searchByHbu(hbu: string): Promise<Employee[]>;
     /**
-     * Verify an employee's identity using the canonical identity hash.
-     * Inputs are hashed server-side and compared — no PII is stored or returned.
+     * Verify an employee's identity from name/dob/SSN inputs alone — no employee ID needed.
+     * Returns the Employee on a match, or null if no employee matches the inputs.
+     * Throws on 400 (missing fields) or 503 (not configured server-side).
      */
-    verifyIdentity(employeeId: string, inputs: {
+    verifyIdentity(inputs: {
         first3FirstName: string;
         first3LastName: string;
         dob: string;
         ssn4: string;
-    }): Promise<{
-        verified: boolean;
-    }>;
+    }): Promise<Employee | null>;
     /** List all LLM log entries (newest first) */
     getLlmLogs(): Promise<LlmLog[]>;
     /** Send a chat completion request to the LLM */

package/dist/index.js

@@ -86,21 +86,24 @@ export class ApiHubClient {
         return this.request(`/employees/search?hbu=${encodeURIComponent(hbu)}`);
     }
     /**
-     * Verify an employee's identity using the canonical identity hash.
-     * Inputs are hashed server-side and compared — no PII is stored or returned.
+     * Verify an employee's identity from name/dob/SSN inputs alone — no employee ID needed.
+     * Returns the Employee on a match, or null if no employee matches the inputs.
+     * Throws on 400 (missing fields) or 503 (not configured server-side).
      */
-    async verifyIdentity(employeeId, inputs) {
+    async verifyIdentity(inputs) {
         let res;
         try {
-            res = await fetch(`${this.baseUrl}/employees/${encodeURIComponent(employeeId)}/verify-identity`, {
+            res = await fetch(`${this.baseUrl}/employees/verify-identity`, {
                 method: 'POST',
                 headers: { 'x-api-key': this.apiKey, 'Content-Type': 'application/json' },
                 body: JSON.stringify(inputs),
             });
         }
         catch {
-            throw new Error(`APIHub unavailable: ${this.baseUrl}/employees/${employeeId}/verify-identity`);
+            throw new Error(`APIHub unavailable: ${this.baseUrl}/employees/verify-identity`);
         }
+        if (res.status === 401)
+            return null;
         if (!res.ok) {
             const body = await res.json().catch(() => null);
             const message = (body && typeof body === 'object' && 'error' in body && typeof body.error === 'string' ? body.error : null) ??

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@brownandroot/api",
-	"version": "0.14.0",
+	"version": "0.15.0",
 	"type": "module",
 	"repository": {
 		"type": "git",