Skip to content

The open alternative to Salesforce, designed for AI.

Write postcard content with ai.generate; mark /rest/ai/generate-text deprecated (#29525)

Félix Malfait1c812a71cc5d
diff --git a/packages/twenty-apps/examples/postcard/package.json b/packages/twenty-apps/examples/postcard/package.json
index 7564e0a4793..fc5f389362e 100644
--- a/packages/twenty-apps/examples/postcard/package.json
+++ b/packages/twenty-apps/examples/postcard/package.json
@@ -6,7 +6,7 @@
"node": "^24.5.0",
"npm": "please-use-yarn",
"yarn": ">=4.0.2",
- "twenty": ">=2.23.0"
+ "twenty": ">=2.56.0"
},
"keywords": [
"twenty-app"
diff --git a/packages/twenty-apps/examples/postcard/src/components/generate-post-card-component-effect.tsx b/packages/twenty-apps/examples/postcard/src/components/generate-post-card-component-effect.tsx
index 5da024d96a9..42595057c7e 100644
--- a/packages/twenty-apps/examples/postcard/src/components/generate-post-card-component-effect.tsx
+++ b/packages/twenty-apps/examples/postcard/src/components/generate-post-card-component-effect.tsx
@@ -6,12 +6,20 @@ import {
updateProgress,
useRecordId,
} from 'twenty-sdk/front-component';
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { RestApiClient, RestApiClientError } from 'twenty-client-sdk/rest';
-const SYSTEM_PROMPT =
- 'You are a postcard writing assistant. Write a short, warm postcard message ' +
- 'under 150 words. Use a personal tone. Output ONLY the postcard message ' +
- 'text, nothing else — no greeting label, no sign-off label, just the message.';
+// the route answers failures with a non-2xx status, so its reason is in the error body
+const getErrorMessage = (error: unknown): string => {
+ if (error instanceof RestApiClientError) {
+ const body = error.body as { error?: string } | undefined;
+
+ if (body?.error) {
+ return body.error;
+ }
+ }
+
+ return error instanceof Error ? error.message : 'Failed to generate content';
+};
const GeneratePostCardEffect = () => {
const recordId = useRecordId();
@@ -28,57 +36,15 @@ const GeneratePostCardEffect = () => {
const generate = async () => {
try {
- const client = new CoreApiClient();
-
- const userPrompt = 'Write a postcard message for a friend.';
-
- const apiBaseUrl = process.env.TWENTY_API_URL;
- const token =
- process.env.TWENTY_APP_ACCESS_TOKEN ?? process.env.TWENTY_API_KEY;
-
- if (!apiBaseUrl || !token) {
- throw new Error('API configuration missing');
- }
+ const result = await new RestApiClient().post<{
+ success: boolean;
+ error?: string;
+ }>('/s/post-cards/generate', { recordId });
- const response = await fetch(`${apiBaseUrl}/rest/ai/generate-text`, {
- method: 'POST',
- headers: {
- 'Content-Type': 'application/json',
- Authorization: `Bearer ${token}`,
- },
- body: JSON.stringify({
- systemPrompt: SYSTEM_PROMPT,
- userPrompt,
- }),
- });
-
- if (!response.ok) {
- const errorBody = await response.text();
-
- if (errorBody.includes('No AI models are available')) {
- throw new Error(
- 'No AI models configured. Go to Settings > Admin Panel > AI to add a provider API key.',
- );
- }
-
- throw new Error(`AI request failed with status ${response.status}`);
+ if (!result.success) {
+ throw new Error(result.error ?? 'Failed to generate content');
}
- const data = (await response.json()) as { text?: string };
- const generatedContent = data.text ?? '';
-
- await updateProgress(0.7);
-
- await client.mutation({
- updatePostCard: {
- __args: {
- id: recordId,
- data: { content: generatedContent },
- },
- id: true,
- },
- });
-
await updateProgress(1);
await enqueueSnackbar({
@@ -89,10 +55,7 @@ const GeneratePostCardEffect = () => {
await unmountFrontComponent();
} catch (error) {
await enqueueSnackbar({
- message:
- error instanceof Error
- ? error.message
- : 'Failed to generate content',
+ message: getErrorMessage(error),
variant: 'error',
});
await unmountFrontComponent();
diff --git a/packages/twenty-apps/examples/postcard/src/logic-functions/generate-post-card-content.ts b/packages/twenty-apps/examples/postcard/src/logic-functions/generate-post-card-content.ts
new file mode 100644
index 00000000000..9f06e6aa550
--- /dev/null
+++ b/packages/twenty-apps/examples/postcard/src/logic-functions/generate-post-card-content.ts
@@ -0,0 +1,82 @@
+import { CoreApiClient } from 'twenty-client-sdk/core';
+import { defineLogicFunction, type RoutePayload } from 'twenty-sdk/define';
+import { ai, Response } from 'twenty-sdk/logic-function';
+
+const SYSTEM_PROMPT =
+ 'You are a postcard writing assistant. Write a short, warm postcard message ' +
+ 'under 150 words. Use a personal tone. Output ONLY the postcard message ' +
+ 'text, nothing else — no greeting label, no sign-off label, just the message.';
+
+const UUID_PATTERN =
+ /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+const respond = ({
+ body,
+ status = 200,
+}: {
+ body: { success: boolean; error?: string };
+ status?: number;
+}) =>
+ new Response(JSON.stringify(body), {
+ status,
+ headers: { 'Content-Type': 'application/json' },
+ });
+
+const handler = async (event: RoutePayload): Promise<Response> => {
+ // API keys reach the route without a user, and would otherwise act with this app's own role
+ if (!event.userWorkspaceId) {
+ return respond({
+ body: {
+ success: false,
+ error: 'Only a workspace member can generate a post card',
+ },
+ status: 403,
+ });
+ }
+
+ const recordId = (event.body as { recordId?: unknown } | null)?.recordId;
+
+ if (typeof recordId !== 'string' || !UUID_PATTERN.test(recordId)) {
+ return respond({
+ body: { success: false, error: 'recordId must be a UUID' },
+ status: 400,
+ });
+ }
+
+ const result = await ai.generate({
+ instructions: SYSTEM_PROMPT,
+ input: 'Write a postcard message for a friend.',
+ });
+
+ if (!result.success || !result.text) {
+ return respond({
+ body: {
+ success: false,
+ error: result.error ?? 'The model returned no text',
+ },
+ status: 502,
+ });
+ }
+
+ await new CoreApiClient().mutation({
+ updatePostCard: {
+ __args: { id: recordId, data: { content: result.text } },
+ id: true,
+ },
+ });
+
+ return respond({ body: { success: true } });
+};
+
+export default defineLogicFunction({
+ universalIdentifier: '9adae148-35aa-431a-8854-fae3b27c3870',
+ name: 'generate-post-card-content',
+ description: 'Writes the content of a post card with ai.generate.',
+ timeoutSeconds: 60,
+ handler,
+ httpRouteTriggerSettings: {
+ path: '/post-cards/generate',
+ httpMethod: 'POST',
+ isAuthRequired: true,
+ },
+});
diff --git a/packages/twenty-apps/examples/postcard/src/roles/default-function.role.ts b/packages/twenty-apps/examples/postcard/src/roles/default-function.role.ts
index 9069023bd3b..07aaf7ae1c3 100644
--- a/packages/twenty-apps/examples/postcard/src/roles/default-function.role.ts
+++ b/packages/twenty-apps/examples/postcard/src/roles/default-function.role.ts
@@ -36,5 +36,8 @@ export default defineRole({
canUpdateFieldValue: true,
},
],
- permissionFlagUniversalIdentifiers: [SystemPermissionFlag.APPLICATIONS],
+ permissionFlagUniversalIdentifiers: [
+ SystemPermissionFlag.APPLICATIONS,
+ SystemPermissionFlag.AI,
+ ],
});
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-generate-text/constants/ai-generate-text-deprecation-header-value.constant.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-generate-text/constants/ai-generate-text-deprecation-header-value.constant.ts
new file mode 100644
index 00000000000..3bb813873d0
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-generate-text/constants/ai-generate-text-deprecation-header-value.constant.ts
@@ -0,0 +1 @@
+export const AI_GENERATE_TEXT_DEPRECATION_HEADER_VALUE = `@${Math.floor(new Date('2026-11-03T00:00:00Z').getTime() / 1000)}`;
diff --git a/packages/twenty-server/src/engine/metadata-modules/ai/ai-generate-text/controllers/ai-generate-text.controller.ts b/packages/twenty-server/src/engine/metadata-modules/ai/ai-generate-text/controllers/ai-generate-text.controller.ts
index 490cbddce6a..6e090309486 100644
--- a/packages/twenty-server/src/engine/metadata-modules/ai/ai-generate-text/controllers/ai-generate-text.controller.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/ai/ai-generate-text/controllers/ai-generate-text.controller.ts
@@ -1,10 +1,18 @@
-import { Body, Controller, Post, UseFilters, UseGuards } from '@nestjs/common';
+import {
+ Body,
+ Controller,
+ Header,
+ Post,
+ UseFilters,
+ UseGuards,
+} from '@nestjs/common';
import { generateText } from 'ai';
import { PermissionFlagType } from 'twenty-shared/constants';
import { ApiPath } from 'twenty-shared/types';
import { RestApiExceptionFilter } from 'src/engine/api/rest/rest-api-exception.filter';
+import { AI_GENERATE_TEXT_DEPRECATION_HEADER_VALUE } from 'src/engine/metadata-modules/ai/ai-generate-text/constants/ai-generate-text-deprecation-header-value.constant';
import { UsageLimitRestApiExceptionFilter } from 'src/engine/core-modules/usage-limit/filters/usage-limit-rest-api-exception.filter';
import { getWorkspaceAuthContext } from 'src/engine/core-modules/auth/storage/workspace-auth-context.storage';
import { UsageOperationType } from 'src/engine/core-modules/usage/enums/usage-operation-type.enum';
@@ -60,7 +68,9 @@ export class AiGenerateTextController {
private readonly aiBillingService: AiBillingService,
) {}
+ // deprecated: use the `generate` GraphQL mutation, or ai.generate in a logic function
@Post('generate-text')
+ @Header('Deprecation', AI_GENERATE_TEXT_DEPRECATION_HEADER_VALUE)
@UseGuards(SettingsPermissionGuard(PermissionFlagType.AI))
async handleGenerateText(
@Body() body: GenerateTextInput,