@paystage/velocity 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,91 @@
1
- # Temporary Holding Version
1
+ # @paystage/velocity
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Rolling-window **rate and spend-pattern checks** for agent payments.
4
+
5
+ `@paystage/velocity` evaluates a proposed payment against recent history and a
6
+ policy's `velocity` configuration. It enforces per-window limits on transaction
7
+ count and aggregate amount (USDC, 6 decimals, BigInt-safe) over configurable
8
+ rolling windows such as 5, 30, and 300 minutes.
9
+
10
+ ## Policy shape
11
+
12
+ Add an optional `velocity` block to a `@paystage/policy` policy:
13
+
14
+ ```json
15
+ {
16
+ "version": 1,
17
+ "max_amount": { "value": "10.00", "decimals": 6 },
18
+ "allowed_pay_to": ["0xabc"],
19
+ "allowed_assets": ["USDC"],
20
+ "allowed_networks": ["base"],
21
+ "max_timeout_seconds": 300,
22
+ "unknown_payee": "deny",
23
+ "velocity": {
24
+ "windows": [
25
+ { "window_seconds": 300, "max_count": 5, "max_amount": { "value": "25.00", "decimals": 6 } },
26
+ { "window_seconds": 1800, "max_count": 20 },
27
+ { "window_seconds": 18000, "max_amount": { "value": "500.00", "decimals": 6 } }
28
+ ]
29
+ }
30
+ }
31
+ ```
32
+
33
+ Each window may specify `max_count`, `max_amount`, or both. The `velocity`
34
+ field is optional and does not affect policies that omit it.
35
+
36
+ ## API
37
+
38
+ ```ts
39
+ import { checkVelocity, parseVelocityPolicy } from "@paystage/velocity";
40
+
41
+ const windows = parseVelocityPolicy(policy);
42
+
43
+ const result = checkVelocity({
44
+ history: [
45
+ { timestamp_ms: Date.now() - 60_000, amount_atomic: 1_000_000n },
46
+ ],
47
+ proposed: { timestamp_ms: Date.now(), amount_atomic: 2_000_000n },
48
+ windows,
49
+ });
50
+
51
+ // result.decision: "allow" | "deny"
52
+ // result.reasons: string[] // names the failing window and whether count or amount
53
+ // result.windows_checked: per-window breakdown
54
+ ```
55
+
56
+ `checkVelocity` is pure: no I/O, and it uses `Date.now()` only when `now_ms`
57
+ is omitted. History actions with `timestamp_ms` strictly greater than
58
+ `now - window_seconds * 1000` are included; actions exactly at the boundary
59
+ are excluded.
60
+
61
+ ## MCP tool: `evaluate_velocity`
62
+
63
+ The package exposes an MCP tool `evaluate_velocity` with input:
64
+
65
+ ```json
66
+ {
67
+ "history": [
68
+ { "timestamp_ms": 1700000000000, "amount_atomic": "1000000" }
69
+ ],
70
+ "proposed": { "timestamp_ms": 1700000060000, "amount": "1.50", "decimals": 6 },
71
+ "policy": { "...": "..." }
72
+ }
73
+ ```
74
+
75
+ Amounts may be given as `amount_atomic` (decimal string of atomic units) or as
76
+ `amount` + `decimals` (human decimal string). The tool returns a JSON
77
+ `VelocityResult` with BigInt fields serialized as strings.
78
+
79
+ ## Install / use
80
+
81
+ Via the PayStage umbrella MCP server:
82
+
83
+ ```sh
84
+ npx @paystage/mcp
85
+ ```
86
+
87
+ The umbrella registers `evaluate_velocity` alongside the other PayStage tools.
88
+
89
+ ## License
90
+
91
+ MIT
@@ -0,0 +1,17 @@
1
+ import type { VelocityWindow } from "@paystage/policy";
2
+ import type { VelocityAction, VelocityResult } from "./types.js";
3
+ export interface CheckVelocityArgs {
4
+ history: VelocityAction[];
5
+ proposed: VelocityAction;
6
+ windows: VelocityWindow[];
7
+ now_ms?: number;
8
+ }
9
+ /**
10
+ * Pure rolling-window velocity check (rate and spend-pattern).
11
+ *
12
+ * History actions with timestamp_ms strictly greater than
13
+ * `now - window_seconds*1000` are included (boundary excluded), plus proposed.
14
+ * Denies if count > max_count or aggregate atomic amount > max_amount.
15
+ */
16
+ export declare function checkVelocity(args: CheckVelocityArgs): VelocityResult;
17
+ //# sourceMappingURL=check.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EAEf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,cAAc,CAmErE"}
package/dist/check.js ADDED
@@ -0,0 +1,58 @@
1
+ import { humanToAtomic } from "@paystage/policy";
2
+ /**
3
+ * Pure rolling-window velocity check (rate and spend-pattern).
4
+ *
5
+ * History actions with timestamp_ms strictly greater than
6
+ * `now - window_seconds*1000` are included (boundary excluded), plus proposed.
7
+ * Denies if count > max_count or aggregate atomic amount > max_amount.
8
+ */
9
+ export function checkVelocity(args) {
10
+ const { history, proposed, windows } = args;
11
+ const now = args.now_ms ?? Date.now();
12
+ const reasons = [];
13
+ const windows_checked = [];
14
+ if (!windows.length) {
15
+ return { decision: "allow", reasons: [], windows_checked: [] };
16
+ }
17
+ for (const window of windows) {
18
+ const cutoff = now - window.window_seconds * 1000;
19
+ let count = 0;
20
+ let amount = 0n;
21
+ for (const action of history) {
22
+ if (action.timestamp_ms > cutoff) {
23
+ count += 1;
24
+ amount += action.amount_atomic;
25
+ }
26
+ }
27
+ count += 1;
28
+ amount += proposed.amount_atomic;
29
+ const maxAmountAtomic = window.max_amount !== undefined
30
+ ? humanToAtomic(window.max_amount.value, window.max_amount.decimals)
31
+ : undefined;
32
+ const countOk = window.max_count === undefined ? true : count <= window.max_count;
33
+ const amountOk = maxAmountAtomic === undefined ? true : amount <= maxAmountAtomic;
34
+ const passed = countOk && amountOk;
35
+ if (!countOk) {
36
+ reasons.push(`window ${window.window_seconds}s: count ${count} exceeds max_count ${window.max_count}`);
37
+ }
38
+ if (!amountOk) {
39
+ reasons.push(`window ${window.window_seconds}s: amount ${amount.toString()} exceeds max_amount ${maxAmountAtomic.toString()}`);
40
+ }
41
+ windows_checked.push({
42
+ window_seconds: window.window_seconds,
43
+ count,
44
+ amount_atomic: amount,
45
+ max_count: window.max_count,
46
+ max_amount_atomic: maxAmountAtomic,
47
+ count_ok: countOk,
48
+ amount_ok: amountOk,
49
+ passed,
50
+ });
51
+ }
52
+ return {
53
+ decision: reasons.length === 0 ? "allow" : "deny",
54
+ reasons,
55
+ windows_checked,
56
+ };
57
+ }
58
+ //# sourceMappingURL=check.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"check.js","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAejD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAuB;IACnD,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IAEtC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,eAAe,GAA2B,EAAE,CAAC;IAEnD,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QACpB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC;IACjE,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;QAElD,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,MAAM,GAAG,EAAE,CAAC;QAEhB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,MAAM,CAAC,YAAY,GAAG,MAAM,EAAE,CAAC;gBACjC,KAAK,IAAI,CAAC,CAAC;gBACX,MAAM,IAAI,MAAM,CAAC,aAAa,CAAC;YACjC,CAAC;QACH,CAAC;QAED,KAAK,IAAI,CAAC,CAAC;QACX,MAAM,IAAI,QAAQ,CAAC,aAAa,CAAC;QAEjC,MAAM,eAAe,GACnB,MAAM,CAAC,UAAU,KAAK,SAAS;YAC7B,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC;YACpE,CAAC,CAAC,SAAS,CAAC;QAEhB,MAAM,OAAO,GACX,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,MAAM,CAAC,SAAS,CAAC;QACpE,MAAM,QAAQ,GACZ,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,eAAe,CAAC;QAEnE,MAAM,MAAM,GAAG,OAAO,IAAI,QAAQ,CAAC;QAEnC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CACV,UAAU,MAAM,CAAC,cAAc,YAAY,KAAK,sBAAsB,MAAM,CAAC,SAAS,EAAE,CACzF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,CAAC,IAAI,CACV,UAAU,MAAM,CAAC,cAAc,aAAa,MAAM,CAAC,QAAQ,EAAE,uBAAuB,eAAgB,CAAC,QAAQ,EAAE,EAAE,CAClH,CAAC;QACJ,CAAC;QAED,eAAe,CAAC,IAAI,CAAC;YACnB,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,KAAK;YACL,aAAa,EAAE,MAAM;YACrB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,iBAAiB,EAAE,eAAe;YAClC,QAAQ,EAAE,OAAO;YACjB,SAAS,EAAE,QAAQ;YACnB,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;QACjD,OAAO;QACP,eAAe;KAChB,CAAC;AACJ,CAAC"}
@@ -0,0 +1,7 @@
1
+ export type { VelocityAction, VelocityDecision, VelocityResult, VelocityWindow, VelocityWindowResult, } from "./types.js";
2
+ export { checkVelocity } from "./check.js";
3
+ export type { CheckVelocityArgs } from "./check.js";
4
+ export { parseVelocityPolicy } from "./parse.js";
5
+ export { EvaluateVelocityInputSchema, VelocityActionInputSchema, evaluateVelocity, serializeVelocityResult, } from "./mcp.js";
6
+ export type { EvaluateVelocityInput } from "./mcp.js";
7
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,EACzB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,4 @@
1
+ export { checkVelocity } from "./check.js";
2
+ export { parseVelocityPolicy } from "./parse.js";
3
+ export { EvaluateVelocityInputSchema, VelocityActionInputSchema, evaluateVelocity, serializeVelocityResult, } from "./mcp.js";
4
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,EACzB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,UAAU,CAAC"}
package/dist/mcp.d.ts ADDED
@@ -0,0 +1,173 @@
1
+ import { z } from "zod";
2
+ import type { VelocityResult } from "./types.js";
3
+ /**
4
+ * Input schema for the `evaluate_velocity` MCP tool.
5
+ *
6
+ * Amounts may be provided either as `amount_atomic` (decimal string of atomic
7
+ * units) or as `amount` + `decimals` (human decimal string). Exactly one form
8
+ * must be present per action.
9
+ */
10
+ export declare const VelocityActionInputSchema: z.ZodEffects<z.ZodObject<{
11
+ id: z.ZodOptional<z.ZodString>;
12
+ timestamp_ms: z.ZodNumber;
13
+ amount_atomic: z.ZodOptional<z.ZodString>;
14
+ amount: z.ZodOptional<z.ZodString>;
15
+ decimals: z.ZodOptional<z.ZodNumber>;
16
+ asset: z.ZodOptional<z.ZodString>;
17
+ }, "strip", z.ZodTypeAny, {
18
+ timestamp_ms: number;
19
+ id?: string | undefined;
20
+ amount_atomic?: string | undefined;
21
+ amount?: string | undefined;
22
+ decimals?: number | undefined;
23
+ asset?: string | undefined;
24
+ }, {
25
+ timestamp_ms: number;
26
+ id?: string | undefined;
27
+ amount_atomic?: string | undefined;
28
+ amount?: string | undefined;
29
+ decimals?: number | undefined;
30
+ asset?: string | undefined;
31
+ }>, {
32
+ timestamp_ms: number;
33
+ id?: string | undefined;
34
+ amount_atomic?: string | undefined;
35
+ amount?: string | undefined;
36
+ decimals?: number | undefined;
37
+ asset?: string | undefined;
38
+ }, {
39
+ timestamp_ms: number;
40
+ id?: string | undefined;
41
+ amount_atomic?: string | undefined;
42
+ amount?: string | undefined;
43
+ decimals?: number | undefined;
44
+ asset?: string | undefined;
45
+ }>;
46
+ export declare const EvaluateVelocityInputSchema: z.ZodObject<{
47
+ history: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodObject<{
48
+ id: z.ZodOptional<z.ZodString>;
49
+ timestamp_ms: z.ZodNumber;
50
+ amount_atomic: z.ZodOptional<z.ZodString>;
51
+ amount: z.ZodOptional<z.ZodString>;
52
+ decimals: z.ZodOptional<z.ZodNumber>;
53
+ asset: z.ZodOptional<z.ZodString>;
54
+ }, "strip", z.ZodTypeAny, {
55
+ timestamp_ms: number;
56
+ id?: string | undefined;
57
+ amount_atomic?: string | undefined;
58
+ amount?: string | undefined;
59
+ decimals?: number | undefined;
60
+ asset?: string | undefined;
61
+ }, {
62
+ timestamp_ms: number;
63
+ id?: string | undefined;
64
+ amount_atomic?: string | undefined;
65
+ amount?: string | undefined;
66
+ decimals?: number | undefined;
67
+ asset?: string | undefined;
68
+ }>, {
69
+ timestamp_ms: number;
70
+ id?: string | undefined;
71
+ amount_atomic?: string | undefined;
72
+ amount?: string | undefined;
73
+ decimals?: number | undefined;
74
+ asset?: string | undefined;
75
+ }, {
76
+ timestamp_ms: number;
77
+ id?: string | undefined;
78
+ amount_atomic?: string | undefined;
79
+ amount?: string | undefined;
80
+ decimals?: number | undefined;
81
+ asset?: string | undefined;
82
+ }>, "many">>;
83
+ proposed: z.ZodEffects<z.ZodObject<{
84
+ id: z.ZodOptional<z.ZodString>;
85
+ timestamp_ms: z.ZodNumber;
86
+ amount_atomic: z.ZodOptional<z.ZodString>;
87
+ amount: z.ZodOptional<z.ZodString>;
88
+ decimals: z.ZodOptional<z.ZodNumber>;
89
+ asset: z.ZodOptional<z.ZodString>;
90
+ }, "strip", z.ZodTypeAny, {
91
+ timestamp_ms: number;
92
+ id?: string | undefined;
93
+ amount_atomic?: string | undefined;
94
+ amount?: string | undefined;
95
+ decimals?: number | undefined;
96
+ asset?: string | undefined;
97
+ }, {
98
+ timestamp_ms: number;
99
+ id?: string | undefined;
100
+ amount_atomic?: string | undefined;
101
+ amount?: string | undefined;
102
+ decimals?: number | undefined;
103
+ asset?: string | undefined;
104
+ }>, {
105
+ timestamp_ms: number;
106
+ id?: string | undefined;
107
+ amount_atomic?: string | undefined;
108
+ amount?: string | undefined;
109
+ decimals?: number | undefined;
110
+ asset?: string | undefined;
111
+ }, {
112
+ timestamp_ms: number;
113
+ id?: string | undefined;
114
+ amount_atomic?: string | undefined;
115
+ amount?: string | undefined;
116
+ decimals?: number | undefined;
117
+ asset?: string | undefined;
118
+ }>;
119
+ policy: z.ZodOptional<z.ZodUnknown>;
120
+ policy_path: z.ZodOptional<z.ZodString>;
121
+ now_ms: z.ZodOptional<z.ZodNumber>;
122
+ }, "strip", z.ZodTypeAny, {
123
+ history: {
124
+ timestamp_ms: number;
125
+ id?: string | undefined;
126
+ amount_atomic?: string | undefined;
127
+ amount?: string | undefined;
128
+ decimals?: number | undefined;
129
+ asset?: string | undefined;
130
+ }[];
131
+ proposed: {
132
+ timestamp_ms: number;
133
+ id?: string | undefined;
134
+ amount_atomic?: string | undefined;
135
+ amount?: string | undefined;
136
+ decimals?: number | undefined;
137
+ asset?: string | undefined;
138
+ };
139
+ policy?: unknown;
140
+ policy_path?: string | undefined;
141
+ now_ms?: number | undefined;
142
+ }, {
143
+ proposed: {
144
+ timestamp_ms: number;
145
+ id?: string | undefined;
146
+ amount_atomic?: string | undefined;
147
+ amount?: string | undefined;
148
+ decimals?: number | undefined;
149
+ asset?: string | undefined;
150
+ };
151
+ history?: {
152
+ timestamp_ms: number;
153
+ id?: string | undefined;
154
+ amount_atomic?: string | undefined;
155
+ amount?: string | undefined;
156
+ decimals?: number | undefined;
157
+ asset?: string | undefined;
158
+ }[] | undefined;
159
+ policy?: unknown;
160
+ policy_path?: string | undefined;
161
+ now_ms?: number | undefined;
162
+ }>;
163
+ export type EvaluateVelocityInput = z.infer<typeof EvaluateVelocityInputSchema>;
164
+ /**
165
+ * Evaluate velocity for a proposed action against history and a policy.
166
+ * Pure aside from optional policy file read when `policy_path` is provided.
167
+ */
168
+ export declare function evaluateVelocity(input: EvaluateVelocityInput): Promise<VelocityResult>;
169
+ /**
170
+ * Serialize a VelocityResult to a JSON-safe object (BigInt -> string).
171
+ */
172
+ export declare function serializeVelocityResult(result: VelocityResult): unknown;
173
+ //# sourceMappingURL=mcp.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAkB,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBnC,CAAC;AAEJ,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMtC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAyBhF;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAmBzB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAevE"}
package/dist/mcp.js ADDED
@@ -0,0 +1,91 @@
1
+ import { humanToAtomic } from "@paystage/policy";
2
+ import { z } from "zod";
3
+ import { checkVelocity } from "./check.js";
4
+ import { parseVelocityPolicy } from "./parse.js";
5
+ /**
6
+ * Input schema for the `evaluate_velocity` MCP tool.
7
+ *
8
+ * Amounts may be provided either as `amount_atomic` (decimal string of atomic
9
+ * units) or as `amount` + `decimals` (human decimal string). Exactly one form
10
+ * must be present per action.
11
+ */
12
+ export const VelocityActionInputSchema = z
13
+ .object({
14
+ id: z.string().optional(),
15
+ timestamp_ms: z.number().int().nonnegative(),
16
+ amount_atomic: z.string().optional(),
17
+ amount: z.string().optional(),
18
+ decimals: z.number().int().nonnegative().optional(),
19
+ asset: z.string().optional(),
20
+ })
21
+ .refine((a) => (a.amount_atomic !== undefined) !==
22
+ (a.amount !== undefined && a.decimals !== undefined), {
23
+ message: "provide exactly one of amount_atomic or (amount + decimals)",
24
+ });
25
+ export const EvaluateVelocityInputSchema = z.object({
26
+ history: z.array(VelocityActionInputSchema).default([]),
27
+ proposed: VelocityActionInputSchema,
28
+ policy: z.unknown().optional(),
29
+ policy_path: z.string().optional(),
30
+ now_ms: z.number().int().nonnegative().optional(),
31
+ });
32
+ function toAtomic(input) {
33
+ if (input.amount_atomic !== undefined) {
34
+ const s = input.amount_atomic.trim();
35
+ if (!/^-?\d+$/.test(s)) {
36
+ throw new Error(`invalid amount_atomic: ${input.amount_atomic}`);
37
+ }
38
+ return BigInt(s);
39
+ }
40
+ // amount + decimals
41
+ return humanToAtomic(input.amount, input.decimals);
42
+ }
43
+ function toAction(input) {
44
+ return {
45
+ id: input.id,
46
+ timestamp_ms: input.timestamp_ms,
47
+ amount_atomic: toAtomic(input),
48
+ asset: input.asset,
49
+ };
50
+ }
51
+ /**
52
+ * Evaluate velocity for a proposed action against history and a policy.
53
+ * Pure aside from optional policy file read when `policy_path` is provided.
54
+ */
55
+ export async function evaluateVelocity(input) {
56
+ let policy = input.policy;
57
+ if (policy === undefined && input.policy_path !== undefined) {
58
+ const { readFile } = await import("node:fs/promises");
59
+ const raw = await readFile(input.policy_path, "utf8");
60
+ policy = JSON.parse(raw);
61
+ }
62
+ const windows = parseVelocityPolicy(policy);
63
+ const history = input.history.map(toAction);
64
+ const proposed = toAction(input.proposed);
65
+ return checkVelocity({
66
+ history,
67
+ proposed,
68
+ windows,
69
+ now_ms: input.now_ms,
70
+ });
71
+ }
72
+ /**
73
+ * Serialize a VelocityResult to a JSON-safe object (BigInt -> string).
74
+ */
75
+ export function serializeVelocityResult(result) {
76
+ return {
77
+ decision: result.decision,
78
+ reasons: result.reasons,
79
+ windows_checked: result.windows_checked.map((w) => ({
80
+ window_seconds: w.window_seconds,
81
+ count: w.count,
82
+ amount_atomic: w.amount_atomic.toString(),
83
+ max_count: w.max_count,
84
+ max_amount_atomic: w.max_amount_atomic?.toString(),
85
+ count_ok: w.count_ok,
86
+ amount_ok: w.amount_ok,
87
+ passed: w.passed,
88
+ })),
89
+ };
90
+ }
91
+ //# sourceMappingURL=mcp.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,7 @@
1
+ import type { Policy, VelocityWindow } from "@paystage/policy";
2
+ /**
3
+ * Extract velocity windows from a policy. Returns an empty array when the
4
+ * policy has no `velocity` field.
5
+ */
6
+ export declare function parseVelocityPolicy(policy: Policy | unknown): VelocityWindow[];
7
+ //# sourceMappingURL=parse.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAE/D;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,cAAc,EAAE,CAa9E"}
package/dist/parse.js ADDED
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Extract velocity windows from a policy. Returns an empty array when the
3
+ * policy has no `velocity` field.
4
+ */
5
+ export function parseVelocityPolicy(policy) {
6
+ if (policy === null || typeof policy !== "object") {
7
+ return [];
8
+ }
9
+ const velocity = policy.velocity;
10
+ if (velocity === null || typeof velocity !== "object") {
11
+ return [];
12
+ }
13
+ const windows = velocity.windows;
14
+ if (!Array.isArray(windows)) {
15
+ return [];
16
+ }
17
+ return windows;
18
+ }
19
+ //# sourceMappingURL=parse.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAwB;IAC1D,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAClD,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,QAAQ,GAAI,MAAiC,CAAC,QAAQ,CAAC;IAC7D,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACtD,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,OAAO,GAAI,QAAkC,CAAC,OAAO,CAAC;IAC5D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,OAA2B,CAAC;AACrC,CAAC"}
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=server.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":""}
package/dist/server.js ADDED
@@ -0,0 +1,32 @@
1
+ #!/usr/bin/env node
2
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
4
+ import { EvaluateVelocityInputSchema, evaluateVelocity, serializeVelocityResult, } from "./mcp.js";
5
+ const server = new McpServer({
6
+ name: "paystage-velocity",
7
+ version: "0.1.0",
8
+ });
9
+ server.registerTool("evaluate_velocity", {
10
+ title: "Evaluate velocity",
11
+ description: "Rolling-window rate and spend-pattern check for a proposed payment against history and a policy.",
12
+ inputSchema: EvaluateVelocityInputSchema,
13
+ }, async (input) => {
14
+ const result = await evaluateVelocity(input);
15
+ return {
16
+ content: [
17
+ {
18
+ type: "text",
19
+ text: JSON.stringify(serializeVelocityResult(result), null, 2),
20
+ },
21
+ ],
22
+ };
23
+ });
24
+ async function main() {
25
+ const transport = new StdioServerTransport();
26
+ await server.connect(transport);
27
+ }
28
+ main().catch((err) => {
29
+ console.error(err);
30
+ process.exit(1);
31
+ });
32
+ //# sourceMappingURL=server.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,2BAA2B,EAC3B,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,UAAU,CAAC;AAElB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,mBAAmB;IACzB,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,MAAM,CAAC,YAAY,CACjB,mBAAmB,EACnB;IACE,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EACT,kGAAkG;IACpG,WAAW,EAAE,2BAA2B;CACzC,EACD,KAAK,EAAE,KAAK,EAAE,EAAE;IACd,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC7C,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,uBAAuB,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;aAC/D;SACF;KACF,CAAC;AACJ,CAAC,CACF,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
@@ -0,0 +1,29 @@
1
+ import type { VelocityWindow } from "@paystage/policy";
2
+ export type { VelocityWindow };
3
+ /**
4
+ * A single payment action considered by the velocity checker.
5
+ * `amount_atomic` is the amount in atomic units (e.g. USDC 6 decimals).
6
+ */
7
+ export interface VelocityAction {
8
+ id?: string;
9
+ timestamp_ms: number;
10
+ amount_atomic: bigint;
11
+ asset?: string;
12
+ }
13
+ export type VelocityDecision = "allow" | "deny";
14
+ export interface VelocityWindowResult {
15
+ window_seconds: number;
16
+ count: number;
17
+ amount_atomic: bigint;
18
+ max_count?: number;
19
+ max_amount_atomic?: bigint;
20
+ count_ok: boolean;
21
+ amount_ok: boolean;
22
+ passed: boolean;
23
+ }
24
+ export interface VelocityResult {
25
+ decision: VelocityDecision;
26
+ reasons: string[];
27
+ windows_checked: VelocityWindowResult[];
28
+ }
29
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEhD,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,EAAE,oBAAoB,EAAE,CAAC;CACzC"}
package/dist/types.js ADDED
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}
package/package.json CHANGED
@@ -1,6 +1,49 @@
1
1
  {
2
2
  "name": "@paystage/velocity",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Rolling-window rate and spend-pattern checks for agent payments.",
5
+ "type": "module",
6
+ "main": "./dist/index.js",
7
+ "types": "./dist/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./dist/index.d.ts",
11
+ "import": "./dist/index.js"
12
+ }
13
+ },
14
+ "bin": {
15
+ "paystage-velocity": "./dist/server.js"
16
+ },
17
+ "files": [
18
+ "dist",
19
+ "README.md"
20
+ ],
21
+ "scripts": {
22
+ "build": "tsc -p tsconfig.json",
23
+ "test": "vitest run",
24
+ "typecheck": "tsc -p tsconfig.json --noEmit"
25
+ },
26
+ "dependencies": {
27
+ "@modelcontextprotocol/sdk": "^1.12.0",
28
+ "@paystage/policy": "0.1.0",
29
+ "zod": "^3.23.8"
30
+ },
31
+ "devDependencies": {
32
+ "typescript": "^5.5.0",
33
+ "vitest": "^2.0.0",
34
+ "@types/node": "^20.14.0"
35
+ },
36
+ "license": "MIT",
37
+ "engines": {
38
+ "node": ">=20"
39
+ },
40
+ "homepage": "https://paystage.xyz",
41
+ "repository": {
42
+ "type": "git",
43
+ "url": "git+https://github.com/base-buzz/paystage.git",
44
+ "directory": "packages/velocity"
45
+ },
46
+ "publishConfig": {
47
+ "access": "public"
48
+ }
49
+ }