@prompt-helm/sdk 1.1.0 → 1.2.1

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 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
- this.#onError(toPromptHelmError(error), slug);
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
- type PromptHelmErrorCode = "unauthorized" | "not_found" | "missing_variables" | "timeout" | "network" | "server";
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
- type PromptHelmErrorCode = "unauthorized" | "not_found" | "missing_variables" | "timeout" | "network" | "server";
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
- this.#onError(toPromptHelmError(error), slug);
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,8 +1,15 @@
1
1
  {
2
2
  "name": "@prompt-helm/sdk",
3
- "version": "1.1.0",
3
+ "version": "1.2.1",
4
4
  "description": "Fetch your PromptHelm prompts at runtime, so changing a prompt needs no redeploy.",
5
5
  "homepage": "https://prompthelm.app/quickstart",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/Runivox/prompthelm-node.git"
9
+ },
10
+ "bugs": {
11
+ "url": "https://github.com/Runivox/prompthelm-node/issues"
12
+ },
6
13
  "keywords": [
7
14
  "prompt",
8
15
  "prompt-management",
@@ -41,9 +48,13 @@
41
48
  "dev": "tsup --watch",
42
49
  "test": "vitest run",
43
50
  "typecheck": "tsc --noEmit",
51
+ "lint": "biome check",
52
+ "format": "biome format --write",
53
+ "smoke": "node scripts/smoke.mjs",
44
54
  "prepublishOnly": "npm run typecheck && npm test && npm run build"
45
55
  },
46
56
  "devDependencies": {
57
+ "@biomejs/biome": "2.4.2",
47
58
  "@types/node": "^22",
48
59
  "tsup": "^9.0.0",
49
60
  "typescript": "~6.0.3",