SDK

Le SDK Abby Node.js, Bun & Deno est la librairie officielle de l’API Abby. Il évite d’écrire vos requêtes HTTP à la main. Il ajoute du typage TypeScript et de la validation runtime.

• NPM : https://www.npmjs.com/package/@abby-inc/node

• GitHub : https://github.com/abby-inc/abby-node

Quand l’utiliser

Utilisez le SDK si vous développez :

• Un backend Node.js.

• Un script Bun.

• Une app Deno.

Pour du no-code, utilisez Make.

Prérequis

• Node.js >= 22.13, Bun >= 1, ou Deno >= 2.

• Une clé API Abby.

Depuis la version 2.0.0 du SDK, Node.js 18 et 20 ne sont plus supportés.

La création et la gestion de la clé est décrite dans Authentification.

Gardez la clé API côté serveur. Ne l’exposez jamais au navigateur. Ne la commitez jamais.

Installation

npm

npm install @abby-inc/node

yarn

yarn add @abby-inc/node

pnpm

pnpm add @abby-inc/node

bun

bun add @abby-inc/node

deno

import Abby from 'npm:@abby-inc/node';

Démarrage rapide

Initialisation

import Abby from '@abby-inc/node';

const abby = new Abby('your_api_key');

Exemple simple

import Abby from '@abby-inc/node';

const abby = new Abby('your_api_key');

async function main() {
  const { data: me } = await abby.company.getMe();
  console.log(`Welcome back, ${me.user.firstname}!`);

  const { data: contacts } = await abby.contact.retrieveContacts({
    query: { limit: 10 },
  });

  console.log(`Found ${contacts.docs.length} contacts.`);
}

main().catch(console.error);

Services

Le SDK expose des services par domaine métier. La liste ci-dessous suit le README.

• abby.company : infos société et préférences.

• abby.invoice : factures.

• abby.estimate : devis.

• abby.contact : contacts (clients).

• abby.organization : organisations.

• abby.billing : utilitaires de facturation (PDF, emails).

• abby.opportunity : CRM et opportunités.

• abby.asset : immobilisations.

• abby.advance : acomptes.

• abby.customerPortal : paiements du portail client et thèmes de facturation.

Pour la doc API dans GitBook :

• Clients

• Factures

• Livre des recettes

• Livre des achats

Configuration

Vous pouvez passer des options au constructeur.

import Abby from '@abby-inc/node';

const abby = new Abby('your_api_key', {
  baseUrl: 'https://api.app-abby.com',
  timeout: 30000,
  headers: {
    'X-Custom-Header': 'value',
  },
});

Options :

• baseUrl (défaut https://api.app-abby.com) : base URL de l’API.

• timeout (défaut 30000) : timeout en millisecondes.

• headers : headers ajoutés à toutes les requêtes.

• fetch (défaut globalThis.fetch) : fetch custom (proxy, logs, tests).

Fetch custom et proxy

Le SDK accepte un fetch custom. Ça sert pour un proxy, des logs, ou des tests.

Proxy avec undici :

import Abby from '@abby-inc/node';
import { fetch as undiciFetch, ProxyAgent } from 'undici';

const proxyAgent = new ProxyAgent('http://proxy.example.com:8080');

const abby = new Abby('your_api_key', {
  fetch: (url, init) =>
    undiciFetch(url, {
      ...init,
      dispatcher: proxyAgent,
    }),
});

Logging simple :

import Abby from '@abby-inc/node';

const abby = new Abby('your_api_key', {
  fetch: async (url, init) => {
    console.log(`[Abby SDK] ${init?.method ?? 'GET'} ${url}`);
    const start = Date.now();

    const response = await globalThis.fetch(url, init);

    console.log(`[Abby SDK] ${response.status} in ${Date.now() - start}ms`);
    return response;
  },
});

Gestion des erreurs

Le SDK lève des erreurs en cas de réponse 4xx/5xx. Vous pouvez router par code HTTP.

try {
  await abby.invoice.getInvoice({
    path: { invoiceId: 'inv_invalid' },
  });
} catch (error) {
  if (error.status === 404) {
    console.error('Invoice not found');
  } else if (error.status === 401) {
    console.error('Invalid API key');
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Pour les détails, voir Erreurs.

Événements (listeners)

Vous pouvez écouter globalement erreurs et réponses. C’est utile pour du logging centralisé.

Écouter toutes les erreurs :

import Abby from '@abby-inc/node';

const abby = new Abby('your_api_key');

abby.on('error', (error) => {
  console.error(`API Error: ${error.status} ${error.statusText}`);
  console.error(`URL: ${error.method} ${error.url}`);
  console.error(`Message: ${error.message}`);
  console.error(`Duration: ${error.duration}ms`);
});

Écouter toutes les réponses :

abby.on('response', (response) => {
  console.log(`${response.method} ${response.url} - ${response.status} (${response.duration}ms)`);
});

Supprimer un listener :

const errorHandler = (error) => console.error(error);

abby.on('error', errorHandler);
abby.off('error', errorHandler);

Interceptors

Les interceptors hookent le cycle request/response.

const client = abby.getClient();

client.interceptors.request.use((request) => {
  request.headers.set('X-Request-ID', crypto.randomUUID());
  return request;
});

client.interceptors.response.use((response) => {
  console.log(`API Response: ${response.status}`);
  return response;
});

Requêtes “raw”

Utilisez le client HTTP si un endpoint manque. La clé API et les headers SDK sont ajoutés automatiquement.

import Abby from '@abby-inc/node';

const abby = new Abby('your_api_key');
const client = abby.getClient();

const { data } = await client.get({
  url: '/v2/some/endpoint',
});

const { data: result } = await client.post({
  url: '/v2/some/endpoint',
  body: { field: 'value' },
});

Validation (Zod)

Le SDK valide les requêtes avec Zod. Une ZodError est levée si le payload ne matche pas le schéma.

Les réponses ne sont pas validées. Les schémas de réponse sont générés et exportés, mais le SDK ne les exécute pas : un écart entre l'API et la spec transformerait sinon un appel réussi en erreur. Le typage des réponses reste garanti à la compilation uniquement. Parsez avec les schémas z*Dto exportés si vous voulez une garantie à l'exécution.

import Abby from '@abby-inc/node';
import { ZodError } from 'zod';

const abby = new Abby('your_api_key');

try {
  await abby.contact.createContact({ body: {} });
} catch (error) {
  if (error instanceof ZodError) {
    console.error('Validation failed:', error.errors);
  }
}

Vous pouvez aussi utiliser les schémas exportés :

import { z } from 'zod';
import { zCreateContactDto, zReadContactDto } from '@abby-inc/node';

type CreateContactInput = z.infer<typeof zCreateContactDto>;
type Contact = z.infer<typeof zReadContactDto>;

const input = {
  firstname: 'John',
  lastname: 'Doe',
  email: '[e-mail]',
};

zCreateContactDto.parse(input);

TypeScript

Le SDK est écrit en TypeScript. Il expose des types pour les DTOs.

import Abby, { ReadMeDto } from '@abby-inc/node';

const abby = new Abby('your_api_key');

async function getCompanyData() {
  const { data }: { data: ReadMeDto } = await abby.company.getMe();
  return data;
}