twenty-sdk 0.0.6 → 0.1.1

package/README.md

@@ -1,6 +1,26 @@
-# twenty-sdk
+<div align="center">
+  <a href="https://twenty.com">
+    <picture>
+      <img alt="Twenty logo" src="https://raw.githubusercontent.com/twentyhq/twenty/2f25922f4cd5bd61e1427c57c4f8ea224e1d552c/packages/twenty-website/public/images/core/logo.svg" height="128">
+    </picture>
+  </a>
+  <h1>Twenty SDK</h1>
 
-A lightweight TypeScript SDK for Twenty CRM.
+<a href="https://www.npmjs.com/package/twenty-sdk"><img alt="NPM version" src="https://img.shields.io/npm/v/twenty-sdk.svg?style=for-the-badge&labelColor=000000"></a>
+<a href="https://github.com/twentyhq/twenty/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/npm/l/next.svg?style=for-the-badge&labelColor=000000"></a>
+<a href="https://discord.gg/cx5n4Jzs57"><img alt="Join the community on Discord" src="https://img.shields.io/badge/Join%20the%20community-blueviolet.svg?style=for-the-badge&logo=Twenty&labelColor=000000&logoWidth=20"></a>
+
+</div>
+
+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
+- Works great with the scaffolder: [create-twenty-app](https://www.npmjs.com/package/create-twenty-app)
+
+## 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
 
 ## Installation
 
@@ -10,18 +30,72 @@ npm install twenty-sdk
 yarn add twenty-sdk
 ```
 
-## Usage
+## Getting started
+You can either scaffold a new app or add the SDK to an existing one.
+
+- Start new (recommended):
+  ```bash
+  npx create-twenty-app@latest my-twenty-app
+  cd my-twenty-app
+  ```
+- Existing project: install the SDK as shown above, then use the CLI below.
+
+## CLI quickstart
+```bash
+# Authenticate using your API key (CLI will prompt for it)
+twenty auth login
+
+# Add a new entity to your application (guided prompts)
+twenty app add
+
+# Generate a typed Twenty client and TypeScript definitions for your workspace entities
+twenty app generate
+
+# Start dev mode: automatically syncs changes to your workspace for instant testing
+twenty app dev
+
+# One‑time sync of local changes
+twenty app sync
 
+# Uninstall the application from the current workspace
+twenty app uninstall
+```
+
+## Usage (SDK)
 ```typescript
+// Example: import what you need from the SDK
 import { /* your exports */ } from 'twenty-sdk';
 ```
 
-## Development
+## Publish your application
+Applications are currently stored in [`twenty/packages/twenty-apps`](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps).
+
+You can share your application with all Twenty users:
 
 ```bash
-# Build
-npx nx build twenty-sdk
+# pull the Twenty project
+git clone https://github.com/twentyhq/twenty.git
+cd twenty
+
+# create a new branch
+git checkout -b feature/my-awesome-app
+```
 
-# Lint
-npx nx lint twenty-sdk
+- Copy your app folder into `twenty/packages/twenty-apps`.
+- Commit your changes and open a pull request on https://github.com/twentyhq/twenty
+
+```bash
+git commit -m "Add new application"
+git push
 ```
+
+Our team reviews contributions for quality, security, and reusability.
+
+## 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`).
+
+## Contributing
+- See our [GitHub](https://github.com/twentyhq/twenty)
+- Join our [Discord](https://discord.gg/cx5n4Jzs57)

package/dist/_commonjsHelpers-DKOUU3wS.js

@@ -0,0 +1 @@
+"use strict";var o=typeof globalThis<"u"?globalThis:typeof window<"u"?window:typeof global<"u"?global:typeof self<"u"?self:{};function l(e){return e&&e.__esModule&&Object.prototype.hasOwnProperty.call(e,"default")?e.default:e}exports.commonjsGlobal=o;exports.getDefaultExportFromCjs=l;

package/dist/_commonjsHelpers-DaMA6jEr.mjs

@@ -0,0 +1,8 @@
+var o = typeof globalThis < "u" ? globalThis : typeof window < "u" ? window : typeof global < "u" ? global : typeof self < "u" ? self : {};
+function l(e) {
+  return e && e.__esModule && Object.prototype.hasOwnProperty.call(e, "default") ? e.default : e;
+}
+export {
+  o as c,
+  l as g
+};

package/dist/application/application-config.d.ts

@@ -1,5 +1,4 @@
-import { SyncableEntityOptions } from '@/application/syncable-entity-options.type';
-
+import { SyncableEntityOptions } from './syncable-entity-options.type';
 type ApplicationVariable = SyncableEntityOptions & {
     value?: string;
     description?: string;

package/dist/application/field-metadata/field.decorator.d.ts

@@ -1,6 +1,5 @@
+import { SyncableEntityOptions } from '../syncable-entity-options.type';
 import { FieldMetadataType, FieldMetadataSettings, FieldMetadataOptions, FieldMetadataDefaultValue } from 'twenty-shared/types';
-import { SyncableEntityOptions } from '@/application/syncable-entity-options.type';
-
 type FieldOptions<T extends FieldMetadataType = Exclude<FieldMetadataType, FieldMetadataType.RELATION>> = SyncableEntityOptions & {
     type: T;
     label: string;

package/dist/application/field-metadata/relation.decorator.d.ts

@@ -1,6 +1,5 @@
+import { SyncableEntityOptions } from '../syncable-entity-options.type';
 import { RelationOnDeleteAction, RelationType } from 'twenty-shared/types';
-import { SyncableEntityOptions } from '@/application/syncable-entity-options.type';
-
 interface WorkspaceRelationMinimumBaseOptions<TClass> {
     label: string;
     description?: string;

package/dist/application/{serverless-function-config.d.ts → function-config.d.ts}

@@ -1,5 +1,4 @@
-import { SyncableEntityOptions } from '@/application/syncable-entity-options.type';
-
+import { SyncableEntityOptions } from './syncable-entity-options.type';
 type RouteTrigger = {
     type: 'route';
     path: string;
@@ -14,11 +13,11 @@ type DatabaseEventTrigger = {
     type: 'databaseEvent';
     eventName: string;
 };
-type ServerlessFunctionTrigger = SyncableEntityOptions & (RouteTrigger | CronTrigger | DatabaseEventTrigger);
-export type ServerlessFunctionConfig = SyncableEntityOptions & {
+type FunctionTrigger = SyncableEntityOptions & (RouteTrigger | CronTrigger | DatabaseEventTrigger);
+export type FunctionConfig = SyncableEntityOptions & {
     name?: string;
     description?: string;
     timeoutSeconds?: number;
-    triggers?: ServerlessFunctionTrigger[];
+    triggers?: FunctionTrigger[];
 };
 export {};

package/dist/application/index.d.ts

@@ -5,7 +5,7 @@ export { Field } from './field-metadata/field.decorator';
 export { OnDeleteAction } from './field-metadata/on-delete-action';
 export { RelationType } from './field-metadata/relation-type';
 export { Relation } from './field-metadata/relation.decorator';
+export type { FunctionConfig } from './function-config';
 export { Object } from './object-metadata/object.decorator';
 export { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from './object-metadata/standard-object-ids';
-export type { ServerlessFunctionConfig } from './serverless-function-config';
 export type { SyncableEntityOptions } from './syncable-entity-options.type';

package/dist/application/object-metadata/object.decorator.d.ts

@@ -1,5 +1,4 @@
-import { SyncableEntityOptions } from '@/application/syncable-entity-options.type';
-
+import { SyncableEntityOptions } from '../syncable-entity-options.type';
 type ObjectMetadataOptions = SyncableEntityOptions & {
     nameSingular: string;
     namePlural: string;

package/dist/cli/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/commands/app-add.command.d.ts

@@ -0,0 +1,12 @@
+export declare enum SyncableEntity {
+    AGENT = "agent",
+    OBJECT = "object",
+    FUNCTION = "function"
+}
+export declare const isSyncableEntity: (value: string) => value is SyncableEntity;
+export declare class AppAddCommand {
+    execute(entityType?: SyncableEntity, path?: string): Promise<void>;
+    private getEntity;
+    private getEntityName;
+    private getObjectData;
+}

package/dist/cli/commands/app-dev.command.d.ts

@@ -0,0 +1,10 @@
+export declare class AppDevCommand {
+    private syncCommand;
+    execute(options: {
+        appPath?: string;
+        debounce: string;
+    }): Promise<void>;
+    private logStartupInfo;
+    private setupFileWatcher;
+    private setupGracefulShutdown;
+}

package/dist/cli/commands/app-generate.command.d.ts

@@ -0,0 +1,4 @@
+export declare class AppGenerateCommand {
+    private generateService;
+    execute(appPath?: string): Promise<void>;
+}

package/dist/cli/commands/app-sync.command.d.ts

@@ -0,0 +1,7 @@
+import { ApiResponse } from '../types/config.types';
+export declare class AppSyncCommand {
+    private apiService;
+    private generateService;
+    execute(appPath?: string): Promise<ApiResponse<any>>;
+    private synchronize;
+}

package/dist/cli/commands/app-uninstall.command.d.ts

@@ -0,0 +1,9 @@
+import { ApiResponse } from '../types/config.types';
+export declare class AppUninstallCommand {
+    private apiService;
+    execute({ appPath, askForConfirmation, }: {
+        appPath?: string;
+        askForConfirmation: boolean;
+    }): Promise<ApiResponse<any>>;
+    private confirmationPrompt;
+}

package/dist/cli/commands/app.command.d.ts

@@ -0,0 +1,9 @@
+import { Command } from 'commander';
+export declare class AppCommand {
+    private devCommand;
+    private syncCommand;
+    private uninstallCommand;
+    private addCommand;
+    private generateCommand;
+    getCommand(): Command;
+}

package/dist/cli/commands/auth.command.d.ts

@@ -0,0 +1,9 @@
+import { Command } from 'commander';
+export declare class AuthCommand {
+    private configService;
+    private apiService;
+    getCommand(): Command;
+    private login;
+    private logout;
+    private status;
+}

package/dist/cli/constants/current-execution-directory.d.ts

@@ -0,0 +1 @@
+export declare const CURRENT_EXECUTION_DIRECTORY: string;

package/dist/cli/services/api.service.d.ts

@@ -0,0 +1,14 @@
+import { ApiResponse, AppManifest, PackageJson } from '../types/config.types';
+export declare class ApiService {
+    private client;
+    private configService;
+    constructor();
+    validateAuth(): Promise<boolean>;
+    syncApplication({ packageJson, yarnLock, manifest, }: {
+        packageJson: PackageJson;
+        yarnLock: string;
+        manifest: AppManifest;
+    }): Promise<ApiResponse>;
+    uninstallApplication(universalIdentifier: string): Promise<ApiResponse>;
+    getSchema(): Promise<ApiResponse<string>>;
+}

package/dist/cli/services/config.service.d.ts

@@ -0,0 +1,14 @@
+import { TwentyConfig } from '../types/config.types';
+export declare class ConfigService {
+    private readonly configPath;
+    private static activeWorkspace;
+    constructor();
+    static setActiveWorkspace(name?: string): void;
+    static getActiveWorkspace(): string;
+    private getActiveWorkspaceName;
+    private readRawConfig;
+    getConfig(): Promise<TwentyConfig>;
+    setConfig(config: Partial<TwentyConfig>): Promise<void>;
+    clearConfig(): Promise<void>;
+    private getDefaultConfig;
+}

package/dist/cli/services/generate.service.d.ts

@@ -0,0 +1,7 @@
+export declare const GENERATED_FOLDER_NAME = "generated";
+export declare class GenerateService {
+    private configService;
+    private apiService;
+    constructor();
+    generateClient(appPath: string): Promise<void>;
+}

package/dist/cli/types/config.types.d.ts

@@ -0,0 +1,99 @@
+export interface TwentyConfig {
+    apiUrl: string;
+    apiKey?: string;
+}
+export type PackageJson = {
+    name: string;
+    license: string;
+    engines: {
+        node: string;
+        npm: string;
+        yarn: string;
+    };
+    packageManager: string;
+    version: string;
+    dependencies?: object;
+    devDependencies?: object;
+};
+type ApplicationVariable = {
+    universalIdentifier: string;
+    value?: string;
+    description?: string;
+    isSecret?: boolean;
+};
+export type Application = {
+    universalIdentifier: string;
+    displayName?: string;
+    description?: string;
+    icon?: string;
+    applicationVariables?: Record<string, ApplicationVariable>;
+};
+export type AppManifest = {
+    application: Application;
+    objects: ObjectManifest[];
+    serverlessFunctions: ServerlessFunctionManifest[];
+    sources: Sources;
+};
+export type ServerlessFunctionManifest = {
+    universalIdentifier: string;
+    name?: string;
+    description?: string;
+    timeoutSeconds?: number;
+    triggers: ServerlessFunctionTriggerManifest[];
+    handlerPath: string;
+    handlerName: string;
+};
+export type DatabaseEventTrigger = {
+    type: 'databaseEvent';
+    eventName: string;
+};
+export type CronTrigger = {
+    type: 'cron';
+    pattern: string;
+};
+export type RouteTrigger = {
+    type: 'route';
+    path: string;
+    httpMethod: string;
+    isAuthRequired: boolean;
+};
+export type ServerlessFunctionTriggerManifest = {
+    universalIdentifier: string;
+} & (CronTrigger | DatabaseEventTrigger | RouteTrigger);
+export type Sources = {
+    [key: string]: string | Sources;
+};
+export type FieldMetadata = {
+    universalIdentifier: string;
+    type: string;
+    label: string;
+    description?: string;
+    icon?: string;
+    defaultValue?: any;
+    options?: any;
+    settings?: any;
+    isNullable?: boolean;
+    isFieldUiReadOnly?: boolean;
+};
+export type ObjectManifest = {
+    universalIdentifier: string;
+    nameSingular: string;
+    namePlural: string;
+    labelSingular: string;
+    labelPlural: string;
+    description?: string;
+    icon?: string;
+    fields: FieldMetadata[];
+};
+export type SuccessfulApiResponse<T = unknown> = {
+    success: true;
+    data: T;
+    message?: string;
+};
+export type FailingApiResponse = {
+    success: false;
+    error?: unknown;
+    message?: string;
+};
+export type ApiResponse<T = unknown> = SuccessfulApiResponse<T> | FailingApiResponse;
+export {};

package/dist/cli/utils/convert-to-label.d.ts

@@ -0,0 +1 @@
+export declare const convertToLabel: (str: string) => string;

package/dist/cli/utils/find-path-file.d.ts

@@ -0,0 +1 @@
+export declare const findPathFile: (appPath: string, fileName: string) => Promise<string>;

package/dist/cli/utils/format-and-warn-ts-diagnostics.d.ts

@@ -0,0 +1,4 @@
+import { Diagnostic } from 'typescript';
+export declare const formatAndWarnTsDiagnostics: ({ diagnostics, }: {
+    diagnostics: Diagnostic[];
+}) => void;

package/dist/cli/utils/format-path.d.ts

@@ -0,0 +1 @@
+export declare const formatPath: (appPath?: string) => string | undefined;

package/dist/cli/utils/get-function-base-file.d.ts

@@ -0,0 +1,4 @@
+export declare const getFunctionBaseFile: ({ name, universalIdentifier, }: {
+    name: string;
+    universalIdentifier?: string;
+}) => string;

package/dist/cli/utils/get-object-decorated-class.d.ts

@@ -0,0 +1,4 @@
+export declare const getObjectDecoratedClass: ({ data, name, }: {
+    data: object;
+    name: string;
+}) => string;

package/dist/cli/utils/get-ts-program-and-diagnostics.d.ts

@@ -0,0 +1,7 @@
+import { Program, Diagnostic } from 'typescript';
+export declare const getTsProgramAndDiagnostics: ({ appPath, }: {
+    appPath: string;
+}) => Promise<{
+    program: Program;
+    diagnostics: Diagnostic[];
+}>;

package/dist/cli/utils/jsonc-parser.d.ts

@@ -0,0 +1,17 @@
+import { ParseError } from 'jsonc-parser';
+export interface JsoncParseOptions {
+    allowTrailingComma?: boolean;
+    disallowComments?: boolean;
+    allowEmptyContent?: boolean;
+}
+export declare class JsoncParseError extends Error {
+    readonly parseErrors: ParseError[];
+    readonly filePath?: string | undefined;
+    constructor(message: string, parseErrors: ParseError[], filePath?: string | undefined);
+}
+export declare const parseJsoncString: (content: string, options?: JsoncParseOptions) => any;
+export declare const parseTextFile: (filePath: string) => Promise<string>;
+export declare const parseJsoncFile: (filePath: string, options?: JsoncParseOptions) => Promise<any>;
+export declare const writeJsoncFile: (filePath: string, data: any, options?: {
+    spaces?: number;
+}) => Promise<void>;

package/dist/cli/utils/load-env-variables.d.ts

@@ -0,0 +1,2 @@
+import { default as dotenv } from 'dotenv';
+export declare const loadEnvVariables: (appPath: string) => Promise<dotenv.DotenvParseOutput>;

package/dist/cli/utils/load-manifest.d.ts

@@ -0,0 +1,9 @@
+import { Program } from 'typescript';
+import { AppManifest, Application, PackageJson } from '../types/config.types';
+export declare const extractTwentyAppConfig: (program: Program) => Application;
+export declare const loadManifest: (appPath: string) => Promise<{
+    packageJson: PackageJson;
+    yarnLock: string;
+    manifest: AppManifest;
+    shouldGenerate: boolean;
+}>;