@theholocron/holocron-plugin-postman 5.0.0-alpha.39 → 5.0.0-alpha.392

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
@@ -1,3 +1,5 @@
1
+ <!-- alex disable postman-postwoman -->
2
+
1
3
  # `@theholocron/holocron-plugin-postman`
2
4
 
3
5
  Postman plugin for [Holocron](../cli). Implements the **multi-cardinality**
package/dist/index.d.mts CHANGED
@@ -1,9 +1,9 @@
1
- import { AuthError, ResolveTokenInput, Tooling, ToolingDoctorReport } from "@theholocron/cli";
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
- //#region src/auth.d.ts
4
- declare const resolveToken: (input?: ResolveTokenInput) => string;
5
- //#endregion
6
- //#region src/capabilities/tooling.d.ts
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. */
4
+ export declare const resolveToken: import("@theholocron/cli").TokenResolver;
5
+ /** Every token this plugin takes, for `holocron doctor tokens`. */
6
+ export declare const tokens: PluginToken[];
7
7
  interface PostmanToolingOptions {
8
8
  workspaceId: string;
9
9
  /** Local OpenAPI JSON path (relative to repoRoot). */
@@ -17,45 +17,60 @@ interface PostmanToolingOptions {
17
17
  /** Working repo root. Defaults to process.cwd(). */
18
18
  repoRoot?: string;
19
19
  }
20
- declare class PostmanTooling implements Tooling {
20
+ /** The Postman implementation of the `tooling` capability: syncs an OpenAPI spec, collection and environments into a workspace. */
21
+ export declare class PostmanTooling implements Tooling {
21
22
  private readonly client;
23
+ /** The capability this class provides, always `"tooling"`. */
22
24
  readonly key: "tooling";
25
+ /** The provider name, `"postman"`. */
23
26
  readonly providerName = "postman";
24
27
  private readonly opts;
25
28
  private readonly repoRoot;
26
29
  constructor(client: () => PostmanClient$1, opts: PostmanToolingOptions);
27
30
  sync(): Promise<void>;
31
+ /** Checks the key and the configured workspace; reports the authenticated user and the workspace, or why either failed. */
28
32
  doctor(): Promise<ToolingDoctorReport>;
33
+ /** Returns the authenticated Postman user. */
29
34
  getMyself(): Promise<PostmanUser>;
35
+ /** Lists the workspaces the key can see. */
30
36
  listWorkspaces(): Promise<PostmanWorkspace[]>;
37
+ /** Finds a collection in the workspace by exact name, or `null` when there is none. */
31
38
  findCollectionByName(input: {
32
39
  workspaceId: string;
33
40
  name: string;
34
41
  }): Promise<PostmanCollection | null>;
42
+ /** Deletes the collection with this uid. */
35
43
  deleteCollection(uid: string): Promise<void>;
44
+ /** Imports an OpenAPI document into the workspace as a collection; throws when Postman returns none. */
36
45
  importOpenApi(input: {
37
46
  workspaceId: string;
38
47
  spec: unknown;
39
48
  }): Promise<PostmanCollection>;
49
+ /** Lists the workspace's environments. */
40
50
  listEnvironments(input: {
41
51
  workspaceId: string;
42
52
  }): Promise<PostmanEnvironment[]>;
53
+ /** Finds an environment in the workspace by exact name, or `null` when there is none. */
43
54
  findEnvironmentByName(input: {
44
55
  workspaceId: string;
45
56
  name: string;
46
57
  }): Promise<PostmanEnvironment | null>;
58
+ /** Creates an environment in the workspace. */
47
59
  createEnvironment(input: {
48
60
  workspaceId: string;
49
61
  environment: unknown;
50
62
  }): Promise<PostmanEnvironment>;
63
+ /** Replaces the environment with this uid. */
51
64
  updateEnvironment(input: {
52
65
  uid: string;
53
66
  environment: unknown;
54
67
  }): Promise<PostmanEnvironment>;
68
+ /** Finds an API spec in the workspace by exact name, or `null` when there is none. */
55
69
  findSpecByName(input: {
56
70
  workspaceId: string;
57
71
  name: string;
58
72
  }): Promise<PostmanSpec | null>;
73
+ /** Creates an API spec in the workspace from the given file content. */
59
74
  createSpec(input: {
60
75
  workspaceId: string;
61
76
  name: string;
@@ -63,36 +78,21 @@ declare class PostmanTooling implements Tooling {
63
78
  filePath?: string;
64
79
  fileContent: string;
65
80
  }): Promise<PostmanSpec>;
81
+ /** Writes new content to a file of an existing spec. */
66
82
  upsertSpecFile(input: {
67
83
  specId: string;
68
84
  filePath: string;
69
85
  content: string;
70
86
  }): Promise<void>;
71
87
  }
72
- //#endregion
73
- //#region src/verify-token.d.ts
74
- /**
75
- * `verifyToken` — plugin-level export used by `holocron auth set` +
76
- * `holocron auth check`. Hits Postman's `/me` endpoint (returns the
77
- * authenticated user).
78
- */
79
- interface VerifyTokenSuccess {
80
- ok: true;
81
- subject: string;
82
- }
83
- interface VerifyTokenFailure {
84
- ok: false;
85
- message: string;
86
- }
87
- type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
88
88
  interface VerifyTokenOptions {
89
89
  baseUrl?: string;
90
90
  fetch?: typeof fetch;
91
91
  }
92
- declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
93
- //#endregion
94
- //#region src/index.d.ts
95
- interface PostmanPluginOptions extends ResolveTokenInput, PostmanToolingOptions {
92
+ /** Checks a Postman API key by fetching the authenticated user; resolves to the user's email, username or name, or the failure message. */
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. */
95
+ export interface PostmanPluginOptions extends ResolveTokenInput, PostmanToolingOptions {
96
96
  /** Working repo root. Used to resolve relative paths in specFile/envFiles. Defaults to process.cwd(). */
97
97
  repoRoot?: string;
98
98
  /** Override base URL for tests. */
@@ -100,14 +100,23 @@ interface PostmanPluginOptions extends ResolveTokenInput, PostmanToolingOptions
100
100
  /** Override `fetch` for tests. */
101
101
  fetch?: typeof fetch;
102
102
  }
103
- interface PluginContext {
103
+ /** The shared state the Postman plugin's capability and probes are built from. */
104
+ export interface PluginContext {
105
+ /** The options the plugin was created with. */
104
106
  options: PostmanPluginOptions;
107
+ /** Memoized client factory; the API key is resolved on first use. */
105
108
  client: () => PostmanClient;
106
109
  }
107
- declare function createContext(options: PostmanPluginOptions): PluginContext;
108
- declare function tooling(ctx: PluginContext): Tooling;
109
- declare function createPlugin(options: PostmanPluginOptions): {
110
+ /** Builds the plugin context from its options; throws when `workspaceId` is missing. */
111
+ export declare function createContext(options: PostmanPluginOptions): PluginContext;
112
+ /** Builds the `tooling` capability for a context, passing only the options that are set. */
113
+ export declare function tooling(ctx: PluginContext): Tooling;
114
+ /** Creates the Postman plugin: its `tooling` capability and its `connection` probe. */
115
+ export declare function createPlugin(options: PostmanPluginOptions): {
110
116
  name: string;
117
+ probes: {
118
+ connection: import("@theholocron/cli").Probe;
119
+ };
111
120
  capabilities: {
112
121
  tooling: () => Tooling;
113
122
  };
@@ -116,6 +125,5 @@ declare function createPlugin(options: PostmanPluginOptions): {
116
125
  * One-line hint printed by `holocron auth set postman` when no
117
126
  * token is supplied or the supplied token is rejected.
118
127
  */
119
- declare const AUTH_HINT: string;
120
- //#endregion
121
- export { AUTH_HINT, AuthError, PluginContext, type PostmanClient, type PostmanClientOptions, PostmanPlanLimitError, PostmanPluginOptions, PostmanTooling, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createPlugin, createPostmanClient, detectPlanLimit, resolveToken, tooling, verifyToken };
128
+ export declare const AUTH_HINT: string;
129
+ export { AuthError, type PostmanClient, type PostmanClientOptions, PostmanPlanLimitError, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createPostmanClient, detectPlanLimit };
package/dist/index.mjs CHANGED
@@ -1,16 +1,19 @@
1
- import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
1
+ import { AuthError, ProviderApiError, connectionProbe, createResolveToken } from "@theholocron/cli";
2
2
  import { readFile } from "node:fs/promises";
3
3
  import { basename, resolve } from "node:path";
4
+ import { errorMessage } from "@theholocron/misc-utils";
4
5
  import { PostmanPlanLimitError, createPostmanClient, detectPlanLimit } from "@theholocron/postman-client";
5
- //#region src/auth.ts
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. */
6
8
  const resolveToken = createResolveToken({
7
9
  envName: "HOLOCRON_POSTMAN_API_KEY",
8
10
  vendorEnvName: "POSTMAN_API_KEY",
9
11
  keyringService: "postman",
10
12
  errorMessage: "no Postman API key found. Pass --token <KEY>, set HOLOCRON_POSTMAN_API_KEY / POSTMAN_API_KEY, or run: holocron auth set postman <KEY>"
11
13
  });
12
- //#endregion
13
- //#region src/capabilities/tooling.ts
14
+ /** Every token this plugin takes, for `holocron doctor tokens`. */
15
+ const tokens = [resolveToken.token];
16
+ // src/capabilities/tooling.ts
14
17
  /**
15
18
  * `tooling` capability for Postman.
16
19
  *
@@ -33,9 +36,12 @@ const resolveToken = createResolveToken({
33
36
  * `doctor()` probes `/me` for auth + `/workspaces` for workspace
34
37
  * reachability and returns a `ToolingDoctorReport`.
35
38
  */
39
+ /** The Postman implementation of the `tooling` capability: syncs an OpenAPI spec, collection and environments into a workspace. */
36
40
  var PostmanTooling = class {
37
41
  client;
42
+ /** The capability this class provides, always `"tooling"`. */
38
43
  key = "tooling";
44
+ /** The provider name, `"postman"`. */
39
45
  providerName = "postman";
40
46
  opts;
41
47
  repoRoot;
@@ -77,7 +83,8 @@ var PostmanTooling = class {
77
83
  spec: specObj
78
84
  });
79
85
  for (const file of this.opts.envFiles ?? []) {
80
- const envText = await readFile(resolve(this.repoRoot, file), "utf8");
86
+ const envPath = resolve(this.repoRoot, file);
87
+ const envText = await readFile(envPath, "utf8");
81
88
  const envObj = JSON.parse(envText);
82
89
  if (!envObj.name) throw new Error(`Postman environment file ${file} is missing a "name" field`);
83
90
  const existing = await this.findEnvironmentByName({
@@ -94,6 +101,7 @@ var PostmanTooling = class {
94
101
  });
95
102
  }
96
103
  }
104
+ /** Checks the key and the configured workspace; reports the authenticated user and the workspace, or why either failed. */
97
105
  async doctor() {
98
106
  try {
99
107
  const me = await this.getMyself();
@@ -109,49 +117,60 @@ var PostmanTooling = class {
109
117
  } catch (err) {
110
118
  return {
111
119
  ok: false,
112
- message: err instanceof Error ? err.message : String(err)
120
+ message: errorMessage(err)
113
121
  };
114
122
  }
115
123
  }
124
+ /** Returns the authenticated Postman user. */
116
125
  async getMyself() {
117
126
  return (await this.client().me.get()).user ?? {};
118
127
  }
128
+ /** Lists the workspaces the key can see. */
119
129
  async listWorkspaces() {
120
130
  const { workspaces } = await this.client().workspaces.list();
121
131
  return workspaces;
122
132
  }
133
+ /** Finds a collection in the workspace by exact name, or `null` when there is none. */
123
134
  async findCollectionByName(input) {
124
135
  const { collections } = await this.client().collections.list(input.workspaceId);
125
136
  return collections.find((c) => c.name === input.name) ?? null;
126
137
  }
138
+ /** Deletes the collection with this uid. */
127
139
  async deleteCollection(uid) {
128
140
  await this.client().collections.delete(uid);
129
141
  }
142
+ /** Imports an OpenAPI document into the workspace as a collection; throws when Postman returns none. */
130
143
  async importOpenApi(input) {
131
144
  const { collections } = await this.client().import.openapi(input.workspaceId, input.spec);
132
145
  const created = collections[0];
133
146
  if (!created) throw new ProviderApiError("Postman returned no collection on import — check the OpenAPI spec is well-formed", 500, void 0);
134
147
  return created;
135
148
  }
149
+ /** Lists the workspace's environments. */
136
150
  async listEnvironments(input) {
137
151
  const { environments } = await this.client().environments.list(input.workspaceId);
138
152
  return environments;
139
153
  }
154
+ /** Finds an environment in the workspace by exact name, or `null` when there is none. */
140
155
  async findEnvironmentByName(input) {
141
156
  return (await this.listEnvironments(input)).find((e) => e.name === input.name) ?? null;
142
157
  }
158
+ /** Creates an environment in the workspace. */
143
159
  async createEnvironment(input) {
144
160
  const { environment } = await this.client().environments.create(input.workspaceId, input.environment);
145
161
  return environment;
146
162
  }
163
+ /** Replaces the environment with this uid. */
147
164
  async updateEnvironment(input) {
148
165
  const { environment } = await this.client().environments.update(input.uid, input.environment);
149
166
  return environment;
150
167
  }
168
+ /** Finds an API spec in the workspace by exact name, or `null` when there is none. */
151
169
  async findSpecByName(input) {
152
170
  const { specs } = await this.client().specs.list(input.workspaceId);
153
171
  return specs.find((s) => s.name === input.name) ?? null;
154
172
  }
173
+ /** Creates an API spec in the workspace from the given file content. */
155
174
  async createSpec(input) {
156
175
  return this.client().specs.create(input.workspaceId, {
157
176
  name: input.name,
@@ -160,17 +179,13 @@ var PostmanTooling = class {
160
179
  fileContent: input.fileContent
161
180
  });
162
181
  }
182
+ /** Writes new content to a file of an existing spec. */
163
183
  async upsertSpecFile(input) {
164
184
  await this.client().specs.updateFile(input.specId, input.filePath, input.content);
165
185
  }
166
186
  };
167
- //#endregion
168
- //#region src/verify-token.ts
169
- /**
170
- * `verifyToken` — plugin-level export used by `holocron auth set` +
171
- * `holocron auth check`. Hits Postman's `/me` endpoint (returns the
172
- * authenticated user).
173
- */
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. */
174
189
  async function verifyToken(token, opts = {}) {
175
190
  const client = createPostmanClient({
176
191
  token,
@@ -186,12 +201,12 @@ async function verifyToken(token, opts = {}) {
186
201
  } catch (err) {
187
202
  return {
188
203
  ok: false,
189
- message: err instanceof Error ? err.message : String(err)
204
+ message: errorMessage(err)
190
205
  };
191
206
  }
192
207
  }
193
- //#endregion
194
- //#region src/index.ts
208
+ // src/index.ts
209
+ /** Builds the plugin context from its options; throws when `workspaceId` is missing. */
195
210
  function createContext(options) {
196
211
  if (!options.workspaceId) throw new Error("@theholocron/holocron-plugin-postman requires `workspaceId` in options");
197
212
  let client;
@@ -204,6 +219,7 @@ function createContext(options) {
204
219
  })
205
220
  };
206
221
  }
222
+ /** Builds the `tooling` capability for a context, passing only the options that are set. */
207
223
  function tooling(ctx) {
208
224
  const opts = { workspaceId: ctx.options.workspaceId };
209
225
  if (ctx.options.specFile !== void 0) opts.specFile = ctx.options.specFile;
@@ -213,10 +229,21 @@ function tooling(ctx) {
213
229
  if (ctx.options.repoRoot !== void 0) opts.repoRoot = ctx.options.repoRoot;
214
230
  return new PostmanTooling(ctx.client, opts);
215
231
  }
232
+ /** Creates the Postman plugin: its `tooling` capability and its `connection` probe. */
216
233
  function createPlugin(options) {
217
234
  const ctx = createContext(options);
218
235
  return {
219
236
  name: "@theholocron/holocron-plugin-postman",
237
+ probes: { connection: connectionProbe({
238
+ provider: "Postman",
239
+ url: options.baseUrl ?? "https://api.getpostman.com",
240
+ fetch: options.fetch,
241
+ token: () => resolveToken(options),
242
+ verify: (token) => verifyToken(token, {
243
+ baseUrl: options.baseUrl,
244
+ fetch: options.fetch
245
+ })
246
+ }) },
220
247
  capabilities: { tooling: () => tooling(ctx) }
221
248
  };
222
249
  }
@@ -225,5 +252,4 @@ function createPlugin(options) {
225
252
  * token is supplied or the supplied token is rejected.
226
253
  */
227
254
  const AUTH_HINT = "generate a Postman API key at https://postman.co/settings/me/api-keys, then run: holocron auth set postman <KEY>";
228
- //#endregion
229
- export { AUTH_HINT, AuthError, PostmanPlanLimitError, PostmanTooling, createContext, createPlugin, createPostmanClient, detectPlanLimit, resolveToken, tooling, verifyToken };
255
+ export { AUTH_HINT, AuthError, PostmanPlanLimitError, PostmanTooling, createContext, createPlugin, createPostmanClient, detectPlanLimit, resolveToken, tokens, tooling, verifyToken };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/holocron-plugin-postman",
3
- "version": "5.0.0-alpha.39",
3
+ "version": "5.0.0-alpha.392",
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",
@@ -8,12 +8,12 @@
8
8
  "postman",
9
9
  "tooling"
10
10
  ],
11
- "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-postman#readme",
11
+ "homepage": "https://docs.theholocron.dev/holocron/plugins/postman/",
12
12
  "bugs": "https://github.com/theholocron/holocron/issues",
13
13
  "repository": {
14
14
  "type": "git",
15
15
  "url": "git+https://github.com/theholocron/holocron.git",
16
- "directory": "packages/holocron-plugin-postman"
16
+ "directory": "plugins/holocron-plugin-postman"
17
17
  },
18
18
  "license": "MIT",
19
19
  "author": "Newton Koumantzelis",
@@ -30,27 +30,29 @@
30
30
  "dist"
31
31
  ],
32
32
  "devDependencies": {
33
- "@theholocron/eslint-config": "^8.0.0",
34
- "@theholocron/http-client": "^1.24.0",
35
- "@theholocron/postman-client": "^1.24.0",
36
- "@theholocron/tsconfig": "^8.0.0",
37
- "@theholocron/tsdown-config": "^8.0.0",
38
- "@theholocron/vitest-config": "^8.0.0",
39
33
  "@types/node": "^26",
40
- "@vitest/coverage-v8": "^4.1.11",
41
- "@vitest/eslint-plugin": "^1.6.27",
42
- "eslint": "^10.8.1",
43
- "eslint-plugin-n": "^18.3.0",
44
- "globals": "^17.11.0",
45
- "tsdown": "^0.22.14",
46
- "tsx": "4.23.12",
34
+ "@vitest/coverage-v8": "^5.1.0",
35
+ "@vitest/eslint-plugin": "^1.6.28",
36
+ "eslint": "^10.14.0",
37
+ "eslint-plugin-n": "^18.5.0",
38
+ "globals": "^17.14.0",
39
+ "tsdown": "^0.23.5",
40
+ "tsx": "4.23.15",
47
41
  "typescript": "^5.9.3",
48
- "vitest": "^4.1.11",
49
- "@theholocron/cli": "5.0.0-alpha.39"
42
+ "vitest": "^5.1.0",
43
+ "@theholocron/cli": "5.0.0-alpha.392",
44
+ "@theholocron/eslint-config": "^8.9.0-alpha.15",
45
+ "@theholocron/postman-client": "^1.58.0-alpha.25",
46
+ "@theholocron/tsconfig": "^8.9.0-alpha.15",
47
+ "@theholocron/misc-utils": "^1.17.0-alpha.3",
48
+ "@theholocron/tsdown-config": "^8.9.0-alpha.15",
49
+ "@theholocron/vitest-config": "^8.9.0-alpha.15",
50
+ "@theholocron/http-client": "^1.58.0-alpha.25"
50
51
  },
51
52
  "peerDependencies": {
52
- "@theholocron/postman-client": "^1.24.0",
53
- "@theholocron/cli": "5.0.0-alpha.39"
53
+ "@theholocron/misc-utils": "^1.16.0",
54
+ "@theholocron/postman-client": "^1.43.1",
55
+ "@theholocron/cli": "5.0.0-alpha.392"
54
56
  },
55
57
  "peerDependenciesMeta": {
56
58
  "@theholocron/postman-client": {}
@@ -62,11 +64,11 @@
62
64
  "access": "public"
63
65
  },
64
66
  "scripts": {
65
- "delivery.build": "tsdown",
66
- "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
67
+ "build": "tsdown",
68
+ "lint:code": "eslint .",
69
+ "test:unit": "vitest run --coverage",
67
70
  "test:watch": "vitest",
68
- "validate": "tsx scripts/validate.mjs",
69
- "verification.typeSafety": "holocron run verification.typeSafety --",
70
- "verification.unitTests": "holocron run verification.unitTests --"
71
+ "typecheck": "tsc --noEmit",
72
+ "validate:plugin": "tsx scripts/validate.mjs"
71
73
  }
72
74
  }