Hooks d'installation

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

​

En un coup d’œil

​

Comportement partagé par les deux hooks

• La configuration est une configuration defineLogicFunction moins les paramètres de déclencheur, plus shouldRunOnVersionUpgrade.
• Quand il s’exécute : uniquement lors des nouvelles installations, par défaut. Définissez shouldRunOnVersionUpgrade: true pour qu’il s’exécute également lors des mises à niveau. Utilisez previousVersion / newVersion pour bifurquer selon le chemin de mise à niveau.
• L’idempotence est importante : le post-install asynchrone peut être relancé, et chaque hook est réexécuté lors des mises à niveau lorsque shouldRunOnVersionUpgrade est activé.
• L’environnement habituel des fonctions logiques (APPLICATION_ID, APP_ACCESS_TOKEN, API_URL) est injecté, ce qui vous permet d’appeler l’API Twenty avec le jeton de votre application.
• Le hook est rattaché automatiquement au manifeste de l’application au moment de la compilation (preInstallLogicFunction / postInstallLogicFunction) — rien à référencer dans defineApplication().
• La valeur par défaut de timeoutSeconds est 300 pour permettre des tâches de configuration plus longues comme l’initialisation des données.
• Non exécuté en mode dev : yarn twenty dev ignore le flux d’installation et synchronise directement les fichiers, donc les hooks ne s’exécutent jamais dans ce cas. Déclenchez-les manuellement à la place :

yarn twenty dev:function:exec --postInstall
yarn twenty dev:function:exec --preInstall

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

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

  const client = new CoreApiClient();
  await client.mutation({
    createPostCard: {
      __args: { data: { name: 'Welcome to Postcard', content: 'Your first card!' } },
      id: true,
    },
  });
};

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

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

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

  const client = new CoreApiClient();
  const { postCards } = await client.query({
    postCards: {
      __args: { filter: { notes: { isNot: null } } },
      edges: { node: { id: true, notes: true } },
    },
  });

  // Copy legacy `notes` into `description` before the migration drops the
  // column. If this fails, the upgrade aborts and the workspace stays on v1.
  for (const { node } of postCards.edges) {
    await client.mutation({
      updatePostCard: {
        __args: { id: node.id, data: { description: node.notes } },
        id: true,
      },
    });
  }
};

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

​

Hook de désinstallation

• Le hook fonctionne selon le principe du “best effort” : il s’exécute de manière synchrone, mais un échec est consigné dans les journaux et ne bloque jamais la désinstallation — le nettoyage ne doit pas rendre une application impossible à supprimer.
• Il reçoit UninstallPayload ({ version?: string } — la version supprimée).
• Il ne s’exécute pas lorsqu’une nouvelle installation ayant échoué est annulée — l’application n’a jamais terminé son installation.
• Le hook ne peut pas s’exécuter après la suppression de l’application, donc le nettoyage externe qui dépend des données de l’application (par exemple des identifiants de bots stockés dans des enregistrements) doit être effectué ici, et non dans une tâche planifiée externe.
• Comme les hooks d’installation, il n’est pas exécuté en mode dev — déclenchez-le manuellement à la place :

yarn twenty dev:function:exec --uninstall

import { defineUninstallLogicFunction, type UninstallPayload } from 'twenty-sdk/define';
import { CoreApiClient } from 'twenty-client-sdk/core';

const handler = async (_payload: UninstallPayload): Promise<void> => {
  const client = new CoreApiClient();
  const { meetingBots } = await client.query({
    meetingBots: { edges: { node: { id: true, externalBotId: true } } },
  });

  // Delete the provider-side bots so nothing keeps recording after uninstall.
  for (const { node } of meetingBots.edges) {
    await fetch(`https://api.recorder.example/bots/${node.externalBotId}`, {
      method: 'DELETE',
      headers: { Authorization: `Bearer ${process.env.RECORDER_API_KEY}` },
    });
  }
};

export default defineUninstallLogicFunction({
  universalIdentifier: 'b2c3d4e5-6789-01bc-def0-234567890abc',
  name: 'uninstall',
  description: 'Deletes remaining recorder bots when the app is uninstalled.',
  timeoutSeconds: 300,
  handler,
});