@flexacms/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Mercedes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @flexacms/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generate TypeScript types from the content models of your [Flexa](https://github.com/flexacms) workspace.
+
+```bash
+FLEXA_URL=https://cms.example.com FLEXA_API_KEY=flx_... npx @flexacms/cli generate --out src/flexa.d.ts
+```
+
+The file contains one `<Entity>Values` interface per content model and a `FlexaSchema` map. Pass it to any Flexa SDK:
+
+```ts
+import type { FlexaSchema } from './flexa';
+
+const flexa = createClient<FlexaSchema>({ url, apiKey });
+```
+
+Field types map to their API values: translatable fields become `Localized<T>`, selects become unions of their options, repeaters become arrays of typed items, relationships become ids, and optional fields are `| null`. Run the command again whenever a content model changes.
+
+| Option  | Default                         |
+| ------- | ------------------------------- |
+| `--url` | `$FLEXA_URL`                    |
+| `--key` | `$FLEXA_API_KEY` (Read ability) |
+| `--out` | `flexa.d.ts`                    |

package/dist/cli.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+import { parseArgs } from "util";
+import { createClient, isFlexaError } from "@flexacms/client";
+
+// src/generate.ts
+function generateTypes(schemas) {
+  const lines = [
+    "// Generated by @flexacms/cli. Do not edit by hand: run `npx @flexacms/cli generate` again instead.",
+    "import type { Localized } from '@flexacms/client';",
+    ""
+  ];
+  const names = /* @__PURE__ */ new Map();
+  for (const schema of schemas) {
+    names.set(
+      schema.slug,
+      uniqueName(`${pascalCase(schema.slug)}Values`, names)
+    );
+  }
+  for (const schema of schemas) {
+    lines.push(
+      `/** ${schema.name}${schema.description ? ` \u2014 ${schema.description}` : ""} */`
+    );
+    lines.push(`export interface ${names.get(schema.slug)} {`);
+    for (const field of schema.fields.filter(
+      (item) => item.is_active !== false
+    )) {
+      const type = fieldType(field);
+      const doc = [field.label, field.description].filter(Boolean).join(" \u2014 ");
+      lines.push(`    /** ${escapeComment(doc)} */`);
+      lines.push(
+        `    ${propertyName(field.key)}: ${field.is_required ? type : `${wrap(type)} | null`};`
+      );
+    }
+    lines.push("}", "");
+  }
+  lines.push("export interface FlexaSchema {");
+  for (const schema of schemas) {
+    lines.push(
+      `    ${propertyName(schema.slug)}: ${names.get(schema.slug)};`
+    );
+  }
+  lines.push("}", "");
+  return lines.join("\n");
+}
+function fieldType(field) {
+  const base = baseType(field);
+  return field.translatable ? `Localized<${base}>` : base;
+}
+function baseType(field) {
+  switch (field.type) {
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "select":
+      return optionsUnion(field.options);
+    case "multiselect":
+      return `${wrap(optionsUnion(field.options))}[]`;
+    case "tags":
+      return "string[]";
+    case "image":
+    case "file":
+      return field.multiple ? "string[]" : "string";
+    case "relationship":
+      return field.multiple ? "number[]" : "number";
+    case "json":
+      return "unknown";
+    case "address":
+      return `{ ${(field.address_parts ?? [
+        "street",
+        "city",
+        "state",
+        "postal_code",
+        "country"
+      ]).map((part) => `${propertyName(part)}?: string | null`).join("; ")} }`;
+    case "repeater":
+      return `Array<${repeaterItem(field.repeater_subfields)}>`;
+    default:
+      return "string";
+  }
+}
+function repeaterItem(subfields) {
+  if (!subfields || subfields.length === 0) {
+    return "Record<string, unknown>";
+  }
+  const properties = subfields.map((subfield) => {
+    const type = baseType({
+      type: subfield.type,
+      options: isOptionMap(subfield.options) ? subfield.options : null,
+      multiple: Boolean(
+        subfield.settings?.multiple ?? subfield.multiple
+      ),
+      address_parts: void 0,
+      repeater_subfields: null
+    });
+    return subfield.is_required === true ? `${propertyName(subfield.key)}: ${type}` : `${propertyName(subfield.key)}?: ${wrap(type)} | null`;
+  });
+  return `{ ${properties.join("; ")} }`;
+}
+function optionsUnion(options) {
+  const keys = isOptionMap(options) ? Object.keys(options) : [];
+  return keys.length > 0 ? keys.map((key) => JSON.stringify(key)).join(" | ") : "string";
+}
+function isOptionMap(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function wrap(type) {
+  let depth = 0;
+  for (let index = 0; index < type.length; index++) {
+    const character = type[index];
+    if (character === "(" || character === "[" || character === "{" || character === "<") {
+      depth++;
+    } else if (character === ")" || character === "]" || character === "}" || character === ">") {
+      depth--;
+    } else if (depth === 0 && type.startsWith(" | ", index)) {
+      return `(${type})`;
+    }
+  }
+  return type;
+}
+function pascalCase(value) {
+  const name = value.split(/[^A-Za-z0-9]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+  return /^[0-9]/.test(name) || name === "" ? `Entity${name}` : name;
+}
+function uniqueName(name, taken) {
+  const used = new Set(taken.values());
+  let candidate = name;
+  let suffix = 2;
+  while (used.has(candidate)) {
+    candidate = `${name}${suffix++}`;
+  }
+  return candidate;
+}
+function propertyName(key) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+}
+function escapeComment(text) {
+  return text.replace(/\*\//g, "*\\/").replace(/\s+/g, " ").trim();
+}
+
+// src/cli.ts
+var HELP = `Usage: flexa generate [options]
+
+Generate TypeScript types for your Flexa workspace's content models.
+
+Options:
+  --url <url>      Flexa URL (default: $FLEXA_URL)
+  --key <key>      API key with the Read ability (default: $FLEXA_API_KEY)
+  --out <file>     Output file (default: flexa.d.ts)
+  -h, --help       Show this help
+`;
+async function main(argv) {
+  const { positionals, values } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      url: { type: "string" },
+      key: { type: "string" },
+      out: { type: "string", default: "flexa.d.ts" },
+      help: { type: "boolean", short: "h" }
+    }
+  });
+  if (values.help || positionals[0] !== "generate") {
+    process.stdout.write(HELP);
+    return values.help ? 0 : 1;
+  }
+  const url = values.url ?? process.env.FLEXA_URL;
+  const apiKey = values.key ?? process.env.FLEXA_API_KEY;
+  if (!url || !apiKey) {
+    process.stderr.write(
+      "Missing --url/--key (or the FLEXA_URL and FLEXA_API_KEY environment variables).\n"
+    );
+    return 1;
+  }
+  const client = createClient({ url, apiKey });
+  const entities = await client.entities();
+  const schemas = await Promise.all(
+    entities.map((entity) => client.entity(entity.slug).schema())
+  );
+  const output = resolve(process.cwd(), values.out ?? "flexa.d.ts");
+  await mkdir(dirname(output), { recursive: true });
+  await writeFile(output, generateTypes(schemas));
+  process.stdout.write(
+    `Generated types for ${schemas.length} content model(s) in ${output}
+`
+  );
+  return 0;
+}
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (error) => {
+    process.stderr.write(
+      `${isFlexaError(error) ? `Flexa API error (${error.status}): ` : ""}${error instanceof Error ? error.message : String(error)}
+`
+    );
+    process.exit(1);
+  }
+);

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { EntitySchema } from '@flexacms/client';
+
+/**
+ * Turn entity schemas into TypeScript declarations: one `<Entity>Values`
+ * interface per entity and a `FlexaSchema` map for `createClient<FlexaSchema>()`.
+ */
+declare function generateTypes(schemas: EntitySchema[]): string;
+
+export { generateTypes };

package/dist/index.js

@@ -0,0 +1,138 @@
+// src/generate.ts
+function generateTypes(schemas) {
+  const lines = [
+    "// Generated by @flexacms/cli. Do not edit by hand: run `npx @flexacms/cli generate` again instead.",
+    "import type { Localized } from '@flexacms/client';",
+    ""
+  ];
+  const names = /* @__PURE__ */ new Map();
+  for (const schema of schemas) {
+    names.set(
+      schema.slug,
+      uniqueName(`${pascalCase(schema.slug)}Values`, names)
+    );
+  }
+  for (const schema of schemas) {
+    lines.push(
+      `/** ${schema.name}${schema.description ? ` \u2014 ${schema.description}` : ""} */`
+    );
+    lines.push(`export interface ${names.get(schema.slug)} {`);
+    for (const field of schema.fields.filter(
+      (item) => item.is_active !== false
+    )) {
+      const type = fieldType(field);
+      const doc = [field.label, field.description].filter(Boolean).join(" \u2014 ");
+      lines.push(`    /** ${escapeComment(doc)} */`);
+      lines.push(
+        `    ${propertyName(field.key)}: ${field.is_required ? type : `${wrap(type)} | null`};`
+      );
+    }
+    lines.push("}", "");
+  }
+  lines.push("export interface FlexaSchema {");
+  for (const schema of schemas) {
+    lines.push(
+      `    ${propertyName(schema.slug)}: ${names.get(schema.slug)};`
+    );
+  }
+  lines.push("}", "");
+  return lines.join("\n");
+}
+function fieldType(field) {
+  const base = baseType(field);
+  return field.translatable ? `Localized<${base}>` : base;
+}
+function baseType(field) {
+  switch (field.type) {
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "select":
+      return optionsUnion(field.options);
+    case "multiselect":
+      return `${wrap(optionsUnion(field.options))}[]`;
+    case "tags":
+      return "string[]";
+    case "image":
+    case "file":
+      return field.multiple ? "string[]" : "string";
+    case "relationship":
+      return field.multiple ? "number[]" : "number";
+    case "json":
+      return "unknown";
+    case "address":
+      return `{ ${(field.address_parts ?? [
+        "street",
+        "city",
+        "state",
+        "postal_code",
+        "country"
+      ]).map((part) => `${propertyName(part)}?: string | null`).join("; ")} }`;
+    case "repeater":
+      return `Array<${repeaterItem(field.repeater_subfields)}>`;
+    default:
+      return "string";
+  }
+}
+function repeaterItem(subfields) {
+  if (!subfields || subfields.length === 0) {
+    return "Record<string, unknown>";
+  }
+  const properties = subfields.map((subfield) => {
+    const type = baseType({
+      type: subfield.type,
+      options: isOptionMap(subfield.options) ? subfield.options : null,
+      multiple: Boolean(
+        subfield.settings?.multiple ?? subfield.multiple
+      ),
+      address_parts: void 0,
+      repeater_subfields: null
+    });
+    return subfield.is_required === true ? `${propertyName(subfield.key)}: ${type}` : `${propertyName(subfield.key)}?: ${wrap(type)} | null`;
+  });
+  return `{ ${properties.join("; ")} }`;
+}
+function optionsUnion(options) {
+  const keys = isOptionMap(options) ? Object.keys(options) : [];
+  return keys.length > 0 ? keys.map((key) => JSON.stringify(key)).join(" | ") : "string";
+}
+function isOptionMap(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function wrap(type) {
+  let depth = 0;
+  for (let index = 0; index < type.length; index++) {
+    const character = type[index];
+    if (character === "(" || character === "[" || character === "{" || character === "<") {
+      depth++;
+    } else if (character === ")" || character === "]" || character === "}" || character === ">") {
+      depth--;
+    } else if (depth === 0 && type.startsWith(" | ", index)) {
+      return `(${type})`;
+    }
+  }
+  return type;
+}
+function pascalCase(value) {
+  const name = value.split(/[^A-Za-z0-9]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+  return /^[0-9]/.test(name) || name === "" ? `Entity${name}` : name;
+}
+function uniqueName(name, taken) {
+  const used = new Set(taken.values());
+  let candidate = name;
+  let suffix = 2;
+  while (used.has(candidate)) {
+    candidate = `${name}${suffix++}`;
+  }
+  return candidate;
+}
+function propertyName(key) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+}
+function escapeComment(text) {
+  return text.replace(/\*\//g, "*\\/").replace(/\s+/g, " ").trim();
+}
+export {
+  generateTypes
+};

package/package.json

@@ -1,6 +1,50 @@
 {
-  "name": "@flexacms/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@flexacms/cli",
+    "version": "0.1.0",
+    "description": "Generate TypeScript types from your Flexa CMS content models.",
+    "keywords": [
+        "cms",
+        "codegen",
+        "flexa",
+        "headless",
+        "typescript"
+    ],
+    "homepage": "https://github.com/flexacms/sdk/tree/main/packages/cli#readme",
+    "bugs": {
+        "url": "https://github.com/flexacms/sdk/issues"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/flexacms/sdk.git",
+        "directory": "packages/cli"
+    },
+    "bin": {
+        "flexa": "./dist/cli.js"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        }
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "tsup",
+        "typecheck": "tsc -p tsconfig.json"
+    },
+    "dependencies": {
+        "@flexacms/client": "^0.1.0"
+    },
+    "engines": {
+        "node": ">=20"
+    }
+}