@alavida/sdk

Component SDK for the Alavida platform. Provides schema definition, auth context extraction, gateway middleware, and async job callbacks for components deployed as standalone services.

Installation

npm install @alavida/sdk

Zero runtime dependencies — uses native fetch() only.

Quick Start

import { Hono } from "hono";
import {
  defineSchemaHono,
  alavidaMiddlewareHono,
  getAuthContext,
  completeJob,
  failJob,
} from "@alavida/sdk";
import type { ComponentSchema } from "@alavida/sdk";

const schema: ComponentSchema = {
  slug: "my-component",
  name: "My Component",
  type: "workflow",
  version: "1.0.0",
  actions: {
    run: {
      description: "Run the main workflow",
      input_schema: {
        type: "object",
        properties: { query: { type: "string" } },
        required: ["query"],
      },
      output_schema: {
        type: "object",
        properties: { result: { type: "string" } },
      },
    },
  },
};

const app = new Hono();

// Schema endpoint — no auth required
app.get("/schema", defineSchemaHono(schema));

// Protected routes — only accept gateway traffic
app.use("/run", alavidaMiddlewareHono());

app.post("/run", async (c) => {
  const { teamId, userId, jobId, callbackUrl } = getAuthContext(c.req.raw.headers);
  const body = await c.req.json();

  // Do your work...
  const result = await doWork(body.input);

  // Report completion back to the platform
  await completeJob(callbackUrl!, {
    result,
    credits_used: 100,
  });

  return c.json({ status: "accepted" });
});

API Reference

defineSchema(config: ComponentSchema)

Returns a (req: Request) => Response handler that serves the component schema as JSON. Framework-agnostic.

import { defineSchema } from "@alavida/sdk";

const handler = defineSchema(schema);
// Use with any framework that gives you a Request object

defineSchemaHono(config: ComponentSchema)

Hono-specific shortcut. Returns (c) => c.json(config).

app.get("/schema", defineSchemaHono(schema));

getAuthContext(headers: Headers | Record<string, string | undefined>)

Extracts auth context from gateway-injected headers:

| Header | Field | Required | |--------|-------|----------| | X-Alavida-Team-Id | teamId | Yes | | X-Alavida-User-Id | userId | Yes | | X-Alavida-Job-Id | jobId | Yes | | X-Alavida-Callback-Url | callbackUrl | No (only for async) |

Throws AlavidaAuthError if any required header is missing.

import { getAuthContext, AlavidaAuthError } from "@alavida/sdk";

try {
  const ctx = getAuthContext(request.headers);
  console.log(ctx.teamId, ctx.userId, ctx.jobId);
} catch (err) {
  if (err instanceof AlavidaAuthError) {
    // Request didn't come through the gateway
  }
}

alavidaMiddleware()

Returns a generic middleware function (req, next) => Response | Promise<Response> that rejects requests missing the X-Alavida-Team-Id header with a 401.

alavidaMiddlewareHono()

Hono-specific middleware. Rejects non-gateway requests with 401.

app.use("/run", alavidaMiddlewareHono());

completeJob(callbackUrl: string, result: JobResult)

Reports successful job completion to the platform.

await completeJob(callbackUrl, {
  result: { companies: [...] },
  credits_used: 500,
});

failJob(callbackUrl: string, error: JobError)

Reports job failure.

await failJob(callbackUrl, {
  error_code: "processing_failed",
  error_message: "API rate limit exceeded",
});

updateProgress(callbackUrl: string, progress: number)

Reports progress (0-100) for long-running jobs.

await updateProgress(callbackUrl, 50); // 50% done

Types

interface ComponentSchema {
  slug: string;
  name: string;
  type: "workflow" | "tool";
  version: string;
  actions: Record<string, ActionSchema>;
}

interface ActionSchema {
  description: string;
  input_schema: Record<string, unknown>;  // JSON Schema
  output_schema: Record<string, unknown>; // JSON Schema
}

interface AuthContext {
  teamId: string;
  userId: string;
  jobId: string;
  callbackUrl?: string;
}

interface JobResult {
  result: unknown;
  credits_used: number;
}

interface JobError {
  error_code: string;
  error_message: string;
}

Environment Variables

| Variable | Description | |----------|-------------| | INTERNAL_SECRET | Shared secret for callback auth. Required for completeJob, failJob, updateProgress. |

How It Works

1. The Alavida gateway proxies user requests to your component service
2. The gateway injects X-Alavida-* headers with auth context and callback URLs
3. Your component uses getAuthContext() to read these headers
4. For async workflows, call completeJob() or failJob() when done
5. The platform handles credits, job tracking, and user notifications