@hasna/connectors 1.3.45 → 1.4.0

package/connectors/wandb/CLAUDE.md

@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working with the Weights & Biases connector.
+
+## Project Overview
+
+connect-wandb is a TypeScript CLI and library for the Weights & Biases GraphQL API (`https://api.wandb.ai/graphql`). It provides viewer lookup, project run listing, and ad-hoc GraphQL queries with multi-profile support.
+
+## Build & Run Commands
+
+```bash
+bun install
+bun run dev
+bun run build
+bun run typecheck
+bun test
+```
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts     # GraphQL client with Bearer auth
+│   ├── viewer.ts     # Viewer query
+│   ├── projects.ts   # Project runs query
+│   ├── graphql.ts    # Ad-hoc queries
+│   └── index.ts      # Wandb facade
+├── cli/index.ts
+├── types/index.ts
+├── utils/config.ts
+└── utils/output.ts
+```
+
+## Authentication
+
+Bearer Token authentication. Credentials via:
+- `WANDB_API_KEY` environment variable
+- Profile config: `wandb config set-key <key>`
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `WANDB_API_KEY` | W&B API key |
+| `WANDB_BASE_URL` | Custom GraphQL endpoint (default: `https://api.wandb.ai/graphql`) |
+
+## Multi-Profile Configuration
+
+Configuration stored in `~/.hasna/connectors/wandb/`:
+
+```
+~/.hasna/connectors/wandb/
+├── current_profile
+└── profiles/
+    └── default.json
+```
+
+## GraphQL Endpoint
+
+- Base URL: `https://api.wandb.ai/graphql`
+- Auth: `Authorization: Bearer <api_key>`
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling

package/connectors/wandb/README.md

@@ -0,0 +1,65 @@
+# connect-wandb
+
+Weights & Biases GraphQL API connector — experiment tracking with multi-profile support.
+
+## Installation
+
+```bash
+bun install -g @hasna/connect-wandb
+```
+
+## Quick Start
+
+```bash
+# Set your API key
+wandb config set-key YOUR_API_KEY
+
+# Or use environment variable
+export WANDB_API_KEY=YOUR_API_KEY
+
+# Verify authentication
+wandb viewer
+```
+
+## CLI Commands
+
+```bash
+wandb config set-key <key>              # Set API key
+wandb config show                       # Show config
+wandb viewer                            # Get authenticated user
+wandb project-runs --entity <e> --project <p>  # List project runs
+wandb graphql --query '<query>' [--variables '<json>']
+wandb raw --body '<json>'               # Raw GraphQL POST body
+wandb profile list                      # List profiles
+wandb profile use <name>                # Switch profile
+```
+
+## Profile Management
+
+```bash
+wandb profile create work --api-key xxx --use
+wandb profile create personal --api-key yyy
+wandb -p personal viewer
+```
+
+## Library Usage
+
+```typescript
+import { Wandb } from '@hasna/connect-wandb';
+
+const client = new Wandb({ apiKey: process.env.WANDB_API_KEY! });
+
+const { viewer } = await client.viewer.get();
+const runs = await client.projects.projectRuns({ entity: 'team', project: 'demo' });
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `WANDB_API_KEY` | API key (overrides profile) |
+| `WANDB_BASE_URL` | Override GraphQL base URL |
+
+## License
+
+Apache-2.0

package/connectors/wandb/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hasna/connect-wandb",
+  "version": "0.1.0",
+  "description": "Weights & Biases GraphQL API connector - experiment tracking with multi-profile support",
+  "type": "module",
+  "bin": {
+    "wandb": "./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 src/api/client.test.ts"
+  },
+  "keywords": [
+    "wandb",
+    "weights-and-biases",
+    "ml",
+    "experiments",
+    "graphql",
+    "connector",
+    "cli",
+    "typescript",
+    "bun",
+    "hasna"
+  ],
+  "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/connectors.git"
+  }
+}

package/connectors/wandb/src/api/client.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { Wandb, WandbClient } from './index';
+import { WandbApiError } from '../types';
+
+const realFetch = globalThis.fetch;
+
+interface RecordedRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body?: string;
+}
+
+function installFetch(handler: (recorded: RecordedRequest) => unknown) {
+  const recorded: RecordedRequest[] = [];
+  globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = typeof input === 'string' ? input : input.toString();
+    const headers: Record<string, string> = {};
+    if (init?.headers) {
+      const h = init.headers as Record<string, string>;
+      Object.assign(headers, h);
+    }
+    const body = typeof init?.body === 'string' ? init.body : undefined;
+    const entry = { url, method: init?.method ?? 'GET', headers, body };
+    recorded.push(entry);
+    const json = handler(entry);
+    return {
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      async json() {
+        return json ?? {};
+      },
+    } as Response;
+  }) as typeof fetch;
+  return recorded;
+}
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe('WandbClient', () => {
+  test('requires API key', () => {
+    expect(() => new WandbClient({ apiKey: '' })).toThrow('W&B API key is required');
+  });
+
+  test('sends Bearer authorization header', async () => {
+    const recorded = installFetch(() => ({
+      data: { viewer: { id: '1', username: 'testuser' } },
+    }));
+    const client = new WandbClient({ apiKey: 'test-key-123' });
+    await client.query('query Viewer { viewer { id username } }');
+    expect(recorded[0].url).toBe('https://api.wandb.ai/graphql');
+    expect(recorded[0].method).toBe('POST');
+    expect(recorded[0].headers['Authorization']).toBe('Bearer test-key-123');
+  });
+
+  test('viewer query sends expected GraphQL body', async () => {
+    const recorded = installFetch(() => ({
+      data: { viewer: { id: 'v1', username: 'alice', name: 'Alice' } },
+    }));
+    const wandb = new Wandb({ apiKey: 'key' });
+    const result = await wandb.viewer.get();
+    expect(result.viewer.username).toBe('alice');
+    const body = JSON.parse(recorded[0].body!);
+    expect(body.query).toContain('viewer');
+    expect(body.query).toContain('username');
+  });
+
+  test('projectRuns passes entity and project variables', async () => {
+    const recorded = installFetch(() => ({
+      data: {
+        project: {
+          runs: {
+            edges: [{ node: { id: 'r1', name: 'run-1', displayName: 'Run 1', state: 'finished' } }],
+          },
+        },
+      },
+    }));
+    const wandb = new Wandb({ apiKey: 'key' });
+    const result = await wandb.projects.projectRuns({ entity: 'team', project: 'demo' });
+    expect(result.project?.runs.edges[0].node.name).toBe('run-1');
+    const body = JSON.parse(recorded[0].body!);
+    expect(body.variables).toEqual({ entity: 'team', project: 'demo', first: 50 });
+    expect(body.query).toContain('ProjectRuns');
+  });
+
+  test('throws WandbApiError on GraphQL errors', async () => {
+    installFetch(() => ({
+      errors: [{ message: 'Not authorized', extensions: { code: 'UNAUTHORIZED' } }],
+    }));
+    const client = new WandbClient({ apiKey: 'bad-key' });
+    await expect(client.query('query { viewer { id } }')).rejects.toThrow('Not authorized');
+  });
+
+  test('throws WandbApiError on HTTP errors', async () => {
+    globalThis.fetch = (async () => ({
+      ok: false,
+      status: 401,
+      statusText: 'Unauthorized',
+      async json() {
+        return {};
+      },
+    })) as unknown as typeof fetch;
+    const client = new WandbClient({ apiKey: 'key' });
+    await expect(client.query('query { viewer { id } }')).rejects.toThrow(WandbApiError);
+  });
+
+  test('custom base URL is respected', async () => {
+    const recorded = installFetch(() => ({ data: { viewer: { id: '1' } } }));
+    const client = new WandbClient({ apiKey: 'key', baseUrl: 'https://custom.example/graphql' });
+    await client.query('query { viewer { id } }');
+    expect(recorded[0].url).toBe('https://custom.example/graphql');
+  });
+});

package/connectors/wandb/src/api/client.ts

@@ -0,0 +1,83 @@
+import type { WandbConfig, GraphQLResponse } from '../types';
+import { WandbApiError } from '../types';
+
+export const DEFAULT_BASE_URL = 'https://api.wandb.ai/graphql';
+
+export class WandbClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+
+  constructor(config: WandbConfig) {
+    if (!config.apiKey) {
+      throw new Error('W&B API key is required');
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  }
+
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  /**
+   * Execute a GraphQL query or mutation against the W&B API.
+   */
+  async query<T>(query: string, variables?: Record<string, unknown>): Promise<T> {
+    const response = await fetch(this.baseUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({ query, variables }),
+    });
+
+    if (!response.ok) {
+      throw new WandbApiError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        'http_error',
+        response.status
+      );
+    }
+
+    const result = await response.json() as GraphQLResponse<T>;
+
+    if (result.errors && result.errors.length > 0) {
+      const error = result.errors[0];
+      throw new WandbApiError(
+        error.message,
+        (error.extensions?.code as string) || 'graphql_error'
+      );
+    }
+
+    if (!result.data) {
+      throw new WandbApiError('No data returned', 'no_data');
+    }
+
+    return result.data;
+  }
+
+  /**
+   * Send a raw JSON body to the GraphQL endpoint (for advanced use).
+   */
+  async raw<T>(body: Record<string, unknown>): Promise<T> {
+    const response = await fetch(this.baseUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      throw new WandbApiError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        'http_error',
+        response.status
+      );
+    }
+
+    return await response.json() as T;
+  }
+}

package/connectors/wandb/src/api/graphql.ts

@@ -0,0 +1,9 @@
+import type { WandbClient } from './client';
+
+export class GraphqlApi {
+  constructor(private readonly client: WandbClient) {}
+
+  async execute<T>(query: string, variables?: Record<string, unknown>): Promise<T> {
+    return this.client.query<T>(query, variables);
+  }
+}

package/connectors/wandb/src/api/index.ts

@@ -0,0 +1,36 @@
+import type { WandbConfig } from '../types';
+import { WandbClient } from './client';
+import { ViewerApi } from './viewer';
+import { ProjectsApi } from './projects';
+import { GraphqlApi } from './graphql';
+
+export { WandbClient, DEFAULT_BASE_URL } from './client';
+export { ViewerApi } from './viewer';
+export { ProjectsApi } from './projects';
+export { GraphqlApi } from './graphql';
+
+/**
+ * Main Weights & Biases GraphQL API class.
+ */
+export class Wandb {
+  private readonly client: WandbClient;
+
+  public readonly viewer: ViewerApi;
+  public readonly projects: ProjectsApi;
+  public readonly graphql: GraphqlApi;
+
+  constructor(config: WandbConfig) {
+    this.client = new WandbClient(config);
+    this.viewer = new ViewerApi(this.client);
+    this.projects = new ProjectsApi(this.client);
+    this.graphql = new GraphqlApi(this.client);
+  }
+
+  async test() {
+    return this.viewer.get();
+  }
+
+  getClient(): WandbClient {
+    return this.client;
+  }
+}

package/connectors/wandb/src/api/projects.ts

@@ -0,0 +1,36 @@
+import type { WandbClient } from './client';
+import type { ProjectRunsOptions, ProjectRunsResponse } from '../types';
+
+const PROJECT_RUNS_QUERY = `query ProjectRuns($entity: String!, $project: String!, $first: Int, $order: String, $filters: JSONString) {
+  project(name: $project, entityName: $entity) {
+    runs(first: $first, order: $order, filters: $filters) {
+      edges {
+        node {
+          id
+          name
+          displayName
+          state
+          createdAt
+          summaryMetrics
+        }
+      }
+      pageInfo {
+        endCursor
+        hasNextPage
+      }
+    }
+  }
+}`;
+
+export class ProjectsApi {
+  constructor(private readonly client: WandbClient) {}
+
+  async projectRuns(options: ProjectRunsOptions) {
+    const { entity, project, first = 50, order, filters } = options;
+    const variables: Record<string, unknown> = { entity, project, first };
+    if (order) variables.order = order;
+    if (filters) variables.filters = JSON.stringify(filters);
+
+    return this.client.query<ProjectRunsResponse>(PROJECT_RUNS_QUERY, variables);
+  }
+}

package/connectors/wandb/src/api/viewer.ts

@@ -0,0 +1,20 @@
+import type { WandbClient } from './client';
+import type { ViewerResponse } from '../types';
+
+const VIEWER_QUERY = `query Viewer {
+  viewer {
+    id
+    username
+    name
+    email
+    entity
+  }
+}`;
+
+export class ViewerApi {
+  constructor(private readonly client: WandbClient) {}
+
+  async get() {
+    return this.client.query<ViewerResponse>(VIEWER_QUERY);
+  }
+}