Print claim URL after provisioning, expose in status

README.md

@@ -21,6 +21,7 @@ That's it. The first `scan`:
 2. POSTs the package list to Patchstack with **no** UUID.
 3. Patchstack provisions a fresh site and returns its UUID.
 4. The connector writes the UUID to `.patchstackrc.json` so the next `scan` targets the same site.
+5. The connector prints a claim URL — open it in a browser to attach the new site to your Patchstack account. You can re-display it any time with `npx @patchstack/connect status`.
 
 Then wire it into builds:
 

dist/index.cjs

@@ -32,6 +32,7 @@ var src_exports = {};
 __export(src_exports, {
   DEFAULT_ENDPOINT: () => DEFAULT_ENDPOINT,
   PatchstackError: () => PatchstackError,
+  buildClaimUrl: () => buildClaimUrl,
   buildEndpointUrl: () => buildEndpointUrl,
   buildWirePayload: () => buildWirePayload,
   compareVersions: () => compareVersions,
@@ -433,6 +434,10 @@ function buildEndpointUrl(base, siteUuid) {
   const trimmed = base.replace(/\/$/, "");
   return siteUuid !== void 0 && siteUuid !== null && siteUuid.length > 0 ? `${trimmed}/${encodeURIComponent(siteUuid)}` : trimmed;
 }
+function buildClaimUrl(endpoint, siteUuid) {
+  const origin = new URL(endpoint).origin;
+  return `${origin}/claim?site=${encodeURIComponent(siteUuid)}`;
+}
 async function postManifest(config, payload) {
   const url = buildEndpointUrl(config.endpoint, config.siteUuid);
   const timeoutMs = config.timeoutMs;
@@ -607,6 +612,7 @@ async function scanAndReport(options = {}) {
 0 && (module.exports = {
   DEFAULT_ENDPOINT,
   PatchstackError,
+  buildClaimUrl,
   buildEndpointUrl,
   buildWirePayload,
   compareVersions,

dist/index.d.cts

@@ -68,6 +68,14 @@ declare function compareVersions(a: string, b: string): number;
 
 declare const DEFAULT_ENDPOINT = "http://api.patchstack.com/monitor/pulse/manifest";
 declare function buildEndpointUrl(base: string, siteUuid?: string | null): string;
+/**
+ * Build the claim URL for a site. The claim page lives on the same origin as
+ * the API endpoint, at `/claim?site=<uuid>`. Using the API endpoint's origin
+ * (rather than a hard-coded https://app.patchstack.com) means staging, ngrok
+ * tunnels and local dev environments all produce a claim URL on the same host
+ * the connector is already talking to.
+ */
+declare function buildClaimUrl(endpoint: string, siteUuid: string): string;
 declare function postManifest(config: Config, payload: WirePayload): Promise<StoreManifestResponse>;
 
 interface ConfigFile {
@@ -108,4 +116,4 @@ interface ScanAndReportResult {
 }
 declare function scanAndReport(options?: ScanAndReportOptions): Promise<ScanAndReportResult>;
 
-export { type Config, DEFAULT_ENDPOINT, type Ecosystem, type Manifest, type PackageEntry, PatchstackError, type ScanAndReportOptions, type ScanAndReportResult, type StoreManifestResponse, buildEndpointUrl, buildWirePayload, compareVersions, detectLockfile, persistSiteUuid, postManifest, resolveConfig, scanAndReport, scanLockfile, writeConfigFile };
+export { type Config, DEFAULT_ENDPOINT, type Ecosystem, type Manifest, type PackageEntry, PatchstackError, type ScanAndReportOptions, type ScanAndReportResult, type StoreManifestResponse, buildClaimUrl, buildEndpointUrl, buildWirePayload, compareVersions, detectLockfile, persistSiteUuid, postManifest, resolveConfig, scanAndReport, scanLockfile, writeConfigFile };

dist/index.d.ts

@@ -68,6 +68,14 @@ declare function compareVersions(a: string, b: string): number;
 
 declare const DEFAULT_ENDPOINT = "http://api.patchstack.com/monitor/pulse/manifest";
 declare function buildEndpointUrl(base: string, siteUuid?: string | null): string;
+/**
+ * Build the claim URL for a site. The claim page lives on the same origin as
+ * the API endpoint, at `/claim?site=<uuid>`. Using the API endpoint's origin
+ * (rather than a hard-coded https://app.patchstack.com) means staging, ngrok
+ * tunnels and local dev environments all produce a claim URL on the same host
+ * the connector is already talking to.
+ */
+declare function buildClaimUrl(endpoint: string, siteUuid: string): string;
 declare function postManifest(config: Config, payload: WirePayload): Promise<StoreManifestResponse>;
 
 interface ConfigFile {
@@ -108,4 +116,4 @@ interface ScanAndReportResult {
 }
 declare function scanAndReport(options?: ScanAndReportOptions): Promise<ScanAndReportResult>;
 
-export { type Config, DEFAULT_ENDPOINT, type Ecosystem, type Manifest, type PackageEntry, PatchstackError, type ScanAndReportOptions, type ScanAndReportResult, type StoreManifestResponse, buildEndpointUrl, buildWirePayload, compareVersions, detectLockfile, persistSiteUuid, postManifest, resolveConfig, scanAndReport, scanLockfile, writeConfigFile };
+export { type Config, DEFAULT_ENDPOINT, type Ecosystem, type Manifest, type PackageEntry, PatchstackError, type ScanAndReportOptions, type ScanAndReportResult, type StoreManifestResponse, buildClaimUrl, buildEndpointUrl, buildWirePayload, compareVersions, detectLockfile, persistSiteUuid, postManifest, resolveConfig, scanAndReport, scanLockfile, writeConfigFile };

src/cli.ts

@@ -1,6 +1,6 @@
 import { scanLockfile } from './parsers/index.js';
 import { buildWirePayload } from './normalize.js';
-import { postManifest } from './client.js';
+import { buildClaimUrl, postManifest } from './client.js';
 import { persistSiteUuid, resolveConfig, writeConfigFile } from './config.js';
 import { PatchstackError } from './types.js';
 
@@ -156,6 +156,16 @@ async function runScan(args: ParsedArgs): Promise<number> {
   } else {
     console.log(`Server response: ${response.message ?? JSON.stringify(response)}`);
   }
+
+  // On the first scan (provisioning), surface the claim URL so the user can
+  // attach this site to their Patchstack account. `npx @patchstack/connect status`
+  // re-displays it any time.
+  if (provisioning && response.uuid !== undefined && response.uuid.length > 0) {
+    console.log('');
+    console.log('Claim this site to view vulnerability reports in your Patchstack dashboard:');
+    console.log(`  ${buildClaimUrl(config.endpoint, response.uuid)}`);
+  }
+
   return 0;
 }
 
@@ -168,6 +178,9 @@ async function runStatus(args: ParsedArgs): Promise<number> {
   console.log(`Site UUID:  ${config.siteUuid ?? '(none yet — the next `scan` will provision one)'}`);
   console.log(`Endpoint:   ${config.endpoint}`);
   console.log(`Timeout:    ${config.timeoutMs}ms`);
+  if (config.siteUuid !== null) {
+    console.log(`Claim URL:  ${buildClaimUrl(config.endpoint, config.siteUuid)}`);
+  }
   return 0;
 }
 

src/client.ts

@@ -11,6 +11,18 @@ export function buildEndpointUrl(base: string, siteUuid?: string | null): string
     : trimmed;
 }
 
+/**
+ * Build the claim URL for a site. The claim page lives on the same origin as
+ * the API endpoint, at `/claim?site=<uuid>`. Using the API endpoint's origin
+ * (rather than a hard-coded https://app.patchstack.com) means staging, ngrok
+ * tunnels and local dev environments all produce a claim URL on the same host
+ * the connector is already talking to.
+ */
+export function buildClaimUrl(endpoint: string, siteUuid: string): string {
+  const origin = new URL(endpoint).origin;
+  return `${origin}/claim?site=${encodeURIComponent(siteUuid)}`;
+}
+
 export async function postManifest(
   config: Config,
   payload: WirePayload,

src/index.ts

@@ -6,7 +6,7 @@ import type { Config, Manifest, StoreManifestResponse } from './types.js';
 
 export { scanLockfile, detectLockfile } from './parsers/index.js';
 export { buildWirePayload, compareVersions } from './normalize.js';
-export { postManifest, buildEndpointUrl, DEFAULT_ENDPOINT } from './client.js';
+export { postManifest, buildClaimUrl, buildEndpointUrl, DEFAULT_ENDPOINT } from './client.js';
 export { persistSiteUuid, resolveConfig, writeConfigFile } from './config.js';
 export {
   PatchstackError,

tests/client.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { buildEndpointUrl, postManifest } from '../src/client.js';
+import { buildClaimUrl, buildEndpointUrl, postManifest } from '../src/client.js';
 import { PatchstackError } from '../src/types.js';
 
 describe('buildEndpointUrl', () => {
@@ -24,6 +24,44 @@ describe('buildEndpointUrl', () => {
   });
 });
 
+describe('buildClaimUrl', () => {
+  it('uses the API endpoint origin plus /claim?site=<uuid>', () => {
+    expect(
+      buildClaimUrl('https://app.patchstack.com/monitor/pulse/manifest', 'abc-def'),
+    ).toBe('https://app.patchstack.com/claim?site=abc-def');
+  });
+
+  it('preserves staging origins (ngrok)', () => {
+    expect(
+      buildClaimUrl('https://3ad1-18-170-248-162.ngrok-free.app/monitor/pulse/manifest', 'xyz'),
+    ).toBe('https://3ad1-18-170-248-162.ngrok-free.app/claim?site=xyz');
+  });
+
+  it('drops the manifest path from the API endpoint', () => {
+    expect(
+      buildClaimUrl('https://example.com/some/deep/path', 'abc'),
+    ).toBe('https://example.com/claim?site=abc');
+  });
+
+  it('handles a trailing slash on the endpoint', () => {
+    expect(
+      buildClaimUrl('https://example.com/monitor/pulse/manifest/', 'abc'),
+    ).toBe('https://example.com/claim?site=abc');
+  });
+
+  it('url-encodes the uuid', () => {
+    expect(buildClaimUrl('https://example.com/x', 'a b')).toBe(
+      'https://example.com/claim?site=a%20b',
+    );
+  });
+
+  it('preserves the scheme (http vs https) of the API endpoint', () => {
+    expect(buildClaimUrl('http://localhost:8001/monitor/pulse/manifest', 'abc')).toBe(
+      'http://localhost:8001/claim?site=abc',
+    );
+  });
+});
+
 describe('postManifest', () => {
   afterEach(() => {
     vi.unstubAllGlobals();