---
title: API Client
slug: oip-next/xzAZ-api-client
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-30T15:26:03.000Z
---

# Présentation

L'API client expose les éléments suivants (*named exports*) :

- la méthode `start` qui permet d'initialiser l'application *React* ;
- le hook `useProcess` qui permet la gestion des transitions et des tâches depuis les composants des vues de l'OAV ;
- le hook `useCommitMutation` qui permet la gestion d'une mutation graphQL depuis les composants des vue de l'OAV ;
- le hook `useSubscription` qui permet la gestion d'une subscription graphQL depuis les composants des vue de l'OAV ;
- la définition des queries graphQL `TaskSubscription` et `TaskWorkflowSubscription` qui permettent de souscrire à l'état d'une tâche ou d'un *workflow* de tâches (à utiliser avec le hook `useSubscription`) ;
- le composant `Router` qui permet d'initialiser les routes de l'OAV et de configurer la navigation navigateur ;
- le hook `useClientSync` lié à la fonctionnalité de la synchronisation des connexions clientes ;
- le hook `useBlockBrowserNav` qui permet de désactiver la navigation navigateur pour la vue appelante.

Les imports depuis l'OAV :

```javascript
import {
  start,
  useProcess,
  Router,
  useCommitMutation,
  useSubscription,
  TaskSubscription,
  TaskWorkflowSubscription,
  useClientSync,
  useBlockBrowserNav,
} from '@fasstech/oip-starter-utils/app';
```

# Méthode start

La méthode `start` initialise l'application *React* de l'OAV. Elle prend en paramètre un objet de configuration.

Exemple :

:::CodeblockTabs
index.js

```javascript
import { start } from '@fasstech/oip-starter-utils/app';

// Init client app
(() => {
  start({ /* properties */ })();
})();
```
:::

## Propriétés requises

### app

Le composant `App` de l'OAV est attendu en valeur. Le composant `App` doit impérativement charger le composant `Router` fournit par la lib.

Exemple :

:::CodeblockTabs
index.js

```javascript
import { start, Router } from '@fasstech/oip-starter-utils/app';

// App component
const App = () => {
  // ...

  return (
    <>
      <OtherProvider>
        {/* Router component must be returned */}
        <Router views={views} />
      </OtherProvider>
    </>
  );
};

// Init client app
(() => {
  start({
    app: App,
    // ...
  });
})();
```
:::

### processFragment

La définition du fragment graphQL de l'obje&#x74;*&#x20;Process* est attendue en valeur.

Exemple :

:::CodeblockTabs
index.js

```javascript
import { start } from '@fasstech/oip-starter-utils/app';
import { gql } from '@apollo/client';

// Process fragment def
const ProcessFragment = gql`
  fragment ProcessFragment on ExtendedProcess {
    # required fields
    projectId
    viewId
    viewData
    sessionId
    clientId

    # additional fields
    # requested fields must match type definition at server/graphql/types/extended-process-type.mjs
    # add your custom fields here
    # ...
  }
`;

// Init client app
(() => {
  start({
    processFragment: ProcessFragment,
    // ...
  });
})();
```
:::

## Propriétés optionnelles

### ctx

Définit la manière dont le token du contexte client est récupéré lors du décrochage sur l'OAV.

Valeurs possibles : `'local-storage' | 'session-storage' | 'shadow-crm' | 'url' | { token: string } | { projectId: string }`

Par défaut ou si la méthode spécifiée échoue, le token est recherché dans les paramètres de l'URL (paramètre `token` ou `projectId`)

Exemple :

:::CodeblockTabs
index.js

```javascript
import { start } from '@fasstech/oip-starter-utils/app';

// from local storage
(() => {
  localStorage.setItem('ctxToken', 'my-ctx-client-token');
  // or
  localStorage.setItem('fasstProjectId', 'my-fasst-project-id');

  start({
    // ...
    ctx: 'local-storage'
  });
})();

// from session storage
(() => {
  sessionStorage.setItem('ctxToken', 'my-ctx-client-token');
  // or
  sessionStorage.setItem('fasstProjectId', 'my-fasst-project-id');

  start({
    // ...
    ctx: 'session-storage'
  });
})();

// as parameter
(() => {
  start({
    // ...
    ctx: {
      token: 'my-ctx-client-token',
      // or
      projectId: 'my-fasst-project-id'
    }
  });
})();

// default like
// URL: https://my.oav.fasst/?token=my-ctx-client-token
// or
// URL: https://my.oav.fasst/?projectId=my-fasst-project-id
(() => {
  start({
    // ...
    ctx: 'url'
  });
})();
```
:::

### redirectOnError

*Boolean*. Permet d'activer ou de désactiver la redirection vers la page d'erreur relative lors d'une erreur HTTP lors de la navigation sur l'OAV. Activé par défaut.

Redirections gérées :

- erreur **400** => redirection vers `/bad-request`
- erreur **401** => redirection vers `/unauthorized`
- erreur **403** => redirection vers `/forbidden`
- erreur **404** => redirection vers `/not-found`
- erreur **500** => redirection vers `/internal-server-error`

Exemple :

:::CodeblockTabs
index.js

```javascript
import { start } from '@fasstech/oip-starter-utils/app';

// Init client app
(() => {
  startApp({
    // ...
    redirectOnError: false
  });
})();
```
:::

### errorPages

Un objet contenant les pages d'erreurs est attendu en valeur :

```typescript
type ErrorPages = {
  badRequestPage?: () => ReactNode;
  unauthorizedPage?: () => ReactNode;
  forbiddenPage?: () => ReactNode;
  notFoundPage?: () => ReactNode;
  internalServerErrorPage?: () => ReactNode;
};
```

Si `redirectOnError` est activé, le composant relatif sera chargé lors de la redicrection en cas d'erreur lors de la navigation sur l'OAV.

Exemple :

:::CodeblockTabs
index.js

```javascript
import { start } from '@fasstech/oip-starter-utils/app';

// bad request component
const BadRequestPage = () => {
  // some logic here

  return (
    <div>
      <h2>OOPS..</h2>
      <p>Bad request!</p>
    </div>
  );
};

(() => {
  start({
    // ...
    redirectOnError: true,
    errorPages: {
      badRequestPage: BadRequestPage
    },
  });
})();
```
:::

### rootElementId

*String*. Permet de personnaliser l'id de l'élément HTML racine de l'application client. Par défaut l'id de l'élément racine est `fasst-oav-root`

Exemple :

:::CodeblockTabs
index.js

```javascript
import { start } from '@fasstech/oip-starter-utils/app';

// index.html file
<!doctype html>
<html lang="fr">
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- change root id here -->
    <div id="my-custom-root-id"></div>
    <script type="module" src="/app/index.js"></script>
  </body>
</html>

// Init client app
(() => {
  start({
    // ...
    rootElementId: 'my-custom-root-id'
  });
})();
```
:::

### customHandlers

Un objet qui contient les handlers personnalisés est attendu en valeur. Les handlers personnalisés seront injectés dans l'objet `processHandlers` (hook `useProcess`)

Exemple :

:::CodeblockTabs
index.js

```javascript
import { start } from '@fasstech/oip-starter-utils/app';

const myCustomHandler = () => {
  // some logic
};

const myOtherCustomHandler = () => {
  // some logic
};

// Init client app
(() => {
  start({
    customHandlers: { myCustomHandler, myOtherCustomHandler },
    // ...
  });
})();
```
:::

### isBundle

*Boolean*, `false` par défaut. Si défini à `true` l'application client sera démarrée en mode *bundle* et l'objet `context` (hook `useProcess`) du composant d'une vue contiendra la propriété `isBundle` définit à `true`

Exemple :

:::CodeblockTabs
index.js

```javascript
import { start } from '@fasstech/oip-starter-utils/app';

// init
(() => {
  start({
    // ...
    isBundle: true
  });
})();
```
:::

### routerBasename

Type *String*. Permet de définir la propriété `basename` du router interne de l'application client.

Exemple :

:::CodeblockTabs
index.js

```javascript
import { start } from '@fasstech/oip-starter-utils/app';

// init
(() => {
  start({
    // ...
    routerBasename: '/fasst'
  });
})();
```
:::

### clientSyncEnabled

:::BlockQuote
**\[info]** Disponible à partir de la version **4.1.0** de la bibliothèque **@fasstech/oip-starter-utils**.
:::

:::BlockQuote
**\[info]** Pour bénéficier de la synchronisation des connexions clientes, la fonctionnalité doit également être activée côté serveur. [Cf. session.clientSync.enabled](https://doc.fasst.tech/oip/api-server#session)
:::

Type *Boolean*, `false` par défaut.

Permet d'activer la fonctionnalité de la **synchronisation des connexions clientes** côté client. Si activée :

- l'application instancie une connexion *websocket* avec le serveur pour garantir le contrôle d'un projet (identifié par `projectId`) par un seul client à la fois ;
- permet de consommer le hook [useClientSync](https://doc.fasst.tech/oip/api-client#hook-useclientsync) qui notifie en temps réel du changement de statut de la connexion courante.

Exemple :

:::CodeblockTabs
index.js

```javascript
import { start } from '@fasstech/oip-starter-utils/app';

// init
(() => {
  start({
    // ...
    clientSyncEnabled: true
  });
})();
```
:::

# Hook useProcess

Le hook `useProcess` exposé par la lib permet de récupérer à partir d'un composant d'une vue le contexte (*Process*) de l'OAV ainsi que les handlers responsables de la gestion des transitions et des tâches.

Exemple :

:::CodeblockTabs
MyView\.jsx

```javascript
import { useProcess } from '@fasstech/oip-starter-utils/app';

const MyView = () => {
  const { context, processHandlers } = useProcess();

  const onNext = () => {
    processHandlers.onNext();
  };

  return (
    <div>
      <h2>{context.viewId}</h2>

      <button onClick={onNext}>NEXT</button>
    </div>
  );
};

export default MyView;
```
:::

## Handlers de la gestion des transitions

### onNext

Déclenche la transition vers la vue suivante.

Signature de la fonction : `async ({ transitionData, resolvedViewData }) => Promise<void>`

Paramètres :

- `transitionData` *(objet)* optionnel, ces données sont reçues en paramètres de :
  - l'handler relatif pour la résolution de la transition
  - les hooks de transition relatifs *before* et *after*
- `resolvedViewData` *(objet)* optionnel, ces données sont injectées à l'objet `context` field `viewData` (hook `useProcess`) de la vue suivante

Exemple :

:::CodeblockTabs
Demo.jsx

```javascript
import { useProcess } from '@fasstech/oip-starter-utils/app';

const Demo = () => {
  const { processHandlers } = useProcess();

  const onNext = () => {
    processHandlers.onNext({
      transitionData: { isSomething: true },
      resolvedViewData: { someData: 42 },
    });
  };

  return (
    <div>
      <h2>DEMO</h2>

      <button onClick={onNext}>NEXT</button>
    </div>
  );
};

export default Demo;
```
:::

### onPrev

Déclenche la transition vers la vue précédente.

Signature de la fonction : `async ({ transitionData, resolvedViewData }) => Promise<void>`

Paramètres : *cf. onNext*

Exemple :

:::CodeblockTabs
Demo.jsx

```javascript
import { useProcess } from '@fasstech/oip-starter-utils/app';

const Demo = () => {
  const { processHandlers } = useProcess();

  const onPrev = () => {
    processHandlers.onPrev({
      transitionData: { isSomething: true },
      resolvedViewData: { someData: 42 },
    });
  };

  return (
    <div>
      <h2>DEMO</h2>

      <button onClick={onPrev}>PREV</button>
    </div>
  );
};

export default Demo;
```
:::

## Handlers de la gestion des tâches

### onGetTask

Récupère les informations d'une tâche précédemment exécutée.

Signature : \*async (\{ **taskName**: string; **workflowName?**: string }) => \****Promise\<Task|null>***

Paramètres :

- `taskName` le nom de la tâche (requis)
- `workflowName` le nom du workflow de tâches auquel appartient la tâche (optionnel)

Exemple :

:::CodeblockTabs
Demo.jsx

```javascript
import { useProcess } from '@fasstech/oip-starter-utils/app';

const Demo = () => {
  const { processHandlers } = useProcess();

  const someLogic = () => {
    processHandlers.onGetTask({
      taskName: 'magicTask',
    }).then((task) => {
      // logic
    });
  };

  return (
    <div>
      <h2>DEMO</h2>
      ...
    </div>
  );
};

export default Demo;
```
:::

### onRunTask

Déclenche l'exécution d'une tâche.

Signature : \*async (\{ **taskName**: string; **metadata?**: object }) => \****Promise\<void>***

Paramètres :

- `taskName` le nom de la tâche (requis)
- `metadata` les métadonnées de la tâche (optionnel)

Exemple :

:::CodeblockTabs
Demo.jsx

```javascript
import { useProcess } from '@fasstech/oip-starter-utils/app';

const Demo = () => {
  const { processHandlers } = useProcess();

  const onRunTask = () => {
    processHandlers.onRunTask({
      taskName: 'magicTask',
      metadata: { something: 'That\'s all Folks!' }
    });
  };

  return (
    <div>
      <h2>DEMO</h2>

      <button onClick={onRunTask}>RUN TASK</button>
    </div>
  );
};

export default Demo;
```
:::

### onRunTaskWorkflow

Déclenche l'exécution d'un workflow de tâches.

Signature : \*async (\{ **workflowName**: string; **metadata?**: object }) => \****Promise\<void>***

Paramètres :&#x20;

- `workflowName` le nom du workflow de tâches (requis)
- `metadata` les métadonnées (optionnel)

Exemple :

:::CodeblockTabs
Demo.jsx

```javascript
import { useProcess } from '@fasstech/oip-starter-utils/app';

const Demo = () => {
  const { processHandlers } = useProcess();

  const onRunTaskWorkflow = () => {
    processHandlers.onRunTaskWorkflow({
      workflowName: 'magicWorkflow',
      metadata: { something: 'That\'s all Folks!' }
    });
  };

  return (
    <div>
      <h2>DEMO</h2>

      <button onClick={onRunTaskWorkflow}>RUN WORKFLOW</button>
    </div>
  );
};

export default Demo;
```
:::

### onCancelTask

Annule une tâche en cours d'exécution.

Signature : \*async (\{ **taskId**: string }) => \****Promise\<void>***

Paramètres : `taskId` l'id de la tâche (requis)

Exemple :

:::CodeblockTabs
Demo.jsx

```javascript
import { useProcess } from '@fasstech/oip-starter-utils/app';

const Demo = () => {
  const { processHandlers } = useProcess();

  const someLogic = () => {
    processHandlers.onCancelTask({ taskId: 'xxx-xxx-xxx' });
  };

  return (
    <div>
      <h2>DEMO</h2>
      ...
    </div>
  );
};

export default Demo;
```
:::

## Autres handlers

### onLogout

:::BlockQuote
**\[warn]** L'handler `onLogout` garantit uniquement la suppression de la session de navigation actuelle côté server. L'implémentation de toute autre mécanique (comme une redirection) est à la charge du code de l'OAV.
:::

Cet handler permet de détruire la session de navigation actuelle côté server.

Signature de la fonction : `async () => Promise<void>`

Exemple :

:::CodeblockTabs
Demo.jsx

```javascript
import { useProcess } from '@fasstech/oip-starter-utils/app';

const Demo = () => {
  const { processHandlers } = useProcess();
  
  const onLogout = () => {
    // some logic (redirect, etc.)
  
    processHandlers.onLogout();
  };

  return (
    <div>
      <h2>DEMO</h2>

      <button onClick={onLogout}>LOGOUT</button>
    </div>
  );
};

export default Demo;
```
:::

### destroyApp

Quand l'application client est démarrée en « mode bundle » cet handler permet de libérer la mémoire lors d'une transition d'un bundle de vues à un autre.

Signature de la fonction : `() => void`

Exemple :

:::CodeblockTabs
Demo.jsx

```javascript
import { useProcess } from '@fasstech/oip-starter-utils/app';

const Demo = () => {
  const { processHandlers } = useProcess();
  
  const onNext = () => {
    processHandlers.onNext()

    // unmount react app from DOM
    processHandlers.destroyApp()
  };

  return (
    <div>
      <h2>DEMO</h2>

      <button onClick={onNext}>NEXT</button>
    </div>
  );
};

export default Demo;
```
:::

# Composant Router

Le composant `Router` exposé par la lib permet d'initialiser les routes des vues de l'OAV. Ce composant doit être impérativement défini en tant que *children* du composant `App` de l'OAV.&#x20;

## Propriétés

### views

Le tableau de la définition des vues de l'OAV ou d'un bundle est attendu en valeur. Propriété requise.

Exemple :

:::CodeblockTabs
App.jsx

```javascript
import { Router } from '@fasstech/oip-starter-utils/app';
import { views } from './views';

const App = () => {
  // some logic

  return (
    <>
      <SomeProvider>
        {/* Router component must be returned */}
        <Router views={views} />
      </SomeProvider>
    </>
  );
};
```

views.js

```javascript
// ce fichier est normalement généré via une commande au niveau de l'OAV
import Home from './home/client/Home';
import Customer from './customer/client/Customer';
import Company from './company/client/Company';

export default {
  home: { component: Home, pathname: '/' },
  customer: { component: Customer, pathname: '/customer' },
  company: { component: Company, pathname: '/company' }
};
```
:::

### disableQueryStringParams

Si définie à *true*, le paramètre d'URL *projectId* n'est plus affiché au niveau de l'URL de l'OAV. Propriété optionnelle, *false* par défaut.

Exemple :

:::CodeblockTabs
App.jsx

```javascript
import { Router } from '@fasstech/oip-starter-utils/app';

export const App = () => {
  // some logic

  return (
    <>
      <SomeProvider>
        {/* Router component must be returned */}
        <Router views={views} disableQueryStringParams={true} />
      </SomeProvider>
    </>
  );
};
```
:::

### browserNavigationMode

:::BlockQuote
**\[info]** Prop disponible à partir de la version **4.1.0** de la bibliothèque.
:::

Défini la manière dont la navigation via l'interface du navigateur est gérée.&#x20;

Trois modes disponibles :

- `standard` (défaut) - la navigation navigateur ignore le moteur de transition OIP, l'application charge la vue liée à l'entrée cible de l'historique de navigation ;
- `oip` - la navigation navigateur utilise le moteur de transition OIP pour résoudre la vue cible, une nouvelle entrée est ajoutée à la pile de l'historique de navigation lors de chaque événement `popstate` ;
- `disabled` - désactive de manière silencieuse la navigation navigateur.

Exemple :

:::CodeblockTabs
App.jsx

```javascript
import { Router } from '@fasstech/oip-starter-utils/app';

export const App = () => {
  // some logic

  return (
    <>
      <SomeProvider>
        {/* Router component must be returned */}
        <Router views={views} browserNavigationMode="oip" />
      </SomeProvider>
    </>
  );
};
```
:::

# Hook useCommitMutation

:::BlockQuote
**\[info]** Ce hook ne doit pas être utilisé directement par les développeurs d'un OAV.
:::

Hook consommé par les hooks générés (responsables de la gestion des mutations d'une vue).

# Hook useSubscription

Le hook `useSubscription` permet de souscrire à l'état d'une tâche depuis un composant d'une vue de l'OAV.

Paramètres attendus :

- la query `TaskSubscription` ou `TaskWorkflowSubscription` (ou autre)
- les variables relatives à la query : `taskName` ou `workflowName`

Exemple :

:::CodeblockTabs
Demo.jsx

```javascript
import { 
  useProcess, 
  useSubscription, 
  TaskSubscription,
} from '@fasstech/oip-starter-utils/app';

const Demo = () => {
  const { context, processHandlers } = useProcess();

  const { 
    data, // subscription data
    loading, 
    error,
  } = useSubscription(TaskSubscription, { taskName: 'magic' });

  const onNext = () => () => {
    processHandlers.onNext();
  };

  const onRunTask = () => {
    processHandlers.onRunTask({
      taskName: 'magic',
      metadata: { foo: 'bar' }
    });
  };

  return (
    <div>
      <h2>{context.viewId.toUpperCase()}</h2>
      <div>
        <p>Context</p>
        <pre>{JSON.stringify(context, null, 2)}</pre>
      </div>

      <div className="mt-3">
        <button onClick={onRunTask}>RUN TASK</button>
      </div>

      <div className="mt-3">
        <button onClick={onNext()}>NEXT</button>
      </div>
    </div>
  );
};

export default Demo;
```
:::

# Hook useClientSync&#x20;

:::BlockQuote
**\[info]** Disponible à partir de la version **4.1.0** de la bibliothèque **@fasstech/oip-starter-utils**.
:::

:::BlockQuote
**\[info]** Il est nécessaire d'activer la synchronisation des connexions clientes côté client et serveur pour utiliser ce hook.
:::

Implémenter le hook `useClientSync` pour bénéficier de la fonctionnalité de la **synchronisation des connexions clientes**. Le hook permet d'être notifié en temps réel des changements de statut de la connexion cliente courante et d'agir en conséquence (afficher un message, proposer la reprise du contrôle, etc.).&#x20;

Le hook peut être consommer dans n'importe quel composant de l'application.

Valeurs exposées :

- `instanceId` identifiant unique de la connexion courante ;
- `status` statut courant du client, valeurs possibles : `IN_CONTROL | OUT_OF_SYNC | SESSION_EXPIRED` ;
- `message` message associé au dernier événement reçu ;
- `reclaimControl` fonction permettant de demander la reprise du contrôle.

Exemple d'implémentation du hook dans le composant `App.jsx` :

:::CodeblockTabs
App.jsx

```javascript
import { Router, useClientSync } from "@fasstech/oip-starter-utils/app";
import views from "./views.mjs";

export const App = () => {
  const { instanceId, status, message, reclaimControl } = useClientSync();

  console.log(">> instanceId", instanceId);

  const onReclaimControl = () => {
    reclaimControl();
  };

  if (status === "SESSION_EXPIRED") {
    return (
      <>
        <div>Session Expired...</div>
      </>
    );
  }

  if (status === "OUT_OF_SYNC") {
    return (
      <>
        <div>{message}</div>
        <button onClick={onReclaimControl}>[RECLAIM CONTROL]</button>
      </>
    );
  }

  return <Router views={views} />;
};
```
:::

# Hook useBlockBrowserNav

:::BlockQuote
**\[info]** Disponible à partir de la version **4.1.0** de la bibliothèque.
:::

Le hook `useBlockBrowserNav` permet de bloquer la navigation navigateur (Précédent / Suivant) pour une vue spécifique :

- `useBlockBrowserNav()` appelé sans argument dans le composant d'une vue bloque en permanence la navigation navigateur de la vue ;
- `useBlockBrowserNav(state)` appelé avec une valeur d'état de type *boolean* conditionne le blocage de la navigation navigateur de la vue.

:::BlockQuote
**\[warn]** Un seul appel actif de `useBlockBrowserNav` par arbre de vue est supporté. Appeler ce hook une seule fois, dans le composant de vue de plus haut niveau.
:::

Ce hook est efficace en mode `oip` et `standard`. [cf. browserNavigationMode](https://doc.fasst.tech/oip/api-client#browsernavigationmode)

Exemple :

:::CodeblockTabs
MyView\.jsx

```javascript
import { useState } from "react";
import { useProcess, useBlockBrowserNav } from "@fasstech/oip-starter-utils/app";

const MyView = () => {
  const { context, processHandlers } = useProcess();
  const [isDirty, setIsDirty] = useState(false);

  // Block always
  useBlockBrowserNav();

  // OR Block conditionally (e.g. unsaved changes)
  useBlockBrowserNav(isDirty);

  return (
    <div>
      <h1>MY FORM</h1>
      ...
    </div>
  );
};
```
:::
