@paystage/policy 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @paystage/policy
 
-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.
+Shared spending-policy schema and loader for PayStage agent payment tools.
+
+## Install
+
+```bash
+npm install @paystage/policy
+```
+
+## Usage
+
+```ts
+import { parsePolicy, loadPolicy, humanToAtomic } from "@paystage/policy";
+
+// Parse an in-memory object (validates against the schema).
+const policy = parsePolicy({
+  version: 1,
+  name: "standard",
+  allowed_networks: ["eip155:8453"],
+  allowed_assets: ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
+  allowed_pay_to: ["0x209693Bc6afc0C5328bA36FaF03C514EF312287C"],
+  max_amount_per_call: "1.00",
+  max_amount_per_session: "10.00",
+  require_human_above: "0.50",
+  max_timeout_seconds: 300,
+  default_verdict: "review",
+});
+
+// Load and validate from disk.
+const fromDisk = await loadPolicy("./policy.json");
+
+// Convert human-readable USDC to atomic units (6 decimals).
+humanToAtomic("0.50"); // "500000"
+```
+
+## API
+
+- `parsePolicy(input)` — validate an object, returns a typed `Policy`.
+- `loadPolicy(path)` — read + parse a JSON policy file.
+- `humanToAtomic(amount)` — convert `"0.50"` → `"500000"` (USDC, 6 decimals).
+
+## Links
+
+- Website: <https://paystage.xyz>
+- Source: <https://github.com/base-buzz/paystage>
+- License: MIT

package/dist/amounts.d.ts

@@ -0,0 +1,2 @@
+export declare function humanToAtomic(human: string, decimals: number): bigint;
+export declare function atomicToHuman(atomic: bigint, decimals: number): string;

package/dist/amounts.js

@@ -0,0 +1,41 @@
+export function humanToAtomic(human, decimals) {
+    if (!/^\d+(?:\.\d+)?$/.test(human)) {
+        throw new Error(`Invalid decimal amount: ${human}`);
+    }
+    if (!Number.isInteger(decimals) || decimals < 0) {
+        throw new Error("decimals must be a non-negative integer");
+    }
+    const [whole, fraction = ""] = human.split(".");
+    if (fraction.length > decimals) {
+        throw new Error(`Too many decimal places: ${human} has ${fraction.length}, expected at most ${decimals}`);
+    }
+    const wholePart = BigInt(whole);
+    const factor = 10n ** BigInt(decimals);
+    const fractionPart = fraction.length > 0 ? BigInt(fraction.padEnd(decimals, "0")) : 0n;
+    return wholePart * factor + fractionPart;
+}
+export function atomicToHuman(atomic, decimals) {
+    if (typeof atomic !== "bigint") {
+        throw new TypeError("atomic must be a bigint");
+    }
+    if (!Number.isInteger(decimals) || decimals < 0) {
+        throw new Error("decimals must be a non-negative integer");
+    }
+    if (atomic < 0n) {
+        throw new Error("atomic amount cannot be negative");
+    }
+    if (decimals === 0) {
+        return atomic.toString();
+    }
+    const factor = 10n ** BigInt(decimals);
+    const whole = atomic / factor;
+    const remainder = atomic % factor;
+    if (remainder === 0n) {
+        return whole.toString();
+    }
+    const fraction = remainder
+        .toString()
+        .padStart(decimals, "0")
+        .replace(/0+$/, "");
+    return `${whole}.${fraction}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./schema.js";
+export * from "./amounts.js";
+export * from "./load.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./schema.js";
+export * from "./amounts.js";
+export * from "./load.js";

package/dist/load.d.ts

@@ -0,0 +1,3 @@
+import type { Policy } from "./types.js";
+export declare function parsePolicy(input: unknown): Policy;
+export declare function loadPolicy(path: string): Promise<Policy>;

package/dist/load.js

@@ -0,0 +1,10 @@
+import { readFile } from "node:fs/promises";
+import { PolicySchema } from "./schema.js";
+export function parsePolicy(input) {
+    return PolicySchema.parse(input);
+}
+export async function loadPolicy(path) {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsePolicy(parsed);
+}

package/dist/schema.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import type { Policy } from "./types.js";
+export declare const PolicySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    max_amount: z.ZodObject<{
+        value: z.ZodString;
+        asset: z.ZodString;
+        decimals: z.ZodNumber;
+    }, z.core.$strip>;
+    daily_cap: z.ZodOptional<z.ZodObject<{
+        value: z.ZodString;
+        asset: z.ZodString;
+        decimals: z.ZodNumber;
+    }, z.core.$strip>>;
+    allowed_pay_to: z.ZodArray<z.ZodString>;
+    allowed_assets: z.ZodArray<z.ZodObject<{
+        symbol: z.ZodString;
+        decimals: z.ZodNumber;
+        address: z.ZodString;
+        network: z.ZodString;
+    }, z.core.$strip>>;
+    allowed_networks: z.ZodArray<z.ZodString>;
+    max_timeout_seconds: z.ZodNumber;
+    require_human_above: z.ZodOptional<z.ZodObject<{
+        value: z.ZodString;
+        asset: z.ZodString;
+        decimals: z.ZodNumber;
+    }, z.core.$strip>>;
+    unknown_payee: z.ZodEnum<{
+        review: "review";
+        deny: "deny";
+    }>;
+    max_auth_validity_seconds: z.ZodOptional<z.ZodNumber>;
+    allowed_spenders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disallow_unlimited_approvals: z.ZodOptional<z.ZodBoolean>;
+    velocity: z.ZodOptional<z.ZodObject<{
+        windows: z.ZodArray<z.ZodObject<{
+            window_seconds: z.ZodNumber;
+            max_count: z.ZodOptional<z.ZodNumber>;
+            max_amount: z.ZodOptional<z.ZodObject<{
+                value: z.ZodString;
+                decimals: z.ZodNumber;
+                asset: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PolicyFromSchema = z.infer<typeof PolicySchema>;
+export type ParsedPolicy = Policy;

package/dist/schema.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+const addressSchema = z
+    .string()
+    .regex(/^0x[a-fA-F0-9]{40}$/, "Expected a 0x-prefixed Ethereum address");
+const amountSpecSchema = z.object({
+    value: z
+        .string()
+        .regex(/^\d+(?:\.\d+)?$/, "Amount value must be a non-negative decimal string"),
+    asset: z.string().min(1),
+    decimals: z.number().int().min(0)
+});
+const assetSchema = z.object({
+    symbol: z.string().min(1),
+    decimals: z.number().int().min(0),
+    address: addressSchema,
+    network: z
+        .string()
+        .regex(/^eip155:\d+$/, "Expected a network id like eip155:8453")
+});
+const velocityAmountSchema = z.object({
+    value: z
+        .string()
+        .regex(/^\d+(?:\.\d+)?$/, "Amount value must be a non-negative decimal string"),
+    decimals: z.number().int().min(0),
+    asset: z.string().min(1).optional(),
+});
+const velocityWindowSchema = z.object({
+    window_seconds: z.number().int().positive(),
+    max_count: z.number().int().nonnegative().optional(),
+    max_amount: velocityAmountSchema.optional(),
+});
+export const PolicySchema = z.object({
+    version: z.literal(1),
+    max_amount: amountSpecSchema,
+    daily_cap: amountSpecSchema.optional(),
+    allowed_pay_to: z.array(addressSchema).min(1),
+    allowed_assets: z.array(assetSchema).min(1),
+    allowed_networks: z
+        .array(z.string().regex(/^eip155:\d+$/))
+        .min(1),
+    max_timeout_seconds: z.number().int().positive(),
+    require_human_above: amountSpecSchema.optional(),
+    unknown_payee: z.enum(["review", "deny"]),
+    max_auth_validity_seconds: z.number().int().positive().optional(),
+    allowed_spenders: z.array(addressSchema).optional(),
+    disallow_unlimited_approvals: z.boolean().optional(),
+    velocity: z
+        .object({ windows: z.array(velocityWindowSchema).min(1) })
+        .optional()
+});

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+export type UnknownPayee = "review" | "deny";
+export interface AmountSpec {
+    value: string;
+    asset: string;
+    decimals: number;
+}
+export interface Asset {
+    symbol: string;
+    decimals: number;
+    address: string;
+    network: string;
+}
+export interface VelocityAmountSpec {
+    value: string;
+    decimals: number;
+    asset?: string;
+}
+export interface VelocityWindow {
+    /** Rolling window length in seconds (e.g. 300, 1800, 18000). */
+    window_seconds: number;
+    /** Max number of transactions allowed in the window. */
+    max_count?: number;
+    /** Max aggregate amount allowed in the window. */
+    max_amount?: VelocityAmountSpec;
+}
+export interface Policy {
+    version: 1;
+    max_amount: AmountSpec;
+    daily_cap?: AmountSpec;
+    allowed_pay_to: string[];
+    allowed_assets: Asset[];
+    allowed_networks: string[];
+    max_timeout_seconds: number;
+    require_human_above?: AmountSpec;
+    unknown_payee: UnknownPayee;
+    max_auth_validity_seconds?: number;
+    allowed_spenders?: string[];
+    disallow_unlimited_approvals?: boolean;
+    /** Optional rolling-window rate and spend-pattern limits. */
+    velocity?: {
+        windows: VelocityWindow[];
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@paystage/policy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Shared spending policy schema and loader for PayStage agent payment tools",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "x402",
+    "agent-payments",
+    "usdc",
+    "base",
+    "policy"
+  ],
+  "homepage": "https://paystage.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/base-buzz/paystage.git",
+    "directory": "packages/policy"
+  },
+  "bugs": {
+    "url": "https://github.com/base-buzz/paystage/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "dependencies": {
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.4",
+    "vitest": "^4.1.12"
+  }
+}