@prompt-helm/sdk 0.1.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 +64 -132
- package/dist/index.cjs +140 -539
- package/dist/index.d.cts +45 -105
- package/dist/index.d.ts +45 -105
- package/dist/index.js +111 -531
- 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,167 +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
|
-
for await (const event of ph.stream({
|
|
50
|
-
promptSlug: "release-notes",
|
|
51
|
-
variables: { version: "1.4.0" },
|
|
52
|
-
})) {
|
|
53
|
-
if (event.type === "chunk") {
|
|
54
|
-
process.stdout.write(event.content);
|
|
55
|
-
} else if (event.type === "done") {
|
|
56
|
-
console.log(`\n[done] tokens=${event.totalTokens} cost=${event.cost}`);
|
|
57
|
-
}
|
|
58
|
-
}
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
You can stop a stream early with an `AbortSignal`:
|
|
36
|
+
// One client for the whole app: it holds the cache.
|
|
37
|
+
export const ph = new PromptHelm();
|
|
62
38
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
for await (const event of ph.stream(
|
|
68
|
-
{ promptSlug: "long-form" },
|
|
69
|
-
{ signal: controller.signal },
|
|
70
|
-
)) {
|
|
71
|
-
if (event.type === "chunk") {
|
|
72
|
-
process.stdout.write(event.content);
|
|
73
|
-
}
|
|
74
|
-
}
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
## Configuration
|
|
78
|
-
|
|
79
|
-
| Option | Type | Default | Description |
|
|
80
|
-
| ------------ | ----------------------- | ------------------------------ | -------------------------------------------------------------------- |
|
|
81
|
-
| `apiKey` | `string` | required | PromptHelm API key in the form `phk_<32 hex>`. |
|
|
82
|
-
| `baseURL` | `string` | `https://api.prompthelm.app` | Override for self-hosted deployments or staging environments. |
|
|
83
|
-
| `timeout` | `number` (ms) | `60000` | Per-request timeout. Aborts the underlying fetch on expiry. |
|
|
84
|
-
| `maxRetries` | `number` | `2` | Retries on network and 5xx errors. 4xx responses are never retried. |
|
|
85
|
-
| `userAgent` | `string` | `—` | Prefix appended to the SDK's User-Agent. Use it to identify the calling app (e.g. `"checkout-service/1.4.2"`). |
|
|
86
|
-
| `headers` | `Record<string,string>` | `{}` | Extra headers merged into every request. |
|
|
87
|
-
| `fetch` | `typeof fetch` | `globalThis.fetch` | Inject a custom `fetch` implementation (used in tests). |
|
|
88
|
-
|
|
89
|
-
## Error handling
|
|
90
|
-
|
|
91
|
-
Every non-2xx response is translated into a typed error so consumers can branch on failure modes:
|
|
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
|
|
42
|
+
});
|
|
92
43
|
|
|
93
|
-
|
|
94
|
-
import {
|
|
95
|
-
PromptHelm,
|
|
96
|
-
AuthenticationError,
|
|
97
|
-
AuthorizationError,
|
|
98
|
-
NotFoundError,
|
|
99
|
-
RateLimitError,
|
|
100
|
-
ApiError,
|
|
101
|
-
TimeoutError,
|
|
102
|
-
} from "@prompt-helm/sdk";
|
|
103
|
-
|
|
104
|
-
const ph = new PromptHelm({ apiKey: "<your-api-token>" });
|
|
105
|
-
|
|
106
|
-
try {
|
|
107
|
-
const result = await ph.execute({ promptSlug: "welcome-email" });
|
|
108
|
-
return result.output;
|
|
109
|
-
} catch (err) {
|
|
110
|
-
if (err instanceof AuthenticationError) {
|
|
111
|
-
// Rotate or refresh the API key.
|
|
112
|
-
} else if (err instanceof RateLimitError) {
|
|
113
|
-
// Back off and retry later.
|
|
114
|
-
} else if (err instanceof NotFoundError) {
|
|
115
|
-
// The slug does not exist in this environment.
|
|
116
|
-
} else if (err instanceof AuthorizationError) {
|
|
117
|
-
// The key cannot access this prompt.
|
|
118
|
-
} else if (err instanceof TimeoutError) {
|
|
119
|
-
// The request exceeded the configured timeout.
|
|
120
|
-
} else if (err instanceof ApiError) {
|
|
121
|
-
// 5xx or unknown server error. Safe to retry with backoff.
|
|
122
|
-
}
|
|
123
|
-
throw err;
|
|
124
|
-
}
|
|
44
|
+
// Pass `system` to your model exactly as you did before.
|
|
125
45
|
```
|
|
126
46
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
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`).
|
|
130
50
|
|
|
131
|
-
|
|
51
|
+
## Options
|
|
132
52
|
|
|
133
|
-
|
|
53
|
+
All optional when the environment variables are set.
|
|
134
54
|
|
|
135
|
-
|
|
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. |
|
|
136
63
|
|
|
137
|
-
|
|
64
|
+
## Errors
|
|
138
65
|
|
|
139
|
-
`
|
|
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.
|
|
140
68
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
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. |
|
|
149
77
|
|
|
150
|
-
|
|
78
|
+
After the first successful fetch, a failed background refresh keeps serving the cached prompt
|
|
79
|
+
and tries again after one ttl.
|
|
151
80
|
|
|
152
|
-
|
|
81
|
+
## Other languages
|
|
153
82
|
|
|
154
|
-
|
|
83
|
+
Any language can fetch the live version with one request:
|
|
155
84
|
|
|
156
|
-
|
|
157
|
-
-
|
|
158
|
-
|
|
159
|
-
|
|
85
|
+
```sh
|
|
86
|
+
curl https://prompthelm.app/v1/prompts/support-reply \
|
|
87
|
+
-H "Authorization: Bearer $PROMPTHELM_API_KEY"
|
|
88
|
+
```
|
|
160
89
|
|
|
161
|
-
##
|
|
90
|
+
## Links
|
|
162
91
|
|
|
163
|
-
|
|
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)
|
|
164
96
|
|
|
165
97
|
## License
|
|
166
98
|
|
|
167
|
-
MIT
|
|
99
|
+
MIT
|