TypeScript

@wajub/js fournit ses propres définitions. Aucun package @types/ à installer ni aucune configuration à effectuer. À partir de la version 1.6.0, chaque enveloppe de framework réexporte les mêmes types. Il suffit donc d'en installer une : import type { PaymentSuccess } from '@wajub/react' fonctionne.

npm install @wajub/js

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

Tous les éléments utiles à importer

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

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

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.

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.

import { loadWajub, mount } from '@wajub/js';

const runtime = await loadWajub();

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

WajubError est déclaré dans les types, mais le module ne l'exporte pas à l'exécution : un import { WajubError } passe la vérification des types, puis vaut undefined ou fait échouer le bundle. Prenez la classe dans ce que renvoie loadWajub(), comme ci-dessus. 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.

'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, à condition que TypeScript charge ces déclarations : un projet qui n'importe jamais le package doit le nommer, avec /// <reference types="@wajub/js" /> en tête d'un fichier ou "types": ["@wajub/js"] dans compilerOptions.

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

Types des frameworks

Chaque enveloppe réexporte tous les éléments ci-dessus, et React et Vue y ajoutent leurs propres types de props.