@theholocron/holocron-plugin-postman 5.0.0-alpha.432 → 5.0.0-alpha.434

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
@@ -57,31 +57,35 @@ Generate the key at <https://web.postman.co/settings/me/api-keys>.
57
57
 
58
58
  ```
59
59
 
60
- - `workspaceId` (required) — Postman workspace id. Find via `holocron tooling postman workspaces`.
60
+ - `workspace` / `workspaceId` (one is required) — the workspace by name (`sync` finds it, or makes it) or by id (wins over the name). Find an id via `holocron tooling postman workspaces`.
61
+ - `workspaceType` (optional) — `personal` (default) or `team`: the type of a workspace `sync` makes.
62
+ - `collectionFiles` (optional) — hand-written Postman collection JSON files. Each is matched to a collection in the workspace by `info.name` and replaced in place, or created.
61
63
  - `specFile` (optional) — relative path to the local OpenAPI JSON. `sync` reads + uploads this.
62
64
  - `specName` (optional) — display name in Postman's Spec Hub. Defaults to repo name.
63
65
  - `collectionName` (optional) — name for the imported collection. Defaults to `specName`.
64
- - `envFiles` (optional) — local Postman environment JSON files to push.
66
+ - `envFiles` (optional) — local Postman environment JSON files to push. A secret the file leaves empty keeps the value the environment already holds.
67
+
68
+ `sync` needs at least one of `specFile`, `collectionFiles` and `envFiles`.
65
69
 
66
70
  ## What's implemented
67
71
 
68
- | Method | What it does |
69
- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
70
- | **Tooling interface** | |
71
- | `sync()` | Reads `specFile`, upserts the Spec Hub spec, delete-then-imports the collection, find-or-creates each env in `envFiles`. |
72
- | `doctor()` | Probes `/me` + `/workspaces`; returns `{ ok, message }`. |
73
- | **Postman-specific methods** (on `PostmanTooling`, not on the `Tooling` interface) | |
74
- | `getMyself` | `GET /me` — authed user identity. |
75
- | `listWorkspaces` | `GET /workspaces`. |
76
- | `findCollectionByName` | `GET /collections?workspace=…` + name filter. |
77
- | `deleteCollection` | `DELETE /collections/{uid}`. |
78
- | `importOpenApi` | `POST /import/openapi?workspace=…` with the spec stringified into `{ type: "string", input }`. |
79
- | `findEnvironmentByName` | `GET /environments?workspace=…` + name filter. |
80
- | `createEnvironment` | `POST /environments?workspace=…`. |
81
- | `updateEnvironment` | `PUT /environments/{uid}`. |
82
- | `findSpecByName` | `GET /specs?workspaceId=…` + name filter. |
83
- | `createSpec` | `POST /specs?workspaceId=…` (flat body — name/type are NOT wrapped under `spec`). |
84
- | `upsertSpecFile` | `PATCH /specs/{id}/files/{path}` (PUT returns 404 here). |
72
+ | Method | What it does |
73
+ | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
74
+ | **Tooling interface** | |
75
+ | `sync()` | Finds or makes the workspace; with `specFile`, upserts the Spec Hub spec and delete-then-imports the collection; replaces or creates each `collectionFiles` collection; find-or-creates each env in `envFiles`. |
76
+ | `doctor()` | Probes `/me` + `/workspaces`; returns `{ ok, message }`. |
77
+ | **Postman-specific methods** (on `PostmanTooling`, not on the `Tooling` interface) | |
78
+ | `getMyself` | `GET /me` — authed user identity. |
79
+ | `listWorkspaces` | `GET /workspaces`. |
80
+ | `findCollectionByName` | `GET /collections?workspace=…` + name filter. |
81
+ | `deleteCollection` | `DELETE /collections/{uid}`. |
82
+ | `importOpenApi` | `POST /import/openapi?workspace=…` with the spec stringified into `{ type: "string", input }`. |
83
+ | `findEnvironmentByName` | `GET /environments?workspace=…` + name filter. |
84
+ | `createEnvironment` | `POST /environments?workspace=…`. |
85
+ | `updateEnvironment` | `PUT /environments/{uid}`. |
86
+ | `findSpecByName` | `GET /specs?workspaceId=…` + name filter. |
87
+ | `createSpec` | `POST /specs?workspaceId=…` (flat body — name/type are NOT wrapped under `spec`). |
88
+ | `upsertSpecFile` | `PATCH /specs/{id}/files/{path}` (PUT returns 404 here). |
85
89
 
86
90
  ## Status
87
91
 
package/dist/index.d.mts CHANGED
@@ -5,7 +5,14 @@ export declare const resolveToken: import("@theholocron/cli").TokenResolver;
5
5
  /** Every token this plugin takes, for `holocron doctor secrets --verify`. */
6
6
  export declare const tokens: PluginToken[];
7
7
  interface PostmanToolingOptions {
8
- workspaceId: string;
8
+ /** Postman workspace id. Wins over `workspace`. */
9
+ workspaceId?: string;
10
+ /** Workspace name; found, or made on `sync()` when no workspace has it. */
11
+ workspace?: string;
12
+ /** Type of a workspace `sync()` makes. Defaults to `personal`. */
13
+ workspaceType?: "personal" | "team";
14
+ /** Local Postman collection JSON files to push (relative to repoRoot), matched to Postman's by `info.name`. */
15
+ collectionFiles?: string[];
9
16
  /** Local OpenAPI JSON path (relative to repoRoot). */
10
17
  specFile?: string;
11
18
  /** Display name in Postman. Defaults to the OpenAPI spec's `info.title`. */
@@ -26,8 +33,14 @@ export declare class PostmanTooling implements Tooling {
26
33
  readonly providerName = "postman";
27
34
  private readonly opts;
28
35
  private readonly repoRoot;
36
+ private workspaceIdPromise;
29
37
  constructor(client: () => PostmanClient$1, opts: PostmanToolingOptions);
30
38
  sync(): Promise<void>;
39
+ private syncSpec;
40
+ private syncCollectionFile;
41
+ private syncEnvironmentFile;
42
+ /** The workspace id: `workspaceId`, else the workspace named `workspace`, which is made when absent. Memoized. */
43
+ private resolveWorkspaceId;
31
44
  /** Checks the key and the configured workspace; reports the authenticated user and the workspace, or why either failed. */
32
45
  doctor(): Promise<ToolingDoctorReport>;
33
46
  /** Returns the authenticated Postman user. */
@@ -39,6 +52,16 @@ export declare class PostmanTooling implements Tooling {
39
52
  workspaceId: string;
40
53
  name: string;
41
54
  }): Promise<PostmanCollection | null>;
55
+ /** Creates a collection in the workspace from a Postman collection document. */
56
+ createCollection(input: {
57
+ workspaceId: string;
58
+ collection: unknown;
59
+ }): Promise<PostmanCollection>;
60
+ /** Replaces the collection with this uid. */
61
+ updateCollection(input: {
62
+ uid: string;
63
+ collection: unknown;
64
+ }): Promise<PostmanCollection>;
42
65
  /** Deletes the collection with this uid. */
43
66
  deleteCollection(uid: string): Promise<void>;
44
67
  /** Imports an OpenAPI document into the workspace as a collection; throws when Postman returns none. */
@@ -55,6 +78,8 @@ export declare class PostmanTooling implements Tooling {
55
78
  workspaceId: string;
56
79
  name: string;
57
80
  }): Promise<PostmanEnvironment | null>;
81
+ /** Reads one environment with its variables. */
82
+ getEnvironment(uid: string): Promise<PostmanEnvironment>;
58
83
  /** Creates an environment in the workspace. */
59
84
  createEnvironment(input: {
60
85
  workspaceId: string;
package/dist/index.mjs CHANGED
@@ -31,7 +31,12 @@ const tokens = [resolveToken.token];
31
31
  * (Postman's import-from-OpenAPI path is create-only — no stable
32
32
  * update path for collections produced from a spec)
33
33
  * 4. Import the spec as a fresh collection
34
- * 5. For each `envFiles[i]`, find-or-create the environment
34
+ * 5. For each `collectionFiles[i]`, find the collection by `info.name` and replace it, or create it
35
+ * 6. For each `envFiles[i]`, find-or-create the environment; a secret the file leaves empty keeps the value
36
+ * the environment already holds
37
+ *
38
+ * The workspace is `workspaceId` when given, else the one named `workspace`, made (type `workspaceType`,
39
+ * default `personal`) when it does not exist. `doctor()` never makes it.
35
40
  *
36
41
  * `doctor()` probes `/me` for auth + `/workspaces` for workspace
37
42
  * reachability and returns a `ToolingDoctorReport`.
@@ -45,22 +50,30 @@ var PostmanTooling = class {
45
50
  providerName = "postman";
46
51
  opts;
47
52
  repoRoot;
53
+ workspaceIdPromise;
48
54
  constructor(client, opts) {
49
55
  this.client = client;
50
- if (!opts.workspaceId) throw new Error("PostmanTooling requires `workspaceId` in options");
56
+ if (!opts.workspaceId && !opts.workspace) throw new Error("PostmanTooling requires `workspaceId` or `workspace` in options");
51
57
  this.opts = opts;
52
58
  this.repoRoot = opts.repoRoot ?? process.cwd();
53
59
  }
54
60
  async sync() {
55
- if (!this.opts.specFile) throw new Error("PostmanTooling.sync() requires `specFile` in options (local OpenAPI JSON path)");
56
- const specPath = resolve(this.repoRoot, this.opts.specFile);
61
+ const { specFile, collectionFiles = [], envFiles = [] } = this.opts;
62
+ if (!specFile && collectionFiles.length === 0 && envFiles.length === 0) throw new Error("PostmanTooling.sync() requires `specFile` (local OpenAPI JSON path), `collectionFiles` or `envFiles` in options");
63
+ const workspaceId = await this.resolveWorkspaceId();
64
+ if (specFile) await this.syncSpec(workspaceId, specFile);
65
+ for (const file of collectionFiles) await this.syncCollectionFile(workspaceId, file);
66
+ for (const file of envFiles) await this.syncEnvironmentFile(workspaceId, file);
67
+ }
68
+ async syncSpec(workspaceId, specFile) {
69
+ const specPath = resolve(this.repoRoot, specFile);
57
70
  const specText = await readFile(specPath, "utf8");
58
71
  const specObj = JSON.parse(specText);
59
72
  const inferredName = specObj.info?.title ?? basename(specPath);
60
73
  const specName = this.opts.specName ?? inferredName;
61
74
  const collectionName = this.opts.collectionName ?? specName;
62
75
  const existingSpec = await this.findSpecByName({
63
- workspaceId: this.opts.workspaceId,
76
+ workspaceId,
64
77
  name: specName
65
78
  });
66
79
  if (existingSpec) await this.upsertSpecFile({
@@ -69,46 +82,91 @@ var PostmanTooling = class {
69
82
  content: specText
70
83
  });
71
84
  else await this.createSpec({
72
- workspaceId: this.opts.workspaceId,
85
+ workspaceId,
73
86
  name: specName,
74
87
  fileContent: specText
75
88
  });
76
89
  const existingCollection = await this.findCollectionByName({
77
- workspaceId: this.opts.workspaceId,
90
+ workspaceId,
78
91
  name: collectionName
79
92
  });
80
93
  if (existingCollection) await this.deleteCollection(existingCollection.uid);
81
94
  await this.importOpenApi({
82
- workspaceId: this.opts.workspaceId,
95
+ workspaceId,
83
96
  spec: specObj
84
97
  });
85
- for (const file of this.opts.envFiles ?? []) {
86
- const envPath = resolve(this.repoRoot, file);
87
- const envText = await readFile(envPath, "utf8");
88
- const envObj = JSON.parse(envText);
89
- if (!envObj.name) throw new Error(`Postman environment file ${file} is missing a "name" field`);
90
- const existing = await this.findEnvironmentByName({
91
- workspaceId: this.opts.workspaceId,
92
- name: envObj.name
93
- });
94
- if (existing) await this.updateEnvironment({
95
- uid: existing.uid,
96
- environment: envObj
97
- });
98
- else await this.createEnvironment({
99
- workspaceId: this.opts.workspaceId,
98
+ }
99
+ async syncCollectionFile(workspaceId, file) {
100
+ const collection = JSON.parse(await readFile(resolve(this.repoRoot, file), "utf8"));
101
+ const name = collection.info?.name;
102
+ if (!name) throw new Error(`Postman collection file ${file} is missing \`info.name\``);
103
+ const existing = await this.findCollectionByName({
104
+ workspaceId,
105
+ name
106
+ });
107
+ if (existing) await this.updateCollection({
108
+ uid: existing.uid,
109
+ collection
110
+ });
111
+ else await this.createCollection({
112
+ workspaceId,
113
+ collection
114
+ });
115
+ }
116
+ async syncEnvironmentFile(workspaceId, file) {
117
+ const envText = await readFile(resolve(this.repoRoot, file), "utf8");
118
+ const envObj = JSON.parse(envText);
119
+ if (!envObj.name) throw new Error(`Postman environment file ${file} is missing a "name" field`);
120
+ const existing = await this.findEnvironmentByName({
121
+ workspaceId,
122
+ name: envObj.name
123
+ });
124
+ if (!existing) {
125
+ await this.createEnvironment({
126
+ workspaceId,
100
127
  environment: envObj
101
128
  });
129
+ return;
102
130
  }
131
+ const values = envObj.values ?? [];
132
+ const environment = values.some((v) => v.type === "secret" && !v.value) ? {
133
+ ...envObj,
134
+ values: keepSecrets(values, (await this.getEnvironment(existing.uid)).values ?? [])
135
+ } : envObj;
136
+ await this.updateEnvironment({
137
+ uid: existing.uid,
138
+ environment
139
+ });
140
+ }
141
+ /** The workspace id: `workspaceId`, else the workspace named `workspace`, which is made when absent. Memoized. */
142
+ resolveWorkspaceId() {
143
+ const { workspaceId, workspace, workspaceType } = this.opts;
144
+ if (workspaceId) return Promise.resolve(workspaceId);
145
+ return this.workspaceIdPromise ??= (async () => {
146
+ const name = workspace;
147
+ const found = (await this.listWorkspaces()).find((w) => w.name === name);
148
+ if (found) return found.id;
149
+ const { workspace: made } = await this.client().workspaces.create({
150
+ name,
151
+ type: workspaceType ?? "personal"
152
+ });
153
+ return made.id;
154
+ })();
103
155
  }
104
156
  /** Checks the key and the configured workspace; reports the authenticated user and the workspace, or why either failed. */
105
157
  async doctor() {
106
158
  try {
107
159
  const me = await this.getMyself();
108
- const found = (await this.listWorkspaces()).find((w) => w.id === this.opts.workspaceId);
160
+ const workspaces = await this.listWorkspaces();
161
+ const wanted = this.opts.workspaceId ?? this.opts.workspace;
162
+ const found = workspaces.find((w) => this.opts.workspaceId ? w.id === wanted : w.name === wanted);
163
+ if (!found && !this.opts.workspaceId) return {
164
+ ok: true,
165
+ message: `authed as ${me.username}; workspace ${wanted} does not exist yet, \`sync\` makes it`
166
+ };
109
167
  if (!found) return {
110
168
  ok: false,
111
- message: `authed as ${me.username}, but workspace ${this.opts.workspaceId} not visible`
169
+ message: `authed as ${me.username}, but workspace ${wanted} not visible`
112
170
  };
113
171
  return {
114
172
  ok: true,
@@ -135,6 +193,16 @@ var PostmanTooling = class {
135
193
  const { collections } = await this.client().collections.list(input.workspaceId);
136
194
  return collections.find((c) => c.name === input.name) ?? null;
137
195
  }
196
+ /** Creates a collection in the workspace from a Postman collection document. */
197
+ async createCollection(input) {
198
+ const { collection } = await this.client().collections.create(input.workspaceId, input.collection);
199
+ return collection;
200
+ }
201
+ /** Replaces the collection with this uid. */
202
+ async updateCollection(input) {
203
+ const { collection } = await this.client().collections.update(input.uid, input.collection);
204
+ return collection;
205
+ }
138
206
  /** Deletes the collection with this uid. */
139
207
  async deleteCollection(uid) {
140
208
  await this.client().collections.delete(uid);
@@ -155,6 +223,11 @@ var PostmanTooling = class {
155
223
  async findEnvironmentByName(input) {
156
224
  return (await this.listEnvironments(input)).find((e) => e.name === input.name) ?? null;
157
225
  }
226
+ /** Reads one environment with its variables. */
227
+ async getEnvironment(uid) {
228
+ const { environment } = await this.client().environments.get(uid);
229
+ return environment;
230
+ }
158
231
  /** Creates an environment in the workspace. */
159
232
  async createEnvironment(input) {
160
233
  const { environment } = await this.client().environments.create(input.workspaceId, input.environment);
@@ -184,6 +257,20 @@ var PostmanTooling = class {
184
257
  await this.client().specs.updateFile(input.specId, input.filePath, input.content);
185
258
  }
186
259
  };
260
+ /**
261
+ * The file's variables, where a secret the file leaves empty takes the value the environment holds under the same
262
+ * key, so syncing never blanks a secret someone set in Postman.
263
+ */
264
+ function keepSecrets(local, existing) {
265
+ return local.map((v) => {
266
+ if (v.type !== "secret" || v.value) return v;
267
+ const held = existing.find((e) => e.key === v.key);
268
+ return held?.value ? {
269
+ ...v,
270
+ value: held.value
271
+ } : v;
272
+ });
273
+ }
187
274
  // src/verify-token.ts
188
275
  /** Checks a Postman API key by fetching the authenticated user; resolves to the user's email, username or name, or the failure message. */
189
276
  async function verifyToken(token, opts = {}) {
@@ -208,7 +295,7 @@ async function verifyToken(token, opts = {}) {
208
295
  // src/index.ts
209
296
  /** Builds the plugin context from its options; throws when `workspaceId` is missing. */
210
297
  function createContext(options) {
211
- if (!options.workspaceId) throw new Error("@theholocron/holocron-plugin-postman requires `workspaceId` in options");
298
+ if (!options.workspaceId && !options.workspace) throw new Error("@theholocron/holocron-plugin-postman requires `workspaceId` or `workspace` in options");
212
299
  let client;
213
300
  return {
214
301
  options,
@@ -221,7 +308,11 @@ function createContext(options) {
221
308
  }
222
309
  /** Builds the `tooling` capability for a context, passing only the options that are set. */
223
310
  function tooling(ctx) {
224
- const opts = { workspaceId: ctx.options.workspaceId };
311
+ const opts = {};
312
+ if (ctx.options.workspaceId !== void 0) opts.workspaceId = ctx.options.workspaceId;
313
+ if (ctx.options.workspace !== void 0) opts.workspace = ctx.options.workspace;
314
+ if (ctx.options.workspaceType !== void 0) opts.workspaceType = ctx.options.workspaceType;
315
+ if (ctx.options.collectionFiles !== void 0) opts.collectionFiles = ctx.options.collectionFiles;
225
316
  if (ctx.options.specFile !== void 0) opts.specFile = ctx.options.specFile;
226
317
  if (ctx.options.specName !== void 0) opts.specName = ctx.options.specName;
227
318
  if (ctx.options.collectionName !== void 0) opts.collectionName = ctx.options.collectionName;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/holocron-plugin-postman",
3
- "version": "5.0.0-alpha.432",
3
+ "version": "5.0.0-alpha.434",
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.1.0",
43
- "@theholocron/cli": "5.0.0-alpha.432",
44
- "@theholocron/http-client": "^1.58.0-alpha.29",
43
+ "@theholocron/cli": "5.0.0-alpha.434",
44
+ "@theholocron/http-client": "^1.58.0-alpha.30",
45
45
  "@theholocron/misc-utils": "^1.17.0-alpha.4",
46
- "@theholocron/postman-client": "^1.58.0-alpha.29",
46
+ "@theholocron/postman-client": "^1.58.0-alpha.30",
47
47
  "@theholocron/tsconfig": "^8.9.0-alpha.17",
48
- "@theholocron/eslint-config": "^8.9.0-alpha.17",
49
48
  "@theholocron/tsdown-config": "^8.9.0-alpha.17",
50
- "@theholocron/vitest-config": "^8.9.0-alpha.17"
49
+ "@theholocron/vitest-config": "^8.9.0-alpha.17",
50
+ "@theholocron/eslint-config": "^8.9.0-alpha.17"
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.432"
55
+ "@theholocron/cli": "5.0.0-alpha.434"
56
56
  },
57
57
  "peerDependenciesMeta": {
58
58
  "@theholocron/postman-client": {}