@hasna/connectors 1.3.2 → 1.3.3

package/dist/lib/llm.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Provider-agnostic LLM client for open-connectors.
+ *
+ * Supports: cerebras, groq, openai, anthropic
+ * Config stored at: ~/.connectors/llm.json
+ *
+ * Cerebras and Groq are OpenAI-compatible (same SDK, different base URLs).
+ * Anthropic has its own API format.
+ */
+export type LLMProvider = "cerebras" | "groq" | "openai" | "anthropic";
+export interface LLMConfig {
+    provider: LLMProvider;
+    model: string;
+    api_key: string;
+    strip: boolean;
+}
+export interface LLMResponse {
+    content: string;
+    provider: LLMProvider;
+    model: string;
+    latency_ms: number;
+}
+export declare const PROVIDER_DEFAULTS: Record<LLMProvider, {
+    model: string;
+}>;
+export declare function getLlmConfig(): LLMConfig | null;
+export declare function saveLlmConfig(config: LLMConfig): void;
+export declare function setLlmStrip(enabled: boolean): void;
+export declare function isStripEnabled(): boolean;
+/** Mask API key for display: show first 8 chars + *** */
+export declare function maskKey(key: string): string;
+export declare class LLMClient {
+    private config;
+    constructor(config: LLMConfig);
+    static fromConfig(): LLMClient | null;
+    complete(prompt: string, content: string): Promise<LLMResponse>;
+    private _anthropicComplete;
+}

package/dist/lib/llm.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/lock.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Advisory file-based write lock for per-connector operations.
+ *
+ * Prevents concurrent agents from racing on token refresh and config writes.
+ * Reads remain unaffected — only write operations (saveApiKey, refreshOAuthToken,
+ * switchProfile) acquire the lock.
+ *
+ * Strategy: atomic O_EXCL file creation as the lock primitive (works on all
+ * platforms including macOS). Lock files live at:
+ *   ~/.connectors/connect-{name}/.write.lock
+ *
+ * Callers that cannot acquire the lock within the timeout receive a LockTimeoutError.
+ */
+export declare class LockTimeoutError extends Error {
+    readonly connector: string;
+    constructor(connector: string);
+}
+/**
+ * Acquire a write lock for a connector, run the callback, then release.
+ * Throws LockTimeoutError if the lock cannot be acquired within LOCK_TIMEOUT_MS.
+ */
+export declare function withWriteLock<T>(connector: string, fn: () => T | Promise<T>): Promise<T>;

package/dist/lib/lock.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/registry.d.ts

@@ -13,6 +13,27 @@ export declare const CATEGORIES: readonly ["AI & ML", "Developer Tools", "Design
 export type Category = (typeof CATEGORIES)[number];
 export declare const CONNECTORS: ConnectorMeta[];
 export declare function getConnectorsByCategory(category: Category): ConnectorMeta[];
-export declare function searchConnectors(query: string): ConnectorMeta[];
+export interface SearchContext {
+    installed?: string[];
+    promoted?: string[];
+    usage?: Map<string, number>;
+}
+export interface ScoredResult extends ConnectorMeta {
+    score: number;
+    matchReasons: string[];
+    badges: string[];
+}
+/**
+ * Ranked connector search with multi-token AND, scoring, and context signals.
+ *
+ * Score formula:
+ *   relevance (name/tag/displayName/description matches)
+ *   + installed boost (+50)
+ *   + promoted boost (+30)
+ *   + usage boost (min(count * 2, 40))
+ */
+export declare function searchConnectors(query: string, context?: SearchContext & {
+    limit?: number;
+}): ScoredResult[];
 export declare function getConnector(name: string): ConnectorMeta | undefined;
 export declare function loadConnectorVersions(): void;

package/dist/lib/scheduler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Connector job scheduler.
+ *
+ * Checks enabled jobs against their cron expressions and runs them
+ * when due. Runs in-process as part of `connectors serve`.
+ *
+ * Cron format: minute hour day month weekday (5-field standard)
+ * Uses a lightweight cron matcher — no external dep needed.
+ */
+import type { Database } from "bun:sqlite";
+import { type ConnectorJob } from "../db/jobs.js";
+/** Start the scheduler. Checks every 30s, fires jobs when cron matches. */
+export declare function startScheduler(db: Database): void;
+export declare function stopScheduler(): void;
+/** Manually trigger a job by ID (for CLI 'connectors jobs run') */
+export declare function triggerJob(job: ConnectorJob, db: Database): Promise<{
+    run_id: string;
+    exit_code: number;
+    output: string;
+}>;

package/dist/lib/scheduler.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/strip.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Global output stripping middleware.
+ *
+ * When strip is enabled in ~/.connectors/llm.json, every output surface
+ * (MCP, REST, CLI) passes through maybeStrip() before returning to the caller.
+ * This reduces token consumption for AI agents consuming connector output.
+ *
+ * If strip is disabled or no LLM config exists, output is returned as-is.
+ */
+export type StripType = "json" | "text";
+/**
+ * Conditionally strip output through LLM if strip is enabled.
+ * Returns output unchanged if strip is disabled or LLM not configured.
+ */
+export declare function maybeStrip(output: string, _type?: StripType): Promise<string>;
+/**
+ * Synchronous passthrough check — returns true if stripping is active.
+ * Use this to decide whether to await maybeStrip or skip it.
+ */
+export declare function isStrippingActive(): boolean;

package/dist/lib/strip.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/synonyms.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Synonym expansion for connector search.
+ * Domain-specific terms only — not a general thesaurus.
+ */
+/**
+ * Expand search tokens with domain synonyms.
+ * Returns original tokens + synonym tokens (deduplicated).
+ */
+export declare function expandQuery(tokens: string[]): {
+    original: string[];
+    expanded: string[];
+};

package/dist/lib/synonyms.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/workflow-runner.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Workflow runner — executes sequential connector pipelines.
+ *
+ * Each step receives the previous step's output as additional context
+ * injected into its args as --input <previous_output>.
+ */
+import type { ConnectorWorkflow } from "../db/workflows.js";
+export interface WorkflowStepResult {
+    step: number;
+    connector: string;
+    command: string;
+    exit_code: number;
+    output: string;
+}
+export interface WorkflowResult {
+    workflow_id: string;
+    workflow_name: string;
+    steps: WorkflowStepResult[];
+    success: boolean;
+    final_output: string;
+}
+export declare function runWorkflow(workflow: ConnectorWorkflow): Promise<WorkflowResult>;

package/dist/server/auth.d.ts

@@ -42,7 +42,7 @@ export declare function getEnvVars(name: string): {
 /**
  * Save an API key to a connector's profile
  */
-export declare function saveApiKey(name: string, key: string, field?: string): void;
+export declare function saveApiKey(name: string, key: string, field?: string): Promise<void>;
 /**
  * Get OAuth client credentials for a connector
  */
@@ -63,7 +63,9 @@ export declare function validateOAuthState(state: string | null, expectedConnect
  */
 export declare function exchangeOAuthCode(name: string, code: string, redirectUri: string): Promise<OAuthTokens>;
 /**
- * Refresh an OAuth token using the stored refresh token
+ * Refresh an OAuth token using the stored refresh token.
+ * Serialized with a per-connector write lock to prevent concurrent agents
+ * from racing on token refresh (double-refresh race condition).
  */
 export declare function refreshOAuthToken(name: string): Promise<OAuthTokens>;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/connectors",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "Open source connector library - Install API connectors with a single command",
   "type": "module",
   "bin": {
@@ -30,6 +30,7 @@
     "dev": "bun run ./src/cli/index.tsx",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
+    "sdk:build": "cd sdk && bun run build",
     "prepublishOnly": "bun test && bun run build"
   },
   "keywords": [

package/connectors/connect-huggingface/src/api/example.ts

@@ -1,48 +0,0 @@
-import type { HuggingFaceClient } from './client';
-import type { ExampleResource, ExampleListResponse, ExampleCreateParams } from '../types';
-
-/**
- * Example API module - demonstrates the pattern for API modules
- * Replace with actual HuggingFace API endpoints (models, datasets, spaces, etc.)
- */
-export class ExampleApi {
-  constructor(private readonly client: HuggingFaceClient) {}
-
-  /**
-   * List resources with optional pagination
-   */
-  async list(options?: { maxResults?: number; pageToken?: string }): Promise<ExampleListResponse> {
-    return this.client.get<ExampleListResponse>('/resources', {
-      max_results: options?.maxResults,
-      page_token: options?.pageToken,
-    });
-  }
-
-  /**
-   * Get a single resource by ID
-   */
-  async get(id: string): Promise<ExampleResource> {
-    return this.client.get<ExampleResource>(`/resources/${id}`);
-  }
-
-  /**
-   * Create a new resource
-   */
-  async create(params: ExampleCreateParams): Promise<ExampleResource> {
-    return this.client.post<ExampleResource>('/resources', params);
-  }
-
-  /**
-   * Update an existing resource
-   */
-  async update(id: string, params: Partial<ExampleCreateParams>): Promise<ExampleResource> {
-    return this.client.patch<ExampleResource>(`/resources/${id}`, params);
-  }
-
-  /**
-   * Delete a resource
-   */
-  async delete(id: string): Promise<void> {
-    await this.client.delete(`/resources/${id}`);
-  }
-}

package/connectors/connect-yousign/CLAUDE.md

@@ -1,48 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code when working with this repository.
-
-## Project Overview
-
-connect-yousign is a TypeScript CLI and library for the Yousign electronic signature API v3. It provides eIDAS-compliant digital signature workflows — create signature requests, upload documents, add signers, and track audit trails.
-
-## Build & Run Commands
-
-```bash
-bun install
-bun run dev
-bun run build
-bun run typecheck
-```
-
-## Authentication
-
-Bearer token (API key). Set via:
-- Environment variable: `YOUSIGN_API_KEY`
-- Profile config: `connect-yousign config set-key <key>`
-
-## API Environments
-
-| Environment | Base URL |
-|---|---|
-| Sandbox | `https://api.sandbox.yousign.app/v3` |
-| Production | `https://api.yousign.app/v3` |
-
-Default: sandbox. Use `--production` flag or set `YOUSIGN_ENV=production`.
-
-## Environment Variables
-
-| Variable | Description |
-|---|---|
-| `YOUSIGN_API_KEY` | API key (Bearer token) |
-| `YOUSIGN_ENV` | `sandbox` (default) or `production` |
-
-## Data Storage
-
-```
-~/.connectors/connect-yousign/
-├── current_profile
-└── profiles/
-    ├── default.json
-    └── {name}.json
-```

package/connectors/connect-yousign/package.json

@@ -1,52 +0,0 @@
-{
-  "name": "@hasna/connect-yousign",
-  "version": "0.0.1",
-  "description": "Yousign connector - eIDAS-compliant electronic signature API (v3)",
-  "type": "module",
-  "bin": {
-    "connect-yousign": "./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": [
-    "yousign",
-    "esignature",
-    "electronic-signature",
-    "eidas",
-    "signature-request",
-    "document-signing",
-    "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/connect-yousign/src/api/client.ts

@@ -1,119 +0,0 @@
-import type { YouSignConfig } from '../types';
-import { YouSignApiError } from '../types';
-
-const BASE_URLS = {
-  sandbox: 'https://api.sandbox.yousign.app/v3',
-  production: 'https://api.yousign.app/v3',
-};
-
-export interface RequestOptions {
-  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-  params?: Record<string, string | number | boolean | undefined>;
-  body?: Record<string, unknown> | unknown[] | FormData;
-  headers?: Record<string, string>;
-}
-
-export class YouSignClient {
-  private readonly apiKey: string;
-  private readonly baseUrl: string;
-
-  constructor(config: YouSignConfig) {
-    if (!config.apiKey) {
-      throw new Error('Yousign API key is required');
-    }
-    this.apiKey = config.apiKey;
-    this.baseUrl = BASE_URLS[config.environment || 'sandbox'];
-  }
-
-  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
-    const url = new URL(`${this.baseUrl}${path}`);
-    if (params) {
-      for (const [key, value] of Object.entries(params)) {
-        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}`,
-      ...headers,
-    };
-
-    const isFormData = body instanceof FormData;
-    if (body && !isFormData && ['POST', 'PUT', 'PATCH'].includes(method)) {
-      requestHeaders['Content-Type'] = 'application/json';
-    }
-
-    requestHeaders['Accept'] = 'application/json';
-
-    const fetchOptions: RequestInit = {
-      method,
-      headers: requestHeaders,
-    };
-
-    if (body) {
-      if (isFormData) {
-        fetchOptions.body = body;
-      } else if (['POST', 'PUT', 'PATCH'].includes(method)) {
-        fetchOptions.body = JSON.stringify(body);
-      }
-    }
-
-    const response = await fetch(url, fetchOptions);
-
-    if (response.status === 204) {
-      return {} as T;
-    }
-
-    // For binary downloads (PDF, etc.)
-    const contentType = response.headers.get('content-type') || '';
-    if (contentType.includes('application/pdf') || contentType.includes('application/octet-stream')) {
-      if (!response.ok) {
-        const text = await response.text();
-        throw new YouSignApiError(response.status, response.statusText, text);
-      }
-      return response.arrayBuffer() as unknown as T;
-    }
-
-    let data: unknown;
-    const text = await response.text();
-    try {
-      data = text ? JSON.parse(text) : {};
-    } catch {
-      data = text;
-    }
-
-    if (!response.ok) {
-      throw new YouSignApiError(response.status, response.statusText, data);
-    }
-
-    return data as T;
-  }
-
-  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
-    return this.request<T>(path, { params });
-  }
-
-  async post<T>(path: string, body?: Record<string, unknown> | unknown[] | FormData): Promise<T> {
-    return this.request<T>(path, { method: 'POST', body });
-  }
-
-  async patch<T>(path: string, body?: Record<string, unknown>): Promise<T> {
-    return this.request<T>(path, { method: 'PATCH', body });
-  }
-
-  async put<T>(path: string, body?: Record<string, unknown>): Promise<T> {
-    return this.request<T>(path, { method: 'PUT', body });
-  }
-
-  async delete<T>(path: string): Promise<T> {
-    return this.request<T>(path, { method: 'DELETE' });
-  }
-}