@letsping/sdk 0.1.0 → 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 +128 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# @letsping/sdk
|
|
2
|
+
|
|
3
|
+
The official Node.js/TypeScript SDK for [LetsPing](https://letsping.co).
|
|
4
|
+
|
|
5
|
+
LetsPing is the Human-in-the-Loop control plane for autonomous agents — the durable state layer that pauses execution before sensitive actions, persists encrypted agent state, and resumes only after explicit human approval (or rejection/correction).
|
|
6
|
+
|
|
7
|
+
## Requirements
|
|
8
|
+
|
|
9
|
+
- Node.js 18+
|
|
10
|
+
- TypeScript 5+ (recommended)
|
|
11
|
+
|
|
12
|
+
## Installation
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install @letsping/sdk
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Usage
|
|
19
|
+
|
|
20
|
+
### Blocking Request (`ask`)
|
|
21
|
+
|
|
22
|
+
Execution suspends until the request is approved, rejected, or times out.
|
|
23
|
+
|
|
24
|
+
```typescript
|
|
25
|
+
import { LetsPing } from "@letsping/sdk";
|
|
26
|
+
|
|
27
|
+
const lp = new LetsPing(process.env.LETSPING_API_KEY!);
|
|
28
|
+
|
|
29
|
+
async function processRefund(userId: string, amount: number) {
|
|
30
|
+
try {
|
|
31
|
+
const decision = await lp.ask({
|
|
32
|
+
service: "billing-service",
|
|
33
|
+
action: "refund_user",
|
|
34
|
+
priority: "high",
|
|
35
|
+
payload: { userId, amount },
|
|
36
|
+
|
|
37
|
+
// Optional: JSON Schema to render an editable form in the dashboard
|
|
38
|
+
// (If using Zod: convert via zodToJsonSchema(mySchema))
|
|
39
|
+
schema: {
|
|
40
|
+
type: "object",
|
|
41
|
+
properties: {
|
|
42
|
+
amount: { type: "number", maximum: 5000 }
|
|
43
|
+
},
|
|
44
|
+
required: ["amount"]
|
|
45
|
+
},
|
|
46
|
+
|
|
47
|
+
// Optional override (default: 24 hours)
|
|
48
|
+
timeoutMs: 30 * 60 * 1000, // 30 minutes
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
if (decision.status === "APPROVED") {
|
|
52
|
+
// Prefer patched_payload if human edited values
|
|
53
|
+
const data = decision.patched_payload ?? decision.payload;
|
|
54
|
+
await stripe.refunds.create({
|
|
55
|
+
charge: data.userId,
|
|
56
|
+
amount: Math.round(data.amount * 100),
|
|
57
|
+
});
|
|
58
|
+
console.log("Refund executed");
|
|
59
|
+
} else {
|
|
60
|
+
console.log(`Refund ${decision.status.toLowerCase()} by operator`);
|
|
61
|
+
}
|
|
62
|
+
} catch (error) {
|
|
63
|
+
console.error("Approval failed or timed out:", error);
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Non-Blocking Request (`defer`)
|
|
69
|
+
|
|
70
|
+
Queues the request immediately and returns; ideal for serverless or event-driven flows.
|
|
71
|
+
|
|
72
|
+
```typescript
|
|
73
|
+
const { id } = await lp.defer({
|
|
74
|
+
service: "notification-agent",
|
|
75
|
+
action: "send_email",
|
|
76
|
+
payload: {
|
|
77
|
+
to: "user@example.com",
|
|
78
|
+
subject: "Your invoice is ready",
|
|
79
|
+
amount: 249.99
|
|
80
|
+
},
|
|
81
|
+
priority: "medium"
|
|
82
|
+
});
|
|
83
|
+
|
|
84
|
+
console.log(`Approval request queued → ${id}`);
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## API Reference
|
|
88
|
+
|
|
89
|
+
### `new LetsPing(apiKey, options?)`
|
|
90
|
+
|
|
91
|
+
- `apiKey` (string) — **required** — Service Role or Project API key from LetsPing dashboard
|
|
92
|
+
- `options.baseUrl` (string) — optional — Override endpoint (self-hosted / staging)
|
|
93
|
+
|
|
94
|
+
### `lp.ask(options): Promise<Decision>`
|
|
95
|
+
|
|
96
|
+
Blocks until resolved (approve / reject / timeout).
|
|
97
|
+
|
|
98
|
+
| Property | Type | Description |
|
|
99
|
+
|--------------|---------------------------------|-----------------------------------------------------------------------------|
|
|
100
|
+
| `service` | `string` | Service / module identifier (e.g. "billing", "compliance") |
|
|
101
|
+
| `action` | `string` | Action name (e.g. "refund", "transfer_funds") |
|
|
102
|
+
| `payload` | `Record<string, any>` | Context passed to human operator (and returned in Decision) |
|
|
103
|
+
| `priority` | `"low" \| "medium" \| "high" \| "critical"` | Routing priority in dashboard |
|
|
104
|
+
| `schema` | `object` | JSON Schema (draft 07) — generates editable form in dashboard |
|
|
105
|
+
| `timeoutMs` | `number` | Max wait time (default: 86_400_000 ms = 24 hours) |
|
|
106
|
+
|
|
107
|
+
### `lp.defer(options): Promise<{ id: string }>`
|
|
108
|
+
|
|
109
|
+
Fire-and-forget: queues request and returns request ID immediately. Same options shape as `ask`.
|
|
110
|
+
|
|
111
|
+
### Decision Type
|
|
112
|
+
|
|
113
|
+
```typescript
|
|
114
|
+
interface Decision {
|
|
115
|
+
status: "APPROVED" | "REJECTED";
|
|
116
|
+
payload: Record<string, any>; // Original payload sent by agent
|
|
117
|
+
patched_payload?: Record<string, any>; // Human-edited values (if modified)
|
|
118
|
+
metadata: {
|
|
119
|
+
actor_id: string; // ID/email of the approving/rejecting human
|
|
120
|
+
resolved_at: string; // ISO 8601 timestamp
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
For full documentation, request schema examples, error codes, and dashboard integration see:
|
|
126
|
+
https://letsping.co/docs#sdk
|
|
127
|
+
|
|
128
|
+
Deploy agents with confidence.
|