@theholocron/holocron-plugin-postman 5.0.0-alpha.278 → 5.0.0-alpha.279
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.mts +25 -0
- package/dist/index.mjs +21 -0
- package/package.json +7 -7
package/dist/index.d.mts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { AuthError, PluginToken, ResolveTokenInput, Tooling, ToolingDoctorReport, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
|
|
2
2
|
import { PostmanClient, PostmanClient as PostmanClient$1, PostmanClientOptions, PostmanCollection, PostmanEnvironment, PostmanPlanLimitError, PostmanSpec, PostmanUser, PostmanWorkspace, createPostmanClient, detectPlanLimit } from "@theholocron/postman-client";
|
|
3
|
+
/** Resolves the Postman API key from `--token`, `HOLOCRON_POSTMAN_API_KEY`, `POSTMAN_API_KEY` or the keyring, and throws an `AuthError` when none is set. */
|
|
3
4
|
export declare const resolveToken: import("@theholocron/cli").TokenResolver;
|
|
4
5
|
/** Every token this plugin takes, for `holocron doctor tokens`. */
|
|
5
6
|
export declare const tokens: PluginToken[];
|
|
@@ -16,45 +17,60 @@ interface PostmanToolingOptions {
|
|
|
16
17
|
/** Working repo root. Defaults to process.cwd(). */
|
|
17
18
|
repoRoot?: string;
|
|
18
19
|
}
|
|
20
|
+
/** The Postman implementation of the `tooling` capability: syncs an OpenAPI spec, collection and environments into a workspace. */
|
|
19
21
|
export declare class PostmanTooling implements Tooling {
|
|
20
22
|
private readonly client;
|
|
23
|
+
/** The capability this class provides, always `"tooling"`. */
|
|
21
24
|
readonly key: "tooling";
|
|
25
|
+
/** The provider name, `"postman"`. */
|
|
22
26
|
readonly providerName = "postman";
|
|
23
27
|
private readonly opts;
|
|
24
28
|
private readonly repoRoot;
|
|
25
29
|
constructor(client: () => PostmanClient$1, opts: PostmanToolingOptions);
|
|
26
30
|
sync(): Promise<void>;
|
|
31
|
+
/** Checks the key and the configured workspace; reports the authenticated user and the workspace, or why either failed. */
|
|
27
32
|
doctor(): Promise<ToolingDoctorReport>;
|
|
33
|
+
/** Returns the authenticated Postman user. */
|
|
28
34
|
getMyself(): Promise<PostmanUser>;
|
|
35
|
+
/** Lists the workspaces the key can see. */
|
|
29
36
|
listWorkspaces(): Promise<PostmanWorkspace[]>;
|
|
37
|
+
/** Finds a collection in the workspace by exact name, or `null` when there is none. */
|
|
30
38
|
findCollectionByName(input: {
|
|
31
39
|
workspaceId: string;
|
|
32
40
|
name: string;
|
|
33
41
|
}): Promise<PostmanCollection | null>;
|
|
42
|
+
/** Deletes the collection with this uid. */
|
|
34
43
|
deleteCollection(uid: string): Promise<void>;
|
|
44
|
+
/** Imports an OpenAPI document into the workspace as a collection; throws when Postman returns none. */
|
|
35
45
|
importOpenApi(input: {
|
|
36
46
|
workspaceId: string;
|
|
37
47
|
spec: unknown;
|
|
38
48
|
}): Promise<PostmanCollection>;
|
|
49
|
+
/** Lists the workspace's environments. */
|
|
39
50
|
listEnvironments(input: {
|
|
40
51
|
workspaceId: string;
|
|
41
52
|
}): Promise<PostmanEnvironment[]>;
|
|
53
|
+
/** Finds an environment in the workspace by exact name, or `null` when there is none. */
|
|
42
54
|
findEnvironmentByName(input: {
|
|
43
55
|
workspaceId: string;
|
|
44
56
|
name: string;
|
|
45
57
|
}): Promise<PostmanEnvironment | null>;
|
|
58
|
+
/** Creates an environment in the workspace. */
|
|
46
59
|
createEnvironment(input: {
|
|
47
60
|
workspaceId: string;
|
|
48
61
|
environment: unknown;
|
|
49
62
|
}): Promise<PostmanEnvironment>;
|
|
63
|
+
/** Replaces the environment with this uid. */
|
|
50
64
|
updateEnvironment(input: {
|
|
51
65
|
uid: string;
|
|
52
66
|
environment: unknown;
|
|
53
67
|
}): Promise<PostmanEnvironment>;
|
|
68
|
+
/** Finds an API spec in the workspace by exact name, or `null` when there is none. */
|
|
54
69
|
findSpecByName(input: {
|
|
55
70
|
workspaceId: string;
|
|
56
71
|
name: string;
|
|
57
72
|
}): Promise<PostmanSpec | null>;
|
|
73
|
+
/** Creates an API spec in the workspace from the given file content. */
|
|
58
74
|
createSpec(input: {
|
|
59
75
|
workspaceId: string;
|
|
60
76
|
name: string;
|
|
@@ -62,6 +78,7 @@ export declare class PostmanTooling implements Tooling {
|
|
|
62
78
|
filePath?: string;
|
|
63
79
|
fileContent: string;
|
|
64
80
|
}): Promise<PostmanSpec>;
|
|
81
|
+
/** Writes new content to a file of an existing spec. */
|
|
65
82
|
upsertSpecFile(input: {
|
|
66
83
|
specId: string;
|
|
67
84
|
filePath: string;
|
|
@@ -72,7 +89,9 @@ interface VerifyTokenOptions {
|
|
|
72
89
|
baseUrl?: string;
|
|
73
90
|
fetch?: typeof fetch;
|
|
74
91
|
}
|
|
92
|
+
/** Checks a Postman API key by fetching the authenticated user; resolves to the user's email, username or name, or the failure message. */
|
|
75
93
|
export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
|
|
94
|
+
/** Options for the Postman plugin: how the API key is resolved, the tooling settings, and test overrides. */
|
|
76
95
|
export interface PostmanPluginOptions extends ResolveTokenInput, PostmanToolingOptions {
|
|
77
96
|
/** Working repo root. Used to resolve relative paths in specFile/envFiles. Defaults to process.cwd(). */
|
|
78
97
|
repoRoot?: string;
|
|
@@ -81,12 +100,18 @@ export interface PostmanPluginOptions extends ResolveTokenInput, PostmanToolingO
|
|
|
81
100
|
/** Override `fetch` for tests. */
|
|
82
101
|
fetch?: typeof fetch;
|
|
83
102
|
}
|
|
103
|
+
/** The shared state the Postman plugin's capability and probes are built from. */
|
|
84
104
|
export interface PluginContext {
|
|
105
|
+
/** The options the plugin was created with. */
|
|
85
106
|
options: PostmanPluginOptions;
|
|
107
|
+
/** Memoized client factory; the API key is resolved on first use. */
|
|
86
108
|
client: () => PostmanClient;
|
|
87
109
|
}
|
|
110
|
+
/** Builds the plugin context from its options; throws when `workspaceId` is missing. */
|
|
88
111
|
export declare function createContext(options: PostmanPluginOptions): PluginContext;
|
|
112
|
+
/** Builds the `tooling` capability for a context, passing only the options that are set. */
|
|
89
113
|
export declare function tooling(ctx: PluginContext): Tooling;
|
|
114
|
+
/** Creates the Postman plugin: its `tooling` capability and its `connection` probe. */
|
|
90
115
|
export declare function createPlugin(options: PostmanPluginOptions): {
|
|
91
116
|
name: string;
|
|
92
117
|
probes: {
|
package/dist/index.mjs
CHANGED
|
@@ -4,6 +4,7 @@ import { basename, resolve } from "node:path";
|
|
|
4
4
|
import { errorMessage } from "@theholocron/misc-utils";
|
|
5
5
|
import { PostmanPlanLimitError, createPostmanClient, detectPlanLimit } from "@theholocron/postman-client";
|
|
6
6
|
// src/auth.ts
|
|
7
|
+
/** Resolves the Postman API key from `--token`, `HOLOCRON_POSTMAN_API_KEY`, `POSTMAN_API_KEY` or the keyring, and throws an `AuthError` when none is set. */
|
|
7
8
|
const resolveToken = createResolveToken({
|
|
8
9
|
envName: "HOLOCRON_POSTMAN_API_KEY",
|
|
9
10
|
vendorEnvName: "POSTMAN_API_KEY",
|
|
@@ -35,9 +36,12 @@ const tokens = [resolveToken.token];
|
|
|
35
36
|
* `doctor()` probes `/me` for auth + `/workspaces` for workspace
|
|
36
37
|
* reachability and returns a `ToolingDoctorReport`.
|
|
37
38
|
*/
|
|
39
|
+
/** The Postman implementation of the `tooling` capability: syncs an OpenAPI spec, collection and environments into a workspace. */
|
|
38
40
|
var PostmanTooling = class {
|
|
39
41
|
client;
|
|
42
|
+
/** The capability this class provides, always `"tooling"`. */
|
|
40
43
|
key = "tooling";
|
|
44
|
+
/** The provider name, `"postman"`. */
|
|
41
45
|
providerName = "postman";
|
|
42
46
|
opts;
|
|
43
47
|
repoRoot;
|
|
@@ -97,6 +101,7 @@ var PostmanTooling = class {
|
|
|
97
101
|
});
|
|
98
102
|
}
|
|
99
103
|
}
|
|
104
|
+
/** Checks the key and the configured workspace; reports the authenticated user and the workspace, or why either failed. */
|
|
100
105
|
async doctor() {
|
|
101
106
|
try {
|
|
102
107
|
const me = await this.getMyself();
|
|
@@ -116,45 +121,56 @@ var PostmanTooling = class {
|
|
|
116
121
|
};
|
|
117
122
|
}
|
|
118
123
|
}
|
|
124
|
+
/** Returns the authenticated Postman user. */
|
|
119
125
|
async getMyself() {
|
|
120
126
|
return (await this.client().me.get()).user ?? {};
|
|
121
127
|
}
|
|
128
|
+
/** Lists the workspaces the key can see. */
|
|
122
129
|
async listWorkspaces() {
|
|
123
130
|
const { workspaces } = await this.client().workspaces.list();
|
|
124
131
|
return workspaces;
|
|
125
132
|
}
|
|
133
|
+
/** Finds a collection in the workspace by exact name, or `null` when there is none. */
|
|
126
134
|
async findCollectionByName(input) {
|
|
127
135
|
const { collections } = await this.client().collections.list(input.workspaceId);
|
|
128
136
|
return collections.find((c) => c.name === input.name) ?? null;
|
|
129
137
|
}
|
|
138
|
+
/** Deletes the collection with this uid. */
|
|
130
139
|
async deleteCollection(uid) {
|
|
131
140
|
await this.client().collections.delete(uid);
|
|
132
141
|
}
|
|
142
|
+
/** Imports an OpenAPI document into the workspace as a collection; throws when Postman returns none. */
|
|
133
143
|
async importOpenApi(input) {
|
|
134
144
|
const { collections } = await this.client().import.openapi(input.workspaceId, input.spec);
|
|
135
145
|
const created = collections[0];
|
|
136
146
|
if (!created) throw new ProviderApiError("Postman returned no collection on import — check the OpenAPI spec is well-formed", 500, void 0);
|
|
137
147
|
return created;
|
|
138
148
|
}
|
|
149
|
+
/** Lists the workspace's environments. */
|
|
139
150
|
async listEnvironments(input) {
|
|
140
151
|
const { environments } = await this.client().environments.list(input.workspaceId);
|
|
141
152
|
return environments;
|
|
142
153
|
}
|
|
154
|
+
/** Finds an environment in the workspace by exact name, or `null` when there is none. */
|
|
143
155
|
async findEnvironmentByName(input) {
|
|
144
156
|
return (await this.listEnvironments(input)).find((e) => e.name === input.name) ?? null;
|
|
145
157
|
}
|
|
158
|
+
/** Creates an environment in the workspace. */
|
|
146
159
|
async createEnvironment(input) {
|
|
147
160
|
const { environment } = await this.client().environments.create(input.workspaceId, input.environment);
|
|
148
161
|
return environment;
|
|
149
162
|
}
|
|
163
|
+
/** Replaces the environment with this uid. */
|
|
150
164
|
async updateEnvironment(input) {
|
|
151
165
|
const { environment } = await this.client().environments.update(input.uid, input.environment);
|
|
152
166
|
return environment;
|
|
153
167
|
}
|
|
168
|
+
/** Finds an API spec in the workspace by exact name, or `null` when there is none. */
|
|
154
169
|
async findSpecByName(input) {
|
|
155
170
|
const { specs } = await this.client().specs.list(input.workspaceId);
|
|
156
171
|
return specs.find((s) => s.name === input.name) ?? null;
|
|
157
172
|
}
|
|
173
|
+
/** Creates an API spec in the workspace from the given file content. */
|
|
158
174
|
async createSpec(input) {
|
|
159
175
|
return this.client().specs.create(input.workspaceId, {
|
|
160
176
|
name: input.name,
|
|
@@ -163,11 +179,13 @@ var PostmanTooling = class {
|
|
|
163
179
|
fileContent: input.fileContent
|
|
164
180
|
});
|
|
165
181
|
}
|
|
182
|
+
/** Writes new content to a file of an existing spec. */
|
|
166
183
|
async upsertSpecFile(input) {
|
|
167
184
|
await this.client().specs.updateFile(input.specId, input.filePath, input.content);
|
|
168
185
|
}
|
|
169
186
|
};
|
|
170
187
|
// src/verify-token.ts
|
|
188
|
+
/** Checks a Postman API key by fetching the authenticated user; resolves to the user's email, username or name, or the failure message. */
|
|
171
189
|
async function verifyToken(token, opts = {}) {
|
|
172
190
|
const client = createPostmanClient({
|
|
173
191
|
token,
|
|
@@ -188,6 +206,7 @@ async function verifyToken(token, opts = {}) {
|
|
|
188
206
|
}
|
|
189
207
|
}
|
|
190
208
|
// src/index.ts
|
|
209
|
+
/** Builds the plugin context from its options; throws when `workspaceId` is missing. */
|
|
191
210
|
function createContext(options) {
|
|
192
211
|
if (!options.workspaceId) throw new Error("@theholocron/holocron-plugin-postman requires `workspaceId` in options");
|
|
193
212
|
let client;
|
|
@@ -200,6 +219,7 @@ function createContext(options) {
|
|
|
200
219
|
})
|
|
201
220
|
};
|
|
202
221
|
}
|
|
222
|
+
/** Builds the `tooling` capability for a context, passing only the options that are set. */
|
|
203
223
|
function tooling(ctx) {
|
|
204
224
|
const opts = { workspaceId: ctx.options.workspaceId };
|
|
205
225
|
if (ctx.options.specFile !== void 0) opts.specFile = ctx.options.specFile;
|
|
@@ -209,6 +229,7 @@ function tooling(ctx) {
|
|
|
209
229
|
if (ctx.options.repoRoot !== void 0) opts.repoRoot = ctx.options.repoRoot;
|
|
210
230
|
return new PostmanTooling(ctx.client, opts);
|
|
211
231
|
}
|
|
232
|
+
/** Creates the Postman plugin: its `tooling` capability and its `connection` probe. */
|
|
212
233
|
function createPlugin(options) {
|
|
213
234
|
const ctx = createContext(options);
|
|
214
235
|
return {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@theholocron/holocron-plugin-postman",
|
|
3
|
-
"version": "5.0.0-alpha.
|
|
3
|
+
"version": "5.0.0-alpha.279",
|
|
4
4
|
"description": "Holocron plugin for Postman. Implements the tooling capability against Postman's REST API — workspace + collection + spec + environment sync.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"holocron",
|
|
@@ -40,19 +40,19 @@
|
|
|
40
40
|
"tsx": "4.23.15",
|
|
41
41
|
"typescript": "^5.9.3",
|
|
42
42
|
"vitest": "^5.0.5",
|
|
43
|
-
"@theholocron/cli": "5.0.0-alpha.
|
|
43
|
+
"@theholocron/cli": "5.0.0-alpha.279",
|
|
44
|
+
"@theholocron/misc-utils": "^1.16.1-alpha.3",
|
|
44
45
|
"@theholocron/http-client": "^1.58.0-alpha.3",
|
|
46
|
+
"@theholocron/eslint-config": "^8.9.0-alpha.4",
|
|
47
|
+
"@theholocron/tsdown-config": "^8.9.0-alpha.4",
|
|
45
48
|
"@theholocron/postman-client": "^1.58.0-alpha.3",
|
|
46
49
|
"@theholocron/tsconfig": "^8.9.0-alpha.4",
|
|
47
|
-
"@theholocron/
|
|
48
|
-
"@theholocron/misc-utils": "^1.16.1-alpha.3",
|
|
49
|
-
"@theholocron/vitest-config": "^8.9.0-alpha.4",
|
|
50
|
-
"@theholocron/tsdown-config": "^8.9.0-alpha.4"
|
|
50
|
+
"@theholocron/vitest-config": "^8.9.0-alpha.4"
|
|
51
51
|
},
|
|
52
52
|
"peerDependencies": {
|
|
53
53
|
"@theholocron/misc-utils": "^1.16.0",
|
|
54
54
|
"@theholocron/postman-client": "^1.43.1",
|
|
55
|
-
"@theholocron/cli": "5.0.0-alpha.
|
|
55
|
+
"@theholocron/cli": "5.0.0-alpha.279"
|
|
56
56
|
},
|
|
57
57
|
"peerDependenciesMeta": {
|
|
58
58
|
"@theholocron/postman-client": {}
|