@prompt-helm/sdk 1.0.0 → 1.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/README.md +25 -0
- package/dist/cli.js +146 -0
- package/dist/index.d.cts +5 -1
- package/dist/index.d.ts +5 -1
- package/package.json +4 -1
package/README.md
CHANGED
|
@@ -78,6 +78,28 @@ Without a `fallback`, `get` throws them; with one, `onError` receives them.
|
|
|
78
78
|
After the first successful fetch, a failed background refresh keeps serving the cached prompt
|
|
79
79
|
and tries again after one ttl.
|
|
80
80
|
|
|
81
|
+
## Keep fallbacks current
|
|
82
|
+
|
|
83
|
+
A fallback is only as good as its text, and a copy kept in your code drifts from what you
|
|
84
|
+
publish. `pull` writes every published prompt of the project to one file, keyed by slug:
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
npx @prompt-helm/sdk pull --out src/prompthelm.fallbacks.ts
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
import { fallbacks } from "./prompthelm.fallbacks";
|
|
92
|
+
|
|
93
|
+
const system = await ph.get("support-reply", {
|
|
94
|
+
vars: { company: "Acme", customer_name: user.name },
|
|
95
|
+
fallback: fallbacks["support-reply"],
|
|
96
|
+
});
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Run it in CI before the build, so every deploy carries the text that was live then. It reads
|
|
100
|
+
`PROMPTHELM_API_KEY` (and `PROMPTHELM_BASE_URL`), and writes JSON for a `.json` path or with
|
|
101
|
+
`--format json`. A prompt appears in the file once it's published.
|
|
102
|
+
|
|
81
103
|
## Other languages
|
|
82
104
|
|
|
83
105
|
Any language can fetch the live version with one request:
|
|
@@ -87,6 +109,9 @@ curl https://prompthelm.app/v1/prompts/support-reply \
|
|
|
87
109
|
-H "Authorization: Bearer $PROMPTHELM_API_KEY"
|
|
88
110
|
```
|
|
89
111
|
|
|
112
|
+
`GET /v1/prompts` returns every published prompt of the key's project at once, as
|
|
113
|
+
`{ "prompts": [ … ] }`.
|
|
114
|
+
|
|
90
115
|
## Links
|
|
91
116
|
|
|
92
117
|
- [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.d.cts
CHANGED
|
@@ -22,6 +22,10 @@ interface PromptPayload {
|
|
|
22
22
|
content: string;
|
|
23
23
|
variables: string[];
|
|
24
24
|
}
|
|
25
|
+
/** Body of `GET /v1/prompts`: every published prompt of the key's project, by slug. */
|
|
26
|
+
interface PromptListPayload {
|
|
27
|
+
prompts: PromptPayload[];
|
|
28
|
+
}
|
|
25
29
|
interface PromptHelmOptions {
|
|
26
30
|
/** Defaults to the PROMPTHELM_API_KEY environment variable. */
|
|
27
31
|
apiKey?: string;
|
|
@@ -51,4 +55,4 @@ declare class PromptHelm {
|
|
|
51
55
|
}
|
|
52
56
|
|
|
53
57
|
export { PromptHelm, PromptHelmError, extractVariables, render };
|
|
54
|
-
export type { GetOptions, PromptHelmErrorCode, PromptHelmOptions, PromptPayload, Vars };
|
|
58
|
+
export type { GetOptions, PromptHelmErrorCode, PromptHelmOptions, PromptListPayload, PromptPayload, Vars };
|
package/dist/index.d.ts
CHANGED
|
@@ -22,6 +22,10 @@ interface PromptPayload {
|
|
|
22
22
|
content: string;
|
|
23
23
|
variables: string[];
|
|
24
24
|
}
|
|
25
|
+
/** Body of `GET /v1/prompts`: every published prompt of the key's project, by slug. */
|
|
26
|
+
interface PromptListPayload {
|
|
27
|
+
prompts: PromptPayload[];
|
|
28
|
+
}
|
|
25
29
|
interface PromptHelmOptions {
|
|
26
30
|
/** Defaults to the PROMPTHELM_API_KEY environment variable. */
|
|
27
31
|
apiKey?: string;
|
|
@@ -51,4 +55,4 @@ declare class PromptHelm {
|
|
|
51
55
|
}
|
|
52
56
|
|
|
53
57
|
export { PromptHelm, PromptHelmError, extractVariables, render };
|
|
54
|
-
export type { GetOptions, PromptHelmErrorCode, PromptHelmOptions, PromptPayload, Vars };
|
|
58
|
+
export type { GetOptions, PromptHelmErrorCode, PromptHelmOptions, PromptListPayload, PromptPayload, Vars };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@prompt-helm/sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.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
|
],
|