@prompt-helm/sdk 1.1.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 +6 -0
- package/dist/index.cjs +30 -1
- package/dist/index.d.cts +14 -2
- package/dist/index.d.ts +14 -2
- package/dist/index.js +28 -1
- package/package.json +1 -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,11 @@ 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
|
+
|
|
81
87
|
## Keep fallbacks current
|
|
82
88
|
|
|
83
89
|
A fallback is only as good as its text, and a copy kept in your code drifts from what you
|
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,11 @@ 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";
|
|
25
32
|
/** Body of `GET /v1/prompts`: every published prompt of the key's project, by slug. */
|
|
26
33
|
interface PromptListPayload {
|
|
27
34
|
prompts: PromptPayload[];
|
|
@@ -38,6 +45,11 @@ interface PromptHelmOptions {
|
|
|
38
45
|
fetch?: typeof globalThis.fetch;
|
|
39
46
|
/** Told whenever a fallback or a stale prompt was served instead of failing. */
|
|
40
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;
|
|
41
53
|
}
|
|
42
54
|
interface GetOptions {
|
|
43
55
|
vars?: Vars;
|
|
@@ -54,5 +66,5 @@ declare class PromptHelm {
|
|
|
54
66
|
get(slug: string, options?: GetOptions): Promise<string>;
|
|
55
67
|
}
|
|
56
68
|
|
|
57
|
-
export { PromptHelm, PromptHelmError, extractVariables, render };
|
|
69
|
+
export { ERROR_CODES, FALLBACK_HEADER, PromptHelm, PromptHelmError, extractVariables, render };
|
|
58
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,11 @@ 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";
|
|
25
32
|
/** Body of `GET /v1/prompts`: every published prompt of the key's project, by slug. */
|
|
26
33
|
interface PromptListPayload {
|
|
27
34
|
prompts: PromptPayload[];
|
|
@@ -38,6 +45,11 @@ interface PromptHelmOptions {
|
|
|
38
45
|
fetch?: typeof globalThis.fetch;
|
|
39
46
|
/** Told whenever a fallback or a stale prompt was served instead of failing. */
|
|
40
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;
|
|
41
53
|
}
|
|
42
54
|
interface GetOptions {
|
|
43
55
|
vars?: Vars;
|
|
@@ -54,5 +66,5 @@ declare class PromptHelm {
|
|
|
54
66
|
get(slug: string, options?: GetOptions): Promise<string>;
|
|
55
67
|
}
|
|
56
68
|
|
|
57
|
-
export { PromptHelm, PromptHelmError, extractVariables, render };
|
|
69
|
+
export { ERROR_CODES, FALLBACK_HEADER, PromptHelm, PromptHelmError, extractVariables, render };
|
|
58
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