Mantıksal işlevler

Sunucu tarafı TypeScript işlevlerini HTTP, cron ve veritabanı olay tetikleyicileriyle tanımlayın.

Mantık işlevleri, Twenty platformunda çalışan sunucu tarafı TypeScript işlevleridir. HTTP istekleri, cron zamanlamaları veya veritabanı olayları tarafından tetiklenebilirler — ve ayrıca yapay zekâ ajanları için araçlar olarak sunulabilirler.

defineLogicFunction

Mantık işlevlerini ve tetikleyicilerini tanımlayın

Her işlev dosyası, bir işleyici ve isteğe bağlı tetikleyiciler içeren bir yapılandırmayı dışa aktarmak için defineLogicFunction() kullanır.

src/logic-functions/createPostCard.logic-function.ts

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 body = (params.body ?? {}) as { name?: string };
  const name = body.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? '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: 'POST',
    isAuthRequired: true,
  },
  /*databaseEventTriggerSettings: {
    eventName: 'people.created',
  },*/
  /*cronTriggerSettings: {
    pattern: '0 0 1 1 *',
  },*/
});

Kullanılabilir tetikleyici türleri:

• httpRoute: İşlevinizi 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 işlevinizi 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 işlevi tetikler.

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

Bir işlevi CLI kullanarak manuel olarak da çalıştırabilirsiniz:

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

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

Günlükleri şu şekilde izleyebilirsiniz:

yarn twenty logs

​

Rota tetikleyicisi yükü

Bir rota tetikleyicisi mantık fonksiyonunuzu çağırdığında, AWS HTTP API v2 formatını izleyen bir RoutePayload nesnesi alır. RoutePayload türünü twenty-sdk içinden içe aktarın:

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' };
};

RoutePayload türünün yapısı şu şekildedir:

Özellik	Tür	Açıklama	Örnek
headers	Record\<string, string | undefined>	HTTP başlıkları (forwardedRequestHeaders içinde listelenenlerle sınırlı)	aşağıdaki bölüme bakın
queryStringParameters	Record\<string, string | undefined>	Sorgu dizesi parametreleri (birden çok değer virgülle birleştirilir)	/users?ids=1&ids=2&ids=3&name=Alice -> { ids: '1,2,3', name: 'Alice' }
pathParameters	Record\<string, string | undefined>	Rota deseninden çıkarılan yol parametreleri	/users/:id, /users/123 -> { id: '123' }
body	object | null	Ayrıştırılmış istek gövdesi (JSON)	{ id: 1 } -> { id: 1 }
rawBody	string | undefined	JSON ayrıştırılmadan önceki özgün UTF-8 istek gövdesi. HMAC tarzı webhook imzalarını doğrulamak için kullanışlıdır (ör. GitHub’ın X-Hub-Signature-256, Stripe). Çalışma zamanı onu korumadığında undefined olur.
isBase64Encoded	boolean	Gövdenin base64 ile kodlanıp kodlanmadığı
requestContext.http.method	string	HTTP yöntemi (GET, POST, PUT, PATCH, DELETE)
requestContext.http.path	string	Ham istek yolu

​

forwardedRequestHeaders

Varsayılan olarak, güvenlik nedenleriyle gelen isteklerden HTTP başlıkları mantık fonksiyonunuza aktarılmaz. Belirli başlıklara erişmek için bunları forwardedRequestHeaders dizisinde listeleyin:

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'],
  },
});

İşleyicinizde, iletilen başlıklara şu şekilde erişin:

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

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

Başlık adları küçük harfe normalize edilir. Onlara küçük harfli anahtarlarla erişin (örneğin, event.headers['content-type']).

​

Bir işlevi bir yapay zekâ aracı veya iş akışı eylemi olarak kullanıma sunma

Mantık işlevleri, her birinin kendi tetikleyicisi olacak şekilde iki yerde kullanılabilir hâle getirilebilir:

• toolTriggerSettings — işlevi Twenty’nin yapay zekâ özellikleri (sohbet, MCP, işlev çağırma) tarafından bulunabilir hâle getirir. Standart JSON Şeması’nı kullanır; LLM’lerin doğal olarak anladığı biçimdir.
• workflowActionTriggerSettings — işlevin görsel iş akışı oluşturucusunda bir adım olarak görünmesini sağlar. Oluşturucunun uygun alan düzenleyicilerini, değişken seçicilerini ve etiketleri oluşturabilmesi için Twenty’nin zengin InputSchema’sını kullanır.

Bir işlev bunlardan birini, diğerini veya her ikisini de tercih edebilir. Bunlar, cronTriggerSettings, databaseEventTriggerSettings ve httpRouteTriggerSettings ile birlikte yer alır — aynı desen, aynı biçim.

src/logic-functions/enrich-company.logic-function.ts

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,
  toolTriggerSettings: {},
});

Önemli noktalar:

• Bir işlev yüzeyleri karıştırabilir — onu sohbette VE iş akışı oluşturucusunda kullanıma sunmak için hem toolTriggerSettings hem de workflowActionTriggerSettings bildirin.
• toolTriggerSettings.inputSchema ve workflowActionTriggerSettings.inputSchema ikisi de isteğe bağlıdır. Atlandığında, manifest oluşturucu bunları işleyici kaynak kodundan çıkarır (yapay zekâ aracı için JSON Şeması, iş akışı eylemi için Twenty’nin InputSchema’sı). Daha zengin tipleme istediğinizde birini açıkça belirtin — örneğin, iş akışı oluşturucu için FieldMetadataType’ı bilen CURRENCY veya RELATION gibi alanlarla ya da yapay zekâ aracısının okuyabileceği description alanlarıyla:

export default defineLogicFunction({
  ...,
  toolTriggerSettings: {
    inputSchema: {
      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'],
    },
  },
});

İyi bir description yazın. AI ajanları, aracı ne zaman kullanacaklarına karar vermek için işlevin description alanına güvenir. Aracın ne yaptığını ve ne zaman çağrılması gerektiğini açıkça belirtin.

Yükleme kancaları — ön yükleme ve yükleme sonrası işleyiciler — bu çalışma zamanını paylaşır ancak kendi tanımlama işlevleriyle bildirilir ve tetikleyici ayarlarını almaz. definePreInstallLogicFunction ve definePostInstallLogicFunction için Yükleme Kancaları bölümüne bakın.

​

Tipli API istemcileri (twenty-client-sdk)

twenty-client-sdk paketi, mantık fonksiyonlarınızdan ve ön uç bileşenlerinizden Twenty API ile etkileşim kurmak için tip tanımlı iki GraphQL istemcisi sağlar.

İstemci	İçe Aktar	Uç nokta	Oluşturuldu mu?
CoreApiClient	twenty-client-sdk/core	/graphql — çalışma alanı verileri (kayıtlar, nesneler)	Evet, geliştirme/derleme zamanında
MetadataApiClient	twenty-client-sdk/metadata	/metadata — çalışma alanı yapılandırması, dosya yüklemeleri	Hayır, önceden hazırlanmış olarak gelir

CoreApiClient

Çalışma alanı verilerini sorgulayın ve değiştirin (kayıtlar, nesneler)

CoreApiClient, çalışma alanı verilerini sorgulamak ve değiştirmek için ana istemcidir. yarn twenty dev veya yarn twenty build sırasında çalışma alanı şemanızdan oluşturulur, bu nedenle nesnelerinize ve alanlarınıza uyacak şekilde tamamen tiplenmiştir.

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,
  },
});

İstemci bir seçim kümesi sözdizimi kullanır: Bir alanı dahil etmek için true geçin, bağımsız değişkenler için __args kullanın ve ilişkiler için nesneleri iç içe yerleştirin. Çalışma alanı şemanıza göre tam otomatik tamamlama ve tip denetimi elde edersiniz.

CoreApiClient geliştirme/derleme zamanında oluşturulur. Bunu önce yarn twenty dev veya yarn twenty build çalıştırmadan kullanırsanız, bir hata verir. Oluşturma otomatik olarak gerçekleşir — CLI, çalışma alanınızın GraphQL şemasını inceler ve @genql/cli kullanarak tiplenmiş bir istemci üretir.

​

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

CoreSchema, çalışma alanı nesnelerinize uyan TypeScript türleri sağlar — bileşen durumunu veya işlev parametrelerini tiplemek için kullanışlıdır:

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);

MetadataApiClient

Çalışma alanı yapılandırması, uygulamalar ve dosya yüklemeleri

MetadataApiClient, SDK ile birlikte önceden hazırlanmış olarak gelir (oluşturma gerektirmez). Çalışma alanı yapılandırması, uygulamalar ve dosya yüklemeleri için /metadata uç noktasını sorgular.

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

MetadataApiClient, dosya türündeki alanlara dosya eklemek için bir uploadFile yöntemi içerir:

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://...' }

Parametre	Tür	Açıklama
fileBuffer	Buffer	Dosyanın ham içeriği
filename	string	Dosyanın adı (depolama ve görüntüleme için kullanılır)
contentType	string	MIME türü (belirtilmezse varsayılan olarak application/octet-stream kullanılır)
fieldMetadataUniversalIdentifier	string	Nesnenizdeki dosya türü alanının universalIdentifier değeri

Önemli noktalar:

• 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.

Kodunuz Twenty üzerinde çalıştığında (mantık işlevleri veya ön uç bileşenleri), platform kimlik bilgilerini ortam değişkenleri olarak enjekte eder:

• TWENTY_API_URL — Twenty API’nin temel URL’si
• TWENTY_APP_ACCESS_TOKEN — Uygulamanızın varsayılan işlev rolü kapsamında kısa ömürlü bir anahtar

Bunları istemcilere iletmeniz gerekmez — otomatik olarak process.env’den okurlar. API anahtarının izinleri, defineApplicationRole() ile bildirilen role (veya application-config.ts içindeki defaultRoleUniversalIdentifier üzerinden referans verilen role) göre belirlenir.