@lakimi/nestjs-external-schema

NestJS module for @lakimi/external-schema. Decorator-based registration of tools that get exposed to the Lakimi platform via WebSocket. Discovered automatically at startup and registered with the Lakimi server on connect.

Features

• @LakimiFunction decorator + auto-discovery via @golevelup/nestjs-discovery.
• Sync (forRoot) and async (forRootAsync) module configuration.
• Forwards all SDK options through client: LakiExternalSchemaClientOptions, so any new SDK feature (heartbeat, schema version, etc.) is supported without changes here.

Installation

pnpm add @lakimi/nestjs-external-schema

Peer deps required by your app: @nestjs/common, @golevelup/nestjs-discovery.

Usage — connector mode (recommended)

import { Module } from '@nestjs/common';
import { LakimiExternalSchemaModule } from '@lakimi/nestjs-external-schema';

@Module({
  imports: [
    LakimiExternalSchemaModule.forRoot({
      client: {
        url: 'https://api.lakimi.io',
        connectorId: process.env.LAKIMI_CONNECTOR_ID!, // from Portal → Conector → Credenciales
        clientId: process.env.LAKIMI_CLIENT_ID!,
        secretKey: process.env.LAKIMI_SECRET_KEY!,
        schemaVersion: '1.0.0',
        instanceId: process.env.HOSTNAME,             // optional, distinguishes replicas
      },
    }),
  ],
})
export class AppModule {}

Async config

LakimiExternalSchemaModule.forRootAsync({
  inject: [ConfigService],
  useFactory: (cfg: ConfigService) => ({
    client: {
      url: cfg.get('LAKIMI_URL'),
      connectorId: cfg.get('LAKIMI_CONNECTOR_ID'),
      clientId: cfg.get('LAKIMI_CLIENT_ID'),
      secretKey: cfg.get('LAKIMI_SECRET_KEY'),
      schemaVersion: cfg.get('SERVICE_VERSION'),
    },
  }),
});

Legacy mode

If you haven't migrated to a connector yet, the legacy name + environment fields still work against the old gateway. Connect via the old URL automatically.

client: {
  url: 'https://api.lakimi.io',
  name: 'my-service',
  clientId: '...',
  secretKey: '...',
  environment: 'production',
}

Define tools

import { Injectable } from '@nestjs/common';
import { LakimiFunction } from '@lakimi/nestjs-external-schema';

@Injectable()
export class MyService {
  @LakimiFunction({
    name: 'add_numbers',
    description: 'Adds two numbers and returns the result.',
    input_schema: {
      type: 'object',
      properties: {
        a: { type: 'number' },
        b: { type: 'number' },
      },
      required: ['a', 'b'],
    },
    constraints: { auth: true },
  })
  async addNumbers({ input }: { input: { a: number; b: number } }) {
    return { result: input.a + input.b };
  }
}

The handler receives a LakiToolContext with { source, input, user? }. source is "agent" or "assistant" depending on who invoked the tool; user is the authenticated user claims when constraints.auth is true.

What you get for free with connector mode

• Multi-instance HA: scale your service horizontally; Lakimi round-robins calls across all live replicas of the same connector.
• Schema versioning: tools registered with a schemaVersion are version-aware on the platform side (rolling deploys + admin pinning).
• Liveness: the SDK pings every 30s; dead replicas are reclaimed in ≤2 min.
• Tool execution heartbeat: long-running tool handlers automatically emit tool_progress so the platform doesn't time out.
• Per-action validation: the platform validates incoming params against your input_schema before invoking your handler.

API

• LakimiExternalSchemaModule.forRoot(options)
• LakimiExternalSchemaModule.forRootAsync({ useFactory, inject })
• @LakimiFunction(metadata) — decorator
• LakimiExternalSchemaService — exposed for advanced use (manually injectable)

License

ISC © 2025 Lakimi Solutions S.L.