@peac/adapter-core 0.12.5 → 0.12.7

package/README.md

@@ -1,6 +1,6 @@
 # @peac/adapter-core
 
-Shared utilities for PEAC payment rail adapters.
+Shared Result types, validators, and payment proof interfaces for PEAC adapters.
 
 ## Installation
 
@@ -8,34 +8,33 @@ Shared utilities for PEAC payment rail adapters.
 pnpm add @peac/adapter-core
 ```
 
-## Usage
+## What It Does
 
-### Result Type
+`@peac/adapter-core` provides the foundational utilities that all PEAC adapters build on. It enforces a "never throws" convention where all adapter functions return explicit `Result<T>` values instead of throwing exceptions. It also provides input validators for common fields (amounts, currencies, networks, timestamps) and defines the `PaymentProofAdapter` interface that payment-focused adapters implement.
 
-All adapter functions use the Result type for explicit error handling:
+## How Do I Use It?
+
+### Use the Result type for explicit error handling
 
 ```typescript
-import { ok, err, isOk, type Result } from '@peac/adapter-core';
+import { ok, adapterErr, isOk, type Result, type AdapterError } from '@peac/adapter-core';
 
-function parseEvent(input: unknown): Result<Event, AdapterError> {
+function parseEvent(input: unknown): Result<{ id: string }, AdapterError> {
   if (!input) {
     return adapterErr('input is required', 'missing_required_field');
   }
-  return ok({ ...parsed });
+  return ok({ id: 'parsed-event' });
 }
 
-// Handle result
 const result = parseEvent(data);
 if (isOk(result)) {
-  console.log(result.value);
+  console.log(result.value.id);
 } else {
-  console.error(result.error.message);
+  console.error(result.error.code, result.error.message);
 }
 ```
 
-### Validators
-
-Common validation functions for adapter inputs:
+### Validate adapter inputs
 
 ```typescript
 import { requireString, requireAmount, requireCurrency, requireObject } from '@peac/adapter-core';
@@ -54,35 +53,33 @@ function parseWebhook(event: unknown) {
 }
 ```
 
-### Available Validators
-
-| Validator                             | Description                 |
-| ------------------------------------- | --------------------------- |
-| `requireString(value, field)`         | Non-empty string required   |
-| `optionalString(value, field)`        | String or undefined         |
-| `requireNumber(value, field)`         | Finite number required      |
-| `requireAmount(value)`                | Non-negative safe integer   |
-| `requireCurrency(value)`              | ISO 4217 currency code      |
-| `optionalNetwork(value)`              | Network identifier (CAIP-2) |
-| `requireObject(value, field)`         | Non-null object             |
-| `optionalTimestamp(value)`            | ISO 8601 or Unix seconds    |
-| `optionalBoolean(value, field)`       | Boolean or undefined        |
-| `requireEnum(value, allowed, field)`  | Value from allowed list     |
-| `optionalEnum(value, allowed, field)` | Enum or undefined           |
-
-### JSON Types
-
-Re-exported from `@peac/kernel` for convenience:
+### Use JSON types for evidence structures
 
 ```typescript
 import type { JsonObject, JsonValue } from '@peac/adapter-core';
 
 interface PaymentEvidence {
   rail: string;
-  evidence: JsonObject; // JSON-safe, no unknown
+  evidence: JsonObject;
 }
 ```
 
+## Integrates With
+
+- `@peac/kernel` (Layer 0): JSON types re-exported for convenience
+- `@peac/adapter-x402` (Layer 4): Uses Result types and validators
+- `@peac/adapter-openclaw` (Layer 4): Uses Result types
+- All `@peac/adapter-*` and `@peac/mappings-*` packages
+
+## For Agent Developers
+
+If you are building a custom PEAC adapter for a new payment rail or protocol:
+
+- Import `Result`, `ok`, `err`, and `adapterErr` to follow the "never throws" convention
+- Use the provided validators (`requireAmount`, `requireCurrency`, `requireString`) for input parsing
+- Implement the `PaymentProofAdapter` interface for payment-focused adapters
+- See the [llms.txt](https://github.com/peacprotocol/peac/blob/main/llms.txt) for a concise protocol overview
+
 ## License
 
 Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peac/adapter-core",
-  "version": "0.12.5",
+  "version": "0.12.7",
   "description": "Shared utilities for PEAC payment rail adapters",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",
@@ -15,10 +15,10 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/peacprotocol/peac.git",
+    "url": "git+https://github.com/peacprotocol/peac.git",
     "directory": "packages/adapters/core"
   },
-  "author": "jithinraj <7850727+jithinraj@users.noreply.github.com>",
+  "author": "PEAC Protocol Contributors",
   "license": "Apache-2.0",
   "files": [
     "dist",
@@ -28,7 +28,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@peac/kernel": "0.12.5"
+    "@peac/kernel": "0.12.7"
   },
   "devDependencies": {
     "@types/node": "^22.19.11",
@@ -36,6 +36,22 @@
     "vitest": "^4.0.0",
     "tsup": "^8.0.0"
   },
+  "bugs": {
+    "url": "https://github.com/peacprotocol/peac/issues"
+  },
+  "homepage": "https://github.com/peacprotocol/peac#readme",
+  "keywords": [
+    "peac",
+    "peacprotocol",
+    "interaction-records",
+    "signed-records",
+    "receipts",
+    "originary",
+    "adapter",
+    "carrier",
+    "transport",
+    "evidence"
+  ],
   "scripts": {
     "prebuild": "rm -rf dist",
     "build": "pnpm run build:js && pnpm run build:types",