@prompt-helm/sdk 0.2.0 → 1.0.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.
- package/LICENSE +1 -1
- package/README.md +63 -158
- package/dist/index.cjs +140 -552
- package/dist/index.d.cts +43 -111
- package/dist/index.d.ts +43 -111
- package/dist/index.js +112 -545
- package/package.json +35 -54
- package/dist/index.cjs.map +0 -1
- package/dist/index.js.map +0 -1
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,194 +1,99 @@
|
|
|
1
1
|
# @prompt-helm/sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Prompt management for LLM apps: fetch your [PromptHelm](https://prompthelm.app) prompts at
|
|
4
|
+
runtime, so changing a prompt needs no rebuild and no redeploy.
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
You edit and publish a prompt in the PromptHelm dashboard. Your app asks for it by name, fills
|
|
7
|
+
in its variables and passes the text to whichever model it already calls. Every publish is a
|
|
8
|
+
version that never changes, and rolling back is one click; your app follows either on its next
|
|
9
|
+
refresh, 60 seconds by default.
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
- **Never takes your app down.** With a `fallback`, every failure (timeout, network, bad key,
|
|
12
|
+
missing prompt, missing variable) returns your fallback and reports through `onError`.
|
|
13
|
+
- **Fast after the first call.** Prompts are served from memory and refreshed in the background;
|
|
14
|
+
a refresh that finds nothing new is an empty `304`.
|
|
15
|
+
- **Your data stays with you.** Variables are filled in on your server. PromptHelm never sees
|
|
16
|
+
their values, your provider keys or your LLM traffic.
|
|
17
|
+
- **Small.** No dependencies, under 2 kB gzipped, ESM and CommonJS, Node.js 18 and later.
|
|
8
18
|
|
|
9
|
-
|
|
10
|
-
- Native `fetch` and `AbortController` — no runtime dependencies
|
|
11
|
-
- Typed error hierarchy for auth, rate limit, and server failures
|
|
12
|
-
- Async iterable streaming with structured SSE events
|
|
13
|
-
- Configurable timeout and exponential-backoff retry for transient failures
|
|
14
|
-
- ESM and CJS builds, full TypeScript declarations, Node 18+
|
|
19
|
+
## Install
|
|
15
20
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
```bash
|
|
21
|
+
```sh
|
|
19
22
|
npm install @prompt-helm/sdk
|
|
20
23
|
```
|
|
21
24
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
```ts
|
|
25
|
-
import { PromptHelm } from "@prompt-helm/sdk";
|
|
26
|
-
|
|
27
|
-
const ph = new PromptHelm({
|
|
28
|
-
apiKey: process.env.PROMPTHELM_API_KEY ?? "<your-api-token>",
|
|
29
|
-
});
|
|
25
|
+
Create an API key in the dashboard and put it in your server's environment:
|
|
30
26
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
variables: { name: "World" },
|
|
34
|
-
});
|
|
35
|
-
|
|
36
|
-
console.log(result.output);
|
|
37
|
-
console.log(`Tokens: ${result.totalTokens}, cost: $${result.cost.toFixed(6)}`);
|
|
27
|
+
```sh
|
|
28
|
+
PROMPTHELM_API_KEY=ph_…
|
|
38
29
|
```
|
|
39
30
|
|
|
40
|
-
##
|
|
41
|
-
|
|
42
|
-
`stream` returns an async iterable of typed events. The iterator terminates after a `done` event and throws a typed error if the server emits an `error` event.
|
|
31
|
+
## Use
|
|
43
32
|
|
|
44
33
|
```ts
|
|
45
34
|
import { PromptHelm } from "@prompt-helm/sdk";
|
|
46
35
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
});
|
|
36
|
+
// One client for the whole app: it holds the cache.
|
|
37
|
+
export const ph = new PromptHelm();
|
|
50
38
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
})) {
|
|
55
|
-
if (event.type === "chunk") {
|
|
56
|
-
process.stdout.write(event.content);
|
|
57
|
-
} else if (event.type === "done") {
|
|
58
|
-
console.log(`\n[done] tokens=${event.totalTokens} cost=${event.cost}`);
|
|
59
|
-
}
|
|
60
|
-
}
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
You can stop a stream early with an `AbortSignal`:
|
|
64
|
-
|
|
65
|
-
```ts
|
|
66
|
-
const controller = new AbortController();
|
|
67
|
-
setTimeout(() => controller.abort(), 5_000);
|
|
68
|
-
|
|
69
|
-
for await (const event of ph.stream(
|
|
70
|
-
{ promptSlug: "long-form" },
|
|
71
|
-
{ signal: controller.signal },
|
|
72
|
-
)) {
|
|
73
|
-
if (event.type === "chunk") {
|
|
74
|
-
process.stdout.write(event.content);
|
|
75
|
-
}
|
|
76
|
-
}
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
## Configuration
|
|
80
|
-
|
|
81
|
-
| Option | Type | Default | Description |
|
|
82
|
-
| ------------ | ----------------------- | ------------------------------ | -------------------------------------------------------------------- |
|
|
83
|
-
| `apiKey` | `string` | required | PromptHelm API key in the form `phk_<32 hex>`. |
|
|
84
|
-
| `baseURL` | `string` | `https://api.prompthelm.app` | Override the API host for self-hosted or non-production deployments. |
|
|
85
|
-
| `timeout` | `number` (ms) | `60000` | Per-request timeout. Aborts the underlying fetch on expiry. |
|
|
86
|
-
| `maxRetries` | `number` | `2` | Retries on network and 5xx errors. 4xx responses are never retried. |
|
|
87
|
-
| `userAgent` | `string` | `—` | Prefix appended to the SDK's User-Agent. Use it to identify the calling app (e.g. `"checkout-service/1.4.2"`). |
|
|
88
|
-
| `headers` | `Record<string,string>` | `{}` | Extra headers merged into every request. |
|
|
89
|
-
| `fetch` | `typeof fetch` | `globalThis.fetch` | Inject a custom `fetch` implementation (used in tests). |
|
|
90
|
-
|
|
91
|
-
## Retries, timeouts & streaming
|
|
92
|
-
|
|
93
|
-
This is the reference SDK that the other-language clients mirror, so its
|
|
94
|
-
transport behavior is deliberately precise:
|
|
95
|
-
|
|
96
|
-
- **Retries** apply to `execute` only. The client retries network failures and
|
|
97
|
-
`5xx` responses with exponential backoff plus jitter, up to `maxRetries`
|
|
98
|
-
(default `2`). `4xx` responses (`400`/`401`/`403`/`404`/`429`) are **never**
|
|
99
|
-
retried, nor are timeouts or caller-initiated aborts. `stream` is not retried
|
|
100
|
-
automatically — re-issue the call yourself if a stream fails.
|
|
101
|
-
- **Timeouts** are enforced per request via an internal `AbortController`. When
|
|
102
|
-
`timeout` (default `60000` ms) elapses the underlying `fetch` is aborted and a
|
|
103
|
-
`TimeoutError` is thrown. For streaming, the timeout covers establishing the
|
|
104
|
-
response; long-lived streams that keep emitting events are not cut off by it.
|
|
105
|
-
- **Cancellation**: pass `options.signal` (an `AbortSignal`) to either method.
|
|
106
|
-
Aborting cancels the in-flight HTTP request; for `stream` the iterator stops
|
|
107
|
-
cleanly and the connection is released.
|
|
108
|
-
- **Streaming protocol**: `stream` consumes Server-Sent Events from
|
|
109
|
-
`POST /api/v1/gateway/stream`. Each `data:` frame is a JSON `StreamEvent`
|
|
110
|
-
(`chunk` | `done` | `error`). The iterator yields `chunk` and `done` events;
|
|
111
|
-
an `error` event is thrown as an `ApiError` carrying `errorCode`, `message`,
|
|
112
|
-
and `requestId`. The stream always ends after a `done` or `error` event.
|
|
113
|
-
|
|
114
|
-
## Error handling
|
|
115
|
-
|
|
116
|
-
Every non-2xx response is translated into a typed error so consumers can branch on failure modes:
|
|
117
|
-
|
|
118
|
-
```ts
|
|
119
|
-
import {
|
|
120
|
-
PromptHelm,
|
|
121
|
-
AuthenticationError,
|
|
122
|
-
AuthorizationError,
|
|
123
|
-
NotFoundError,
|
|
124
|
-
RateLimitError,
|
|
125
|
-
ApiError,
|
|
126
|
-
TimeoutError,
|
|
127
|
-
} from "@prompt-helm/sdk";
|
|
128
|
-
|
|
129
|
-
const ph = new PromptHelm({
|
|
130
|
-
apiKey: process.env.PROMPTHELM_API_KEY ?? "<your-api-token>",
|
|
39
|
+
const system = await ph.get("support-reply", {
|
|
40
|
+
vars: { company: "Acme", customer_name: user.name },
|
|
41
|
+
fallback: SUPPORT_REPLY, // the prompt you had hard-coded
|
|
131
42
|
});
|
|
132
43
|
|
|
133
|
-
|
|
134
|
-
const result = await ph.execute({ promptSlug: "welcome-email" });
|
|
135
|
-
return result.output;
|
|
136
|
-
} catch (err) {
|
|
137
|
-
if (err instanceof AuthenticationError) {
|
|
138
|
-
// Rotate or refresh the API key.
|
|
139
|
-
} else if (err instanceof RateLimitError) {
|
|
140
|
-
// Back off and retry later.
|
|
141
|
-
} else if (err instanceof NotFoundError) {
|
|
142
|
-
// The slug does not exist in this environment.
|
|
143
|
-
} else if (err instanceof AuthorizationError) {
|
|
144
|
-
// The key cannot access this prompt.
|
|
145
|
-
} else if (err instanceof TimeoutError) {
|
|
146
|
-
// The request exceeded the configured timeout.
|
|
147
|
-
} else if (err instanceof ApiError) {
|
|
148
|
-
// 5xx or unknown server error. Safe to retry with backoff.
|
|
149
|
-
}
|
|
150
|
-
throw err;
|
|
151
|
-
}
|
|
44
|
+
// Pass `system` to your model exactly as you did before.
|
|
152
45
|
```
|
|
153
46
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
47
|
+
The stored prompt marks each variable in double braces, such as `{{customer_name}}`. If the live
|
|
48
|
+
version uses a variable the call doesn't pass, `get` doesn't send a half-filled prompt: it
|
|
49
|
+
returns the fallback (or, without one, throws `missing_variables`).
|
|
157
50
|
|
|
158
|
-
|
|
51
|
+
## Options
|
|
159
52
|
|
|
160
|
-
|
|
53
|
+
All optional when the environment variables are set.
|
|
161
54
|
|
|
162
|
-
|
|
55
|
+
| Option | Default | What it does |
|
|
56
|
+
| --------- | ------------------------------------------------- | -------------------------------------------------------------------- |
|
|
57
|
+
| `apiKey` | `PROMPTHELM_API_KEY` | Your project's API key. Keep it on the server. |
|
|
58
|
+
| `baseUrl` | `PROMPTHELM_BASE_URL`, then `https://prompthelm.app` | Where prompts are fetched from. |
|
|
59
|
+
| `ttl` | `60000` | How long, in ms, a prompt is served before checking for a newer one. |
|
|
60
|
+
| `timeout` | `3000` | How long, in ms, one request may take. |
|
|
61
|
+
| `onError` | `console.warn` | Called with the error and the slug when a fallback or a cached prompt was served instead of failing. |
|
|
62
|
+
| `fetch` | global `fetch` | Your own fetch, for tests or a proxy. |
|
|
163
63
|
|
|
164
|
-
|
|
64
|
+
## Errors
|
|
165
65
|
|
|
166
|
-
`
|
|
66
|
+
Failures are `PromptHelmError`s with a `code`, a `message` and, for HTTP errors, a `status`.
|
|
67
|
+
Without a `fallback`, `get` throws them; with one, `onError` receives them.
|
|
167
68
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
69
|
+
| Code | When |
|
|
70
|
+
| ------------------- | ---------------------------------------------------------- |
|
|
71
|
+
| `unauthorized` | The API key is missing, wrong or revoked. |
|
|
72
|
+
| `not_found` | The project has no published prompt with that slug. |
|
|
73
|
+
| `missing_variables` | The live version uses a variable the call doesn't pass. |
|
|
74
|
+
| `timeout` | No response within the timeout. |
|
|
75
|
+
| `network` | PromptHelm couldn't be reached. |
|
|
76
|
+
| `server` | Anything else, such as a 5xx response. |
|
|
176
77
|
|
|
177
|
-
|
|
78
|
+
After the first successful fetch, a failed background refresh keeps serving the cached prompt
|
|
79
|
+
and tries again after one ttl.
|
|
178
80
|
|
|
179
|
-
|
|
81
|
+
## Other languages
|
|
180
82
|
|
|
181
|
-
|
|
83
|
+
Any language can fetch the live version with one request:
|
|
182
84
|
|
|
183
|
-
|
|
184
|
-
-
|
|
185
|
-
|
|
186
|
-
|
|
85
|
+
```sh
|
|
86
|
+
curl https://prompthelm.app/v1/prompts/support-reply \
|
|
87
|
+
-H "Authorization: Bearer $PROMPTHELM_API_KEY"
|
|
88
|
+
```
|
|
187
89
|
|
|
188
|
-
##
|
|
90
|
+
## Links
|
|
189
91
|
|
|
190
|
-
|
|
92
|
+
- [Quickstart](https://prompthelm.app/quickstart)
|
|
93
|
+
- [Changing a prompt without a redeploy](https://prompthelm.app/guides/change-prompts-without-redeploying)
|
|
94
|
+
- [Prompt versioning and rollback](https://prompthelm.app/guides/prompt-versioning)
|
|
95
|
+
- [Pricing](https://prompthelm.app/pricing)
|
|
191
96
|
|
|
192
97
|
## License
|
|
193
98
|
|
|
194
|
-
MIT
|
|
99
|
+
MIT
|