-
Notifications
You must be signed in to change notification settings - Fork 1
Description
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-apiin apps/web- Refactor
DirectAdapter.tsto wrap the espresso-api client - Remove raw fetch calls from
main.tsxinterceptor 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 parsingprocessProfileVariables()— resolve$keyreferences in stagesfindVariableReferences()— show which stages use each variable- Canonical types matching the machine firmware
Implementation
bun add @meticulous-home/espresso-profilein 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
-
@meticulous-home/espresso-apiadded as dependency -
@meticulous-home/espresso-profileadded as dependency - DirectAdapter wraps espresso-api instead of raw fetch
- Profile types use espresso-profile canonical types
-
abort,purge,homeactions available in DirectAdapter - All existing tests pass
- Build succeeds with no new type errors
References
- Research: research: MeticulousHome repository analysis — findings & impact for milestones 2.2–2.4 #283
- Capacitor app: iOS app: native client via Capacitor + MachineDirectAdapter #253
- MachineService: DirectAdapter.ts, MeticAIAdapter.ts
- OEM repos: espresso-api, espresso-profile