@theholocron/holocron-plugin-postman 2.0.0-alpha.1 → 2.0.0-alpha.5

package/dist/index.d.mts

@@ -4,10 +4,13 @@ import { Tooling, ToolingDoctorReport } from "@theholocron/cli";
 /**
  * Token resolution for the Postman plugin.
  *
- * Resolution order:
+ * Resolution order (matches the standard 4-step precedence set by
+ * `.notes/tech-auth-bootstrap.spec.md`):
  *   1. explicit `cliToken` argument (from `--token` flag)
  *   2. HOLOCRON_POSTMAN_API_KEY env var (preferred — explicit intent)
  *   3. POSTMAN_API_KEY env var (Postman's own default)
+ *   4. keyring (com.theholocron.cli / "postman")
+ *   5. AuthError naming all four options + the bootstrap hint
  */
 declare class AuthError extends Error {
   name: string;
@@ -17,6 +20,8 @@ interface ResolveTokenInput {
   cliToken?: string;
   /** Env vars; passed in for testability. Defaults to `process.env`. */
   env?: NodeJS.ProcessEnv;
+  /** Keyring lookup fn; passed in for testability. Defaults to `getToken(provider)`. */
+  keyring?: (provider: string) => string | null;
 }
 declare function resolveToken(input?: ResolveTokenInput): string;
 //#endregion
@@ -167,6 +172,27 @@ declare class PostmanPlanLimitError extends Error {
  */
 declare function detectPlanLimit(body: string): string | null;
 //#endregion
+//#region src/verify-token.d.ts
+/**
+ * `verifyToken` — plugin-level export used by `holocron auth set` +
+ * `holocron auth check`. Hits Postman's `/me` endpoint (returns the
+ * authenticated user).
+ */
+interface VerifyTokenSuccess {
+  ok: true;
+  subject: string;
+}
+interface VerifyTokenFailure {
+  ok: false;
+  message: string;
+}
+type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
+interface VerifyTokenOptions {
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
+//#endregion
 //#region src/index.d.ts
 interface PostmanPluginOptions extends ResolveTokenInput, PostmanToolingOptions {
   /** Working repo root. Used to resolve relative paths in specFile/envFiles. Defaults to process.cwd(). */
@@ -188,5 +214,10 @@ declare function createPlugin(options: PostmanPluginOptions): {
     tooling: () => Tooling;
   };
 };
+/**
+ * One-line hint printed by `holocron auth set postman` when no
+ * token is supplied or the supplied token is rejected.
+ */
+declare const AUTH_HINT: string;
 //#endregion
-export { AuthError, PluginContext, PostmanPlanLimitError, PostmanPluginOptions, PostmanRestClient, PostmanTooling, ResolveTokenInput, createContext, createPlugin, detectPlanLimit, resolveToken, tooling };
+export { AUTH_HINT, AuthError, PluginContext, PostmanPlanLimitError, PostmanPluginOptions, PostmanRestClient, PostmanTooling, ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createPlugin, detectPlanLimit, resolveToken, tooling, verifyToken };

package/dist/index.mjs

@@ -1,22 +1,26 @@
+import { ProviderApiError, getToken } from "@theholocron/cli";
 import { readFile } from "node:fs/promises";
 import { basename, resolve } from "node:path";
-import { ProviderApiError } from "@theholocron/cli";
 //#region src/auth.ts
 /**
 * Token resolution for the Postman plugin.
 *
-* Resolution order:
+* Resolution order (matches the standard 4-step precedence set by
+* `.notes/tech-auth-bootstrap.spec.md`):
 *   1. explicit `cliToken` argument (from `--token` flag)
 *   2. HOLOCRON_POSTMAN_API_KEY env var (preferred — explicit intent)
 *   3. POSTMAN_API_KEY env var (Postman's own default)
+*   4. keyring (com.theholocron.cli / "postman")
+*   5. AuthError naming all four options + the bootstrap hint
 */
 var AuthError = class extends Error {
 	name = "AuthError";
 };
 function resolveToken(input = {}) {
 	const env = input.env ?? process.env;
-	const token = input.cliToken || env.HOLOCRON_POSTMAN_API_KEY || env.POSTMAN_API_KEY;
-	if (!token) throw new AuthError("no Postman API key found. Pass --token <KEY>, or set HOLOCRON_POSTMAN_API_KEY / POSTMAN_API_KEY.");
+	const keyring = input.keyring ?? getToken;
+	const token = input.cliToken || env["HOLOCRON_POSTMAN_API_KEY"] || env["POSTMAN_API_KEY"] || keyring("postman");
+	if (!token) throw new AuthError("no Postman API key found. Pass --token <KEY>, set HOLOCRON_POSTMAN_API_KEY / POSTMAN_API_KEY, or run: holocron auth set postman <KEY>");
 	return token;
 }
 //#endregion
@@ -321,6 +325,31 @@ var PostmanRestClient = class {
 	}
 };
 //#endregion
+//#region src/verify-token.ts
+/**
+* `verifyToken` — plugin-level export used by `holocron auth set` +
+* `holocron auth check`. Hits Postman's `/me` endpoint (returns the
+* authenticated user).
+*/
+async function verifyToken(token, opts = {}) {
+	const restOpts = { token };
+	if (opts.baseUrl !== void 0) restOpts.baseUrl = opts.baseUrl;
+	if (opts.fetch !== void 0) restOpts.fetch = opts.fetch;
+	const rest = new PostmanRestClient(restOpts);
+	try {
+		const res = await rest.request("/me");
+		return {
+			ok: true,
+			subject: `user @ ${res?.user?.email ?? res?.user?.username ?? res?.user?.fullName ?? String(res?.user?.id ?? "unknown")}`
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
 //#region src/index.ts
 function createContext(options) {
 	if (!options.workspaceId) throw new Error("@theholocron/holocron-plugin-postman requires `workspaceId` in options");
@@ -348,5 +377,10 @@ function createPlugin(options) {
 		capabilities: { tooling: () => tooling(ctx) }
 	};
 }
+/**
+* One-line hint printed by `holocron auth set postman` when no
+* token is supplied or the supplied token is rejected.
+*/
+const AUTH_HINT = "generate a Postman API key at https://postman.co/settings/me/api-keys, then run: holocron auth set postman <KEY>";
 //#endregion
-export { AuthError, PostmanPlanLimitError, PostmanRestClient, PostmanTooling, createContext, createPlugin, detectPlanLimit, resolveToken, tooling };
+export { AUTH_HINT, AuthError, PostmanPlanLimitError, PostmanRestClient, PostmanTooling, createContext, createPlugin, detectPlanLimit, resolveToken, tooling, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-postman",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0-alpha.5",
   "description": "Holocron plugin for Postman. Implements the tooling capability against Postman's REST API — workspace + collection + spec + environment sync.",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-postman#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
@@ -21,7 +21,7 @@
     }
   },
   "peerDependencies": {
-    "@theholocron/cli": "2.0.0-alpha.1"
+    "@theholocron/cli": "2.0.0-alpha.5"
   },
   "devDependencies": {
     "@theholocron/tsconfig": "^4.1.0",
@@ -32,7 +32,8 @@
     "typescript": "^5.9.3",
     "vitest": "^3.2.6",
     "tsdown": "^0.22.3",
-    "@theholocron/cli": "2.0.0-alpha.1"
+    "tsx": "^4.22.4",
+    "@theholocron/cli": "2.0.0-alpha.5"
   },
   "publishConfig": {
     "access": "public"
@@ -47,7 +48,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "validate": "tsx scripts/validate.mjs"
   },
   "types": "./dist/index.d.mts"
 }