The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
i18n - docs translations (#24529)
github-actions[bot]e9d63e73dfd3
diff --git a/packages/twenty-docs/l/ar/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/ar/developers/extend/apps/config/application.mdxindex 0fbf52580cb..361b061a252 100644--- a/packages/twenty-docs/l/ar/developers/extend/apps/config/application.mdx+++ b/packages/twenty-docs/l/ar/developers/extend/apps/config/application.mdx@@ -97,7 +97,7 @@ const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3يتحكم الدور المعلن باستخدام [`defineApplicationRole()`](/l/ar/developers/extend/apps/config/roles) في ما يمكن لوظائف منطق التطبيق ومكوّنات الواجهة الوصول إليه:-* رمز وقت التشغيل المحقون باسم `TWENTY_APP_ACCESS_TOKEN` مستمد من هذا الدور.+* رموز وقت التشغيل المحقونة في دوال المنطق لديك مستمدة من هذا الدور. تُقيَّد المكالمة التي تتصرف كشخص بشكل أكبر بما يمكن لذلك الشخص القيام به، لذا لا يمكنها أبدًا تجاوز أيٍّ منهما. راجع [صلاحيات الوصول التي تستخدمها المكالمة](/l/ar/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* يكون عميل واجهة برمجة التطبيقات مضبوط الأنواع مقيّدًا بالأذونات الممنوحة لذلك الدور.* اتبع مبدأ أقل امتياز: صرّح فقط عن الأذونات التي تحتاجها دوالك.diff --git a/packages/twenty-docs/l/ar/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/l/ar/developers/extend/apps/getting-started/concepts.mdxindex fbcb0fdcab5..1d3573c2f0b 100644--- a/packages/twenty-docs/l/ar/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/l/ar/developers/extend/apps/getting-started/concepts.mdx@@ -54,9 +54,9 @@ your-app/## العزل-* **الدوال المنطقية** تعمل في عمليات Node.js معزولة على الخادم. لا تصل إلى البيانات إلا عبر عميل API مضبوط الأنواع، ومقيَّد بأذونات دور التطبيق.+* **الدوال المنطقية** تعمل في عمليات Node.js معزولة على الخادم. لا تصل إلى البيانات إلا من خلال عميل API مكتوب الأنواع، الذي يعمل إما بصفة الشخص الذي بدأ التشغيل أو بصفة التطبيق نفسه. راجع [صلاحيات الوصول التي تستخدمها الاستدعاءات](/l/ar/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* **المكوّنات الأمامية** تعمل ضمن Web Workers باستخدام Remote DOM — معزولة عن الصفحة الرئيسية لكنها تعرض عناصر DOM الأصلية (وليس iframes). تتواصل مع Twenty عبر واجهة API للمضيف تعتمد تمرير الرسائل.-* **الأذونات** تُطبَّق على مستوى واجهة API. يُشتق رمز وقت التشغيل (`TWENTY_APP_ACCESS_TOKEN`) من الدور المعرَّف في `defineApplication()`.+* **الأذونات** تُطبَّق على مستوى واجهة API. يتم إدخال رمزي تشغيل، وكلاهما مشتق من الدور المُعلن باستخدام `defineApplicationRole()`؛ ويُقيَّد الرمز الافتراضي بشكل أكبر بما يستطيع الشخص الذي بدأ التشغيل القيام به كلما كان هناك شخص وراء التشغيل.## دورة حياة التطبيقdiff --git a/packages/twenty-docs/l/ar/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/ar/developers/extend/apps/layout/front-components.mdxindex 15e5140c569..ed26a6ba74e 100644--- a/packages/twenty-docs/l/ar/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/l/ar/developers/extend/apps/layout/front-components.mdx@@ -333,6 +333,8 @@ export default defineLogicFunction({لاستدعاء مسارات HTTP الخاصة بالتطبيق أو لقراءة سجلات Twenty وكتابتها من مكوِّن واجهة أمامية، استخدم `RestApiClient` من `twenty-client-sdk/rest`. يُرسل المسارات من نوع `/s/...` إلى عنوان URL الأساسي للدوال في مساحة العمل الخاصة بك، ويُرسل أي مسار آخر، بما في ذلك `/rest/...`، إلى `TWENTY_API_URL`.+يتصرف دائمًا بصفته الشخص الذي ينظر إلى الصفحة. `runAs: 'application'` هو خيار لدالة منطقية فقط: لا يتلقى المكوّن أبدًا الرمز المميز الخاص بتطبيقك، لذا فإن طلبه هنا يؤدي إلى طرح استثناء. ضع العمل الذي يحتاج إلى وصول التطبيق الخاص خلف دالة منطقية واستدعها بدلًا من ذلك.+| طريقة | الوصف || --------------------------------- | ----------------------------------------------------------------------- || `get(path, options?)` | يرسل طلبًا من نوع `GET` |@@ -445,10 +447,10 @@ export default defineFrontComponent({متغيرات النظام التالية تكون متاحة دائمًا عبر `process.env`:-| المتغيّر | الوصف |-| ------------------------- | --------------------------------------- |-| `TWENTY_API_URL` | عنوان URL الأساسي لـ Twenty Core API |-| `TWENTY_APP_ACCESS_TOKEN` | رمز مميز قصير العمر مُقيَّد بدور تطبيقك |+| المتغيّر | الوصف |+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `TWENTY_API_URL` | عنوان URL الأساسي لـ Twenty Core API |+| `TWENTY_APP_ACCESS_TOKEN` | رمز مميز قصير العمر يقتصر نطاقه على دور الشخص المسجّل دخوله والمتقاطع مع دور تطبيقك، لذا لا يمكن للمكوّن أبدًا أن يفعل أكثر مما يستطيع الشخص الذي ينظر إليه فعله |### `TWENTY_FUNCTIONS_URL`diff --git a/packages/twenty-docs/l/ar/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/l/ar/developers/extend/apps/logic/logic-functions.mdxindex e02d06eae96..8e4d3daf9b5 100644--- a/packages/twenty-docs/l/ar/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/l/ar/developers/extend/apps/logic/logic-functions.mdx@@ -447,6 +447,78 @@ const handler = async (event: PersonDestroyedEvent) => {};```+#### سياق التنفيذ++يتلقى كل معالج وسيطًا ثانيًا يصف عملية التشغيل نفسها، بغض النظر عما شغّلها. بينما يتغير شكل الوسيط الأول بحسب المُشغِّل، لا يتغير شكل هذا الوسيط:++```ts+import type { LogicFunctionExecutionContext } from 'twenty-sdk/logic-function';++const handler = async (+ event: DatabaseEventPayload,+ { workspaceId, workspaceMemberId }: LogicFunctionExecutionContext,+) => {+ if (workspaceMemberId === null) {+ throw new Error('This function must be triggered by a person');+ }++ return { reviewedBy: workspaceMemberId, workspaceId };+};+```++| الحقل | النوع | الوصف |+| ------------------- | ---------------- | --------------------------------------------------------------------------------------------- |+| `workspaceId` | `string` | مساحة العمل التي تنتمي إليها عملية التشغيل. |+| `userWorkspaceId` | `string \| null` | الشخص الذي شغّل عملية التشغيل، ممثلًا بعضويته في مساحة العمل هذه. |+| `workspaceMemberId` | `string \| null` | الشخص نفسه بصفته سجل عضو في مساحة العمل، وهو ما تربط السجلات به. |+| `retryCount` | `number` | `0` في المحاولة الأولى. راجع [المهام الخلفية](/l/ar/developers/extend/apps/logic/background-jobs). |+| `maxRetries` | `number` | الحد الأقصى لعمليات إعادة المحاولة التي يطلبها التطبيق. |++يكون `userWorkspaceId` و`workspaceMemberId` بقيمة `null` عندما لا يشغّل أحد عملية التشغيل: فلا توجد جهة خلف جداول cron وخطافات التثبيت وخطافات الويب غير الموثقة. ويكونان أيضًا بقيمة `null` عندما لا يكون لدى الشخص سجل عضو في مساحة العمل، أو عندما يكون سجله قد حُذف.++<Note>+**يخبرك السياق بمن شغّل عملية التشغيل.** أما ما قد *تفعله* عملية التشغيل فهو تعريف منفصل أدناه.+</Note>++#### أذونات الوصول التي تستخدمها المكالمة++يتصرف كل عميل — `CoreApiClient` و`MetadataApiClient` و`RestApiClient` — بصفته الشخص الذي شغّل عملية التشغيل: إذ يتقاطع دوره مع دور تطبيقك، لذا لا يمكن للمكالمة أبدًا أن تفعل أكثر مما يسمح به أيّ منكما. هذا هو السلوك الافتراضي، ويعني أنه لا يمكن للشخص أبدًا استخدام تطبيقك لتجاوز أذوناته الخاصة.++عندما لا يشغّل أحد عملية التشغيل، لا يوجد شخص للتصرف بصفته، لذا يعود العميل نفسه إلى أذونات الوصول الخاصة بتطبيقك: لا تحتاج جداول cron وخطافات التثبيت وخطافات الويب غير الموثقة إلى معالجة خاصة.++تحتاج بعض المكالمات بصورة مشروعة إلى أذونات الوصول الخاصة بالتطبيق حتى عندما يكون هناك شخص *خلف* عملية التشغيل — مثل قراءة سجلات إعدادات تطبيقك، أو تنفيذ عمل لا يستطيع ذلك الشخص تنفيذه بنفسه. أنشئ عميلاً ثانيًا لهذه الحالات:++```ts+import { CoreApiClient } from 'twenty-client-sdk/core';++const asPerson = new CoreApiClient();+const asApplication = new CoreApiClient({ runAs: 'application' });++const handler = async (event: DatabaseEventPayload) => {+ // config records only your app may read+ const { slackUserLinks } = await asApplication.query({ ... });++ // created as the person, so it is attributed and permission-checked+ await asPerson.mutation({ createNote: { ... } });+};+```++أنشئ كليهما مرة واحدة، في نطاق الوحدة، ثم يحدد كل موضع استدعاء أذونات الوصول التي يستخدمها من خلال العميل الذي يستدعيه. يأخذ `RestApiClient` الخيار نفسه:++```ts+import { RestApiClient } from 'twenty-client-sdk/rest';++const asApplication = new RestApiClient({ runAs: 'application' });+```++<Note>+**عملية التشغيل التي لم يشغّلها أحد تتصرف بصفتها تطبيقك.** لا يوجد شخص خلف جداول cron وخطافات التثبيت وخطافات الويب غير الموثقة، لذا يعود العميل الافتراضي إلى أذونات الوصول الخاصة بتطبيقك ويستمر في العمل. لا يلزم استخدام `runAs: 'application'` إلا عندما تريد أذونات الوصول تلك في عملية تشغيل شغّلها شخص *بالفعل*.++تحقق من `context.workspaceMemberId` عندما تتصرف دالة بشكل مختلف بناءً على وجود شخص خلفها، على سبيل المثال لإسناد سجل.+</Note>++تستخدم مساعدات SDK التي تصل إلى موارد تطبيقك الخاصة أذونات الوصول الخاصة به دائمًا وتتجاهل `runAs`: وهي [مخزن المفتاح-القيمة](/l/ar/developers/extend/apps/logic/key-value-store) و[الاتصالات](/l/ar/developers/extend/apps/logic/connections) و`runAgent` و`getPublicAssetUrl` وفرض رسوم الأرصدة.+#### إتاحة دالة كأداة ذكاء اصطناعي أو كإجراء ضمن سير العمليمكن إتاحة دوال المنطق على واجهتين، ولكلٍ منهما مشغِّل خاص به:@@ -722,7 +794,7 @@ setCompany(result.company);</Accordion><Accordion title="MetadataApiClient" description="إعدادات مساحة العمل، والتطبيقات، ورفع الملفات">-يأتي `MetadataApiClient` مُجهّزًا مسبقًا مع SDK (لا حاجة للتوليد). يستعلم عن نقطة النهاية `/metadata` للحصول على تكوين مساحة العمل والتطبيقات ورفع الملفات.+يأتي `MetadataApiClient` مُجهّزًا مسبقًا مع SDK (لا حاجة للتوليد). يستعلم عن نقطة النهاية `/metadata` للحصول على تكوين مساحة العمل والتطبيقات ورفع الملفات. يأخذ خيار `runAs` نفسه الذي يأخذه `CoreApiClient` — راجع [أذونات الوصول التي تستخدمها المكالمة](#whose-access-a-call-uses).```tsimport { MetadataApiClient } from 'twenty-client-sdk/metadata';@@ -775,8 +847,8 @@ console.log(uploadedFile);| المعلمة | النوع | الوصف || ---------------------------------- | ------------ | ---------------------------------------------------------------------- || `fileBuffer` | `Buffer` | المحتوى الخام للملف |-| `filename` | `string` | اسم الملف (يُستخدم للتخزين والعرض) |-| `contentType` | `سلسلة نصية` | نوع MIME (القيمة الافتراضية `application/octet-stream` إذا لم يُحدَّد) |+| `filename` | `سلسلة نصية` | اسم الملف (يُستخدم للتخزين والعرض) |+| `contentType` | `string` | نوع MIME (القيمة الافتراضية `application/octet-stream` إذا لم يُحدَّد) || `fieldMetadataUniversalIdentifier` | `string` | قيمة `universalIdentifier` لحقل نوع الملف في كائنك |النقاط الرئيسية:@@ -790,7 +862,8 @@ console.log(uploadedFile);عند تشغيل كودك على Twenty (وظائف منطقية أو مكوّنات أمامية)، يقوم النظام الأساسي بحقن بيانات الاعتماد كمتغيرات بيئية:* `TWENTY_API_URL` — عنوان URL الأساسي لواجهة Twenty البرمجية- * `TWENTY_APP_ACCESS_TOKEN` — مفتاح قصير العمر ذو نطاق يقتصر على الدور الافتراضي لوظيفة تطبيقك+ * `TWENTY_APP_ACCESS_TOKEN` — مفتاح قصير العمر لأذونات الوصول الافتراضية: دور الشخص متقاطعًا مع دور تطبيقك عندما يكون هناك شخص خلف عملية التشغيل، ودور تطبيقك الخاص عندما لا يكون هناك أحد. الشخص هو من شغّل عملية التشغيل في دالة منطقية، أو من ينظر إلى الصفحة في مكوّن أمامي.+ * `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — مفتاح قصير العمر يقتصر نطاقه على دور تطبيقك الخاص وحده. للدوال المنطقية فقط، ويُحقن فيها دائمًا، وهو ما يستخدمه `runAs: 'application'`.- لست **بحاجة** إلى تمرير هذه القيم إلى العملاء — فهي تُقرأ تلقائيًا من `process.env`. تُحدَّد أذونات مفتاح واجهة برمجة التطبيقات بواسطة الدور المُعلن باستخدام `defineApplicationRole()` (أو المشار إليه عبر `defaultRoleUniversalIdentifier` في `application-config.ts`).+ **لا** تحتاج إلى تمرير هذه إلى العملاء — فهم يقرؤون من `process.env` تلقائيًا، ويغطي [أذونات الوصول التي تستخدمها المكالمة](#whose-access-a-call-uses) الاختيار بينها. تُحدَّد أذونات تطبيقك الخاصة بواسطة الدور المُعلن باستخدام `defineApplicationRole()` (أو المشار إليه عبر `defaultRoleUniversalIdentifier` في `application-config.ts`)؛ ولا يمكن لعملية تشغيل تتصرف بصفة شخص أن تتجاوز ذلك الدور أو دوره.</Note>diff --git a/packages/twenty-docs/l/cs/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/cs/developers/extend/apps/config/application.mdxindex 67b848ac278..44179e4c73d 100644--- a/packages/twenty-docs/l/cs/developers/extend/apps/config/application.mdx+++ b/packages/twenty-docs/l/cs/developers/extend/apps/config/application.mdx@@ -97,7 +97,7 @@ Totéž platí pro frontendové komponenty, které čtou hodnoty pomocí `getAppRole deklarovaná pomocí [`defineApplicationRole()`](/l/cs/developers/extend/apps/config/roles) určuje, k čemu mají přístup logické funkce a front-endové komponenty aplikace:-* Běhový token vložený jako `TWENTY_APP_ACCESS_TOKEN` je odvozen z této role.+* Běhové tokeny vložené do vašich logických funkcí jsou odvozeny z této role. Volání jednající jako osoba je dále omezeno tím, co tato osoba může dělat, takže nikdy nemůže překročit ani jedno z těchto oprávnění. Vizte [Čí přístup volání používá](/l/cs/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* Typovaný klient API je omezen na oprávnění udělená této roli.* Dodržujte princip nejmenších oprávnění: deklarujte pouze ta oprávnění, která vaše funkce potřebují.diff --git a/packages/twenty-docs/l/cs/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/l/cs/developers/extend/apps/getting-started/concepts.mdxindex 8b22bc35c15..1acd135ff5e 100644--- a/packages/twenty-docs/l/cs/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/l/cs/developers/extend/apps/getting-started/concepts.mdx@@ -54,9 +54,9 @@ your-app/## Izolace (sandboxing)-* **Logické funkce** běží v izolovaných procesech Node.js na serveru. K datům přistupují pouze prostřednictvím typovaného klienta API, a to v rozsahu oprávnění role aplikace.+* **Logické funkce** běží v izolovaných procesech Node.js na serveru. K datům přistupují pouze prostřednictvím typovaného klienta API, který vystupuje buď jako osoba, jež spuštění vyvolala, nebo jako samotná aplikace. Viz [čí přístup volání používá](/l/cs/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* **Frontendové komponenty** běží ve Web Workerech s využitím Remote DOM — jsou oddělené od hlavní stránky, ale vykreslují nativní prvky DOM (nikoli iframy). Komunikují s Twenty prostřednictvím hostitelského API pro předávání zpráv.-* **Oprávnění** jsou vynucována na úrovni API. Běhový token (`TWENTY_APP_ACCESS_TOKEN`) je odvozen z role definované v `defineApplication()`.+* **Oprávnění** jsou vynucována na úrovni API. Vkládají se dva tokeny běhového prostředí, oba odvozené z role deklarované pomocí `defineApplicationRole()`; výchozí token je dále omezen na to, co může provést osoba, která spuštění vyvolala, kdykoli za spuštěním stojí nějaká osoba.## Životní cyklus aplikacediff --git a/packages/twenty-docs/l/cs/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/cs/developers/extend/apps/layout/front-components.mdxindex 9aafc3edbe5..1af3bb43e13 100644--- a/packages/twenty-docs/l/cs/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/l/cs/developers/extend/apps/layout/front-components.mdx@@ -333,6 +333,8 @@ export default defineLogicFunction({Pro volání aplikačních HTTP tras nebo čtení a zápis záznamů Twenty z front komponenty použijte `RestApiClient` z `twenty-client-sdk/rest`. Odesílá cesty `/s/...` na základní URL funkcí vašeho workspace a všechny ostatní cesty, včetně `/rest/...`, na `TWENTY_API_URL`.+Vždy jedná jako osoba, která si stránku prohlíží. `runAs: 'application'` je pouze volba funkce logiky: komponenta nikdy neobdrží vlastní token vaší aplikace, takže požadavek na něj zde vyvolá chybu. Práci, která vyžaduje vlastní přístup aplikace, vložte do funkce logiky a místo toho volejte ji.+| Metoda | Popis || --------------------------------- | -------------------------------------------------------------------- || `get(path, options?)` | Odešle požadavek `GET` |@@ -445,10 +447,10 @@ Tajné proměnné (`isSecret: true`) **nejsou** zpřístupněny front-endovým kNásledující systémové proměnné jsou vždy dostupné přes `process.env`:-| Proměnná | Popis |-| ------------------------- | -------------------------------------------------------------- |-| `TWENTY_API_URL` | Základní URL Twenty core API |-| `TWENTY_APP_ACCESS_TOKEN` | Krátkodobý token s oprávněními omezenými na roli vaší aplikace |+| Proměnná | Popis |+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `TWENTY_API_URL` | Základní URL Twenty core API |+| `TWENTY_APP_ACCESS_TOKEN` | Krátkodobý token s rozsahem oprávnění omezeným na roli přihlášené osoby v průniku s rolí vaší aplikace, takže komponenta nikdy nemůže dělat víc než osoba, která si ji prohlíží |### `TWENTY_FUNCTIONS_URL`diff --git a/packages/twenty-docs/l/cs/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/l/cs/developers/extend/apps/logic/logic-functions.mdxindex f6662a3b241..58b718148a6 100644--- a/packages/twenty-docs/l/cs/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/l/cs/developers/extend/apps/logic/logic-functions.mdx@@ -448,6 +448,78 @@ const handler = async (event: PersonDestroyedEvent) => {};```+#### Kontext provádění++Každá obslužná funkce obdrží druhý argument popisující samotný běh bez ohledu na to, co jej spustilo. Zatímco tvar prvního argumentu se liší podle spouštěče, tento se nemění:++```ts+import type { LogicFunctionExecutionContext } from 'twenty-sdk/logic-function';++const handler = async (+ event: DatabaseEventPayload,+ { workspaceId, workspaceMemberId }: LogicFunctionExecutionContext,+) => {+ if (workspaceMemberId === null) {+ throw new Error('This function must be triggered by a person');+ }++ return { reviewedBy: workspaceMemberId, workspaceId };+};+```++| Pole | Typ | Popis |+| ------------------- | ---------------- | -------------------------------------------------------------------------------------------- |+| `workspaceId` | `string` | Pracovní prostor, ke kterému běh patří. |+| `userWorkspaceId` | `string \| null` | Osoba, která běh spustila, jako její členství v tomto pracovním prostoru. |+| `workspaceMemberId` | `string \| null` | Tatáž osoba jako záznam člena pracovního prostoru, což je to, k čemu propojujete záznamy. |+| `retryCount` | `number` | `0` při prvním pokusu. Viz [Úlohy na pozadí](/l/cs/developers/extend/apps/logic/background-jobs). |+| `maxRetries` | `number` | Horní limit opakovaných pokusů požadovaných aplikací. |++`userWorkspaceId` a `workspaceMemberId` mají hodnotu `null`, když běh nikdo nespustil: plány cron, hooky instalace a neověřené webhooky za sebou nemají žádnou osobu. Hodnotu `null` mají také tehdy, když osoba nemá záznam člena pracovního prostoru nebo když byl její záznam odstraněn.++<Note>+**Kontext vám sdělí, kdo běh spustil.** To, co běh smí *dělat*, je samostatná deklarace uvedená níže.+</Note>++#### Čí přístup volání používá++Každý klient — `CoreApiClient`, `MetadataApiClient` a `RestApiClient` — jedná jako osoba, která běh spustila: její role se protíná s rolí vaší aplikace, takže volání nikdy nemůže udělat více, než může kterýkoli z vás. Toto je výchozí chování a znamená, že osoba nikdy nemůže použít vaši aplikaci k překročení vlastních oprávnění.++Když běh nikdo nespustil, není žádná osoba, za kterou by bylo možné jednat, takže stejný klient přejde na vlastní přístup vaší aplikace: plány cron, hooky instalace a neověřené webhooky nevyžadují zvláštní zpracování.++Některá volání oprávněně potřebují vlastní přístup aplikace, i když za během *je* osoba — například pro čtení konfiguračních záznamů vaší aplikace nebo provádění práce, kterou by tato osoba sama nemohla vykonat. Pro tyto případy vytvořte druhého klienta:++```ts+import { CoreApiClient } from 'twenty-client-sdk/core';++const asPerson = new CoreApiClient();+const asApplication = new CoreApiClient({ runAs: 'application' });++const handler = async (event: DatabaseEventPayload) => {+ // config records only your app may read+ const { slackUserLinks } = await asApplication.query({ ... });++ // created as the person, so it is attributed and permission-checked+ await asPerson.mutation({ createNote: { ... } });+};+```++Oba vytvořte jednou v rozsahu modulu a každé místo volání pak podle volaného klienta určí, který přístup používá. `RestApiClient` přijímá stejnou možnost:++```ts+import { RestApiClient } from 'twenty-client-sdk/rest';++const asApplication = new RestApiClient({ runAs: 'application' });+```++<Note>+**Běh, který nikdo nespustil, jedná jako vaše aplikace.** Plány cron, hooky instalace a neověřené webhooky za sebou nemají žádnou osobu, takže výchozí klient přejde na vlastní přístup vaší aplikace a nadále funguje. `runAs: 'application'` je potřeba jen tehdy, když tento přístup chcete při běhu, který osoba *skutečně* spustila.++Když se funkce chová odlišně podle toho, zda za ní někdo stojí, zkontrolujte `context.workspaceMemberId`, například pro přiřazení záznamu.+</Note>++Pomocné funkce SDK, které přistupují k vlastním prostředkům vaší aplikace, vždy používají její přístup a ignorují `runAs`: [úložiště klíč-hodnota](/l/cs/developers/extend/apps/logic/key-value-store), [připojení](/l/cs/developers/extend/apps/logic/connections), `runAgent`, `getPublicAssetUrl` a účtování kreditů.+#### Zpřístupnění funkce jako nástroje AI nebo akce pracovního postupuLogické funkce lze zpřístupnit na dvou rozhraních, z nichž každé má vlastní spouštěč:@@ -723,7 +795,7 @@ setCompany(result.company);</Accordion><Accordion title="MetadataApiClient" description="Konfigurace pracovního prostoru, aplikace a nahrávání souborů">-`MetadataApiClient` je dodáván předem sestavený v rámci SDK (není vyžadováno žádné generování). Odesílá dotazy na endpoint `/metadata` pro konfiguraci pracovního prostoru, aplikace a nahrávání souborů.+`MetadataApiClient` je dodáván předem sestavený v rámci SDK (není vyžadováno žádné generování). Odesílá dotazy na endpoint `/metadata` pro konfiguraci pracovního prostoru, aplikace a nahrávání souborů. Přijímá stejnou možnost `runAs` jako `CoreApiClient` — viz [Čí přístup volání používá](#whose-access-a-call-uses).```tsimport { MetadataApiClient } from 'twenty-client-sdk/metadata';@@ -791,7 +863,8 @@ Hlavní body:Když váš kód běží na Twenty (logické funkce nebo frontendové komponenty), platforma vloží přihlašovací údaje jako proměnné prostředí:* `TWENTY_API_URL` — Základní URL Twenty API- * `TWENTY_APP_ACCESS_TOKEN` — krátkodobý klíč s rozsahem omezeným na výchozí roli funkce vaší aplikace+ * `TWENTY_APP_ACCESS_TOKEN` — krátkodobý klíč pro výchozí přístup: roli osoby, když někdo stojí za během, protíná role vaší aplikace; když nikdo nestojí za během, používá se vlastní role vaší aplikace. Osobou je kdokoli, kdo spustil běh v logické funkci, nebo kdokoli, kdo si prohlíží stránku ve frontové komponentě.+ * `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — krátkodobý klíč s rozsahem omezeným pouze na vlastní roli vaší aplikace. Pouze pro logické funkce, vždy se do nich vkládá a používá jej `runAs: 'application'`.- Není nutné je předávat klientům — čtou je automaticky z `process.env`. Oprávnění API klíče jsou určena rolí deklarovanou pomocí `defineApplicationRole()` (nebo odkazovanou prostřednictvím `defaultRoleUniversalIdentifier` v `application-config.ts`).+ Tyto hodnoty klientům **nemusíte** předávat — automaticky je čtou z `process.env` a [Čí přístup volání používá](#whose-access-a-call-uses) popisuje volbu mezi nimi. Vlastní oprávnění vaší aplikace jsou určena rolí deklarovanou pomocí `defineApplicationRole()` (nebo odkazovanou prostřednictvím `defaultRoleUniversalIdentifier` v `application-config.ts`); běh jednající jako osoba nikdy nemůže překročit ani tuto roli, ani roli této osoby.</Note>diff --git a/packages/twenty-docs/l/de/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/de/developers/extend/apps/config/application.mdxindex 7319b54d546..5021ac17835 100644--- a/packages/twenty-docs/l/de/developers/extend/apps/config/application.mdx+++ b/packages/twenty-docs/l/de/developers/extend/apps/config/application.mdx@@ -97,7 +97,7 @@ Das Gleiche gilt für Frontend-Komponenten, die Werte über `getApplicationVariaDie mit [`defineApplicationRole()`](/l/de/developers/extend/apps/config/roles) deklarierte Rolle steuert, worauf die Logikfunktionen und Frontend-Komponenten der App zugreifen können:-* Das zur Laufzeit als `TWENTY_APP_ACCESS_TOKEN` injizierte Token wird aus dieser Rolle abgeleitet.+* Die zur Laufzeit in Ihre Logikfunktionen injizierten Token werden aus dieser Rolle abgeleitet. Ein Aufruf, der als Person agiert, wird zusätzlich durch die Möglichkeiten dieser Person eingeschränkt und kann daher niemals eine der beiden Berechtigungen überschreiten. Siehe [Wessen Zugriff ein Aufruf verwendet](/l/de/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* Der typisierte API-Client ist auf die dieser Rolle gewährten Berechtigungen beschränkt.* Befolgen Sie das Least-Privilege-Prinzip: Deklarieren Sie nur die Berechtigungen, die Ihre Funktionen benötigen.diff --git a/packages/twenty-docs/l/de/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/l/de/developers/extend/apps/getting-started/concepts.mdxindex 9dc37b519ea..6c478051853 100644--- a/packages/twenty-docs/l/de/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/l/de/developers/extend/apps/getting-started/concepts.mdx@@ -54,9 +54,9 @@ your-app/## Sandboxing-* **Logikfunktionen** laufen in isolierten Node.js-Prozessen auf dem Server. Sie greifen nur über den typisierten API-Client auf Daten zu, begrenzt durch die Rollenberechtigungen der App.+* **Logikfunktionen** laufen in isolierten Node.js-Prozessen auf dem Server. Sie greifen nur über den typisierten API-Client auf Daten zu, der entweder als die Person fungiert, die die Ausführung ausgelöst hat, oder als die App selbst. Siehe [Wessen Zugriff ein Aufruf verwendet](/l/de/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* **Frontend-Komponenten** laufen in Web Workers mit Remote DOM — von der Hauptseite isoliert, rendern aber native DOM-Elemente (keine iframes). Sie kommunizieren über eine Message-Passing-Host-API mit Twenty.-* **Berechtigungen** werden auf API-Ebene durchgesetzt. Das Laufzeit-Token (`TWENTY_APP_ACCESS_TOKEN`) wird aus der in `defineApplication()` definierten Rolle abgeleitet.+* **Berechtigungen** werden auf API-Ebene durchgesetzt. Zwei Laufzeit-Token werden eingefügt, die beide von der mit `defineApplicationRole()` deklarierten Rolle abgeleitet sind; das Standard-Token wird weiter auf das eingeschränkt, was die auslösende Person tun kann, wenn jemand hinter der Ausführung steht.## App-Lebenszyklusdiff --git a/packages/twenty-docs/l/de/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/de/developers/extend/apps/layout/front-components.mdxindex 042574bf861..63732f2dbe9 100644--- a/packages/twenty-docs/l/de/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/l/de/developers/extend/apps/layout/front-components.mdx@@ -333,6 +333,8 @@ export default defineLogicFunction({Um App-HTTP-Routen aufzurufen oder Twenty-Datensätze aus einer Front-Komponente zu lesen und zu schreiben, verwende `RestApiClient` aus `twenty-client-sdk/rest`. Es sendet `/s/...`-Pfade an die Funktions-Basis-URL deines Arbeitsbereichs und alle anderen Pfade, einschließlich `/rest/...`, an `TWENTY_API_URL`.+Es handelt immer als die Person, die die Seite betrachtet. `runAs: 'application'` ist nur eine Option für Logikfunktionen: Eine Komponente erhält niemals das eigene Token Ihrer Anwendung. Wenn Sie es hier anfordern, wird ein Fehler ausgelöst. Lagern Sie Arbeiten, die den eigenen Zugriff der Anwendung benötigen, hinter eine Logikfunktion aus und rufen Sie stattdessen diese auf.+| Methode | Beschreibung || --------------------------------- | ---------------------------------------------------------------------------------------- || `get(path, options?)` | Sendet eine `GET`-Anfrage |@@ -445,10 +447,10 @@ Geheime Variablen (`isSecret: true`) werden **nicht** in Front-Komponenten offenDie folgenden Systemvariablen sind immer über `process.env` verfügbar:-| Variable | Beschreibung |-| ------------------------- | ------------------------------------------------------------- |-| `TWENTY_API_URL` | Basis-URL der Twenty-Core-API |-| `TWENTY_APP_ACCESS_TOKEN` | Kurzlebiges Token mit dem Geltungsbereich der Rolle Ihrer App |+| Variable | Beschreibung |+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `TWENTY_API_URL` | Basis-URL der Twenty-Core-API |+| `TWENTY_APP_ACCESS_TOKEN` | Kurzlebiges Token, das auf die Schnittmenge der Rolle der angemeldeten Person und der Rolle Ihrer Anwendung beschränkt ist, sodass eine Komponente niemals mehr tun kann als die Person, die sie betrachtet |### `TWENTY_FUNCTIONS_URL`diff --git a/packages/twenty-docs/l/de/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/l/de/developers/extend/apps/logic/logic-functions.mdxindex 5d65528a178..fed44520c59 100644--- a/packages/twenty-docs/l/de/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/l/de/developers/extend/apps/logic/logic-functions.mdx@@ -447,6 +447,78 @@ const handler = async (event: PersonDestroyedEvent) => {};```+#### Ausführungskontext++Jeder Handler erhält ein zweites Argument, das die Ausführung selbst beschreibt, unabhängig davon, wodurch sie ausgelöst wurde. Während sich die Form des ersten Arguments je nach Auslöser ändert, bleibt dieses unverändert:++```ts+import type { LogicFunctionExecutionContext } from 'twenty-sdk/logic-function';++const handler = async (+ event: DatabaseEventPayload,+ { workspaceId, workspaceMemberId }: LogicFunctionExecutionContext,+) => {+ if (workspaceMemberId === null) {+ throw new Error('This function must be triggered by a person');+ }++ return { reviewedBy: workspaceMemberId, workspaceId };+};+```++| Feld | Typ | Beschreibung |+| ------------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |+| `workspaceId` | `string` | Der Arbeitsbereich, zu dem die Ausführung gehört. |+| `userWorkspaceId` | `string \| null` | Die Person, die die Ausführung ausgelöst hat, als Mitglied dieses Arbeitsbereichs. |+| `workspaceMemberId` | `string \| null` | Dieselbe Person als Arbeitsbereichsmitgliedsdatensatz, mit dem Sie Datensätze verknüpfen. |+| `retryCount` | `number` | `0` beim ersten Versuch. Siehe [Hintergrundaufgaben](/l/de/developers/extend/apps/logic/background-jobs). |+| `maxRetries` | `number` | Obergrenze für von der Anwendung angeforderte Wiederholungsversuche. |++`userWorkspaceId` und `workspaceMemberId` sind `null`, wenn niemand die Ausführung ausgelöst hat: Cron-Zeitpläne, Installations-Hooks und nicht authentifizierte Webhooks haben keine Person hinter sich. Sie sind auch `null`, wenn die Person keinen Arbeitsbereichsmitgliedsdatensatz hat oder ihr Datensatz gelöscht wurde.++<Note>+**Der Kontext teilt Ihnen mit, wer die Ausführung ausgelöst hat.** Was die Ausführung *tun* darf, ist eine separate Deklaration, siehe unten.+</Note>++#### Wessen Zugriff ein Aufruf verwendet++Jeder Client — `CoreApiClient`, `MetadataApiClient` und `RestApiClient` — agiert als die Person, die die Ausführung ausgelöst hat: ihre Rolle wird mit der Ihrer Anwendung geschnitten, sodass der Aufruf nie mehr tun kann als jede von Ihnen beiden. Das ist die Standardeinstellung und bedeutet, dass eine Person Ihre App niemals dazu verwenden kann, ihre eigenen Berechtigungen zu überschreiten.++Wenn niemand die Ausführung ausgelöst hat, gibt es keine Person, als die agiert werden kann; daher greift derselbe Client auf den eigenen Zugriff Ihrer Anwendung zurück: Cron-Zeitpläne, Installations-Hooks und nicht authentifizierte Webhooks benötigen keine besondere Behandlung.++Einige Aufrufe benötigen berechtigterweise den eigenen Zugriff der Anwendung, selbst wenn eine Person *hinter* der Ausführung steht — etwa zum Lesen der Konfigurationsdatensätze Ihrer App oder zum Ausführen von Aufgaben, die diese Person selbst nicht erledigen könnte. Erstellen Sie dafür einen zweiten Client:++```ts+import { CoreApiClient } from 'twenty-client-sdk/core';++const asPerson = new CoreApiClient();+const asApplication = new CoreApiClient({ runAs: 'application' });++const handler = async (event: DatabaseEventPayload) => {+ // config records only your app may read+ const { slackUserLinks } = await asApplication.query({ ... });++ // created as the person, so it is attributed and permission-checked+ await asPerson.mutation({ createNote: { ... } });+};+```++Erstellen Sie beide einmal im Modulbereich, und jede Aufrufstelle gibt dann anhand des aufgerufenen Clients an, welchen Zugriff sie verwendet. `RestApiClient` akzeptiert dieselbe Option:++```ts+import { RestApiClient } from 'twenty-client-sdk/rest';++const asApplication = new RestApiClient({ runAs: 'application' });+```++<Note>+**Eine Ausführung, die niemand ausgelöst hat, agiert als Ihre Anwendung.** Cron-Zeitpläne, Installations-Hooks und nicht authentifizierte Webhooks haben keine Person hinter sich, daher greift der Standard-Client auf den eigenen Zugriff Ihrer Anwendung zurück und funktioniert weiterhin. `runAs: 'application'` wird nur benötigt, wenn Sie diesen Zugriff in einer Ausführung wünschen, die eine Person *doch* ausgelöst hat.++Prüfen Sie `context.workspaceMemberId`, wenn sich eine Funktion unterschiedlich verhält, je nachdem, ob jemand hinter ihr steht, beispielsweise um einen Datensatz zuzuordnen.+</Note>++Die SDK-Hilfsfunktionen, die auf die eigenen Ressourcen Ihrer Anwendung zugreifen, verwenden immer deren Zugriff und ignorieren `runAs`: der [Schlüssel-Wert-Speicher](/l/de/developers/extend/apps/logic/key-value-store), [Verbindungen](/l/de/developers/extend/apps/logic/connections), `runAgent`, `getPublicAssetUrl` und die Abrechnung von Credits.+#### Eine Funktion als KI-Tool oder Workflow-Aktion verfügbar machenLogikfunktionen können auf zwei Oberflächen verfügbar gemacht werden, jeweils mit eigenem Trigger:@@ -722,7 +794,7 @@ setCompany(result.company);</Accordion><Accordion title="MetadataApiClient" description="Konfiguration des Arbeitsbereichs, Anwendungen und Dateiuploads">-`MetadataApiClient` ist im SDK bereits vorgefertigt enthalten (keine Generierung erforderlich). Er fragt den Endpunkt `/metadata` nach Arbeitsbereichskonfiguration, Anwendungen und Datei-Uploads ab.+`MetadataApiClient` ist im SDK bereits vorgefertigt enthalten (keine Generierung erforderlich). Er fragt den Endpunkt `/metadata` nach Arbeitsbereichskonfiguration, Anwendungen und Datei-Uploads ab. Er verwendet dieselbe Option `runAs` wie `CoreApiClient` — siehe [Wessen Zugriff ein Aufruf verwendet](#whose-access-a-call-uses).```tsimport { MetadataApiClient } from 'twenty-client-sdk/metadata';@@ -775,8 +847,8 @@ console.log(uploadedFile);| Parameter | Typ | Beschreibung || ---------------------------------- | -------------- | --------------------------------------------------------------------- || `fileBuffer` | `Buffer` | Der Rohinhalt der Datei |-| `filename` | `string` | Der Name der Datei (wird für Speicherung und Anzeige verwendet) |-| `contentType` | `Zeichenkette` | MIME-Typ (standardmäßig `application/octet-stream`, wenn weggelassen) |+| `filename` | `Zeichenkette` | Der Name der Datei (wird für Speicherung und Anzeige verwendet) |+| `contentType` | `string` | MIME-Typ (standardmäßig `application/octet-stream`, wenn weggelassen) || `fieldMetadataUniversalIdentifier` | `string` | Der `universalIdentifier` des Dateityp-Felds in Ihrem Objekt |Hauptpunkte:@@ -790,7 +862,8 @@ Hauptpunkte:Wenn Ihr Code auf Twenty ausgeführt wird (Logikfunktionen oder Frontend-Komponenten), injiziert die Plattform Anmeldedaten als Umgebungsvariablen:* `TWENTY_API_URL` — Basis-URL der Twenty-API- * `TWENTY_APP_ACCESS_TOKEN` — Kurzlebiger Schlüssel, der auf die Standard-Funktionsrolle Ihrer Anwendung begrenzt ist+ * `TWENTY_APP_ACCESS_TOKEN` — Kurzlebiger Schlüssel für den Standardzugriff: die Rolle einer Person wird mit der Ihrer Anwendung geschnitten, wenn jemand hinter der Ausführung steht; die eigene Rolle Ihrer Anwendung, wenn niemand dahintersteht. Die Person ist in einer Logikfunktion diejenige, die die Ausführung ausgelöst hat, und in einer Front-Komponente diejenige, die die Seite betrachtet.+ * `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — Kurzlebiger Schlüssel, der ausschließlich auf die eigene Rolle Ihrer Anwendung begrenzt ist. Nur Logikfunktionen, dort immer eingefügt, und wird von `runAs: 'application'` verwendet.- Sie müssen diese **nicht** an die Clients übergeben — sie lesen automatisch aus `process.env`. Die Berechtigungen des API-Schlüssels werden durch die Rolle bestimmt, die mit `defineApplicationRole()` deklariert wird (oder über `defaultRoleUniversalIdentifier` in `application-config.ts` referenziert wird).+ Sie müssen diese **nicht** an die Clients übergeben — sie lesen sie automatisch aus `process.env`, und [Wessen Zugriff ein Aufruf verwendet](#whose-access-a-call-uses) behandelt die Auswahl zwischen ihnen. Die eigenen Berechtigungen Ihrer Anwendung werden durch die Rolle bestimmt, die mit `defineApplicationRole()` deklariert wird (oder über `defaultRoleUniversalIdentifier` in `application-config.ts` referenziert wird); eine Ausführung, die als Person agiert, kann weder diese Rolle noch die der Person überschreiten.</Note>diff --git a/packages/twenty-docs/l/es/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/es/developers/extend/apps/config/application.mdxindex 50f3ca8efe8..0d4cba9cd84 100644--- a/packages/twenty-docs/l/es/developers/extend/apps/config/application.mdx+++ b/packages/twenty-docs/l/es/developers/extend/apps/config/application.mdx@@ -97,7 +97,7 @@ Lo mismo se aplica a los componentes de interfaz que leen valores mediante `getAEl rol declarado con [`defineApplicationRole()`](/l/es/developers/extend/apps/config/roles) controla a qué pueden acceder las funciones de lógica y los componentes de interfaz de la aplicación:-* El token en tiempo de ejecución inyectado como `TWENTY_APP_ACCESS_TOKEN` se deriva de este rol.+* Los tokens en tiempo de ejecución inyectados en tus funciones de lógica se derivan de este rol. Una llamada que actúa como una persona se limita aún más a lo que esa persona puede hacer, por lo que nunca puede superar ninguno de los dos. Consulta [Qué acceso usa una llamada](/l/es/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* El cliente de API tipado está restringido a los permisos otorgados a ese rol.* Sigue el principio de mínimo privilegio: declara solo los permisos que necesitan tus funciones.diff --git a/packages/twenty-docs/l/es/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/l/es/developers/extend/apps/getting-started/concepts.mdxindex 826b79f7b93..98556af2beb 100644--- a/packages/twenty-docs/l/es/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/l/es/developers/extend/apps/getting-started/concepts.mdx@@ -54,9 +54,9 @@ your-app/## Sandboxing-* **Las funciones de lógica** se ejecutan en procesos de Node.js aislados en el servidor. Solo acceden a los datos a través del cliente de API tipado, limitado a los permisos del rol de la aplicación.+* **Las funciones de lógica** se ejecutan en procesos de Node.js aislados en el servidor. Solo acceden a los datos a través del cliente de API tipado, que actúa como la persona que desencadenó la ejecución o como la propia aplicación. Consulta [Qué acceso usa una llamada](/l/es/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* **Los componentes de frontend** se ejecutan en Web Workers usando Remote DOM — aislados de la página principal pero renderizando elementos DOM nativos (no iframes). Se comunican con Twenty a través de una API de host de paso de mensajes.-* **Los permisos** se aplican a nivel de API. El token de tiempo de ejecución (`TWENTY_APP_ACCESS_TOKEN`) se deriva del rol definido en `defineApplication()`.+* **Los permisos** se aplican a nivel de API. Se inyectan dos tokens de tiempo de ejecución, ambos derivados del rol declarado con `defineApplicationRole()`; el predeterminado se restringe aún más a lo que puede hacer la persona que desencadena la ejecución siempre que haya alguien detrás de ella.## Ciclo de vida de la aplicacióndiff --git a/packages/twenty-docs/l/es/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/es/developers/extend/apps/layout/front-components.mdxindex 891de149c5f..ba059668ea8 100644--- a/packages/twenty-docs/l/es/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/l/es/developers/extend/apps/layout/front-components.mdx@@ -333,6 +333,8 @@ export default defineLogicFunction({Para llamar a rutas HTTP de la aplicación o leer y escribir registros de Twenty desde un componente de interfaz, utiliza `RestApiClient` de `twenty-client-sdk/rest`. Envía las rutas `/s/...` a la URL base de las funciones de tu espacio de trabajo y cualquier otra ruta, incluidas `/rest/...`, a `TWENTY_API_URL`.+Siempre actúa como la persona que está mirando la página. `runAs: 'application'` es una opción exclusiva de las funciones lógicas: un componente nunca recibe el propio token de tu aplicación, por lo que solicitarlo aquí genera un error. Coloca el trabajo que necesita el acceso propio de la aplicación detrás de una función lógica y llama a esa en su lugar.+| Método | Descripción || --------------------------------- | --------------------------------------------------------------------------- || `get(path, options?)` | Envía una solicitud `GET` |@@ -445,10 +447,10 @@ Las variables secretas (`isSecret: true`) **no** se exponen a los componentes deLas siguientes variables de sistema siempre están disponibles a través de `process.env`:-| Variable | Descripción |-| ------------------------- | -------------------------------------------------------- |-| `TWENTY_API_URL` | URL base de la API principal de Twenty |-| `TWENTY_APP_ACCESS_TOKEN` | Token de corta duración limitado al rol de tu aplicación |+| Variable | Descripción |+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `TWENTY_API_URL` | URL base de la API principal de Twenty |+| `TWENTY_APP_ACCESS_TOKEN` | Token de corta duración limitado al rol de la persona que ha iniciado sesión, en intersección con el de tu aplicación, por lo que un componente nunca puede hacer más de lo que puede hacer la persona que lo está mirando |### `TWENTY_FUNCTIONS_URL`diff --git a/packages/twenty-docs/l/es/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/l/es/developers/extend/apps/logic/logic-functions.mdxindex a7070cbc761..cccf90ff717 100644--- a/packages/twenty-docs/l/es/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/l/es/developers/extend/apps/logic/logic-functions.mdx@@ -448,6 +448,78 @@ const handler = async (event: PersonDestroyedEvent) => {};```+#### Contexto de ejecución++Cada controlador recibe un segundo argumento que describe la propia ejecución, independientemente de lo que la haya desencadenado. Mientras que el primer argumento cambia de forma según el desencadenante, este no:++```ts+import type { LogicFunctionExecutionContext } from 'twenty-sdk/logic-function';++const handler = async (+ event: DatabaseEventPayload,+ { workspaceId, workspaceMemberId }: LogicFunctionExecutionContext,+) => {+ if (workspaceMemberId === null) {+ throw new Error('This function must be triggered by a person');+ }++ return { reviewedBy: workspaceMemberId, workspaceId };+};+```++| Campo | Tipo | Descripción |+| ------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------- |+| `workspaceId` | `string` | El espacio de trabajo al que pertenece la ejecución. |+| `userWorkspaceId` | `string \| null` | La persona que desencadenó la ejecución, como miembro de este espacio de trabajo. |+| `workspaceMemberId` | `string \| null` | La misma persona como un registro de miembro del espacio de trabajo, que es a lo que vinculas los registros. |+| `retryCount` | `number` | `0` en el primer intento. Consulta [Trabajos en segundo plano](/l/es/developers/extend/apps/logic/background-jobs). |+| `maxRetries` | `number` | Límite superior de los reintentos solicitados por la aplicación. |++`userWorkspaceId` y `workspaceMemberId` son `null` cuando nadie desencadenó la ejecución: las programaciones cron, los hooks de instalación y los webhooks no autenticados no tienen a ninguna persona detrás. También son `null` cuando la persona no tiene un registro de miembro del espacio de trabajo, o cuando el suyo se ha eliminado.++<Note>+**El contexto te indica quién desencadenó la ejecución.** Lo que la ejecución puede *hacer* es una declaración independiente, a continuación.+</Note>++#### Qué acceso utiliza una llamada++Cada cliente — `CoreApiClient`, `MetadataApiClient` y `RestApiClient` — actúa como la persona que desencadenó la ejecución: su rol se intersecta con el de tu aplicación, por lo que la llamada nunca puede hacer más de lo que cualquiera de los dos puede hacer. Ese es el comportamiento predeterminado y significa que una persona nunca puede usar tu aplicación para superar sus propios permisos.++Cuando nadie desencadenó la ejecución, no hay ninguna persona como la que actuar, por lo que el mismo cliente recurre al acceso propio de tu aplicación: las programaciones cron, los hooks de instalación y los webhooks no autenticados no requieren ninguna gestión especial.++Algunas llamadas necesitan legítimamente el acceso propio de la aplicación incluso cuando hay una persona detrás de la ejecución — leer los registros de configuración de tu aplicación o realizar trabajo que esa persona no podría hacer por sí misma. Crea un segundo cliente para esos casos:++```ts+import { CoreApiClient } from 'twenty-client-sdk/core';++const asPerson = new CoreApiClient();+const asApplication = new CoreApiClient({ runAs: 'application' });++const handler = async (event: DatabaseEventPayload) => {+ // config records only your app may read+ const { slackUserLinks } = await asApplication.query({ ... });++ // created as the person, so it is attributed and permission-checked+ await asPerson.mutation({ createNote: { ... } });+};+```++Crea ambos una vez, en el ámbito del módulo, y cada sitio de llamada indica entonces qué acceso utiliza según el cliente al que llama. `RestApiClient` acepta la misma opción:++```ts+import { RestApiClient } from 'twenty-client-sdk/rest';++const asApplication = new RestApiClient({ runAs: 'application' });+```++<Note>+**Una ejecución que nadie desencadenó actúa como tu aplicación.** Las programaciones cron, los hooks de instalación y los webhooks no autenticados no tienen a ninguna persona detrás, por lo que el cliente predeterminado recurre al acceso propio de tu aplicación y sigue funcionando. `runAs: 'application'` solo se necesita cuando quieres ese acceso en una ejecución que una persona *sí* desencadenó.++Comprueba `context.workspaceMemberId` cuando una función se comporta de forma diferente según haya alguien detrás de ella, por ejemplo, para atribuir un registro.+</Note>++Los सहायantes del SDK que acceden a los recursos propios de tu aplicación siempre usan su acceso e ignoran `runAs`: el [almacén de clave-valor](/l/es/developers/extend/apps/logic/key-value-store), las [conexiones](/l/es/developers/extend/apps/logic/connections), `runAgent`, `getPublicAssetUrl` y el cobro de créditos.+#### Exponer una función como herramienta de IA o acción de flujo de trabajoLas funciones lógicas pueden exponerse en dos ámbitos, cada uno con su propio disparador:@@ -723,7 +795,7 @@ setCompany(result.company);</Accordion><Accordion title="MetadataApiClient" description="Configuración del espacio de trabajo, aplicaciones y cargas de archivos">-`MetadataApiClient` viene preconstruido con el SDK (no se requiere generación). Consulta el endpoint `/metadata` para la configuración del espacio de trabajo, las aplicaciones y las cargas de archivos.+`MetadataApiClient` viene preconstruido con el SDK (no se requiere generación). Consulta el endpoint `/metadata` para la configuración del espacio de trabajo, las aplicaciones y las cargas de archivos. Acepta la misma opción `runAs` que `CoreApiClient` — consulta [Qué acceso utiliza una llamada](#whose-access-a-call-uses).```tsimport { MetadataApiClient } from 'twenty-client-sdk/metadata';@@ -791,7 +863,8 @@ Puntos clave:Cuando tu código se ejecuta en Twenty (funciones de lógica o componentes de frontend), la plataforma inyecta credenciales como variables de entorno:* `TWENTY_API_URL` — URL base de la API de Twenty- * `TWENTY_APP_ACCESS_TOKEN` — Token de corta duración con alcance al rol de función predeterminado de tu aplicación+ * `TWENTY_APP_ACCESS_TOKEN` — Clave de corta duración para el acceso predeterminado: el rol de una persona se intersecta con el de tu aplicación cuando hay alguien detrás de la ejecución; el rol propio de tu aplicación cuando no hay nadie. La persona es quien haya desencadenado la ejecución en una función de lógica, o quien esté viendo la página en un componente de frontend.+ * `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — Clave de corta duración con alcance únicamente al rol propio de tu aplicación. Solo funciones de lógica, siempre se inyecta allí, y es lo que utiliza `runAs: 'application'`.- No necesitas pasar estas credenciales a los clientes — leen de `process.env` automáticamente. Los permisos de la clave de API están determinados por el rol declarado con `defineApplicationRole()` (o referenciado mediante `defaultRoleUniversalIdentifier` en `application-config.ts`).+ **No** necesitas pasar estas a los clientes — leen de `process.env` automáticamente, y [Qué acceso utiliza una llamada](#whose-access-a-call-uses) explica cómo elegir entre ellas. Los permisos propios de tu aplicación están determinados por el rol declarado con `defineApplicationRole()` (o referenciado mediante `defaultRoleUniversalIdentifier` en `application-config.ts`); una ejecución que actúa como una persona nunca puede superar ese rol ni el suyo.</Note>diff --git a/packages/twenty-docs/l/fr/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/fr/developers/extend/apps/config/application.mdxindex 7c4596e1890..1171156733a 100644--- a/packages/twenty-docs/l/fr/developers/extend/apps/config/application.mdx+++ b/packages/twenty-docs/l/fr/developers/extend/apps/config/application.mdx@@ -97,7 +97,7 @@ Il en va de même pour les composants front qui lisent les valeurs via `getAppliLe rôle déclaré avec [`defineApplicationRole()`](/l/fr/developers/extend/apps/config/roles) contrôle ce à quoi les fonctions logiques de l’application et les composants front peuvent accéder :-* Le jeton d'exécution injecté sous `TWENTY_APP_ACCESS_TOKEN` est dérivé de ce rôle.+* Les jetons d'exécution injectés dans vos fonctions logiques sont dérivés de ce rôle. Un appel agissant en tant que personne est davantage limité par ce que cette personne peut faire, de sorte qu'il ne peut jamais dépasser l'un ou l'autre. Voir [Les accès qu'un appel utilise](/l/fr/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* Le client d'API typé est limité aux autorisations accordées à ce rôle.* Appliquez le principe du moindre privilège : déclarez uniquement les autorisations dont vos fonctions ont besoin.diff --git a/packages/twenty-docs/l/fr/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/l/fr/developers/extend/apps/getting-started/concepts.mdxindex 6d9b78c9e64..48e6b81f3ff 100644--- a/packages/twenty-docs/l/fr/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/l/fr/developers/extend/apps/getting-started/concepts.mdx@@ -54,9 +54,9 @@ your-app/## Exécution en bac à sable-* **Les fonctions logiques** s’exécutent dans des processus Node.js isolés sur le serveur. Elles n’accèdent aux données qu’au moyen du client d’API typé, limité par les autorisations du rôle de l’application.+* **Les fonctions logiques** s’exécutent dans des processus Node.js isolés sur le serveur. Ils accèdent uniquement aux données via le client d’API typé, qui agit soit en tant que personne ayant déclenché l’exécution, soit en tant que l’application elle-même. Consultez [Les accès utilisés par un appel](/l/fr/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* **Les composants frontaux** s’exécutent dans des Web Workers en utilisant Remote DOM — isolés en bac à sable de la page principale mais rendant des éléments DOM natifs (pas d’iframes). Ils communiquent avec Twenty via une API hôte de passage de messages.-* **Les autorisations** sont appliquées au niveau de l’API. Le jeton d’exécution (`TWENTY_APP_ACCESS_TOKEN`) est dérivé du rôle défini dans `defineApplication()`.+* **Les autorisations** sont appliquées au niveau de l’API. Deux jetons d’exécution sont injectés, tous deux dérivés du rôle déclaré avec `defineApplicationRole()` ; le jeton par défaut est davantage restreint à ce que la personne ayant déclenché l’exécution peut faire lorsqu’une personne est à l’origine de l’exécution.## Cycle de vie de l’applicationdiff --git a/packages/twenty-docs/l/fr/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/fr/developers/extend/apps/layout/front-components.mdxindex 8d3a2127a15..c403ca95154 100644--- a/packages/twenty-docs/l/fr/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/l/fr/developers/extend/apps/layout/front-components.mdx@@ -333,6 +333,8 @@ export default defineLogicFunction({Pour appeler des routes HTTP d’application ou lire et écrire des enregistrements Twenty depuis un composant frontal, utilisez `RestApiClient` depuis `twenty-client-sdk/rest`. Il envoie les chemins `/s/...` vers l’URL de base des fonctions de votre espace de travail et tous les autres chemins, y compris `/rest/...`, vers `TWENTY_API_URL`.+Il agit toujours en tant que la personne qui consulte la page. `runAs: 'application'` est une option réservée aux fonctions logiques : un composant ne reçoit jamais le jeton propre à votre application, donc le demander ici génère une erreur. Placez le travail nécessitant l'accès propre à l'application derrière une fonction logique et appelez-la à la place.+| Méthode | Description || --------------------------------- | ------------------------------------------------------------------------------- || `get(path, options?)` | Envoie une requête `GET` |@@ -445,10 +447,10 @@ Les variables secrètes (`isSecret: true`) ne sont **pas** exposées aux composaLes variables système suivantes sont toujours disponibles via `process.env` :-| Variable | Description |-| ------------------------- | --------------------------------------------------------- |-| `TWENTY_API_URL` | URL de base de l’API principale de Twenty |-| `TWENTY_APP_ACCESS_TOKEN` | Jeton de courte durée limité au rôle de votre application |+| Variable | Description |+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `TWENTY_API_URL` | URL de base de l’API principale de Twenty |+| `TWENTY_APP_ACCESS_TOKEN` | Jeton à courte durée de vie dont la portée correspond à l'intersection entre le rôle de la personne connectée et celui de votre application, de sorte qu'un composant ne peut jamais faire plus que la personne qui le consulte |### `TWENTY_FUNCTIONS_URL`diff --git a/packages/twenty-docs/l/fr/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/l/fr/developers/extend/apps/logic/logic-functions.mdxindex 670fc6ded41..84f54f48df0 100644--- a/packages/twenty-docs/l/fr/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/l/fr/developers/extend/apps/logic/logic-functions.mdx@@ -448,6 +448,78 @@ const handler = async (event: PersonDestroyedEvent) => {};```+#### Contexte d'exécution++Chaque gestionnaire reçoit un deuxième argument décrivant l'exécution elle-même, quel que soit ce qui l'a déclenchée. Alors que la forme du premier argument varie selon le déclencheur, celle-ci ne varie pas :++```ts+import type { LogicFunctionExecutionContext } from 'twenty-sdk/logic-function';++const handler = async (+ event: DatabaseEventPayload,+ { workspaceId, workspaceMemberId }: LogicFunctionExecutionContext,+) => {+ if (workspaceMemberId === null) {+ throw new Error('This function must be triggered by a person');+ }++ return { reviewedBy: workspaceMemberId, workspaceId };+};+```++| Champ | Type | Description |+| ------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |+| `workspaceId` | `string` | L'espace de travail auquel appartient l'exécution. |+| `userWorkspaceId` | `string \| null` | La personne qui a déclenché l'exécution, en tant que membre de cet espace de travail. |+| `workspaceMemberId` | `string \| null` | La même personne sous la forme d'un enregistrement de membre de l'espace de travail, auquel vous liez les enregistrements. |+| `retryCount` | `number` | `0` lors de la première tentative. Voir [Tâches en arrière-plan](/l/fr/developers/extend/apps/logic/background-jobs). |+| `maxRetries` | `number` | Limite supérieure des nouvelles tentatives demandées par l'application. |++`userWorkspaceId` et `workspaceMemberId` sont `null` lorsque personne n'a déclenché l'exécution : les planifications cron, les hooks d'installation et les webhooks non authentifiés n'ont aucune personne derrière eux. Ils sont également `null` lorsque la personne ne possède aucun enregistrement de membre de l'espace de travail, ou que le sien a été supprimé.++<Note>+**Le contexte vous indique qui a déclenché l'exécution.** Ce que l'exécution peut *faire* est une déclaration distincte, ci-dessous.+</Note>++#### Quels accès un appel utilise++Chaque client — `CoreApiClient`, `MetadataApiClient` et `RestApiClient` — agit en tant que personne ayant déclenché l'exécution : son rôle est combiné à celui de votre application, de sorte que l'appel ne peut jamais faire plus que l'un ou l'autre. C'est le comportement par défaut, et cela signifie qu'une personne ne peut jamais utiliser votre application pour dépasser ses propres autorisations.++Lorsque personne n'a déclenché l'exécution, il n'y a aucune personne dont il faut adopter l'identité, le même client utilise donc les propres accès de votre application : les planifications cron, les hooks d'installation et les webhooks non authentifiés ne nécessitent aucun traitement particulier.++Certains appels nécessitent légitimement les propres accès de l'application même lorsqu'une personne *est* à l'origine de l'exécution — pour lire les enregistrements de configuration de votre application, ou effectuer un travail que cette personne ne pourrait pas faire elle-même. Créez un deuxième client pour ceux-ci :++```ts+import { CoreApiClient } from 'twenty-client-sdk/core';++const asPerson = new CoreApiClient();+const asApplication = new CoreApiClient({ runAs: 'application' });++const handler = async (event: DatabaseEventPayload) => {+ // config records only your app may read+ const { slackUserLinks } = await asApplication.query({ ... });++ // created as the person, so it is attributed and permission-checked+ await asPerson.mutation({ createNote: { ... } });+};+```++Créez les deux une seule fois, à la portée du module, et chaque site d'appel indique alors les accès qu'il utilise par le client qu'il appelle. `RestApiClient` accepte la même option :++```ts+import { RestApiClient } from 'twenty-client-sdk/rest';++const asApplication = new RestApiClient({ runAs: 'application' });+```++<Note>+**Une exécution que personne n'a déclenchée agit en tant que votre application.** Les planifications cron, les hooks d'installation et les webhooks non authentifiés n'ont aucune personne derrière eux, le client par défaut utilise donc les propres accès de votre application et continue de fonctionner. `runAs: 'application'` n'est nécessaire que lorsque vous souhaitez utiliser ces accès dans une exécution qu'une personne *a* déclenchée.++Vérifiez `context.workspaceMemberId` lorsqu'une fonction se comporte différemment selon qu'une personne est derrière elle, par exemple pour attribuer un enregistrement.+</Note>++Les assistants du SDK qui accèdent aux propres ressources de votre application utilisent toujours ses accès et ignorent `runAs` : le [magasin clé-valeur](/l/fr/developers/extend/apps/logic/key-value-store), les [connexions](/l/fr/developers/extend/apps/logic/connections), `runAgent`, `getPublicAssetUrl` et la facturation de crédits.+#### Exposer une fonction en tant qu'outil d'IA ou en tant qu'action de workflowLes fonctions logiques peuvent être exposées sur deux surfaces, chacune avec son propre déclencheur :@@ -723,7 +795,7 @@ setCompany(result.company);</Accordion><Accordion title="MetadataApiClient" description="Configuration de l'espace de travail, applications et téléversements de fichiers">-`MetadataApiClient` est livré prêt à l'emploi avec le SDK (aucune génération requise). Il interroge le point de terminaison `/metadata` pour la configuration de l'espace de travail, les applications et les téléversements de fichiers.+`MetadataApiClient` est livré prêt à l'emploi avec le SDK (aucune génération requise). Il interroge le point de terminaison `/metadata` pour la configuration de l'espace de travail, les applications et les téléversements de fichiers. Il accepte la même option `runAs` que `CoreApiClient` — voir [Quels accès un appel utilise](#whose-access-a-call-uses).```tsimport { MetadataApiClient } from 'twenty-client-sdk/metadata';@@ -791,7 +863,8 @@ Points clés :Lorsque votre code s'exécute sur Twenty (fonctions logiques ou composants frontaux), la plateforme injecte des identifiants sous forme de variables d'environnement :* `TWENTY_API_URL` — URL de base de l'API Twenty- * `TWENTY_APP_ACCESS_TOKEN` — Clé de courte durée limitée au rôle de fonction par défaut de votre application+ * `TWENTY_APP_ACCESS_TOKEN` — Clé de courte durée pour l'accès par défaut : le rôle d'une personne combiné à celui de votre application lorsqu'une personne est à l'origine de l'exécution, le propre rôle de votre application lorsque personne ne l'est. La personne est celle qui a déclenché l'exécution dans une fonction logique, ou celle qui consulte la page dans un composant frontal.+ * `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — Clé de courte durée limitée au seul rôle de votre application. Uniquement pour les fonctions logiques, toujours injectée dans celles-ci, et utilisée par `runAs: 'application'`.- Vous n'avez **pas** besoin de les transmettre aux clients — ils lisent automatiquement depuis `process.env`. Les autorisations de la clé API sont déterminées par le rôle déclaré avec `defineApplicationRole()` (ou référencé via `defaultRoleUniversalIdentifier` dans `application-config.ts`).+ Vous n'avez **pas** besoin de les transmettre aux clients — ils lisent automatiquement depuis `process.env`, et [Quels accès un appel utilise](#whose-access-a-call-uses) explique comment choisir entre eux. Les propres autorisations de votre application sont déterminées par le rôle déclaré avec `defineApplicationRole()` (ou référencé via `defaultRoleUniversalIdentifier` dans `application-config.ts`) ; une exécution agissant en tant que personne ne peut jamais dépasser ce rôle, ni le sien.</Note>diff --git a/packages/twenty-docs/l/it/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/it/developers/extend/apps/config/application.mdxindex 7cc73cf640f..e3b5debfd65 100644--- a/packages/twenty-docs/l/it/developers/extend/apps/config/application.mdx+++ b/packages/twenty-docs/l/it/developers/extend/apps/config/application.mdx@@ -97,7 +97,7 @@ Lo stesso vale per i componenti front-end che leggono i valori tramite `getAppliIl ruolo dichiarato con [`defineApplicationRole()`](/l/it/developers/extend/apps/config/roles) controlla a cosa possono accedere le funzioni di logica e i componenti di interfaccia dell'app:-* Il token di runtime iniettato come `TWENTY_APP_ACCESS_TOKEN` è derivato da questo ruolo.+* I token di runtime iniettati nelle funzioni logiche sono derivati da questo ruolo. Una chiamata che agisce come una persona è ulteriormente limitata a ciò che tale persona può fare, quindi non può mai superare nessuno dei due. Vedi [L'accesso utilizzato da una chiamata](/l/it/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* Il client API tipizzato è limitato alle autorizzazioni concesse a quel ruolo.* Segui il principio del privilegio minimo: dichiara solo le autorizzazioni necessarie alle tue funzioni.diff --git a/packages/twenty-docs/l/it/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/l/it/developers/extend/apps/getting-started/concepts.mdxindex 8baf96d2878..e0dd9fb09b0 100644--- a/packages/twenty-docs/l/it/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/l/it/developers/extend/apps/getting-started/concepts.mdx@@ -54,9 +54,9 @@ your-app/## Sandboxing-* **Le funzioni logiche** vengono eseguite in processi Node.js isolati sul server. Accedono ai dati solo tramite il client API tipizzato, con ambito limitato alle autorizzazioni del ruolo dell'app.+* **Le funzioni logiche** vengono eseguite in processi Node.js isolati sul server. Accedono ai dati solo tramite il client API tipizzato, che agisce come la persona che ha attivato l'esecuzione o come l'app stessa. Consulta [L'accesso utilizzato da una chiamata](/l/it/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* **I componenti front-end** vengono eseguiti in Web Workers utilizzando il Remote DOM — isolati dalla pagina principale ma renderizzando elementi DOM nativi (non iframe). Comunicano con Twenty tramite un'API host basata sul passaggio di messaggi.-* **Le autorizzazioni** vengono applicate a livello di API. Il token di runtime (`TWENTY_APP_ACCESS_TOKEN`) è derivato dal ruolo definito in `defineApplication()`.+* **Le autorizzazioni** vengono applicate a livello di API. Vengono inseriti due token di runtime, entrambi derivati dal ruolo dichiarato con `defineApplicationRole()`; quello predefinito è ulteriormente limitato a ciò che la persona che attiva l'esecuzione può fare quando qualcuno è responsabile dell'esecuzione.## Ciclo di vita dell'appdiff --git a/packages/twenty-docs/l/it/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/it/developers/extend/apps/layout/front-components.mdxindex 4063b147808..0c574d452d6 100644--- a/packages/twenty-docs/l/it/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/l/it/developers/extend/apps/layout/front-components.mdx@@ -333,6 +333,8 @@ export default defineLogicFunction({Per chiamare le route HTTP dell’app o leggere e scrivere record di Twenty da un front component, usa `RestApiClient` da `twenty-client-sdk/rest`. Invia i percorsi `/s/...` alla base URL delle funzioni del tuo workspace e tutti gli altri percorsi, inclusi `/rest/...`, a `TWENTY_API_URL`.+Agisce sempre come la persona che visualizza la pagina. `runAs: 'application'` è un'opzione esclusiva delle funzioni logiche: un componente non riceve mai il token della tua applicazione, quindi richiederlo qui genera un errore. Inserisci il lavoro che richiede l'accesso dell'app dietro una funzione logica e chiama invece quella.+| Metodo | Descrizione || --------------------------------- | --------------------------------------------------------------------------------- || `get(path, options?)` | Invia una richiesta `GET` |@@ -445,10 +447,10 @@ Le variabili segrete (`isSecret: true`) **non** sono esposte ai componenti frontLe seguenti variabili di sistema sono sempre disponibili tramite `process.env`:-| Variabile | Descrizione |-| ------------------------- | ---------------------------------------------------------------- |-| `TWENTY_API_URL` | URL di base dell'API Core di Twenty |-| `TWENTY_APP_ACCESS_TOKEN` | Token di breve durata con ambito limitato al ruolo della tua app |+| Variabile | Descrizione |+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `TWENTY_API_URL` | URL di base dell'API Core di Twenty |+| `TWENTY_APP_ACCESS_TOKEN` | Token di breve durata limitato al ruolo della persona che ha effettuato l'accesso, intersecato con quello della tua app, quindi un componente non può mai fare più di quanto possa fare la persona che lo visualizza |### `TWENTY_FUNCTIONS_URL`diff --git a/packages/twenty-docs/l/it/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/l/it/developers/extend/apps/logic/logic-functions.mdxindex 2e0a841a06c..6d8a826865d 100644--- a/packages/twenty-docs/l/it/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/l/it/developers/extend/apps/logic/logic-functions.mdx@@ -447,6 +447,78 @@ const handler = async (event: PersonDestroyedEvent) => {};```+#### Contesto di esecuzione++Ogni gestore riceve un secondo argomento che descrive l'esecuzione stessa, indipendentemente da cosa l'abbia attivata. Mentre il primo argomento cambia struttura in base all'attivatore, questo no:++```ts+import type { LogicFunctionExecutionContext } from 'twenty-sdk/logic-function';++const handler = async (+ event: DatabaseEventPayload,+ { workspaceId, workspaceMemberId }: LogicFunctionExecutionContext,+) => {+ if (workspaceMemberId === null) {+ throw new Error('This function must be triggered by a person');+ }++ return { reviewedBy: workspaceMemberId, workspaceId };+};+```++| Campo | Tipo | Descrizione |+| ------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |+| `workspaceId` | `string` | Lo spazio di lavoro a cui appartiene l'esecuzione. |+| `userWorkspaceId` | `string \| null` | La persona che ha attivato l'esecuzione, in quanto membro di questo spazio di lavoro. |+| `workspaceMemberId` | `string \| null` | La stessa persona come record del membro dello spazio di lavoro, a cui si collegano i record. |+| `retryCount` | `number` | `0` al primo tentativo. Vedi [Processi in background](/l/it/developers/extend/apps/logic/background-jobs). |+| `maxRetries` | `number` | Limite massimo per i tentativi richiesti dall'applicazione. |++`userWorkspaceId` e `workspaceMemberId` sono `null` quando nessuno ha attivato l'esecuzione: le pianificazioni cron, gli hook di installazione e i webhook non autenticati non hanno una persona alle spalle. Sono inoltre `null` quando la persona non ha un record del membro dello spazio di lavoro o quando il suo è stato eliminato.++<Note>+**Il contesto indica chi ha attivato l'esecuzione.** Ciò che l'esecuzione può *fare* è una dichiarazione separata, riportata di seguito.+</Note>++#### Quale accesso utilizza una chiamata++Ogni client — `CoreApiClient`, `MetadataApiClient` e `RestApiClient` — agisce come la persona che ha attivato l'esecuzione: il suo ruolo intersecato con quello della tua applicazione, quindi la chiamata non può mai fare più di quanto possa fare ciascuno dei due. Questo è il comportamento predefinito e significa che una persona non può mai usare la tua app per superare le proprie autorizzazioni.++Quando nessuno ha attivato l'esecuzione, non c'è nessuna persona per conto della quale agire, quindi lo stesso client usa come fallback l'accesso della tua applicazione: le pianificazioni cron, gli hook di installazione e i webhook non autenticati non richiedono una gestione speciale.++Alcune chiamate necessitano legittimamente dell'accesso della tua applicazione anche quando una persona *è* alle spalle dell'esecuzione — per leggere i record di configurazione della tua app o per eseguire un'attività che quella persona non potrebbe svolgere autonomamente. Crea un secondo client per questi casi:++```ts+import { CoreApiClient } from 'twenty-client-sdk/core';++const asPerson = new CoreApiClient();+const asApplication = new CoreApiClient({ runAs: 'application' });++const handler = async (event: DatabaseEventPayload) => {+ // config records only your app may read+ const { slackUserLinks } = await asApplication.query({ ... });++ // created as the person, so it is attributed and permission-checked+ await asPerson.mutation({ createNote: { ... } });+};+```++Crea entrambi una sola volta, nell'ambito del modulo, e ogni punto di chiamata indica quindi quale accesso utilizza in base al client che chiama. `RestApiClient` accetta la stessa opzione:++```ts+import { RestApiClient } from 'twenty-client-sdk/rest';++const asApplication = new RestApiClient({ runAs: 'application' });+```++<Note>+**Un'esecuzione che nessuno ha attivato agisce come la tua applicazione.** Le pianificazioni cron, gli hook di installazione e i webhook non autenticati non hanno una persona alle spalle, quindi il client predefinito usa come fallback l'accesso della tua applicazione e continua a funzionare. `runAs: 'application'` è necessario solo quando vuoi tale accesso in un'esecuzione che una persona *ha* attivato.++Controlla `context.workspaceMemberId` quando una funzione si comporta diversamente a seconda che ci sia qualcuno alle sue spalle, ad esempio per attribuire un record.+</Note>++Gli helper dell'SDK che raggiungono le risorse della tua applicazione utilizzano sempre il suo accesso e ignorano `runAs`: l'[archivio chiave-valore](/l/it/developers/extend/apps/logic/key-value-store), le [connessioni](/l/it/developers/extend/apps/logic/connections), `runAgent`, `getPublicAssetUrl` e l'addebito dei crediti.+#### Esporre una funzione come strumento di IA o come azione del flusso di lavoroLe funzioni logiche possono essere esposte su due superfici, ciascuna con il proprio trigger:@@ -722,7 +794,7 @@ setCompany(result.company);</Accordion><Accordion title="MetadataApiClient" description="Configurazione dello spazio di lavoro, applicazioni e caricamenti di file">-`MetadataApiClient` è fornito pronto all'uso con l'SDK (nessuna generazione richiesta). Interroga l'endpoint `/metadata` per la configurazione dello spazio di lavoro, le applicazioni e i caricamenti di file.+`MetadataApiClient` è fornito pronto all'uso con l'SDK (nessuna generazione richiesta). Interroga l'endpoint `/metadata` per la configurazione dello spazio di lavoro, le applicazioni e i caricamenti di file. Accetta la stessa opzione `runAs` di `CoreApiClient` — vedi [Quale accesso utilizza una chiamata](#whose-access-a-call-uses).```tsimport { MetadataApiClient } from 'twenty-client-sdk/metadata';@@ -790,7 +862,8 @@ Punti chiave:Quando il tuo codice viene eseguito su Twenty (funzioni logiche o componenti front-end), la piattaforma inietta le credenziali come variabili d'ambiente:* `TWENTY_API_URL` — URL di base dell'API di Twenty- * `TWENTY_APP_ACCESS_TOKEN` — Chiave a breve durata con ambito al ruolo funzione predefinito della tua applicazione+ * `TWENTY_APP_ACCESS_TOKEN` — Chiave a breve durata per l'accesso predefinito: il ruolo di una persona intersecato con quello della tua applicazione quando qualcuno è alle spalle dell'esecuzione, il ruolo della tua applicazione quando non c'è nessuno. La persona è chiunque abbia attivato l'esecuzione in una funzione logica, oppure chiunque stia visualizzando la pagina in un componente front-end.+ * `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — Chiave a breve durata con ambito esclusivamente al ruolo della tua applicazione. Solo funzioni logiche, sempre inserita lì, ed è ciò che utilizza `runAs: 'application'`.- Non è **necessario** passarle ai client — vengono lette automaticamente da `process.env`. I permessi della chiave API sono determinati dal ruolo dichiarato con `defineApplicationRole()` (o referenziato tramite `defaultRoleUniversalIdentifier` in `application-config.ts`).+ **Non** devi passare questi elementi ai client — vengono letti automaticamente da `process.env` e [Quale accesso utilizza una chiamata](#whose-access-a-call-uses) spiega come scegliere tra di essi. Le autorizzazioni della tua applicazione sono determinate dal ruolo dichiarato con `defineApplicationRole()` (o referenziato tramite `defaultRoleUniversalIdentifier` in `application-config.ts`); un'esecuzione che agisce come una persona non può mai superare né tale ruolo né il proprio.</Note>diff --git a/packages/twenty-docs/l/ja/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/ja/developers/extend/apps/config/application.mdxindex 7c982fb1ffa..5face230705 100644--- a/packages/twenty-docs/l/ja/developers/extend/apps/config/application.mdx+++ b/packages/twenty-docs/l/ja/developers/extend/apps/config/application.mdx@@ -97,7 +97,7 @@ const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3[`defineApplicationRole()`](/l/ja/developers/extend/apps/config/roles) で宣言されたロールは、アプリのロジック関数とフロントコンポーネントがアクセスできる内容を制御します。-* `TWENTY_APP_ACCESS_TOKEN` として注入される実行時トークンは、このロールに基づいて生成されます。+* ロジック関数に注入される実行時トークンは、このロールに基づいて生成されます。 人物として動作する呼び出しは、その人物が実行できる範囲によってさらに制限されるため、どちらか一方の権限を超えることはありません。 [呼び出しで使用されるアクセス権](/l/ja/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses)を参照してください。* 型付き API クライアントは、そのロールに付与された権限に制限されます。* 最小権限の原則に従い、関数に必要な権限のみを宣言してください。diff --git a/packages/twenty-docs/l/ja/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/l/ja/developers/extend/apps/getting-started/concepts.mdxindex e2ab754e43e..4f2ce3c905e 100644--- a/packages/twenty-docs/l/ja/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/l/ja/developers/extend/apps/getting-started/concepts.mdx@@ -54,9 +54,9 @@ your-app/## サンドボックス化-* **ロジック関数**は、サーバー上の分離された Node.js プロセスで実行されます。 データへのアクセスは型付き API クライアント経由に限定され、アプリのロール権限の範囲にスコープされます。+* **ロジック関数**は、サーバー上の分離された Node.js プロセスで実行されます。 これらは、実行をトリガーしたユーザーまたはアプリ自体として動作する型付き API クライアントを介してのみデータにアクセスします。 [呼び出しで使用されるアクセス権](/l/ja/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses)を参照してください。* **フロントコンポーネント**は Remote DOM を用いた Web Workers 内で実行されます—メインページからサンドボックス化されつつ、ネイティブの DOM 要素(iframe ではありません)をレンダリングします。 メッセージパッシング型のホスト API を介して Twenty と通信します。-* **権限**は API レベルで強制されます。 実行時トークン(`TWENTY_APP_ACCESS_TOKEN`)は、`defineApplication()` で定義されたロールに基づいて生成されます。+* **権限**は API レベルで強制されます。 `defineApplicationRole()` で宣言されたロールから派生した 2 つのランタイムトークンが挿入されます。デフォルトのトークンは、実行の背後にユーザーがいる場合は常に、そのトリガーとなったユーザーが実行できる操作にさらに制限されます。## アプリのライフサイクルdiff --git a/packages/twenty-docs/l/ja/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/ja/developers/extend/apps/layout/front-components.mdxindex 594fcc6f0cf..11e6c9b0cf3 100644--- a/packages/twenty-docs/l/ja/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/l/ja/developers/extend/apps/layout/front-components.mdx@@ -333,6 +333,8 @@ export default defineLogicFunction({アプリの HTTP ルートを呼び出したり、フロントコンポーネントから Twenty のレコードを読み書きしたりするには、`twenty-client-sdk/rest` の `RestApiClient` を使用します。 これは、`/s/...` のパスをワークスペースの関数のベース URL に送り、`/rest/...` を含むそれ以外のすべてのパスを `TWENTY_API_URL` に送信します。+常にページを見ている人として動作します。 `runAs: 'application'` はロジック関数専用のオプションです。コンポーネントにはアプリケーション自身のトークンが渡されないため、ここでそれを要求するとエラーになります。 アプリ自身のアクセスが必要な処理はロジック関数内に置き、代わりにその関数を呼び出してください。+| メソッド | 説明 || --------------------------------- | ------------------------------------ || `get(path, options?)` | `GET` リクエストを送信します |@@ -445,10 +447,10 @@ export default defineFrontComponent({次のシステム変数は、常に `process.env` 経由で利用できます。-| 変数 | 説明 |-| ------------------------- | -------------------------- |-| `TWENTY_API_URL` | Twenty コア API のベース URL |-| `TWENTY_APP_ACCESS_TOKEN` | アプリのロールにスコープされた有効期間の短いトークン |+| 変数 | 説明 |+| ------------------------- | -------------------------------------------------------------------------------- |+| `TWENTY_API_URL` | Twenty コア API のベース URL |+| `TWENTY_APP_ACCESS_TOKEN` | サインインしている人のロールとアプリのロールの共通部分にスコープ設定された短期間有効なトークン。そのため、コンポーネントが閲覧者以上の権限を持つことはありません |### `TWENTY_FUNCTIONS_URL`diff --git a/packages/twenty-docs/l/ja/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/l/ja/developers/extend/apps/logic/logic-functions.mdxindex dab43f81088..25fbb09340f 100644--- a/packages/twenty-docs/l/ja/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/l/ja/developers/extend/apps/logic/logic-functions.mdx@@ -448,6 +448,78 @@ const handler = async (event: PersonDestroyedEvent) => {};```+#### 実行コンテキスト++すべてのハンドラーは、何によってトリガーされたかにかかわらず、実行自体を説明する2番目の引数を受け取ります。 最初の引数はトリガーごとに形式が変わりますが、こちらは変わりません:++```ts+import type { LogicFunctionExecutionContext } from 'twenty-sdk/logic-function';++const handler = async (+ event: DatabaseEventPayload,+ { workspaceId, workspaceMemberId }: LogicFunctionExecutionContext,+) => {+ if (workspaceMemberId === null) {+ throw new Error('This function must be triggered by a person');+ }++ return { reviewedBy: workspaceMemberId, workspaceId };+};+```++| フィールド | タイプ | 説明 |+| ------------------- | ---------------- | ----------------------------------------------------------------------------------- |+| `workspaceId` | `string` | 実行が属するワークスペース。 |+| `userWorkspaceId` | `string \| null` | このワークスペースにおけるメンバーシップとしての、実行をトリガーした人物。 |+| `workspaceMemberId` | `string \| null` | ワークスペースメンバーのレコードとしての同じ人物であり、レコードをリンクする対象です。 |+| `retryCount` | `number` | 最初の試行では `0`。 [バックグラウンドジョブ](/l/ja/developers/extend/apps/logic/background-jobs)を参照してください。 |+| `maxRetries` | `number` | アプリケーションが要求する再試行回数の上限。 |++誰も実行をトリガーしていない場合、`userWorkspaceId` と `workspaceMemberId` は `null` です。cron スケジュール、インストールフック、および認証されていない Webhook には、それに対応する人物がいません。 その人物にワークスペースメンバーのレコードがない場合、またはそのレコードが削除されている場合も、これらは `null` です。++<Note>+**コンテキストは、誰が実行をトリガーしたかを示します。** 実行で*できること*は、以下で説明する別の宣言です。+</Note>++#### 呼び出しで使用されるアクセス権++すべてのクライアント(`CoreApiClient`、`MetadataApiClient`、`RestApiClient`)は、実行をトリガーした人物として動作します。その人物のロールとアプリケーションのロールの共通部分が適用されるため、呼び出しでできることは、どちらか一方ができることを超えません。 これがデフォルトであり、人物がアプリを使用して自身の権限を超えることは決してできないことを意味します。++誰も実行をトリガーしていない場合、動作する人物がいないため、同じクライアントはアプリケーション自身のアクセス権にフォールバックします。cron スケジュール、インストールフック、および認証されていない Webhook には特別な処理は必要ありません。++人物が実行の背後に*いる*場合でも、アプリケーション自身のアクセス権を正当に必要とする呼び出しがあります。たとえば、アプリの設定レコードの読み取りや、その人物自身では実行できない作業です。 そのために2つ目のクライアントを作成します:++```ts+import { CoreApiClient } from 'twenty-client-sdk/core';++const asPerson = new CoreApiClient();+const asApplication = new CoreApiClient({ runAs: 'application' });++const handler = async (event: DatabaseEventPayload) => {+ // config records only your app may read+ const { slackUserLinks } = await asApplication.query({ ... });++ // created as the person, so it is attributed and permission-checked+ await asPerson.mutation({ createNote: { ... } });+};+```++両方をモジュールスコープで一度だけ作成し、各呼び出し箇所では、呼び出すクライアントによって使用するアクセス権を指定します。 `RestApiClient` も同じオプションを受け取ります:++```ts+import { RestApiClient } from 'twenty-client-sdk/rest';++const asApplication = new RestApiClient({ runAs: 'application' });+```++<Note>+**誰にもトリガーされていない実行は、アプリケーションとして動作します。** cron スケジュール、インストールフック、および認証されていない Webhook には、それに対応する人物がいないため、デフォルトのクライアントはアプリケーション自身のアクセス権にフォールバックして動作し続けます。 `runAs: 'application'` が必要なのは、人物が実行をトリガーした場合にそのアクセス権を使用したいときだけです。++たとえばレコードの帰属先を指定するためなど、誰かが背後にいるかどうかによって関数の動作が異なる場合は、`context.workspaceMemberId` を確認してください。+</Note>++アプリケーション自身のリソースにアクセスする SDK ヘルパーは、常にそのアクセス権を使用し、`runAs` を無視します。[キー値ストア](/l/ja/developers/extend/apps/logic/key-value-store)、[接続](/l/ja/developers/extend/apps/logic/connections)、`runAgent`、`getPublicAssetUrl`、およびクレジットの請求が該当します。+#### 関数を AI ツールまたはワークフロー アクションとして公開するロジック関数は 2 つのサーフェス上で公開でき、それぞれに固有のトリガーがあります:@@ -723,7 +795,7 @@ setCompany(result.company);</Accordion><Accordion title="MetadataApiClient" description="ワークスペースの設定、アプリケーション、ファイルアップロード">-`MetadataApiClient` は SDK に同梱されており、あらかじめビルド済みです(生成は不要)。 ワークスペースの設定、アプリケーション、ファイルアップロードのために `/metadata` エンドポイントに対してクエリを実行します。+`MetadataApiClient` は SDK に同梱されており、あらかじめビルド済みです(生成は不要)。 ワークスペースの設定、アプリケーション、ファイルアップロードのために `/metadata` エンドポイントに対してクエリを実行します。 これは `CoreApiClient` と同じ `runAs` オプションを受け取ります。詳細は[呼び出しで使用されるアクセス権](#whose-access-a-call-uses)を参照してください。```tsimport { MetadataApiClient } from 'twenty-client-sdk/metadata';@@ -791,7 +863,8 @@ console.log(uploadedFile);コードが Twenty 上で実行される際(ロジック関数やフロントコンポーネント)、プラットフォームは認証情報を環境変数として注入します:* `TWENTY_API_URL` — Twenty API のベース URL- * `TWENTY_APP_ACCESS_TOKEN` — アプリケーションのデフォルト関数ロールにスコープされた短命のキー+ * `TWENTY_APP_ACCESS_TOKEN` — デフォルトのアクセス権用の短命のキーです。誰かが実行の背後にいる場合はその人物のロールとアプリケーションのロールの共通部分、誰もいない場合はアプリケーション自身のロールが適用されます。 ロジック関数では実行をトリガーした人、フロントコンポーネントではページを見ている人が、その人物です。+ * `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — アプリケーション自身のロールのみにスコープされた短命のキーです。 ロジック関数でのみ使用され、常にそこに注入されます。また、`runAs: 'application'` が使用するものです。- これらをクライアントに渡す必要はありません — 自動的に `process.env` から読み取ります。 API キーの権限は、`defineApplicationRole()` で宣言されたロール(または `application-config.ts` の `defaultRoleUniversalIdentifier` で参照されるロール)によって決まります。+ これらをクライアントに渡す必要は**ありません**。クライアントは `process.env` から自動的に読み取り、どちらを選択するかについては[呼び出しで使用されるアクセス権](#whose-access-a-call-uses)で説明しています。 アプリケーション自身の権限は、`defineApplicationRole()` で宣言されたロール(または `application-config.ts` の `defaultRoleUniversalIdentifier` で参照されるロール)によって決まります。人物として動作する実行は、そのロールもその人物のロールも超えることはできません。</Note>diff --git a/packages/twenty-docs/l/ko/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/ko/developers/extend/apps/config/application.mdxindex 93ac668600f..2a803397622 100644--- a/packages/twenty-docs/l/ko/developers/extend/apps/config/application.mdx+++ b/packages/twenty-docs/l/ko/developers/extend/apps/config/application.mdx@@ -97,7 +97,7 @@ const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3[`defineApplicationRole()`](/l/ko/developers/extend/apps/config/roles)로 선언된 역할은 앱의 로직 함수와 프런트엔드 컴포넌트가 무엇에 접근할 수 있는지를 제어합니다:-* `TWENTY_APP_ACCESS_TOKEN`로 주입되는 런타임 토큰은 이 역할에서 파생됩니다.+* 로직 함수에 주입되는 런타임 토큰은 이 역할에서 파생됩니다. 사용자 권한으로 작동하는 호출은 해당 사용자가 할 수 있는 작업으로 더욱 제한되므로, 어느 쪽의 권한도 초과할 수 없습니다. [호출이 사용하는 액세스 권한](/l/ko/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses)을 참조하세요.* 타입드 API 클라이언트는 해당 역할에 부여된 권한으로 제한됩니다.* 최소 권한 원칙을 따르세요: 함수에 필요한 권한만 선언하세요.diff --git a/packages/twenty-docs/l/ko/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/l/ko/developers/extend/apps/getting-started/concepts.mdxindex 3d4a9bbb757..a0ee8237386 100644--- a/packages/twenty-docs/l/ko/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/l/ko/developers/extend/apps/getting-started/concepts.mdx@@ -54,9 +54,9 @@ your-app/## 샌드박싱-* **로직 함수**는 서버의 격리된 Node.js 프로세스에서 실행됩니다. 이들은 앱의 역할 권한 범위로 제한된 타입이 지정된 API 클라이언트를 통해서만 데이터에 접근합니다.+* **로직 함수**는 서버의 격리된 Node.js 프로세스에서 실행됩니다. 이들은 타입이 지정된 API 클라이언트를 통해서만 데이터에 액세스하며, 이 클라이언트는 실행을 트리거한 사람 또는 앱 자체로 작동합니다. [호출에 사용되는 액세스 권한](/l/ko/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses)을 참조하세요.* **프런트 컴포넌트**는 Remote DOM을 사용하는 Web Worker에서 실행됩니다 — 메인 페이지와는 샌드박스로 격리되어 있지만 네이티브 DOM 요소를 렌더링합니다(iframe이 아님). 이들은 메시지 전달 호스트 API를 통해 Twenty와 통신합니다.-* **권한**은 API 수준에서 강제 적용됩니다. 런타임 토큰(`TWENTY_APP_ACCESS_TOKEN`)은 `defineApplication()`에 정의된 역할에서 파생됩니다.+* **권한**은 API 수준에서 강제 적용됩니다. `defineApplicationRole()`로 선언된 역할에서 파생된 두 개의 런타임 토큰이 주입됩니다. 기본 토큰은 실행 뒤에 사람이 있는 경우마다 실행을 트리거한 사람이 할 수 있는 작업으로 더 제한됩니다.## 앱 라이프사이클diff --git a/packages/twenty-docs/l/ko/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/ko/developers/extend/apps/layout/front-components.mdxindex cd56821d7c6..b265a5762dc 100644--- a/packages/twenty-docs/l/ko/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/l/ko/developers/extend/apps/layout/front-components.mdx@@ -333,6 +333,8 @@ export default defineLogicFunction({앱 HTTP 라우트를 호출하거나 프론트 컴포넌트에서 Twenty 레코드를 읽고 쓰려면 `twenty-client-sdk/rest`의 `RestApiClient`를 사용하세요. 이 클라이언트는 `/s/...` 경로를 작업공간의 함수 base URL로 전송하고, `/rest/...`를 포함한 그 외 모든 경로는 `TWENTY_API_URL`로 전송합니다.+항상 페이지를 보는 사람으로 작동합니다. `runAs: 'application'`은 로직 함수 전용 옵션입니다. 구성 요소는 애플리케이션 자체 토큰을 절대 받지 않으므로, 여기에서 이를 요청하면 오류가 발생합니다. 앱 자체 액세스가 필요한 작업은 로직 함수 뒤에 두고 대신 이를 호출하세요.+| 방법 | 설명 || --------------------------------- | ------------------------------------- || `get(path, options?)` | `GET` 요청을 전송합니다. |@@ -445,10 +447,10 @@ export default defineFrontComponent({다음 시스템 변수는 항상 `process.env`를 통해 사용할 수 있습니다:-| 변수 | 설명 |-| ------------------------- | ------------------------ |-| `TWENTY_API_URL` | Twenty 코어 API의 기본 URL |-| `TWENTY_APP_ACCESS_TOKEN` | 앱의 역할 범위로 제한된 단기간 유효한 토큰 |+| 변수 | 설명 |+| ------------------------- | ------------------------------------------------------------------------------- |+| `TWENTY_API_URL` | Twenty 코어 API의 기본 URL |+| `TWENTY_APP_ACCESS_TOKEN` | 로그인한 사람의 역할과 앱의 역할이 교차하는 범위로 지정된 단기 토큰이므로, 구성 요소는 이를 보는 사람보다 더 많은 작업을 할 수 없습니다. |### `TWENTY_FUNCTIONS_URL`diff --git a/packages/twenty-docs/l/ko/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/l/ko/developers/extend/apps/logic/logic-functions.mdxindex 089e398d2f4..11442f0f9ef 100644--- a/packages/twenty-docs/l/ko/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/l/ko/developers/extend/apps/logic/logic-functions.mdx@@ -447,6 +447,78 @@ const handler = async (event: PersonDestroyedEvent) => {};```+#### 실행 컨텍스트++모든 핸들러는 무엇이 이를 트리거했는지와 관계없이 실행 자체를 설명하는 두 번째 인수를 받습니다. 첫 번째 인수는 트리거에 따라 형태가 달라지지만, 이 인수는 달라지지 않습니다:++```ts+import type { LogicFunctionExecutionContext } from 'twenty-sdk/logic-function';++const handler = async (+ event: DatabaseEventPayload,+ { workspaceId, workspaceMemberId }: LogicFunctionExecutionContext,+) => {+ if (workspaceMemberId === null) {+ throw new Error('This function must be triggered by a person');+ }++ return { reviewedBy: workspaceMemberId, workspaceId };+};+```++| 필드 | 유형 | 설명 |+| ------------------- | ---------------- | ------------------------------------------------------------------------------------ |+| `workspaceId` | `string` | 실행이 속한 워크스페이스입니다. |+| `userWorkspaceId` | `string \| null` | 실행을 트리거한 사람을 이 워크스페이스의 멤버십으로 나타낸 것입니다. |+| `workspaceMemberId` | `string \| null` | 레코드를 연결하는 대상인 워크스페이스 멤버 레코드로서의 동일한 사람입니다. |+| `retryCount` | `number` | 첫 번째 시도에서는 `0`입니다. [백그라운드 작업](/l/ko/developers/extend/apps/logic/background-jobs)을 참조하세요. |+| `maxRetries` | `number` | 애플리케이션이 요청한 재시도의 상한입니다. |++아무도 실행을 트리거하지 않은 경우 `userWorkspaceId` 및 `workspaceMemberId`는 `null`입니다. cron 일정, 설치 훅 및 인증되지 않은 웹훅에는 그 뒤에 사람이 없습니다. 해당 사람에게 워크스페이스 멤버 레코드가 없거나 그 레코드가 삭제된 경우에도 `null`입니다.++<Note>+**컨텍스트는 실행을 트리거한 사람이 누구인지 알려 줍니다.** 실행이 *수행할 수 있는* 작업은 아래의 별도 선언입니다.+</Note>++#### 호출에서 사용하는 액세스 주체++모든 클라이언트, 즉 `CoreApiClient`, `MetadataApiClient`, `RestApiClient`는 실행을 트리거한 사람으로 동작합니다. 해당 사람의 역할과 애플리케이션의 역할이 교차되므로, 호출은 둘 중 어느 쪽보다도 더 많은 작업을 수행할 수 없습니다. 이것이 기본값이며, 사용자는 앱을 사용해 자신의 권한을 초과할 수 없음을 의미합니다.++아무도 실행을 트리거하지 않은 경우 동작할 사람이 없으므로, 동일한 클라이언트는 애플리케이션 자체의 액세스로 대체됩니다. cron 일정, 설치 훅 및 인증되지 않은 웹훅은 특별한 처리가 필요하지 않습니다.++실행 뒤에 사람이 *있는* 경우에도 일부 호출에는 정당하게 애플리케이션 자체의 액세스가 필요합니다. 예를 들어 앱의 구성 레코드를 읽거나, 해당 사람이 직접 수행할 수 없는 작업을 하는 경우입니다. 이러한 경우를 위한 두 번째 클라이언트를 만드세요:++```ts+import { CoreApiClient } from 'twenty-client-sdk/core';++const asPerson = new CoreApiClient();+const asApplication = new CoreApiClient({ runAs: 'application' });++const handler = async (event: DatabaseEventPayload) => {+ // config records only your app may read+ const { slackUserLinks } = await asApplication.query({ ... });++ // created as the person, so it is attributed and permission-checked+ await asPerson.mutation({ createNote: { ... } });+};+```++둘 다 모듈 범위에서 한 번만 만들면, 각 호출 위치는 호출하는 클라이언트에 따라 사용하는 액세스를 지정합니다. `RestApiClient`도 동일한 옵션을 사용합니다:++```ts+import { RestApiClient } from 'twenty-client-sdk/rest';++const asApplication = new RestApiClient({ runAs: 'application' });+```++<Note>+**아무도 트리거하지 않은 실행은 애플리케이션으로 동작합니다.** cron 일정, 설치 훅 및 인증되지 않은 웹훅에는 그 뒤에 사람이 없으므로, 기본 클라이언트는 애플리케이션 자체의 액세스로 대체되어 계속 작동합니다. `runAs: 'application'`은 사람이 *실제로* 트리거한 실행에서 해당 액세스를 원하는 경우에만 필요합니다.++예를 들어 레코드의 귀속을 지정하는 등, 누군가가 그 뒤에 있는지 여부에 따라 함수가 다르게 동작하는 경우 `context.workspaceMemberId`를 확인하세요.+</Note>++애플리케이션 자체의 리소스에 접근하는 SDK 헬퍼는 항상 해당 액세스를 사용하며 `runAs`를 무시합니다. [키-값 저장소](/l/ko/developers/extend/apps/logic/key-value-store), [연결](/l/ko/developers/extend/apps/logic/connections), `runAgent`, `getPublicAssetUrl`, 크레딧 청구가 이에 해당합니다.+#### 함수를 AI 도구 또는 워크플로 작업으로 노출하기로직 함수는 두 가지 영역에서 노출될 수 있으며, 각 영역마다 자체 트리거가 있습니다:@@ -722,7 +794,7 @@ setCompany(result.company);</Accordion><Accordion title="MetadataApiClient" description="워크스페이스 구성, 애플리케이션, 파일 업로드">-`MetadataApiClient`는 SDK와 함께 사전 빌드된 상태로 제공됩니다(생성 필요 없음). 워크스페이스 구성, 애플리케이션 및 파일 업로드를 위해 `/metadata` 엔드포인트를 조회합니다.+`MetadataApiClient`는 SDK와 함께 사전 빌드된 상태로 제공됩니다(생성 필요 없음). 워크스페이스 구성, 애플리케이션 및 파일 업로드를 위해 `/metadata` 엔드포인트를 조회합니다. 이는 `CoreApiClient`와 동일한 `runAs` 옵션을 사용합니다. [호출에서 사용하는 액세스 주체](#whose-access-a-call-uses)를 참조하세요.```tsimport { MetadataApiClient } from 'twenty-client-sdk/metadata';@@ -790,7 +862,8 @@ console.log(uploadedFile);코드가 Twenty에서 실행될 때(로직 함수 또는 프런트 컴포넌트), 플랫폼이 자격 증명을 환경 변수로 주입합니다:* `TWENTY_API_URL` — Twenty API의 기본 URL- * `TWENTY_APP_ACCESS_TOKEN` — 애플리케이션의 기본 함수 역할 범위로 제한된 단기 키+ * `TWENTY_APP_ACCESS_TOKEN` — 기본 액세스를 위한 단기 키입니다. 실행 뒤에 사람이 있는 경우 해당 사람의 역할과 애플리케이션의 역할이 교차된 역할이며, 아무도 없는 경우 애플리케이션 자체의 역할입니다. 로직 함수에서는 실행을 트리거한 사람이, 프런트 컴포넌트에서는 페이지를 보고 있는 사람이 해당 사람입니다.+ * `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — 애플리케이션 자체의 역할로만 범위가 제한된 단기 키입니다. 로직 함수에서만 사용되며, այնտեղ 항상 주입되고, `runAs: 'application'`이 사용하는 키입니다.- 클라이언트에 이를 전달할 필요가 없습니다 — 자동으로 `process.env`에서 읽습니다. API 키의 권한은 `defineApplicationRole()`으로 선언된 역할(또는 `application-config.ts`의 `defaultRoleUniversalIdentifier`를 통해 참조된 역할)에 의해 결정됩니다.+ 이 키들을 클라이언트에 전달할 필요는 **없습니다**. 클라이언트가 `process.env`에서 자동으로 읽으며, [호출에서 사용하는 액세스 주체](#whose-access-a-call-uses)에서 둘 중 무엇을 선택하는지 다룹니다. 애플리케이션 자체의 권한은 `defineApplicationRole()`로 선언된 역할(또는 `application-config.ts`의 `defaultRoleUniversalIdentifier`를 통해 참조된 역할)로 결정됩니다. 사람으로 동작하는 실행은 해당 역할이나 그 사람의 역할을 절대 초과할 수 없습니다.</Note>diff --git a/packages/twenty-docs/l/pt/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/config/application.mdxindex b1678baabfc..b05a1c4cc5e 100644--- a/packages/twenty-docs/l/pt/developers/extend/apps/config/application.mdx+++ b/packages/twenty-docs/l/pt/developers/extend/apps/config/application.mdx@@ -97,7 +97,7 @@ O mesmo se aplica a componentes de front-end que leem valores via `getApplicatioO papel declarado com [`defineApplicationRole()`](/l/pt/developers/extend/apps/config/roles) controla o que as funções de lógica e os componentes de front-end do aplicativo podem acessar:-* O token em tempo de execução injetado como `TWENTY_APP_ACCESS_TOKEN` é derivado desse papel.+* Os tokens de tempo de execução injetados nas suas funções de lógica são derivados desse papel. Uma chamada que atua como uma pessoa é ainda mais limitada pelo que essa pessoa pode fazer, portanto nunca pode exceder nenhum dos dois. Consulte [Qual acesso uma chamada usa](/l/pt/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* O cliente de API tipado é restrito às permissões concedidas a esse papel.* Siga o princípio do menor privilégio: declare apenas as permissões de que suas funções precisam.diff --git a/packages/twenty-docs/l/pt/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/getting-started/concepts.mdxindex 1e6ed262f43..57bdef7f66e 100644--- a/packages/twenty-docs/l/pt/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/l/pt/developers/extend/apps/getting-started/concepts.mdx@@ -54,9 +54,9 @@ your-app/## Sandboxing-* **Funções lógicas** são executadas em processos Node.js isolados no servidor. Elas acessam dados apenas por meio do cliente de API tipado, restrito às permissões do papel do aplicativo.+* **Funções lógicas** são executadas em processos Node.js isolados no servidor. Eles acessam dados apenas por meio do cliente de API tipado, que atua como a pessoa que disparou a execução ou como o próprio app. Consulte [Qual acesso uma chamada usa](/l/pt/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* **Componentes de front-end** executam em Web Workers usando Remote DOM — isolados da página principal, mas renderizando elementos DOM nativos (não iframes). Eles se comunicam com o Twenty por meio de uma API de host com passagem de mensagens.-* **Permissões** são aplicadas no nível da API. O token de tempo de execução (`TWENTY_APP_ACCESS_TOKEN`) é derivado do papel definido em `defineApplication()`.+* **Permissões** são aplicadas no nível da API. Dois tokens de runtime são inseridos, ambos derivados da função declarada com `defineApplicationRole()`; o padrão é ainda mais limitado ao que a pessoa que disparou a execução pode fazer quando há alguém por trás da execução.## Ciclo de vida do aplicativodiff --git a/packages/twenty-docs/l/pt/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/layout/front-components.mdxindex 0288aaa2a21..2333b17d15e 100644--- a/packages/twenty-docs/l/pt/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/l/pt/developers/extend/apps/layout/front-components.mdx@@ -333,6 +333,8 @@ export default defineLogicFunction({Para chamar rotas HTTP do aplicativo ou ler e gravar registros da Twenty a partir de um front component, use `RestApiClient` de `twenty-client-sdk/rest`. Ele envia caminhos `/s/...` para a URL base das funções do seu workspace e qualquer outro caminho, incluindo `/rest/...`, para `TWENTY_API_URL`.+Ele sempre atua como a pessoa que está visualizando a página. `runAs: 'application'` é uma opção apenas de função de lógica: um componente nunca recebe o token do seu próprio aplicativo, portanto, solicitá-lo aqui gera um erro. Coloque o trabalho que precisa do acesso do próprio aplicativo atrás de uma função de lógica e chame-a em vez disso.+| Método | Descrição || --------------------------------- | ------------------------------------------------------------------------------- || `get(path, options?)` | Envia uma requisição `GET` |@@ -445,10 +447,10 @@ Variáveis secretas (`isSecret: true`) **não** são expostas aos componentes deAs seguintes variáveis de sistema estão sempre disponíveis via `process.env`:-| Variável | Descrição |-| ------------------------- | ------------------------------------------------------------- |-| `TWENTY_API_URL` | URL base da API principal da Twenty |-| `TWENTY_APP_ACCESS_TOKEN` | Token de curta duração limitado ao escopo do papel do seu app |+| Variável | Descrição |+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `TWENTY_API_URL` | URL base da API principal da Twenty |+| `TWENTY_APP_ACCESS_TOKEN` | Token de curta duração com escopo limitado à interseção entre a função da pessoa conectada e a do seu aplicativo, de modo que um componente nunca possa fazer mais do que a pessoa que o está visualizando |### `TWENTY_FUNCTIONS_URL`diff --git a/packages/twenty-docs/l/pt/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/logic/logic-functions.mdxindex 5e96dba71a6..f2f4fb43c60 100644--- a/packages/twenty-docs/l/pt/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/l/pt/developers/extend/apps/logic/logic-functions.mdx@@ -447,6 +447,78 @@ const handler = async (event: PersonDestroyedEvent) => {};```+#### Contexto de execução++Cada manipulador recebe um segundo argumento que descreve a própria execução, independentemente do que a acionou. Enquanto o primeiro argumento muda de formato conforme o acionador, este não muda:++```ts+import type { LogicFunctionExecutionContext } from 'twenty-sdk/logic-function';++const handler = async (+ event: DatabaseEventPayload,+ { workspaceId, workspaceMemberId }: LogicFunctionExecutionContext,+) => {+ if (workspaceMemberId === null) {+ throw new Error('This function must be triggered by a person');+ }++ return { reviewedBy: workspaceMemberId, workspaceId };+};+```++| Campo | Tipo | Descrição |+| ------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------- |+| `workspaceId` | `string` | O espaço de trabalho ao qual a execução pertence. |+| `userWorkspaceId` | `string \| null` | A pessoa que acionou a execução, como seu vínculo neste espaço de trabalho. |+| `workspaceMemberId` | `string \| null` | A mesma pessoa como um registro de membro do espaço de trabalho, ao qual você vincula registros. |+| `retryCount` | `number` | `0` na primeira tentativa. Consulte [Tarefas em segundo plano](/l/pt/developers/extend/apps/logic/background-jobs). |+| `maxRetries` | `number` | Limite superior de novas tentativas solicitadas pelo aplicativo. |++`userWorkspaceId` e `workspaceMemberId` são `null` quando ninguém acionou a execução: agendamentos cron, hooks de instalação e webhooks não autenticados não têm uma pessoa por trás deles. Eles também são `null` quando a pessoa não tem um registro de membro do espaço de trabalho ou quando o seu foi excluído.++<Note>+**O contexto informa quem acionou a execução.** O que a execução pode *fazer* é uma declaração separada, abaixo.+</Note>++#### O acesso que uma chamada usa++Cada cliente — `CoreApiClient`, `MetadataApiClient` e `RestApiClient` — atua como a pessoa que acionou a execução: seu papel é combinado com o do seu aplicativo, portanto a chamada nunca pode fazer mais do que qualquer um dos dois. Esse é o padrão e significa que uma pessoa nunca pode usar seu aplicativo para exceder as próprias permissões.++Quando ninguém acionou a execução, não há uma pessoa para representar, então o mesmo cliente recorre ao acesso do próprio aplicativo: agendamentos cron, hooks de instalação e webhooks não autenticados não exigem tratamento especial.++Algumas chamadas precisam legitimamente do acesso do próprio aplicativo mesmo quando há uma pessoa por trás da execução — para ler os registros de configuração do seu aplicativo ou realizar tarefas que essa pessoa não conseguiria realizar por conta própria. Crie um segundo cliente para essas chamadas:++```ts+import { CoreApiClient } from 'twenty-client-sdk/core';++const asPerson = new CoreApiClient();+const asApplication = new CoreApiClient({ runAs: 'application' });++const handler = async (event: DatabaseEventPayload) => {+ // config records only your app may read+ const { slackUserLinks } = await asApplication.query({ ... });++ // created as the person, so it is attributed and permission-checked+ await asPerson.mutation({ createNote: { ... } });+};+```++Crie ambos uma vez, no escopo do módulo, e cada local de chamada indicará qual acesso usa pelo cliente que chama. `RestApiClient` aceita a mesma opção:++```ts+import { RestApiClient } from 'twenty-client-sdk/rest';++const asApplication = new RestApiClient({ runAs: 'application' });+```++<Note>+**Uma execução que ninguém acionou atua como seu aplicativo.** Agendamentos cron, hooks de instalação e webhooks não autenticados não têm uma pessoa por trás deles, portanto o cliente padrão recorre ao acesso do próprio aplicativo e continua funcionando. `runAs: 'application'` é necessário apenas quando você quer esse acesso em uma execução que uma pessoa *acionou*.++Verifique `context.workspaceMemberId` quando uma função se comportar de modo diferente dependendo de haver alguém por trás dela, por exemplo, para atribuir um registro.+</Note>++Os auxiliares do SDK que acessam os recursos do próprio aplicativo sempre usam o acesso dele e ignoram `runAs`: o [armazenamento de chave-valor](/l/pt/developers/extend/apps/logic/key-value-store), as [conexões](/l/pt/developers/extend/apps/logic/connections), `runAgent`, `getPublicAssetUrl` e a cobrança de créditos.+#### Expor uma função como ferramenta de IA ou como ação de fluxo de trabalhoAs funções de lógica podem ser expostas em duas superfícies, cada uma com seu próprio gatilho:@@ -722,7 +794,7 @@ setCompany(result.company);</Accordion><Accordion title="MetadataApiClient" description="Configuração do espaço de trabalho, aplicativos e upload de arquivos">-`MetadataApiClient` é fornecido pré-compilado com o SDK (não é necessário gerar). Ele consulta o endpoint `/metadata` para configuração do espaço de trabalho, aplicativos e upload de arquivos.+`MetadataApiClient` é fornecido pré-compilado com o SDK (não é necessário gerar). Ele consulta o endpoint `/metadata` para configuração do espaço de trabalho, aplicativos e upload de arquivos. Ele aceita a mesma opção `runAs` que `CoreApiClient` — consulte [O acesso que uma chamada usa](#whose-access-a-call-uses).```tsimport { MetadataApiClient } from 'twenty-client-sdk/metadata';@@ -790,7 +862,8 @@ Pontos-chave:Quando seu código é executado no Twenty (funções de lógica ou componentes de front-end), a plataforma injeta credenciais como variáveis de ambiente:* `TWENTY_API_URL` — URL base da API do Twenty- * `TWENTY_APP_ACCESS_TOKEN` — Chave de curta duração com escopo para o papel de função padrão do seu aplicativo+ * `TWENTY_APP_ACCESS_TOKEN` — Chave de curta duração para o acesso padrão: o papel de uma pessoa combinado com o do seu aplicativo quando há alguém por trás da execução, o papel do próprio aplicativo quando não há ninguém. A pessoa é quem acionou a execução em uma função lógica ou quem está visualizando a página em um componente front.+ * `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — Chave de curta duração com escopo apenas para o papel do próprio aplicativo. Apenas funções lógicas, sempre injetada nelas, e é o que `runAs: 'application'` usa.- Você **não** precisa passá-las para os clientes — eles leem de `process.env` automaticamente. As permissões da chave de API são determinadas pelo papel declarado com `defineApplicationRole()` (ou referenciado via `defaultRoleUniversalIdentifier` em `application-config.ts`).+ Você **não** precisa passá-las aos clientes — eles leem de `process.env` automaticamente, e [O acesso que uma chamada usa](#whose-access-a-call-uses) explica como escolher entre elas. As permissões do próprio aplicativo são determinadas pelo papel declarado com `defineApplicationRole()` (ou referenciado via `defaultRoleUniversalIdentifier` em `application-config.ts`); uma execução que atua como uma pessoa nunca pode exceder esse papel nem o dela.</Note>diff --git a/packages/twenty-docs/l/ro/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/config/application.mdxindex 5437625c1c8..e89fdb18621 100644--- a/packages/twenty-docs/l/ro/developers/extend/apps/config/application.mdx+++ b/packages/twenty-docs/l/ro/developers/extend/apps/config/application.mdx@@ -97,7 +97,7 @@ Același lucru se aplică și componentelor de interfață care citesc valori prRolul declarat cu [`defineApplicationRole()`](/l/ro/developers/extend/apps/config/roles) controlează la ce pot avea acces funcțiile logice și componentele de interfață ale aplicației:-* Tokenul de runtime injectat ca `TWENTY_APP_ACCESS_TOKEN` este derivat din acest rol.+* Tokenurile de runtime injectate în funcțiile dvs. de logică sunt derivate din acest rol. Un apel care acționează ca o persoană este restrâns suplimentar la ceea ce poate face acea persoană, astfel încât nu poate depăși niciodată niciuna dintre cele două limite. Consultați [Ce acces utilizează un apel](/l/ro/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* Clientul API tipizat este restricționat la permisiunile acordate acelui rol.* Respectați principiul celui mai mic privilegiu: declarați doar permisiunile de care au nevoie funcțiile.diff --git a/packages/twenty-docs/l/ro/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/getting-started/concepts.mdxindex 1fc7b98d1f9..9d0b7956943 100644--- a/packages/twenty-docs/l/ro/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/l/ro/developers/extend/apps/getting-started/concepts.mdx@@ -54,9 +54,9 @@ your-app/## Izolare (sandboxing)-* **Funcțiile logice** rulează în procese Node.js izolate pe server. Acestea accesează datele doar prin clientul API tipizat, limitat de permisiunile rolului aplicației.+* **Funcțiile logice** rulează în procese Node.js izolate pe server. Acestea accesează datele numai prin clientul API tipizat, care acționează fie ca persoana care a declanșat execuția, fie ca aplicația în sine. Consultați [Ce acces utilizează un apel](/l/ro/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* **Componentele front-end** rulează în Web Workers folosind Remote DOM — izolate de pagina principală, dar randând elemente DOM native (nu iframes). Acestea comunică cu Twenty printr-un API al gazdei bazat pe transmiterea de mesaje.-* **Permisiunile** sunt aplicate la nivelul API-ului. Tokenul de rulare (`TWENTY_APP_ACCESS_TOKEN`) este derivat din rolul definit în `defineApplication()`.+* **Permisiunile** sunt aplicate la nivelul API-ului. Sunt injectate două tokenuri de execuție, ambele derivate din rolul declarat cu `defineApplicationRole()`; cel implicit este restrâns suplimentar la ceea ce poate face persoana care a declanșat execuția, ori de câte ori o persoană se află în spatele execuției.## Ciclul de viață al aplicațieidiff --git a/packages/twenty-docs/l/ro/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/layout/front-components.mdxindex d8f12bd99e9..02c5d08ed10 100644--- a/packages/twenty-docs/l/ro/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/l/ro/developers/extend/apps/layout/front-components.mdx@@ -333,6 +333,8 @@ export default defineLogicFunction({Pentru a apela rute HTTP ale aplicației sau pentru a citi și scrie înregistrări Twenty dintr-un front component, folosește `RestApiClient` din `twenty-client-sdk/rest`. Trimite căile de forma `/s/...` către URL-ul de bază al funcțiilor spațiului tău de lucru, iar orice altă cale, inclusiv `/rest/...`, către `TWENTY_API_URL`.+Acționează întotdeauna ca persoana care se uită la pagină. `runAs: 'application'` este o opțiune exclusivă pentru funcțiile logice: o componentă nu primește niciodată propriul token al aplicației tale, astfel că solicitarea lui aici generează o eroare. Pune activitatea care necesită propriul acces al aplicației în spatele unei funcții logice și apeleaz-o în schimb pe aceasta.+| Metodă | Descriere || --------------------------------- | ----------------------------------------------------------------------------- || `get(path, options?)` | Trimite o cerere `GET` |@@ -445,10 +447,10 @@ Variabilele secrete (`isSecret: true`) **nu** sunt expuse componentelor de interUrmătoarele variabile de sistem sunt întotdeauna disponibile prin `process.env`:-| Variabilă | Descriere |-| ------------------------- | -------------------------------------------------------- |-| `TWENTY_API_URL` | URL-ul de bază al API-ului de bază Twenty |-| `TWENTY_APP_ACCESS_TOKEN` | Token cu durată scurtă, limitat la rolul aplicației dvs. |+| Variabilă | Descriere |+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `TWENTY_API_URL` | URL-ul de bază al API-ului de bază Twenty |+| `TWENTY_APP_ACCESS_TOKEN` | Token cu durată scurtă, limitat la rolul persoanei autentificate intersectat cu cel al aplicației tale, astfel încât o componentă nu poate face niciodată mai mult decât persoana care o privește |### `TWENTY_FUNCTIONS_URL`diff --git a/packages/twenty-docs/l/ro/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/logic/logic-functions.mdxindex ff8ae2a7a2c..1add0847d1f 100644--- a/packages/twenty-docs/l/ro/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/l/ro/developers/extend/apps/logic/logic-functions.mdx@@ -448,6 +448,78 @@ const handler = async (event: PersonDestroyedEvent) => {};```+#### Contextul execuției.++Fiecare gestionar primește un al doilea argument care descrie execuția propriu-zisă, indiferent de ce a declanșat-o. În timp ce primul argument își schimbă forma pentru fiecare declanșator, acesta nu se schimbă:++```ts+import type { LogicFunctionExecutionContext } from 'twenty-sdk/logic-function';++const handler = async (+ event: DatabaseEventPayload,+ { workspaceId, workspaceMemberId }: LogicFunctionExecutionContext,+) => {+ if (workspaceMemberId === null) {+ throw new Error('This function must be triggered by a person');+ }++ return { reviewedBy: workspaceMemberId, workspaceId };+};+```++| Câmp | Tip | Descriere |+| ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------ |+| `workspaceId` | `string` | Spațiul de lucru căruia îi aparține execuția. |+| `userWorkspaceId` | `string \| null` | Persoana care a declanșat execuția, ca membru al acestui spațiu de lucru. |+| `workspaceMemberId` | `string \| null` | Aceeași persoană ca înregistrare de membru al spațiului de lucru, la care conectați înregistrări. |+| `retryCount` | `number` | `0` la prima încercare. Consultați [sarcini de fundal](/l/ro/developers/extend/apps/logic/background-jobs). |+| `maxRetries` | `number` | Limita superioară a reîncercărilor solicitate de aplicație. |++`userWorkspaceId` și `workspaceMemberId` sunt `null` atunci când nimeni nu a declanșat execuția: programările cron, hookurile de instalare și webhookurile neautentificate nu au nicio persoană în spatele lor. De asemenea, sunt `null` atunci când persoana nu are o înregistrare de membru al spațiului de lucru sau când aceasta a fost ștearsă.++<Note>+**Contextul vă indică cine a declanșat execuția.** Ceea ce poate *face* execuția este o declarație separată, mai jos.+</Note>++#### Ale cui accesări le utilizează un apel++Fiecare client — `CoreApiClient`, `MetadataApiClient` și `RestApiClient` — acționează ca persoana care a declanșat execuția: rolul acesteia se intersectează cu cel al aplicației dvs., astfel încât apelul nu poate face niciodată mai mult decât poate face oricare dintre voi. Acesta este comportamentul implicit și înseamnă că o persoană nu poate folosi niciodată aplicația dvs. pentru a-și depăși propriile permisiuni.++Când nimeni nu a declanșat execuția, nu există nicio persoană în numele căreia să se acționeze, astfel încât același client revine la accesul propriu al aplicației dvs.: programările cron, hookurile de instalare și webhookurile neautentificate nu necesită o gestionare specială.++Unele apeluri au nevoie în mod legitim de accesul propriu al aplicației chiar și atunci când o persoană *se află* în spatele execuției — de exemplu, pentru a citi înregistrările de configurare ale aplicației dvs. sau pentru a efectua lucrări pe care persoana respectivă nu le-ar putea face singură. Creați un al doilea client pentru acestea:++```ts+import { CoreApiClient } from 'twenty-client-sdk/core';++const asPerson = new CoreApiClient();+const asApplication = new CoreApiClient({ runAs: 'application' });++const handler = async (event: DatabaseEventPayload) => {+ // config records only your app may read+ const { slackUserLinks } = await asApplication.query({ ... });++ // created as the person, so it is attributed and permission-checked+ await asPerson.mutation({ createNote: { ... } });+};+```++Creați-le pe amândouă o singură dată, la nivel de modul, iar fiecare loc de apel indică apoi accesul utilizat prin clientul pe care îl apelează. `RestApiClient` acceptă aceeași opțiune:++```ts+import { RestApiClient } from 'twenty-client-sdk/rest';++const asApplication = new RestApiClient({ runAs: 'application' });+```++<Note>+**O execuție pe care nu a declanșat-o nimeni acționează ca aplicația dvs.** Programările cron, hookurile de instalare și webhookurile neautentificate nu au nicio persoană în spatele lor, astfel încât clientul implicit revine la accesul propriu al aplicației dvs. și continuă să funcționeze. `runAs: 'application'` este necesar doar când doriți acel acces într-o execuție pe care o persoană *a* declanșat-o.++Verificați `context.workspaceMemberId` atunci când o funcție se comportă diferit în funcție de existența unei persoane în spatele ei, de exemplu pentru a atribui o înregistrare.+</Note>++Ajutoarele SDK care accesează resursele proprii ale aplicației dvs. folosesc întotdeauna accesul acesteia și ignoră `runAs`: [stocarea cheie-valoare](/l/ro/developers/extend/apps/logic/key-value-store), [conexiunile](/l/ro/developers/extend/apps/logic/connections), `runAgent`, `getPublicAssetUrl` și taxarea creditelor.+#### Expunerea unei funcții ca instrument AI sau ca acțiune în fluxul de lucruFuncțiile logice pot fi expuse în două locuri, fiecare cu propriul declanșator:@@ -723,7 +795,7 @@ setCompany(result.company);</Accordion><Accordion title="MetadataApiClient" description="Configurația spațiului de lucru, aplicații și încărcări de fișiere">-`MetadataApiClient` este livrat preconstruit împreună cu SDK-ul (nu este necesară generarea). Interoghează endpointul `/metadata` pentru configurarea spațiului de lucru, aplicații și încărcări de fișiere.+`MetadataApiClient` este livrat preconstruit împreună cu SDK-ul (nu este necesară generarea). Interoghează endpointul `/metadata` pentru configurarea spațiului de lucru, aplicații și încărcări de fișiere. Acceptă aceeași opțiune `runAs` ca `CoreApiClient` — consultați [Ale cui accesări le utilizează un apel](#whose-access-a-call-uses).```tsimport { MetadataApiClient } from 'twenty-client-sdk/metadata';@@ -777,7 +849,7 @@ console.log(uploadedFile);| ---------------------------------- | -------- | ------------------------------------------------------------------- || `fileBuffer` | `Buffer` | Conținutul brut al fișierului || `filename` | `string` | Numele fișierului (folosit pentru stocare și afișare) |-| `contentType` | `string` | Tipul MIME (implicit `application/octet-stream` dacă este omis) |+| `contentType` | `șir` | Tipul MIME (implicit `application/octet-stream` dacă este omis) || `fieldMetadataUniversalIdentifier` | `șir` | `universalIdentifier` al câmpului de tip fișier de pe obiectul dvs. |Puncte cheie:@@ -791,7 +863,8 @@ Puncte cheie:Când codul dvs. rulează pe Twenty (funcții de logică sau componente Front), platforma injectează acreditările ca variabile de mediu:* `TWENTY_API_URL` — URL-ul de bază al API-ului Twenty- * `TWENTY_APP_ACCESS_TOKEN` — Cheie cu durată scurtă, limitată la rolul implicit de funcție al aplicației+ * `TWENTY_APP_ACCESS_TOKEN` — Cheie cu durată scurtă pentru accesul implicit: rolul unei persoane se intersectează cu cel al aplicației dvs. atunci când cineva se află în spatele execuției, iar rolul propriu al aplicației dvs. atunci când nu se află nimeni. Persoana este cea care a declanșat execuția într-o funcție logică sau cea care privește pagina într-o componentă front-end.+ * `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — Cheie cu durată scurtă, limitată numai la rolul propriu al aplicației dvs. Numai funcții logice, injectată întotdeauna acolo și utilizată de `runAs: 'application'`.- Nu trebuie să le transmiteți clienților — aceștia citesc automat din `process.env`. Permisiunile cheii API sunt determinate de rolul declarat cu `defineApplicationRole()` (sau referențiat prin `defaultRoleUniversalIdentifier` în `application-config.ts`).+ Nu trebuie să transmiteți aceste valori clienților — aceștia citesc automat din `process.env`, iar [Ale cui accesări le utilizează un apel](#whose-access-a-call-uses) explică alegerea dintre ele. Permisiunile proprii ale aplicației dvs. sunt determinate de rolul declarat cu `defineApplicationRole()` (sau referențiat prin `defaultRoleUniversalIdentifier` în `application-config.ts`); o execuție care acționează ca o persoană nu poate depăși niciodată acel rol sau rolul persoanei.</Note>diff --git a/packages/twenty-docs/l/ru/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/ru/developers/extend/apps/config/application.mdxindex 18e92785dce..abc499001be 100644--- a/packages/twenty-docs/l/ru/developers/extend/apps/config/application.mdx+++ b/packages/twenty-docs/l/ru/developers/extend/apps/config/application.mdx@@ -97,7 +97,7 @@ const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3Роль, объявленная с помощью [`defineApplicationRole()`](/l/ru/developers/extend/apps/config/roles), определяет, к чему могут получать доступ логические функции и фронтенд‑компоненты приложения:-* Токен времени выполнения, подставляемый как `TWENTY_APP_ACCESS_TOKEN`, формируется из этой роли.+* Токены времени выполнения, подставляемые в ваши функции логики, формируются из этой роли. Вызов, выполняемый от имени пользователя, дополнительно ограничен тем, что может делать этот пользователь, поэтому он никогда не может превышать ни один из них. См. [Чей доступ использует вызов](/l/ru/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* Типизированный клиент API ограничен правами, предоставленными этой роли.* Следуйте принципу наименьших привилегий: объявляйте только те разрешения, которые действительно нужны вашим функциям.diff --git a/packages/twenty-docs/l/ru/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/l/ru/developers/extend/apps/getting-started/concepts.mdxindex a983d4e8a99..c691d16c392 100644--- a/packages/twenty-docs/l/ru/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/l/ru/developers/extend/apps/getting-started/concepts.mdx@@ -54,9 +54,9 @@ your-app/## Изоляция в песочнице-* **Логические функции** выполняются в изолированных процессах Node.js на сервере. Они получают доступ к данным только через типизированный клиент API, ограниченный правами роли приложения.+* **Логические функции** выполняются в изолированных процессах Node.js на сервере. Они получают доступ к данным только через типизированный API-клиент, который действует либо от имени человека, запустившего выполнение, либо от имени самого приложения. См. [Чей доступ использует вызов](/l/ru/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* **Компоненты фронтенда** запускаются в Web Workers с использованием Remote DOM — изолированы от основной страницы, но при этом рендерят нативные элементы DOM (не iframes). Они взаимодействуют с Twenty через хостовый API обмена сообщениями.-* **Права доступа** применяются на уровне API. Токен времени выполнения (`TWENTY_APP_ACCESS_TOKEN`) выводится из роли, определённой в `defineApplication()`.+* **Права доступа** применяются на уровне API. Внедряются два токена времени выполнения, оба производные от роли, объявленной с помощью `defineApplicationRole()`; область действия токена по умолчанию дополнительно ограничивается тем, что может делать человек, запустивший выполнение, когда за выполнением стоит человек.## Жизненный цикл приложенияdiff --git a/packages/twenty-docs/l/ru/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/ru/developers/extend/apps/layout/front-components.mdxindex 5c183f5d0fd..e3e0f2a0d22 100644--- a/packages/twenty-docs/l/ru/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/l/ru/developers/extend/apps/layout/front-components.mdx@@ -333,6 +333,8 @@ export default defineLogicFunction({Чтобы вызывать HTTP-маршруты приложения или читать и изменять записи Twenty из фронт-компонента, используйте `RestApiClient` из `twenty-client-sdk/rest`. Он отправляет пути вида `/s/...` на базовый URL функций вашего рабочего пространства, а все остальные пути, включая `/rest/...`, — на `TWENTY_API_URL`.+Он всегда действует от имени человека, просматривающего страницу. `runAs: 'application'` — это параметр только для логической функции: компонент никогда не получает собственный токен вашего приложения, поэтому его запрос здесь вызывает ошибку. Поместите работу, требующую собственного доступа приложения, за логическую функцию и вызывайте вместо этого её.+| Метод | Описание || --------------------------------- | ----------------------------------------------------------------- || `get(path, options?)` | Отправляет запрос `GET` |@@ -445,10 +447,10 @@ export default defineFrontComponent({Следующие системные переменные всегда доступны через `process.env`:-| Переменная | Описание |-| ------------------------- | ----------------------------------------------------------------------------- |-| `TWENTY_API_URL` | Базовый URL основного API Twenty |-| `TWENTY_APP_ACCESS_TOKEN` | Краткоживущий токен с областью действия, ограниченной ролью вашего приложения |+| Переменная | Описание |+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `TWENTY_API_URL` | Базовый URL основного API Twenty |+| `TWENTY_APP_ACCESS_TOKEN` | Кратковременный токен, область действия которого ограничена пересечением роли вошедшего в систему пользователя и роли вашего приложения, поэтому компонент никогда не сможет сделать больше, чем человек, который его просматривает |### `TWENTY_FUNCTIONS_URL`diff --git a/packages/twenty-docs/l/ru/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/l/ru/developers/extend/apps/logic/logic-functions.mdxindex 594390e8372..ac7a240a059 100644--- a/packages/twenty-docs/l/ru/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/l/ru/developers/extend/apps/logic/logic-functions.mdx@@ -447,6 +447,78 @@ const handler = async (event: PersonDestroyedEvent) => {};```+#### Контекст выполнения++Каждый обработчик получает второй аргумент, описывающий сам запуск независимо от того, что его вызвало. Если форма первого аргумента меняется в зависимости от триггера, то форма этого не меняется:++```ts+import type { LogicFunctionExecutionContext } from 'twenty-sdk/logic-function';++const handler = async (+ event: DatabaseEventPayload,+ { workspaceId, workspaceMemberId }: LogicFunctionExecutionContext,+) => {+ if (workspaceMemberId === null) {+ throw new Error('This function must be triggered by a person');+ }++ return { reviewedBy: workspaceMemberId, workspaceId };+};+```++| Поле | Тип | Описание |+| ------------------- | ---------------- | --------------------------------------------------------------------------------------------- |+| `workspaceId` | `string` | Рабочее пространство, к которому относится запуск. |+| `userWorkspaceId` | `string \| null` | Человек, вызвавший запуск, представленный своим участием в этом рабочем пространстве. |+| `workspaceMemberId` | `string \| null` | Тот же человек в виде записи участника рабочего пространства, к которой привязываются записи. |+| `retryCount` | `number` | `0` при первой попытке. См. [Фоновые задачи](/l/ru/developers/extend/apps/logic/background-jobs). |+| `maxRetries` | `number` | Верхняя граница количества повторных попыток, запрошенных приложением. |++`userWorkspaceId` и `workspaceMemberId` имеют значение `null`, когда запуск никто не вызвал: у cron-расписаний, хуков установки и неаутентифицированных вебхуков нет человека, стоящего за ними. Они также имеют значение `null`, когда у человека нет записи участника рабочего пространства или когда она была удалена.++<Note>+**Контекст сообщает, кто вызвал запуск.** То, что запуск может *делать*, определяется отдельно, ниже.+</Note>++#### Чьи права доступа использует вызов++Каждый клиент — `CoreApiClient`, `MetadataApiClient` и `RestApiClient` — действует от имени человека, вызвавшего запуск: его роль пересекается с ролью вашего приложения, поэтому вызов никогда не может сделать больше, чем позволяет любая из этих ролей. Это поведение по умолчанию, и оно означает, что человек никогда не сможет использовать ваше приложение для превышения собственных разрешений.++Когда запуск никто не вызвал, нет человека, от имени которого можно действовать, поэтому тот же клиент использует права доступа самого приложения: cron-расписания, хуки установки и неаутентифицированные вебхуки не требуют специальной обработки.++Для некоторых вызовов правомерно требуются права доступа самого приложения, даже когда за запуском *стоит* человек — например, для чтения записей конфигурации вашего приложения или выполнения работы, которую этот человек не мог бы выполнить сам. Создайте для них второй клиент:++```ts+import { CoreApiClient } from 'twenty-client-sdk/core';++const asPerson = new CoreApiClient();+const asApplication = new CoreApiClient({ runAs: 'application' });++const handler = async (event: DatabaseEventPayload) => {+ // config records only your app may read+ const { slackUserLinks } = await asApplication.query({ ... });++ // created as the person, so it is attributed and permission-checked+ await asPerson.mutation({ createNote: { ... } });+};+```++Создайте оба клиента один раз в области видимости модуля, и тогда каждый сайт вызова будет указывать используемые права доступа через вызываемый клиент. `RestApiClient` принимает тот же параметр:++```ts+import { RestApiClient } from 'twenty-client-sdk/rest';++const asApplication = new RestApiClient({ runAs: 'application' });+```++<Note>+**Запуск, который никто не вызвал, действует как ваше приложение.** У cron-расписаний, хуков установки и неаутентифицированных вебхуков нет человека, стоящего за ними, поэтому клиент по умолчанию использует права доступа самого приложения и продолжает работать. `runAs: 'application'` нужен только тогда, когда вам требуются эти права доступа в запуске, который *вызвал* человек.++Проверяйте `context.workspaceMemberId`, когда функция ведет себя по-разному в зависимости от того, стоит ли за ней кто-то, например чтобы указать автора записи.+</Note>++Помощники SDK, обращающиеся к собственным ресурсам вашего приложения, всегда используют его права доступа и игнорируют `runAs`: [хранилище ключей и значений](/l/ru/developers/extend/apps/logic/key-value-store), [подключения](/l/ru/developers/extend/apps/logic/connections), `runAgent`, `getPublicAssetUrl` и списание кредитов.+#### Предоставление функции в качестве инструмента ИИ или действия рабочего процессаФункции логики могут быть представлены в двух интерфейсах, у каждого — свой триггер:@@ -722,7 +794,7 @@ setCompany(result.company);</Accordion><Accordion title="MetadataApiClient" description="Конфигурация рабочего пространства, приложения и загрузка файлов">-`MetadataApiClient` поставляется в готовом виде вместе с SDK (генерация не требуется). Он выполняет запросы к эндпоинту `/metadata` для получения конфигурации рабочего пространства, приложений и загрузки файлов.+`MetadataApiClient` поставляется в готовом виде вместе с SDK (генерация не требуется). Он выполняет запросы к эндпоинту `/metadata` для получения конфигурации рабочего пространства, приложений и загрузки файлов. Он принимает тот же параметр `runAs`, что и `CoreApiClient` — см. [Чьи права доступа использует вызов](#whose-access-a-call-uses).```tsimport { MetadataApiClient } from 'twenty-client-sdk/metadata';@@ -790,7 +862,8 @@ console.log(uploadedFile);Когда ваш код выполняется на Twenty (логические функции или фронт-компоненты), платформа предоставляет учётные данные в виде переменных окружения:* `TWENTY_API_URL` — базовый URL API Twenty- * `TWENTY_APP_ACCESS_TOKEN` — краткоживущий ключ, ограниченный ролью функции по умолчанию вашего приложения+ * `TWENTY_APP_ACCESS_TOKEN` — краткоживущий ключ для прав доступа по умолчанию: роль человека пересекается с ролью вашего приложения, когда за запуском кто-то стоит; если никто не стоит — используется собственная роль вашего приложения. В логической функции человек — это тот, кто вызвал запуск, а во фронтенд-компоненте — тот, кто просматривает страницу.+ * `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — краткоживущий ключ, ограниченный исключительно собственной ролью вашего приложения. Только для логических функций, всегда внедряется в них и используется `runAs: 'application'`.- Вам не нужно передавать их клиентам — они автоматически читаются из `process.env`. Права ключа API определяются ролью, объявленной с помощью `defineApplicationRole()` (или указанной через `defaultRoleUniversalIdentifier` в `application-config.ts`).+ Вам **не** нужно передавать их клиентам — они автоматически считываются из `process.env`, а в разделе [Чьи права доступа использует вызов](#whose-access-a-call-uses) описан выбор между ними. Собственные разрешения вашего приложения определяются ролью, объявленной с помощью `defineApplicationRole()` (или указанной через `defaultRoleUniversalIdentifier` в `application-config.ts`); запуск, действующий от имени человека, никогда не может превысить ни эту роль, ни его собственную.</Note>diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/config/application.mdxindex f116ba955de..0d754e4305d 100644--- a/packages/twenty-docs/l/tr/developers/extend/apps/config/application.mdx+++ b/packages/twenty-docs/l/tr/developers/extend/apps/config/application.mdx@@ -97,7 +97,7 @@ Aynısı, `getApplicationVariable('VARIABLE_NAME')` ile değerleri okuyan ön bi[`defineApplicationRole()`](/l/tr/developers/extend/apps/config/roles) ile bildirilen rol, uygulamanın iş mantığı işlevlerinin ve ön uç bileşenlerinin neye erişebileceğini kontrol eder:-* `TWENTY_APP_ACCESS_TOKEN` olarak enjekte edilen çalışma zamanı belirteci bu rolden türetilir.+* Mantık işlevlerinize enjekte edilen çalışma zamanı belirteçleri bu rolden türetilir. Bir kişi olarak davranan çağrı, o kişinin yapabilecekleriyle daha da sınırlandırılır; dolayısıyla hiçbir zaman ikisinden birini aşamaz. Bkz. [Bir çağrının kullandığı erişim](/l/tr/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).* Türlendirilmiş API istemcisi, o role tanınan izinlerle sınırlandırılır.* En az ayrıcalık ilkesini izleyin: yalnızca fonksiyonlarınızın ihtiyaç duyduğu izinleri bildirin.diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/getting-started/concepts.mdxindex 332eff3276b..8157dc0a29a 100644--- a/packages/twenty-docs/l/tr/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/l/tr/developers/extend/apps/getting-started/concepts.mdx@@ -54,9 +54,9 @@ your-app/## Korumalı alan-* **Mantık işlevleri** sunucuda yalıtılmış Node.js işlemlerinde çalışır. Verilere yalnızca, kapsamı uygulamanın rol izinleriyle sınırlandırılmış tipli API istemcisi üzerinden erişirler.+* **Mantık işlevleri** sunucuda yalıtılmış Node.js işlemlerinde çalışır. Verilere yalnızca, çalıştırmayı tetikleyen kişi veya uygulamanın kendisi olarak hareket eden tür güvenlikli API istemcisi aracılığıyla erişirler. [Bir çağrının hangi erişimi kullandığına](/l/tr/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses) bakın.* **Ön uç bileşenleri**, Remote DOM kullanan Web Worker'larda çalışır — ana sayfadan yalıtılmıştır ancak yerel DOM öğelerini (iframe'ler değil) oluşturur. Twenty ile mesaj iletimi yapan bir ana makine API'si aracılığıyla iletişim kurarlar.-* **İzinler**, API düzeyinde uygulanır. Çalışma zamanı belirteci (`TWENTY_APP_ACCESS_TOKEN`), `defineApplication()` içinde tanımlanan rolden türetilir.+* **İzinler**, API düzeyinde uygulanır. Her ikisi de `defineApplicationRole()` ile tanımlanan rolden türetilen iki çalışma zamanı belirteci eklenir; varsayılan belirteç, çalıştırmanın arkasında biri olduğunda tetikleyen kişinin yapabilecekleriyle daha da sınırlandırılır.## Uygulama yaşam döngüsüdiff --git a/packages/twenty-docs/l/tr/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/layout/front-components.mdxindex ea2b0506bcd..a6d3d3c58f9 100644--- a/packages/twenty-docs/l/tr/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/l/tr/developers/extend/apps/layout/front-components.mdx@@ -333,6 +333,8 @@ export default defineLogicFunction({Uygulama HTTP rotalarını çağırmak veya bir front bileşeninden Twenty kayıtlarını okumak ve yazmak için `twenty-client-sdk/rest` paketinden `RestApiClient` kullanın. `/s/...` yollarını çalışma alanınızdaki işlevlerin temel URL'sine, `/rest/...` dahil diğer tüm yolları ise `TWENTY_API_URL`'ye gönderir.+Her zaman sayfayı görüntüleyen kişi olarak hareket eder. `runAs: 'application'` yalnızca bir mantık işlevi seçeneğidir: bir bileşen uygulamanızın kendi token'ını asla almaz; dolayısıyla burada bunu istemek hata verir. Uygulamanın kendi erişimini gerektiren işleri bir mantık işlevinin arkasına yerleştirin ve bunun yerine onu çağırın.+| Yöntem | Açıklama || --------------------------------- | ------------------------------------------------------------------------ || `get(path, options?)` | Bir `GET` isteği gönderir |@@ -445,10 +447,10 @@ Gizli değişkenler (`isSecret: true`) ön uç bileşenlere açıklanmaz. BunlarAşağıdaki sistem değişkenleri her zaman `process.env` aracılığıyla kullanılabilir:-| Değişken | Açıklama |-| ------------------------- | --------------------------------------------------------- |-| `TWENTY_API_URL` | Twenty çekirdek API'sinin temel URL'si |-| `TWENTY_APP_ACCESS_TOKEN` | Uygulamanızın rolüyle sınırlanan kısa ömürlü bir belirteç |+| Değişken | Açıklama |+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| `TWENTY_API_URL` | Twenty çekirdek API'sinin temel URL'si |+| `TWENTY_APP_ACCESS_TOKEN` | Oturum açmış kişinin roluyla uygulamanızın rolunun kesişimiyle kapsamı belirlenen kısa ömürlü token; böylece bir bileşen, onu görüntüleyen kişiden asla daha fazlasını yapamaz |### `TWENTY_FUNCTIONS_URL`diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/logic/logic-functions.mdxindex cbf339e4505..839862db840 100644--- a/packages/twenty-docs/l/tr/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/l/tr/developers/extend/apps/logic/logic-functions.mdx@@ -448,6 +448,78 @@ const handler = async (event: PersonDestroyedEvent) => {};```+#### Yürütme bağlamı++Her işleyici, onu neyin tetiklediğinden bağımsız olarak çalıştırmanın kendisini açıklayan ikinci bir bağımsız değişken alır. İlk bağımsız değişken tetikleyiciye göre biçim değiştirirken, bu değişmez:++```ts+import type { LogicFunctionExecutionContext } from 'twenty-sdk/logic-function';++const handler = async (+ event: DatabaseEventPayload,+ { workspaceId, workspaceMemberId }: LogicFunctionExecutionContext,+) => {+ if (workspaceMemberId === null) {+ throw new Error('This function must be triggered by a person');+ }++ return { reviewedBy: workspaceMemberId, workspaceId };+};+```++| Alan | Tür | Açıklama |+| ------------------- | ---------------- | --------------------------------------------------------------------------------------------------- |+| `workspaceId` | `string` | Çalıştırmanın ait olduğu çalışma alanı. |+| `userWorkspaceId` | `string \| null` | Çalıştırmayı tetikleyen kişi, bu çalışma alanındaki üyeliği olarak. |+| `workspaceMemberId` | `string \| null` | Kayıtları bağladığınız çalışma alanı üyesi kaydı olarak aynı kişi. |+| `retryCount` | `number` | İlk denemede `0`. [Arka plan işleri](/l/tr/developers/extend/apps/logic/background-jobs) bölümüne bakın. |+| `maxRetries` | `number` | Uygulama tarafından istenen yeniden denemelerin üst sınırı. |++Kimse çalıştırmayı tetiklemediğinde `userWorkspaceId` ve `workspaceMemberId` `null` olur: cron zamanlamalarının, yükleme kancalarının ve kimliği doğrulanmamış webhook'ların arkasında kişi yoktur. Kişinin çalışma alanı üyesi kaydı olmadığında veya bu kayıt silindiğinde de `null` olurlar.++<Note>+**Bağlam, çalıştırmayı kimin tetiklediğini söyler.** Çalıştırmanın ne *yapabileceği* aşağıda ayrı bir bildirimdir.+</Note>++#### Bir çağrının hangi erişimi kullandığı++Her istemci — `CoreApiClient`, `MetadataApiClient` ve `RestApiClient` — çalıştırmayı tetikleyen kişi olarak davranır: kişinin rolü uygulamanızın rolüyle kesiştirilir; dolayısıyla çağrı hiçbir zaman ikinizden birinin yapabileceğinden fazlasını yapamaz. Bu varsayılandır ve bir kişinin kendi izinlerini aşmak için uygulamanızı asla kullanamayacağı anlamına gelir.++Çalıştırmayı kimse tetiklemediğinde adına davranılacak bir kişi yoktur; bu nedenle aynı istemci uygulamanızın kendi erişimine geri döner: cron zamanlamaları, yükleme kancaları ve kimliği doğrulanmamış webhook'lar özel işlem gerektirmez.++Bazı çağrılar, çalıştırmanın arkasında bir kişi *olsa bile* haklı olarak uygulamanın kendi erişimine ihtiyaç duyar — uygulamanızın yapılandırma kayıtlarını okumak veya o kişinin kendisinin yapamayacağı işleri gerçekleştirmek gibi. Bunlar için ikinci bir istemci oluşturun:++```ts+import { CoreApiClient } from 'twenty-client-sdk/core';++const asPerson = new CoreApiClient();+const asApplication = new CoreApiClient({ runAs: 'application' });++const handler = async (event: DatabaseEventPayload) => {+ // config records only your app may read+ const { slackUserLinks } = await asApplication.query({ ... });++ // created as the person, so it is attributed and permission-checked+ await asPerson.mutation({ createNote: { ... } });+};+```++Her ikisini de modül kapsamında bir kez oluşturun; ardından her çağrı noktası, çağırdığı istemciyle hangi erişimi kullandığını belirtir. `RestApiClient` aynı seçeneği alır:++```ts+import { RestApiClient } from 'twenty-client-sdk/rest';++const asApplication = new RestApiClient({ runAs: 'application' });+```++<Note>+**Kimsenin tetiklemediği bir çalıştırma uygulamanız olarak davranır.** Cron zamanlamalarının, yükleme kancalarının ve kimliği doğrulanmamış webhook'ların arkasında kişi yoktur; bu nedenle varsayılan istemci uygulamanızın kendi erişimine geri döner ve çalışmaya devam eder. `runAs: 'application'`, yalnızca bir kişinin *tetiklediği* çalıştırmada bu erişimi istediğinizde gereklidir.++Örneğin bir kaydı atfetmek için, bir işlev arkasında birinin olup olmamasına bağlı olarak farklı davranıyorsa `context.workspaceMemberId` değerini kontrol edin.+</Note>++Uygulamanızın kendi kaynaklarına erişen SDK yardımcıları her zaman kendi erişimini kullanır ve `runAs` değerini yok sayar: [anahtar-değer deposu](/l/tr/developers/extend/apps/logic/key-value-store), [bağlantılar](/l/tr/developers/extend/apps/logic/connections), `runAgent`, `getPublicAssetUrl` ve kredi ücretlendirmesi.+#### Bir işlevi bir yapay zekâ aracı veya iş akışı eylemi olarak kullanıma sunmaMantık işlevleri, her birinin kendi tetikleyicisi olacak şekilde iki yerde kullanılabilir hâle getirilebilir:@@ -723,7 +795,7 @@ setCompany(result.company);</Accordion><Accordion title="MetadataApiClient" description="Ç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.+`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. `CoreApiClient` ile aynı `runAs` seçeneğini alır — [Bir çağrının hangi erişimi kullandığı](#whose-access-a-call-uses) bölümüne bakın.```tsimport { MetadataApiClient } from 'twenty-client-sdk/metadata';@@ -791,7 +863,8 @@ console.log(uploadedFile);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+ * `TWENTY_APP_ACCESS_TOKEN` — Varsayılan erişim için kısa ömürlü anahtar: çalıştırmanın arkasında biri olduğunda kişinin rolü uygulamanızın rolüyle kesiştirilir, kimse olmadığında uygulamanızın kendi rolü kullanılır. Kişi, bir mantık işlevinde çalıştırmayı tetikleyen kişi; bir ön bileşende ise sayfaya bakan kişidir.+ * `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — Yalnızca uygulamanızın kendi rolü kapsamında olan kısa ömürlü anahtar. Yalnızca mantık işlevlerinde, her zaman oraya eklenir ve `runAs: 'application'` tarafından kullanılır.- 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.+ Bunları istemcilere geçirmeniz **gerekmez** — bunları `process.env` üzerinden otomatik olarak okurlar ve [Bir çağrının hangi erişimi kullandığı](#whose-access-a-call-uses) bölümü aralarından seçim yapmayı açıklar. Uygulamanızın kendi izinleri, `defineApplicationRole()` ile bildirilen role (veya `application-config.ts` içindeki `defaultRoleUniversalIdentifier` üzerinden referans verilen role) göre belirlenir; kişi olarak davranan bir çalıştırma ne bu rolü ne de kişinin rolünü aşabilir.</Note>diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/config/application.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/config/application.mdxindex b3e9b4f6ddc..35d8ec1e167 100644--- a/packages/twenty-docs/l/zh/developers/extend/apps/config/application.mdx+++ b/packages/twenty-docs/l/zh/developers/extend/apps/config/application.mdx@@ -97,7 +97,7 @@ const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3使用 [`defineApplicationRole()`](/l/zh/developers/extend/apps/config/roles) 声明的角色控制应用的逻辑函数和前端组件可以访问的内容:-* 作为 `TWENTY_APP_ACCESS_TOKEN` 注入的运行时令牌来源于该角色。+* 注入到您的逻辑函数中的运行时令牌来源于该角色。 以某个人的身份执行的调用会进一步受限于该人能够执行的操作,因此其权限永远不会超过两者中的任一方。 请参阅[调用使用谁的访问权限](/l/zh/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses)。* 类型化 API 客户端将受限于授予该角色的权限。* 遵循最小权限原则:只声明你的函数所需的权限。diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/getting-started/concepts.mdxindex e219b50f81b..d334984ecf3 100644--- a/packages/twenty-docs/l/zh/developers/extend/apps/getting-started/concepts.mdx+++ b/packages/twenty-docs/l/zh/developers/extend/apps/getting-started/concepts.mdx@@ -54,9 +54,9 @@ your-app/## 沙盒化-* **逻辑函数** 在服务器上的独立 Node.js 进程中运行。 它们只能通过类型化的 API 客户端访问数据,且范围受应用角色权限限制。+* **逻辑函数** 在服务器上的独立 Node.js 进程中运行。 它们仅通过类型化 API 客户端访问数据,该客户端会以触发运行的人员或应用本身的身份执行操作。 请参阅[调用使用谁的访问权限](/l/zh/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses)。* **前端组件** 在使用 Remote DOM 的 Web Worker 中运行——与主页面沙盒隔离,但渲染原生 DOM 元素(非 iframe)。 它们通过消息传递的宿主 API 与 Twenty 通信。-* **权限** 在 API 层面强制执行。 运行时令牌(`TWENTY_APP_ACCESS_TOKEN`)源自 `defineApplication()` 中定义的角色。+* **权限** 在 API 层面强制执行。 系统会注入两个运行时令牌,二者均派生自通过 `defineApplicationRole()` 声明的角色;只要运行由人员触发,默认令牌的权限范围就会进一步缩小为该触发人员可执行的操作。## 应用生命周期diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/layout/front-components.mdxindex c46723310e3..63ed375b6cc 100644--- a/packages/twenty-docs/l/zh/developers/extend/apps/layout/front-components.mdx+++ b/packages/twenty-docs/l/zh/developers/extend/apps/layout/front-components.mdx@@ -333,6 +333,8 @@ export default defineLogicFunction({要在前端组件中调用应用 HTTP 路由或读取、写入 Twenty 记录,请使用来自 `twenty-client-sdk/rest` 的 `RestApiClient`。 它会将 `/s/...` 路径发送到你工作区的函数基础 URL,而将包括 `/rest/...` 在内的其他所有路径发送到 `TWENTY_API_URL`。+它始终以查看页面的人的身份行事。 `runAs: 'application'` 仅是逻辑函数选项:组件永远不会收到你自己的应用令牌,因此在此请求它会抛出错误。 将需要访问应用自身资源的工作放在逻辑函数后面,并改为调用该函数。+| 方法 | 描述 || --------------------------------- | ----------------------------- || `get(path, options?)` | 发送一个 `GET` 请求 |@@ -445,10 +447,10 @@ export default defineFrontComponent({以下系统变量始终可以通过 `process.env` 获取:-| 变量 | 描述 |-| ------------------------- | --------------------- |-| `TWENTY_API_URL` | Twenty 核心 API 的基础 URL |-| `TWENTY_APP_ACCESS_TOKEN` | 限定在你的应用角色范围内的短期令牌 |+| 变量 | 描述 |+| ------------------------- | --------------------------------------------------- |+| `TWENTY_API_URL` | Twenty 核心 API 的基础 URL |+| `TWENTY_APP_ACCESS_TOKEN` | 短期令牌,其作用域是登录人员的角色与应用角色的交集,因此组件永远无法执行超出查看它的人员权限范围的操作 |### `TWENTY_FUNCTIONS_URL`diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/logic/logic-functions.mdxindex a1fb57b18be..4ff0e275d53 100644--- a/packages/twenty-docs/l/zh/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/l/zh/developers/extend/apps/logic/logic-functions.mdx@@ -448,6 +448,78 @@ const handler = async (event: PersonDestroyedEvent) => {};```+#### 执行上下文++每个处理程序都会收到第二个参数,用于描述运行本身,无论是什么触发了它。 第一个参数会因触发器而具有不同的结构,而这个参数不会:++```ts+import type { LogicFunctionExecutionContext } from 'twenty-sdk/logic-function';++const handler = async (+ event: DatabaseEventPayload,+ { workspaceId, workspaceMemberId }: LogicFunctionExecutionContext,+) => {+ if (workspaceMemberId === null) {+ throw new Error('This function must be triggered by a person');+ }++ return { reviewedBy: workspaceMemberId, workspaceId };+};+```++| 字段 | 类型 | 描述 |+| ------------------- | ---------------- | --------------------------------------------------------------------- |+| `workspaceId` | `string` | 该运行所属的工作区。 |+| `userWorkspaceId` | `string \| null` | 触发该运行的人员,以其作为此工作区成员的身份。 |+| `workspaceMemberId` | `string \| null` | 同一人员的工作区成员记录,也就是你链接记录时使用的对象。 |+| `retryCount` | `number` | 首次尝试时为 `0`。 请参阅[后台作业](/l/zh/developers/extend/apps/logic/background-jobs)。 |+| `maxRetries` | `number` | 应用程序请求重试次数的上限。 |++当没有人触发运行时,`userWorkspaceId` 和 `workspaceMemberId` 为 `null`:cron 计划、安装钩子和未经身份验证的 Webhook 背后没有人员。 当该人员没有工作区成员记录,或者其记录已被删除时,它们也为 `null`。++<Note>+**上下文会告诉你是谁触发了运行。** 运行可以*执行*什么操作则是下面单独的声明。+</Note>++#### 调用使用谁的访问权限++每个客户端 — `CoreApiClient`、`MetadataApiClient` 和 `RestApiClient` — 都会以触发运行的人员身份执行操作:其角色与你的应用程序角色相交,因此调用所能执行的操作绝不会超过你们任一方的权限。 这是默认行为,意味着人员绝不能使用你的应用超出其自身权限。++当没有人触发运行时,没有可代为执行操作的人员,因此同一客户端会回退到使用你的应用程序自身访问权限:cron 计划、安装钩子和未经身份验证的 Webhook 无需特殊处理。++即使运行背后*有*人员,某些调用也确实需要应用程序自身的访问权限 — 例如读取应用的配置记录,或执行该人员自己无法完成的工作。 为这些情况构建第二个客户端:++```ts+import { CoreApiClient } from 'twenty-client-sdk/core';++const asPerson = new CoreApiClient();+const asApplication = new CoreApiClient({ runAs: 'application' });++const handler = async (event: DatabaseEventPayload) => {+ // config records only your app may read+ const { slackUserLinks } = await asApplication.query({ ... });++ // created as the person, so it is attributed and permission-checked+ await asPerson.mutation({ createNote: { ... } });+};+```++在模块作用域中一次性构建两个客户端,之后每个调用位置都会通过所调用的客户端表明其使用的访问权限。 `RestApiClient` 接受相同的选项:++```ts+import { RestApiClient } from 'twenty-client-sdk/rest';++const asApplication = new RestApiClient({ runAs: 'application' });+```++<Note>+**无人触发的运行会以你的应用程序身份执行。** Cron 计划、安装钩子和未经身份验证的 Webhook 背后没有人员,因此默认客户端会回退到使用你的应用程序自身访问权限,并继续正常工作。 仅当你希望在由人员*触发*的运行中使用该访问权限时,才需要 `runAs: 'application'`。++当函数的行为取决于其背后是否有人员时,请检查 `context.workspaceMemberId`,例如用于为记录归属。+</Note>++用于访问你的应用程序自身资源的 SDK 辅助工具始终使用其访问权限,并忽略 `runAs`:包括[键值存储](/l/zh/developers/extend/apps/logic/key-value-store)、[连接](/l/zh/developers/extend/apps/logic/connections)、`runAgent`、`getPublicAssetUrl` 和积分扣费。+#### 将函数公开为 AI 工具或工作流操作逻辑函数可以在两个入口对外公开,每个入口都有各自的触发器:@@ -723,7 +795,7 @@ setCompany(result.company);</Accordion><Accordion title="MetadataApiClient" description="工作区配置、应用和文件上传">-`MetadataApiClient` 随 SDK 一并提供,已预构建(无需生成)。 它会查询 `/metadata` 端点以获取工作区配置、应用和文件上传。+`MetadataApiClient` 随 SDK 一并提供,已预构建(无需生成)。 它会查询 `/metadata` 端点以获取工作区配置、应用和文件上传。 它接受与 `CoreApiClient` 相同的 `runAs` 选项 — 请参阅[调用使用谁的访问权限](#whose-access-a-call-uses)。```tsimport { MetadataApiClient } from 'twenty-client-sdk/metadata';@@ -791,7 +863,8 @@ console.log(uploadedFile);当你的代码在 Twenty 上运行(逻辑函数或前端组件)时,平台会以环境变量的形式注入凭据:* `TWENTY_API_URL`——Twenty API 的基础 URL- * `TWENTY_APP_ACCESS_TOKEN`——作用域限定为你的应用默认函数角色的短期密钥+ * `TWENTY_APP_ACCESS_TOKEN` — 用于默认访问权限的短期密钥:当运行背后有人员时,使用该人员角色与你的应用程序角色的交集;当没有人员时,使用你的应用程序自身角色。 在逻辑函数中,该人员是触发运行的人;在前端组件中,则是正在查看页面的人。+ * `TWENTY_APP_APPLICATION_ACCESS_TOKEN` — 仅限定于你的应用程序自身角色的短期密钥。 仅用于逻辑函数,始终会在其中注入,并由 `runAs: 'application'` 使用。- 你无需将这些值传递给客户端——它们会自动从 `process.env` 读取。 API 密钥的权限由使用 `defineApplicationRole()` 声明的角色(或在 `application-config.ts` 中通过 `defaultRoleUniversalIdentifier` 引用的角色)决定。+ 你**不**需要将这些传递给客户端 — 它们会自动从 `process.env` 读取,而[调用使用谁的访问权限](#whose-access-a-call-uses)介绍了如何在它们之间进行选择。 你的应用程序自身权限由通过 `defineApplicationRole()` 声明的角色(或在 `application-config.ts` 中通过 `defaultRoleUniversalIdentifier` 引用的角色)决定;以人员身份执行的运行绝不能超出该角色或该人员角色的权限。</Note>