@hasna/connectors 1.3.43 → 1.3.45

package/connectors/usps/src/utils/storage.ts

@@ -0,0 +1,198 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { getConfigDir } from './config';
+
+// ============================================
+// Generic Data Storage Utility
+// ============================================
+
+/**
+ * Base interface for storable entities
+ * All stored entities should have an id field
+ */
+export interface Storable {
+  id: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/**
+ * Get the storage directory for an entity type
+ */
+function getStorageDir(entityType: string): string {
+  const dir = join(getConfigDir(), 'data', entityType);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+/**
+ * Convert an ID to a safe filename
+ */
+function idToFilename(id: string): string {
+  return id.toLowerCase().replace(/[^a-z0-9]/g, '_') + '.json';
+}
+
+/**
+ * Get the file path for an entity
+ */
+function getEntityPath(entityType: string, id: string): string {
+  return join(getStorageDir(entityType), idToFilename(id));
+}
+
+/**
+ * Save an entity to storage
+ */
+export function saveEntity<T extends Storable>(entityType: string, entity: T): void {
+  const filepath = getEntityPath(entityType, entity.id);
+  const now = new Date().toISOString();
+
+  const existing = getEntity<T>(entityType, entity.id);
+
+  const data: T = {
+    ...entity,
+    createdAt: existing?.createdAt || now,
+    updatedAt: now,
+  };
+
+  writeFileSync(filepath, JSON.stringify(data, null, 2));
+}
+
+/**
+ * Get an entity by ID
+ */
+export function getEntity<T extends Storable>(entityType: string, id: string): T | null {
+  const filepath = getEntityPath(entityType, id);
+
+  if (!existsSync(filepath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(filepath, 'utf-8');
+    return JSON.parse(content) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if an entity exists
+ */
+export function entityExists(entityType: string, id: string): boolean {
+  return existsSync(getEntityPath(entityType, id));
+}
+
+/**
+ * Get all entities of a type
+ */
+export function getAllEntities<T extends Storable>(entityType: string): T[] {
+  const storageDir = getStorageDir(entityType);
+  const files = readdirSync(storageDir).filter(f => f.endsWith('.json'));
+
+  const entities: T[] = [];
+  for (const file of files) {
+    try {
+      const content = readFileSync(join(storageDir, file), 'utf-8');
+      entities.push(JSON.parse(content) as T);
+    } catch {
+      // Skip invalid files
+    }
+  }
+
+  return entities.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Delete an entity
+ */
+export function deleteEntity(entityType: string, id: string): boolean {
+  const filepath = getEntityPath(entityType, id);
+
+  if (existsSync(filepath)) {
+    unlinkSync(filepath);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Search entities by a predicate function
+ */
+export function searchEntities<T extends Storable>(
+  entityType: string,
+  predicate: (entity: T) => boolean
+): T[] {
+  const all = getAllEntities<T>(entityType);
+  return all.filter(predicate);
+}
+
+/**
+ * Search entities by text match across all string fields
+ */
+export function searchEntitiesByText<T extends Storable>(
+  entityType: string,
+  query: string,
+  fields?: (keyof T)[]
+): T[] {
+  const all = getAllEntities<T>(entityType);
+  const q = query.toLowerCase();
+
+  return all.filter(entity => {
+    const searchFields = fields || (Object.keys(entity) as (keyof T)[]);
+    return searchFields.some(field => {
+      const value = entity[field];
+      if (typeof value === 'string') {
+        return value.toLowerCase().includes(q);
+      }
+      return false;
+    });
+  });
+}
+
+/**
+ * Count entities of a type
+ */
+export function countEntities(entityType: string): number {
+  const storageDir = getStorageDir(entityType);
+  if (!existsSync(storageDir)) {
+    return 0;
+  }
+  return readdirSync(storageDir).filter(f => f.endsWith('.json')).length;
+}
+
+/**
+ * Clear all entities of a type
+ */
+export function clearEntities(entityType: string): number {
+  const storageDir = getStorageDir(entityType);
+  if (!existsSync(storageDir)) {
+    return 0;
+  }
+
+  const files = readdirSync(storageDir).filter(f => f.endsWith('.json'));
+  for (const file of files) {
+    unlinkSync(join(storageDir, file));
+  }
+
+  return files.length;
+}
+
+/**
+ * Create a typed storage helper for a specific entity type
+ * This provides a cleaner API for working with a single entity type
+ */
+export function createStorage<T extends Storable>(entityType: string) {
+  return {
+    save: (entity: T) => saveEntity<T>(entityType, entity),
+    get: (id: string) => getEntity<T>(entityType, id),
+    exists: (id: string) => entityExists(entityType, id),
+    getAll: () => getAllEntities<T>(entityType),
+    delete: (id: string) => deleteEntity(entityType, id),
+    search: (predicate: (entity: T) => boolean) => searchEntities<T>(entityType, predicate),
+    searchByText: (query: string, fields?: (keyof T)[]) => searchEntitiesByText<T>(entityType, query, fields),
+    count: () => countEntities(entityType),
+    clear: () => clearEntities(entityType),
+  };
+}

package/connectors/usps/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "bin"]
+}

package/connectors/v0/.env.example

@@ -0,0 +1,5 @@
+# v0 Platform API key from https://v0.dev/chat/settings/keys
+V0_API_KEY=your-api-key-here
+
+# Optional: override API base URL (default https://api.v0.dev/v1)
+# V0_BASE_URL=https://api.v0.dev/v1

package/connectors/v0/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with the v0 Platform API connector.
+
+## Project Overview
+
+`@hasna/connect-v0` is a TypeScript CLI and library for the [v0 Platform API](https://v0.app/docs/api/platform/overview).
+
+- **Authentication**: Bearer token (`V0_API_KEY` or profile `apiKey`)
+- **Base URL**: `https://api.v0.dev/v1` (override via `V0_BASE_URL` or profile `baseUrl`)
+
+## Build & Run Commands
+
+```bash
+bun install
+bun run dev
+bun run build
+bun run typecheck
+bun test
+```
+
+## API Surface
+
+| Resource | Endpoints |
+|----------|-----------|
+| User | `GET /user`, `GET /user/scopes` |
+| Projects | `GET/POST /projects`, `GET/PUT/DELETE /projects/:id` |
+| Chats | `GET/POST /chats`, `GET/DELETE /chats/:id` |
+| Messages | `GET/POST /chats/:id/messages`, `GET /chats/:id/messages/:messageId` |
+| Deployments | `GET/POST /deployments`, `GET /deployments/:id` |
+| Completions | `POST /chat/completions` |
+
+## CLI Examples
+
+```bash
+connect-v0 config set-key <api-key>
+connect-v0 user get
+connect-v0 projects list
+connect-v0 chats create -m "Create a todo app"
+connect-v0 chat-completions -m "Hello" --model v0-1.5-md
+connect-v0 deployments create --chat-id <id> --version-id <id>
+```
+
+## Configuration
+
+Profiles stored in `~/.hasna/connectors/connect-v0/profiles/`.
+
+| Variable | Description |
+|----------|-------------|
+| `V0_API_KEY` | API key from v0.dev/chat/settings/keys |
+| `V0_BASE_URL` | Optional API base URL override |
+
+## Auth Type
+
+Bearer token — detected by dashboard auth from this CLAUDE.md.

package/connectors/v0/README.md

@@ -0,0 +1,63 @@
+# @hasna/connect-v0
+
+TypeScript connector for the [v0 Platform API](https://v0.app/docs/api/platform/overview) — projects, AI chats, deployments, and model completions.
+
+## Features
+
+- Bearer token authentication
+- Multi-profile configuration
+- Full Platform API coverage (user, projects, chats, messages, deployments, completions)
+- Library exports and CLI (`connect-v0`)
+- JSON and pretty output formats
+
+## Quick Start
+
+```bash
+cd connectors/v0
+bun install
+export V0_API_KEY=your-api-key-here
+bun run dev user get
+```
+
+Or configure a profile:
+
+```bash
+bun run dev config set-key your-api-key-here
+bun run dev projects list
+```
+
+## CLI Commands
+
+```bash
+connect-v0 profile list|use|create|delete|show
+connect-v0 config set-key|show|clear
+connect-v0 user get|scopes
+connect-v0 projects list|create|get|update|delete
+connect-v0 chats list|create|init|get|delete
+connect-v0 messages list|get|send
+connect-v0 deployments list|create|get
+connect-v0 chat-completions
+connect-v0 stream-chat-completions
+connect-v0 raw-request
+```
+
+## Library Usage
+
+```typescript
+import { V0 } from '@hasna/connect-v0';
+
+const v0 = V0.fromEnv();
+const user = await v0.getUser();
+const project = await v0.createProject({ name: 'My App' });
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `V0_API_KEY` | API key from https://v0.dev/chat/settings/keys |
+| `V0_BASE_URL` | Optional base URL (default `https://api.v0.dev/v1`) |
+
+## License
+
+Apache-2.0

package/connectors/v0/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@hasna/connect-v0",
+  "version": "0.0.1",
+  "description": "v0 Platform API connector CLI - projects, chats, deployments, and model completions",
+  "type": "module",
+  "bin": {
+    "connect-v0": "./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",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "v0",
+    "vercel",
+    "ai",
+    "codegen",
+    "platform",
+    "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/connectors.git"
+  }
+}

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

@@ -0,0 +1,123 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { V0Client, DEFAULT_BASE_URL } from './client';
+
+const realFetch = globalThis.fetch;
+
+interface RecordedRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body?: string;
+}
+
+function headerValue(headers: Record<string, string>, name: string): string | undefined {
+  const key = Object.keys(headers).find(k => k.toLowerCase() === name.toLowerCase());
+  return key ? headers[key] : undefined;
+}
+
+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> = {};
+    new Headers(init?.headers).forEach((value, key) => {
+      headers[key] = value;
+    });
+    const entry: RecordedRequest = {
+      url,
+      method: init?.method ?? 'GET',
+      headers,
+      body: typeof init?.body === 'string' ? init.body : undefined,
+    };
+    recorded.push(entry);
+    const json = handler(entry);
+    return {
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      headers: new Headers({ 'content-type': 'application/json' }),
+      async text() {
+        return JSON.stringify(json ?? {});
+      },
+    } as Response;
+  }) as typeof fetch;
+  return recorded;
+}
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe('V0Client', () => {
+  test('uses default base URL', () => {
+    const client = new V0Client({ apiKey: 'test-key' });
+    expect(client.getBaseUrl()).toBe(DEFAULT_BASE_URL);
+  });
+
+  test('allows custom base URL override', () => {
+    const client = new V0Client({ apiKey: 'test-key', baseUrl: 'https://custom.example/v1/' });
+    expect(client.getBaseUrl()).toBe('https://custom.example/v1');
+  });
+
+  test('requires API key', () => {
+    expect(() => new V0Client({ apiKey: '' })).toThrow('API key is required');
+  });
+
+  test('GET /user sends Bearer auth header', async () => {
+    const recorded = installFetch((req) => {
+      expect(req.url).toBe('https://api.v0.dev/v1/user');
+      expect(req.method).toBe('GET');
+      expect(headerValue(req.headers, 'Authorization')).toBe('Bearer v0_test_key');
+      return { id: 'user_1', email: 'dev@example.com' };
+    });
+    const client = new V0Client({ apiKey: 'v0_test_key' });
+    const user = await client.get<{ id: string }>('/user');
+    expect(user.id).toBe('user_1');
+    expect(recorded).toHaveLength(1);
+  });
+
+  test('POST /projects sends JSON body', async () => {
+    const recorded = installFetch((req) => {
+      expect(req.url).toBe('https://api.v0.dev/v1/projects');
+      expect(req.method).toBe('POST');
+      expect(headerValue(req.headers, 'Authorization')).toBe('Bearer v0_test_key');
+      expect(headerValue(req.headers, 'Content-Type')).toBe('application/json');
+      expect(JSON.parse(req.body!)).toEqual({ name: 'My App', description: 'Demo' });
+      return { id: 'proj_1', name: 'My App' };
+    });
+    const client = new V0Client({ apiKey: 'v0_test_key' });
+    const project = await client.post<{ id: string }>('/projects', { name: 'My App', description: 'Demo' });
+    expect(project.id).toBe('proj_1');
+    expect(recorded).toHaveLength(1);
+  });
+
+  test('POST /chat/completions sends messages payload', async () => {
+    installFetch((req) => {
+      expect(req.url).toBe('https://api.v0.dev/v1/chat/completions');
+      expect(req.method).toBe('POST');
+      const body = JSON.parse(req.body!);
+      expect(body.messages).toEqual([{ role: 'user', content: 'Hello' }]);
+      expect(body.stream).toBeUndefined();
+      return { choices: [{ message: { role: 'assistant', content: 'Hi' } }] };
+    });
+    const client = new V0Client({ apiKey: 'v0_test_key' });
+    const result = await client.post('/chat/completions', {
+      messages: [{ role: 'user', content: 'Hello' }],
+    });
+    expect((result as { choices: unknown[] }).choices).toHaveLength(1);
+  });
+
+  test('throws V0ApiError on non-OK responses', async () => {
+    globalThis.fetch = (async () => ({
+      ok: false,
+      status: 401,
+      statusText: 'Unauthorized',
+      headers: new Headers({ 'content-type': 'application/json' }),
+      async text() {
+        return JSON.stringify({ error: { message: 'Invalid API key' } });
+      },
+    })) as unknown as typeof fetch;
+    const client = new V0Client({ apiKey: 'bad' });
+    await expect(client.get('/user')).rejects.toThrow('Invalid API key');
+  });
+});

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

@@ -0,0 +1,121 @@
+import type { V0Config } from '../types';
+import { V0ApiError } from '../types';
+
+export const DEFAULT_BASE_URL = 'https://api.v0.dev/v1';
+
+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>;
+}
+
+export class V0Client {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+
+  constructor(config: V0Config) {
+    if (!config.apiKey) {
+      throw new Error('API key is required');
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    const url = new URL(`${this.baseUrl}${normalizedPath}`);
+    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> = {
+      Authorization: `Bearer ${this.apiKey}`,
+      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);
+
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    let data: unknown;
+    const contentType = response.headers.get('content-type') || '';
+
+    if (contentType.includes('application/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 errorMessage = typeof data === 'object' && data !== null
+        ? ((data as Record<string, unknown>).message as string)
+          || ((data as { error?: { message?: string } }).error?.message)
+          || JSON.stringify(data)
+        : String(data || response.statusText);
+      throw new V0ApiError(errorMessage, response.status);
+    }
+
+    return data as T;
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined> | object): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params: params as Record<string, string | number | boolean | undefined> });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown> | unknown[] | string | object): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body: body as Record<string, unknown> });
+  }
+
+  async put<T>(path: string, body?: Record<string, unknown> | unknown[] | string | object): Promise<T> {
+    return this.request<T>(path, { method: 'PUT', body: body as Record<string, unknown> });
+  }
+
+  async delete<T>(path: string): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE' });
+  }
+
+  getApiKeyPreview(): string {
+    if (this.apiKey.length > 10) {
+      return `${this.apiKey.substring(0, 6)}...${this.apiKey.substring(this.apiKey.length - 4)}`;
+    }
+    return '***';
+  }
+
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+}