@lakimi/external-schema

@lakimi/external-schema is a library that facilitates integrating Node.js applications with Lakimi's function execution pipeline. It allows you to register custom tools and respond to events using socket.io, ensuring real-time communication with the Lakimi platform.

🚀 Features

• Register tools with input schemas defined using JSONSchema.
• Support for authentication and role-based access control.
• Real-time communication with socket.io.
• Event handling for tool execution and schema registration.

📦 Installation

npm install @lakimi/external-schema

Or with Yarn:

yarn add @lakimi/external-schema

⚙️ Configuration

Create a client instance

The first step is to create an instance of LakiExternalSchemaClient, providing the necessary connection options.

import { LakiExternalSchemaClient } from "@lakimi/external-schema";

const client = new LakiExternalSchemaClient({
  connectorId: "<your-connector-id>", // copied from the Lakimi portal
  secretKey: "<your-secret-key>",     // agency token (or scoped token covering this connector)
  url: "https://api.lakimi.io",       // optional — defaults to the public API
  clientVersion: "1.0.0",             // optional — surfaced as the `x-client-version` header
});

Connect the client

To start communicating with the Lakimi platform, call the connect method:

client.connect();

🛠 Registering and Handling Tools

You can register tools that the client will execute upon receiving a request from Lakimi. Each tool must define its input schema (input_schema) and provide a handler function (handle) to implement the desired logic.

Defining a Tool

import { JSONSchema7 } from "json-schema";
import { LakiTool } from "@lakimi/external-schema";

const myTool: LakiTool = {
  name: "example_tool",
  description: "An example tool that adds two numbers.",
  input_schema: {
    type: "object",
    properties: {
      a: { type: "number" },
      b: { type: "number" }
    },
    required: ["a", "b"]
  },
  handle: async ({ input }) => {
    const { a, b } = input as { a: number; b: number };
    return { result: a + b };
  }
};

Registering the Tool with the Client

client.useTool(myTool);

📂 Working with Files

Tools that need to receive or return binary content (PDFs, images, spreadsheets…) don't ship the bytes through the WebSocket — Lakimi sends only lightweight metadata in the tool payload, and the SDK fetches or uploads the actual bytes over HTTPS lazily.

There is no privileged JSON Schema slot. Tools embed file references inside any payload shape that makes sense for them. A typical input looks like:

{
  "attachments": [
    { "id": "<lakimi_id>", "name": "invoice.pdf" },
    { "id": "<lakimi_id>", "name": "spec.pdf" }
  ]
}

You can use the exported LakiFileMetadataInputSchema (and the matching LakiFileMetadataInput TS type) so the agent learns the expected shape:

import {
  LakiFileMetadataInputSchema,
  type LakiFileMetadataInput,
  type LakiTool,
} from "@lakimi/external-schema";

const processDocumentsTool: LakiTool = {
  name: "process_documents",
  description: "Process a batch of attached documents and return a summary file.",
  input_schema: {
    type: "object",
    required: ["attachments"],
    properties: {
      attachments: {
        type: "array",
        description: "Files to process, referenced by their Lakimi id.",
        items: LakiFileMetadataInputSchema,
      },
    },
  },
  handle: async ({ input, files }) => {
    const { attachments } = input as { attachments: LakiFileMetadataInput[] };

    // 1) Download attachments lazily — only when actually needed.
    for (const doc of attachments) {
      const buf = await files.download(doc.id);
      await processFile(doc.name, buf);
    }

    // 2) Produce a result file and embed its meta in the response.
    const summary = await renderSummary(attachments);
    const meta = await files.upload({
      buffer: summary,
      filename: "summary.pdf",
      mime_type: "application/pdf",
    });

    return {
      ok: true,
      summary: meta, // { id, filename, mime_type, size, sha256 }
    };
  },
};

The same namespace is also available on the client itself:

const meta = await client.files.upload({ buffer, filename: "x.pdf" });
const buf  = await client.files.download(meta.id);
const info = await client.files.describe(meta.id); // metadata only

Notes:

• File operations require the new connectorId-based connection (the legacy name-based gateway is not supported).
• Authentication reuses the same secretKey you pass to the client.
• Lakimi enforces an upload size limit on the server. files.upload rejects oversized payloads with a descriptive error — let it surface and the integrator will know to split or compress.
• Only file ids you received in a tool invocation, or that you uploaded yourself through this connector, can be downloaded. Other ids return 404.

📡 Events Handled by the Client

• connect: Notifies that the client has successfully connected to the Lakimi platform.
• disconnect: Notifies that the client has disconnected.
• request_schema: Requests the client to register its tool schema.
• execute_tool: Requests the execution of a registered tool.

📚 Full Example

import { LakiExternalSchemaClient, type LakiTool } from "@lakimi/external-schema";

const client = new LakiExternalSchemaClient({
  connectorId: "<your-connector-id>",
  secretKey: "<your-secret-key>",
});

const sumTool: LakiTool = {
  name: "sum_tool",
  description: "Adds two numbers.",
  input_schema: {
    type: "object",
    properties: {
      a: { type: "number" },
      b: { type: "number" }
    },
    required: ["a", "b"]
  },
  handle: async ({ input }) => {
    const { a, b } = input as { a: number; b: number };
    return { result: a + b };
  }
};

client.useTool(sumTool);
client.connect();

⚠️ Common Errors

• Tool not found: Make sure the tool is registered with the correct name.
• Connection failed: Verify your connectorId, secretKey, and (if overridden) the url.

📖 API Reference

LakiExternalSchemaClient(options: LakiExternalSchemaClientOptions)

Creates a new client instance.

• options.connectorId: Identifier of the connector this SDK is bound to (copy it from the Lakimi portal).
• options.secretKey: Bearer token used for both the WebSocket session and the file bridge.
• options.url: (optional) Lakimi API origin. Defaults to the public API.
• options.clientVersion: (optional) Sent as x-client-version for visibility in logs.
• options.progressIntervalMs: (optional) How often to emit tool_progress while a handler runs.

useTool(tool: LakiTool): LakiExternalSchemaClient

Registers a tool in the client.

connect(): void

Connects the client to the Lakimi platform.

📑 Types and Schemas

LakiExternalSchemaClientOptions

interface LakiExternalSchemaClientOptions {
  connectorId: string;
  secretKey: string;
  url?: string;
  clientVersion?: string;
  progressIntervalMs?: number;
}

LakiTool

interface LakiTool {
  name: string;
  description: string;
  input_schema: JSONSchema7;
  constraints?: LakiConstraints;
  handle: (context: LakiToolContext) => Promise<any>;
}

📝 License

ISC © 2025 Lakimi Solutions S.L.