@lunnoa/client 1.0.0 → 1.1.0

package/README.md

@@ -266,7 +266,13 @@ Re-run codegen whenever entity types, workflows, or agents change on the deploym
 
 ## Define, run, and CLI deploy
 
-Author local definitions with `defineWorkflow` / `defineAgent`, run linear chains with `lunnoa.runs.start`, and upsert into a project with the CLI (prefer CLI over calling upsert from app code):
+Author local definitions with `defineWorkflow` / `defineAgent` / `defineEntityType`, run linear chains with `lunnoa.runs.start`, and upsert with the CLI (prefer CLI over calling upsert from app code). Entity types are workspace-scoped (no `--project-id`); instance writes reject unknown attribute keys unless `allowUnknownAttributes` is true — use the reserved `extensions` object for flexible bags:
+
+```bash
+npx @lunnoa/client entity-types deploy ./human.ts --url https://lunnoa.example --api-key lna_...
+```
+
+Workflows and agents:
 
 ```bash
 npx @lunnoa/client workflows deploy ./workflows/sync-orders.ts \

package/dist/cli.js

@@ -537,7 +537,8 @@ var DEFINE_KINDS = {
   aiConnection: "aiConnection",
   action: "action",
   workflow: "workflow",
-  agent: "agent"
+  agent: "agent",
+  entityType: "entityType"
 };
 function resolveActionAppId(action) {
   if (action.appId?.trim()) {
@@ -1016,6 +1017,21 @@ var EntitiesResource = class {
 };
 
 // src/resources/entity-types.ts
+function entityTypeDefinitionToUpsert(def) {
+  return {
+    slug: def.slug,
+    name: def.name,
+    namePlural: def.namePlural,
+    description: def.description,
+    icon: def.icon,
+    color: def.color,
+    attributeSchema: def.attributeSchema,
+    stateSchema: def.stateSchema,
+    isEnabled: def.isEnabled,
+    allowUnknownAttributes: def.allowUnknownAttributes ?? false,
+    managedByCode: true
+  };
+}
 var EntityTypesResource = class {
   constructor(http) {
     this.http = http;
@@ -1046,6 +1062,19 @@ var EntityTypesResource = class {
       query: { expansion: serializeCsv(options.expansion) }
     });
   }
+  /**
+   * Creates or updates an entity type by workspace-scoped slug.
+   * Prefer the CLI (`npx @lunnoa/client entity-types deploy`) for happy-path deploy.
+   */
+  upsertBySlug(definition) {
+    const payload = "kind" in definition && definition.kind === "entityType" ? entityTypeDefinitionToUpsert(definition) : definition;
+    return this.http.post("/api/object-types/upsert", {
+      body: payload,
+      query: {
+        expansion: "attributeSchema,stateSchema,description"
+      }
+    });
+  }
 };
 
 // src/resources/approvals.ts
@@ -2021,6 +2050,14 @@ var LunnoaClient = class {
 };
 
 // src/cli/generate.ts
+function computeDeploymentSchemaFingerprint(entityTypes) {
+  const parts = [...entityTypes].map((type) => {
+    const revision = type.schemaRevision ?? 1;
+    const allowUnknown = type.allowUnknownAttributes ?? false;
+    return `${type.slug}:${revision}:${allowUnknown ? 1 : 0}`;
+  }).sort();
+  return parts.join("|") || "empty";
+}
 function toCamelCase(input) {
   const parts = input.replace(/[^a-zA-Z0-9]+/g, " ").trim().split(/\s+/);
   if (parts.length === 0 || parts[0] === "") {
@@ -2140,6 +2177,9 @@ function isFieldRequired(field) {
 }
 function generateDeploymentModule(definitions) {
   const chunks = [];
+  const schemaFingerprint = computeDeploymentSchemaFingerprint(
+    definitions.entityTypes
+  );
   chunks.push(
     `/* eslint-disable */
 /**
@@ -2148,8 +2188,23 @@ function generateDeploymentModule(definitions) {
  * Generated by \`npx @lunnoa/client codegen\` \u2014 do not edit by hand.
  * Re-run codegen whenever entity types, workflows, or agents change on
  * the deployment.
+ *
+ * Schema fingerprint: ${schemaFingerprint}
  */
 import type { LunnoaClient, Entity, Execution, ExecuteWorkflowResult, PaginatedEntities, Task, AgentChatStream, WaitUntilFinishedOptions, ListEntitiesOptions, UIMessage } from '@lunnoa/client';
+
+/** Fingerprint of entity-type schemas at codegen time (slug:revision:allowUnknown). */
+export const DEPLOYMENT_SCHEMA_FINGERPRINT = ${JSON.stringify(schemaFingerprint)};
+
+/** Per-type schemaRevision values captured at codegen time. */
+export const ENTITY_TYPE_SCHEMA_REVISIONS = ${JSON.stringify(
+      Object.fromEntries(
+        definitions.entityTypes.map((type) => [
+          type.slug,
+          type.schemaRevision ?? 1
+        ])
+      )
+    )} as const;
 `
   );
   chunks.push(GENERATED_RUNTIME_HELPERS);
@@ -2438,6 +2493,21 @@ function pickAgentDefinition(mod) {
     "No defineAgent() export found. Export the definition as default or `agent`."
   );
 }
+function pickEntityTypeDefinition(mod) {
+  const candidates = [
+    mod.default,
+    mod.entityType,
+    ...Object.values(mod)
+  ];
+  for (const value of candidates) {
+    if (value && typeof value === "object" && value.kind === DEFINE_KINDS.entityType) {
+      return value;
+    }
+  }
+  throw new Error(
+    "No defineEntityType() export found. Export the definition as default or `entityType`."
+  );
+}
 async function loadOptionalConfig() {
   const candidates = [
     "lunnoa.config.ts",
@@ -2470,7 +2540,7 @@ async function loadOptionalConfig() {
 function parseArgs(argv) {
   const args = { command: argv[0], out: "./src/lunnoa" };
   let i = 1;
-  if (args.command === "workflows" || args.command === "agents") {
+  if (args.command === "workflows" || args.command === "agents" || args.command === "entity-types") {
     args.subcommand = argv[1];
     i = 2;
     if (argv[2] && !argv[2].startsWith("--")) {
@@ -2516,16 +2586,20 @@ var USAGE = `Usage:
   npx @lunnoa/client codegen --url <deployment-url> --api-key <lna_key> [--out <dir>]
   npx @lunnoa/client workflows deploy <path> --url <url> --api-key <key> --project-id <uuid>
   npx @lunnoa/client agents deploy <path> --url <url> --api-key <key> --project-id <uuid>
+  npx @lunnoa/client entity-types deploy <path> --url <url> --api-key <key>
 
 Options:
   --url           Base URL of the Lunnoa Automate deployment
   --api-key       Machine API key (lna_...)
   --access-token  User JWT as an alternative to --api-key
-  --project-id    Project UUID (required for deploy)
+  --project-id    Project UUID (required for workflow/agent deploy)
   --out           Output directory for lunnoa.generated.ts (codegen; default: ./src/lunnoa)
 
 Environment: LUNNOA_URL, LUNNOA_API_KEY, LUNNOA_PROJECT_ID
 Optional config file: lunnoa.config.ts | .mjs | .js | .json
+
+Entity-type deploy is workspace-scoped (no --project-id). Unknown instance
+attributes are rejected unless allowUnknownAttributes is true; use extensions.
 `;
 async function bindClient(args) {
   const fileConfig = await loadOptionalConfig();
@@ -2636,6 +2710,22 @@ async function deployAgent(args) {
   const result = await client.agents.upsertBySlug(projectId, payload);
   console.log(`Upserted agent ${result.id} (${payload.slug})`);
 }
+async function deployEntityType(args) {
+  if (!args.path) {
+    throw new Error(
+      "Missing definition path. Example: entity-types deploy ./entity-type.ts"
+    );
+  }
+  const { client } = await bindClient(args);
+  const mod = await loadDefinitionModule(args.path);
+  const def = pickEntityTypeDefinition(mod);
+  const payload = entityTypeDefinitionToUpsert(def);
+  console.log(`Deploying entity type slug="${payload.slug}" ...`);
+  const result = await client.entityTypes.upsertBySlug(payload);
+  console.log(
+    `Upserted entity type ${result.id} (${payload.slug})` + (typeof result.schemaRevision === "number" ? ` schemaRevision=${result.schemaRevision}` : "")
+  );
+}
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (!args.command || args.command === "--help" || args.command === "help") {
@@ -2654,6 +2744,10 @@ async function main() {
     await deployAgent(args);
     return;
   }
+  if (args.command === "entity-types" && args.subcommand === "deploy") {
+    await deployEntityType(args);
+    return;
+  }
   console.error(`Unknown command: ${args.command} ${args.subcommand ?? ""}
 `);
   console.log(USAGE);

package/dist/index.cjs

@@ -533,7 +533,8 @@ var DEFINE_KINDS = {
   aiConnection: "aiConnection",
   action: "action",
   workflow: "workflow",
-  agent: "agent"
+  agent: "agent",
+  entityType: "entityType"
 };
 function defineConnection(config = {}) {
   return { kind: DEFINE_KINDS.connection, ...config };
@@ -568,6 +569,19 @@ function defineAgent(config) {
   }
   return { kind: DEFINE_KINDS.agent, ...config };
 }
+function defineEntityType(config) {
+  if (!config.slug?.trim()) {
+    throw new Error("defineEntityType requires slug");
+  }
+  if (!config.attributeSchema || typeof config.attributeSchema !== "object" || Array.isArray(config.attributeSchema)) {
+    throw new Error("defineEntityType requires attributeSchema object");
+  }
+  return {
+    kind: DEFINE_KINDS.entityType,
+    allowUnknownAttributes: false,
+    ...config
+  };
+}
 function resolveActionAppId(action) {
   if (action.appId?.trim()) {
     return action.appId.trim();
@@ -1045,6 +1059,21 @@ var EntitiesResource = class {
 };
 
 // src/resources/entity-types.ts
+function entityTypeDefinitionToUpsert(def) {
+  return {
+    slug: def.slug,
+    name: def.name,
+    namePlural: def.namePlural,
+    description: def.description,
+    icon: def.icon,
+    color: def.color,
+    attributeSchema: def.attributeSchema,
+    stateSchema: def.stateSchema,
+    isEnabled: def.isEnabled,
+    allowUnknownAttributes: def.allowUnknownAttributes ?? false,
+    managedByCode: true
+  };
+}
 var EntityTypesResource = class {
   constructor(http) {
     this.http = http;
@@ -1075,6 +1104,19 @@ var EntityTypesResource = class {
       query: { expansion: serializeCsv(options.expansion) }
     });
   }
+  /**
+   * Creates or updates an entity type by workspace-scoped slug.
+   * Prefer the CLI (`npx @lunnoa/client entity-types deploy`) for happy-path deploy.
+   */
+  upsertBySlug(definition) {
+    const payload = "kind" in definition && definition.kind === "entityType" ? entityTypeDefinitionToUpsert(definition) : definition;
+    return this.http.post("/api/object-types/upsert", {
+      body: payload,
+      query: {
+        expansion: "attributeSchema,stateSchema,description"
+      }
+    });
+  }
 };
 
 // src/resources/approvals.ts
@@ -2158,7 +2200,9 @@ exports.defineAction = defineAction;
 exports.defineAgent = defineAgent;
 exports.defineAiConnection = defineAiConnection;
 exports.defineConnection = defineConnection;
+exports.defineEntityType = defineEntityType;
 exports.defineWorkflow = defineWorkflow;
+exports.entityTypeDefinitionToUpsert = entityTypeDefinitionToUpsert;
 exports.isBrowserEnvironment = isBrowserEnvironment;
 exports.isLoginRequires2FA = isLoginRequires2FA;
 exports.iterateOffset = iterateOffset;