@theholocron/postman-client 1.58.0-alpha.3 → 1.58.0-alpha.31

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/postman-client`
2
4
 
3
5
  TypeScript client for the [Postman API](https://www.postman.com/postman/postman-public-workspace/documentation/8kv5pif/postman-api).
@@ -27,6 +29,16 @@ const { collections } = await postman.collections.list("workspace-id");
27
29
  // Delete a collection
28
30
  await postman.collections.delete("collection-uid");
29
31
 
32
+ // Create or replace a collection from a Postman collection document
33
+ await postman.collections.create("workspace-id", collection);
34
+ await postman.collections.update("collection-uid", collection);
35
+
36
+ // Make a workspace
37
+ await postman.workspaces.create({ name: "Holocron", type: "personal" });
38
+
39
+ // Read one environment with its variables
40
+ const { environment } = await postman.environments.get("environment-uid");
41
+
30
42
  // Import an OpenAPI spec as a collection
31
43
  const { collections: imported } = await postman.import.openapi("workspace-id", spec);
32
44
 
package/dist/index.d.mts CHANGED
@@ -1,5 +1,6 @@
1
1
  import "@theholocron/http-client";
2
2
  import { ErrorSink, Logger } from "@theholocron/observability/core";
3
+ /** Options for `createPostmanClient`. */
3
4
  interface PostmanClientOptions {
4
5
  /** Postman API key. */
5
6
  token: string;
@@ -12,77 +13,161 @@ interface PostmanClientOptions {
12
13
  /** Reports transport failures and unexpected 5xx. Defaults to a no-op. */
13
14
  errors?: ErrorSink;
14
15
  }
16
+ /** A Postman collection, as listed by the API. */
15
17
  interface PostmanCollection {
18
+ /** The collection's id. */
16
19
  id: string;
20
+ /** The collection's unique id, prefixed with its owner's id. */
17
21
  uid: string;
22
+ /** The collection's name. */
18
23
  name: string;
19
24
  }
25
+ /** The response of listing collections. */
20
26
  interface PostmanCollectionsResponse {
27
+ /** The collections returned. */
21
28
  collections: PostmanCollection[];
22
29
  }
30
+ /** The response of fetching, creating or updating one collection. */
31
+ interface PostmanCollectionResponse {
32
+ /** The collection. */
33
+ collection: PostmanCollection;
34
+ }
35
+ /** One variable of an environment. */
36
+ interface PostmanEnvironmentValue {
37
+ /** The variable's name. */
38
+ key: string;
39
+ /** The variable's value. */
40
+ value?: string;
41
+ /** The variable's type, such as `default` or `secret`. */
42
+ type?: string;
43
+ /** Whether the variable is in use. */
44
+ enabled?: boolean;
45
+ }
46
+ /** A Postman environment, as listed by the API. */
23
47
  interface PostmanEnvironment {
48
+ /** The environment's id. */
24
49
  id: string;
50
+ /** The environment's unique id, prefixed with its owner's id. */
25
51
  uid: string;
52
+ /** The environment's name. */
26
53
  name: string;
54
+ /** The variables; only present when one environment is fetched. */
55
+ values?: PostmanEnvironmentValue[];
27
56
  }
57
+ /** The response of listing environments. */
28
58
  interface PostmanEnvironmentsResponse {
59
+ /** The environments returned. */
29
60
  environments: PostmanEnvironment[];
30
61
  }
62
+ /** The response of fetching or creating one environment. */
31
63
  interface PostmanEnvironmentResponse {
64
+ /** The environment. */
32
65
  environment: PostmanEnvironment;
33
66
  }
67
+ /** The response of importing an OpenAPI definition. */
34
68
  interface PostmanImportOpenApiResponse {
69
+ /** The collections the import created. */
35
70
  collections: PostmanCollection[];
36
71
  }
72
+ /** The user the API key belongs to. */
37
73
  interface PostmanUser {
74
+ /** The user's id. */
38
75
  id?: number | string;
76
+ /** The user's username. */
39
77
  username?: string;
78
+ /** The user's email address. */
40
79
  email?: string;
80
+ /** The user's full name. */
41
81
  fullName?: string;
42
82
  }
83
+ /** The response of fetching the current user. */
43
84
  interface PostmanMeResponse {
85
+ /** The user. */
44
86
  user?: PostmanUser;
45
87
  }
88
+ /** A Postman API specification, as listed by the API. */
46
89
  interface PostmanSpec {
90
+ /** The specification's id. */
47
91
  id: string;
92
+ /** The specification's name. */
48
93
  name: string;
94
+ /** The specification's type. */
49
95
  type: string;
50
96
  }
97
+ /** The response of listing specifications. */
51
98
  interface PostmanSpecsResponse {
99
+ /** The specifications returned. */
52
100
  specs: PostmanSpec[];
53
101
  }
102
+ /** What to send to Postman to create a specification. */
54
103
  interface PostmanCreateSpecInput {
104
+ /** The specification's name. */
55
105
  name: string;
106
+ /** The specification's content, as a string. */
56
107
  fileContent: string;
108
+ /** The specification's type, when set. */
57
109
  type?: string;
110
+ /** The path of the specification's file, when set. */
58
111
  filePath?: string;
59
112
  }
113
+ /** A Postman workspace, as listed by the API. */
60
114
  interface PostmanWorkspace {
115
+ /** The workspace's id. */
61
116
  id: string;
117
+ /** The workspace's name. */
62
118
  name: string;
119
+ /** The workspace's type. */
63
120
  type: string;
64
121
  }
122
+ /** The response of listing workspaces. */
65
123
  interface PostmanWorkspacesResponse {
124
+ /** The workspaces returned. */
66
125
  workspaces: PostmanWorkspace[];
67
126
  }
127
+ /** What `workspaces.create` takes. */
128
+ interface PostmanCreateWorkspaceInput {
129
+ /** The workspace's name. */
130
+ name: string;
131
+ /** The workspace's type: `personal` or `team`. */
132
+ type: "personal" | "team";
133
+ /** A description shown in Postman. */
134
+ description?: string;
135
+ }
136
+ /** The response of creating one workspace. */
137
+ interface PostmanWorkspaceResponse {
138
+ /** The workspace made. */
139
+ workspace: Pick<PostmanWorkspace, "id" | "name">;
140
+ }
68
141
  /**
69
142
  * Thrown when Postman returns a `limitReachedError` (e.g., a Free-tier
70
143
  * account hitting the "0 APIs" cap).
71
144
  */
72
145
  export declare class PostmanPlanLimitError extends Error {
146
+ /** Postman's message about the plan limit. */
73
147
  readonly limitMessage: string;
148
+ /** The raw response body Postman returned. */
74
149
  readonly body: string;
150
+ /** The error's name, `"PostmanPlanLimitError"`. */
75
151
  name: string;
76
- constructor(limitMessage: string, body: string);
152
+ constructor(
153
+ /** Postman's message about the plan limit. */
154
+ limitMessage: string,
155
+ /** The raw response body Postman returned. */
156
+ body: string);
77
157
  }
158
+ /** Returns the message of a `limitReachedError` in a Postman response body, or `null` when the body is not one (or is not JSON). */
78
159
  export declare function detectPlanLimit(body: string): string | null;
160
+ /** Creates a Postman client with `collections`, `environments`, `import`, `me`, `specs` and `workspaces` groups sharing one REST client. */
79
161
  export declare function createPostmanClient(opts: PostmanClientOptions): {
80
162
  collections: {
81
163
  list: (workspaceId: string) => Promise<PostmanCollectionsResponse>;
164
+ create: (workspaceId: string, collection: unknown) => Promise<PostmanCollectionResponse>;
165
+ update: (uid: string, collection: unknown) => Promise<PostmanCollectionResponse>;
82
166
  delete: (uid: string) => Promise<void>;
83
167
  };
84
168
  environments: {
85
169
  list: (workspaceId: string) => Promise<PostmanEnvironmentsResponse>;
170
+ get: (uid: string) => Promise<PostmanEnvironmentResponse>;
86
171
  create: (workspaceId: string, environment: unknown) => Promise<PostmanEnvironmentResponse>;
87
172
  update: (uid: string, environment: unknown) => Promise<PostmanEnvironmentResponse>;
88
173
  };
@@ -99,7 +184,9 @@ export declare function createPostmanClient(opts: PostmanClientOptions): {
99
184
  };
100
185
  workspaces: {
101
186
  list: () => Promise<PostmanWorkspacesResponse>;
187
+ create: (input: PostmanCreateWorkspaceInput) => Promise<PostmanWorkspaceResponse>;
102
188
  };
103
189
  };
190
+ /** The client `createPostmanClient` returns. */
104
191
  export type PostmanClient = ReturnType<typeof createPostmanClient>;
105
- export type { PostmanClientOptions, PostmanCollection, PostmanCollectionsResponse, PostmanCreateSpecInput, PostmanEnvironment, PostmanEnvironmentResponse, PostmanEnvironmentsResponse, PostmanImportOpenApiResponse, PostmanMeResponse, PostmanSpec, PostmanSpecsResponse, PostmanUser, PostmanWorkspace, PostmanWorkspacesResponse };
192
+ export type { PostmanClientOptions, PostmanCollection, PostmanCollectionResponse, PostmanCollectionsResponse, PostmanCreateSpecInput, PostmanCreateWorkspaceInput, PostmanEnvironment, PostmanEnvironmentResponse, PostmanEnvironmentValue, PostmanEnvironmentsResponse, PostmanImportOpenApiResponse, PostmanMeResponse, PostmanSpec, PostmanSpecsResponse, PostmanUser, PostmanWorkspace, PostmanWorkspaceResponse, PostmanWorkspacesResponse };
package/dist/index.mjs CHANGED
@@ -3,6 +3,15 @@ import { createRestClient } from "@theholocron/http-client";
3
3
  function collections(rest) {
4
4
  return {
5
5
  list: (workspaceId) => rest.request("/collections", { query: { workspace: workspaceId } }),
6
+ create: (workspaceId, collection) => rest.request("/collections", {
7
+ method: "POST",
8
+ query: { workspace: workspaceId },
9
+ body: { collection }
10
+ }),
11
+ update: (uid, collection) => rest.request(`/collections/${encodeURIComponent(uid)}`, {
12
+ method: "PUT",
13
+ body: { collection }
14
+ }),
6
15
  delete: (uid) => rest.request(`/collections/${encodeURIComponent(uid)}`, { method: "DELETE" })
7
16
  };
8
17
  }
@@ -10,6 +19,7 @@ function collections(rest) {
10
19
  function environments(rest) {
11
20
  return {
12
21
  list: (workspaceId) => rest.request("/environments", { query: { workspace: workspaceId } }),
22
+ get: (uid) => rest.request(`/environments/${encodeURIComponent(uid)}`),
13
23
  create: (workspaceId, environment) => rest.request("/environments", {
14
24
  method: "POST",
15
25
  query: { workspace: workspaceId },
@@ -66,6 +76,7 @@ function specs(rest) {
66
76
  var PostmanPlanLimitError = class extends Error {
67
77
  limitMessage;
68
78
  body;
79
+ /** The error's name, `"PostmanPlanLimitError"`. */
69
80
  name = "PostmanPlanLimitError";
70
81
  constructor(limitMessage, body) {
71
82
  super(limitMessage);
@@ -73,6 +84,7 @@ var PostmanPlanLimitError = class extends Error {
73
84
  this.body = body;
74
85
  }
75
86
  };
87
+ /** Returns the message of a `limitReachedError` in a Postman response body, or `null` when the body is not one (or is not JSON). */
76
88
  function detectPlanLimit(body) {
77
89
  try {
78
90
  const parsed = JSON.parse(body);
@@ -110,9 +122,16 @@ function createPostmanRestClient(opts) {
110
122
  }
111
123
  // src/workspaces/workspaces.ts
112
124
  function workspaces(rest) {
113
- return { list: () => rest.request("/workspaces") };
125
+ return {
126
+ list: () => rest.request("/workspaces"),
127
+ create: (input) => rest.request("/workspaces", {
128
+ method: "POST",
129
+ body: { workspace: input }
130
+ })
131
+ };
114
132
  }
115
133
  // src/index.ts
134
+ /** Creates a Postman client with `collections`, `environments`, `import`, `me`, `specs` and `workspaces` groups sharing one REST client. */
116
135
  function createPostmanClient(opts) {
117
136
  const rest = createPostmanRestClient(opts);
118
137
  return {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/postman-client",
3
- "version": "1.58.0-alpha.3",
3
+ "version": "1.58.0-alpha.31",
4
4
  "description": "A TypeScript client for the Postman API",
5
5
  "keywords": [
6
6
  "postman",
@@ -31,23 +31,23 @@
31
31
  "dist"
32
32
  ],
33
33
  "dependencies": {
34
- "@theholocron/http-client": "^1.58.0-alpha.3",
35
- "@theholocron/observability": "^0.6.1-alpha.1"
34
+ "@theholocron/http-client": "^1.58.0-alpha.31",
35
+ "@theholocron/observability": "^0.7.0-alpha.4"
36
36
  },
37
37
  "devDependencies": {
38
38
  "@types/node": "^26",
39
- "@vitest/coverage-v8": "^5.0.5",
40
- "@vitest/eslint-plugin": "^1.6.27",
41
- "eslint": "^10.8.1",
42
- "eslint-plugin-n": "^18.3.0",
43
- "globals": "^17.11.0",
44
- "tsdown": "^0.23.3",
39
+ "@vitest/coverage-v8": "^5.1.0",
40
+ "@vitest/eslint-plugin": "^1.6.28",
41
+ "eslint": "^10.14.0",
42
+ "eslint-plugin-n": "^18.5.0",
43
+ "globals": "^17.14.0",
44
+ "tsdown": "^0.23.5",
45
45
  "typescript": "^5.9.3",
46
- "vitest": "^5.0.5",
47
- "@theholocron/eslint-config": "^8.9.0-alpha.3",
48
- "@theholocron/tsconfig": "^8.9.0-alpha.3",
49
- "@theholocron/tsdown-config": "^8.9.0-alpha.3",
50
- "@theholocron/vitest-config": "^8.9.0-alpha.3"
46
+ "vitest": "^5.1.0",
47
+ "@theholocron/eslint-config": "^8.9.0-alpha.17",
48
+ "@theholocron/tsdown-config": "^8.9.0-alpha.17",
49
+ "@theholocron/tsconfig": "^8.9.0-alpha.17",
50
+ "@theholocron/vitest-config": "^8.9.0-alpha.17"
51
51
  },
52
52
  "engines": {
53
53
  "node": ">=22.0.0"
@@ -56,10 +56,10 @@
56
56
  "access": "public"
57
57
  },
58
58
  "scripts": {
59
- "delivery.build": "tsdown && node ../scripts/check-bundle-size.mjs",
60
- "sourceQuality.staticAnalysis": "eslint .",
59
+ "build": "tsdown && node ../scripts/check-bundle-size.mjs",
60
+ "lint:code": "eslint .",
61
+ "test:unit": "vitest run --coverage",
61
62
  "test:watch": "vitest",
62
- "verification.typeSafety": "tsc --noEmit",
63
- "verification.unitTests": "vitest run"
63
+ "typecheck": "tsc --noEmit"
64
64
  }
65
65
  }