Skip to content

Add Time-of-Use tariff write to @teslemetry/api#49

Merged
Bre77 merged 1 commit into
mainfrom
fm/e14-tou-write-gap
Jul 12, 2026
Merged

Add Time-of-Use tariff write to @teslemetry/api#49
Bre77 merged 1 commit into
mainfrom
fm/e14-tou-write-gap

Conversation

@Bre77

@Bre77 Bre77 commented Jul 12, 2026

Copy link
Copy Markdown
Member

Intent

  • The tier-2 parity audit (Homey/Node-RED vs the HA teslemetry integration) found one
    genuine client-library gap across the whole TypeScript ecosystem: Time-of-Use tariff write.
    Every other absent write in either wrapper already had a method on @teslemetry/api - this was
    the one that didn't, so no amount of wrapper work in Homey or Node-RED could close it.
    • Approach: add TeslemetryEnergyApi.setTimeOfUseSettings(), mirroring the server's
      POST /api/1/energy_sites/{id}/time_of_use_settings route schema (tou_settings.tariff_content_v2).
    • The generated OpenAPI client (src/client/sdk.gen.ts) already had the underlying
      postApi1EnergySitesByIdTimeOfUseSettings function from a prior spec sync - no codegen/spec
      change was needed, just a hand-written wrapper following the existing pass-through-body idiom
      used by neighboring methods like addChargeSchedule/setScheduledDeparture.
    • Typing: request body is typed via the generated PostApi1EnergySitesByIdTimeOfUseSettingsData["body"]
      (no any), consistent with how other complex-body setters in this file are typed.
  • Scope boundary: library method only. Wiring this into homebridge-teslemetry,
    n8n-nodes-teslemetry, or iobroker.teslemetry is explicitly out of scope here - those are
    follow-up stories per the audit's recommendations.

What Changed

  • packages/api/src/TeslemetryEnergyApi.ts: new setTimeOfUseSettings(body) method.
  • packages/api/test/energyApi.test.ts: new test asserting the method POSTs the
    tou_settings body to the correct per-site URL and returns the parsed response.
  • .changeset/tou-tariff-write.md: minor version bump changeset for @teslemetry/api.
  • AGENTS.md: one-line note that the generated client often already has functions for
    endpoints the hand-written API classes haven't wrapped yet - worth checking before assuming
    an SDK gap needs a spec regen.

Risk Assessment

Low risk, additive-only change to the SDK. No existing methods or call sites touched.

Testing

  • pnpm --filter @teslemetry/api test - all 8 tests pass (new test included)
  • pnpm --filter @teslemetry/api tsc - clean
  • pnpm lint (root, oxlint) - clean
  • pnpm --filter @teslemetry/api build - clean
Full narrative / original brief

[E1.4] typescript-teslemetry: add the Time-of-Use (TOU) tariff WRITE capability to
@teslemetry/api (packages/api) - identified by the parity audit
(/home/brett/firstmate/data/e14-tier2-parity-m2/report.md) as the single true
client-library-level gap blocking tier-2 integrations from TOU control.

Scope:

  1. Read the parity report's evidence for exactly which endpoint/shape is missing, and mirror
    the api server's route schema (the Teslemetry api repo cloned at
    /home/brett/firstmate/projects/api - the energy tariff routes and their request schemas are
    the source of truth; the ENERGY_TARIFF_OUTPUT shape in src/routes/mcp/ as secondary
    reference).
  2. Implement in the library's existing idioms (neighboring energy-site methods for style,
    typing, and test patterns). Type the request per the server schema - no any-bags.
  3. Tests per the package's conventions.
  4. Library method only - do NOT wire it into the homebridge/n8n/iobroker packages in this PR
    (consumers are follow-up stories).

Closes the one true client-level gap identified by the tier-2 parity
audit: no TypeScript SDK method existed for HA's time_of_use write,
blocking Homey/Node-RED from ever reaching tariff control regardless
of wrapper work. The generated OpenAPI client already had the
underlying function (postApi1EnergySitesByIdTimeOfUseSettings); this
just wires a hand-written method to it, matching the pass-through body
typing used by neighboring schedule-setter methods.
@Bre77
Bre77 merged commit ba44c14 into main Jul 12, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant