feat(api-contract): nodeControl.getBalance schemas and contract definition [1/4] (#739)

* feat(api-contract): nodeControl.getBalance schemas and contract definition [1/4]

Add GetBalanceResultSchema and the standalone getBalanceContract on
contracts/node-control. Deliberately leave the `nodeControl` router
unwired until the SDK handler ships in the implementation PR.

The SDK core's `implement(nodeControl).router({...})` is exhaustive, so
adding to `nodeControl` here without the matching handler in
@moneydevkit/core would break the workspace build. Splitting the
wire-up into the next commit keeps each PR independently green.

Bump api-contract to 0.1.27.

* fix(api-contract): re-export GetBalanceResult{,Schema} from package root

Address Codex review on #739: the node-control GetBalanceResult type
and schema were declared but not re-exported, so external consumers
couldn't import them via @moneydevkit/api-contract.

Aliased to NodeGetBalanceResult{,Schema} to avoid colliding with the
checkout-side GetBalanceResult{,Schema} that ships in PR [2/4]
(#740), mirroring the existing NodeProgrammaticPayoutInput alias.

The standalone getBalanceContract itself is intentionally NOT
re-exported: none of its node-control siblings (payoutContract,
programmaticPayoutContract, invoiceCreateBolt11Contract, ...) are
re-exported either. Consumers access the contract through the
nodeControl namespace once PR [3/4] wires it in.

Author: martinsaposnic

packages/api-contract/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moneydevkit/api-contract",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "API Contract for moneydevkit",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

packages/api-contract/src/contracts/node-control.ts

@@ -1,6 +1,7 @@
 import { eventIterator, oc } from "@orpc/contract";
 import { z } from "zod";
 import {
+	GetBalanceResultSchema,
 	InvoiceBolt11ResultSchema,
 	InvoiceBolt12OfferResultSchema,
 	InvoiceCreateBolt11InputSchema,
@@ -34,6 +35,18 @@ export const invoiceCreateBolt12OfferContract = oc
 	.input(InvoiceCreateBolt12OfferInputSchema)
 	.output(InvoiceBolt12OfferResultSchema);
 
+/**
+ * Read the merchant node's spendable (outbound) balance.
+ *
+ * Deliberately not yet wired into the `nodeControl` router export below: the
+ * SDK's `implement(nodeControl).router({...})` is exhaustive, so wiring here
+ * without the matching handler in @moneydevkit/core would break the workspace
+ * build. The wire-up lands together with the handler in the implementation PR.
+ */
+export const getBalanceContract = oc
+	.input(z.void())
+	.output(GetBalanceResultSchema);
+
 /** Server-pushed event stream. Single subscriber per session, buffered, FIFO. */
 export const nodeEventsContract = oc
 	.input(z.void())

packages/api-contract/src/index.ts

@@ -198,6 +198,7 @@ export type {
 	InvoiceCreateBolt12OfferInput,
 	InvoiceBolt12OfferResult,
 	NodeEvent,
+	GetBalanceResult as NodeGetBalanceResult,
 } from "./schemas/node-control";
 export {
 	PayoutInputSchema,
@@ -208,6 +209,7 @@ export {
 	InvoiceCreateBolt12OfferInputSchema,
 	InvoiceBolt12OfferResultSchema,
 	NodeEventSchema,
+	GetBalanceResultSchema as NodeGetBalanceResultSchema,
 } from "./schemas/node-control";
 
 // SDK contract - only the methods the SDK router implements

packages/api-contract/src/schemas/node-control.ts

@@ -83,6 +83,17 @@ export type InvoiceBolt12OfferResult = z.infer<
 	typeof InvoiceBolt12OfferResultSchema
 >;
 
+/**
+ * Result of the getBalance command on a merchant node. Returns the merchant's
+ * total outbound liquidity in sats (matches lightning-js `getBalance()` /
+ * `getBalanceWhileRunning()` units, which sum `outbound_capacity_msat` across
+ * channels and divide by 1000).
+ */
+export const GetBalanceResultSchema = z.object({
+	balanceSats: z.number().int().nonnegative(),
+});
+export type GetBalanceResult = z.infer<typeof GetBalanceResultSchema>;
+
 /**
  * Events pushed from the node to mdk.com over the events() AsyncIterable.
  *

packages/api-contract/tests/contracts/node-control.test.ts

@@ -0,0 +1,21 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { getBalanceContract, nodeControl } from '../../src/contracts/node-control'
+
+describe('node-control contracts', () => {
+  describe('getBalanceContract', () => {
+    it('is exported as an oRPC contract object', () => {
+      assert.ok(getBalanceContract)
+      assert.equal(typeof getBalanceContract, 'object')
+    })
+
+    it('is intentionally NOT yet wired into the nodeControl router', () => {
+      // Keep this assertion red until the implementation PR lands the SDK
+      // handler. Adding `getBalance` to `nodeControl` without the matching
+      // handler in @moneydevkit/core would break the workspace build via
+      // implement(nodeControl).router(...). Flip this assertion in PR3.
+      const router = nodeControl as Record<string, unknown>
+      assert.equal('getBalance' in router, false)
+    })
+  })
+})

packages/api-contract/tests/schemas/node-control.test.ts

@@ -0,0 +1,40 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { GetBalanceResultSchema } from '../../src/schemas/node-control'
+
+describe('node-control schemas', () => {
+  describe('GetBalanceResultSchema', () => {
+    it('accepts a non-negative integer sat balance', () => {
+      assert.equal(GetBalanceResultSchema.safeParse({ balanceSats: 0 }).success, true)
+      assert.equal(
+        GetBalanceResultSchema.safeParse({ balanceSats: 1_234_567 }).success,
+        true,
+      )
+    })
+
+    it('rejects negative balances', () => {
+      assert.equal(
+        GetBalanceResultSchema.safeParse({ balanceSats: -1 }).success,
+        false,
+      )
+    })
+
+    it('rejects fractional sats (lightning-js returns integer sats)', () => {
+      assert.equal(
+        GetBalanceResultSchema.safeParse({ balanceSats: 1.5 }).success,
+        false,
+      )
+    })
+
+    it('rejects missing balanceSats', () => {
+      assert.equal(GetBalanceResultSchema.safeParse({}).success, false)
+    })
+
+    it('rejects non-number balanceSats', () => {
+      assert.equal(
+        GetBalanceResultSchema.safeParse({ balanceSats: '1000' }).success,
+        false,
+      )
+    })
+  })
+})