@pincerpay/core 0.1.1 → 0.2.0

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.
Files changed (6) hide show
  1. package/README.md +83 -3
  2. package/dist/constants.d.ts +6 -0
  3. package/dist/constants.d.ts.map +1 -1
  4. package/dist/constants.js +6 -0
  5. package/dist/constants.js.map +1 -1
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
  [![license](https://img.shields.io/npm/l/@pincerpay/core?style=flat-square)](https://github.com/ds1/pincerpay/blob/master/LICENSE)
6
6
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
7
7
 
8
- Shared types, chain configurations, and constants for the PincerPay ecosystem.
8
+ Shared types, chain configurations, and constants for the [PincerPay](https://pincerpay.com) ecosystem -- on-chain USDC payments for AI agents via the x402 protocol.
9
9
 
10
10
  ## Install
11
11
 
@@ -17,7 +17,7 @@ npm install @pincerpay/core
17
17
 
18
18
  ```typescript
19
19
  import { resolveChain, toCAIP2, DEFAULT_FACILITATOR_URL } from "@pincerpay/core";
20
- import type { ChainConfig, TransactionStatus } from "@pincerpay/core/types";
20
+ import type { ChainConfig, Transaction, AgentProfile } from "@pincerpay/core/types";
21
21
 
22
22
  const chain = resolveChain("solana");
23
23
  // { caip2Id: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", name: "Solana Devnet", ... }
@@ -63,6 +63,15 @@ const API_VERSION = "v1";
63
63
  const USDC_DECIMALS = 6;
64
64
  const OPTIMISTIC_THRESHOLD = "1000000"; // 1 USDC
65
65
  const API_KEY_HEADER = "x-pincerpay-api-key";
66
+ const API_KEY_PREFIX_LENGTH = 12;
67
+
68
+ const RATE_LIMIT = {
69
+ perMinute: 120,
70
+ perSecond: 20,
71
+ };
72
+
73
+ const TX_POLL_INTERVAL_MS = 2000;
74
+ const TX_CONFIRMATION_TIMEOUT_MS = 120_000;
66
75
 
67
76
  const FACILITATOR_ROUTES = {
68
77
  verify: "/v1/verify",
@@ -70,6 +79,12 @@ const FACILITATOR_ROUTES = {
70
79
  status: "/v1/status",
71
80
  supported: "/v1/supported",
72
81
  health: "/health",
82
+ metrics: "/v1/metrics",
83
+ paywalls: "/v1/paywalls",
84
+ transactions: "/v1/transactions",
85
+ agents: "/v1/agents",
86
+ webhooks: "/v1/webhooks",
87
+ merchant: "/v1/merchant",
73
88
  };
74
89
  ```
75
90
 
@@ -86,6 +101,9 @@ interface PincerPayConfig {
86
101
  merchantAddress: string;
87
102
  facilitatorUrl?: string;
88
103
  routes: Record<string, RoutePaywallConfig>;
104
+ /** Defer facilitator sync to first request instead of middleware init (default: false).
105
+ * Useful in Next.js to avoid build-time network calls during prerendering. */
106
+ syncFacilitatorOnStart?: boolean;
89
107
  }
90
108
 
91
109
  interface AgentConfig {
@@ -97,13 +115,67 @@ interface AgentConfig {
97
115
  }
98
116
 
99
117
  interface SpendingPolicy {
100
- maxPerTransaction?: string;
118
+ maxPerTransaction?: string; // Base units (e.g., "1000000" = 1 USDC)
101
119
  maxPerDay?: string;
102
120
  allowedMerchants?: string[];
103
121
  allowedChains?: string[];
104
122
  }
105
123
  ```
106
124
 
125
+ ### Transaction
126
+
127
+ ```typescript
128
+ interface Transaction {
129
+ id: string;
130
+ merchantId: string;
131
+ chainId: string; // CAIP-2
132
+ txHash: string;
133
+ fromAddress: string;
134
+ toAddress: string;
135
+ amount: string; // USDC base units
136
+ gasCost: string; // Base units of gasToken
137
+ gasToken: string; // "ETH" | "SOL" | "MATIC" | "USDC"
138
+ status: TransactionStatus;
139
+ optimistic: boolean;
140
+ settlementType?: SettlementType; // "x402" or "direct" (Anchor program)
141
+ programNonce?: string; // On-chain settlement nonce
142
+ slot?: string; // Solana slot number
143
+ priorityFee?: string; // Solana priority fee (microlamports)
144
+ computeUnits?: string; // Solana compute units consumed
145
+ createdAt: Date;
146
+ confirmedAt?: Date;
147
+ }
148
+ ```
149
+
150
+ ### Agent Profile
151
+
152
+ ```typescript
153
+ interface AgentProfile {
154
+ id: string;
155
+ merchantId: string;
156
+ name: string;
157
+ solanaAddress: string;
158
+ smartAccountPda?: string; // Squads Smart Account PDA
159
+ settingsPda?: string;
160
+ spendingLimitPda?: string;
161
+ maxPerTransaction?: string; // USDC base units
162
+ maxPerDay?: string;
163
+ status: AgentStatus;
164
+ createdAt: Date;
165
+ updatedAt: Date;
166
+ }
167
+ ```
168
+
169
+ ### Zod Schemas
170
+
171
+ Validation schemas for use at system boundaries:
172
+
173
+ ```typescript
174
+ import { PincerPayConfigSchema, SpendingPolicySchema, RoutePaywallConfigSchema } from "@pincerpay/core";
175
+
176
+ const result = PincerPayConfigSchema.safeParse(userInput);
177
+ ```
178
+
107
179
  ### Supported Chains
108
180
 
109
181
  | Chain | CAIP-2 ID | Shorthand | Testnet |
@@ -115,6 +187,14 @@ interface SpendingPolicy {
115
187
  | Solana | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` | `solana` | No |
116
188
  | Solana Devnet | `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` | `solana-devnet` | Yes |
117
189
 
190
+ ## Sub-path Exports
191
+
192
+ ```typescript
193
+ import { ... } from "@pincerpay/core"; // Everything
194
+ import type { ... } from "@pincerpay/core/types"; // Types only
195
+ import { resolveChain } from "@pincerpay/core/chains"; // Chain resolution only
196
+ ```
197
+
118
198
  ## Common Patterns
119
199
 
120
200
  ### Resolve chain by shorthand or CAIP-2 ID
package/dist/constants.d.ts CHANGED
@@ -9,6 +9,12 @@ export declare const FACILITATOR_ROUTES: {
9
9
  readonly status: "/v1/status";
10
10
  readonly supported: "/v1/supported";
11
11
  readonly health: "/health";
12
+ readonly metrics: "/v1/metrics";
13
+ readonly paywalls: "/v1/paywalls";
14
+ readonly transactions: "/v1/transactions";
15
+ readonly agents: "/v1/agents";
16
+ readonly webhooks: "/v1/webhooks";
17
+ readonly merchant: "/v1/merchant";
12
18
  };
13
19
  /** USDC decimals (consistent across all chains) */
14
20
  export declare const USDC_DECIMALS = 6;
package/dist/constants.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,eAAO,MAAM,uBAAuB,sCAAsC,CAAC;AAE3E,qCAAqC;AACrC,eAAO,MAAM,WAAW,OAAO,CAAC;AAEhC,yBAAyB;AACzB,eAAO,MAAM,kBAAkB;;;;;;CAMrB,CAAC;AAEX,mDAAmD;AACnD,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAE9C,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,0BAA0B;AAC1B,eAAO,MAAM,cAAc,wBAAwB,CAAC;AAEpD,0BAA0B;AAC1B,eAAO,MAAM,UAAU;IACrB,0CAA0C;;IAE1C,kDAAkD;;CAE1C,CAAC;AAEX,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,qDAAqD;AACrD,eAAO,MAAM,0BAA0B,SAAU,CAAC"}
1
+ {"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,eAAO,MAAM,uBAAuB,sCAAsC,CAAC;AAE3E,qCAAqC;AACrC,eAAO,MAAM,WAAW,OAAO,CAAC;AAEhC,yBAAyB;AACzB,eAAO,MAAM,kBAAkB;;;;;;;;;;;;CAYrB,CAAC;AAEX,mDAAmD;AACnD,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAE9C,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,0BAA0B;AAC1B,eAAO,MAAM,cAAc,wBAAwB,CAAC;AAEpD,0BAA0B;AAC1B,eAAO,MAAM,UAAU;IACrB,0CAA0C;;IAE1C,kDAAkD;;CAE1C,CAAC;AAEX,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,qDAAqD;AACrD,eAAO,MAAM,0BAA0B,SAAU,CAAC"}
package/dist/constants.js CHANGED
@@ -9,6 +9,12 @@ export const FACILITATOR_ROUTES = {
9
9
  status: `/${API_VERSION}/status`,
10
10
  supported: `/${API_VERSION}/supported`,
11
11
  health: "/health",
12
+ metrics: `/${API_VERSION}/metrics`,
13
+ paywalls: `/${API_VERSION}/paywalls`,
14
+ transactions: `/${API_VERSION}/transactions`,
15
+ agents: `/${API_VERSION}/agents`,
16
+ webhooks: `/${API_VERSION}/webhooks`,
17
+ merchant: `/${API_VERSION}/merchant`,
12
18
  };
13
19
  /** USDC decimals (consistent across all chains) */
14
20
  export const USDC_DECIMALS = 6;
package/dist/constants.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,MAAM,CAAC,MAAM,uBAAuB,GAAG,mCAAmC,CAAC;AAE3E,qCAAqC;AACrC,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC;AAEhC,yBAAyB;AACzB,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,MAAM,EAAE,IAAI,WAAW,SAAS;IAChC,MAAM,EAAE,IAAI,WAAW,SAAS;IAChC,MAAM,EAAE,IAAI,WAAW,SAAS;IAChC,SAAS,EAAE,IAAI,WAAW,YAAY;IACtC,MAAM,EAAE,SAAS;CACT,CAAC;AAEX,mDAAmD;AACnD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC;AAE/B,4EAA4E;AAC5E,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAE9C,qEAAqE;AACrE,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC,0BAA0B;AAC1B,MAAM,CAAC,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAEpD,0BAA0B;AAC1B,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,0CAA0C;IAC1C,SAAS,EAAE,GAAG;IACd,kDAAkD;IAClD,SAAS,EAAE,EAAE;CACL,CAAC;AAEX,6CAA6C;AAC7C,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAExC,qDAAqD;AACrD,MAAM,CAAC,MAAM,0BAA0B,GAAG,OAAO,CAAC"}
1
+ {"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,MAAM,CAAC,MAAM,uBAAuB,GAAG,mCAAmC,CAAC;AAE3E,qCAAqC;AACrC,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC;AAEhC,yBAAyB;AACzB,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,MAAM,EAAE,IAAI,WAAW,SAAS;IAChC,MAAM,EAAE,IAAI,WAAW,SAAS;IAChC,MAAM,EAAE,IAAI,WAAW,SAAS;IAChC,SAAS,EAAE,IAAI,WAAW,YAAY;IACtC,MAAM,EAAE,SAAS;IACjB,OAAO,EAAE,IAAI,WAAW,UAAU;IAClC,QAAQ,EAAE,IAAI,WAAW,WAAW;IACpC,YAAY,EAAE,IAAI,WAAW,eAAe;IAC5C,MAAM,EAAE,IAAI,WAAW,SAAS;IAChC,QAAQ,EAAE,IAAI,WAAW,WAAW;IACpC,QAAQ,EAAE,IAAI,WAAW,WAAW;CAC5B,CAAC;AAEX,mDAAmD;AACnD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC;AAE/B,4EAA4E;AAC5E,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAE9C,qEAAqE;AACrE,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC,0BAA0B;AAC1B,MAAM,CAAC,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAEpD,0BAA0B;AAC1B,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,0CAA0C;IAC1C,SAAS,EAAE,GAAG;IACd,kDAAkD;IAClD,SAAS,EAAE,EAAE;CACL,CAAC;AAEX,6CAA6C;AAC7C,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAExC,qDAAqD;AACrD,MAAM,CAAC,MAAM,0BAA0B,GAAG,OAAO,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pincerpay/core",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "type": "module",
5
5
  "description": "Shared types, chain configs, and constants for PincerPay on-chain payment gateway",
6
6
  "license": "MIT",