@prompts-gpt/client 0.1.0 → 0.2.2
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/CHANGELOG.md +95 -0
- package/README.md +244 -69
- package/dist/cli.js +742 -130
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +67 -25
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +508 -102
- package/dist/index.js.map +1 -1
- package/package.json +21 -15
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,100 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
### Security
|
|
6
|
+
|
|
7
|
+
- Validate `constraints` and `desiredOutput` length (max 1600 chars) client-side before network requests
|
|
8
|
+
- Validate token prefix (`pgpt_`) in `saveLocalCredentials` to reject malformed tokens at save time
|
|
9
|
+
- Sanitize Copilot prompt-file variable names to strip `$`, `{`, `}` injection characters
|
|
10
|
+
- Sanitize managed-block content to prevent marker injection via prompt content
|
|
11
|
+
- Validate API URL scheme (must be `https` or `http`) in `normalizeApiUrl`
|
|
12
|
+
- Auto-generate client-side request IDs (`pgcli_*`) when caller doesn't provide one for correlation
|
|
13
|
+
|
|
14
|
+
### Fixed
|
|
15
|
+
|
|
16
|
+
- Fix package version mismatch between `package.json` (0.2.1) and CHANGELOG (0.2.2)
|
|
17
|
+
- Fix npm publish failure on unsupported CI providers by removing forced provenance from package metadata
|
|
18
|
+
- Fix race condition in file writes: use atomic `wx` flag with `EEXIST` catch instead of `existsSync` + `wx`
|
|
19
|
+
- Fix `formatPromptMarkdown` producing double blank lines when both `usageNotes` and `variables` are empty
|
|
20
|
+
- Fix `normalizeAgentTargets` deduplication when `all` is mixed with explicit targets (e.g. `all,codex`)
|
|
21
|
+
- Fix `normalizeAgentTargets` returning empty array for empty string input
|
|
22
|
+
- Fix `loadLocalCredentials` returning empty-string token instead of `null` for whitespace-only stored tokens
|
|
23
|
+
- Fix `safeSlug` for unicode-only input by normalizing NFKD and stripping combining marks
|
|
24
|
+
- Fix `ensureGitignoreEntry` to preserve CRLF line endings on Windows-style `.gitignore` files
|
|
25
|
+
- Fix `parseRetryAfterHeader` to cap parsed values at 10 minutes, preventing unbounded waits
|
|
26
|
+
- Fix `assertInside` / `assertSafeOutputDir` boundary comparison for paths at the project root
|
|
27
|
+
- Fix `writePromptIndex` to escape `[` and `]` in Markdown link text to prevent broken rendering
|
|
28
|
+
- Fix `yamlScalar` to handle multi-line strings by normalizing `\r\n` before quoting
|
|
29
|
+
- Serialize agent file writes sequentially to prevent concurrent write races on shared files
|
|
30
|
+
|
|
31
|
+
### Improvements
|
|
32
|
+
|
|
33
|
+
- Add `--dry-run` flag to `sync` and `install-agents` commands for previewing changes
|
|
34
|
+
- Add dedicated CLI exit code `4` for rate-limit errors (HTTP 429)
|
|
35
|
+
- Use longer default timeout (60s) for prompt generation requests
|
|
36
|
+
- Add `DEFAULT_GENERATE_TIMEOUT_MS` constant for prompt generation timeout
|
|
37
|
+
|
|
38
|
+
### Packaging
|
|
39
|
+
|
|
40
|
+
- Add npm `homepage` and `bugs.email` metadata so package consumers have a first-party support path from the registry page
|
|
41
|
+
- Clarify the project-local CLI install path and pre-publish `npm pack --dry-run` verification flow in the README
|
|
42
|
+
|
|
43
|
+
## 0.2.2 (2026-05-16)
|
|
44
|
+
|
|
45
|
+
### Local Sync
|
|
46
|
+
|
|
47
|
+
- Reject prompt filename collisions after slug normalization before writing local artifacts
|
|
48
|
+
- Respect each prompt pack's declared `agentTargets` when generating Codex, Cursor, VS Code, and Copilot files
|
|
49
|
+
- Skip existing non-managed agent files unless `--overwrite` is explicitly passed
|
|
50
|
+
- Expand `manifest.json` with agent targets, recommended path, and generated file locations for downstream discovery
|
|
51
|
+
- Emit GitHub Copilot prompt files in prompt-file format instead of generic prompt-pack Markdown
|
|
52
|
+
- Add `.github/instructions/prompts-gpt.instructions.md` so Copilot treats synced agent artifacts as generated files
|
|
53
|
+
|
|
54
|
+
## 0.2.1 (2026-05-16)
|
|
55
|
+
|
|
56
|
+
### Packaging
|
|
57
|
+
|
|
58
|
+
- Add an explicit `default` export target for better ESM consumer and bundler compatibility
|
|
59
|
+
- Enable npm provenance on publish for stronger package registry attestation
|
|
60
|
+
- Remove the redundant `typesVersions` entry and rely on the package `types` field plus export metadata
|
|
61
|
+
|
|
62
|
+
### Documentation
|
|
63
|
+
|
|
64
|
+
- Replace stale `npx`-only examples with `npm exec` flows that pin to the latest published package
|
|
65
|
+
- Clarify that the importable SDK does not read `process.env` and requires explicit `fetch`
|
|
66
|
+
- Align CI/CD examples with the real CLI contract of passing tokens as flags instead of ambient env reads
|
|
67
|
+
- Document the packed artifact contents shipped to npm
|
|
68
|
+
|
|
69
|
+
## 0.2.0 (2026-05-16)
|
|
70
|
+
|
|
71
|
+
### Security
|
|
72
|
+
|
|
73
|
+
- Token prefix validation now enforced client-side before any network request
|
|
74
|
+
- Response content-type validation prevents processing non-JSON responses
|
|
75
|
+
- Retry delay capped at 30 seconds to prevent retry-after abuse
|
|
76
|
+
- Token length validation on `saveLocalCredentials` prevents oversized storage
|
|
77
|
+
- Control characters stripped from shell-quoted CLI output
|
|
78
|
+
|
|
79
|
+
### Improvements
|
|
80
|
+
|
|
81
|
+
- Add `accept: application/json` header to all API requests
|
|
82
|
+
- Validate response `content-type` before parsing JSON
|
|
83
|
+
- Cap retry sleep to prevent unbounded waits from malicious `retry-after` headers
|
|
84
|
+
- Improved error messages with structured `code` and `recovery` fields
|
|
85
|
+
- Added `package.json` subpath export for bundler compatibility
|
|
86
|
+
- Extended npm keywords for better discoverability
|
|
87
|
+
- Added `typesVersions` for legacy TypeScript resolution
|
|
88
|
+
|
|
89
|
+
### Fixed
|
|
90
|
+
|
|
91
|
+
- Fixed potential timeout leak when retries re-create AbortControllers
|
|
92
|
+
|
|
93
|
+
## 0.1.1 (2026-05-16)
|
|
94
|
+
|
|
95
|
+
- Remove public GitHub repository metadata from the npm package manifest while the source repository remains non-public.
|
|
96
|
+
- Preserve executable permissions for the `prompts-gpt` CLI after package builds.
|
|
97
|
+
|
|
3
98
|
## 0.1.0 (2026-05-16)
|
|
4
99
|
|
|
5
100
|
Initial release.
|
package/README.md
CHANGED
|
@@ -1,147 +1,271 @@
|
|
|
1
1
|
# @prompts-gpt/client
|
|
2
2
|
|
|
3
|
-
CLI and SDK for
|
|
3
|
+
CLI and Node.js SDK for syncing [Prompts-GPT](https://prompts-gpt.com) prompt packs into any local project — with first-class integrations for **Codex**, **Cursor**, **VS Code**, and **GitHub Copilot**.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Why
|
|
8
|
+
|
|
9
|
+
AI coding agents work best when they have stable, discoverable instructions inside the repository. This package bridges Prompts-GPT's cloud prompt library with the local files each agent reads:
|
|
10
|
+
|
|
11
|
+
| Agent | What gets written |
|
|
12
|
+
|-------|-------------------|
|
|
13
|
+
| **Codex** | `AGENTS.md` managed block |
|
|
14
|
+
| **Cursor** | `.cursor/rules/prompts-gpt-*.mdc` |
|
|
15
|
+
| **VS Code** | `.github/copilot-instructions.md` + `.github/instructions/*.instructions.md` + `.vscode/*.code-snippets` |
|
|
16
|
+
| **Copilot** | `.github/prompts/*.prompt.md` |
|
|
17
|
+
|
|
18
|
+
Prompt Markdown files and a `manifest.json` are always written to `.prompts-gpt/` for discovery.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Quick start
|
|
6
23
|
|
|
7
24
|
```bash
|
|
8
|
-
#
|
|
9
|
-
|
|
25
|
+
# Run the latest CLI without installing it globally
|
|
26
|
+
npm exec --yes @prompts-gpt/client@latest -- init --token <project-token>
|
|
10
27
|
|
|
11
|
-
# Sync prompt packs
|
|
12
|
-
|
|
28
|
+
# Sync prompt packs + agent files in one command
|
|
29
|
+
npm exec --yes @prompts-gpt/client@latest -- sync --agent all
|
|
13
30
|
|
|
14
|
-
# Generate a project-aware prompt
|
|
15
|
-
|
|
31
|
+
# Generate a project-aware prompt and sync it
|
|
32
|
+
npm exec --yes @prompts-gpt/client@latest -- generate \
|
|
33
|
+
--goal "Review this diff for security issues" \
|
|
34
|
+
--context "Node.js API with PostgreSQL" \
|
|
35
|
+
--agent codex,cursor,vscode
|
|
16
36
|
```
|
|
17
37
|
|
|
18
|
-
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Install
|
|
19
41
|
|
|
20
42
|
```bash
|
|
21
43
|
npm install @prompts-gpt/client
|
|
22
44
|
```
|
|
23
45
|
|
|
24
|
-
|
|
46
|
+
If you want a project-local CLI instead of one-off `npm exec` usage, install it as a dev dependency and call the bin from `package.json` scripts:
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"scripts": {
|
|
51
|
+
"prompts:sync": "prompts-gpt sync --agent all",
|
|
52
|
+
"prompts:generate": "prompts-gpt generate --goal \"Review this diff for security issues\" --agent codex"
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Or run directly with `npx` — no install required:
|
|
25
58
|
|
|
26
59
|
```bash
|
|
27
|
-
npx @prompts-gpt/client <command>
|
|
60
|
+
npx @prompts-gpt/client@latest <command>
|
|
28
61
|
```
|
|
29
62
|
|
|
30
|
-
**
|
|
63
|
+
**Requires** Node.js 18.18 or later.
|
|
64
|
+
|
|
65
|
+
---
|
|
31
66
|
|
|
32
67
|
## Authentication
|
|
33
68
|
|
|
34
|
-
Create a project token in the [Prompts-GPT dashboard](https://prompts-gpt.com/dashboard/agents), then
|
|
69
|
+
Create a project token in the [Prompts-GPT dashboard](https://prompts-gpt.com/dashboard/agents), then:
|
|
35
70
|
|
|
36
71
|
```bash
|
|
37
|
-
prompts-gpt init --token
|
|
72
|
+
prompts-gpt init --token-prompt
|
|
38
73
|
```
|
|
39
74
|
|
|
40
|
-
|
|
75
|
+
Credentials are saved to `.prompts-gpt/.credentials.json` with `0600` permissions and automatically added to `.gitignore`.
|
|
41
76
|
|
|
42
|
-
|
|
77
|
+
Project tokens are project-scoped, support separate `Read Prompts` and `Generate Prompts` scopes, and should use the shortest practical expiry for the machine or CI job that needs them.
|
|
43
78
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
### `init`
|
|
47
|
-
|
|
48
|
-
Save a project token to the local credentials file.
|
|
79
|
+
For CI/CD or secret-manager pipes, use stdin instead of putting the raw token in shell history:
|
|
49
80
|
|
|
50
81
|
```bash
|
|
51
|
-
prompts-gpt
|
|
82
|
+
printf '%s' "$PROMPTS_GPT_TOKEN" | prompts-gpt sync --token-stdin --agent all
|
|
52
83
|
```
|
|
53
84
|
|
|
54
|
-
|
|
85
|
+
The importable SDK never reads `process.env` and never captures ambient `globalThis.fetch`. Pass explicit runtime dependencies in code.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## CLI reference
|
|
55
90
|
|
|
56
|
-
|
|
91
|
+
### `init` — Save credentials
|
|
57
92
|
|
|
58
93
|
```bash
|
|
59
|
-
prompts-gpt
|
|
94
|
+
prompts-gpt init (--token <token> | --token-stdin | --token-prompt) [--api-url <url>] [--cwd <path>]
|
|
60
95
|
```
|
|
61
96
|
|
|
62
|
-
|
|
97
|
+
Use `--token-prompt` for local interactive setup and `--token-stdin` for CI or secret-manager pipes.
|
|
63
98
|
|
|
64
|
-
|
|
99
|
+
### `sync` — Pull + generate + write everything
|
|
65
100
|
|
|
66
101
|
```bash
|
|
67
|
-
prompts-gpt
|
|
102
|
+
prompts-gpt sync [--goal "..."] [--limit 25] [--agent all] [--overwrite]
|
|
68
103
|
```
|
|
69
104
|
|
|
70
|
-
|
|
105
|
+
The default workflow. Pulls library prompts, optionally generates one, writes Markdown files, agent integration files, and a manifest.
|
|
106
|
+
|
|
107
|
+
Existing prompt Markdown, Cursor rules, Copilot prompt files, and VS Code snippet files are skipped unless you pass `--overwrite`. Managed Prompts-GPT blocks inside `AGENTS.md` and `.github/copilot-instructions.md` remain idempotent and update in place, and a shared `.github/instructions/prompts-gpt.instructions.md` file teaches Copilot to treat synced artifacts as generated outputs.
|
|
71
108
|
|
|
72
|
-
|
|
109
|
+
### `pull` — Download prompt packs
|
|
73
110
|
|
|
74
111
|
```bash
|
|
75
|
-
prompts-gpt
|
|
112
|
+
prompts-gpt pull [--query "repo audit"] [--category coding] [--tool Codex] [--limit 25] [--overwrite]
|
|
76
113
|
```
|
|
77
114
|
|
|
78
|
-
### `
|
|
115
|
+
### `generate` — Create a project-aware prompt
|
|
79
116
|
|
|
80
|
-
|
|
117
|
+
```bash
|
|
118
|
+
prompts-gpt generate --goal "Review this diff" [--context "Next.js app"] [--tool Codex] [--agent codex,cursor]
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### `install-agents` — Write agent files only
|
|
81
122
|
|
|
82
123
|
```bash
|
|
83
124
|
prompts-gpt install-agents [--agent codex,cursor,vscode,copilot]
|
|
84
125
|
```
|
|
85
126
|
|
|
86
|
-
### `project`
|
|
87
|
-
|
|
88
|
-
Print the project name and website from the API.
|
|
127
|
+
### `project` — Print project info
|
|
89
128
|
|
|
90
129
|
```bash
|
|
91
130
|
prompts-gpt project
|
|
92
131
|
```
|
|
93
132
|
|
|
94
|
-
|
|
133
|
+
### `version` / `help`
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
prompts-gpt version
|
|
137
|
+
prompts-gpt help
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Common flags
|
|
141
|
+
|
|
142
|
+
| Flag | Description |
|
|
143
|
+
|------|-------------|
|
|
144
|
+
| `--token <token>` | Project API token |
|
|
145
|
+
| `--token-stdin` | Read the token from stdin |
|
|
146
|
+
| `--token-prompt` | Prompt for the token without echoing it |
|
|
147
|
+
| `--api-url <url>` | Custom API base URL |
|
|
148
|
+
| `--cwd <path>` | Target directory for config and generated files |
|
|
149
|
+
| `--agent <targets>` | Comma-separated: `codex`, `cursor`, `vscode`, `copilot`, or `all` |
|
|
150
|
+
| `--overwrite` | Replace existing files instead of skipping |
|
|
151
|
+
| `--out <dir>` | Output directory (default: `.prompts-gpt`) |
|
|
152
|
+
|
|
153
|
+
### Supported tools
|
|
154
|
+
|
|
155
|
+
Codex, Claude Code, Cursor, GitHub Copilot, ChatGPT, Gemini, Perplexity, Grok, DeepSeek, Claude.
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## Programmatic SDK
|
|
95
160
|
|
|
96
161
|
```typescript
|
|
97
|
-
import {
|
|
162
|
+
import {
|
|
163
|
+
DEFAULT_PROMPTS_GPT_API_URL,
|
|
164
|
+
PromptsGptClient,
|
|
165
|
+
syncPrompts,
|
|
166
|
+
writeAgentFiles,
|
|
167
|
+
formatPromptMarkdown,
|
|
168
|
+
} from "@prompts-gpt/client";
|
|
98
169
|
|
|
99
170
|
const client = new PromptsGptClient({
|
|
100
|
-
token:
|
|
171
|
+
token: "pgpt_your_token_here",
|
|
172
|
+
apiUrl: DEFAULT_PROMPTS_GPT_API_URL,
|
|
173
|
+
fetch,
|
|
101
174
|
});
|
|
102
175
|
|
|
103
176
|
// Fetch project context
|
|
104
177
|
const project = await client.getProject();
|
|
105
|
-
console.log(project.brandName);
|
|
178
|
+
console.log(project.brandName, project.websiteUrl);
|
|
106
179
|
|
|
107
|
-
// Pull prompt packs
|
|
180
|
+
// Pull prompt packs from the library
|
|
108
181
|
const prompts = await client.pullPrompts({ limit: 10, tool: "Codex" });
|
|
109
182
|
|
|
110
|
-
// Generate a prompt
|
|
183
|
+
// Generate a project-aware prompt
|
|
111
184
|
const generated = await client.generatePrompt({
|
|
112
185
|
goal: "Review production diffs for security issues",
|
|
113
186
|
context: "Node.js microservice with PostgreSQL",
|
|
114
187
|
tool: "Codex",
|
|
115
188
|
});
|
|
116
189
|
|
|
117
|
-
// Sync everything to disk
|
|
190
|
+
// Sync everything to disk (Markdown + agent files + manifest)
|
|
118
191
|
const result = await syncPrompts([...prompts, generated], {
|
|
119
192
|
agent: "all",
|
|
120
193
|
overwrite: true,
|
|
121
194
|
});
|
|
195
|
+
|
|
196
|
+
console.log(`Wrote ${result.markdown.written.length} prompts`);
|
|
197
|
+
console.log(`Synced ${result.agents.written.length} agent files`);
|
|
122
198
|
```
|
|
123
199
|
|
|
124
|
-
|
|
200
|
+
### Runtime requirements
|
|
125
201
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
| Manifest | `.prompts-gpt/manifest.json` | Index for agent discovery |
|
|
130
|
-
| Codex | `AGENTS.md` | Managed block with prompt-pack links |
|
|
131
|
-
| Cursor | `.cursor/rules/prompts-gpt-*.mdc` | Per-prompt rule files |
|
|
132
|
-
| VS Code | `.github/copilot-instructions.md`, `.vscode/*.code-snippets` | Copilot instructions and snippets |
|
|
133
|
-
| Copilot | `.github/prompts/*.prompt.md` | Prompt files for GitHub Copilot |
|
|
202
|
+
- `PromptsGptClient` requires an explicit `fetch` implementation. In Node.js 18.18+ you can pass the built-in `fetch`.
|
|
203
|
+
- The SDK is ESM-only. Use `import`, not `require`.
|
|
204
|
+
- File-writing helpers only write inside the provided project directory and reject path traversal.
|
|
134
205
|
|
|
135
|
-
|
|
206
|
+
### API methods
|
|
136
207
|
|
|
137
|
-
|
|
|
138
|
-
|
|
139
|
-
| `
|
|
140
|
-
| `
|
|
208
|
+
| Method | Description |
|
|
209
|
+
|--------|-------------|
|
|
210
|
+
| `client.getProject()` | Returns project context (brand, competitors, keywords) |
|
|
211
|
+
| `client.pullPrompts(query?)` | Fetches prompt packs from the library |
|
|
212
|
+
| `client.generatePrompt(input)` | Generates a prompt using project context |
|
|
141
213
|
|
|
142
|
-
|
|
214
|
+
### File-writing utilities
|
|
143
215
|
|
|
144
|
-
|
|
216
|
+
| Function | Description |
|
|
217
|
+
|----------|-------------|
|
|
218
|
+
| `syncPrompts(prompts, opts)` | Full sync: Markdown + agents + manifest |
|
|
219
|
+
| `writePromptMarkdownFiles(prompts, opts)` | Write `.md` files only |
|
|
220
|
+
| `writeAgentFiles(prompts, opts)` | Write agent integration files only |
|
|
221
|
+
| `writePromptManifest(prompts, opts)` | Write `manifest.json` only |
|
|
222
|
+
| `formatPromptMarkdown(prompt)` | Render a single prompt as Markdown |
|
|
223
|
+
| `saveLocalCredentials(input)` | Save token to `.prompts-gpt/.credentials.json` |
|
|
224
|
+
| `loadLocalCredentials(cwd?)` | Load saved credentials |
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
## Generated file structure
|
|
229
|
+
|
|
230
|
+
After running `sync --agent all`, your repository will contain:
|
|
231
|
+
|
|
232
|
+
```
|
|
233
|
+
.prompts-gpt/
|
|
234
|
+
manifest.json # Machine-readable index
|
|
235
|
+
README.md # Human-readable index
|
|
236
|
+
senior-code-reviewer.md # Prompt pack (YAML frontmatter + Markdown)
|
|
237
|
+
...
|
|
238
|
+
|
|
239
|
+
AGENTS.md # Codex: managed <!-- prompts-gpt:start --> block
|
|
240
|
+
|
|
241
|
+
.cursor/rules/
|
|
242
|
+
prompts-gpt-senior-code-reviewer.mdc # Cursor rule file
|
|
243
|
+
|
|
244
|
+
.github/
|
|
245
|
+
copilot-instructions.md # VS Code / Copilot shared instructions
|
|
246
|
+
instructions/
|
|
247
|
+
prompts-gpt.instructions.md # Copilot path-specific instructions for generated artifacts
|
|
248
|
+
prompts/
|
|
249
|
+
prompts-gpt-senior-code-reviewer.prompt.md # Copilot prompt file
|
|
250
|
+
|
|
251
|
+
.vscode/
|
|
252
|
+
prompts-gpt.code-snippets # VS Code snippets
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
`manifest.json` includes each prompt's supported agent targets, recommended local path, and generated file locations so downstream tools can discover the synced artifacts without guessing paths.
|
|
256
|
+
|
|
257
|
+
---
|
|
258
|
+
|
|
259
|
+
## Environment variables
|
|
260
|
+
|
|
261
|
+
| Variable | Description |
|
|
262
|
+
|----------|-------------|
|
|
263
|
+
| `PROMPTS_GPT_TOKEN` | Shell variable you can expand into `--token` for CI or local scripts |
|
|
264
|
+
| `PROMPTS_GPT_API_URL` | Shell variable you can expand into `--api-url` for self-hosted instances |
|
|
265
|
+
|
|
266
|
+
---
|
|
267
|
+
|
|
268
|
+
## Error handling
|
|
145
269
|
|
|
146
270
|
```typescript
|
|
147
271
|
import { PromptsGptApiError } from "@prompts-gpt/client";
|
|
@@ -150,22 +274,73 @@ try {
|
|
|
150
274
|
await client.pullPrompts();
|
|
151
275
|
} catch (error) {
|
|
152
276
|
if (error instanceof PromptsGptApiError) {
|
|
153
|
-
console.error(error.message);
|
|
154
|
-
console.error(error.code);
|
|
155
|
-
console.error(error.status);
|
|
156
|
-
console.error(error.recovery);
|
|
277
|
+
console.error(error.message); // Human-readable message
|
|
278
|
+
console.error(error.code); // Machine-readable code
|
|
279
|
+
console.error(error.status); // HTTP status (e.g. 401, 429)
|
|
280
|
+
console.error(error.recovery); // Suggested fix
|
|
157
281
|
}
|
|
158
282
|
}
|
|
159
283
|
```
|
|
160
284
|
|
|
285
|
+
**Error codes:** `AUTH_ERROR`, `VALIDATION_ERROR`, `RATE_LIMIT_ERROR`, `TIMEOUT`, `NETWORK_ERROR`, `INVALID_RESPONSE`, `MISSING_FETCH`.
|
|
286
|
+
|
|
287
|
+
The client automatically retries on `429`, `502`, `503`, and `504` responses with exponential backoff and jitter.
|
|
288
|
+
|
|
289
|
+
SDK responses include `X-Request-Id` plus rate-limit headers so CLI errors can be correlated with one server-side request path during support or incident triage.
|
|
290
|
+
|
|
291
|
+
---
|
|
292
|
+
|
|
293
|
+
## CI/CD usage
|
|
294
|
+
|
|
295
|
+
```yaml
|
|
296
|
+
# GitHub Actions example
|
|
297
|
+
- name: Sync Prompts-GPT agent files
|
|
298
|
+
env:
|
|
299
|
+
PROMPTS_GPT_TOKEN: ${{ secrets.PROMPTS_GPT_TOKEN }}
|
|
300
|
+
run: npm exec --yes @prompts-gpt/client@latest -- sync --token "$PROMPTS_GPT_TOKEN" --agent all --overwrite
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
Use `npm exec` here so the job always resolves the package bin explicitly and does not depend on a preinstalled global CLI.
|
|
304
|
+
|
|
305
|
+
---
|
|
306
|
+
|
|
307
|
+
## Package contents
|
|
308
|
+
|
|
309
|
+
The published tarball includes:
|
|
310
|
+
|
|
311
|
+
- `dist/` ESM JavaScript, source maps, and `.d.ts` files
|
|
312
|
+
- `README.md`
|
|
313
|
+
- `CHANGELOG.md`
|
|
314
|
+
- `LICENSE`
|
|
315
|
+
- `package.json`
|
|
316
|
+
|
|
317
|
+
This package intentionally does not publish source TypeScript, test fixtures, or local credential files.
|
|
318
|
+
|
|
319
|
+
Before publishing a new release, run:
|
|
320
|
+
|
|
321
|
+
```bash
|
|
322
|
+
TMPDIR=/private/tmp npm_config_cache=/private/tmp/prompts-gpt-npm-cache npm pack --dry-run
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
That verifies the `files` whitelist, the generated `dist/` output, and the executable mode on `dist/cli.js` without mutating the real npm cache.
|
|
326
|
+
|
|
327
|
+
Publish with the default npm flow unless the release runs inside a provider that supports npm provenance attestation. If you want provenance, enable it explicitly in that CI job instead of forcing it in `package.json`.
|
|
328
|
+
|
|
329
|
+
---
|
|
330
|
+
|
|
161
331
|
## Security
|
|
162
332
|
|
|
163
|
-
- Credentials
|
|
164
|
-
-
|
|
165
|
-
- HTTPS
|
|
166
|
-
-
|
|
167
|
-
-
|
|
333
|
+
- Credentials stored with `0600` file permissions (owner read/write only)
|
|
334
|
+
- Token prefix (`pgpt_`) validated before any network request
|
|
335
|
+
- HTTPS enforced in production
|
|
336
|
+
- Response content-type validated before JSON parsing
|
|
337
|
+
- Path traversal blocked for all file writes
|
|
338
|
+
- Control characters sanitized from CLI output
|
|
339
|
+
- Retry delays capped to prevent abuse via `retry-after`
|
|
340
|
+
- Context sent to `generate` is ephemeral — never persisted server-side
|
|
341
|
+
|
|
342
|
+
---
|
|
168
343
|
|
|
169
344
|
## License
|
|
170
345
|
|
|
171
|
-
MIT
|
|
346
|
+
[MIT](./LICENSE)
|