@prompt-helm/sdk 1.0.0 → 1.2.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/README.md +31 -0
- package/dist/cli.js +146 -0
- package/dist/index.cjs +30 -1
- package/dist/index.d.cts +19 -3
- package/dist/index.d.ts +19 -3
- package/dist/index.js +28 -1
- package/package.json +4 -1
package/README.md
CHANGED
|
@@ -59,6 +59,7 @@ All optional when the environment variables are set.
|
|
|
59
59
|
| `ttl` | `60000` | How long, in ms, a prompt is served before checking for a newer one. |
|
|
60
60
|
| `timeout` | `3000` | How long, in ms, one request may take. |
|
|
61
61
|
| `onError` | `console.warn` | Called with the error and the slug when a fallback or a cached prompt was served instead of failing. |
|
|
62
|
+
| `reportFallbacks` | `true` | Tells PromptHelm, by error code only, when a fallback or a cached prompt was served, so the prompt's page shows which app fell back and why. |
|
|
62
63
|
| `fetch` | global `fetch` | Your own fetch, for tests or a proxy. |
|
|
63
64
|
|
|
64
65
|
## Errors
|
|
@@ -78,6 +79,33 @@ Without a `fallback`, `get` throws them; with one, `onError` receives them.
|
|
|
78
79
|
After the first successful fetch, a failed background refresh keeps serving the cached prompt
|
|
79
80
|
and tries again after one ttl.
|
|
80
81
|
|
|
82
|
+
When a fallback or a cached prompt was served, the next request for that slug carries the error's
|
|
83
|
+
code (`x-prompthelm-fallback: missing_variables`), so the prompt's page in the dashboard shows
|
|
84
|
+
which key fell back and why. Only the code is sent, never the text or a variable's value; pass
|
|
85
|
+
`reportFallbacks: false` to send nothing.
|
|
86
|
+
|
|
87
|
+
## Keep fallbacks current
|
|
88
|
+
|
|
89
|
+
A fallback is only as good as its text, and a copy kept in your code drifts from what you
|
|
90
|
+
publish. `pull` writes every published prompt of the project to one file, keyed by slug:
|
|
91
|
+
|
|
92
|
+
```sh
|
|
93
|
+
npx @prompt-helm/sdk pull --out src/prompthelm.fallbacks.ts
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
import { fallbacks } from "./prompthelm.fallbacks";
|
|
98
|
+
|
|
99
|
+
const system = await ph.get("support-reply", {
|
|
100
|
+
vars: { company: "Acme", customer_name: user.name },
|
|
101
|
+
fallback: fallbacks["support-reply"],
|
|
102
|
+
});
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Run it in CI before the build, so every deploy carries the text that was live then. It reads
|
|
106
|
+
`PROMPTHELM_API_KEY` (and `PROMPTHELM_BASE_URL`), and writes JSON for a `.json` path or with
|
|
107
|
+
`--format json`. A prompt appears in the file once it's published.
|
|
108
|
+
|
|
81
109
|
## Other languages
|
|
82
110
|
|
|
83
111
|
Any language can fetch the live version with one request:
|
|
@@ -87,6 +115,9 @@ curl https://prompthelm.app/v1/prompts/support-reply \
|
|
|
87
115
|
-H "Authorization: Bearer $PROMPTHELM_API_KEY"
|
|
88
116
|
```
|
|
89
117
|
|
|
118
|
+
`GET /v1/prompts` returns every published prompt of the key's project at once, as
|
|
119
|
+
`{ "prompts": [ … ] }`.
|
|
120
|
+
|
|
90
121
|
## Links
|
|
91
122
|
|
|
92
123
|
- [Quickstart](https://prompthelm.app/quickstart)
|
package/dist/cli.js
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
// src/pull.ts
|
|
4
|
+
import { mkdir, writeFile } from "fs/promises";
|
|
5
|
+
import { dirname, extname } from "path";
|
|
6
|
+
|
|
7
|
+
// src/errors.ts
|
|
8
|
+
var PromptHelmError = class extends Error {
|
|
9
|
+
constructor(code, message, status) {
|
|
10
|
+
super(message);
|
|
11
|
+
this.code = code;
|
|
12
|
+
this.status = status;
|
|
13
|
+
}
|
|
14
|
+
code;
|
|
15
|
+
status;
|
|
16
|
+
name = "PromptHelmError";
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
// src/client.ts
|
|
20
|
+
var DEFAULT_BASE_URL = "https://prompthelm.app";
|
|
21
|
+
async function errorFromResponse(response) {
|
|
22
|
+
const body = await response.json().catch(() => null);
|
|
23
|
+
const message = body?.error?.message ?? `HTTP ${response.status}`;
|
|
24
|
+
const code = response.status === 401 || response.status === 403 ? "unauthorized" : response.status === 404 ? "not_found" : "server";
|
|
25
|
+
return new PromptHelmError(code, message, response.status);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
// src/pull.ts
|
|
29
|
+
var DEFAULT_OUT = "prompthelm.fallbacks.json";
|
|
30
|
+
var TIMEOUT_MS = 1e4;
|
|
31
|
+
var USAGE = `Usage: npx @prompt-helm/sdk pull [--out <file>] [--format json|ts]
|
|
32
|
+
|
|
33
|
+
Writes the live text of every published prompt in the project to one file, keyed by slug,
|
|
34
|
+
to pass to get() as its fallback.
|
|
35
|
+
|
|
36
|
+
--out <file> Where to write it. Default: ${DEFAULT_OUT}
|
|
37
|
+
--format <name> json or ts. Default: from the file's extension.
|
|
38
|
+
|
|
39
|
+
Reads PROMPTHELM_API_KEY, and PROMPTHELM_BASE_URL when it's set.`;
|
|
40
|
+
var TS_HEADER = `// Written by \`npx @prompt-helm/sdk pull\`: the live text of each prompt, to pass to get() as
|
|
41
|
+
// its fallback. Run it again to refresh it; edits here are overwritten.
|
|
42
|
+
`;
|
|
43
|
+
function parsePullArgs(args) {
|
|
44
|
+
let out = DEFAULT_OUT;
|
|
45
|
+
let format;
|
|
46
|
+
for (let index = 0; index < args.length; index++) {
|
|
47
|
+
const arg = args[index] ?? "";
|
|
48
|
+
if (arg === "-h" || arg === "--help") return "help";
|
|
49
|
+
const match = /^--(out|format)(?:=(.*))?$/.exec(arg);
|
|
50
|
+
if (!match) return { error: `Unknown argument: ${arg}` };
|
|
51
|
+
const value = match[2] ?? args[++index];
|
|
52
|
+
if (!value) return { error: `--${match[1]} needs a value` };
|
|
53
|
+
if (match[1] === "out") out = value;
|
|
54
|
+
else format = value;
|
|
55
|
+
}
|
|
56
|
+
format ??= formatFromExtension(out);
|
|
57
|
+
if (format === "json" || format === "ts") return { out, format };
|
|
58
|
+
return format === void 0 ? { error: `Can't tell the format from "${out}": pass --format json or --format ts` } : { error: `Unknown format "${format}": use json or ts` };
|
|
59
|
+
}
|
|
60
|
+
function formatFromExtension(path) {
|
|
61
|
+
const extension = extname(path).toLowerCase();
|
|
62
|
+
if (extension === ".json") return "json";
|
|
63
|
+
if (extension === ".ts" || extension === ".mts" || extension === ".cts") return "ts";
|
|
64
|
+
return void 0;
|
|
65
|
+
}
|
|
66
|
+
async function fetchLivePrompts(options) {
|
|
67
|
+
const request = options.fetch ?? globalThis.fetch;
|
|
68
|
+
let response;
|
|
69
|
+
try {
|
|
70
|
+
response = await request(`${options.baseUrl.replace(/\/+$/, "")}/v1/prompts`, {
|
|
71
|
+
headers: { authorization: `Bearer ${options.apiKey}`, accept: "application/json" },
|
|
72
|
+
signal: AbortSignal.timeout(TIMEOUT_MS)
|
|
73
|
+
});
|
|
74
|
+
} catch (error) {
|
|
75
|
+
if (error?.name === "TimeoutError") {
|
|
76
|
+
throw new PromptHelmError("timeout", `No response within ${TIMEOUT_MS} ms`);
|
|
77
|
+
}
|
|
78
|
+
throw new PromptHelmError("network", error instanceof Error ? error.message : String(error));
|
|
79
|
+
}
|
|
80
|
+
if (!response.ok) throw await errorFromResponse(response);
|
|
81
|
+
return (await response.json()).prompts;
|
|
82
|
+
}
|
|
83
|
+
function renderFallbacks(prompts, format) {
|
|
84
|
+
const sorted = [...prompts].sort((a, b) => a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0);
|
|
85
|
+
const json = JSON.stringify(Object.fromEntries(sorted.map((p) => [p.slug, p.content])), null, 2);
|
|
86
|
+
return format === "json" ? `${json}
|
|
87
|
+
` : `${TS_HEADER}export const fallbacks = ${json} as const;
|
|
88
|
+
`;
|
|
89
|
+
}
|
|
90
|
+
var nodeIO = () => ({
|
|
91
|
+
env: process.env,
|
|
92
|
+
log: (message) => console.log(message),
|
|
93
|
+
error: (message) => console.error(message),
|
|
94
|
+
write: async (path, text) => {
|
|
95
|
+
await mkdir(dirname(path), { recursive: true });
|
|
96
|
+
await writeFile(path, text);
|
|
97
|
+
}
|
|
98
|
+
});
|
|
99
|
+
async function runCli(argv, io = nodeIO()) {
|
|
100
|
+
const [command, ...rest] = argv;
|
|
101
|
+
if (command === "-h" || command === "--help") {
|
|
102
|
+
io.log(USAGE);
|
|
103
|
+
return 0;
|
|
104
|
+
}
|
|
105
|
+
if (command !== "pull") {
|
|
106
|
+
io.error(command ? `Unknown command: ${command}
|
|
107
|
+
|
|
108
|
+
${USAGE}` : USAGE);
|
|
109
|
+
return 1;
|
|
110
|
+
}
|
|
111
|
+
const parsed = parsePullArgs(rest);
|
|
112
|
+
if (parsed === "help") {
|
|
113
|
+
io.log(USAGE);
|
|
114
|
+
return 0;
|
|
115
|
+
}
|
|
116
|
+
if ("error" in parsed) {
|
|
117
|
+
io.error(`${parsed.error}
|
|
118
|
+
|
|
119
|
+
${USAGE}`);
|
|
120
|
+
return 1;
|
|
121
|
+
}
|
|
122
|
+
const apiKey = io.env.PROMPTHELM_API_KEY;
|
|
123
|
+
if (!apiKey) {
|
|
124
|
+
io.error("Set PROMPTHELM_API_KEY to an API key of the project to pull.");
|
|
125
|
+
return 1;
|
|
126
|
+
}
|
|
127
|
+
try {
|
|
128
|
+
const prompts = await fetchLivePrompts({
|
|
129
|
+
apiKey,
|
|
130
|
+
baseUrl: io.env.PROMPTHELM_BASE_URL || DEFAULT_BASE_URL,
|
|
131
|
+
fetch: io.fetch
|
|
132
|
+
});
|
|
133
|
+
await io.write(parsed.out, renderFallbacks(prompts, parsed.format));
|
|
134
|
+
io.log(
|
|
135
|
+
prompts.length === 0 ? `No published prompts yet; wrote an empty list to ${parsed.out}.` : `Wrote ${prompts.length} ${prompts.length === 1 ? "prompt" : "prompts"} to ${parsed.out}:
|
|
136
|
+
${prompts.map((p) => ` ${p.slug} v${p.version}`).join("\n")}`
|
|
137
|
+
);
|
|
138
|
+
return 0;
|
|
139
|
+
} catch (error) {
|
|
140
|
+
io.error(`PromptHelm: ${error instanceof Error ? error.message : String(error)}`);
|
|
141
|
+
return 1;
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
// src/cli.ts
|
|
146
|
+
process.exitCode = await runCli(process.argv.slice(2));
|
package/dist/index.cjs
CHANGED
|
@@ -20,6 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
|
|
|
20
20
|
// src/index.ts
|
|
21
21
|
var index_exports = {};
|
|
22
22
|
__export(index_exports, {
|
|
23
|
+
ERROR_CODES: () => ERROR_CODES,
|
|
24
|
+
FALLBACK_HEADER: () => FALLBACK_HEADER,
|
|
23
25
|
PromptHelm: () => PromptHelm,
|
|
24
26
|
PromptHelmError: () => PromptHelmError,
|
|
25
27
|
extractVariables: () => extractVariables,
|
|
@@ -28,6 +30,14 @@ __export(index_exports, {
|
|
|
28
30
|
module.exports = __toCommonJS(index_exports);
|
|
29
31
|
|
|
30
32
|
// src/errors.ts
|
|
33
|
+
var ERROR_CODES = [
|
|
34
|
+
"unauthorized",
|
|
35
|
+
"not_found",
|
|
36
|
+
"missing_variables",
|
|
37
|
+
"timeout",
|
|
38
|
+
"network",
|
|
39
|
+
"server"
|
|
40
|
+
];
|
|
31
41
|
var PromptHelmError = class extends Error {
|
|
32
42
|
constructor(code, message, status) {
|
|
33
43
|
super(message);
|
|
@@ -58,6 +68,7 @@ function render(template, vars = {}) {
|
|
|
58
68
|
|
|
59
69
|
// src/client.ts
|
|
60
70
|
var DEFAULT_BASE_URL = "https://prompthelm.app";
|
|
71
|
+
var FALLBACK_HEADER = "x-prompthelm-fallback";
|
|
61
72
|
var PromptHelm = class {
|
|
62
73
|
#apiKey;
|
|
63
74
|
#baseUrl;
|
|
@@ -67,6 +78,10 @@ var PromptHelm = class {
|
|
|
67
78
|
#onError;
|
|
68
79
|
#cache = /* @__PURE__ */ new Map();
|
|
69
80
|
#inflight = /* @__PURE__ */ new Map();
|
|
81
|
+
#reportFallbacks;
|
|
82
|
+
// Per slug, why the live text last couldn't be served, until a request carries it. An object,
|
|
83
|
+
// so a report made while that request is in flight isn't cleared with the one it carried.
|
|
84
|
+
#unreported = /* @__PURE__ */ new Map();
|
|
70
85
|
constructor(options = {}) {
|
|
71
86
|
const apiKey = options.apiKey ?? env("PROMPTHELM_API_KEY");
|
|
72
87
|
if (!apiKey) throw new Error("PromptHelm: pass apiKey or set PROMPTHELM_API_KEY");
|
|
@@ -77,6 +92,7 @@ var PromptHelm = class {
|
|
|
77
92
|
this.#timeout = options.timeout ?? 3e3;
|
|
78
93
|
this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
|
|
79
94
|
this.#onError = options.onError ?? ((error, slug) => console.warn(`[PromptHelm] ${slug}: ${error.message}`));
|
|
95
|
+
this.#reportFallbacks = options.reportFallbacks ?? true;
|
|
80
96
|
}
|
|
81
97
|
/** The live version of a prompt with its variables filled in. */
|
|
82
98
|
async get(slug, options = {}) {
|
|
@@ -86,6 +102,7 @@ var PromptHelm = class {
|
|
|
86
102
|
return render(entry.content, vars);
|
|
87
103
|
} catch (error) {
|
|
88
104
|
const failure = toPromptHelmError(error);
|
|
105
|
+
this.#remember(slug, failure.code);
|
|
89
106
|
if (fallback === void 0) throw failure;
|
|
90
107
|
this.#onError(failure, slug);
|
|
91
108
|
return render(fallback, vars);
|
|
@@ -97,11 +114,16 @@ var PromptHelm = class {
|
|
|
97
114
|
if (Date.now() - cached.fetchedAt >= this.#ttl) {
|
|
98
115
|
this.#load(slug).catch((error) => {
|
|
99
116
|
cached.fetchedAt = Date.now();
|
|
100
|
-
|
|
117
|
+
const failure = toPromptHelmError(error);
|
|
118
|
+
this.#remember(slug, failure.code);
|
|
119
|
+
this.#onError(failure, slug);
|
|
101
120
|
});
|
|
102
121
|
}
|
|
103
122
|
return Promise.resolve(cached);
|
|
104
123
|
}
|
|
124
|
+
#remember(slug, code) {
|
|
125
|
+
if (this.#reportFallbacks) this.#unreported.set(slug, { code });
|
|
126
|
+
}
|
|
105
127
|
#load(slug) {
|
|
106
128
|
let pending = this.#inflight.get(slug);
|
|
107
129
|
if (!pending) {
|
|
@@ -117,6 +139,8 @@ var PromptHelm = class {
|
|
|
117
139
|
accept: "application/json"
|
|
118
140
|
};
|
|
119
141
|
if (cached?.etag) headers["if-none-match"] = cached.etag;
|
|
142
|
+
const report = this.#unreported.get(slug);
|
|
143
|
+
if (report) headers[FALLBACK_HEADER] = report.code;
|
|
120
144
|
let response;
|
|
121
145
|
try {
|
|
122
146
|
response = await this.#fetch(`${this.#baseUrl}/v1/prompts/${encodeURIComponent(slug)}`, {
|
|
@@ -129,6 +153,9 @@ var PromptHelm = class {
|
|
|
129
153
|
}
|
|
130
154
|
throw new PromptHelmError("network", error instanceof Error ? error.message : String(error));
|
|
131
155
|
}
|
|
156
|
+
if (report && (response.ok || response.status === 304) && this.#unreported.get(slug) === report) {
|
|
157
|
+
this.#unreported.delete(slug);
|
|
158
|
+
}
|
|
132
159
|
if (response.status === 304 && cached) {
|
|
133
160
|
const entry2 = { ...cached, fetchedAt: Date.now() };
|
|
134
161
|
this.#cache.set(slug, entry2);
|
|
@@ -160,6 +187,8 @@ function toPromptHelmError(error) {
|
|
|
160
187
|
}
|
|
161
188
|
// Annotate the CommonJS export names for ESM import in node:
|
|
162
189
|
0 && (module.exports = {
|
|
190
|
+
ERROR_CODES,
|
|
191
|
+
FALLBACK_HEADER,
|
|
163
192
|
PromptHelm,
|
|
164
193
|
PromptHelmError,
|
|
165
194
|
extractVariables,
|
package/dist/index.d.cts
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
-
|
|
1
|
+
/** Every code a PromptHelmError carries. The server checks fallback reports against this list. */
|
|
2
|
+
declare const ERROR_CODES: readonly ["unauthorized", "not_found", "missing_variables", "timeout", "network", "server"];
|
|
3
|
+
type PromptHelmErrorCode = (typeof ERROR_CODES)[number];
|
|
2
4
|
declare class PromptHelmError extends Error {
|
|
3
5
|
readonly code: PromptHelmErrorCode;
|
|
4
6
|
readonly status?: number | undefined;
|
|
@@ -22,6 +24,15 @@ interface PromptPayload {
|
|
|
22
24
|
content: string;
|
|
23
25
|
variables: string[];
|
|
24
26
|
}
|
|
27
|
+
/**
|
|
28
|
+
* Sent with the next request for a slug after `get()` couldn't serve its live text: the error's
|
|
29
|
+
* code alone, never any text or variable value. The server records it for the prompt page.
|
|
30
|
+
*/
|
|
31
|
+
declare const FALLBACK_HEADER = "x-prompthelm-fallback";
|
|
32
|
+
/** Body of `GET /v1/prompts`: every published prompt of the key's project, by slug. */
|
|
33
|
+
interface PromptListPayload {
|
|
34
|
+
prompts: PromptPayload[];
|
|
35
|
+
}
|
|
25
36
|
interface PromptHelmOptions {
|
|
26
37
|
/** Defaults to the PROMPTHELM_API_KEY environment variable. */
|
|
27
38
|
apiKey?: string;
|
|
@@ -34,6 +45,11 @@ interface PromptHelmOptions {
|
|
|
34
45
|
fetch?: typeof globalThis.fetch;
|
|
35
46
|
/** Told whenever a fallback or a stale prompt was served instead of failing. */
|
|
36
47
|
onError?: (error: PromptHelmError, slug: string) => void;
|
|
48
|
+
/**
|
|
49
|
+
* Whether to tell PromptHelm, by error code only, when the live text couldn't be served, so the
|
|
50
|
+
* prompt's page shows it. Defaults to true.
|
|
51
|
+
*/
|
|
52
|
+
reportFallbacks?: boolean;
|
|
37
53
|
}
|
|
38
54
|
interface GetOptions {
|
|
39
55
|
vars?: Vars;
|
|
@@ -50,5 +66,5 @@ declare class PromptHelm {
|
|
|
50
66
|
get(slug: string, options?: GetOptions): Promise<string>;
|
|
51
67
|
}
|
|
52
68
|
|
|
53
|
-
export { PromptHelm, PromptHelmError, extractVariables, render };
|
|
54
|
-
export type { GetOptions, PromptHelmErrorCode, PromptHelmOptions, PromptPayload, Vars };
|
|
69
|
+
export { ERROR_CODES, FALLBACK_HEADER, PromptHelm, PromptHelmError, extractVariables, render };
|
|
70
|
+
export type { GetOptions, PromptHelmErrorCode, PromptHelmOptions, PromptListPayload, PromptPayload, Vars };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
-
|
|
1
|
+
/** Every code a PromptHelmError carries. The server checks fallback reports against this list. */
|
|
2
|
+
declare const ERROR_CODES: readonly ["unauthorized", "not_found", "missing_variables", "timeout", "network", "server"];
|
|
3
|
+
type PromptHelmErrorCode = (typeof ERROR_CODES)[number];
|
|
2
4
|
declare class PromptHelmError extends Error {
|
|
3
5
|
readonly code: PromptHelmErrorCode;
|
|
4
6
|
readonly status?: number | undefined;
|
|
@@ -22,6 +24,15 @@ interface PromptPayload {
|
|
|
22
24
|
content: string;
|
|
23
25
|
variables: string[];
|
|
24
26
|
}
|
|
27
|
+
/**
|
|
28
|
+
* Sent with the next request for a slug after `get()` couldn't serve its live text: the error's
|
|
29
|
+
* code alone, never any text or variable value. The server records it for the prompt page.
|
|
30
|
+
*/
|
|
31
|
+
declare const FALLBACK_HEADER = "x-prompthelm-fallback";
|
|
32
|
+
/** Body of `GET /v1/prompts`: every published prompt of the key's project, by slug. */
|
|
33
|
+
interface PromptListPayload {
|
|
34
|
+
prompts: PromptPayload[];
|
|
35
|
+
}
|
|
25
36
|
interface PromptHelmOptions {
|
|
26
37
|
/** Defaults to the PROMPTHELM_API_KEY environment variable. */
|
|
27
38
|
apiKey?: string;
|
|
@@ -34,6 +45,11 @@ interface PromptHelmOptions {
|
|
|
34
45
|
fetch?: typeof globalThis.fetch;
|
|
35
46
|
/** Told whenever a fallback or a stale prompt was served instead of failing. */
|
|
36
47
|
onError?: (error: PromptHelmError, slug: string) => void;
|
|
48
|
+
/**
|
|
49
|
+
* Whether to tell PromptHelm, by error code only, when the live text couldn't be served, so the
|
|
50
|
+
* prompt's page shows it. Defaults to true.
|
|
51
|
+
*/
|
|
52
|
+
reportFallbacks?: boolean;
|
|
37
53
|
}
|
|
38
54
|
interface GetOptions {
|
|
39
55
|
vars?: Vars;
|
|
@@ -50,5 +66,5 @@ declare class PromptHelm {
|
|
|
50
66
|
get(slug: string, options?: GetOptions): Promise<string>;
|
|
51
67
|
}
|
|
52
68
|
|
|
53
|
-
export { PromptHelm, PromptHelmError, extractVariables, render };
|
|
54
|
-
export type { GetOptions, PromptHelmErrorCode, PromptHelmOptions, PromptPayload, Vars };
|
|
69
|
+
export { ERROR_CODES, FALLBACK_HEADER, PromptHelm, PromptHelmError, extractVariables, render };
|
|
70
|
+
export type { GetOptions, PromptHelmErrorCode, PromptHelmOptions, PromptListPayload, PromptPayload, Vars };
|
package/dist/index.js
CHANGED
|
@@ -1,4 +1,12 @@
|
|
|
1
1
|
// src/errors.ts
|
|
2
|
+
var ERROR_CODES = [
|
|
3
|
+
"unauthorized",
|
|
4
|
+
"not_found",
|
|
5
|
+
"missing_variables",
|
|
6
|
+
"timeout",
|
|
7
|
+
"network",
|
|
8
|
+
"server"
|
|
9
|
+
];
|
|
2
10
|
var PromptHelmError = class extends Error {
|
|
3
11
|
constructor(code, message, status) {
|
|
4
12
|
super(message);
|
|
@@ -29,6 +37,7 @@ function render(template, vars = {}) {
|
|
|
29
37
|
|
|
30
38
|
// src/client.ts
|
|
31
39
|
var DEFAULT_BASE_URL = "https://prompthelm.app";
|
|
40
|
+
var FALLBACK_HEADER = "x-prompthelm-fallback";
|
|
32
41
|
var PromptHelm = class {
|
|
33
42
|
#apiKey;
|
|
34
43
|
#baseUrl;
|
|
@@ -38,6 +47,10 @@ var PromptHelm = class {
|
|
|
38
47
|
#onError;
|
|
39
48
|
#cache = /* @__PURE__ */ new Map();
|
|
40
49
|
#inflight = /* @__PURE__ */ new Map();
|
|
50
|
+
#reportFallbacks;
|
|
51
|
+
// Per slug, why the live text last couldn't be served, until a request carries it. An object,
|
|
52
|
+
// so a report made while that request is in flight isn't cleared with the one it carried.
|
|
53
|
+
#unreported = /* @__PURE__ */ new Map();
|
|
41
54
|
constructor(options = {}) {
|
|
42
55
|
const apiKey = options.apiKey ?? env("PROMPTHELM_API_KEY");
|
|
43
56
|
if (!apiKey) throw new Error("PromptHelm: pass apiKey or set PROMPTHELM_API_KEY");
|
|
@@ -48,6 +61,7 @@ var PromptHelm = class {
|
|
|
48
61
|
this.#timeout = options.timeout ?? 3e3;
|
|
49
62
|
this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
|
|
50
63
|
this.#onError = options.onError ?? ((error, slug) => console.warn(`[PromptHelm] ${slug}: ${error.message}`));
|
|
64
|
+
this.#reportFallbacks = options.reportFallbacks ?? true;
|
|
51
65
|
}
|
|
52
66
|
/** The live version of a prompt with its variables filled in. */
|
|
53
67
|
async get(slug, options = {}) {
|
|
@@ -57,6 +71,7 @@ var PromptHelm = class {
|
|
|
57
71
|
return render(entry.content, vars);
|
|
58
72
|
} catch (error) {
|
|
59
73
|
const failure = toPromptHelmError(error);
|
|
74
|
+
this.#remember(slug, failure.code);
|
|
60
75
|
if (fallback === void 0) throw failure;
|
|
61
76
|
this.#onError(failure, slug);
|
|
62
77
|
return render(fallback, vars);
|
|
@@ -68,11 +83,16 @@ var PromptHelm = class {
|
|
|
68
83
|
if (Date.now() - cached.fetchedAt >= this.#ttl) {
|
|
69
84
|
this.#load(slug).catch((error) => {
|
|
70
85
|
cached.fetchedAt = Date.now();
|
|
71
|
-
|
|
86
|
+
const failure = toPromptHelmError(error);
|
|
87
|
+
this.#remember(slug, failure.code);
|
|
88
|
+
this.#onError(failure, slug);
|
|
72
89
|
});
|
|
73
90
|
}
|
|
74
91
|
return Promise.resolve(cached);
|
|
75
92
|
}
|
|
93
|
+
#remember(slug, code) {
|
|
94
|
+
if (this.#reportFallbacks) this.#unreported.set(slug, { code });
|
|
95
|
+
}
|
|
76
96
|
#load(slug) {
|
|
77
97
|
let pending = this.#inflight.get(slug);
|
|
78
98
|
if (!pending) {
|
|
@@ -88,6 +108,8 @@ var PromptHelm = class {
|
|
|
88
108
|
accept: "application/json"
|
|
89
109
|
};
|
|
90
110
|
if (cached?.etag) headers["if-none-match"] = cached.etag;
|
|
111
|
+
const report = this.#unreported.get(slug);
|
|
112
|
+
if (report) headers[FALLBACK_HEADER] = report.code;
|
|
91
113
|
let response;
|
|
92
114
|
try {
|
|
93
115
|
response = await this.#fetch(`${this.#baseUrl}/v1/prompts/${encodeURIComponent(slug)}`, {
|
|
@@ -100,6 +122,9 @@ var PromptHelm = class {
|
|
|
100
122
|
}
|
|
101
123
|
throw new PromptHelmError("network", error instanceof Error ? error.message : String(error));
|
|
102
124
|
}
|
|
125
|
+
if (report && (response.ok || response.status === 304) && this.#unreported.get(slug) === report) {
|
|
126
|
+
this.#unreported.delete(slug);
|
|
127
|
+
}
|
|
103
128
|
if (response.status === 304 && cached) {
|
|
104
129
|
const entry2 = { ...cached, fetchedAt: Date.now() };
|
|
105
130
|
this.#cache.set(slug, entry2);
|
|
@@ -130,6 +155,8 @@ function toPromptHelmError(error) {
|
|
|
130
155
|
return new PromptHelmError("server", error instanceof Error ? error.message : String(error));
|
|
131
156
|
}
|
|
132
157
|
export {
|
|
158
|
+
ERROR_CODES,
|
|
159
|
+
FALLBACK_HEADER,
|
|
133
160
|
PromptHelm,
|
|
134
161
|
PromptHelmError,
|
|
135
162
|
extractVariables,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@prompt-helm/sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"description": "Fetch your PromptHelm prompts at runtime, so changing a prompt needs no redeploy.",
|
|
5
5
|
"homepage": "https://prompthelm.app/quickstart",
|
|
6
6
|
"keywords": [
|
|
@@ -29,6 +29,9 @@
|
|
|
29
29
|
}
|
|
30
30
|
}
|
|
31
31
|
},
|
|
32
|
+
"bin": {
|
|
33
|
+
"prompthelm": "./dist/cli.js"
|
|
34
|
+
},
|
|
32
35
|
"files": [
|
|
33
36
|
"dist"
|
|
34
37
|
],
|