@postman-cse/onboarding-bootstrap 0.11.0 → 0.13.0

package/src/lib/github/github-api-client.ts

@@ -1,262 +0,0 @@
-import { createSecretMasker, type SecretMasker } from '../secrets.js';
-
-export type GitHubApiClientAuthMode =
-  | 'github_token_first'
-  | 'fallback_pat_first'
-  | 'app_token';
-
-export interface GitHubApiClientOptions {
-  apiBase?: string;
-  appToken?: string;
-  authMode?: GitHubApiClientAuthMode;
-  fallbackToken?: string;
-  fetch?: typeof fetch;
-  repository: string;
-  secretMasker?: SecretMasker;
-  token: string;
-}
-
-function buildErrorMessage(
-  method: string,
-  path: string,
-  response: Response,
-  body: string,
-  masker: SecretMasker
-): string {
-  const status = `${response.status}${response.statusText ? ` ${response.statusText}` : ''}`;
-  const sanitizedBody = masker(body || '');
-  return sanitizedBody
-    ? masker(`${method} ${path} failed with ${status} - ${sanitizedBody}`)
-    : masker(`${method} ${path} failed with ${status} - [REDACTED]`);
-}
-
-export class GitHubApiClient {
-  private readonly apiBase: string;
-  private readonly authMode: GitHubApiClientAuthMode;
-  private readonly appToken: string;
-  private readonly fallbackToken: string;
-  private readonly fetchImpl: typeof fetch;
-  private readonly owner: string;
-  private readonly repo: string;
-  private readonly repository: string;
-  private readonly secretMasker: SecretMasker;
-  private readonly token: string;
-
-  constructor(options: GitHubApiClientOptions) {
-    this.apiBase = String(options.apiBase || 'https://api.github.com').replace(
-      /\/+$/,
-      ''
-    );
-    this.appToken = String(options.appToken || '').trim();
-    this.authMode = options.authMode || 'github_token_first';
-    this.fallbackToken = String(options.fallbackToken || '').trim();
-    this.fetchImpl = options.fetch ?? fetch;
-    this.repository = options.repository;
-    const [owner, repo] = options.repository.split('/');
-    this.owner = owner;
-    this.repo = repo;
-    this.token = String(options.token || '').trim();
-    this.secretMasker =
-      options.secretMasker ??
-      createSecretMasker([this.token, this.fallbackToken, this.appToken]);
-  }
-
-  getTokenOrder(): string[] {
-    const ordered: string[] = [];
-
-    if (this.authMode === 'app_token') {
-      if (this.appToken) ordered.push(this.appToken);
-      if (this.token && this.token !== this.appToken) ordered.push(this.token);
-      if (
-        this.fallbackToken &&
-        this.fallbackToken !== this.appToken &&
-        this.fallbackToken !== this.token
-      ) {
-        ordered.push(this.fallbackToken);
-      }
-      return ordered;
-    }
-
-    if (this.authMode === 'fallback_pat_first') {
-      if (this.fallbackToken) ordered.push(this.fallbackToken);
-      if (this.token && this.token !== this.fallbackToken) ordered.push(this.token);
-      return ordered;
-    }
-
-    if (this.token) ordered.push(this.token);
-    if (this.fallbackToken && this.fallbackToken !== this.token) {
-      ordered.push(this.fallbackToken);
-    }
-    return ordered;
-  }
-
-  private isVariablesEndpoint(path: string): boolean {
-    return path.startsWith(`/repos/${this.owner}/${this.repo}/actions/variables`);
-  }
-
-  private canUseFallback(path: string): boolean {
-    return (
-      this.isVariablesEndpoint(path) ||
-      path.includes(`/repos/${this.owner}/${this.repo}/contents`) ||
-      path.includes('/dispatches')
-    );
-  }
-
-  private rateLimitDelayMs(response: Response, attempt: number): number {
-    const retryAfter = Number(response.headers.get('retry-after') || '');
-    if (Number.isFinite(retryAfter) && retryAfter > 0) {
-      return Math.min(retryAfter * 1000, 120_000);
-    }
-
-    const resetAtSeconds = Number(response.headers.get('x-ratelimit-reset') || '');
-    if (Number.isFinite(resetAtSeconds) && resetAtSeconds > 0) {
-      const delta = resetAtSeconds * 1000 - Date.now();
-      if (delta > 0) {
-        return Math.min(delta + 250, 120_000);
-      }
-    }
-
-    const base = Math.min(5000 * Math.pow(2, attempt), 120_000);
-    const jitter = Math.floor(Math.random() * 250);
-    return Math.min(base + jitter, 120_000);
-  }
-
-  private async requestWithToken(
-    path: string,
-    init: RequestInit,
-    token: string
-  ): Promise<Response> {
-    const MAX_RETRIES = 5;
-    const normalizedToken = String(token || '').trim();
-    if (!normalizedToken) {
-      throw new Error(`Missing GitHub auth token for request ${path}`);
-    }
-
-    for (let attempt = 0; ; attempt++) {
-      const response = await this.fetchImpl(`${this.apiBase}${path}`, {
-        ...init,
-        headers: {
-          Accept: 'application/vnd.github+json',
-          Authorization: `Bearer ${normalizedToken}`,
-          'Content-Type': 'application/json',
-          ...(init.headers || {})
-        }
-      });
-
-      if (attempt < MAX_RETRIES && (response.status === 403 || response.status === 429)) {
-        const body = await response.clone().text().catch(() => '');
-        if (isRateLimitedResponse(response, body)) {
-          const delay = this.rateLimitDelayMs(response, attempt);
-          console.log(
-            `GitHub API rate limited, retrying in ${Math.ceil(delay / 1000)}s (attempt ${attempt + 1}/${MAX_RETRIES})...`
-          );
-          await new Promise((r) => setTimeout(r, delay));
-          continue;
-        }
-      }
-
-      return response;
-    }
-  }
-
-  private async request(path: string, init: RequestInit = {}): Promise<Response> {
-    const orderedTokens = this.getTokenOrder();
-    if (orderedTokens.length === 0) {
-      throw new Error('No GitHub auth token configured');
-    }
-
-    const first = await this.requestWithToken(path, init, orderedTokens[0]);
-
-    if (orderedTokens.length < 2 || !this.canUseFallback(path)) {
-      return first;
-    }
-
-    // GitHub returns 404 (not 403) when GITHUB_TOKEN lacks permission to
-    // read repo variables — this prevents information disclosure but means
-    // the action silently treats existing variables as missing. Retry with
-    // the fallback PAT for both 403 and variable-GET-404 cases.
-    const isVariableGet404 =
-      first.status === 404 &&
-      (!init.method || init.method === 'GET') &&
-      this.isVariablesEndpoint(path);
-
-    if (first.status !== 403 && !isVariableGet404) {
-      return first;
-    }
-
-    return this.requestWithToken(path, init, orderedTokens[1]);
-  }
-
-  async setRepositoryVariable(name: string, value: string): Promise<void> {
-    if (!value) {
-      throw new Error(`Repo variable ${name} is empty`);
-    }
-
-    const path = `/repos/${this.repository}/actions/variables`;
-    const body = JSON.stringify({ name, value: String(value) });
-    const createResponse = await this.request(path, {
-      method: 'POST',
-      body
-    });
-
-    if (createResponse.ok || createResponse.status === 201) {
-      return;
-    }
-
-    if (createResponse.status === 409 || createResponse.status === 422) {
-      const updatePath = `/repos/${this.repository}/actions/variables/${name}`;
-      const updateResponse = await this.request(updatePath, {
-        method: 'PATCH',
-        body
-      });
-      if (updateResponse.ok) {
-        return;
-      }
-      const text = await updateResponse.text().catch(() => '');
-      throw new Error(
-        buildErrorMessage('PATCH', updatePath, updateResponse, text, this.secretMasker)
-      );
-    }
-
-    const text = await createResponse.text().catch(() => '');
-    throw new Error(
-      buildErrorMessage('POST', path, createResponse, text, this.secretMasker)
-    );
-  }
-
-  async getRepositoryVariable(name: string): Promise<string> {
-    const path = `/repos/${this.repository}/actions/variables/${name}`;
-    const response = await this.request(path, {
-      method: 'GET'
-    });
-
-    if (response.status === 404) {
-      return '';
-    }
-    if (!response.ok) {
-      const text = await response.text().catch(() => '');
-      throw new Error(
-        buildErrorMessage('GET', path, response, text, this.secretMasker)
-      );
-    }
-
-    const data = (await response.json()) as { value?: string };
-    return String(data.value || '');
-  }
-}
-
-function isRateLimitedResponse(response: Response, body: string): boolean {
-  if (response.status !== 403 && response.status !== 429) return false;
-
-  const remaining = response.headers.get('x-ratelimit-remaining');
-  const retryAfter = response.headers.get('retry-after');
-
-  if (remaining === '0') return true;
-  if (retryAfter) return true;
-
-  const message = body.toLowerCase();
-  if (message.includes('secondary rate limit')) return true;
-  if (message.includes('api rate limit exceeded')) return true;
-
-  return response.status === 429;
-}

package/src/lib/http-error.ts

@@ -1,80 +0,0 @@
-import { redactSecrets, sanitizeHeaders, type HeaderBag } from './secrets.js';
-
-export interface HttpErrorInit {
-  method: string;
-  url: string;
-  status: number;
-  statusText: string;
-  requestHeaders?: HeaderBag;
-  responseBody?: string;
-  secretValues?: unknown;
-  bodyLimit?: number;
-}
-
-function truncate(value: string, limit: number): string {
-  if (value.length <= limit) {
-    return value;
-  }
-  return `${value.slice(0, limit)}...[truncated]`;
-}
-
-function buildMessage(init: HttpErrorInit): string {
-  const method = String(init.method || 'GET').toUpperCase();
-  const status = `${init.status}${init.statusText ? ` ${init.statusText}` : ''}`;
-  const url = redactSecrets(init.url, init.secretValues);
-  const body = truncate(
-    redactSecrets(init.responseBody || '', init.secretValues),
-    Math.max(0, init.bodyLimit ?? 800)
-  );
-  return body ? `${method} ${url} failed: ${status} - ${body}` : `${method} ${url} failed: ${status}`;
-}
-
-export class HttpError extends Error {
-  readonly method: string;
-  readonly requestHeaders: HeaderBag | undefined;
-  readonly responseBody: string;
-  readonly secretValues: unknown;
-  readonly status: number;
-  readonly statusText: string;
-  readonly url: string;
-
-  constructor(init: HttpErrorInit) {
-    super(buildMessage(init));
-    this.name = 'HttpError';
-    this.method = String(init.method || 'GET').toUpperCase();
-    this.requestHeaders = init.requestHeaders;
-    this.responseBody = init.responseBody || '';
-    this.secretValues = init.secretValues;
-    this.status = init.status;
-    this.statusText = init.statusText;
-    this.url = init.url;
-  }
-
-  static async fromResponse(
-    response: Response,
-    init: Omit<HttpErrorInit, 'responseBody' | 'status' | 'statusText'> & {
-      responseBody?: string;
-    }
-  ): Promise<HttpError> {
-    const responseBody =
-      init.responseBody ?? (await response.text().catch(() => ''));
-    return new HttpError({
-      ...init,
-      responseBody,
-      status: response.status,
-      statusText: response.statusText
-    });
-  }
-
-  toJSON() {
-    return {
-      method: this.method,
-      name: this.name,
-      requestHeaders: sanitizeHeaders(this.requestHeaders, this.secretValues),
-      responseBody: redactSecrets(this.responseBody, this.secretValues),
-      status: this.status,
-      statusText: this.statusText,
-      url: redactSecrets(this.url, this.secretValues)
-    };
-  }
-}

package/src/lib/postman/internal-integration-adapter.ts

@@ -1,358 +0,0 @@
-import { HttpError } from '../http-error.js';
-import { normalizeGitRepoUrl } from './postman-assets-client.js';
-import { createSecretMasker, type SecretMasker } from '../secrets.js';
-
-export type InternalIntegrationBackend = 'bifrost';
-
-export interface GovernanceAssociation {
-  envUid: string;
-  systemEnvId: string;
-}
-
-export interface SpecificationCollectionLink {
-  collectionId: string;
-  syncOptions?: {
-    syncExamples: boolean;
-  };
-}
-
-export interface InternalIntegrationAdapterOptions {
-  accessToken: string;
-  backend: string;
-  fetchImpl?: typeof fetch;
-  secretMasker?: SecretMasker;
-  teamId: string;
-  workerBaseUrl?: string;
-}
-
-export interface InternalIntegrationAdapter {
-  assignWorkspaceToGovernanceGroup(
-    workspaceId: string,
-    domain: string,
-    mappingJson: string
-  ): Promise<void>;
-  associateSystemEnvironments(
-    workspaceId: string,
-    associations: GovernanceAssociation[]
-  ): Promise<void>;
-  connectWorkspaceToRepository(
-    workspaceId: string,
-    repoUrl: string
-  ): Promise<void>;
-  linkCollectionsToSpecification(
-    specificationId: string,
-    collections: SpecificationCollectionLink[]
-  ): Promise<void>;
-  syncCollection(
-    specificationId: string,
-    collectionId: string
-  ): Promise<void>;
-}
-
-class BifrostInternalIntegrationAdapter implements InternalIntegrationAdapter {
-  private readonly accessToken: string;
-  private readonly fetchImpl: typeof fetch;
-  private readonly secretMasker: SecretMasker;
-  private readonly teamId: string;
-  private readonly workerBaseUrl: string;
-
-  constructor(options: InternalIntegrationAdapterOptions) {
-    this.accessToken = String(options.accessToken || '').trim();
-    this.fetchImpl = options.fetchImpl ?? fetch;
-    this.secretMasker =
-      options.secretMasker ?? createSecretMasker([this.accessToken]);
-    this.teamId = String(options.teamId || '').trim();
-    this.workerBaseUrl = String(
-      options.workerBaseUrl ||
-        'https://catalog-admin.postman-account2009.workers.dev'
-    ).replace(/\/+$/, '');
-  }
-
-  private async proxyRequest(
-    service: string,
-    method: string,
-    requestPath: string,
-    body?: unknown
-  ): Promise<Response> {
-    const url = 'https://bifrost-premium-https-v4.gw.postman.com/ws/proxy';
-    const headers: Record<string, string> = {
-      'Content-Type': 'application/json',
-      'x-access-token': this.accessToken
-    };
-    if (this.teamId) {
-      headers['x-entity-team-id'] = this.teamId;
-    }
-
-    return this.fetchImpl(url, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify({
-        service,
-        method,
-        path: requestPath,
-        ...(body !== undefined ? { body } : {})
-      })
-    });
-  }
-
-  async assignWorkspaceToGovernanceGroup(
-    workspaceId: string,
-    domain: string,
-    mappingJson: string
-  ): Promise<void> {
-    let mapping: Record<string, string>;
-    try {
-      mapping = JSON.parse(mappingJson || '{}');
-    } catch {
-      return;
-    }
-
-    const groupName = String(mapping[domain] || '').trim();
-    if (!groupName) {
-      return;
-    }
-
-    const listResponse = await this.fetchImpl(
-      'https://gateway.postman.com/configure/workspace-groups',
-      {
-        headers: {
-          'x-access-token': this.accessToken
-        }
-      }
-    );
-
-    if (!listResponse.ok) {
-      throw await HttpError.fromResponse(listResponse, {
-        method: 'GET',
-        requestHeaders: {
-          'x-access-token': this.accessToken
-        },
-        secretValues: [this.accessToken],
-        url: 'https://gateway.postman.com/configure/workspace-groups'
-      });
-    }
-
-    const groups = (await listResponse.json()) as {
-      data?: Array<{ id: string; name: string }>;
-    };
-    const group = groups.data?.find((entry) => entry.name === groupName);
-    if (!group?.id) {
-      return;
-    }
-
-    const patchResponse = await this.fetchImpl(
-      `https://gateway.postman.com/configure/workspace-groups/${group.id}`,
-      {
-        method: 'PATCH',
-        headers: {
-          'Content-Type': 'application/json',
-          'x-access-token': this.accessToken
-        },
-        body: JSON.stringify({
-          workspaces: [workspaceId]
-        })
-      }
-    );
-
-    if (!patchResponse.ok) {
-      throw await HttpError.fromResponse(patchResponse, {
-        method: 'PATCH',
-        requestHeaders: {
-          'Content-Type': 'application/json',
-          'x-access-token': this.accessToken
-        },
-        secretValues: [this.accessToken],
-        url: `https://gateway.postman.com/configure/workspace-groups/${group.id}`
-      });
-    }
-  }
-
-  async associateSystemEnvironments(
-    workspaceId: string,
-    associations: GovernanceAssociation[]
-  ): Promise<void> {
-    if (associations.length === 0) {
-      return;
-    }
-
-    const response = await this.fetchImpl(
-      `${this.workerBaseUrl}/api/internal/system-envs/associate`,
-      {
-        method: 'POST',
-        headers: {
-          Authorization: `Bearer ${this.accessToken}`,
-          'Content-Type': 'application/json'
-        },
-        body: JSON.stringify({
-          workspace_id: workspaceId,
-          associations: associations.map((entry) => ({
-            env_uid: entry.envUid,
-            system_env_id: entry.systemEnvId
-          }))
-        })
-      }
-    );
-
-    if (!response.ok) {
-      throw await HttpError.fromResponse(response, {
-        method: 'POST',
-        requestHeaders: {
-          Authorization: `Bearer ${this.accessToken}`,
-          'Content-Type': 'application/json'
-        },
-        secretValues: [this.accessToken],
-        url: `${this.workerBaseUrl}/api/internal/system-envs/associate`
-      });
-    }
-  }
-
-  async connectWorkspaceToRepository(
-    workspaceId: string,
-    repoUrl: string
-  ): Promise<void> {
-    const payload = {
-      service: 'workspaces',
-      method: 'POST',
-      path: `/workspaces/${workspaceId}/filesystem`,
-      body: {
-        path: '/',
-        repo: repoUrl,
-        versionControl: true
-      }
-    };
-
-    const response = await this.proxyRequest(
-      payload.service,
-      payload.method,
-      payload.path,
-      payload.body
-    );
-
-    if (response.ok) return;
-
-    if (response.status === 400) {
-      const body = await response.text();
-      // Handle both legacy ('invalidParamError' + 'already exists') and
-      // current ('projectAlreadyConnected') Bifrost duplicate-link errors.
-      const isDuplicate =
-        (body.includes('invalidParamError') && body.includes('already exists')) ||
-        body.includes('projectAlreadyConnected');
-      if (isDuplicate) {
-        const linkedUrl = await this.getWorkspaceGitRepoUrl(workspaceId);
-        if (normalizeGitRepoUrl(linkedUrl) === normalizeGitRepoUrl(repoUrl)) {
-          return;
-        }
-        throw new Error(
-          `Bifrost link already exists for workspace ${workspaceId}, but linked to a different repo`
-        );
-      }
-    }
-
-    throw await HttpError.fromResponse(response, {
-      method: 'POST',
-      requestHeaders: {
-        'Content-Type': 'application/json',
-        'x-access-token': this.accessToken,
-        ...(this.teamId ? { 'x-entity-team-id': this.teamId } : {})
-      },
-      secretValues: [this.accessToken],
-      url: 'https://bifrost-premium-https-v4.gw.postman.com/ws/proxy'
-    });
-  }
-
-  async linkCollectionsToSpecification(
-    specificationId: string,
-    collections: SpecificationCollectionLink[]
-  ): Promise<void> {
-    if (collections.length === 0) {
-      return;
-    }
-
-    const response = await this.proxyRequest(
-      'specification',
-      'put',
-      `/specifications/${specificationId}/collections`,
-      collections.map((collection) => ({
-        collectionId: collection.collectionId,
-        ...(collection.syncOptions ? { syncOptions: collection.syncOptions } : {})
-      }))
-    );
-
-    if (response.ok) {
-      return;
-    }
-
-    throw await HttpError.fromResponse(response, {
-      method: 'POST',
-      requestHeaders: {
-        'Content-Type': 'application/json',
-        'x-access-token': this.accessToken,
-        ...(this.teamId ? { 'x-entity-team-id': this.teamId } : {})
-      },
-      secretValues: [this.accessToken],
-      url: 'https://bifrost-premium-https-v4.gw.postman.com/ws/proxy'
-    });
-  }
-
-  async syncCollection(
-    specificationId: string,
-    collectionId: string
-  ): Promise<void> {
-    const response = await this.proxyRequest(
-      'specification',
-      'post',
-      `/specifications/${specificationId}/collections/${collectionId}/sync`
-    );
-
-    if (response.ok) {
-      return;
-    }
-
-    throw await HttpError.fromResponse(response, {
-      method: 'POST',
-      requestHeaders: {
-        'Content-Type': 'application/json',
-        'x-access-token': this.accessToken,
-        ...(this.teamId ? { 'x-entity-team-id': this.teamId } : {})
-      },
-      secretValues: [this.accessToken],
-      url: 'https://bifrost-premium-https-v4.gw.postman.com/ws/proxy'
-    });
-  }
-
-  private async getWorkspaceGitRepoUrl(workspaceId: string): Promise<string | null> {
-    const response = await this.proxyRequest(
-      'workspaces',
-      'GET',
-      `/workspaces/${workspaceId}/filesystem`
-    );
-
-    if (response.status === 404) return null;
-    if (!response.ok) return null;
-
-    const body = await response.text();
-    if (!body.trim()) return null;
-
-    try {
-      const data = JSON.parse(body);
-      const repo = data?.repo || data?.repository || data?.repoUrl;
-      return typeof repo === 'string' ? repo : null;
-    } catch {
-      return null;
-    }
-  }
-}
-
-export function createInternalIntegrationAdapter(
-  options: InternalIntegrationAdapterOptions
-): InternalIntegrationAdapter {
-  if (options.backend !== 'bifrost') {
-    const masker =
-      options.secretMasker ?? createSecretMasker([options.accessToken]);
-    throw new Error(
-      masker(`Unsupported integration backend: ${String(options.backend || '')}`)
-    );
-  }
-
-  return new BifrostInternalIntegrationAdapter(options);
-}