TypeScript

L'origine des types, les types disponibles et les deux qui doivent être affinés.

@wajub/js fournit ses propres définitions. Aucun package @types/ à installer ni aucune configuration à effectuer. Chaque enveloppe de framework réexporte les mêmes types. Il suffit donc d'en installer une.

npm install @wajub/js

Le package déclare trois points d'entrée, chacun avec ses propres définitions.

Import	Définitions	Effet de bord
`@wajub/js`	`dist/index.d.ts`	Charge l'environnement d'exécution lors de l'importation
`@wajub/js/pure`	`dist/pure.d.ts`	Aucun avant l'appel de `loadWajub()`
`https://js.wajub.com`	Aucune, uniquement des variables globales	Tout l'environnement d'exécution

Tous les éléments utiles à importer

Configuration et instances

import type {
  EmbeddedConfig,
  PopupConfig,
  CheckoutInstance,
  PopupInstance,
  ComponentConfig,
  ComponentInstance,
  ComponentsFactory,
  ComponentType,
  ConfirmPaymentOptions,
} from '@wajub/js';

Styles, payloads et erreurs

import type {
  AppearanceConfig,
  AppearanceVariables,
  AppearanceRules,
  AppearanceThemePreset,
  AppearanceColorScheme,
  AppearanceLabels,
  CheckoutLayout,
  CheckoutState,
  EmbedBreakdown,
  SessionPreview,
  ComponentChangeEvent,
  ComponentAddressValue,
  AddressValue,
  AddressMode,
  PhoneFieldMode,
  WajubError,
  WajubErrorType,
} from '@wajub/js';

Environnement d'exécution et client

import type {
  WajubRuntime,
  WajubSDK,
  WajubClient,
  WajubFactory,
  WajubInitOptions,
  LoadWajubOptions,
  CreatePaymentParams,
  CreatePaymentResult,
  InitCheckoutOptions,
  InitCheckoutResult,
} from '@wajub/js';

Deux autres types assurent la compatibilité : EmbedTheme, l'ancienne structure de thème, et WajubErrorShape, l'objet simple derrière une WajubError.

Deux cas où l'affinage des types est important

Les helpers peuvent renvoyer null. Tout élément importé depuis @wajub/js renvoie null en l'absence de window. Le rendu serveur reste ainsi sûr. TypeScript vous oblige à traiter ce cas.

Aucune erreur sur le serveur

import { loadWajub } from '@wajub/js/pure';

const runtime = await loadWajub();
if (!runtime) return;

const checkout = runtime.wajub.mount('#checkout', { sessionId });

Une fois l'environnement d'exécution obtenu, ses méthodes sont synchrones et ne renvoient jamais null. Cette vérification est donc la seule nécessaire.

Les callbacks d'erreur ne sont pas typés comme WajubError. Ils reçoivent WajubError | Record<string, unknown>, car l'iframe peut aussi envoyer une erreur sous forme de payload brut. Affinez le type avant de lire code.

Affiner le type d'une erreur

import { WajubError } from '@wajub/js';

await mount('#checkout', {
  sessionId,
  onError: (error) => {
    if (error instanceof WajubError) {
      report(error.code, error.retryable);
      return;
    }
    report('unknown_error', false);
  },
});

WajubError est exporté comme valeur et pas seulement comme type. instanceof fonctionne donc. Tous les autres éléments de cette page sont importés uniquement comme types.

Rendu serveur

Les trois packages de framework vérifient déjà la présence du navigateur grâce à WajubProvider. Utilisez le code ci-dessous uniquement si vous intégrez vous-même @wajub/js.

React sans l'enveloppe

'use client';

import { useEffect, useRef } from 'react';
import { loadWajub } from '@wajub/js/pure';
import type { CheckoutInstance } from '@wajub/js';

export function Checkout({ sessionId }: { sessionId: string }) {
  const host = useRef<HTMLDivElement>(null);
  const instance = useRef<CheckoutInstance | null>(null);

  useEffect(() => {
    loadWajub().then((runtime) => {
      if (!runtime || !host.current) return;
      instance.current = runtime.wajub.mount(host.current, { sessionId });
    });

    return () => instance.current?.destroy();
  }, [sessionId]);

  return <div ref={host} />;
}

L'importation depuis /pure évite les effets de bord. Le bundler n'ajoute donc pas de requête au CDN dans votre build serveur.

Typer les variables globales du CDN

Avec la balise script et sans package npm, wajub, Wajub et WajubError sont disponibles sur window. Le package les déclare globalement. Son installation comme dépendance de développement permet donc de typer un projet sans jamais l'inclure dans le bundle.

Déjà déclarés pour vous

declare global {
  interface Window {
    wajub: WajubSDK;
    Wajub: WajubFactory;
    WajubError: typeof WajubError;
  }
}

Un chemin de référence distant ne fonctionne pas

https://js.wajub.com/wajub-checkout.d.ts est disponible, mais TypeScript résout uniquement /// <reference path> sur le système de fichiers local. Téléchargez le fichier à côté de votre code et référencez ce chemin, ou ajoutez @wajub/js comme dépendance de développement pour que le compilateur le trouve seul. La seconde solution demande moins de maintenance.

Types des frameworks

React et Vue exportent leurs propres types de props en plus des éléments ci-dessus.

Package	Ajouts
`@wajub/react`	`WajubProviderProps`, `CheckoutEmbedProps`, `ComponentEmbedProps`, `WajubContextValue`
`@wajub/vue`	Les quatre mêmes, avec `WAJUB_INJECTION_KEY`
`@wajub/svelte`	Uniquement `WajubContextValue`

Les composants Svelte ne sont pas typés

Chaque composant de @wajub/svelte est déclaré comme un simple SvelteComponent et le package n'exporte aucun type de prop. Votre éditeur ne complétera pas les props et svelte-check ne détectera pas une faute de frappe. Les détails et la solution de contournement figurent sur la page Svelte.

Pages associées

Tous les éléments utiles à importer

Deux cas où l'affinage des types est important

Rendu serveur

Typer les variables globales du CDN

Types des frameworks

Que pensez-vous de ce contenu ?