@prompt-helm/sdk 0.2.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/dist/index.d.cts CHANGED
@@ -1,122 +1,54 @@
1
- type Environment = "production" | "development";
2
- interface ExecuteRequest {
3
- promptSlug?: string;
4
- promptId?: string;
5
- variables?: Record<string, string>;
6
- system?: string;
7
- user?: string;
8
- model?: string;
9
- temperature?: number;
10
- maxTokens?: number;
11
- topP?: number;
12
- stopSequences?: string[];
13
- environment?: Environment;
14
- timeoutMs?: number;
15
- }
16
- interface ExecuteResponse {
17
- id: string;
18
- output: string;
19
- model: string;
20
- inputTokens: number;
21
- outputTokens: number;
22
- totalTokens: number;
23
- latencyMs: number;
24
- cost: number;
25
- timestamp: string;
26
- }
27
- interface StreamChunkEvent {
28
- type: "chunk";
29
- content: string;
30
- }
31
- interface StreamDoneEvent {
32
- type: "done";
33
- inputTokens: number;
34
- outputTokens: number;
35
- totalTokens: number;
36
- cost: number;
37
- model: string;
38
- latencyMs: number;
39
- }
40
- interface StreamErrorEvent {
41
- type: "error";
42
- errorCode: string;
43
- message: string;
44
- requestId?: string;
1
+ type PromptHelmErrorCode = "unauthorized" | "not_found" | "missing_variables" | "timeout" | "network" | "server";
2
+ declare class PromptHelmError extends Error {
3
+ readonly code: PromptHelmErrorCode;
4
+ readonly status?: number | undefined;
5
+ readonly name = "PromptHelmError";
6
+ constructor(code: PromptHelmErrorCode, message: string, status?: number | undefined);
45
7
  }
46
- type StreamEvent = StreamChunkEvent | StreamDoneEvent | StreamErrorEvent;
8
+
9
+ type Vars = Readonly<Record<string, string | number | boolean>>;
10
+ /** The `{{variables}}` a template uses, in order of first appearance. */
11
+ declare function extractVariables(template: string): string[];
47
12
  /**
48
- * JSON error envelope returned by the PromptHelm API for non-2xx responses.
49
- * All five fields are always present on the wire; `message` may be a single
50
- * string or an array of validation messages.
13
+ * Fills in every `{{variable}}`. Throws `missing_variables` rather than leaving a
14
+ * placeholder in the text, because a half-filled prompt reaches the model silently.
51
15
  */
52
- interface ErrorEnvelope {
53
- statusCode: number;
54
- errorCode: string;
55
- message: string | string[];
56
- timestamp: string;
57
- requestId: string;
58
- }
59
- interface RequestOptions {
60
- signal?: AbortSignal;
61
- }
16
+ declare function render(template: string, vars?: Vars): string;
62
17
 
63
- interface PromptHelmConfig {
64
- apiKey: string;
65
- baseURL?: string;
18
+ /** Body of `GET /v1/prompts/:slug`. The server types its response with this too. */
19
+ interface PromptPayload {
20
+ slug: string;
21
+ version: number;
22
+ content: string;
23
+ variables: string[];
24
+ }
25
+ interface PromptHelmOptions {
26
+ /** Defaults to the PROMPTHELM_API_KEY environment variable. */
27
+ apiKey?: string;
28
+ /** Defaults to PROMPTHELM_BASE_URL, then https://prompthelm.app. */
29
+ baseUrl?: string;
30
+ /** How long a fetched prompt is served before checking for a newer version, in ms. */
31
+ ttl?: number;
32
+ /** Per-request timeout in ms. */
66
33
  timeout?: number;
67
- maxRetries?: number;
34
+ fetch?: typeof globalThis.fetch;
35
+ /** Told whenever a fallback or a stale prompt was served instead of failing. */
36
+ onError?: (error: PromptHelmError, slug: string) => void;
37
+ }
38
+ interface GetOptions {
39
+ vars?: Vars;
68
40
  /**
69
- * Prefix appended to the SDK's User-Agent header. Use it to identify the
70
- * application or service making the call (helpful when one tenant runs
71
- * many apps against the same prompt). Example: `"my-checkout-service/1.4.2"`.
41
+ * Served when PromptHelm can't be reached, the prompt doesn't exist, or the live
42
+ * version uses a variable this call doesn't pass. Without it those cases throw.
72
43
  */
73
- userAgent?: string;
74
- fetch?: typeof globalThis.fetch;
75
- headers?: Record<string, string>;
44
+ fallback?: string;
76
45
  }
77
46
  declare class PromptHelm {
78
- private readonly apiKey;
79
- private readonly baseURL;
80
- private readonly timeout;
81
- private readonly maxRetries;
82
- private readonly fetchFn;
83
- private readonly extraHeaders;
84
- private readonly userAgent;
85
- constructor(config: PromptHelmConfig);
86
- execute(request: ExecuteRequest, options?: RequestOptions): Promise<ExecuteResponse>;
87
- stream(request: ExecuteRequest, options?: RequestOptions): AsyncIterable<StreamEvent>;
88
- private executeOnce;
89
- private buildHeaders;
90
- private isRetryable;
91
- }
92
-
93
- declare class PromptHelmError extends Error {
94
- /** HTTP status code (or the inferred status for SSE error events). */
95
- readonly statusCode: number;
96
- /** Machine-readable error code from the API envelope, e.g. `VALIDATION_ERROR`. */
97
- readonly errorCode: string | undefined;
98
- /** Request correlation id — quote this when contacting PromptHelm support. */
99
- readonly requestId: string | undefined;
100
- constructor(statusCode: number, errorCode: string | undefined, requestId: string | undefined, message: string);
101
- }
102
- declare class AuthenticationError extends PromptHelmError {
103
- constructor(statusCode: number, errorCode: string | undefined, requestId: string | undefined, message: string);
104
- }
105
- declare class AuthorizationError extends PromptHelmError {
106
- constructor(statusCode: number, errorCode: string | undefined, requestId: string | undefined, message: string);
107
- }
108
- declare class RateLimitError extends PromptHelmError {
109
- constructor(statusCode: number, errorCode: string | undefined, requestId: string | undefined, message: string);
110
- }
111
- declare class NotFoundError extends PromptHelmError {
112
- constructor(statusCode: number, errorCode: string | undefined, requestId: string | undefined, message: string);
113
- }
114
- declare class ApiError extends PromptHelmError {
115
- constructor(statusCode: number, errorCode: string | undefined, requestId: string | undefined, message: string);
116
- }
117
- declare class TimeoutError extends Error {
118
- readonly timeoutMs: number;
119
- constructor(timeoutMs: number, message?: string);
47
+ #private;
48
+ constructor(options?: PromptHelmOptions);
49
+ /** The live version of a prompt with its variables filled in. */
50
+ get(slug: string, options?: GetOptions): Promise<string>;
120
51
  }
121
52
 
122
- export { ApiError, AuthenticationError, AuthorizationError, type Environment, type ErrorEnvelope, type ExecuteRequest, type ExecuteResponse, NotFoundError, PromptHelm, type PromptHelmConfig, PromptHelmError, RateLimitError, type RequestOptions, type StreamChunkEvent, type StreamDoneEvent, type StreamErrorEvent, type StreamEvent, TimeoutError };
53
+ export { PromptHelm, PromptHelmError, extractVariables, render };
54
+ export type { GetOptions, PromptHelmErrorCode, PromptHelmOptions, PromptPayload, Vars };
package/dist/index.d.ts CHANGED
@@ -1,122 +1,54 @@
1
- type Environment = "production" | "development";
2
- interface ExecuteRequest {
3
- promptSlug?: string;
4
- promptId?: string;
5
- variables?: Record<string, string>;
6
- system?: string;
7
- user?: string;
8
- model?: string;
9
- temperature?: number;
10
- maxTokens?: number;
11
- topP?: number;
12
- stopSequences?: string[];
13
- environment?: Environment;
14
- timeoutMs?: number;
15
- }
16
- interface ExecuteResponse {
17
- id: string;
18
- output: string;
19
- model: string;
20
- inputTokens: number;
21
- outputTokens: number;
22
- totalTokens: number;
23
- latencyMs: number;
24
- cost: number;
25
- timestamp: string;
26
- }
27
- interface StreamChunkEvent {
28
- type: "chunk";
29
- content: string;
30
- }
31
- interface StreamDoneEvent {
32
- type: "done";
33
- inputTokens: number;
34
- outputTokens: number;
35
- totalTokens: number;
36
- cost: number;
37
- model: string;
38
- latencyMs: number;
39
- }
40
- interface StreamErrorEvent {
41
- type: "error";
42
- errorCode: string;
43
- message: string;
44
- requestId?: string;
1
+ type PromptHelmErrorCode = "unauthorized" | "not_found" | "missing_variables" | "timeout" | "network" | "server";
2
+ declare class PromptHelmError extends Error {
3
+ readonly code: PromptHelmErrorCode;
4
+ readonly status?: number | undefined;
5
+ readonly name = "PromptHelmError";
6
+ constructor(code: PromptHelmErrorCode, message: string, status?: number | undefined);
45
7
  }
46
- type StreamEvent = StreamChunkEvent | StreamDoneEvent | StreamErrorEvent;
8
+
9
+ type Vars = Readonly<Record<string, string | number | boolean>>;
10
+ /** The `{{variables}}` a template uses, in order of first appearance. */
11
+ declare function extractVariables(template: string): string[];
47
12
  /**
48
- * JSON error envelope returned by the PromptHelm API for non-2xx responses.
49
- * All five fields are always present on the wire; `message` may be a single
50
- * string or an array of validation messages.
13
+ * Fills in every `{{variable}}`. Throws `missing_variables` rather than leaving a
14
+ * placeholder in the text, because a half-filled prompt reaches the model silently.
51
15
  */
52
- interface ErrorEnvelope {
53
- statusCode: number;
54
- errorCode: string;
55
- message: string | string[];
56
- timestamp: string;
57
- requestId: string;
58
- }
59
- interface RequestOptions {
60
- signal?: AbortSignal;
61
- }
16
+ declare function render(template: string, vars?: Vars): string;
62
17
 
63
- interface PromptHelmConfig {
64
- apiKey: string;
65
- baseURL?: string;
18
+ /** Body of `GET /v1/prompts/:slug`. The server types its response with this too. */
19
+ interface PromptPayload {
20
+ slug: string;
21
+ version: number;
22
+ content: string;
23
+ variables: string[];
24
+ }
25
+ interface PromptHelmOptions {
26
+ /** Defaults to the PROMPTHELM_API_KEY environment variable. */
27
+ apiKey?: string;
28
+ /** Defaults to PROMPTHELM_BASE_URL, then https://prompthelm.app. */
29
+ baseUrl?: string;
30
+ /** How long a fetched prompt is served before checking for a newer version, in ms. */
31
+ ttl?: number;
32
+ /** Per-request timeout in ms. */
66
33
  timeout?: number;
67
- maxRetries?: number;
34
+ fetch?: typeof globalThis.fetch;
35
+ /** Told whenever a fallback or a stale prompt was served instead of failing. */
36
+ onError?: (error: PromptHelmError, slug: string) => void;
37
+ }
38
+ interface GetOptions {
39
+ vars?: Vars;
68
40
  /**
69
- * Prefix appended to the SDK's User-Agent header. Use it to identify the
70
- * application or service making the call (helpful when one tenant runs
71
- * many apps against the same prompt). Example: `"my-checkout-service/1.4.2"`.
41
+ * Served when PromptHelm can't be reached, the prompt doesn't exist, or the live
42
+ * version uses a variable this call doesn't pass. Without it those cases throw.
72
43
  */
73
- userAgent?: string;
74
- fetch?: typeof globalThis.fetch;
75
- headers?: Record<string, string>;
44
+ fallback?: string;
76
45
  }
77
46
  declare class PromptHelm {
78
- private readonly apiKey;
79
- private readonly baseURL;
80
- private readonly timeout;
81
- private readonly maxRetries;
82
- private readonly fetchFn;
83
- private readonly extraHeaders;
84
- private readonly userAgent;
85
- constructor(config: PromptHelmConfig);
86
- execute(request: ExecuteRequest, options?: RequestOptions): Promise<ExecuteResponse>;
87
- stream(request: ExecuteRequest, options?: RequestOptions): AsyncIterable<StreamEvent>;
88
- private executeOnce;
89
- private buildHeaders;
90
- private isRetryable;
91
- }
92
-
93
- declare class PromptHelmError extends Error {
94
- /** HTTP status code (or the inferred status for SSE error events). */
95
- readonly statusCode: number;
96
- /** Machine-readable error code from the API envelope, e.g. `VALIDATION_ERROR`. */
97
- readonly errorCode: string | undefined;
98
- /** Request correlation id — quote this when contacting PromptHelm support. */
99
- readonly requestId: string | undefined;
100
- constructor(statusCode: number, errorCode: string | undefined, requestId: string | undefined, message: string);
101
- }
102
- declare class AuthenticationError extends PromptHelmError {
103
- constructor(statusCode: number, errorCode: string | undefined, requestId: string | undefined, message: string);
104
- }
105
- declare class AuthorizationError extends PromptHelmError {
106
- constructor(statusCode: number, errorCode: string | undefined, requestId: string | undefined, message: string);
107
- }
108
- declare class RateLimitError extends PromptHelmError {
109
- constructor(statusCode: number, errorCode: string | undefined, requestId: string | undefined, message: string);
110
- }
111
- declare class NotFoundError extends PromptHelmError {
112
- constructor(statusCode: number, errorCode: string | undefined, requestId: string | undefined, message: string);
113
- }
114
- declare class ApiError extends PromptHelmError {
115
- constructor(statusCode: number, errorCode: string | undefined, requestId: string | undefined, message: string);
116
- }
117
- declare class TimeoutError extends Error {
118
- readonly timeoutMs: number;
119
- constructor(timeoutMs: number, message?: string);
47
+ #private;
48
+ constructor(options?: PromptHelmOptions);
49
+ /** The live version of a prompt with its variables filled in. */
50
+ get(slug: string, options?: GetOptions): Promise<string>;
120
51
  }
121
52
 
122
- export { ApiError, AuthenticationError, AuthorizationError, type Environment, type ErrorEnvelope, type ExecuteRequest, type ExecuteResponse, NotFoundError, PromptHelm, type PromptHelmConfig, PromptHelmError, RateLimitError, type RequestOptions, type StreamChunkEvent, type StreamDoneEvent, type StreamErrorEvent, type StreamEvent, TimeoutError };
53
+ export { PromptHelm, PromptHelmError, extractVariables, render };
54
+ export type { GetOptions, PromptHelmErrorCode, PromptHelmOptions, PromptPayload, Vars };