@warmio/contracts 1.0.0

package/README.md

@@ -0,0 +1,15 @@
+# @warmio/contracts
+
+Machine-readable, side-effect-free contracts for Warm's public API and authenticated/local MCP surfaces. This is a contract package, not a client SDK: it contains schemas, inferred DTOs, endpoint metadata, examples, OpenAPI generation, and MCP descriptors; it does not perform network requests or start a server.
+
+```ts
+import { API_ORIGIN, apiEndpointManifest } from '@warmio/contracts/manifest';
+import { financialContextSchema } from '@warmio/contracts/schemas';
+import { buildOpenApiYaml } from '@warmio/contracts/openapi';
+```
+
+`@warmio/contracts/manifest` is intentionally safe for docs and edge consumers that only need URL, auth, rate-limit, and endpoint facts. The authenticated/local MCP definitions are exported from the root or `@warmio/contracts/mcp`; public discovery MCP tools remain owned by the edge worker.
+
+Warm publishes this package from `jasonstockman/warm-app`. It follows semver for documented public exports and wire-contract changes, but it is not a general-purpose SDK or a promise of hosted support beyond those contracts.
+
+The package is publicly readable for Warm's runtime and documentation consumers, but it is not open-source licensed. Public npm visibility does not grant permission to copy or redistribute its source beyond applicable package-use terms.

package/dist/api/endpoints.d.ts

@@ -0,0 +1,461 @@
+export declare const API_ORIGIN = "https://app.warm.io";
+export declare const DISCOVERY_ORIGIN = "https://warm.io";
+export declare const PUBLIC_DOCS_ORIGIN = "https://warm.io";
+export declare const OPENAPI_PATH = "/openapi.yaml";
+export declare const DEVELOPERS_PATH = "/developers";
+export declare const PUBLIC_DISCOVERY_MCP_PATH = "/mcp";
+export declare const VERIFY_PATH = "/api/verify";
+export declare const apiKeyPrefixesByAudience: {
+    readonly automation: 'warm_auto_';
+    readonly context: 'warm_ctx_';
+};
+export declare const apiAuthSchemes: {
+    readonly automation: {
+        readonly bearer_prefix: "warm_auto_";
+        readonly description: 'Automation routes require an automation API key.';
+        readonly scheme: 'bearer';
+    };
+    readonly context: {
+        readonly bearer_prefix: "warm_ctx_";
+        readonly description: 'Read/export routes accept a Warm API key or signed-in access token.';
+        readonly scheme: 'bearer';
+    };
+};
+export declare const apiRateLimits: {
+    readonly automation: {
+        readonly requests_per_hour: 500;
+    };
+    readonly context: {
+        readonly requests_per_hour: 200;
+    };
+};
+export declare const automationOperationDescriptors: readonly [{
+    readonly operation_id: "budgets.list";
+    readonly method: "GET";
+    readonly path: "/api/pwa/budgets";
+    readonly path_parameter_kind: null;
+    readonly summary: "List budgets";
+    readonly description: "List the user’s budgets and current progress.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "budgets.create";
+    readonly method: "POST";
+    readonly path: "/api/pwa/budgets";
+    readonly path_parameter_kind: null;
+    readonly summary: "Create budget";
+    readonly description: "Create a category or merchant budget.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "budgets.get";
+    readonly method: "GET";
+    readonly path: "/api/pwa/budgets/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Get budget";
+    readonly description: "Get one budget by ID.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "budgets.update";
+    readonly method: "PATCH";
+    readonly path: "/api/pwa/budgets/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Update budget";
+    readonly description: "Update one budget by ID.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "budgets.delete";
+    readonly method: "DELETE";
+    readonly path: "/api/pwa/budgets/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Delete budget";
+    readonly description: "Permanently delete one budget.";
+    readonly risk: ["destructive"];
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "goals.create";
+    readonly method: "POST";
+    readonly path: "/api/pwa/goals";
+    readonly path_parameter_kind: null;
+    readonly summary: "Create goal";
+    readonly description: "Create a savings goal.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "goals.get";
+    readonly method: "GET";
+    readonly path: "/api/pwa/goals/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Get goal";
+    readonly description: "Get one savings goal by ID.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "goals.update";
+    readonly method: "PATCH";
+    readonly path: "/api/pwa/goals/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Update goal";
+    readonly description: "Update one savings goal.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "goals.delete";
+    readonly method: "DELETE";
+    readonly path: "/api/pwa/goals/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Delete goal";
+    readonly description: "Permanently delete one savings goal.";
+    readonly risk: ["destructive"];
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "goals.complete";
+    readonly method: "POST";
+    readonly path: "/api/pwa/goals/{id}/complete";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Complete goal";
+    readonly description: "Mark a savings goal complete.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "goals.reopen";
+    readonly method: "POST";
+    readonly path: "/api/pwa/goals/{id}/reopen";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Reopen goal";
+    readonly description: "Reopen a completed savings goal.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "transactions.create";
+    readonly method: "POST";
+    readonly path: "/api/pwa/transactions";
+    readonly path_parameter_kind: null;
+    readonly summary: "Create transaction";
+    readonly description: "Create a manual transaction.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "transactions.get";
+    readonly method: "GET";
+    readonly path: "/api/pwa/transactions/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Get transaction";
+    readonly description: "Get one transaction by ID.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "transactions.update";
+    readonly method: "PATCH";
+    readonly path: "/api/pwa/transactions/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Update transaction";
+    readonly description: "Update one transaction.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "transactions.delete";
+    readonly method: "DELETE";
+    readonly path: "/api/pwa/transactions/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Delete transaction";
+    readonly description: "Permanently delete one transaction.";
+    readonly risk: ["destructive"];
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "transactions.confirm";
+    readonly method: "POST";
+    readonly path: "/api/pwa/transactions/{id}/confirm";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Confirm transaction";
+    readonly description: "Confirm a pending transaction classification.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "transactions.skip";
+    readonly method: "POST";
+    readonly path: "/api/pwa/transactions/{id}/skip";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Skip transaction";
+    readonly description: "Skip a pending transaction review.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "assets.list";
+    readonly method: "GET";
+    readonly path: "/api/pwa/assets";
+    readonly path_parameter_kind: null;
+    readonly summary: "List assets";
+    readonly description: "List manually tracked assets.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "assets.create";
+    readonly method: "POST";
+    readonly path: "/api/pwa/assets";
+    readonly path_parameter_kind: null;
+    readonly summary: "Create asset";
+    readonly description: "Create a manually tracked asset.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "assets.get";
+    readonly method: "GET";
+    readonly path: "/api/pwa/assets/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Get asset";
+    readonly description: "Get one asset by ID.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "assets.update";
+    readonly method: "PATCH";
+    readonly path: "/api/pwa/assets/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Update asset";
+    readonly description: "Update one manually tracked asset.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "assets.delete";
+    readonly method: "DELETE";
+    readonly path: "/api/pwa/assets/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Delete asset";
+    readonly description: "Permanently delete one manually tracked asset.";
+    readonly risk: ["destructive"];
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "accounts.get";
+    readonly method: "GET";
+    readonly path: "/api/pwa/accounts/{id}";
+    readonly path_parameter_kind: "opaque";
+    readonly summary: "Get account";
+    readonly description: "Get one account by ID.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "accounts.update";
+    readonly method: "PATCH";
+    readonly path: "/api/pwa/accounts/{id}";
+    readonly path_parameter_kind: "opaque";
+    readonly summary: "Update account";
+    readonly description: "Update editable account fields.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "accounts.delete";
+    readonly method: "DELETE";
+    readonly path: "/api/pwa/accounts/{id}";
+    readonly path_parameter_kind: "opaque";
+    readonly summary: "Delete account";
+    readonly description: "Permanently delete a user-owned account.";
+    readonly risk: ["destructive"];
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "alerts.list";
+    readonly method: "GET";
+    readonly path: "/api/pwa/alerts";
+    readonly path_parameter_kind: null;
+    readonly summary: "List alerts";
+    readonly description: "List spending alerts.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "alerts.acknowledge";
+    readonly method: "PATCH";
+    readonly path: "/api/pwa/alerts/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Acknowledge alert";
+    readonly description: "Acknowledge one spending alert.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "alerts.delete";
+    readonly method: "DELETE";
+    readonly path: "/api/pwa/alerts/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Delete alert";
+    readonly description: "Permanently delete one spending alert.";
+    readonly risk: ["destructive"];
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "tag_rules.list";
+    readonly method: "GET";
+    readonly path: "/api/pwa/tag-rules";
+    readonly path_parameter_kind: null;
+    readonly summary: "List tag rules";
+    readonly description: "List automatic transaction tag rules.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "tag_rules.create";
+    readonly method: "POST";
+    readonly path: "/api/pwa/tag-rules";
+    readonly path_parameter_kind: null;
+    readonly summary: "Create tag rule";
+    readonly description: "Create an automatic transaction tag rule.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "tag_rules.get";
+    readonly method: "GET";
+    readonly path: "/api/pwa/tag-rules/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Get tag rule";
+    readonly description: "Get one tag rule by ID.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "tag_rules.update";
+    readonly method: "PATCH";
+    readonly path: "/api/pwa/tag-rules/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Update tag rule";
+    readonly description: "Update one automatic tag rule.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "tag_rules.delete";
+    readonly method: "DELETE";
+    readonly path: "/api/pwa/tag-rules/{id}";
+    readonly path_parameter_kind: "uuid";
+    readonly summary: "Delete tag rule";
+    readonly description: "Permanently delete one automatic tag rule.";
+    readonly risk: ["destructive"];
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "recurring.update";
+    readonly method: "PATCH";
+    readonly path: "/api/pwa/recurring/{id}";
+    readonly path_parameter_kind: "opaque";
+    readonly summary: "Update recurring item";
+    readonly description: "Update one recurring transaction item.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "recurring.delete";
+    readonly method: "DELETE";
+    readonly path: "/api/pwa/recurring/{id}";
+    readonly path_parameter_kind: "opaque";
+    readonly summary: "Delete recurring item";
+    readonly description: "Permanently delete one recurring item.";
+    readonly risk: ["destructive"];
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "settings.get";
+    readonly method: "GET";
+    readonly path: "/api/pwa/settings";
+    readonly path_parameter_kind: null;
+    readonly summary: "Get settings";
+    readonly description: "Get user settings.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}, {
+    readonly operation_id: "settings.update";
+    readonly method: "PATCH";
+    readonly path: "/api/pwa/settings";
+    readonly path_parameter_kind: null;
+    readonly summary: "Update settings";
+    readonly description: "Update user settings.";
+} & {
+    confirmation_required: boolean;
+    risk: ("destructive" | "external_effect" | "read" | "write")[];
+}];
+export type AutomationOperationId = (typeof automationOperationDescriptors)[number]['operation_id'];
+export declare const apiEndpointManifest: readonly [{
+    readonly audience: 'context';
+    readonly method: 'GET';
+    readonly operation_id: 'verifyApiAccess';
+    readonly path: "/api/verify";
+    readonly summary: 'Verify API credentials';
+}, {
+    readonly audience: 'context';
+    readonly method: 'GET';
+    readonly operation_id: 'getDatasetExport';
+    readonly path: '/api/export';
+    readonly summary: 'Get a typed dataset export';
+}, {
+    readonly audience: 'context';
+    readonly method: 'GET';
+    readonly operation_id: 'getFinancialContext';
+    readonly path: '/api/financial-context';
+    readonly summary: 'Get compact financial context';
+}, {
+    readonly audience: 'context';
+    readonly method: 'GET';
+    readonly operation_id: 'getFinancialContextTransactions';
+    readonly path: '/api/financial-context/transactions';
+    readonly summary: 'Get financial-context transactions';
+}, {
+    readonly audience: 'context';
+    readonly method: 'GET';
+    readonly operation_id: 'getFinancialContextMeta';
+    readonly path: '/api/financial-context/meta';
+    readonly summary: 'Get financial-context metadata';
+}, {
+    readonly audience: 'automation';
+    readonly method: 'POST';
+    readonly operation_id: 'searchOperations';
+    readonly path: '/api/automation/operations/search';
+    readonly summary: 'Search supported automation operations';
+}, {
+    readonly audience: 'automation';
+    readonly method: 'POST';
+    readonly operation_id: 'describeOperation';
+    readonly path: '/api/automation/operations/describe';
+    readonly summary: 'Describe one supported operation';
+}, {
+    readonly audience: 'automation';
+    readonly method: 'POST';
+    readonly operation_id: 'invokeOperation';
+    readonly path: '/api/automation/operations/invoke';
+    readonly summary: 'Invoke one supported operation';
+}];
+//# sourceMappingURL=endpoints.d.ts.map

package/dist/api/endpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.d.ts","sourceRoot":"","sources":["../../src/api/endpoints.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU,wBAAwB,CAAC;AAChD,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAClD,eAAO,MAAM,kBAAkB,oBAAmB,CAAC;AACnD,eAAO,MAAM,YAAY,kBAAkB,CAAC;AAC5C,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAC7C,eAAO,MAAM,yBAAyB,SAAS,CAAC;AAChD,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAEzC,eAAO,MAAM,wBAAwB;aACnC,UAAU,EAAE,YAAY;aACxB,OAAO,EAAE,WAAW;CACZ,CAAC;AAEX,eAAO,MAAM,cAAc;aACzB,UAAU;iBACR,aAAa;iBACb,WAAW,EAAE,kDAAkD;iBAC/D,MAAM,EAAE,QAAQ;;aAElB,OAAO;iBACL,aAAa;iBACb,WAAW,EAAE,qEAAqE;iBAClF,MAAM,EAAE,QAAQ;;CAEV,CAAC;AAEX,eAAO,MAAM,aAAa;aACxB,UAAU;iBAAI,iBAAiB,EAAE,GAAG;;aACpC,OAAO;iBAAI,iBAAiB,EAAE,GAAG;;CACzB,CAAC;AAYX,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiTkB,CAAC;AAE9D,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;AAEpG,eAAO,MAAM,mBAAmB;aAE5B,QAAQ,EAAE,SAAS;aACnB,MAAM,EAAE,KAAK;aACb,YAAY,EAAE,iBAAiB;aAC/B,IAAI;aACJ,OAAO,EAAE,wBAAwB;;aAGjC,QAAQ,EAAE,SAAS;aACnB,MAAM,EAAE,KAAK;aACb,YAAY,EAAE,kBAAkB;aAChC,IAAI,EAAE,aAAa;aACnB,OAAO,EAAE,4BAA4B;;aAGrC,QAAQ,EAAE,SAAS;aACnB,MAAM,EAAE,KAAK;aACb,YAAY,EAAE,qBAAqB;aACnC,IAAI,EAAE,wBAAwB;aAC9B,OAAO,EAAE,+BAA+B;;aAGxC,QAAQ,EAAE,SAAS;aACnB,MAAM,EAAE,KAAK;aACb,YAAY,EAAE,iCAAiC;aAC/C,IAAI,EAAE,qCAAqC;aAC3C,OAAO,EAAE,oCAAoC;;aAG7C,QAAQ,EAAE,SAAS;aACnB,MAAM,EAAE,KAAK;aACb,YAAY,EAAE,yBAAyB;aACvC,IAAI,EAAE,6BAA6B;aACnC,OAAO,EAAE,gCAAgC;;aAGzC,QAAQ,EAAE,YAAY;aACtB,MAAM,EAAE,MAAM;aACd,YAAY,EAAE,kBAAkB;aAChC,IAAI,EAAE,mCAAmC;aACzC,OAAO,EAAE,wCAAwC;;aAGjD,QAAQ,EAAE,YAAY;aACtB,MAAM,EAAE,MAAM;aACd,YAAY,EAAE,mBAAmB;aACjC,IAAI,EAAE,qCAAqC;aAC3C,OAAO,EAAE,kCAAkC;;aAG3C,QAAQ,EAAE,YAAY;aACtB,MAAM,EAAE,MAAM;aACd,YAAY,EAAE,iBAAiB;aAC/B,IAAI,EAAE,mCAAmC;aACzC,OAAO,EAAE,gCAAgC;EAEnC,CAAC"}