@signaliz/sdk 1.0.1

package/README.md

@@ -0,0 +1,98 @@
+# @signaliz/sdk
+
+The official Signaliz SDK for JavaScript/TypeScript — GTM intelligence for AI agents.
+
+## Installation
+
+```bash
+npm install @signaliz/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Signaliz } from '@signaliz/sdk';
+
+const signaliz = new Signaliz({
+  apiKey: process.env.SIGNALIZ_API_KEY,
+});
+
+// Find and verify an email
+const email = await signaliz.emails.find({
+  fullName: 'Jane Smith',
+  companyDomain: 'stripe.com',
+});
+console.log(email);
+// → { email: 'jane.smith@stripe.com', verificationStatus: 'valid', confidence: 0.95 }
+
+// Verify an email
+const result = await signaliz.emails.verify('jane@stripe.com');
+// → { isValid: true, isDeliverable: true, isCatchAll: false, confidenceScore: 0.98 }
+
+// Company signals
+const signals = await signaliz.signals.enrich({
+  companyName: 'Stripe',
+  researchPrompt: 'Find recent hiring activities',
+});
+
+// Systems (pipelines)
+const system = await signaliz.systems.create({
+  name: 'Email Pipeline',
+  capabilities: ['mcp_input', 'find_emails_with_verification', 'mcp_output'],
+});
+const run = await signaliz.systems.run(system.id, { data: [...] });
+
+// Stream progress
+for await (const event of signaliz.runs.stream(run.runId)) {
+  console.log(`${event.completedRows}/${event.totalRows} — ${event.status}`);
+}
+
+// HTTP proxy
+const response = await signaliz.http.request({
+  url: 'https://api.example.com/data',
+  method: 'GET',
+});
+```
+
+## MCP Setup
+
+Connect Signaliz to your AI agent in one command:
+
+```bash
+npx @signaliz/mcp
+```
+
+## Authentication
+
+### API Key (simplest)
+```typescript
+const signaliz = new Signaliz({ apiKey: 'sk_...' });
+```
+
+### M2M OAuth
+```typescript
+const signaliz = new Signaliz({
+  clientId: process.env.SIGNALIZ_CLIENT_ID,
+  clientSecret: process.env.SIGNALIZ_CLIENT_SECRET,
+});
+```
+
+## Error Handling
+
+```typescript
+import { Signaliz, SignalizError } from '@signaliz/sdk';
+
+try {
+  await signaliz.emails.find({ fullName: 'Test', companyDomain: 'example.com' });
+} catch (e) {
+  if (e instanceof SignalizError) {
+    console.log(e.errorType);  // 'rate_limited' | 'validation' | 'timeout' | ...
+    console.log(e.retryAfter); // seconds to wait (for 429s)
+    console.log(e.isRetryable); // boolean
+  }
+}
+```
+
+## License
+
+MIT

package/dist/chunk-R657OZE7.mjs

@@ -0,0 +1,543 @@
+// src/errors.ts
+var SignalizError = class extends Error {
+  constructor(data) {
+    super(data.message);
+    this.name = "SignalizError";
+    this.code = data.code;
+    this.errorType = data.errorType;
+    this.retryAfter = data.retryAfter;
+    this.details = data.details;
+  }
+  get isRetryable() {
+    return this.errorType === "rate_limited" || this.errorType === "timeout" || this.errorType === "provider_error";
+  }
+};
+function parseError(status, body) {
+  if (body?.error && typeof body.error === "object") {
+    return new SignalizError({
+      code: body.error.code || `HTTP_${status}`,
+      message: body.error.message || `Request failed with status ${status}`,
+      errorType: mapErrorType(body.error.code, status),
+      retryAfter: body.error.retry_after,
+      details: body.error.details
+    });
+  }
+  return new SignalizError({
+    code: `HTTP_${status}`,
+    message: body?.message || body?.error || `Request failed with status ${status}`,
+    errorType: mapErrorType(void 0, status)
+  });
+}
+function mapErrorType(code, status) {
+  if (code === "RATE_LIMITED" || status === 429) return "rate_limited";
+  if (code === "VALIDATION_ERROR" || status === 400) return "validation";
+  if (code === "NOT_FOUND" || status === 404) return "not_found";
+  if (code === "AUTH_EXPIRED" || status === 401) return "auth_expired";
+  if (code === "INSUFFICIENT_CREDITS" || status === 402) return "insufficient_credits";
+  if (code === "TIMEOUT" || status === 504) return "timeout";
+  if (status >= 500) return "provider_error";
+  return "unknown";
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.signaliz.com/functions/v1";
+var DEFAULT_TIMEOUT = 12e4;
+var DEFAULT_MAX_RETRIES = 3;
+var HttpClient = class {
+  constructor(config) {
+    this.baseUrl = config.baseUrl?.replace(/\/$/, "") || DEFAULT_BASE_URL;
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.apiKey = config.apiKey;
+    this.clientId = config.clientId;
+    this.clientSecret = config.clientSecret;
+    if (!this.apiKey && !(this.clientId && this.clientSecret)) {
+      throw new Error("Signaliz: provide either apiKey or clientId + clientSecret");
+    }
+  }
+  async request(functionName, body, method = "POST") {
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const token = await this.getToken();
+        const url = `${this.baseUrl}/${functionName}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        const init = {
+          method,
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`
+          },
+          signal: controller.signal
+        };
+        if (method === "POST") {
+          init.body = JSON.stringify(body);
+        }
+        const res = await fetch(url, init);
+        clearTimeout(timer);
+        if (!res.ok) {
+          const errBody = await res.json().catch(() => ({}));
+          const err = parseError(res.status, errBody);
+          if (err.isRetryable && attempt < this.maxRetries) {
+            const wait = err.retryAfter ? err.retryAfter * 1e3 : Math.min(1e3 * Math.pow(2, attempt), 1e4);
+            await sleep(wait);
+            lastError = err;
+            continue;
+          }
+          throw err;
+        }
+        return await res.json();
+      } catch (e) {
+        if (e instanceof SignalizError) throw e;
+        if (e.name === "AbortError") {
+          const timeout = new SignalizError({
+            code: "TIMEOUT",
+            message: `Request timed out after ${this.timeout}ms`,
+            errorType: "timeout"
+          });
+          if (attempt < this.maxRetries) {
+            lastError = timeout;
+            await sleep(1e3 * Math.pow(2, attempt));
+            continue;
+          }
+          throw timeout;
+        }
+        lastError = e;
+        if (attempt < this.maxRetries) {
+          await sleep(1e3 * Math.pow(2, attempt));
+          continue;
+        }
+      }
+    }
+    throw lastError || new Error("Request failed after retries");
+  }
+  /** Convenience wrapper for POST-based edge function calls */
+  async post(functionName, body) {
+    return this.request(functionName, body, "POST");
+  }
+  /** JSON-RPC call to the MCP server */
+  async mcp(method, params = {}) {
+    const token = await this.getToken();
+    const url = `${this.baseUrl}/signaliz-mcp`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: Date.now(),
+        method,
+        params
+      })
+    });
+    const data = await res.json();
+    if (data.error) {
+      throw new SignalizError({
+        code: data.error.code?.toString() || "MCP_ERROR",
+        message: data.error.message || "MCP request failed",
+        errorType: "unknown"
+      });
+    }
+    if (data.result?.content?.[0]?.text) {
+      try {
+        return JSON.parse(data.result.content[0].text);
+      } catch {
+        return data.result.content[0].text;
+      }
+    }
+    if (data.result?.structuredContent) {
+      return data.result.structuredContent;
+    }
+    return data.result;
+  }
+  async getToken() {
+    if (this.apiKey) return this.apiKey;
+    if (this.accessToken) return this.accessToken;
+    const res = await fetch("https://api.signaliz.com/token", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        grant_type: "client_credentials",
+        client_id: this.clientId,
+        client_secret: this.clientSecret
+      })
+    });
+    if (!res.ok) {
+      throw new SignalizError({
+        code: "AUTH_FAILED",
+        message: "Failed to obtain access token",
+        errorType: "auth_expired"
+      });
+    }
+    const data = await res.json();
+    this.accessToken = data.access_token;
+    return this.accessToken;
+  }
+};
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// src/resources/emails.ts
+var Emails = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Find and verify an email address for a person at a company */
+  async find(params) {
+    const body = {
+      company_domain: params.companyDomain
+    };
+    if (params.fullName) body.full_name = params.fullName;
+    if (params.firstName) body.first_name = params.firstName;
+    if (params.lastName) body.last_name = params.lastName;
+    if (params.linkedinUrl) body.linkedin_url = params.linkedinUrl;
+    if (params.companyName) body.company_name = params.companyName;
+    const data = await this.client.mcp("tools/call", {
+      name: "find_emails_with_verification",
+      arguments: body
+    });
+    return {
+      email: data.email,
+      firstName: data.first_name,
+      lastName: data.last_name,
+      confidence: data.confidence ?? data.confidence_score ?? 0,
+      verificationStatus: data.verification_status ?? "unknown",
+      providerUsed: data.provider_used ?? data.source ?? "unknown"
+    };
+  }
+  /** Verify a single email address */
+  async verify(email) {
+    const data = await this.client.mcp("tools/call", {
+      name: "verify_email",
+      arguments: { email }
+    });
+    return {
+      email: data.email ?? email,
+      isValid: data.is_valid ?? false,
+      isDeliverable: data.is_deliverable ?? false,
+      isCatchAll: data.is_catch_all ?? false,
+      provider: data.provider,
+      confidenceScore: data.confidence_score ?? 0,
+      verificationSource: data.verification_source
+    };
+  }
+};
+
+// src/resources/signals.ts
+var Signals = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Enrich a company with actionable signals (V1) */
+  async enrich(params) {
+    const args = {
+      company_name: params.companyName
+    };
+    if (params.domain) args.domain = params.domain;
+    if (params.researchPrompt) args.research_prompt = params.researchPrompt;
+    if (params.signalTypes) args.signal_types = params.signalTypes;
+    const data = await this.client.mcp("tools/call", {
+      name: "enrich_company_signals",
+      arguments: args
+    });
+    return {
+      companyName: data.company_name ?? params.companyName,
+      signals: (data.signals ?? []).map((s) => ({
+        title: s.title,
+        signalType: s.signal_type,
+        confidenceScore: s.confidence_score ?? 0,
+        detectedAt: s.detected_at ?? "",
+        url: s.url,
+        content: s.content ?? ""
+      })),
+      totalSignals: data.total_signals ?? data.signals?.length ?? 0,
+      fromCache: data.from_cache ?? false
+    };
+  }
+  /** Enrich a company with actionable signals (V2 — clean response + online mode) */
+  async enrichV2(params) {
+    const args = {};
+    if (params.companyName) args.company_name = params.companyName;
+    if (params.domain) args.domain = params.domain;
+    if (params.companyDomain) args.company_domain = params.companyDomain;
+    if (params.researchPrompt) args.research_prompt = params.researchPrompt;
+    if (params.signalTypes) args.signal_types = params.signalTypes;
+    if (params.online !== void 0) args.online = params.online;
+    if (params.targetSignalCount) args.target_signal_count = params.targetSignalCount;
+    if (params.lookbackDays) args.lookback_days = params.lookbackDays;
+    if (params.model) args.model = params.model;
+    if (params.enableDeepSearch) args.enable_deep_search = params.enableDeepSearch;
+    if (params.enableOutreachIntelligence) args.enable_outreach_intelligence = params.enableOutreachIntelligence;
+    if (params.enablePredictiveIntelligence) args.enable_predictive_intelligence = params.enablePredictiveIntelligence;
+    if (params.icpId) args.icp_id = params.icpId;
+    if (params.cacheTtlHours !== void 0) args.cache_ttl_hours = params.cacheTtlHours;
+    if (params.skipCache) args.skip_cache = params.skipCache;
+    const data = await this.client.post("company-signal-enrichment-v2", args);
+    return {
+      success: data.success ?? false,
+      company: {
+        name: data.company?.name ?? null,
+        domain: data.company?.domain ?? null
+      },
+      signals: (data.signals ?? []).map((s) => ({
+        id: s.id,
+        title: s.title,
+        type: s.type,
+        content: s.content ?? "",
+        date: s.date ?? null,
+        sourceUrl: s.source_url ?? null,
+        sourceType: s.source_type ?? "unknown",
+        confidence: s.confidence ?? null
+      })),
+      signalCount: data.signal_count ?? 0,
+      intelligence: data.intelligence ? {
+        executiveSummary: data.intelligence.executive_summary ?? null,
+        keyThemes: data.intelligence.key_themes ?? [],
+        relevanceScore: data.intelligence.relevance_score ?? null,
+        outreach: data.intelligence.outreach ? {
+          urgencyScore: data.intelligence.outreach.urgency_score ?? null,
+          bestTiming: data.intelligence.outreach.best_timing ?? null,
+          primaryAngle: data.intelligence.outreach.primary_angle ?? null,
+          ctas: data.intelligence.outreach.ctas ? {
+            soft: data.intelligence.outreach.ctas.soft,
+            direct: data.intelligence.outreach.ctas.direct,
+            valueFirst: data.intelligence.outreach.ctas.value_first
+          } : null,
+          conversationStarters: data.intelligence.outreach.conversation_starters ?? []
+        } : null,
+        predictions: (data.intelligence.predictions ?? []).map((p) => ({
+          prediction: p.prediction,
+          confidence: p.confidence,
+          targetPersona: p.target_persona ?? null,
+          recommendedAction: p.recommended_action ?? null
+        }))
+      } : null,
+      credits: {
+        charged: data.credits?.charged ?? 0,
+        billingType: data.credits?.billing_type ?? "unknown",
+        breakdown: {
+          signalCredits: data.credits?.breakdown?.signal_credits ?? 0,
+          modelCostUsd: data.credits?.breakdown?.model_cost_usd ?? 0,
+          modelCredits: data.credits?.breakdown?.model_credits ?? 0,
+          explanation: data.credits?.breakdown?.explanation ?? ""
+        }
+      },
+      metadata: {
+        version: data.metadata?.version ?? "",
+        model: data.metadata?.model ?? "",
+        online: data.metadata?.online ?? false,
+        processingTimeMs: data.metadata?.processing_time_ms ?? 0
+      }
+    };
+  }
+};
+
+// src/resources/systems.ts
+var Systems = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Create a new pipeline/system */
+  async create(params) {
+    const data = await this.client.mcp("tools/call", {
+      name: "create_system",
+      arguments: {
+        name: params.name,
+        description: params.description,
+        capabilities: params.capabilities,
+        field_mappings: params.fieldMappings
+      }
+    });
+    return {
+      id: data.system_id ?? data.id,
+      name: data.name ?? params.name,
+      status: data.status ?? "created",
+      nodeCount: data.node_count ?? params.capabilities.length,
+      createdAt: data.created_at ?? (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  /** Run a system with input data */
+  async run(systemId, params) {
+    const data = await this.client.mcp("tools/call", {
+      name: "run_system",
+      arguments: {
+        system_id: systemId,
+        input_data: params.data,
+        async: params.async ?? false
+      }
+    });
+    return {
+      runId: data.run_id ?? data.id,
+      status: data.status ?? "running",
+      totalRows: data.total_rows,
+      completedRows: data.completed_rows ?? 0,
+      creditsUsed: data.credits_used ?? 0
+    };
+  }
+  /** Get a system by ID */
+  async get(systemId) {
+    const data = await this.client.mcp("tools/call", {
+      name: "get_system",
+      arguments: { system_id: systemId }
+    });
+    return {
+      id: data.id ?? systemId,
+      name: data.name,
+      status: data.status,
+      nodeCount: data.node_count ?? 0,
+      createdAt: data.created_at
+    };
+  }
+  /** List all systems */
+  async list() {
+    const data = await this.client.mcp("tools/call", {
+      name: "list_systems",
+      arguments: {}
+    });
+    return (data.systems ?? data ?? []).map((s) => ({
+      id: s.id,
+      name: s.name,
+      status: s.status,
+      nodeCount: s.node_count ?? 0,
+      createdAt: s.created_at
+    }));
+  }
+};
+
+// src/resources/runs.ts
+var Runs = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Get run status */
+  async get(runId) {
+    const data = await this.client.mcp("tools/call", {
+      name: "get_run_results",
+      arguments: { run_id: runId }
+    });
+    return {
+      runId: data.run_id ?? runId,
+      status: data.status,
+      totalRows: data.total_rows,
+      completedRows: data.completed_rows ?? 0,
+      creditsUsed: data.credits_used ?? 0
+    };
+  }
+  /** Poll until a run completes. Returns final result. */
+  async waitForCompletion(runId, pollIntervalMs = 2e3) {
+    while (true) {
+      const run = await this.get(runId);
+      if (["completed", "failed", "cancelled", "crashed", "timed_out", "interrupted", "system_failure"].includes(run.status)) {
+        return run;
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+  }
+  /**
+   * Stream run progress as an async iterator.
+   * Usage: for await (const event of signaliz.runs.stream(runId)) { ... }
+   */
+  async *stream(runId, pollIntervalMs = 1500) {
+    let lastCompleted = -1;
+    while (true) {
+      const run = await this.get(runId);
+      const event = {
+        runId,
+        status: run.status,
+        completedRows: run.completedRows ?? 0,
+        totalRows: run.totalRows ?? 0,
+        creditsUsed: run.creditsUsed ?? 0
+      };
+      if (event.completedRows !== lastCompleted) {
+        lastCompleted = event.completedRows;
+        yield event;
+      }
+      if (["completed", "failed", "cancelled"].includes(run.status)) {
+        return;
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+  }
+};
+
+// src/resources/http.ts
+var Http = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Proxy an HTTP request through Signaliz */
+  async request(params) {
+    const data = await this.client.mcp("tools/call", {
+      name: "http_request",
+      arguments: {
+        url: params.url,
+        method: params.method,
+        headers: params.headers,
+        body: params.body ? JSON.stringify(params.body) : void 0
+      }
+    });
+    return {
+      statusCode: data.status_code ?? data.statusCode ?? 200,
+      headers: data.headers ?? {},
+      body: data.body ?? data.response ?? data
+    };
+  }
+};
+
+// src/index.ts
+var Signaliz = class {
+  constructor(config) {
+    this.client = new HttpClient(config);
+    this.emails = new Emails(this.client);
+    this.signals = new Signals(this.client);
+    this.systems = new Systems(this.client);
+    this.runs = new Runs(this.client);
+    this.http = new Http(this.client);
+  }
+  /** Get current workspace info including credits */
+  async getWorkspace() {
+    const data = await this.client.mcp("tools/call", {
+      name: "get_workspace",
+      arguments: {}
+    });
+    return {
+      id: data.workspace_id ?? data.id,
+      name: data.workspace_name ?? data.name ?? "Unknown",
+      creditsRemaining: data.credits_remaining ?? data.credits ?? 0,
+      plan: data.plan ?? "unknown"
+    };
+  }
+  /** List all available MCP tools */
+  async listTools() {
+    const data = await this.client.mcp("tools/list", {});
+    const tools = data?.tools ?? data ?? [];
+    return tools.map((t) => ({
+      name: t.name,
+      description: (t.description ?? "").slice(0, 120),
+      category: t.annotations?.category,
+      costCredits: t.annotations?.cost_credits
+    }));
+  }
+  /** Discover tools by natural language query */
+  async discover(query, category) {
+    const data = await this.client.mcp("tools/call", {
+      name: "discover_capabilities",
+      arguments: { query, category }
+    });
+    return (data.matches ?? []).map((m) => ({
+      name: m.tool,
+      description: m.description,
+      category: m.category,
+      costCredits: m.cost_credits
+    }));
+  }
+};
+
+export {
+  SignalizError,
+  Signaliz
+};

package/dist/cli.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node