twenty-sdk 0.3.0 → 0.4.0

package/README.md

@@ -15,9 +15,12 @@
 A CLI and SDK to develop, build, and publish applications that extend [Twenty CRM](https://twenty.com).
 
 - Type‑safe client and workspace entity typings
-- Built‑in CLI for auth, generate, dev sync, one‑off sync, and uninstall
+- Built‑in CLI for auth, dev mode (watch & sync), generate, uninstall, and function management
 - Works great with the scaffolder: [create-twenty-app](https://www.npmjs.com/package/create-twenty-app)
 
+## Documentation
+See Twenty application documentation https://docs.twenty.com/developers/extend/capabilities/apps
+
 ## Prerequisites
 - Node.js 24+ (recommended) and Yarn 4
 - A Twenty workspace and an API key. Generate one at https://app.twenty.com/settings/api-webhooks
@@ -43,8 +46,17 @@ Options:
   -h, --help           display help for command
 
 Commands:
-  auth                 Authentication commands
-  app                  Application development commands
+  auth:login           Authenticate with Twenty
+  auth:logout          Remove authentication credentials
+  auth:status          Check authentication status
+  auth:switch          Switch the default workspace
+  auth:list            List all configured workspaces
+  app:dev              Watch and sync local application changes
+  app:generate         Generate Twenty client
+  app:uninstall        Uninstall application from Twenty
+  entity:add           Add a new entity to your application
+  function:logs        Watch application function logs
+  function:execute     Execute a logic function with a JSON payload
   help [command]       display help for command
 ```
 
@@ -58,92 +70,127 @@ Commands:
 
 Authenticate the CLI against your Twenty workspace.
 
-- `twenty auth login` — Authenticate with Twenty.
+- `twenty auth:login` — Authenticate with Twenty.
   - Options:
     - `--api-key <key>`: API key for authentication.
     - `--api-url <url>`: Twenty API URL (defaults to your current profile's value or `http://localhost:3000`).
   - Behavior: Prompts for any missing values, persists them to the active workspace profile, and validates the credentials.
 
-- `twenty auth logout` — Remove authentication credentials for the active workspace profile.
+- `twenty auth:logout` — Remove authentication credentials for the active workspace profile.
+
+- `twenty auth:status` — Print the current authentication status (API URL, masked API key, validity).
+
+- `twenty auth:list` — List all configured workspaces.
+  - Behavior: Displays all available workspaces with their authentication status and API URLs. Shows which workspace is the current default.
 
-- `twenty auth status` — Print the current authentication status (API URL, masked API key, validity).
+- `twenty auth:switch [workspace]` — Switch the default workspace for authentication.
+  - Arguments:
+    - `workspace` (optional): Name of the workspace to switch to. If omitted, shows an interactive selection.
+  - Behavior: Sets the specified workspace as the default, so subsequent commands use it without needing `--workspace`.
 
 Examples:
 
 ```bash
 # Login interactively (recommended)
-twenty auth login
+twenty auth:login
 
 # Provide values in flags
-twenty auth login --api-key $TWENTY_API_KEY --api-url https://api.twenty.com
+twenty auth:login --api-key $TWENTY_API_KEY --api-url https://api.twenty.com
 
 # Login interactively for a specific workspace profile
-twenty auth login --workspace my-custom-workspace
+twenty auth:login --workspace my-custom-workspace
 
 # Check status
-twenty auth status
+twenty auth:status
 
 # Logout current profile
-twenty auth logout
+twenty auth:logout
+
+# List all configured workspaces
+twenty auth:list
+
+# Switch default workspace interactively
+twenty auth:switch
+
+# Switch to a specific workspace
+twenty auth:switch production
 ```
 
 ### App
 
 Application development commands.
 
-- `twenty app sync [appPath]` — One-time sync of the application to your Twenty workspace.
-- Behavior: Compute your application's manifest and send it to your workspace to sync your application
+- `twenty app:dev [appPath]` — Start development mode: watch and sync local application changes.
+  - Behavior: Builds your application (functions and front components), computes the manifest, syncs everything to your workspace, then watches the directory for changes and re-syncs automatically. Displays an interactive UI showing build and sync status in real time. Press Ctrl+C to stop.
 
-- `twenty app dev [appPath]` — Watch and sync local application changes.
-  - Options:
-    - `-d, --debounce <ms>`: Debounce delay in milliseconds (default: `1000`).
-  - Behavior: Performs an initial sync, then watches the directory for changes and re-syncs after debounced edits. Press Ctrl+C to stop.
+- `twenty app:uninstall [appPath]` — Uninstall the application from the current workspace.
+
+- `twenty app:generate [appPath]` — Generate the typed Twenty client for your application.
 
-- `twenty app uninstall [appPath]` — Uninstall the application from the current workspace.
-  - Note: `twenty app delete` exists as a hidden alias for backward compatibility.
+### Entity
 
-- `twenty app add [entityType]` — Add a new entity to your application.
+- `twenty entity:add [entityType]` — Add a new entity to your application.
   - Arguments:
-    - `entityType`: one of `function` or `object`. If omitted, an interactive prompt is shown.
+    - `entityType`: one of `function`, `front-component`, `object`, or `role`. If omitted, an interactive prompt is shown.
   - Options:
     - `--path <path>`: The path where the entity file should be created (relative to the current directory).
   - Behavior:
-    - `object`: prompts for singular/plural names and labels, then creates a new object definition file.
-    - `function`: prompts for a name and scaffolds a serverless function file.
+    - `object`: prompts for singular/plural names and labels, then creates a `*.object.ts` definition file.
+    - `function`: prompts for a name and scaffolds a `*.function.ts` logic function file.
+    - `front-component`: prompts for a name and scaffolds a `*.front-component.tsx` file.
+    - `role`: prompts for a name and scaffolds a `*.role.ts` role definition file.
 
-- `twenty app generate [appPath]` — Generate the typed Twenty client for your application.
+### Function
 
-- `twenty app logs [appPath]` — Stream application function logs.
+- `twenty function:logs [appPath]` — Stream application function logs.
   - Options:
     - `-u, --functionUniversalIdentifier <id>`: Only show logs for a specific function universal ID.
     - `-n, --functionName <name>`: Only show logs for a specific function name.
 
+- `twenty function:execute [appPath]` — Execute a logic function with a JSON payload.
+  - Options:
+    - `-n, --functionName <name>`: Name of the function to execute (required if `-u` not provided).
+    - `-u, --functionUniversalIdentifier <id>`: Universal ID of the function to execute (required if `-n` not provided).
+    - `-p, --payload <payload>`: JSON payload to send to the function (default: `{}`).
+
 Examples:
 
 ```bash
-# Start dev mode with default debounce
-twenty app dev
+# Start dev mode (watch, build, and sync)
+twenty app:dev
 
-# Start dev mode with custom workspace profile
-twenty app dev --workspace my-custom-workspace
+# Start dev mode with a custom workspace profile
+twenty app:dev --workspace my-custom-workspace
 
-# Dev mode with custom debounce
-twenty app dev --debounce 1500
+# Add a new entity interactively
+twenty entity:add
 
-# One-time sync of the current directory
-twenty app sync
+# Add a new function
+twenty entity:add function
 
-# Add a new object interactively
-twenty app add
+# Add a new front component
+twenty entity:add front-component
 
 # Generate client types
-twenty app generate
+twenty app:generate
+
+# Uninstall the app from the workspace
+twenty app:uninstall
 
 # Watch all function logs
-twenty app logs
+twenty function:logs
 
 # Watch logs for a specific function by name
-twenty app logs -n my-function
+twenty function:logs -n my-function
+
+# Execute a function by name (with empty payload)
+twenty function:execute -n my-function
+
+# Execute a function with a JSON payload
+twenty function:execute -n my-function -p '{"name": "test"}'
+
+# Execute a function by universal identifier
+twenty function:execute -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf -p '{"key": "value"}'
 ```
 
 ## Configuration
@@ -151,12 +198,13 @@ twenty app logs -n my-function
 The CLI stores configuration per user in a JSON file:
 
 - Location: `~/.twenty/config.json`
-- Structure: Profiles keyed by workspace name. The active profile is selected with `--workspace <name>`.
+- Structure: Profiles keyed by workspace name. The active profile is selected with `--workspace <name>` or by the `defaultWorkspace` setting.
 
 Example configuration file:
 
 ```json
 {
+  "defaultWorkspace": "prod",
   "profiles": {
     "default": {
       "apiUrl": "http://localhost:3000",
@@ -173,15 +221,62 @@ Example configuration file:
 Notes:
 
 - If a profile is missing, `apiUrl` defaults to `http://localhost:3000` until set.
-- `twenty auth login` writes the `apiUrl` and `apiKey` for the default profile.
-- `twenty auth login --workspace custom-workspace` writes the `apiUrl` and `apiKey` for a custom `custom-workspace` profile.
+- `twenty auth:login` writes the `apiUrl` and `apiKey` for the active workspace profile.
+- `twenty auth:login --workspace custom-workspace` writes the `apiUrl` and `apiKey` for a custom `custom-workspace` profile.
+- `twenty auth:switch` sets the `defaultWorkspace` field, which is used when `--workspace` is not specified.
+- `twenty auth:list` shows all configured workspaces and their authentication status.
 
 
 ## Troubleshooting
-- Auth errors: run `twenty auth login` again and ensure the API key has the required permissions.
-- Typings out of date: run `twenty app generate` to refresh the client and types.
-- Not seeing changes in dev: make sure dev mode is running (`twenty app dev`).
+- Auth errors: run `twenty auth:login` again and ensure the API key has the required permissions.
+- Typings out of date: run `twenty app:generate` to refresh the client and types.
+- Not seeing changes in dev: make sure dev mode is running (`twenty app:dev`).
 
 ## Contributing
+
+### Development Setup
+
+To contribute to the twenty-sdk package, clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/twentyhq/twenty.git
+cd twenty
+yarn install
+```
+
+### Development Mode
+
+Run the SDK build in watch mode to automatically rebuild on file changes:
+
+```bash
+npx nx run twenty-sdk:dev
+```
+
+This will watch for changes and rebuild the `dist` folder automatically.
+
+### Production Build
+
+Build the SDK for production:
+
+```bash
+npx nx run twenty-sdk:build
+```
+
+### Running the CLI Locally
+
+After building, you can run the CLI directly:
+
+```bash
+npx nx run twenty-sdk:start -- <command>
+# Example: npx nx run twenty-sdk:start -- auth:status
+```
+
+Or run the built CLI directly:
+
+```bash
+node packages/twenty-sdk/dist/cli.cjs <command>
+```
+
+### Resources
 - See our [GitHub](https://github.com/twentyhq/twenty)
 - Join our [Discord](https://discord.gg/cx5n4Jzs57)

package/dist/HtmlTagToRemoteComponent-Bd5sgek2.js

@@ -0,0 +1 @@
+"use strict";const e=[{tag:"html-div",name:"HtmlDiv",properties:{}},{tag:"html-span",name:"HtmlSpan",properties:{}},{tag:"html-section",name:"HtmlSection",properties:{}},{tag:"html-article",name:"HtmlArticle",properties:{}},{tag:"html-header",name:"HtmlHeader",properties:{}},{tag:"html-footer",name:"HtmlFooter",properties:{}},{tag:"html-main",name:"HtmlMain",properties:{}},{tag:"html-nav",name:"HtmlNav",properties:{}},{tag:"html-aside",name:"HtmlAside",properties:{}},{tag:"html-p",name:"HtmlP",properties:{}},{tag:"html-h1",name:"HtmlH1",properties:{}},{tag:"html-h2",name:"HtmlH2",properties:{}},{tag:"html-h3",name:"HtmlH3",properties:{}},{tag:"html-h4",name:"HtmlH4",properties:{}},{tag:"html-h5",name:"HtmlH5",properties:{}},{tag:"html-h6",name:"HtmlH6",properties:{}},{tag:"html-strong",name:"HtmlStrong",properties:{}},{tag:"html-em",name:"HtmlEm",properties:{}},{tag:"html-small",name:"HtmlSmall",properties:{}},{tag:"html-code",name:"HtmlCode",properties:{}},{tag:"html-pre",name:"HtmlPre",properties:{}},{tag:"html-blockquote",name:"HtmlBlockquote",properties:{}},{tag:"html-a",name:"HtmlA",properties:{href:{type:"string",optional:!0},target:{type:"string",optional:!0},rel:{type:"string",optional:!0}}},{tag:"html-img",name:"HtmlImg",properties:{src:{type:"string",optional:!0},alt:{type:"string",optional:!0},width:{type:"number",optional:!0},height:{type:"number",optional:!0}}},{tag:"html-ul",name:"HtmlUl",properties:{}},{tag:"html-ol",name:"HtmlOl",properties:{}},{tag:"html-li",name:"HtmlLi",properties:{}},{tag:"html-form",name:"HtmlForm",properties:{action:{type:"string",optional:!0},method:{type:"string",optional:!0}}},{tag:"html-label",name:"HtmlLabel",properties:{htmlFor:{type:"string",optional:!0}}},{tag:"html-input",name:"HtmlInput",properties:{type:{type:"string",optional:!0},name:{type:"string",optional:!0},value:{type:"string",optional:!0},placeholder:{type:"string",optional:!0},disabled:{type:"boolean",optional:!0},checked:{type:"boolean",optional:!0},readOnly:{type:"boolean",optional:!0}}},{tag:"html-textarea",name:"HtmlTextarea",properties:{name:{type:"string",optional:!0},value:{type:"string",optional:!0},placeholder:{type:"string",optional:!0},disabled:{type:"boolean",optional:!0},readOnly:{type:"boolean",optional:!0},rows:{type:"number",optional:!0},cols:{type:"number",optional:!0}}},{tag:"html-select",name:"HtmlSelect",properties:{name:{type:"string",optional:!0},value:{type:"string",optional:!0},disabled:{type:"boolean",optional:!0},multiple:{type:"boolean",optional:!0}}},{tag:"html-option",name:"HtmlOption",properties:{value:{type:"string",optional:!0},disabled:{type:"boolean",optional:!0},selected:{type:"boolean",optional:!0}}},{tag:"html-button",name:"HtmlButton",properties:{type:{type:"string",optional:!0},disabled:{type:"boolean",optional:!0}}},{tag:"html-table",name:"HtmlTable",properties:{}},{tag:"html-thead",name:"HtmlThead",properties:{}},{tag:"html-tbody",name:"HtmlTbody",properties:{}},{tag:"html-tfoot",name:"HtmlTfoot",properties:{}},{tag:"html-tr",name:"HtmlTr",properties:{}},{tag:"html-th",name:"HtmlTh",properties:{colSpan:{type:"number",optional:!0},rowSpan:{type:"number",optional:!0}}},{tag:"html-td",name:"HtmlTd",properties:{colSpan:{type:"number",optional:!0},rowSpan:{type:"number",optional:!0}}},{tag:"html-br",name:"HtmlBr",properties:{}},{tag:"html-hr",name:"HtmlHr",properties:{}}],r=Object.fromEntries(e.map(t=>[t.tag.startsWith("html-")?t.tag.slice(5):t.tag,t.name]));exports.ALLOWED_HTML_ELEMENTS=e;exports.HTML_TAG_TO_REMOTE_COMPONENT=r;

package/dist/HtmlTagToRemoteComponent-DlsAI7JU.mjs

@@ -0,0 +1,146 @@
+const e = [
+  { tag: "html-div", name: "HtmlDiv", properties: {} },
+  { tag: "html-span", name: "HtmlSpan", properties: {} },
+  { tag: "html-section", name: "HtmlSection", properties: {} },
+  { tag: "html-article", name: "HtmlArticle", properties: {} },
+  { tag: "html-header", name: "HtmlHeader", properties: {} },
+  { tag: "html-footer", name: "HtmlFooter", properties: {} },
+  { tag: "html-main", name: "HtmlMain", properties: {} },
+  { tag: "html-nav", name: "HtmlNav", properties: {} },
+  { tag: "html-aside", name: "HtmlAside", properties: {} },
+  { tag: "html-p", name: "HtmlP", properties: {} },
+  { tag: "html-h1", name: "HtmlH1", properties: {} },
+  { tag: "html-h2", name: "HtmlH2", properties: {} },
+  { tag: "html-h3", name: "HtmlH3", properties: {} },
+  { tag: "html-h4", name: "HtmlH4", properties: {} },
+  { tag: "html-h5", name: "HtmlH5", properties: {} },
+  { tag: "html-h6", name: "HtmlH6", properties: {} },
+  { tag: "html-strong", name: "HtmlStrong", properties: {} },
+  { tag: "html-em", name: "HtmlEm", properties: {} },
+  { tag: "html-small", name: "HtmlSmall", properties: {} },
+  { tag: "html-code", name: "HtmlCode", properties: {} },
+  { tag: "html-pre", name: "HtmlPre", properties: {} },
+  { tag: "html-blockquote", name: "HtmlBlockquote", properties: {} },
+  {
+    tag: "html-a",
+    name: "HtmlA",
+    properties: {
+      href: { type: "string", optional: !0 },
+      target: { type: "string", optional: !0 },
+      rel: { type: "string", optional: !0 }
+    }
+  },
+  {
+    tag: "html-img",
+    name: "HtmlImg",
+    properties: {
+      src: { type: "string", optional: !0 },
+      alt: { type: "string", optional: !0 },
+      width: { type: "number", optional: !0 },
+      height: { type: "number", optional: !0 }
+    }
+  },
+  { tag: "html-ul", name: "HtmlUl", properties: {} },
+  { tag: "html-ol", name: "HtmlOl", properties: {} },
+  { tag: "html-li", name: "HtmlLi", properties: {} },
+  {
+    tag: "html-form",
+    name: "HtmlForm",
+    properties: {
+      action: { type: "string", optional: !0 },
+      method: { type: "string", optional: !0 }
+    }
+  },
+  {
+    tag: "html-label",
+    name: "HtmlLabel",
+    properties: {
+      htmlFor: { type: "string", optional: !0 }
+    }
+  },
+  {
+    tag: "html-input",
+    name: "HtmlInput",
+    properties: {
+      type: { type: "string", optional: !0 },
+      name: { type: "string", optional: !0 },
+      value: { type: "string", optional: !0 },
+      placeholder: { type: "string", optional: !0 },
+      disabled: { type: "boolean", optional: !0 },
+      checked: { type: "boolean", optional: !0 },
+      readOnly: { type: "boolean", optional: !0 }
+    }
+  },
+  {
+    tag: "html-textarea",
+    name: "HtmlTextarea",
+    properties: {
+      name: { type: "string", optional: !0 },
+      value: { type: "string", optional: !0 },
+      placeholder: { type: "string", optional: !0 },
+      disabled: { type: "boolean", optional: !0 },
+      readOnly: { type: "boolean", optional: !0 },
+      rows: { type: "number", optional: !0 },
+      cols: { type: "number", optional: !0 }
+    }
+  },
+  {
+    tag: "html-select",
+    name: "HtmlSelect",
+    properties: {
+      name: { type: "string", optional: !0 },
+      value: { type: "string", optional: !0 },
+      disabled: { type: "boolean", optional: !0 },
+      multiple: { type: "boolean", optional: !0 }
+    }
+  },
+  {
+    tag: "html-option",
+    name: "HtmlOption",
+    properties: {
+      value: { type: "string", optional: !0 },
+      disabled: { type: "boolean", optional: !0 },
+      selected: { type: "boolean", optional: !0 }
+    }
+  },
+  {
+    tag: "html-button",
+    name: "HtmlButton",
+    properties: {
+      type: { type: "string", optional: !0 },
+      disabled: { type: "boolean", optional: !0 }
+    }
+  },
+  { tag: "html-table", name: "HtmlTable", properties: {} },
+  { tag: "html-thead", name: "HtmlThead", properties: {} },
+  { tag: "html-tbody", name: "HtmlTbody", properties: {} },
+  { tag: "html-tfoot", name: "HtmlTfoot", properties: {} },
+  { tag: "html-tr", name: "HtmlTr", properties: {} },
+  {
+    tag: "html-th",
+    name: "HtmlTh",
+    properties: {
+      colSpan: { type: "number", optional: !0 },
+      rowSpan: { type: "number", optional: !0 }
+    }
+  },
+  {
+    tag: "html-td",
+    name: "HtmlTd",
+    properties: {
+      colSpan: { type: "number", optional: !0 },
+      rowSpan: { type: "number", optional: !0 }
+    }
+  },
+  { tag: "html-br", name: "HtmlBr", properties: {} },
+  { tag: "html-hr", name: "HtmlHr", properties: {} }
+], a = Object.fromEntries(
+  e.map((t) => [
+    t.tag.startsWith("html-") ? t.tag.slice(5) : t.tag,
+    t.name
+  ])
+);
+export {
+  e as A,
+  a as H
+};