Mantıksal işlevler

import { defineLogicFunction } from 'twenty-sdk/define';
import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk/define';
import { CoreApiClient, type Person } from 'twenty-client-sdk/core';

const handler = async (params: RoutePayload) => {
  const client = new CoreApiClient();
  const name = 'name' in params.queryStringParameters
    ? params.queryStringParameters.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world'
    : 'Hello world';

  const result = await client.mutation({
    createPostCard: {
      __args: { data: { name } },
      id: true,
      name: true,
    },
  });
  return result;
};

export default defineLogicFunction({
  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
  name: 'create-new-post-card',
  timeoutSeconds: 2,
  handler,
  httpRouteTriggerSettings: {
    path: '/post-card/create',
    httpMethod: 'GET',
    isAuthRequired: true,
  },
  /*databaseEventTriggerSettings: {
    eventName: 'people.created',
  },*/
  /*cronTriggerSettings: {
    pattern: '0 0 1 1 *',
  },*/
});

• httpRoute: Fonksiyonunuzu bir HTTP yolu ve yöntemiyle /s/ uç noktasının altında kullanıma sunar:

örn. path: '/post-card/create' https://your-twenty-server.com/s/post-card/create adresinden çağrılabilir

• cron: Bir CRON ifadesi kullanarak fonksiyonunuzu bir zamanlamayla çalıştırır.
• databaseEvent: Çalışma alanı nesnesi yaşam döngüsü olaylarında çalışır. Olay işlemi updated olduğunda, dinlenecek belirli alanlar updatedFields dizisinde belirtilebilir. Tanımsız veya boş bırakılırsa, herhangi bir güncelleme fonksiyonu tetikler.

örn. person.updated, *.created, company.*

yarn twenty exec -n create-new-post-card -p '{"key": "value"}'

yarn twenty exec -y e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf

yarn twenty logs

​

Rota tetikleyicisi yükü

import { defineLogicFunction, type RoutePayload } from 'twenty-sdk/define';

const handler = async (event: RoutePayload) => {
  const { headers, queryStringParameters, pathParameters, body } = event;
  const { method, path } = event.requestContext.http;

  return { message: 'Success' };
};

​

forwardedRequestHeaders

export default defineLogicFunction({
  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
  name: 'webhook-handler',
  handler,
  httpRouteTriggerSettings: {
    path: '/webhook',
    httpMethod: 'POST',
    isAuthRequired: false,
    forwardedRequestHeaders: ['x-webhook-signature', 'content-type'],
  },
});

const handler = async (event: RoutePayload) => {
  const signature = event.headers['x-webhook-signature'];
  const contentType = event.headers['content-type'];

  // Validate webhook signature...
  return { received: true };
};

​

Bir fonksiyonu araç olarak sunma

import { defineLogicFunction } from 'twenty-sdk/define';
import { CoreApiClient } from 'twenty-client-sdk/core';

const handler = async (params: { companyName: string; domain?: string }) => {
  const client = new CoreApiClient();

  const result = await client.mutation({
    createTask: {
      __args: {
        data: {
          title: `Enrich data for ${params.companyName}`,
          body: `Domain: ${params.domain ?? 'unknown'}`,
        },
      },
      id: true,
    },
  });

  return { taskId: result.createTask.id };
};

export default defineLogicFunction({
  universalIdentifier: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
  name: 'enrich-company',
  description: 'Enrich a company record with external data',
  timeoutSeconds: 10,
  handler,
  isTool: true,
});

• isTool özelliğini tetikleyicilerle birleştirebilirsiniz — bir fonksiyon aynı anda hem bir araç (yapay zeka ajanları tarafından çağrılabilir) olabilir hem de olaylar tarafından tetiklenebilir.
• toolInputSchema (isteğe bağlı): Fonksiyonunuzun kabul ettiği parametreleri tanımlayan bir JSON Schema nesnesi. Şema, kaynak kodun statik analizinden otomatik olarak oluşturulur, ancak bunu açıkça belirleyebilirsiniz:

export default defineLogicFunction({
  ...,
  toolInputSchema: {
    type: 'object',
    properties: {
      companyName: {
        type: 'string',
        description: 'The name of the company to enrich',
      },
      domain: {
        type: 'string',
        description: 'The company website domain (optional)',
      },
    },
    required: ['companyName'],
  },
});

import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';

const handler = async (payload: InstallPayload): Promise<void> => {
  console.log('Post install logic function executed successfully!', payload.previousVersion);
};

export default definePostInstallLogicFunction({
  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
  name: 'post-install',
  description: 'Runs after installation to set up the application.',
  timeoutSeconds: 300,
  shouldRunOnVersionUpgrade: false,
  shouldRunSynchronously: false,
  handler,
});

yarn twenty exec --postInstall

• Kurulum sonrası işlevler definePostInstallLogicFunction() kullanır — tetikleyici ayarlarını atlayan (cronTriggerSettings, databaseEventTriggerSettings, httpRouteTriggerSettings, isTool) özel bir varyanttır.
• İşleyici, { previousVersion?: string; newVersion: string } içeren bir InstallPayload alır — newVersion, yüklenen sürümdür; previousVersion ise daha önce yüklü olan sürümdür (veya ilk kurulumda undefined). Bu değerleri ilk kurulumları yükseltmelerden ayırt etmek ve sürüme özgü geçiş (migration) mantığını çalıştırmak için kullanın.
• Kanca ne zaman çalışır: varsayılan olarak yalnızca ilk kurulumlarda. Uygulama önceki bir sürümden yükseltildiğinde de çalışmasını istiyorsanız shouldRunOnVersionUpgrade: true geçin. Belirtilmediğinde, bayrak varsayılan olarak false olur ve yükseltmeler kancayı atlar.
• Yürütme modeli — varsayılan olarak eşzamansız, isteğe bağlı senkron: shouldRunSynchronously bayrağı kurulum sonrası işlemin nasıl yürütüldüğünü kontrol eder.
  • shouldRunSynchronously: false (varsayılan) — kanca, retryLimit: 3 ile mesaj kuyruğuna alınır ve bir worker içinde eşzamansız çalışır. İş kuyruğa alınır alınmaz kurulum yanıtı döner; dolayısıyla yavaşlayan veya hata veren bir işleyici çağıranı engellemez. Worker en fazla üç kez yeniden deneyecektir. Bunu uzun süre çalışan işler için kullanın — büyük veri kümelerini tohumlama, yavaş üçüncü taraf API’lerini çağırma, harici kaynakları sağlama; makul bir HTTP yanıt süresini aşabilecek her şey.
  • shouldRunSynchronously: true — kanca kurulum akışı sırasında satır içi olarak yürütülür (kurulum öncesi ile aynı yürütücü). İşleyici bitene kadar kurulum isteği engellenir; hata fırlatırsa, kurulum çağıranı bir POST_INSTALL_ERROR alır. Otomatik yeniden deneme yok. Bunu, yanıt dönmeden mutlaka tamamlanması gereken hızlı işler için kullanın — örneğin, kullanıcıya bir doğrulama hatası iletmek veya kurulum çağrısı döner dönmez istemcinin ihtiyaç duyacağı hızlı bir kurulum yapmak. Kurulum sonrası çalıştığında, üstveri (metadata) geçişinin zaten uygulanmış olduğunu unutmayın; bu nedenle, senkron moddaki bir hata şema değişikliklerini geri almaz — yalnızca hatayı görünür kılar.
• İşleyicinizin idempotent olduğundan emin olun. Eşzamansız modda kuyruk en fazla üç kez yeniden deneyebilir; her iki modda da shouldRunOnVersionUpgrade: true iken yükseltmelerde kanca tekrar çalışabilir.
• Ortam değişkenleri APPLICATION_ID, APP_ACCESS_TOKEN ve API_URL işleyici içinde kullanılabilir (diğer mantık işlevlerinde olduğu gibi), böylece uygulamanıza özel kapsamda bir uygulama erişim belirteciyle Twenty API’sini çağırabilirsiniz.
• Uygulama başına yalnızca bir kurulum sonrası işlevine izin verilir. Birden fazla tespit edilirse manifest oluşturma hataya düşer.
• İşlevin universalIdentifier, shouldRunOnVersionUpgrade ve shouldRunSynchronously değerleri, derleme sırasında uygulama manifestine postInstallLogicFunction alanı altında otomatik olarak eklenir — bunlara defineApplication() içinde atıfta bulunmanıza gerek yoktur.
• Varsayılan zaman aşımı, veri tohumlama gibi daha uzun kurulum görevlerine izin vermek için 300 saniye (5 dakika) olarak ayarlanmıştır.
• Geliştirme modunda çalıştırılmaz: bir uygulama yerel olarak kaydedildiğinde (yarn twenty dev aracılığıyla), sunucu kurulum akışını tamamen atlar ve dosyaları doğrudan CLI watcher üzerinden eşitler — bu nedenle, shouldRunSynchronously ne olursa olsun, kurulum sonrası geliştirme modunda hiç çalışmaz. Çalışan bir çalışma alanında bunu elle tetiklemek için yarn twenty exec --postInstall kullanın.

import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';

const handler = async (payload: InstallPayload): Promise<void> => {
  console.log('Pre install logic function executed successfully!', payload.previousVersion);
};

export default definePreInstallLogicFunction({
  universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
  name: 'pre-install',
  description: 'Runs before installation to prepare the application.',
  timeoutSeconds: 300,
  shouldRunOnVersionUpgrade: true,
  handler,
});

yarn twenty exec --preInstall

• Kurulum öncesi işlevler definePreInstallLogicFunction() kullanır — kurulum sonrasıyla aynı özel yapılandırma, sadece yaşam döngüsünde farklı bir yuvaya eklenir.
• Hem kurulum öncesi hem de kurulum sonrası işleyiciler aynı InstallPayload türünü alır: { previousVersion?: string; newVersion: string }. Bunu bir kez içe aktarın ve her iki kanca için yeniden kullanın.
• Kanca ne zaman çalışır: çalışma alanı üstveri (metadata) geçişinden hemen önce konumlandırılır (synchronizeFromManifest). Çalıştırmadan önce, sunucu yalnızca ekleyici bir “indirgenmiş eşitleme” yürütür; bu, çalışma alanı üstverisinde yeni sürümün kurulum öncesi işlevini kaydeder — başka hiçbir şeye dokunulmaz — ve ardından bunu yürütür. Bu eşitleme yalnızca ekleyici olduğundan, işleyiciniz çalıştığında önceki sürümün nesneleri, alanları ve verileri hâlâ sağlamdır: geçiş öncesi durumu güvenle okuyabilir ve yedekleyebilirsiniz.
• Yürütme modeli: kurulum öncesi senkron olarak yürütülür ve kurulumu bloklar. İşleyici bir hata fırlatırsa, herhangi bir şema değişikliği uygulanmadan önce kurulum iptal edilir — çalışma alanı, tutarlı bir durumda önceki sürümde kalır. Bu kasıtlıdır: kurulum öncesi, riskli bir yükseltmeyi reddetmek için son şansınızdır.
• Kurulum sonrası ile aynı şekilde, uygulama başına yalnızca bir kurulum öncesi işlevine izin verilir. Derleme sırasında uygulama manifestine preInstallLogicFunction altında otomatik olarak eklenir.
• Geliştirme modunda çalıştırılmaz: kurulum sonrasında olduğu gibi — yerel olarak kaydedilen uygulamalarda kurulum akışı tamamen atlanır, bu nedenle yarn twenty dev altında kurulum öncesi hiç çalışmaz. Bunu elle tetiklemek için yarn twenty exec --preInstall kullanın.

┌─────────────────────────────────────────────────────────────┐
│ install flow                                                │
│                                                             │
│   upload package → [pre-install] → metadata migration →     │
│   generate SDK → [post-install]                             │
│                                                             │
│                  old schema visible    new schema visible   │
└─────────────────────────────────────────────────────────────┘

• Yeni eklenen nesne ve alanlara karşı varsayılan verileri tohumlama (ilk kayıtları, varsayılan görünümleri, demo içeriği oluşturma).
• Uygulamanın kimlik bilgileri artık mevcut olduğuna göre, üçüncü taraf hizmetlerle webhook’ları kaydetmek.
• Eşitlenmiş üstveriye (metadata) bağlı kurulumu tamamlamak için kendi API’nizi çağırmak.
• Her yükseltmede durumu uzlaştırması gereken idempotent “bu mevcut olsun” mantığı — shouldRunOnVersionUpgrade: true ile birleştirin.

import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
import { createClient } from './generated/client';

const handler = async ({ previousVersion }: InstallPayload): Promise<void> => {
  if (previousVersion) return; // fresh installs only

  const client = createClient();
  await client.postCard.create({
    data: { title: 'Welcome to Postcard', content: 'Your first card!' },
  });
};

export default definePostInstallLogicFunction({
  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
  name: 'post-install',
  description: 'Seeds a welcome post card after install.',
  timeoutSeconds: 300,
  shouldRunOnVersionUpgrade: false,
  handler,
});

• Kaldırılmak veya yeniden yapılandırılmak üzere olan verileri yedekleme — örn. v2’de bir alanı kaldırıyorsunuz ve geçiş çalışmadan önce değerlerini başka bir alana kopyalamanız veya depolamaya aktarmanız gerekiyor.
• Yeni bir kısıtın geçersiz kılacağı kayıtları arşivleme — örn. bir alan NOT NULL oluyor ve önce null değerli satırları silmeniz veya düzeltmeniz gerekiyor.
• Uyumluluğu doğrulama ve mevcut veriler temiz bir şekilde geçirilemiyorsa yükseltmeyi reddetme — işleyiciden hata fırlatın ve kurulum, herhangi bir değişiklik uygulanmadan iptal edilir. Bu, uyumsuzluğu geçişin ortasında keşfetmekten daha güvenlidir.
• İlişkilendirmeyi kaybettirecek bir şema değişikliğinden önce verileri yeniden adlandırma veya yeniden anahtarlama.

import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
import { createClient } from './generated/client';

const handler = async ({ previousVersion, newVersion }: InstallPayload): Promise<void> => {
  // Only the 1.x → 2.x upgrade drops the legacy `notes` field.
  if (!previousVersion?.startsWith('1.') || !newVersion.startsWith('2.')) {
    return;
  }

  const client = createClient();
  const legacyRecords = await client.postCard.findMany({
    where: { notes: { isNotNull: true } },
  });

  if (legacyRecords.length === 0) return;

  // Copy legacy `notes` into the new `description` field before the migration
  // drops the `notes` column. If this fails, the upgrade is aborted and the
  // workspace stays on v1 with all data intact.
  await Promise.all(
    legacyRecords.map((record) =>
      client.postCard.update({
        where: { id: record.id },
        data: { description: record.notes },
      }),
    ),
  );
};

export default definePreInstallLogicFunction({
  universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
  name: 'pre-install',
  description: 'Backs up legacy notes into description before the v2 migration.',
  timeoutSeconds: 300,
  shouldRunOnVersionUpgrade: true,
  handler,
});

import { CoreApiClient } from 'twenty-client-sdk/core';

const client = new CoreApiClient();

// Query records
const { companies } = await client.query({
  companies: {
    edges: {
      node: {
        id: true,
        name: true,
        domainName: {
          primaryLinkLabel: true,
          primaryLinkUrl: true,
        },
      },
    },
  },
});

// Create a record
const { createCompany } = await client.mutation({
  createCompany: {
    __args: {
      data: {
        name: 'Acme Corp',
      },
    },
    id: true,
    name: true,
  },
});

​

Tür açıklamaları için CoreSchema’yı kullanma

import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
import { useState } from 'react';

const [company, setCompany] = useState<
  Pick<CoreSchema.Company, 'id' | 'name'> | undefined
>(undefined);

const client = new CoreApiClient();
const result = await client.query({
  company: {
    __args: { filter: { position: { eq: 1 } } },
    id: true,
    name: true,
  },
});
setCompany(result.company);

import { MetadataApiClient } from 'twenty-client-sdk/metadata';

const metadataClient = new MetadataApiClient();

// List first 10 objects in the workspace
const { objects } = await metadataClient.query({
  objects: {
    edges: {
      node: {
        id: true,
        nameSingular: true,
        namePlural: true,
        labelSingular: true,
        isCustom: true,
      },
    },
    __args: {
      filter: {},
      paging: { first: 10 },
    },
  },
});

​

Dosya yükleme

import { MetadataApiClient } from 'twenty-client-sdk/metadata';
import * as fs from 'fs';

const metadataClient = new MetadataApiClient();

const fileBuffer = fs.readFileSync('./invoice.pdf');

const uploadedFile = await metadataClient.uploadFile(
  fileBuffer,                                         // file contents as a Buffer
  'invoice.pdf',                                      // filename
  'application/pdf',                                  // MIME type
  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
);

console.log(uploadedFile);
// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }

• Alan için universalIdentifier kullanır (çalışma alanına özgü kimliği değil), böylece yükleme kodunuz uygulamanızın yüklü olduğu herhangi bir çalışma alanında çalışır.
• Döndürülen url, yüklenen dosyaya erişmek için kullanabileceğiniz imzalı bir URL’dir.