@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 PromptHelm
3
+ Copyright (c) 2026 Runivox Ltd
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,167 +1,99 @@
1
1
  # @prompt-helm/sdk
2
2
 
3
- Official Node.js SDK for [PromptHelm](https://prompthelm.app) — call your managed prompts from any application.
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
- 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
+ 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
- ## Features
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
- - 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+
19
+ ## Install
15
20
 
16
- ## Installation
17
-
18
- ```bash
21
+ ```sh
19
22
  npm install @prompt-helm/sdk
20
23
  ```
21
24
 
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
- });
25
+ Create an API key in the dashboard and put it in your server's environment:
30
26
 
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)}`);
27
+ ```sh
28
+ PROMPTHELM_API_KEY=ph_…
38
29
  ```
39
30
 
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.
31
+ ## Use
43
32
 
44
33
  ```ts
45
34
  import { PromptHelm } from "@prompt-helm/sdk";
46
35
 
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`:
36
+ // One client for the whole app: it holds the cache.
37
+ export const ph = new PromptHelm();
62
38
 
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:
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
- ```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
- }
44
+ // Pass `system` to your model exactly as you did before.
125
45
  ```
126
46
 
127
- Every `PromptHelmError` exposes `statusCode`, `code`, and `correlationId` so failures can be filed against PromptHelm support with full traceability.
128
-
129
- ## API reference
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
- ### `new PromptHelm(config: PromptHelmConfig)`
51
+ ## Options
132
52
 
133
- Construct a client. Throws synchronously if `apiKey` is missing or malformed, if `baseURL` is invalid, or if `timeout` / `maxRetries` are out of range.
53
+ All optional when the environment variables are set.
134
54
 
135
- ### `execute(request, options?): Promise<ExecuteResponse>`
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
- Performs a single non-streaming gateway call.
64
+ ## Errors
138
65
 
139
- `request` accepts:
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
- - `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.
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
- `options.signal` lets you cancel mid-flight.
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
- ### `stream(request, options?): AsyncIterable<StreamEvent>`
81
+ ## Other languages
153
82
 
154
- Same request shape as `execute`. Yields:
83
+ Any language can fetch the live version with one request:
155
84
 
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.
85
+ ```sh
86
+ curl https://prompthelm.app/v1/prompts/support-reply \
87
+ -H "Authorization: Bearer $PROMPTHELM_API_KEY"
88
+ ```
160
89
 
161
- ## Versioning
90
+ ## Links
162
91
 
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.
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 — see [LICENSE](./LICENSE).
99
+ MIT