@bacano/sdk 1.1.9 → 1.1.12

package/CONTENT_TYPE_MANAGEMENT.md

@@ -0,0 +1,192 @@
+# Gestión de tipos de Content para agentes
+
+`@bacano/sdk/content-management` permite que una herramienta administrativa o
+un agente autorizado consulte, cree y mantenga **tipos y componentes** de
+Bacano Content. No permite administrar entradas, productos, ventas, clientes ni
+ningún otro dato de la empresa.
+
+Este contrato es independiente del cliente público del storefront. Debe usarse
+solo desde un proceso local o servidor confiable; nunca desde el navegador ni
+dentro del bundle del sitio web.
+
+## Activar un acceso temporal
+
+1. En Bacano, abre **Sitios web → Contenido → Tipos** o **Componentes**.
+2. Selecciona **Conectar agente**.
+3. Elige 15, 30 o 60 minutos y genera el acceso.
+4. Copia el token al entorno local del agente.
+
+El token está firmado, pertenece a una sola empresa y solo contiene el alcance
+`content_types:manage`. Cada petición vuelve a comprobar que el usuario que lo
+generó continúa vinculado a la empresa y conserva `websites.manage`. Al vencer
+o perder ese permiso deja de funcionar.
+
+No guardes el token en Git, Figma, Content, logs, variables públicas ni archivos
+que se empaqueten con el storefront.
+
+## Crear el cliente
+
+```ts
+import { createContentManagementClient } from "@bacano/sdk/content-management";
+
+const content = createContentManagementClient({
+  apiUrl: process.env.BACANO_API_URL!,
+  accessToken: process.env.BACANO_CONTENT_ACCESS_TOKEN!,
+});
+
+const context = await content.getContext();
+console.log(context.companyId, context.expiresAt);
+```
+
+El cliente ofrece:
+
+- `getContext()` para confirmar empresa, alcance y vencimiento.
+- `getReferences()` para consultar categorías, subcategorías, listas de opciones
+  y unidades de medida válidas.
+- `listTypes()` y `getType(idOrKey)`.
+- `createType(input)` y `updateType(idOrKey, input)`.
+- `inspectLifecycle(idOrKey, operation)`.
+- `applyLifecycle(idOrKey, operation)`.
+
+## Flujo seguro para un agente
+
+1. Ejecutar `getContext()` y confirmar la empresa con el usuario.
+2. Ejecutar `listTypes()` y `getReferences()` antes de proponer cambios.
+3. Reutilizar tipos, componentes, listas y keys existentes cuando correspondan.
+4. Crear primero los componentes que serán referenciados por otros tipos.
+5. Crear o actualizar en `draft`.
+6. Volver a consultar el tipo y presentar un resumen del resultado.
+7. Activarlo únicamente cuando el usuario haya aprobado la estructura.
+8. Para archivar, restaurar o eliminar, ejecutar primero
+   `inspectLifecycle()` y mostrar dependencias y bloqueos.
+9. Ejecutar `applyLifecycle()` solo después de una confirmación explícita.
+
+`updateType()` reemplaza la definición completa. Antes de usarlo debes obtener
+el tipo con `getType()`, conservar los IDs de campos existentes y enviar todos
+los campos y secciones que deban permanecer. La omisión de un campo se interpreta
+como una eliminación estructural y puede requerir
+`confirmDestructiveChanges: true`.
+
+## Ejemplo: componente y tipo editorial
+
+```ts
+await content.createType({
+  key: "cta_button",
+  name: "Botón de llamada a la acción",
+  kind: "component",
+  status: "draft",
+  fields: [
+    {
+      key: "label",
+      label: "Texto",
+      type: "text",
+      required: true,
+      sortOrder: 1,
+      settings: { isVisible: true, maxLength: 80 },
+    },
+    {
+      key: "url",
+      label: "Enlace",
+      type: "link",
+      required: true,
+      sortOrder: 2,
+      settings: { isVisible: true },
+    },
+  ],
+});
+
+await content.createType({
+  key: "home_hero",
+  name: "Hero del inicio",
+  kind: "entry",
+  status: "draft",
+  usages: ["website_content"],
+  sections: [{ key: "content", title: "Contenido", sortOrder: 1 }],
+  fields: [
+    {
+      key: "title",
+      label: "Título",
+      type: "text",
+      required: true,
+      sortOrder: 1,
+      sectionKey: "content",
+      settings: { isVisible: true, maxLength: 120 },
+    },
+    {
+      key: "actions",
+      label: "Acciones",
+      type: "repeater",
+      required: false,
+      sortOrder: 2,
+      sectionKey: "content",
+      settings: { isVisible: true, minRows: 0, maxRows: 3 },
+      children: [
+        {
+          key: "button",
+          label: "Botón",
+          type: "component",
+          required: true,
+          sortOrder: 1,
+          componentKey: "cta_button",
+          settings: { isVisible: true },
+        },
+      ],
+    },
+  ],
+});
+```
+
+## Ajustes de campos
+
+Todos los campos aceptan `helpText`, `defaultValue`, `isPrivate` e
+`isVisible`. Usa además los ajustes correspondientes al tipo:
+
+| Tipo | Ajustes principales |
+| --- | --- |
+| `text`, `textarea`, `slug` | `minLength`, `maxLength`, `pattern` |
+| `rich_text`, `rich_text_full` | `richTextMode` |
+| `media` | `mediaMultiple`, `acceptedMediaKinds` |
+| `date` | `dateMode`: `date` o `datetime` |
+| `number` | `min`, `max`, `step`, `precision` |
+| `measure` | `measureDimensionCode`, `measureAllowedUnitCodes`, `measurePublicUnitCode` |
+| `select` | `selectSource`, `selectOptions`, `selectSourceKey`, `selectMultiple` |
+| `reference` | `referenceType`, `referenceContentTypeKey`, `referenceMultiple` |
+| `repeater` | `minRows`, `maxRows` y `children` |
+| `component` | `componentKey` |
+
+Para una lista administrable usa `selectSource: "option_list"` y una key
+devuelta por `getReferences().optionLists`. Para medidas usa exclusivamente los
+códigos devueltos por `getReferences().measureDimensions`; no inventes unidades.
+
+Una ficha técnica usa `usages: ["product_specification"]` y al menos un alcance
+en `specificationScopes`. Sus campos técnicos pueden declarar
+`isFilterable: true` únicamente cuando las reglas de Bacano lo permitan. Los
+otros usos editoriales son `website_content` y `product_additional`.
+
+## Ciclo de vida
+
+```ts
+const preview = await content.inspectLifecycle("home_hero", "delete");
+
+if (preview.allowed && userConfirmed) {
+  await content.applyLifecycle("home_hero", "delete");
+}
+```
+
+Nunca ignores `dependencies`, `allowed` o `errors`. Archivar es preferible a
+eliminar cuando existe contenido histórico. El backend aplica las mismas reglas
+de dependencias, keys, componentes, secciones y cambios destructivos que el
+backoffice; el SDK no crea un camino alterno.
+
+## Límites de esta versión
+
+- No crea ni modifica entradas de Content.
+- No carga archivos ni media.
+- No crea listas de opciones.
+- No funciona desde el cliente público del storefront.
+- No acepta GraphQL directo ni credenciales administrativas permanentes.
+
+El resultado esperado del flujo Figma es: el agente propone el blueprint, el
+usuario habilita el acceso temporal, el agente crea o ajusta los tipos y
+componentes aprobados, y el equipo editorial completa las entradas desde
+Bacano.

package/README.md

@@ -21,6 +21,21 @@ React hooks are available from `@bacano/sdk/react` and require `react >= 18`
 as a peer dependency. The core client has no runtime dependencies and works
 without React.
 
+### Gestión de tipos de Content para agentes
+
+Un agente autorizado puede consultar, crear y mantener tipos y componentes con
+el entrypoint administrativo `@bacano/sdk/content-management`. El acceso se
+genera temporalmente desde Bacano, está limitado a una empresa y nunca debe
+incluirse en el storefront:
+
+```ts
+import { createContentManagementClient } from "@bacano/sdk/content-management";
+```
+
+Lee [`CONTENT_TYPE_MANAGEMENT.md`](./CONTENT_TYPE_MANAGEMENT.md) antes de usarlo.
+La guía contiene el flujo de autorización, contratos de campos, referencias,
+cambios destructivos y límites de seguridad.
+
 ### Auditoría del storefront
 
 El SDK incluye la skill oficial `bacano-web`. Instalarla al iniciar un
@@ -44,6 +59,44 @@ descubrimiento. `check` confirma que está vigente. Ninguno ejecuta la auditorí
 modifica el storefront ni despliega; esa revisión comienza únicamente cuando
 el usuario o agente invoca la skill.
 
+### Implementación desde Figma
+
+El SDK también incluye `bacano-figma-web`, la skill oficial para convertir un
+diseño Figma en una web informativa o tienda que conserve el cascarón, Static
+First y contratos públicos de Bacano:
+
+```bash
+pnpm exec bacano-figma-web install --agent all
+pnpm exec bacano-figma-web check
+pnpm exec bacano-figma-web doctor
+```
+
+Después invocarla como `$bacano-figma-web` en Codex, `/bacano-figma-web` en
+Claude Code o solicitar “usar Bacano Figma Web” en Antigravity. La skill guía la
+conexión al MCP remoto oficial, MCP local oficial de Figma Desktop, Desktop
+Bridge comunitario o REST autorizado. Prefiere siempre el MCP oficial y nunca
+guarda ni imprime tokens.
+
+`doctor` comprueba instalación, endpoint local, puertos del bridge y solamente
+la presencia del token REST. El OAuth del MCP remoto debe confirmarse dentro del
+agente con las herramientas de Figma. La extracción se conserva como snapshot
+normalizado. Cuando el equipo de Content y desarrollo trabajan en tiempos
+distintos, la skill genera un blueprint de entrega y permite fixtures locales
+con el mismo contrato de los componentes. Las entradas reales continúan
+creándose desde Bacano. Con autorización temporal, la skill puede crear o
+ajustar tipos y componentes mediante el entrypoint administrativo oficial; un
+fixture activo bloquea la aprobación de producción.
+
+El snapshot puede validarse con:
+
+```bash
+pnpm exec bacano-figma-web validate-snapshot .bacano/designs/<proyecto>/manifest.json
+```
+
+Las instrucciones completas viajan dentro de
+`skills/bacano-figma-web/references/`; no es necesario copiar documentación ni
+crear integraciones particulares en cada storefront.
+
 Every storefront must follow [`STOREFRONT_MARKETING.md`](./STOREFRONT_MARKETING.md)
 when instrumenting analytics, advertising signals, contact actions, ecommerce
 events, attribution, or preview behavior. It is the canonical implementation

package/content-management.cjs

@@ -0,0 +1,135 @@
+"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);
+
+// libs/sdk/src/content-management.ts
+var content_management_exports = {};
+__export(content_management_exports, {
+  ContentManagementError: () => ContentManagementError,
+  createContentManagementClient: () => createContentManagementClient
+});
+module.exports = __toCommonJS(content_management_exports);
+var ContentManagementError = class extends Error {
+  code;
+  status;
+  details;
+  constructor(input) {
+    super(input.message);
+    this.name = "ContentManagementError";
+    this.code = input.code ?? "CONTENT_MANAGEMENT_ERROR";
+    this.status = input.status;
+    this.details = input.details;
+  }
+};
+function normalizeApiUrl(apiUrl) {
+  const normalized = apiUrl.trim().replace(/\/+$/, "");
+  if (!normalized) {
+    throw new ContentManagementError({
+      message: "apiUrl is required.",
+      code: "CONTENT_MANAGEMENT_CONFIG_INVALID",
+      status: 0
+    });
+  }
+  return normalized;
+}
+function encodeIdentifier(identifier) {
+  const normalized = identifier.trim();
+  if (!normalized) {
+    throw new ContentManagementError({
+      message: "A content type id or key is required.",
+      code: "CONTENT_TYPE_IDENTIFIER_INVALID",
+      status: 0
+    });
+  }
+  return encodeURIComponent(normalized);
+}
+function createContentManagementClient(config) {
+  const apiUrl = normalizeApiUrl(config.apiUrl);
+  const fetchImplementation = config.fetch ?? globalThis.fetch;
+  if (!fetchImplementation) {
+    throw new ContentManagementError({
+      message: "A fetch implementation is required.",
+      code: "CONTENT_MANAGEMENT_CONFIG_INVALID",
+      status: 0
+    });
+  }
+  const getAccessToken = async () => {
+    const token = typeof config.accessToken === "function" ? await config.accessToken() : config.accessToken;
+    const normalized = token.trim();
+    if (!normalized) {
+      throw new ContentManagementError({
+        message: "A temporary content management access token is required.",
+        code: "CONTENT_MANAGEMENT_ACCESS_REQUIRED",
+        status: 0
+      });
+    }
+    return normalized;
+  };
+  const request = async (path, init) => {
+    const response = await fetchImplementation(
+      `${apiUrl}/api/v1/content-management${path}`,
+      {
+        ...init,
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${await getAccessToken()}`,
+          ...init?.body ? { "Content-Type": "application/json" } : {},
+          ...init?.headers
+        }
+      }
+    );
+    let payload = null;
+    try {
+      payload = await response.json();
+    } catch {
+    }
+    if (!response.ok || !payload || payload.success !== true) {
+      const error = payload && "error" in payload ? payload.error : null;
+      throw new ContentManagementError({
+        message: error?.message ?? `Content management request failed with HTTP ${response.status}.`,
+        code: error?.code,
+        status: response.status,
+        details: error?.details
+      });
+    }
+    return payload.data;
+  };
+  const lifecycle = (identifier, operation, dryRun) => request(
+    `/types/${encodeIdentifier(identifier)}/lifecycle`,
+    {
+      method: "POST",
+      body: JSON.stringify({ operation, dryRun })
+    }
+  );
+  return {
+    getContext: () => request("/context"),
+    getReferences: () => request("/references"),
+    listTypes: () => request("/types"),
+    getType: (identifier) => request(`/types/${encodeIdentifier(identifier)}`),
+    createType: (input) => request("/types", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateType: (identifier, input) => request(`/types/${encodeIdentifier(identifier)}`, {
+      method: "PUT",
+      body: JSON.stringify(input)
+    }),
+    inspectLifecycle: (identifier, operation) => lifecycle(identifier, operation, true),
+    applyLifecycle: (identifier, operation) => lifecycle(identifier, operation, false)
+  };
+}

package/content-management.d.ts

@@ -0,0 +1,144 @@
+export type ContentManagementTypeKind = "entry" | "component";
+export type ContentManagementTypeStatus = "draft" | "active" | "archived";
+export type ContentManagementTypeUsage = "website_content" | "product_additional" | "product_specification";
+export type ContentManagementFieldType = "boolean" | "component" | "date" | "link" | "measure" | "media" | "number" | "reference" | "repeater" | "rich_text" | "rich_text_full" | "select" | "slug" | "text" | "textarea";
+export interface ContentManagementChildFieldInput {
+    id?: string | null;
+    key: string;
+    label: string;
+    type: ContentManagementFieldType;
+    required?: boolean;
+    sortOrder: number;
+    settings?: Record<string, unknown>;
+    componentKey?: string | null;
+}
+export interface ContentManagementFieldInput extends ContentManagementChildFieldInput {
+    sectionKey?: string | null;
+    children?: ContentManagementChildFieldInput[];
+}
+export interface ContentManagementTypeInput {
+    key: string;
+    name: string;
+    description?: string;
+    kind: ContentManagementTypeKind;
+    status?: "draft" | "active";
+    settings?: Record<string, unknown>;
+    usages?: ContentManagementTypeUsage[];
+    sections?: Array<{
+        key: string;
+        title: string;
+        description?: string;
+        sortOrder: number;
+    }>;
+    specificationScopes?: Array<{
+        category?: string | null;
+        subcategoryId?: string | null;
+    }>;
+    deletedPaths?: string[];
+    confirmDestructiveChanges?: boolean;
+    fields?: ContentManagementFieldInput[];
+}
+export interface ContentManagementType extends Omit<ContentManagementTypeInput, "status"> {
+    id: string;
+    companyId: string;
+    description: string;
+    status: ContentManagementTypeStatus;
+    settings: Record<string, unknown>;
+    usages: ContentManagementTypeUsage[];
+    sections: Array<{
+        id: string;
+        key: string;
+        title: string;
+        description: string;
+        sortOrder: number;
+    }>;
+    specificationScopes: Array<{
+        id: string;
+        category: string | null;
+        subcategoryId: string | null;
+    }>;
+    fields: ContentManagementFieldInput[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ContentManagementContext {
+    companyId: string;
+    scope: "content_types:manage";
+    expiresAt: string;
+}
+export interface ContentManagementReferences {
+    categories: Array<{
+        code: string;
+        name: string;
+        subcategories: Array<{
+            id: string;
+            name: string;
+        }>;
+    }>;
+    optionLists: Array<{
+        key: string;
+        name: string;
+        isExtensible: boolean;
+        options: Array<{
+            value: string;
+            label: string;
+        }>;
+    }>;
+    measureDimensions: Array<{
+        code: string;
+        name: string;
+        canonicalUnitCode: string;
+        units: Array<{
+            code: string;
+            name: string;
+            symbol: string;
+        }>;
+    }>;
+}
+export type ContentManagementLifecycleOperation = "archive" | "restore" | "delete";
+export interface ContentManagementLifecycleResult {
+    success: boolean;
+    allowed: boolean;
+    applied: boolean;
+    entity_id: string | null;
+    entity_type: "type" | "component" | null;
+    operation: ContentManagementLifecycleOperation | null;
+    name: string | null;
+    status: string | null;
+    dependencies: Array<{
+        code: string;
+        label: string;
+        count: number;
+        blocking: boolean;
+    }>;
+    message: string | null;
+    errors: string[];
+}
+export type ContentManagementAccessTokenProvider = () => string | Promise<string>;
+export interface ContentManagementClientConfig {
+    apiUrl: string;
+    accessToken: string | ContentManagementAccessTokenProvider;
+    fetch?: typeof fetch;
+}
+export declare class ContentManagementError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details: unknown;
+    constructor(input: {
+        message: string;
+        code?: string;
+        status: number;
+        details?: unknown;
+    });
+}
+export interface ContentManagementClient {
+    getContext(): Promise<ContentManagementContext>;
+    getReferences(): Promise<ContentManagementReferences>;
+    listTypes(): Promise<ContentManagementType[]>;
+    getType(identifier: string): Promise<ContentManagementType>;
+    createType(input: ContentManagementTypeInput): Promise<ContentManagementType>;
+    updateType(identifier: string, input: ContentManagementTypeInput): Promise<ContentManagementType>;
+    inspectLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
+    applyLifecycle(identifier: string, operation: ContentManagementLifecycleOperation): Promise<ContentManagementLifecycleResult>;
+}
+export declare function createContentManagementClient(config: ContentManagementClientConfig): ContentManagementClient;

package/content-management.js

@@ -0,0 +1,114 @@
+// libs/sdk/src/content-management.ts
+var ContentManagementError = class extends Error {
+  code;
+  status;
+  details;
+  constructor(input) {
+    super(input.message);
+    this.name = "ContentManagementError";
+    this.code = input.code ?? "CONTENT_MANAGEMENT_ERROR";
+    this.status = input.status;
+    this.details = input.details;
+  }
+};
+function normalizeApiUrl(apiUrl) {
+  const normalized = apiUrl.trim().replace(/\/+$/, "");
+  if (!normalized) {
+    throw new ContentManagementError({
+      message: "apiUrl is required.",
+      code: "CONTENT_MANAGEMENT_CONFIG_INVALID",
+      status: 0
+    });
+  }
+  return normalized;
+}
+function encodeIdentifier(identifier) {
+  const normalized = identifier.trim();
+  if (!normalized) {
+    throw new ContentManagementError({
+      message: "A content type id or key is required.",
+      code: "CONTENT_TYPE_IDENTIFIER_INVALID",
+      status: 0
+    });
+  }
+  return encodeURIComponent(normalized);
+}
+function createContentManagementClient(config) {
+  const apiUrl = normalizeApiUrl(config.apiUrl);
+  const fetchImplementation = config.fetch ?? globalThis.fetch;
+  if (!fetchImplementation) {
+    throw new ContentManagementError({
+      message: "A fetch implementation is required.",
+      code: "CONTENT_MANAGEMENT_CONFIG_INVALID",
+      status: 0
+    });
+  }
+  const getAccessToken = async () => {
+    const token = typeof config.accessToken === "function" ? await config.accessToken() : config.accessToken;
+    const normalized = token.trim();
+    if (!normalized) {
+      throw new ContentManagementError({
+        message: "A temporary content management access token is required.",
+        code: "CONTENT_MANAGEMENT_ACCESS_REQUIRED",
+        status: 0
+      });
+    }
+    return normalized;
+  };
+  const request = async (path, init) => {
+    const response = await fetchImplementation(
+      `${apiUrl}/api/v1/content-management${path}`,
+      {
+        ...init,
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${await getAccessToken()}`,
+          ...init?.body ? { "Content-Type": "application/json" } : {},
+          ...init?.headers
+        }
+      }
+    );
+    let payload = null;
+    try {
+      payload = await response.json();
+    } catch {
+    }
+    if (!response.ok || !payload || payload.success !== true) {
+      const error = payload && "error" in payload ? payload.error : null;
+      throw new ContentManagementError({
+        message: error?.message ?? `Content management request failed with HTTP ${response.status}.`,
+        code: error?.code,
+        status: response.status,
+        details: error?.details
+      });
+    }
+    return payload.data;
+  };
+  const lifecycle = (identifier, operation, dryRun) => request(
+    `/types/${encodeIdentifier(identifier)}/lifecycle`,
+    {
+      method: "POST",
+      body: JSON.stringify({ operation, dryRun })
+    }
+  );
+  return {
+    getContext: () => request("/context"),
+    getReferences: () => request("/references"),
+    listTypes: () => request("/types"),
+    getType: (identifier) => request(`/types/${encodeIdentifier(identifier)}`),
+    createType: (input) => request("/types", {
+      method: "POST",
+      body: JSON.stringify(input)
+    }),
+    updateType: (identifier, input) => request(`/types/${encodeIdentifier(identifier)}`, {
+      method: "PUT",
+      body: JSON.stringify(input)
+    }),
+    inspectLifecycle: (identifier, operation) => lifecycle(identifier, operation, true),
+    applyLifecycle: (identifier, operation) => lifecycle(identifier, operation, false)
+  };
+}
+export {
+  ContentManagementError,
+  createContentManagementClient
+};

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@bacano/sdk",
-  "version": "1.1.9",
+  "version": "1.1.12",
   "description": "TypeScript SDK for building websites on the Bacano ERP",
   "main": "./index.cjs",
   "module": "./index.js",
   "types": "./index.d.ts",
   "bin": {
+    "bacano-figma-web": "./skills/bacano-figma-web/scripts/cli.mjs",
     "bacano-web": "./skills/bacano-web/scripts/cli.mjs"
   },
   "scripts": {
@@ -22,6 +23,11 @@
       "import": "./graphql.js",
       "require": "./graphql.cjs"
     },
+    "./content-management": {
+      "types": "./content-management.d.ts",
+      "import": "./content-management.js",
+      "require": "./content-management.cjs"
+    },
     "./react": {
       "types": "./react.d.ts",
       "import": "./react.js",