@vantageos/integration-kit

Abstract integration adapter interfaces for Vantage Immo — swappable Composio/GWS/Firecrawl/OpenAI/etc.

What it is

Defines the stable adapter interfaces (IIntegrationAdapter, ISigningAdapter, IPropertyManagementAdapter, IReviewAdapter, IScraperAdapter, IEmbeddingProvider) that feature MCPs import. The concrete implementation can be swapped without touching any feature MCP code.

Adapters

| Export | Description | |---|---| | IIntegrationAdapter | Core interface — file ops + mail ops | | ISigningAdapter | E-signature platforms (Yousign, DocuSign) | | IPropertyManagementAdapter | Property management tools (Hektor, LOJII) | | IReviewAdapter | Customer review platforms (Immodvisor) | | IScraperAdapter | Web scraping backends (Firecrawl, Playwright) — v0.2.0 | | IEmbeddingProvider | Embedding providers (OpenAI, Cohere) — v0.2.0 | | ComposioAdapter | Composio implementation (test phase, C6 build) | | createComposioAdapter | Factory — pass apiKey + connectedAccountId | | FirecrawlScraperAdapter | Firecrawl stub (C-scraper build) | | createFirecrawlAdapter | Factory — pass apiKey + optional allowedHostnames | | OpenAIEmbeddingsAdapter | OpenAI embeddings stub (C-embedding build) | | createOpenAIEmbeddingsAdapter | Factory — pass apiKey + optional model / dimensions | | AdapterRegistry | Type for registering adapters by key |

Usage — existing adapters (v0.1.0)

import type { IIntegrationAdapter } from "@vantageos/integration-kit";
import { createComposioAdapter } from "@vantageos/integration-kit/composio";

// Feature MCP imports only the interface — never the concrete adapter
function processFiles(adapter: IIntegrationAdapter) {
  return adapter.listFiles({ limit: 50 });
}

// Wired at app bootstrap (C6 build)
const adapter = createComposioAdapter({
  apiKey: process.env.COMPOSIO_API_KEY!,
  connectedAccountId: orgConnectedAccountId,
});

v0.2.0 additions

IScraperAdapter (F-add-1)

Uniform interface for web scraping backends. Allows swapping Firecrawl for any other scraping backend without modifying feature MCP code.

import type { IScraperAdapter, ScraperOpts, ScraperResult } from "@vantageos/integration-kit/scraper";
import { createFirecrawlAdapter } from "@vantageos/integration-kit/adapters/firecrawl";

// Feature MCP — depends only on the interface
async function scrapeProperty(adapter: IScraperAdapter, url: string) {
  if (!adapter.supports(url)) {
    throw new Error(`Adapter ${adapter.name} does not support: ${url}`);
  }
  const result: ScraperResult = await adapter.fetch(url, {
    formats: ["rawText", "jsonExtract"],
    extractSchema: {
      type: "object",
      properties: {
        price: { type: "number" },
        surface: { type: "number" },
        address: { type: "string" },
      },
    },
    timeoutMs: 30_000,
  });
  // result.contentHash — SHA-256 of content, for dedup in the data lake
  // result.fetchMethod — "firecrawl" (adapter name, for lineage tracking)
  // result.qualityFlags — { paywalled?, jsRendered?, authRequired?, robotsDisallowed? }
  return result;
}

// Wired at app bootstrap (C-scraper build)
// Env var: FIRECRAWL_API_KEY
const scraper = createFirecrawlAdapter({
  apiKey: process.env.FIRECRAWL_API_KEY!,
  allowedHostnames: ["seloger.com", "leboncoin.fr"], // optional allowlist
});

Key properties of ScraperResult:

| Field | Type | Description | |---|---|---| | contentHash | string | SHA-256 hex of canonicalized content — for deduplication | | fetchMethod | string | Adapter name (e.g. "firecrawl") — for lineage | | qualityFlags | QualityFlags | paywalled, jsRendered, authRequired, robotsDisallowed | | durationMs | number | Wall-clock fetch time in ms | | rawText? | string | Plain text content (requested via formats: ["rawText"]) | | rawHtml? | string | Raw HTML (requested via formats: ["rawHtml"]) | | jsonExtract? | unknown | Structured extraction (requested via formats: ["jsonExtract"]) |

IEmbeddingProvider (F-add-3)

Uniform interface for embedding providers. Supports the versioning triplet (contentHash, modelId, promptVersion) used in the VantageOS radar / cache-invalidation pipeline.

import type { IEmbeddingProvider, EmbeddingRequest, EmbeddingResult } from "@vantageos/integration-kit/embedding";
import { createOpenAIEmbeddingsAdapter } from "@vantageos/integration-kit/adapters/openai-embeddings";

// Feature MCP — depends only on the interface
async function embedDescription(provider: IEmbeddingProvider, text: string) {
  const result: EmbeddingResult = await provider.embed({
    text,
    // model defaults to provider.defaultModel ("text-embedding-3-small")
    promptVersion: "v1", // for cache invalidation triplet
  });
  // result.vector       — number[] (1536 dims for text-embedding-3-small)
  // result.modelId      — "text-embedding-3-small" (always set)
  // result.promptVersion — "v1" (always set, defaults if omitted in request)
  return result;
}

// Batch variant — one API round-trip for many texts
async function embedBatch(provider: IEmbeddingProvider, texts: string[]) {
  return provider.embedBatch(
    texts.map((text) => ({ text, promptVersion: "v1" })),
  );
}

// Wired at app bootstrap (C-embedding build)
// Env var: OPENAI_API_KEY
const embedder = createOpenAIEmbeddingsAdapter({
  apiKey: process.env.OPENAI_API_KEY!,
  // model: "text-embedding-3-large", // optional — defaults to text-embedding-3-small
  // dimensions: 3072,                // optional — must match model output
});

Key properties of EmbeddingResult:

| Field | Type | Description | |---|---|---| | vector | number[] | Dense embedding vector | | dimensions | number | Length of vector (e.g. 1536 for text-embedding-3-small) | | modelId | string | Resolved model — always set (part of versioning triplet) | | promptVersion | string | Resolved prompt version — always set, defaults to "v1" |

Versioning triplet — store (contentHash, modelId, promptVersion) alongside every embedding in the data lake. Re-embed when any element of the triplet changes (content updated, model changed, prompt template versioned).

License

MIT