{"_id":"@alavida/sdk","name":"@alavida/sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@alavida/sdk","version":"0.1.0","type":"module","description":"Alavida component SDK — schema, auth context, callbacks, middleware","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"engines":{"node":">=18"},"publishConfig":{"access":"public"},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","lint":"echo ok"},"devDependencies":{"@types/node":"^22.10.0","tsup":"^8.3.0","typescript":"^5.7.0"},"gitHead":"f110ffa2ab9bb68cdbd96644b9473cd6d3565925","_id":"@alavida/sdk@0.1.0","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-NNub9t+F3dD0bYiPAjnyJwo4UsMXZSz/79kJcGcEIz2Ix6i94oY8WBnMMER6Kxg3Nk58jExCqEtYZbO2463XwA==","shasum":"c7e933c242a0930867380e42fd8742c56b0baadb","tarball":"https://registry.npmjs.org/@alavida/sdk/-/sdk-0.1.0.tgz","fileCount":5,"unpackedSize":18929,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGEJvBjC8SAcu4j29eVuiQQL2rzjm1VXsRfc5CzrwzmmAiAp1Z4VibUwKdawY28tEt7WGjJoEj9LJq5BZNjXWl0ohA=="}]},"_npmUser":{"name":"alexalavida","email":"alex@alavida.ai"},"directories":{},"maintainers":[{"name":"alexalavida","email":"alex@alavida.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.0_1770828927811_0.5701804837870441"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-11T16:55:27.741Z","0.1.0":"2026-02-11T16:55:27.960Z","modified":"2026-02-11T16:55:28.168Z"},"maintainers":[{"name":"alexalavida","email":"alex@alavida.ai"}],"description":"Alavida component SDK — schema, auth context, callbacks, middleware","readme":"# @alavida/sdk\n\nComponent SDK for the Alavida platform. Provides schema definition, auth context extraction, gateway middleware, and async job callbacks for components deployed as standalone services.\n\n## Installation\n\n```bash\nnpm install @alavida/sdk\n```\n\nZero runtime dependencies — uses native `fetch()` only.\n\n## Quick Start\n\n```typescript\nimport { Hono } from \"hono\";\nimport {\n  defineSchemaHono,\n  alavidaMiddlewareHono,\n  getAuthContext,\n  completeJob,\n  failJob,\n} from \"@alavida/sdk\";\nimport type { ComponentSchema } from \"@alavida/sdk\";\n\nconst schema: ComponentSchema = {\n  slug: \"my-component\",\n  name: \"My Component\",\n  type: \"workflow\",\n  version: \"1.0.0\",\n  actions: {\n    run: {\n      description: \"Run the main workflow\",\n      input_schema: {\n        type: \"object\",\n        properties: { query: { type: \"string\" } },\n        required: [\"query\"],\n      },\n      output_schema: {\n        type: \"object\",\n        properties: { result: { type: \"string\" } },\n      },\n    },\n  },\n};\n\nconst app = new Hono();\n\n// Schema endpoint — no auth required\napp.get(\"/schema\", defineSchemaHono(schema));\n\n// Protected routes — only accept gateway traffic\napp.use(\"/run\", alavidaMiddlewareHono());\n\napp.post(\"/run\", async (c) => {\n  const { teamId, userId, jobId, callbackUrl } = getAuthContext(c.req.raw.headers);\n  const body = await c.req.json();\n\n  // Do your work...\n  const result = await doWork(body.input);\n\n  // Report completion back to the platform\n  await completeJob(callbackUrl!, {\n    result,\n    credits_used: 100,\n  });\n\n  return c.json({ status: \"accepted\" });\n});\n```\n\n## API Reference\n\n### `defineSchema(config: ComponentSchema)`\n\nReturns a `(req: Request) => Response` handler that serves the component schema as JSON. Framework-agnostic.\n\n```typescript\nimport { defineSchema } from \"@alavida/sdk\";\n\nconst handler = defineSchema(schema);\n// Use with any framework that gives you a Request object\n```\n\n### `defineSchemaHono(config: ComponentSchema)`\n\nHono-specific shortcut. Returns `(c) => c.json(config)`.\n\n```typescript\napp.get(\"/schema\", defineSchemaHono(schema));\n```\n\n### `getAuthContext(headers: Headers | Record<string, string | undefined>)`\n\nExtracts auth context from gateway-injected headers:\n\n| Header | Field | Required |\n|--------|-------|----------|\n| `X-Alavida-Team-Id` | `teamId` | Yes |\n| `X-Alavida-User-Id` | `userId` | Yes |\n| `X-Alavida-Job-Id` | `jobId` | Yes |\n| `X-Alavida-Callback-Url` | `callbackUrl` | No (only for async) |\n\nThrows `AlavidaAuthError` if any required header is missing.\n\n```typescript\nimport { getAuthContext, AlavidaAuthError } from \"@alavida/sdk\";\n\ntry {\n  const ctx = getAuthContext(request.headers);\n  console.log(ctx.teamId, ctx.userId, ctx.jobId);\n} catch (err) {\n  if (err instanceof AlavidaAuthError) {\n    // Request didn't come through the gateway\n  }\n}\n```\n\n### `alavidaMiddleware()`\n\nReturns a generic middleware function `(req, next) => Response | Promise<Response>` that rejects requests missing the `X-Alavida-Team-Id` header with a 401.\n\n### `alavidaMiddlewareHono()`\n\nHono-specific middleware. Rejects non-gateway requests with 401.\n\n```typescript\napp.use(\"/run\", alavidaMiddlewareHono());\n```\n\n### `completeJob(callbackUrl: string, result: JobResult)`\n\nReports successful job completion to the platform.\n\n```typescript\nawait completeJob(callbackUrl, {\n  result: { companies: [...] },\n  credits_used: 500,\n});\n```\n\n### `failJob(callbackUrl: string, error: JobError)`\n\nReports job failure.\n\n```typescript\nawait failJob(callbackUrl, {\n  error_code: \"processing_failed\",\n  error_message: \"API rate limit exceeded\",\n});\n```\n\n### `updateProgress(callbackUrl: string, progress: number)`\n\nReports progress (0-100) for long-running jobs.\n\n```typescript\nawait updateProgress(callbackUrl, 50); // 50% done\n```\n\n## Types\n\n```typescript\ninterface ComponentSchema {\n  slug: string;\n  name: string;\n  type: \"workflow\" | \"tool\";\n  version: string;\n  actions: Record<string, ActionSchema>;\n}\n\ninterface ActionSchema {\n  description: string;\n  input_schema: Record<string, unknown>;  // JSON Schema\n  output_schema: Record<string, unknown>; // JSON Schema\n}\n\ninterface AuthContext {\n  teamId: string;\n  userId: string;\n  jobId: string;\n  callbackUrl?: string;\n}\n\ninterface JobResult {\n  result: unknown;\n  credits_used: number;\n}\n\ninterface JobError {\n  error_code: string;\n  error_message: string;\n}\n```\n\n## Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `INTERNAL_SECRET` | Shared secret for callback auth. Required for `completeJob`, `failJob`, `updateProgress`. |\n\n## How It Works\n\n1. The Alavida gateway proxies user requests to your component service\n2. The gateway injects `X-Alavida-*` headers with auth context and callback URLs\n3. Your component uses `getAuthContext()` to read these headers\n4. For async workflows, call `completeJob()` or `failJob()` when done\n5. The platform handles credits, job tracking, and user notifications\n","readmeFilename":"README.md","_rev":"1-922eea21c5aa514aaae906ccc32d727a"}