@prompt-helm/sdk 0.1.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 +21 -0
- package/README.md +167 -0
- package/dist/index.cjs +566 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +114 -0
- package/dist/index.d.ts +114 -0
- package/dist/index.js +557 -0
- package/dist/index.js.map +1 -0
- package/package.json +74 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 PromptHelm
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
# @prompt-helm/sdk
|
|
2
|
+
|
|
3
|
+
Official Node.js SDK for [PromptHelm](https://prompthelm.app) — call your managed prompts from any application.
|
|
4
|
+
|
|
5
|
+
PromptHelm is an enterprise LLMOps control plane: versioned prompts, encrypted provider keys, a multi-provider gateway (OpenAI, Anthropic, Gemini, DeepSeek), and first-class cost / latency / cache analytics. This SDK gives you a typed, ergonomic client for the PromptHelm gateway.
|
|
6
|
+
|
|
7
|
+
## Features
|
|
8
|
+
|
|
9
|
+
- Typed `execute` and `stream` methods backed by the PromptHelm gateway
|
|
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+
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install @prompt-helm/sdk
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Quickstart
|
|
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
|
+
});
|
|
30
|
+
|
|
31
|
+
const result = await ph.execute({
|
|
32
|
+
promptSlug: "welcome-email",
|
|
33
|
+
variables: { name: "World" },
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
console.log(result.output);
|
|
37
|
+
console.log(`Tokens: ${result.totalTokens}, cost: $${result.cost.toFixed(6)}`);
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Streaming
|
|
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.
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
import { PromptHelm } from "@prompt-helm/sdk";
|
|
46
|
+
|
|
47
|
+
const ph = new PromptHelm({ apiKey: "<your-api-token>" });
|
|
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`:
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
const controller = new AbortController();
|
|
65
|
+
setTimeout(() => controller.abort(), 5_000);
|
|
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:
|
|
92
|
+
|
|
93
|
+
```ts
|
|
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
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Every `PromptHelmError` exposes `statusCode`, `code`, and `correlationId` so failures can be filed against PromptHelm support with full traceability.
|
|
128
|
+
|
|
129
|
+
## API reference
|
|
130
|
+
|
|
131
|
+
### `new PromptHelm(config: PromptHelmConfig)`
|
|
132
|
+
|
|
133
|
+
Construct a client. Throws synchronously if `apiKey` is missing or malformed, if `baseURL` is invalid, or if `timeout` / `maxRetries` are out of range.
|
|
134
|
+
|
|
135
|
+
### `execute(request, options?): Promise<ExecuteResponse>`
|
|
136
|
+
|
|
137
|
+
Performs a single non-streaming gateway call.
|
|
138
|
+
|
|
139
|
+
`request` accepts:
|
|
140
|
+
|
|
141
|
+
- `promptSlug?: string` — managed prompt slug.
|
|
142
|
+
- `promptId?: string` — managed prompt id (alternative to `promptSlug`).
|
|
143
|
+
- `variables?: Record<string, string>` — template variables.
|
|
144
|
+
- `system?: string`, `user?: string` — ad-hoc messages.
|
|
145
|
+
- `model?: string` — override the prompt's default model.
|
|
146
|
+
- `temperature?`, `maxTokens?`, `topP?`, `stopSequences?` — provider parameters.
|
|
147
|
+
- `environment?: "production" | "development"` — which prompt branch to resolve.
|
|
148
|
+
- `timeoutMs?: number` — server-side execution deadline.
|
|
149
|
+
|
|
150
|
+
`options.signal` lets you cancel mid-flight.
|
|
151
|
+
|
|
152
|
+
### `stream(request, options?): AsyncIterable<StreamEvent>`
|
|
153
|
+
|
|
154
|
+
Same request shape as `execute`. Yields:
|
|
155
|
+
|
|
156
|
+
- `{ type: "chunk", content: string }` — incremental output.
|
|
157
|
+
- `{ type: "done", inputTokens, outputTokens, totalTokens, cost, model, latencyMs }` — final usage and pricing.
|
|
158
|
+
|
|
159
|
+
If the server emits `{ type: "error" }`, the iterator throws an `ApiError`. If the external `AbortSignal` fires, the iterator stops and the underlying HTTP request is cancelled.
|
|
160
|
+
|
|
161
|
+
## Versioning
|
|
162
|
+
|
|
163
|
+
`@prompt-helm/sdk` follows [Semantic Versioning](https://semver.org). Breaking changes will only ship on a major version bump. See the changelog for details.
|
|
164
|
+
|
|
165
|
+
## License
|
|
166
|
+
|
|
167
|
+
MIT — see [LICENSE](./LICENSE).
|