Summary
Integrate the official MeticulousHome TypeScript packages into our web app to close API gaps and improve type safety for the Capacitor app (#253) and machine-hosted PWA.
Background
Research in #283 identified three official packages that our DirectAdapter should leverage instead of raw fetch/Socket.IO:
Gap 1: @meticulous-home/espresso-api (v0.10.11)
Current state: DirectAdapter uses raw fetch() + socket.io-client to communicate with the machine.
Target: Wrap @meticulous-home/espresso-api which provides 47+ typed methods covering all machine operations.
Benefits:
- Type-safe API calls with full TypeScript definitions
- Socket.IO client built-in with typed events
- Maintained by OEM — reduces our surface area for API drift
- Battle-tested in meticulous-dial and meticulous-web-ui
Implementation
bun add @meticulous-home/espresso-api in apps/web
- Refactor
DirectAdapter.ts to wrap the espresso-api client
- Remove raw fetch calls from
main.tsx interceptor where espresso-api covers them
- Keep supplemental REST calls only for endpoints not covered by the package
Gap 2: @meticulous-home/espresso-profile (v0.4.2)
Current state: Profile types are ad-hoc TypeScript interfaces scattered across components.
Target: Use the zero-dependency official types package for profile parsing and variable handling.
Benefits:
parseProfile() — validated profile parsing
processProfileVariables() — resolve $key references in stages
findVariableReferences() — show which stages use each variable
- Canonical types matching the machine firmware
Implementation
bun add @meticulous-home/espresso-profile in apps/web
- Replace ad-hoc profile types with imports from espresso-profile
- Use
processProfileVariables() before sending profiles to machine
- Use
findVariableReferences() in profile editing UI
Gap 3: Missing API actions
Current state: DirectAdapter cannot trigger abort, purge, or home actions.
Target: Full action parity with pyMeticulous backend.
The TS API enum is missing these actions. Supplement with direct REST calls:
POST /api/v1/action/abort
POST /api/v1/action/purge
POST /api/v1/action/home
Implementation
- Add
abort(), purge(), home() methods to MachineService interface
- Implement in DirectAdapter via direct REST (
/api/v1/action/{action})
- Implement in MeticAIAdapter as pass-through to backend
- Wire up UI controls (e.g. emergency stop → abort)
Acceptance Criteria
References
Summary
Integrate the official MeticulousHome TypeScript packages into our web app to close API gaps and improve type safety for the Capacitor app (#253) and machine-hosted PWA.
Background
Research in #283 identified three official packages that our DirectAdapter should leverage instead of raw fetch/Socket.IO:
Gap 1:
@meticulous-home/espresso-api(v0.10.11)Current state: DirectAdapter uses raw
fetch()+socket.io-clientto communicate with the machine.Target: Wrap
@meticulous-home/espresso-apiwhich provides 47+ typed methods covering all machine operations.Benefits:
Implementation
bun add @meticulous-home/espresso-apiin apps/webDirectAdapter.tsto wrap the espresso-api clientmain.tsxinterceptor where espresso-api covers themGap 2:
@meticulous-home/espresso-profile(v0.4.2)Current state: Profile types are ad-hoc TypeScript interfaces scattered across components.
Target: Use the zero-dependency official types package for profile parsing and variable handling.
Benefits:
parseProfile()— validated profile parsingprocessProfileVariables()— resolve$keyreferences in stagesfindVariableReferences()— show which stages use each variableImplementation
bun add @meticulous-home/espresso-profilein apps/webprocessProfileVariables()before sending profiles to machinefindVariableReferences()in profile editing UIGap 3: Missing API actions
Current state: DirectAdapter cannot trigger
abort,purge, orhomeactions.Target: Full action parity with pyMeticulous backend.
The TS API enum is missing these actions. Supplement with direct REST calls:
Implementation
abort(),purge(),home()methods to MachineService interface/api/v1/action/{action})Acceptance Criteria
@meticulous-home/espresso-apiadded as dependency@meticulous-home/espresso-profileadded as dependencyabort,purge,homeactions available in DirectAdapterReferences