@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 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.278",
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.278",
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/eslint-config": "^8.9.0-alpha.4",
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.278"
55
+ "@theholocron/cli": "5.0.0-alpha.279"
56
56
  },
57
57
  "peerDependenciesMeta": {
58
58
  "@theholocron/postman-client": {}