@vaia-lab/sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,601 @@
+// @vaia/sdk — VAIA Platform Integration SDK
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  VAIAError: () => VAIAError,
+  defineCapability: () => defineCapability,
+  gandia: () => gandia,
+  handeia: () => handeia,
+  toManifest: () => toManifest
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/gandia/index.ts
+var gandia_exports = {};
+__export(gandia_exports, {
+  can: () => can,
+  canAll: () => canAll,
+  canAny: () => canAny,
+  isProbe: () => isProbe,
+  jwt: () => jwt_exports,
+  make: () => make,
+  require: () => require2,
+  requireAll: () => requireAll,
+  respond: () => respond,
+  verify: () => verify
+});
+
+// src/crypto.ts
+var enc = new TextEncoder();
+function hexToBytes(hex) {
+  if (hex.length % 2 !== 0) throw new Error("Invalid hex string");
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+  }
+  return bytes;
+}
+async function importHMACKey(secret) {
+  return crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign", "verify"]
+  );
+}
+async function hmacVerify(secret, data, hexSignature) {
+  try {
+    const key = await importHMACKey(secret);
+    const sigBytes = hexToBytes(hexSignature);
+    return await crypto.subtle.verify("HMAC", key, sigBytes, enc.encode(data));
+  } catch {
+    return false;
+  }
+}
+
+// src/types.ts
+var VAIAError = class extends Error {
+  constructor(message, code, status = 500) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "VAIAError";
+  }
+  code;
+  status;
+};
+
+// src/gandia/verify.ts
+var REPLAY_WINDOW_MS = 5 * 60 * 1e3;
+var PROBE_HEADER = "x-gandia-probe";
+async function verify(request, secret) {
+  const rawBody = await request.text();
+  const headers = request.headers;
+  const sigHeader = headers.get("x-gandia-signature") ?? "";
+  const tsHeader = headers.get("x-gandia-timestamp") ?? "";
+  const callId = headers.get("x-gandia-call-id") ?? "";
+  if (headers.get(PROBE_HEADER) === "1") {
+    return { ctx: buildProbeCtx(callId), raw: rawBody };
+  }
+  if (!sigHeader || !tsHeader) {
+    throw new VAIAError(
+      "Faltan headers de autenticaci\xF3n (X-Gandia-Signature, X-Gandia-Timestamp)",
+      "MISSING_AUTH_HEADERS",
+      401
+    );
+  }
+  const ts = parseInt(tsHeader, 10);
+  if (isNaN(ts) || Math.abs(Date.now() - ts) > REPLAY_WINDOW_MS) {
+    throw new VAIAError("Timestamp fuera de ventana (\xB15 min)", "TIMESTAMP_OUT_OF_RANGE", 401);
+  }
+  const hexSig = sigHeader.startsWith("sha256=") ? sigHeader.slice(7) : sigHeader;
+  const signedData = `${tsHeader}.${rawBody}`;
+  const valid = await hmacVerify(secret, signedData, hexSig);
+  if (!valid) {
+    throw new VAIAError("Firma HMAC inv\xE1lida", "HMAC_INVALID", 401);
+  }
+  let body;
+  try {
+    body = JSON.parse(rawBody);
+  } catch {
+    throw new VAIAError("Body no es JSON v\xE1lido", "BODY_PARSE_ERROR", 400);
+  }
+  const ctx = parseContext(body, callId);
+  return { ctx, raw: rawBody };
+}
+function parseContext(body, fallbackCallId) {
+  if (typeof body !== "object" || body === null) {
+    throw new VAIAError("Body inv\xE1lido", "BODY_INVALID", 400);
+  }
+  const b = body;
+  return {
+    capability_id: str(b, "capability_id"),
+    call_id: str(b, "call_id", fallbackCallId),
+    tenant: {
+      id: nestedStr(b, "tenant", "id"),
+      name: nestedStr(b, "tenant", "name"),
+      sector: nestedStr(b, "tenant", "sector")
+    },
+    user: {
+      id: nestedStr(b, "user", "id"),
+      role: nestedStr(b, "user", "role"),
+      email: nestedStrOpt(b, "user", "email")
+    },
+    permissions: arr(b, "permissions"),
+    trigger: str(b, "context.trigger", "gaia_invoke"),
+    surface: str(b, "context.surface", "data"),
+    query: nestedStrOpt(b, "context", "query")
+  };
+}
+function buildProbeCtx(callId) {
+  return {
+    capability_id: "__probe__",
+    call_id: callId || crypto.randomUUID(),
+    tenant: { id: "__probe__", name: "__probe__", sector: "__probe__" },
+    user: { id: "__probe__", role: "__probe__" },
+    permissions: [],
+    trigger: "gaia_invoke",
+    surface: "data"
+  };
+}
+function str(obj, key, fallback = "") {
+  const parts = key.split(".");
+  let cur = obj;
+  for (const part of parts) {
+    if (typeof cur !== "object" || cur === null) return fallback;
+    cur = cur[part];
+  }
+  return typeof cur === "string" ? cur : fallback;
+}
+function nestedStr(obj, parent, key, fallback = "") {
+  const p = obj[parent];
+  if (typeof p !== "object" || p === null) return fallback;
+  const v = p[key];
+  return typeof v === "string" ? v : fallback;
+}
+function nestedStrOpt(obj, parent, key) {
+  const p = obj[parent];
+  if (typeof p !== "object" || p === null) return void 0;
+  const v = p[key];
+  return typeof v === "string" ? v : void 0;
+}
+function arr(obj, key) {
+  const v = obj[key];
+  if (!Array.isArray(v)) return [];
+  return v.filter((x) => typeof x === "string");
+}
+function isProbe(request) {
+  return request.headers.get(PROBE_HEADER) === "1";
+}
+
+// src/gandia/jwt.ts
+var jwt_exports = {};
+__export(jwt_exports, {
+  fromUrl: () => fromUrl,
+  sign: () => sign,
+  verify: () => verify2
+});
+
+// src/jwt-utils.ts
+var enc2 = new TextEncoder();
+function b64urlEncode(data) {
+  const str2 = typeof data === "string" ? data : String.fromCharCode(...new Uint8Array(data));
+  return btoa(str2).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function b64urlDecode(str2) {
+  const padded = str2.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = padded.length % 4;
+  return atob(pad ? padded + "=".repeat(4 - pad) : padded);
+}
+async function importHMACKey2(secret) {
+  return crypto.subtle.importKey(
+    "raw",
+    enc2.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign", "verify"]
+  );
+}
+var HEADER = b64urlEncode(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+async function jwtSign(payload, secret) {
+  const body = b64urlEncode(JSON.stringify(payload));
+  const unsigned = `${HEADER}.${body}`;
+  const key = await importHMACKey2(secret);
+  const sig = await crypto.subtle.sign("HMAC", key, enc2.encode(unsigned));
+  return `${unsigned}.${b64urlEncode(sig)}`;
+}
+async function jwtVerify(token, secret) {
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    throw new VAIAError("JWT malformado", "JWT_MALFORMED", 401);
+  }
+  const [header, body, sig] = parts;
+  const unsigned = `${header}.${body}`;
+  const key = await importHMACKey2(secret);
+  const sigBytes = Uint8Array.from(b64urlDecode(sig), (c) => c.charCodeAt(0));
+  const valid = await crypto.subtle.verify("HMAC", key, sigBytes, enc2.encode(unsigned));
+  if (!valid) {
+    throw new VAIAError("Firma JWT inv\xE1lida", "JWT_SIGNATURE_INVALID", 401);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(b64urlDecode(body));
+  } catch {
+    throw new VAIAError("JWT payload inv\xE1lido", "JWT_PAYLOAD_INVALID", 401);
+  }
+  if (typeof payload.exp === "number" && Date.now() / 1e3 > payload.exp) {
+    throw new VAIAError("JWT expirado", "JWT_EXPIRED", 401);
+  }
+  return payload;
+}
+
+// src/gandia/jwt.ts
+var DEFAULT_EXPIRES_IN = 3600;
+async function sign(input, secret, opts = {}) {
+  const now = Math.floor(Date.now() / 1e3);
+  return jwtSign(
+    {
+      ...input,
+      permissions: input.permissions ?? [],
+      iat: now,
+      exp: now + (opts.expiresIn ?? DEFAULT_EXPIRES_IN)
+    },
+    secret
+  );
+}
+async function verify2(token, secret) {
+  return jwtVerify(token, secret);
+}
+async function fromUrl(url, secret) {
+  const u = typeof url === "string" ? new URL(url) : url;
+  const token = u.searchParams.get("gandia_token");
+  if (!token) {
+    throw new Error("gandia_token no encontrado en la URL");
+  }
+  return verify2(token, secret);
+}
+
+// src/gandia/respond.ts
+var JSON_HEADERS = { "Content-Type": "application/json" };
+function toResponse(body, status = 200) {
+  return new Response(JSON.stringify(body), { status, headers: JSON_HEADERS });
+}
+var make = {
+  card(payload, opts = {}) {
+    return { ok: true, output_type: "card", data: payload, ...opts };
+  },
+  table(payload, opts = {}) {
+    return { ok: true, output_type: "table", data: payload, ...opts };
+  },
+  text(content, opts = {}) {
+    const { markdown, ...rest } = opts;
+    return { ok: true, output_type: "text", text: content, markdown, ...rest };
+  },
+  widget(payload, opts = {}) {
+    return { ok: true, output_type: "widget", data: payload, ...opts };
+  },
+  action(payload, opts = {}) {
+    return { ok: true, output_type: "action", data: payload, ...opts };
+  },
+  data(payload, opts = {}) {
+    return { ok: true, output_type: "data", data: payload, ...opts };
+  }
+};
+var respond = {
+  /** A compact card: title, value, unit, trend, etc. */
+  card(payload, opts = {}) {
+    return toResponse(make.card(payload, opts));
+  },
+  /** Tabular data with columns + rows. */
+  table(payload, opts = {}) {
+    return toResponse(make.table(payload, opts));
+  },
+  /** Plain text or markdown — shown in chat or narrative views. */
+  text(content, opts = {}) {
+    return toResponse(make.text(content, opts));
+  },
+  /** An iframe pointing to the developer's own UI. */
+  widget(payload, opts = {}) {
+    return toResponse(make.widget(payload, opts));
+  },
+  /** Trigger an action (mutation, navigation, confirm dialog). */
+  action(payload, opts = {}) {
+    return toResponse(make.action(payload, opts));
+  },
+  /** Arbitrary JSON — HAIA decides how to render based on shape. */
+  data(payload, opts = {}) {
+    return toResponse(make.data(payload, opts));
+  },
+  /** Simple 200 OK — useful for probe responses. */
+  ok(opts = {}) {
+    return toResponse(make.data({ status: "ok" }, opts));
+  },
+  /** Returns a 4xx/5xx error response. */
+  error(message, status = 500, code) {
+    return toResponse({ ok: false, error: message, ...code ? { code } : {} }, status);
+  },
+  /**
+   * Multi-surface responder.
+   * GAIA sends `ctx.surface` telling you what to render.
+   * Map each surface to its handler and this picks the right one.
+   *
+   *   return gandia.respond.surface(ctx.surface, {
+   *     card:  () => ({ title: 'Riesgo', value: 72, unit: '%' }),
+   *     table: () => ({ columns: [...], rows: [...] }),
+   *     text:  () => `El riesgo es 72%`,
+   *   }, opts)
+   */
+  async surface(surface, handlers, opts = {}) {
+    const handler = handlers[surface];
+    if (!handler) {
+      const fallback = handlers.data ?? handlers.text ?? Object.values(handlers).find(Boolean);
+      if (!fallback) {
+        throw new VAIAError(
+          `Surface '${surface}' no soportada por esta capacidad`,
+          "SURFACE_NOT_SUPPORTED",
+          422
+        );
+      }
+      return respond.surface(
+        handlers.data ? "data" : handlers.text ? "text" : Object.keys(handlers)[0],
+        handlers,
+        opts
+      );
+    }
+    switch (surface) {
+      case "card":
+        return respond.card(await handlers.card(), opts);
+      case "table":
+        return respond.table(await handlers.table(), opts);
+      case "text":
+        return respond.text(await handlers.text(), opts);
+      case "widget":
+        return respond.widget(await handlers.widget(), opts);
+      case "action":
+        return respond.action(await handlers.action(), opts);
+      case "data":
+        return respond.data(await handlers.data(), opts);
+      default:
+        return respond.data(await (handlers.data ?? handlers.text ?? (() => ({})))(), opts);
+    }
+  }
+};
+
+// src/gandia/permissions.ts
+function matches(permission, granted) {
+  if (granted.includes(permission)) return true;
+  const [action] = permission.split(":");
+  return granted.includes(`${action}:*`);
+}
+function can(ctx, permission) {
+  return matches(permission, ctx.permissions);
+}
+function canAll(ctx, ...permissions) {
+  return permissions.every((p) => matches(p, ctx.permissions));
+}
+function canAny(ctx, ...permissions) {
+  return permissions.some((p) => matches(p, ctx.permissions));
+}
+function require2(ctx, permission) {
+  if (!matches(permission, ctx.permissions)) {
+    throw new VAIAError(
+      `Permiso requerido: ${permission}`,
+      "PERMISSION_DENIED",
+      403
+    );
+  }
+}
+function requireAll(ctx, ...permissions) {
+  const missing = permissions.filter((p) => !matches(p, ctx.permissions));
+  if (missing.length > 0) {
+    throw new VAIAError(
+      `Permisos requeridos: ${missing.join(", ")}`,
+      "PERMISSION_DENIED",
+      403
+    );
+  }
+}
+
+// src/handeia/index.ts
+var handeia_exports = {};
+__export(handeia_exports, {
+  can: () => can,
+  canAll: () => canAll,
+  canAny: () => canAny,
+  isProbe: () => isProbe2,
+  jwt: () => jwt_exports2,
+  make: () => make,
+  require: () => require2,
+  requireAll: () => requireAll,
+  respond: () => respond,
+  verify: () => verify3
+});
+
+// src/handeia/verify.ts
+var REPLAY_WINDOW_MS2 = 5 * 60 * 1e3;
+var PROBE_HEADER2 = "x-handeia-probe";
+async function verify3(request, secret) {
+  const rawBody = await request.text();
+  const headers = request.headers;
+  const sigHeader = headers.get("x-handeia-signature") ?? "";
+  const tsHeader = headers.get("x-handeia-timestamp") ?? "";
+  const callId = headers.get("x-handeia-call-id") ?? "";
+  if (headers.get(PROBE_HEADER2) === "1") {
+    return { ctx: buildProbeCtx2(callId), raw: rawBody };
+  }
+  if (!sigHeader || !tsHeader) {
+    throw new VAIAError(
+      "Faltan headers de autenticaci\xF3n (X-Handeia-Signature, X-Handeia-Timestamp)",
+      "MISSING_AUTH_HEADERS",
+      401
+    );
+  }
+  const ts = parseInt(tsHeader, 10);
+  if (isNaN(ts) || Math.abs(Date.now() - ts) > REPLAY_WINDOW_MS2) {
+    throw new VAIAError("Timestamp fuera de ventana (\xB15 min)", "TIMESTAMP_OUT_OF_RANGE", 401);
+  }
+  const hexSig = sigHeader.startsWith("sha256=") ? sigHeader.slice(7) : sigHeader;
+  const signedData = `${tsHeader}.${rawBody}`;
+  const valid = await hmacVerify(secret, signedData, hexSig);
+  if (!valid) {
+    throw new VAIAError("Firma HMAC inv\xE1lida", "HMAC_INVALID", 401);
+  }
+  let body;
+  try {
+    body = JSON.parse(rawBody);
+  } catch {
+    throw new VAIAError("Body no es JSON v\xE1lido", "BODY_PARSE_ERROR", 400);
+  }
+  const ctx = parseContext2(body, callId);
+  return { ctx, raw: rawBody };
+}
+function parseContext2(body, fallbackCallId) {
+  if (typeof body !== "object" || body === null) {
+    throw new VAIAError("Body inv\xE1lido", "BODY_INVALID", 400);
+  }
+  const b = body;
+  const user = b["user"] ?? {};
+  const ctx = b["context"] ?? {};
+  return {
+    capability_id: s(b["capability_id"]),
+    call_id: s(b["call_id"], fallbackCallId),
+    user: {
+      id: s(user["id"]),
+      email: sOpt(user["email"]),
+      name: sOpt(user["name"])
+    },
+    permissions: arr2(b["permissions"]),
+    trigger: s(ctx["trigger"], "haia_invoke"),
+    surface: s(ctx["surface"], "data"),
+    query: sOpt(ctx["query"])
+  };
+}
+function buildProbeCtx2(callId) {
+  return {
+    capability_id: "__probe__",
+    call_id: callId || crypto.randomUUID(),
+    user: { id: "__probe__" },
+    permissions: [],
+    trigger: "haia_invoke",
+    surface: "data"
+  };
+}
+function s(v, fallback = "") {
+  return typeof v === "string" ? v : fallback;
+}
+function sOpt(v) {
+  return typeof v === "string" ? v : void 0;
+}
+function arr2(v) {
+  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+function isProbe2(request) {
+  return request.headers.get(PROBE_HEADER2) === "1";
+}
+
+// src/handeia/jwt.ts
+var jwt_exports2 = {};
+__export(jwt_exports2, {
+  fromUrl: () => fromUrl2,
+  sign: () => sign2,
+  verify: () => verify4
+});
+var DEFAULT_EXPIRES_IN2 = 3600;
+async function sign2(input, secret, opts = {}) {
+  const now = Math.floor(Date.now() / 1e3);
+  return jwtSign(
+    {
+      ...input,
+      permissions: input.permissions ?? [],
+      iat: now,
+      exp: now + (opts.expiresIn ?? DEFAULT_EXPIRES_IN2)
+    },
+    secret
+  );
+}
+async function verify4(token, secret) {
+  return jwtVerify(token, secret);
+}
+async function fromUrl2(url, secret) {
+  const u = typeof url === "string" ? new URL(url) : url;
+  const token = u.searchParams.get("handeia_token");
+  if (!token) throw new Error("handeia_token no encontrado en la URL");
+  return verify4(token, secret);
+}
+
+// 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/index.ts
+var gandia = gandia_exports;
+var handeia = handeia_exports;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  VAIAError,
+  defineCapability,
+  gandia,
+  handeia,
+  toManifest
+});
+//# sourceMappingURL=index.cjs.map