Démarrer avec le SDK TypeScript

Ce guide relie une application TypeScript côté serveur à l’API de décision hébergée System One. Vous allez installer le SDK, configurer une clé d’API de plateforme et un modèle du catalogue, puis évaluer un message de support comme un choix d’équipe, un score d’urgence et une probabilité de double débit. L’API renvoie des décisions ; elle ne route pas un ticket, n’émet pas de remboursement et n’exécute aucun outil.

Prêt pour les questions

Q: Comment démarrer avec le SDK TypeScript System One ?
A: Install the System One TypeScript SDK, set your API key, choose a model such as Clef Flash or Jev, and call Choice, Score, or Noul for a typed decision from the hosted System One API.

Q: Credits?
A: Les nouveaux comptes reçoivent 100 crédits à l’inscription ; les crédits n’expirent pas.

Prêt pour les questions

Comment démarrer avec le SDK TypeScript System One ? Installez le SDK TypeScript System One, définissez votre clé d’API, choisissez un modèle comme Clef Flash ou Jev, puis appelez Choice, Score ou Noul pour obtenir une décision typée depuis l’API System One hébergée.

Les crédits ? Les nouveaux comptes reçoivent 100 crédits à l’inscription ; les crédits n’expirent pas.

L’installation du SDK et la tarification de l’API sont séparées

Le SDK TypeScript open source fournit le client, les adaptateurs et les résultats typés. L’installer ne crée pas de compte hébergé et n’achète pas d’inférence. Les appels à l’API de décision hébergée utilisent les crédits de votre compte System One au prix courant du modèle sélectionné. Vérifiez ce prix et la taille de la requête avant d’envoyer une décision : l’installation du SDK n’est pas un plan tarifaire.

Ce guide utilise une clé d’API de plateforme System One, pas une clé de fournisseur direct. Pour connecter le SDK directement à un autre service, suivez plutôt Installation du SDK et adaptateurs de service direct : ces intégrations utilisent leurs propres identifiants et leur propre facturation. Ne placez pas une clé de fournisseur dans SYSTEM_ONE_API_KEY.

1. Créer une clé d’API et choisir un modèle

Connectez-vous à System One, terminez la vérification de l’adresse e-mail et ouvrez API keys dans votre console. Créez une clé nommée et copiez le secret lorsqu’il s’affiche. La liste n’affiche qu’un préfixe ; le secret complet ne peut pas être récupéré plus tard. Conservez-le sur votre serveur, hors des prompts, du code navigateur, des journaux et du contrôle de version.

Les nouveaux comptes reçoivent 100 crédits gratuits à l’inscription. Vérifiez le solde dans la console. Créer d’autres clés n’ajoute pas de crédits de bienvenue.

Choisissez un modèle à partir du répertoire actuel ou du sélecteur du Playground. Cliquez sur Model information à côté du sélecteur pour consulter le tarif et les limites du modèle sélectionné. Copiez son name exact et vérifiez qu’il accepte Choice, Score et Noul. Vous pouvez aussi récupérer le répertoire avec GET /v1/models public. YOUR_MODEL_ID ci-dessous est un espace réservé, pas un alias pris en charge.

2. Installer et configurer

Le SDK prend en charge Node.js 20+. Les commandes ci-dessous utilisent Node.js 22.18+, qui exécute directement ces fichiers TypeScript .mts.

npm install @system-one-ai/core@0.8.0 @system-one-ai/adapter-system-one@0.7.0 @system-one-ai/transport-fetch@0.8.0

Créez un fichier .env local exclu du contrôle de version :

SYSTEM_ONE_API_KEY=replace-with-your-platform-key
SYSTEM_ONE_BASE_URL=https://system-one.dev/v1
SYSTEM_ONE_MODEL=YOUR_MODEL_ID

L’API utilise l’origine du site principal, pas l’hôte de documentation. Remplacez YOUR_MODEL_ID par le name exact de l’entrée de catalogue choisie.

3. Envoyer une première décision

L’exemple fournit un message de support partagé comme state et trois questions nommées. choice() déclare les équipes autorisées, score() déclare une échelle d’urgence ordonnée et booleanQuestion() demande une probabilité plutôt qu’une action vrai/faux. Voir Primitives de décision Choice, Score et Noul pour concevoir ces questions.

Enregistrez ce code sous decision.mts :

import { createSystemOne, choice, score, booleanQuestion } from '@system-one-ai/core';
import { systemOneAdapter } from '@system-one-ai/adapter-system-one';
import { createFetchTransport } from '@system-one-ai/transport-fetch';

const apiKey = process.env.SYSTEM_ONE_API_KEY;
const baseURL = process.env.SYSTEM_ONE_BASE_URL;
const model = process.env.SYSTEM_ONE_MODEL;
if (!apiKey || !baseURL || !model || model === 'YOUR_MODEL_ID') {
  throw new Error('Set the API key, base URL, and catalog model.');
}

const client = createSystemOne({
  apiKey,
  baseURL,
  model,
  adapter: systemOneAdapter,
  transport: createFetchTransport(),
  timeoutMs: 30_000,
  maxRetries: 0,
});

const operation = {
  idempotencyKey: crypto.randomUUID(),
  request: {
    model,
    state: { message: 'I was charged twice for the same order.' },
    questions: {
      team: choice('Choose the team that should review this request.', {
        billing: 'Payments, invoices, and refunds',
        support: 'Technical troubleshooting',
        review: 'More context is needed',
      }),
      urgency: score('Rate urgency using this ordered rubric.', [
        'Can wait for normal review',
        'Needs a timely response',
        'Needs immediate human attention',
      ]),
      duplicate: booleanQuestion('Does the message report a duplicate charge?', {
        true: 'The same order was charged more than once',
        false: 'No duplicate charge is reported',
      }),
    },
  },
};

const result = await client.evaluate(operation.request, {
  headers: { 'Idempotency-Key': operation.idempotencyKey },
});

console.log({
  team: result.answers.team.choice,
  distribution: result.answers.team.probabilities,
  urgency: result.answers.urgency.score,
  duplicateProbability: result.answers.duplicate.probability,
  inputTokens: result.usage.inputTokens,
  model: result.model,
  requestId: result.response.requestId,
});

node --env-file=.env decision.mts

Chaque exécution de ce script démarre une nouvelle opération facturable, même si l’entrée est inchangée. L’opération n’existe qu’en mémoire ; relancer le script n’est pas une reprise après un délai dépassé ou un crash.

4. Comprendre le résultat

• team.choice est l’un des noms d’option déclarés, avec son type littéral préservé.
• urgency.score peut être fractionnaire entre 0 et 2 pour cette échelle à trois niveaux.
• duplicate.probability est P(true) entre 0 et 1, pas un booléen JavaScript.
• Les statistiques optionnelles et les comptes de jetons restent inconnus lorsqu’ils sont absents. Ne les remplacez pas par zéro.

Core normalise le résultat entre les adaptateurs. Sur le réseau, booleanQuestion() devient type: 'noul', avec un champ de réponse nommé noul ; core expose type: 'boolean' et probability. Ce résultat typé n’est pas le corps HTTP exact et n’expose pas tous les en-têtes de réponse. Consultez result.model à côté des réponses typées et conservez l’identifiant de requête pour le diagnostic, sans journaliser les identifiants ni l’état sensible.

Modèles

N’excluez pas model si vous souhaitez que l’API hébergée utilise son défaut de déploiement. Pour choisir un autre modèle, copiez un name exact depuis GET /v1/models. Les alias peuvent changer ; le nom de modèle renvoyé est distinct de l’identifiant demandé. Voir Choisir un modèle.

Reprendre une requête interrompue

Pour une reprise dans le même processus, réutilisez le même operation.idempotencyKey et la même operation.request. Après un crash ou un redémarrage, votre application doit enregistrer durablement l’opération complète dans son enregistrement de tâche avant le premier envoi, puis charger cet enregistrement au lieu de créer un nouvel UUID. Une interruption ne prouve pas qu’aucun débit n’a eu lieu. Voir Idempotence et reprises.

Étapes suivantes

• Documentation du SDK
• Extraire des champs avec Clairic
• Choisir un modèle
• Référence API