@vaia-lab/sdk 0.1.0

package/README.md

@@ -0,0 +1,225 @@
+# @vaia/sdk
+
+VAIA Platform Integration SDK — connect your app, agent, or skill to [Gandia-7](https://gandia7.com) and [Handeia](https://handeia.com).
+
+Zero runtime dependencies · Works in Node 18+, Edge, Bun, Deno · TypeScript-first
+
+---
+
+## Install
+
+```bash
+npm install @vaia/sdk
+```
+
+---
+
+## Quick start (Next.js — Gandia-7)
+
+```ts
+// app/api/gandia/invoke/route.ts
+import { gandia, VAIAError } from '@vaia/sdk'
+
+export const runtime = 'edge'
+
+export async function POST(req: Request) {
+  try {
+    const { ctx } = await gandia.verify(req, process.env.GANDIA_KEY_SECRET!)
+    gandia.require(ctx, 'read:students')
+
+    const data = await myDb.getStudents(ctx.tenant.id)
+
+    return gandia.respond.surface(ctx.surface, {
+      card:  () => ({ title: 'Alumnos', value: data.length }),
+      table: () => ({ columns: ['nombre', 'riesgo'], rows: data }),
+      text:  () => `${data.length} alumnos en ${ctx.tenant.name}`,
+    })
+  } catch (err) {
+    if (err instanceof VAIAError) return gandia.respond.error(err.message, err.status)
+    throw err
+  }
+}
+```
+
+---
+
+## API Reference
+
+### `gandia.verify(request, secret)`
+
+Verifies the HMAC-SHA256 signature on an incoming invoke call from Gandia-7.
+
+- Checks `X-Gandia-Signature`, `X-Gandia-Timestamp` (replay window ±5 min)
+- Returns `{ ctx: GandiaContext, raw: string }`
+- Throws `VAIAError` (status 401) if invalid
+
+```ts
+const { ctx } = await gandia.verify(req, process.env.GANDIA_KEY_SECRET!)
+// ctx.tenant.id, ctx.tenant.name, ctx.tenant.sector
+// ctx.user.id, ctx.user.role
+// ctx.permissions  → ['read:students', 'read:grades']
+// ctx.surface      → 'card' | 'table' | 'text' | 'widget' | 'action' | 'data'
+// ctx.query        → user's original question (if trigger = 'user_query')
+```
+
+### `gandia.require(ctx, permission)`
+
+Throws `VAIAError` (403) if the context doesn't have the required permission.
+
+```ts
+gandia.require(ctx, 'write:alerts')           // single
+gandia.requireAll(ctx, 'read:students', 'read:grades')  // all
+const ok = gandia.can(ctx, 'read:health')     // boolean check
+```
+
+### `gandia.respond.surface(surface, handlers, opts?)`
+
+Multi-surface responder — GAIA tells you which surface it wants via `ctx.surface`.
+
+```ts
+return gandia.respond.surface(ctx.surface, {
+  card:  () => ({ title: 'Riesgo', value: 72, unit: '%', trend: 'up' }),
+  table: () => ({ columns: ['alumno', 'score'], rows }),
+  text:  () => `El riesgo promedio es 72%`,
+}, { audit: { data_sources: ['supabase:students'], records_accessed: 120 } })
+```
+
+Available surfaces: `card` · `table` · `text` · `widget` · `action` · `data`
+
+### `gandia.respond.*` — individual builders
+
+```ts
+gandia.respond.card({ title, value, unit, trend, subtitle, color })
+gandia.respond.table({ columns, rows, total })
+gandia.respond.text(content, { markdown: true })
+gandia.respond.widget({ url, height, width })
+gandia.respond.action({ type, label, params, confirm })
+gandia.respond.data(payload)
+gandia.respond.ok()
+gandia.respond.error(message, status, code?)
+```
+
+All return a `Response` (Web API standard). For Express/Fastify use `gandia.make.*` instead (returns plain JSON object).
+
+### `gandia.jwt.verify(token, secret)`
+
+Verifies a Gandia-7 iframe JWT (`gandia_token` URL param). Use in iframe entry routes to skip your own login.
+
+```ts
+// In your iframe entry route:
+const claims = await gandia.jwt.fromUrl(request.url, process.env.GANDIA_KEY_SECRET!)
+// claims.sub         → user_id
+// claims.tenant_id   → institution id
+// claims.email       → user email (if available)
+// claims.permissions → what the user can do
+```
+
+---
+
+### `handeia.*`
+
+Same API as `gandia.*` but for Handeia (personal platform). No tenant — just the user.
+
+```ts
+const { ctx } = await handeia.verify(req, process.env.HANDEIA_KEY_SECRET!)
+// ctx.user.id, ctx.user.email
+// ctx.permissions, ctx.surface, ctx.query
+```
+
+---
+
+### `defineCapability(config)`
+
+Declares your capability metadata in code. The Shazam engine reads this with 100% confidence — no manual confirmation needed in the Developer Portal.
+
+```ts
+// vaia.config.ts
+import { defineCapability } from '@vaia/sdk'
+
+export default defineCapability({
+  id: 'mx.monitor-riesgo-academico',  // reverse-domain
+  name: 'Monitor de Riesgo Académico',
+  version: '1.0.0',
+  target: 'gandia',           // 'gandia' | 'handeia' | 'both'
+  type: 'app',                // 'app' | 'ia' | 'skill' | 'eco'
+  level: 'artefacto',         // 'widget' | 'artefacto' | 'espacio'
+  sector: 'educacion',
+  surfaces: {
+    card:  { endpoint: '/api/gandia/invoke' },
+    table: { endpoint: '/api/gandia/invoke' },
+    text:  { endpoint: '/api/gandia/invoke' },
+  },
+  permissions: ['read:students', 'read:grades', 'write:alerts'],
+  risk: 'medium',
+})
+```
+
+Generate `gandia.manifest.json`:
+
+```bash
+# Compile vaia.config.ts first, then:
+npx vaia manifest
+
+# Validate existing manifest:
+npx vaia manifest --validate
+```
+
+---
+
+## Error handling
+
+All verification functions throw `VAIAError` on failure:
+
+```ts
+import { VAIAError } from '@vaia/sdk'
+
+try {
+  const { ctx } = await gandia.verify(req, secret)
+  // ...
+} catch (err) {
+  if (err instanceof VAIAError) {
+    // err.message → human-readable message (Spanish)
+    // err.code    → machine-readable: 'HMAC_INVALID', 'JWT_EXPIRED', 'PERMISSION_DENIED', etc.
+    // err.status  → HTTP status: 401, 403, 400, 422
+    return gandia.respond.error(err.message, err.status, err.code)
+  }
+  throw err
+}
+```
+
+### Error codes
+
+| Code | Status | When |
+|---|---|---|
+| `MISSING_AUTH_HEADERS` | 401 | X-Gandia-Signature or X-Gandia-Timestamp missing |
+| `TIMESTAMP_OUT_OF_RANGE` | 401 | Timestamp outside ±5 min window |
+| `HMAC_INVALID` | 401 | Signature doesn't match |
+| `BODY_PARSE_ERROR` | 400 | Body is not valid JSON |
+| `JWT_MALFORMED` | 401 | JWT doesn't have 3 parts |
+| `JWT_SIGNATURE_INVALID` | 401 | JWT signature check failed |
+| `JWT_EXPIRED` | 401 | JWT exp claim is in the past |
+| `PERMISSION_DENIED` | 403 | Missing required permission |
+| `SURFACE_NOT_SUPPORTED` | 422 | No handler for requested surface |
+
+---
+
+## CLI
+
+```bash
+npx vaia manifest            # generate gandia.manifest.json
+npx vaia manifest --validate # validate existing manifest
+npx vaia sign payload.json   # sign a payload (needs GANDIA_KEY_SECRET)
+npx vaia version             # SDK version
+```
+
+---
+
+## Publishing
+
+Publication to npm is done manually by the VAIA team via `npm login` + `npm publish`.
+
+---
+
+## License
+
+MIT — VAIA

package/dist/cli.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { resolve, join } from "path";
+import { createInterface } from "readline";
+
+// src/crypto.ts
+var enc = new TextEncoder();
+async function importHMACKey(secret) {
+  return crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign", "verify"]
+  );
+}
+async function hmacSign(secret, data) {
+  const key = await importHMACKey(secret);
+  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(data));
+  return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/define.ts
+function defineCapability(config) {
+  const required = ["id", "name", "version", "target", "type", "sector", "permissions", "risk"];
+  for (const key of required) {
+    if (config[key] === void 0 || config[key] === "") {
+      throw new Error(`[@vaia/sdk] defineCapability: campo requerido faltante: '${key}'`);
+    }
+  }
+  if (!config.id.includes(".")) {
+    throw new Error(
+      `[@vaia/sdk] defineCapability: 'id' debe usar formato reverse-domain (ej. 'mx.mi-capacidad'). Recibido: '${config.id}'`
+    );
+  }
+  if (Object.keys(config.surfaces).length === 0) {
+    throw new Error(`[@vaia/sdk] defineCapability: 'surfaces' no puede estar vac\xEDo. Define al menos un surface con su endpoint.`);
+  }
+  return config;
+}
+function toManifest(config) {
+  const surfaces = Object.keys(config.surfaces);
+  return {
+    schema: "1.0",
+    capability_id: config.id,
+    name: config.name,
+    version: config.version,
+    target: config.target === "both" ? ["gandia", "handeia"] : config.target,
+    type: config.type,
+    level: config.level,
+    sector: config.sector,
+    surfaces,
+    permissions: config.permissions,
+    risk: config.risk,
+    has_own_auth: config.has_own_auth ?? false,
+    stores_data: config.stores_data ?? false,
+    trains_models: config.trains_models ?? false,
+    requires_consent: config.requires_consent ?? false,
+    description: config.description,
+    tags: config.tags,
+    linked: config.target === "both",
+    generated_by: "@vaia/sdk",
+    generated_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+
+// src/cli.ts
+var pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+var args = process.argv.slice(2);
+var cmd = args[0];
+async function main() {
+  switch (cmd) {
+    case "manifest":
+      return cmdManifest();
+    case "sign":
+      return cmdSign();
+    case "version":
+    case "-v":
+    case "--version":
+      console.log(`@vaia/sdk v${pkg.version}`);
+      break;
+    default:
+      printHelp();
+  }
+}
+async function cmdManifest() {
+  const cwd = process.cwd();
+  const configPath = resolve(cwd, "vaia.config.js");
+  const outPath = join(cwd, "gandia.manifest.json");
+  const validate = args.includes("--validate");
+  if (validate) {
+    if (!existsSync(outPath)) {
+      console.error("\u2717 gandia.manifest.json no encontrado.");
+      process.exit(1);
+    }
+    const raw = JSON.parse(readFileSync(outPath, "utf8"));
+    const required = ["schema", "capability_id", "name", "version", "target", "type", "sector", "permissions", "risk"];
+    const missing = required.filter((k) => !raw[k]);
+    if (missing.length > 0) {
+      console.error(`\u2717 Campos requeridos faltantes: ${missing.join(", ")}`);
+      process.exit(1);
+    }
+    console.log(`\u2713 gandia.manifest.json v\xE1lido (${raw["capability_id"]})`);
+    return;
+  }
+  if (!existsSync(configPath)) {
+    console.error([
+      "\u2717 vaia.config.js no encontrado en:",
+      cwd,
+      "",
+      "Crea vaia.config.ts en la ra\xEDz de tu proyecto:",
+      "",
+      "  import { defineCapability } from '@vaia/sdk'",
+      "  export default defineCapability({",
+      "    id: 'mx.mi-capacidad',",
+      "    name: 'Mi Capacidad',",
+      "    version: '1.0.0',",
+      "    target: 'gandia',",
+      "    type: 'app',",
+      "    sector: 'educacion',",
+      "    surfaces: { card: { endpoint: '/api/gandia/invoke' } },",
+      "    permissions: ['read:data'],",
+      "    risk: 'low',",
+      "  })",
+      "",
+      "Compila primero con tsc o tsx, luego corre: npx vaia manifest"
+    ].join("\n"));
+    process.exit(1);
+  }
+  let config;
+  try {
+    const mod = await import(configPath);
+    config = mod.default;
+    defineCapability(config);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`\u2717 Error al cargar vaia.config.js:
+  ${msg}`);
+    process.exit(1);
+  }
+  if (!config) {
+    console.error("\u2717 vaia.config.js no export\xF3 ninguna configuraci\xF3n.");
+    process.exit(1);
+  }
+  const manifest = toManifest(config);
+  writeFileSync(outPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+  console.log(`\u2713 gandia.manifest.json generado \u2192 ${outPath}`);
+  console.log(`  capability_id : ${manifest.capability_id}`);
+  console.log(`  target        : ${Array.isArray(manifest.target) ? manifest.target.join(" + ") : manifest.target}`);
+  console.log(`  surfaces      : ${manifest.surfaces.join(", ")}`);
+  console.log(`  permissions   : ${manifest.permissions.join(", ")}`);
+  console.log(`  risk          : ${manifest.risk}`);
+}
+async function cmdSign() {
+  const payloadArg = args[1];
+  const secret = process.env["GANDIA_KEY_SECRET"] ?? process.env["HANDEIA_KEY_SECRET"];
+  if (!secret) {
+    console.error("\u2717 GANDIA_KEY_SECRET o HANDEIA_KEY_SECRET requerido en el entorno.");
+    process.exit(1);
+  }
+  let payload;
+  if (payloadArg && existsSync(payloadArg)) {
+    payload = readFileSync(payloadArg, "utf8").trim();
+  } else if (payloadArg) {
+    payload = payloadArg;
+  } else {
+    payload = await readStdin();
+  }
+  const timestamp = Date.now().toString();
+  const signed = `${timestamp}.${payload}`;
+  const sig = await hmacSign(secret, signed);
+  console.log(JSON.stringify({
+    "X-Gandia-Signature": `sha256=${sig}`,
+    "X-Gandia-Timestamp": timestamp,
+    signed_payload: signed
+  }, null, 2));
+}
+function printHelp() {
+  console.log([
+    `@vaia/sdk v${pkg.version}`,
+    "",
+    "Comandos:",
+    "  vaia manifest              Genera gandia.manifest.json desde vaia.config.js",
+    "  vaia manifest --validate   Valida un gandia.manifest.json existente",
+    "  vaia sign [payload]        Firma un payload con GANDIA_KEY_SECRET",
+    "  vaia version               Muestra la versi\xF3n del SDK",
+    "",
+    "Docs: https://github.com/diegoramirez772/vaia-sdk"
+  ].join("\n"));
+}
+function readStdin() {
+  return new Promise((resolve2) => {
+    const rl = createInterface({ input: process.stdin });
+    const lines = [];
+    rl.on("line", (l) => lines.push(l));
+    rl.on("close", () => resolve2(lines.join("\n")));
+  });
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});