VendorService
Service for creating, searching, and managing vendors.
Overview
VendorService handles all vendor-related operations. It is exposed via printChecks.vendors on a PrintChecksCore instance, or can be instantiated directly.
Constructor
new VendorService(config: VendorServiceConfig)interface VendorServiceConfig {
storage: StorageAdapter
}Example
import { VendorService, LocalStorageAdapter } from '@printchecks/core'
const service = new VendorService({
storage: new LocalStorageAdapter()
})Methods
createVendor()
Create and persist a new vendor. Validates before saving; throws if validation fails.
async createVendor(data: VendorData): Promise<Vendor>| Parameter | Type | Description |
|---|---|---|
data | VendorData | Vendor fields. name is required. id, createdAt, updatedAt are auto-generated. |
Returns: The created Vendor instance.
Throws: Error if validation fails (e.g. name missing, invalid email format).
const vendor = await printChecks.vendors.createVendor({
name: 'Acme Corporation',
email: 'billing@acme.com',
phone: '555-555-0100',
address: '123 Main St',
city: 'Springfield',
state: 'IL',
zip: '62701'
})getVendor()
Retrieve a single vendor by ID.
async getVendor(id: string): Promise<Vendor | null>Returns: Vendor instance, or null if not found.
const vendor = await printChecks.vendors.getVendor('v1')getVendors()
Retrieve all vendors, with optional filtering.
async getVendors(filters?: VendorFilters): Promise<Vendor[]>VendorFilters
interface VendorFilters {
category?: string // exact category match
tags?: string[] // vendor must have ALL listed tags
isActive?: boolean // active/inactive filter
isFavorite?: boolean // favorites-only filter
searchTerm?: string // searches name, displayName, email, phone, businessNumber
}Returns: Array of matching Vendor instances.
// Active vendors only
const active = await printChecks.vendors.getVendors({ isActive: true })
// Vendors tagged with both 'supplier' and 'preferred'
const preferred = await printChecks.vendors.getVendors({
tags: ['supplier', 'preferred']
})
// Text search
const results = await printChecks.vendors.getVendors({ searchTerm: 'acme' })updateVendor()
Update fields on an existing vendor. Re-validates after update. id and createdAt cannot be overwritten.
async updateVendor(id: string, updates: Partial<VendorData>): Promise<Vendor>Throws: Error if the vendor is not found or the updated state fails validation.
const updated = await printChecks.vendors.updateVendor('v1', {
phone: '555-555-0200',
category: 'supplier'
})deleteVendor()
Permanently delete a vendor.
async deleteVendor(id: string): Promise<void>await printChecks.vendors.deleteVendor('v1')searchVendors()
Shorthand for getVendors({ searchTerm }). Searches name, displayName, email, phone, and businessNumber (case-insensitive).
async searchVendors(searchTerm: string): Promise<Vendor[]>const matches = await printChecks.vendors.searchVendors('acme')getVendorsByCategory()
Retrieve all vendors in a given category.
async getVendorsByCategory(category: string): Promise<Vendor[]>const suppliers = await printChecks.vendors.getVendorsByCategory('supplier')getFavoriteVendors()
Retrieve all vendors where isFavorite is true.
async getFavoriteVendors(): Promise<Vendor[]>const favs = await printChecks.vendors.getFavoriteVendors()getActiveVendors()
Retrieve all vendors where isActive is true.
async getActiveVendors(): Promise<Vendor[]>const active = await printChecks.vendors.getActiveVendors()getCategories()
Return a sorted list of all unique category strings used across vendors.
async getCategories(): Promise<string[]>const categories = await printChecks.vendors.getCategories()
// e.g. ['freelancer', 'supplier', 'utility']getTags()
Return a sorted list of all unique tag strings used across vendors.
async getTags(): Promise<string[]>const tags = await printChecks.vendors.getTags()
// e.g. ['net-30', 'preferred', 'recurring']toggleFavorite()
Toggle the isFavorite flag on a vendor.
async toggleFavorite(id: string): Promise<Vendor>Throws: Error if the vendor is not found.
const vendor = await printChecks.vendors.toggleFavorite('v1')
console.log(vendor.isFavorite) // true (if it was false before)toggleActive()
Toggle the isActive flag on a vendor.
async toggleActive(id: string): Promise<Vendor>Throws: Error if the vendor is not found.
const vendor = await printChecks.vendors.toggleActive('v1')
console.log(vendor.isActive) // false (if it was true before)addTag()
Add a tag to a vendor. No-ops if the tag is already present (duplicate guard enforced by Vendor.addTag()).
async addTag(id: string, tag: string): Promise<Vendor>Throws: Error if the vendor is not found.
const vendor = await printChecks.vendors.addTag('v1', 'preferred')
console.log(vendor.tags) // ['preferred']removeTag()
Remove a tag from a vendor.
async removeTag(id: string, tag: string): Promise<Vendor>Throws: Error if the vendor is not found.
await printChecks.vendors.removeTag('v1', 'preferred')getStatistics()
Get aggregate statistics across all vendors.
async getStatistics(): Promise<{
total: number
active: number
inactive: number
favorites: number
byCategory: Record<string, number>
}>| Field | Description |
|---|---|
total | Total number of vendors |
active | Vendors where isActive is true |
inactive | Vendors where isActive is false |
favorites | Vendors where isFavorite is true |
byCategory | Map of category → count |
const stats = await printChecks.vendors.getStatistics()
console.log(`${stats.active} active vendors`)
console.log(stats.byCategory) // e.g. { supplier: 3, utility: 2 }importVendors()
Bulk-import vendors from an array. Each entry is validated; failures are counted but do not halt the import.
async importVendors(vendorsData: VendorData[]): Promise<{ success: number; failed: number }>const result = await printChecks.vendors.importVendors(exportedData)
console.log(`Imported ${result.success}, failed ${result.failed}`)exportVendors()
Export all vendors as a plain-object array suitable for JSON serialization.
async exportVendors(): Promise<VendorData[]>const data = await printChecks.vendors.exportVendors()
localStorage.setItem('backup', JSON.stringify(data))clearAll()
Delete all stored vendors. Use with caution — this cannot be undone.
async clearAll(): Promise<void>