Skip to content

feat: integrate OEM TypeScript packages into DirectAdapter #326

@hessius

Description

@hessius

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

  1. bun add @meticulous-home/espresso-api in apps/web
  2. Refactor DirectAdapter.ts to wrap the espresso-api client
  3. Remove raw fetch calls from main.tsx interceptor where espresso-api covers them
  4. 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

  1. bun add @meticulous-home/espresso-profile in apps/web
  2. Replace ad-hoc profile types with imports from espresso-profile
  3. Use processProfileVariables() before sending profiles to machine
  4. 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

  1. Add abort(), purge(), home() methods to MachineService interface
  2. Implement in DirectAdapter via direct REST (/api/v1/action/{action})
  3. Implement in MeticAIAdapter as pass-through to backend
  4. Wire up UI controls (e.g. emergency stop → abort)

Acceptance Criteria

  • @meticulous-home/espresso-api added as dependency
  • @meticulous-home/espresso-profile added as dependency
  • DirectAdapter wraps espresso-api instead of raw fetch
  • Profile types use espresso-profile canonical types
  • abort, purge, home actions available in DirectAdapter
  • All existing tests pass
  • Build succeeds with no new type errors

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions