@hasna/treasury 0.1.2

package/docker-compose.yml

@@ -0,0 +1,53 @@
+services:
+  db:
+    image: postgres:16
+    environment:
+      POSTGRES_DB: treasury
+      POSTGRES_USER: treasury
+      POSTGRES_PASSWORD_FILE: /run/secrets/pg_password
+    secrets: [pg_password]
+    volumes: ["pgdata:/var/lib/postgresql/data"]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U treasury"]
+      interval: 5s
+      retries: 10
+  serve:
+    image: oven/bun:1
+    # --package selects the serve bin; a bare `bunx @hasna/treasury treasury-serve`
+    # would run the CLI and treat "treasury-serve" as a bogus argument.
+    command: ["bunx", "--package", "@hasna/treasury", "treasury-serve"]
+    environment:
+      HASNA_TREASURY_STORAGE_MODE: cloud
+      HASNA_TREASURY_DATABASE_URL_FILE: /run/secrets/database_url
+      HASNA_TREASURY_PORT: "3486"
+      HASNA_TREASURY_BIND_HOST: "0.0.0.0"
+      HASNA_TREASURY_CORS_ORIGINS: ${CORS_ORIGINS:-}
+      HASNA_TREASURY_API_CREDENTIALS: ${TREASURY_API_CREDENTIALS:-}
+    secrets: [database_url]
+    depends_on: { db: { condition: service_healthy } }
+    ports: ["3486:3486"]
+  mcp:
+    image: oven/bun:1
+    # --package selects the MCP bin; a bare `bunx @hasna/treasury treasury-mcp` would run
+    # the CLI and treat "treasury-mcp" as a bogus argument. (BUILD-SPEC §6.4)
+    command: ["bunx", "--package", "@hasna/treasury", "treasury-mcp", "--http", "--port", "8890"]
+    environment:
+      HASNA_TREASURY_STORAGE_MODE: cloud
+      HASNA_TREASURY_DATABASE_URL_FILE: /run/secrets/database_url
+      MCP_HTTP: "1"
+      MCP_HTTP_PORT: "8890"
+      # Bind 0.0.0.0 so the published 8890 port is reachable; the default loopback
+      # bind is invisible to Docker port forwarding. A non-loopback bind forces auth
+      # ON and is asserted fail-closed at startup (assertMcpServeSafety), satisfied
+      # here by wiring API_CREDENTIALS. Never publish this port without credentials.
+      HASNA_TREASURY_MCP_BIND_HOST: "0.0.0.0"
+      HASNA_TREASURY_API_CREDENTIALS: ${TREASURY_API_CREDENTIALS:-}
+    secrets: [database_url]
+    depends_on: { db: { condition: service_healthy } }
+    ports: ["8890:8890"]
+secrets:
+  pg_password:
+    file: ./secrets/pg_password
+  database_url:
+    file: ./secrets/database_url   # postgres://treasury:<pw>@db:5432/treasury?sslmode=verify-full
+volumes: { pgdata: {} }

package/hasna.contract.json

@@ -0,0 +1,20 @@
+{
+  "schema": "hasna.service_contract.v1",
+  "name": "treasury",
+  "class": "cli-with-store",
+  "contractVersion": "v1",
+  "kitVersion": "0.4.1",
+  "description": "Multi-entity cash/treasury cockpit CLI + MCP + serve. Local mode uses SQLite at ~/.hasna/treasury/treasury.db; cloud mode (HASNA_TREASURY_STORAGE_MODE=cloud) is PURE REMOTE per Amendment A1 with all reads/writes hitting the shared cloud Postgres.",
+  "bins": [
+    "treasury",
+    "treasury-mcp",
+    "treasury-serve"
+  ],
+  "storage": {
+    "mode": "local",
+    "envPrefix": "HASNA_TREASURY_",
+    "aliasEnvPrefix": "TREASURY_",
+    "databaseUrlSecretRef": "hasna/oss/treasury/database-url",
+    "sqlitePath": "~/.hasna/treasury/treasury.db"
+  }
+}

package/openapi.json

@@ -0,0 +1,615 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "@hasna/treasury API",
+    "version": "0.1.2",
+    "description": "Multi-entity cash/treasury cockpit — consolidated balances, FX exposure, runway, forecast, and advisory sweep recommendations."
+  },
+  "paths": {
+    "/health": {
+      "get": {
+        "operationId": "getHealth",
+        "summary": "Liveness",
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/ready": {
+      "get": {
+        "operationId": "getReady",
+        "summary": "Readiness",
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/version": {
+      "get": {
+        "operationId": "getVersion",
+        "summary": "Version",
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/v1/entities": {
+      "get": {
+        "operationId": "listEntities",
+        "summary": "List entities the caller is authorized to see.",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        }
+      },
+      "post": {
+        "operationId": "createEntity",
+        "summary": "Create (cache) an entity anchor.",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "name",
+                  "base_currency"
+                ],
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  },
+                  "base_currency": {
+                    "type": "string"
+                  },
+                  "entity_slug": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/entities/{entity_id}": {
+      "get": {
+        "operationId": "getEntity",
+        "summary": "Get a single entity by entity_id.",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "parameters": [
+          {
+            "name": "entity_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      }
+    },
+    "/v1/balances": {
+      "get": {
+        "operationId": "listBalances",
+        "summary": "List cached balance snapshots (optionally for one entity).",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "parameters": [
+          {
+            "name": "entity_id",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      },
+      "post": {
+        "operationId": "recordBalance",
+        "summary": "Cache a balance snapshot with provenance.",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "entity_id",
+                  "account_ref",
+                  "account_kind",
+                  "currency",
+                  "amount_minor"
+                ],
+                "properties": {
+                  "entity_id": {
+                    "type": "string"
+                  },
+                  "account_ref": {
+                    "type": "string"
+                  },
+                  "account_kind": {
+                    "type": "string"
+                  },
+                  "currency": {
+                    "type": "string"
+                  },
+                  "amount_minor": {
+                    "type": "integer"
+                  },
+                  "source": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/balances/consolidated": {
+      "get": {
+        "operationId": "consolidatedBalances",
+        "summary": "Consolidated balances across visible entities, converted to a base.",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "parameters": [
+          {
+            "name": "base",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      }
+    },
+    "/v1/fx-rates": {
+      "get": {
+        "operationId": "listFxRates",
+        "summary": "List cached FX rates.",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        }
+      },
+      "post": {
+        "operationId": "recordFxRate",
+        "summary": "Cache an FX rate (1 base = rate quote).",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "base_currency",
+                  "quote_currency",
+                  "rate"
+                ],
+                "properties": {
+                  "base_currency": {
+                    "type": "string"
+                  },
+                  "quote_currency": {
+                    "type": "string"
+                  },
+                  "rate": {
+                    "type": "number"
+                  },
+                  "source": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/exposure": {
+      "get": {
+        "operationId": "fxExposure",
+        "summary": "FX exposure across visible balances, converted to a base.",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "parameters": [
+          {
+            "name": "base",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      }
+    },
+    "/v1/cost-feeds": {
+      "post": {
+        "operationId": "recordCostFeed",
+        "summary": "Record an entity's monthly net cash burn.",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "entity_id",
+                  "currency",
+                  "monthly_burn_minor"
+                ],
+                "properties": {
+                  "entity_id": {
+                    "type": "string"
+                  },
+                  "currency": {
+                    "type": "string"
+                  },
+                  "monthly_burn_minor": {
+                    "type": "integer"
+                  },
+                  "source": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "operationId": "listCostFeeds",
+        "summary": "List cached cost feeds (optionally for one entity).",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "parameters": [
+          {
+            "name": "entity_id",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      }
+    },
+    "/v1/runway/{entity_id}": {
+      "get": {
+        "operationId": "entityRunway",
+        "summary": "Runway (months) for a single entity.",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "parameters": [
+          {
+            "name": "entity_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "base",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      }
+    },
+    "/v1/runway": {
+      "get": {
+        "operationId": "groupRunway",
+        "summary": "Consolidated group runway (months).",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "parameters": [
+          {
+            "name": "base",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      }
+    },
+    "/v1/forecast": {
+      "get": {
+        "operationId": "cashForecast",
+        "summary": "Short-horizon cash projection (entity or group).",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "parameters": [
+          {
+            "name": "entity_id",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "base",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "horizon_months",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ]
+      }
+    },
+    "/v1/sweeps": {
+      "get": {
+        "operationId": "listSweeps",
+        "summary": "List sweep / intercompany-funding recommendations.",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "parameters": [
+          {
+            "name": "status",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      }
+    },
+    "/v1/sweeps/{id}": {
+      "get": {
+        "operationId": "getSweep",
+        "summary": "Get a single sweep recommendation.",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      },
+      "patch": {
+        "operationId": "updateSweepStatus",
+        "summary": "Acknowledge or dismiss a sweep recommendation (advisory only).",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "status"
+                ],
+                "properties": {
+                  "status": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/sweeps/generate": {
+      "post": {
+        "operationId": "generateSweeps",
+        "summary": "Generate intercompany-funding recommendations (advisory only).",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [],
+                "properties": {
+                  "base": {
+                    "type": "string"
+                  },
+                  "min_runway_months": {
+                    "type": "number"
+                  },
+                  "healthy_runway_months": {
+                    "type": "number"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/ingest": {
+      "post": {
+        "operationId": "ingestFixtures",
+        "summary": "Ingest balances/FX/cost from the v0 fixture adapters for two demo entities.",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "4XX": {
+            "description": "Error envelope { code, message, suggestion }"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "us_entity_id",
+                  "ro_entity_id"
+                ],
+                "properties": {
+                  "us_entity_id": {
+                    "type": "string"
+                  },
+                  "ro_entity_id": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}