@hasna/connectors 1.3.43 → 1.3.45

package/connectors/stoplight-api-platform/CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+## Project Overview
+
+connect-stoplight-api-platform is a TypeScript connector for the Stoplight API
+(https://stoplight.io/api). Stoplight is an API design, documentation, and
+governance platform. This connector provides CLI and library access to
+workspaces, projects, branches, members, access groups, and documentation nodes
+(OpenAPI files, JSON Schema models, and Markdown articles).
+
+## Build & Run Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build for distribution
+bun run build
+
+# Type check
+bun run typecheck
+
+# Run tests
+bun test
+
+# Run specific commands
+bun run dev config show
+bun run dev workspace projects <workspaceId>
+bun run dev project get <projectId>
+bun run dev project toc <projectId>
+bun run dev node get <workspaceSlug> <projectSlug> --uri /reference/api.yaml
+```
+
+## Authentication
+
+Stoplight uses **workspace tokens** (read-only) or **personal access tokens**.
+The token is sent verbatim in the `Authorization` header — there is **no
+`Bearer` prefix** (the API rejects a `Bearer <token>` value as "Missing
+authorization"). Set it via `STOPLIGHT_API_TOKEN` or `config set-token`.
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (type: module)
+- Use async/await for all async operations
+- Minimal dependencies: commander, chalk only
+- Type annotations required everywhere
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts       # HTTP client (Authorization: <token>, no Bearer)
+│   ├── client.test.ts  # Client unit tests
+│   └── index.ts        # Stoplight API wrapper class
+├── cli/
+│   └── index.ts        # CLI commands
+├── types/
+│   └── index.ts        # Type definitions
+├── utils/
+│   ├── config.ts       # Multi-profile configuration
+│   └── output.ts       # CLI output formatting
+└── index.ts            # Library exports
+```
+
+## API Coverage
+
+### Workspaces
+- List projects in a workspace
+- List access groups in a workspace
+
+### Projects
+- Get a project
+- List branches
+- List members
+- Get the table of contents
+
+### Nodes
+- Read a node (OpenAPI / model / markdown) by URI
+- Export a bundled (dereferenced) node
+
+A generic `request()` escape hatch is available on the wrapper and client for
+endpoints not modeled here.

package/connectors/stoplight-api-platform/README.md

@@ -0,0 +1,86 @@
+# @hasna/connect-stoplight-api-platform
+
+A TypeScript connector (CLI + library) for the [Stoplight](https://stoplight.io)
+API design, documentation, and governance platform.
+
+## Features
+
+- Multi-profile configuration (switch between different tokens/accounts)
+- Workspace token / personal access token authentication
+- Workspaces, projects, branches, members, groups, and documentation nodes
+- Pretty, table, and JSON output formats
+- TypeScript with strict mode, minimal dependencies (commander, chalk)
+
+## Installation
+
+```bash
+bun install
+bun run build
+```
+
+## Authentication
+
+Create a **Workspace Token** (read-only) or a **Personal Access Token** in your
+Stoplight workspace settings. The token is sent verbatim in the `Authorization`
+header (no `Bearer` prefix).
+
+```bash
+# Save the token to the active profile
+connect-stoplight-api-platform config set-token <your-token>
+
+# Or use an environment variable
+export STOPLIGHT_API_TOKEN=<your-token>
+```
+
+To point at a self-hosted / on-prem instance:
+
+```bash
+connect-stoplight-api-platform config set-base-url https://stoplight.example.com/api
+# or STOPLIGHT_BASE_URL=...
+```
+
+## CLI Usage
+
+```bash
+# Workspaces
+connect-stoplight-api-platform workspace projects <workspaceId>
+connect-stoplight-api-platform workspace groups <workspaceId>
+
+# Projects
+connect-stoplight-api-platform project get <projectId>
+connect-stoplight-api-platform project branches <projectId>
+connect-stoplight-api-platform project members <projectId>
+connect-stoplight-api-platform project toc <projectId> --branch main
+
+# Nodes (OpenAPI / models / markdown)
+connect-stoplight-api-platform node get <workspaceSlug> <projectSlug> --uri /reference/api.yaml
+connect-stoplight-api-platform node export <workspaceSlug> <projectSlug> --uri /reference/api.yaml
+
+# Output format
+connect-stoplight-api-platform project get <projectId> --format json
+```
+
+## Library Usage
+
+```ts
+import { Stoplight } from '@hasna/connect-stoplight-api-platform';
+
+const stoplight = Stoplight.fromEnv(); // reads STOPLIGHT_API_TOKEN
+
+const projects = await stoplight.listWorkspaceProjects('workspaceId');
+const project = await stoplight.getProject('projectId');
+const toc = await stoplight.getTableOfContents('projectId');
+const spec = await stoplight.exportBundledNode('acme', 'my-api', '/reference/api.yaml');
+```
+
+## Development
+
+```bash
+bun run dev <command>   # run the CLI from source
+bun run typecheck       # tsc --noEmit
+bun test                # run unit tests
+```
+
+## License
+
+Apache-2.0

package/connectors/stoplight-api-platform/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@hasna/connect-stoplight-api-platform",
+  "version": "0.0.1",
+  "description": "Stoplight connector - Manage workspaces, projects, members, groups, and API documentation nodes",
+  "type": "module",
+  "bin": {
+    "connect-stoplight-api-platform": "./bin/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "dev": "bun run ./src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "stoplight",
+    "openapi",
+    "api-design",
+    "documentation",
+    "governance",
+    "developer",
+    "connector",
+    "cli",
+    "typescript",
+    "bun"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/open-connectors.git"
+  }
+}

package/connectors/stoplight-api-platform/src/api/client.test.ts

@@ -0,0 +1,121 @@
+import { describe, test, expect, afterEach } from 'bun:test';
+import { StoplightClient, DEFAULT_BASE_URL } from './client';
+import { StoplightApiError } from '../types';
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+function mockFetch(handler: (url: string, init: RequestInit) => Response) {
+  globalThis.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+    return Promise.resolve(handler(String(input), init ?? {}));
+  }) as typeof fetch;
+}
+
+describe('StoplightClient', () => {
+  test('requires a token', () => {
+    expect(() => new StoplightClient({ token: '' })).toThrow('API token is required');
+  });
+
+  test('defaults to the public base URL', () => {
+    expect(DEFAULT_BASE_URL).toBe('https://stoplight.io/api');
+  });
+
+  test('builds URLs with a leading slash and query params', async () => {
+    let seenUrl = '';
+    mockFetch((url) => {
+      seenUrl = url;
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    });
+
+    const client = new StoplightClient({ token: 'tok' });
+    await client.get('/v1/projects/abc/branches', { page: 2, page_size: undefined, empty: '' });
+
+    expect(seenUrl).toBe('https://stoplight.io/api/v1/projects/abc/branches?page=2');
+  });
+
+  test('sends the token in the Authorization header WITHOUT a Bearer prefix', async () => {
+    const seen: { auth: string | null } = { auth: null };
+    mockFetch((_url, init) => {
+      const headers = new Headers(init.headers as HeadersInit);
+      seen.auth = headers.get('Authorization');
+      return new Response(JSON.stringify({}), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    });
+
+    const client = new StoplightClient({ token: 'my-secret-token' });
+    await client.get('/v1/projects/abc');
+
+    expect(seen.auth).toBe('my-secret-token');
+    expect(seen.auth).not.toContain('Bearer');
+  });
+
+  test('honors a custom base URL and strips a trailing slash', async () => {
+    let seenUrl = '';
+    mockFetch((url) => {
+      seenUrl = url;
+      return new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } });
+    });
+
+    const client = new StoplightClient({ token: 'tok', baseUrl: 'https://stoplight.example.com/api/' });
+    await client.get('/v1/projects/abc');
+
+    expect(seenUrl).toBe('https://stoplight.example.com/api/v1/projects/abc');
+  });
+
+  test('maps non-ok JSON responses to StoplightApiError', async () => {
+    mockFetch(() =>
+      new Response(JSON.stringify({ message: 'Unauthorized', code: 401, type: 'INVALID_TOKEN' }), {
+        status: 401,
+        headers: { 'content-type': 'application/json' },
+      }),
+    );
+
+    const client = new StoplightClient({ token: 'tok' });
+
+    let caught: unknown;
+    try {
+      await client.get('/v1/projects/abc/members');
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(StoplightApiError);
+    const apiErr = caught as StoplightApiError;
+    expect(apiErr.statusCode).toBe(401);
+    expect(apiErr.code).toBe(401);
+    expect(apiErr.type).toBe('INVALID_TOKEN');
+    expect(apiErr.message).toBe('Unauthorized');
+  });
+
+  test('handles RFC7807 problem+json error bodies', async () => {
+    mockFetch(() =>
+      new Response(JSON.stringify({ title: 'Missing authorization.', status: 401 }), {
+        status: 401,
+        headers: { 'content-type': 'application/problem+json' },
+      }),
+    );
+
+    const client = new StoplightClient({ token: 'tok' });
+    await expect(client.get('/v1/projects/abc')).rejects.toThrow('Missing authorization.');
+  });
+
+  test('returns an empty object for 204 No Content', async () => {
+    mockFetch(() => new Response(null, { status: 204 }));
+    const client = new StoplightClient({ token: 'tok' });
+    const result = await client.delete('/v1/projects/abc');
+    expect(result).toEqual({});
+  });
+
+  test('previews long tokens without exposing them', () => {
+    const client = new StoplightClient({ token: 'abcdefghijklmnop' });
+    expect(client.getTokenPreview()).toBe('abcdef...mnop');
+  });
+});

package/connectors/stoplight-api-platform/src/api/client.ts

@@ -0,0 +1,134 @@
+import type { StoplightConfig, StoplightErrorResponse } from '../types';
+import { StoplightApiError } from '../types';
+
+export const DEFAULT_BASE_URL = 'https://stoplight.io/api';
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown> | unknown[] | string;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Low-level HTTP client for the Stoplight API.
+ *
+ * Authentication note: Stoplight workspace tokens and personal access tokens
+ * are sent verbatim in the `Authorization` header WITHOUT a `Bearer` prefix.
+ * (The API rejects a `Bearer <token>` value as "Missing authorization.")
+ */
+export class StoplightClient {
+  private readonly token: string;
+  private readonly baseUrl: string;
+
+  constructor(config: StoplightConfig) {
+    if (!config.token) {
+      throw new Error('API token is required');
+    }
+    this.token = config.token;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const url = new URL(`${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {} } = options;
+
+    const url = this.buildUrl(path, params);
+
+    const requestHeaders: Record<string, string> = {
+      // Stoplight tokens are passed raw (no "Bearer" prefix).
+      'Authorization': this.token,
+      'Accept': 'application/json',
+      ...headers,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      requestHeaders['Content-Type'] = 'application/json';
+    }
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    // Handle 204 No Content
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    // Parse response
+    let data: unknown;
+    const contentType = response.headers.get('content-type') || '';
+
+    if (contentType.includes('application/json') || contentType.includes('application/problem+json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      }
+    } else {
+      data = await response.text();
+    }
+
+    if (!response.ok) {
+      const err = (data && typeof data === 'object' ? data : {}) as StoplightErrorResponse;
+      const message =
+        err.message ||
+        err.title ||
+        (typeof data === 'string' && data ? data : response.statusText) ||
+        `Request failed with status ${response.status}`;
+      throw new StoplightApiError(message, response.status, err.code, err.type, err.data);
+    }
+
+    return data as T;
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown> | unknown[] | string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body, params });
+  }
+
+  async put<T>(path: string, body?: Record<string, unknown> | unknown[] | string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PUT', body, params });
+  }
+
+  async patch<T>(path: string, body?: Record<string, unknown> | unknown[] | string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PATCH', body, params });
+  }
+
+  async delete<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE', params });
+  }
+
+  getTokenPreview(): string {
+    if (this.token.length > 10) {
+      return `${this.token.substring(0, 6)}...${this.token.substring(this.token.length - 4)}`;
+    }
+    return '***';
+  }
+}

package/connectors/stoplight-api-platform/src/api/index.ts

@@ -0,0 +1,154 @@
+import type {
+  StoplightConfig,
+  Project,
+  Branch,
+  Member,
+  Group,
+  Node,
+  TableOfContents,
+  GetNodeParams,
+  PaginationParams,
+} from '../types';
+import { StoplightClient, DEFAULT_BASE_URL } from './client';
+
+/**
+ * High-level wrapper around the Stoplight API.
+ *
+ * Endpoint coverage mirrors the public Stoplight API surface:
+ *   - workspaces/{id}/projects, workspaces/{id}/groups
+ *   - projects/{id}, projects/{id}/branches, projects/{id}/members,
+ *     projects/{id}/table-of-contents
+ *   - projects/{workspace}/{project}/nodes  (OpenAPI/Markdown export)
+ *
+ * `request()` is exposed as an escape hatch for endpoints not modeled here.
+ */
+export class Stoplight {
+  private readonly client: StoplightClient;
+
+  constructor(config: StoplightConfig) {
+    this.client = new StoplightClient(config);
+  }
+
+  static fromEnv(): Stoplight {
+    const token = process.env.STOPLIGHT_API_TOKEN;
+    if (!token) {
+      throw new Error('STOPLIGHT_API_TOKEN environment variable is required');
+    }
+    const baseUrl = process.env.STOPLIGHT_BASE_URL || DEFAULT_BASE_URL;
+    return new Stoplight({ token, baseUrl });
+  }
+
+  getTokenPreview(): string {
+    return this.client.getTokenPreview();
+  }
+
+  getClient(): StoplightClient {
+    return this.client;
+  }
+
+  private static pageParams(params?: PaginationParams): Record<string, string | number | undefined> {
+    if (!params) return {};
+    return {
+      page: params.page,
+      page_size: params.pageSize,
+    };
+  }
+
+  // ============================================
+  // Workspace Methods
+  // ============================================
+
+  /** List the projects that belong to a workspace. */
+  async listWorkspaceProjects(workspaceId: string, params?: PaginationParams): Promise<Project[]> {
+    return this.client.get<Project[]>(
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/projects`,
+      Stoplight.pageParams(params),
+    );
+  }
+
+  /** List the access groups defined in a workspace. */
+  async listWorkspaceGroups(workspaceId: string, params?: PaginationParams): Promise<Group[]> {
+    return this.client.get<Group[]>(
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/groups`,
+      Stoplight.pageParams(params),
+    );
+  }
+
+  // ============================================
+  // Project Methods
+  // ============================================
+
+  /** Get a single project by its id. */
+  async getProject(projectId: string): Promise<Project> {
+    return this.client.get<Project>(`/v1/projects/${encodeURIComponent(projectId)}`);
+  }
+
+  /** List the branches available in a project. */
+  async listProjectBranches(projectId: string, params?: PaginationParams): Promise<Branch[]> {
+    return this.client.get<Branch[]>(
+      `/v1/projects/${encodeURIComponent(projectId)}/branches`,
+      Stoplight.pageParams(params),
+    );
+  }
+
+  /** List the members (and their roles) of a project. */
+  async listProjectMembers(projectId: string, params?: PaginationParams): Promise<Member[]> {
+    return this.client.get<Member[]>(
+      `/v1/projects/${encodeURIComponent(projectId)}/members`,
+      Stoplight.pageParams(params),
+    );
+  }
+
+  /** Get the rendered table of contents for a project. */
+  async getTableOfContents(projectId: string, branch?: string): Promise<TableOfContents> {
+    return this.client.get<TableOfContents>(
+      `/v1/projects/${encodeURIComponent(projectId)}/table-of-contents`,
+      branch ? { branch } : undefined,
+    );
+  }
+
+  // ============================================
+  // Node / Spec Export Methods
+  // ============================================
+
+  /**
+   * Read a single node (OpenAPI file, JSON Schema model, or Markdown article)
+   * from a project. Uses the slug-addressed nodes endpoint:
+   *   GET /v1/projects/{workspaceSlug}/{projectSlug}/nodes?uri=...
+   */
+  async getNode(workspaceSlug: string, projectSlug: string, params: GetNodeParams): Promise<Node> {
+    const query: Record<string, string | number | boolean | undefined> = {
+      uri: params.uri,
+      branch: params.branch,
+    };
+    if (params.deref !== undefined) {
+      query.deref = params.deref === true ? 'bundle' : params.deref === false ? undefined : params.deref;
+    }
+    return this.client.get<Node>(
+      `/v1/projects/${encodeURIComponent(workspaceSlug)}/${encodeURIComponent(projectSlug)}/nodes`,
+      query,
+    );
+  }
+
+  /**
+   * Convenience helper: fetch a bundled (fully dereferenced) OpenAPI or JSON
+   * Schema document for the given node uri.
+   */
+  async exportBundledNode(workspaceSlug: string, projectSlug: string, uri: string, branch?: string): Promise<Node> {
+    return this.getNode(workspaceSlug, projectSlug, { uri, branch, deref: 'bundle' });
+  }
+
+  // ============================================
+  // Escape Hatch
+  // ============================================
+
+  /** Perform an arbitrary request against the Stoplight API. */
+  async request<T>(
+    path: string,
+    options?: { method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'; params?: Record<string, string | number | boolean | undefined>; body?: Record<string, unknown> | unknown[] | string },
+  ): Promise<T> {
+    return this.client.request<T>(path, options);
+  }
+}
+
+export { StoplightClient, DEFAULT_BASE_URL } from './client';