@hearthnpm/public-api-client

Client TypeScript officiel pour Hearth Public API v1.

Les tokens happ_... sont des secrets serveur-à-serveur. Ne les placez jamais dans du JavaScript livré à un navigateur public. Pour une application Web, mobile ou desktop agissant au nom d'un utilisateur, utilisez OAuth Authorization Code + PKCE S256 (M54).

Installation

npm install @hearthnpm/public-api-client

Node.js 18 ou plus récent est requis (le SDK utilise le fetch natif).

Exemple

import { HearthPublicApiClient } from "@hearthnpm/public-api-client";

const hearth = new HearthPublicApiClient({
  baseUrl: "https://hearth.syscorp-technologies.com",
  token: process.env.HEARTH_TOKEN!,
});

const me = await hearth.me();
const { items: servers } = await hearth.servers();

console.log(me.application.name, servers);

Envoyer un message

await hearth.createMessage(
  "CHANNEL_ID",
  { content: "Bonjour depuis mon bot." },
  { idempotencyKey: crypto.randomUUID() },
);

Authentification et scopes

Créez une application dans Hearth, installez-la sur le serveur concerné, accordez uniquement les scopes nécessaires puis créez un token API. Les scopes de l'API v1 incluent notamment :

• servers.read
• channels.read
• messages.read
• messages.write
• members.read
• roles.read
• events.read
• webhooks.read
• webhooks.write

Le token ne contourne jamais les permissions Hearth du bot installé sur le serveur.

Gestion des erreurs

import {
  HearthPublicApiClient,
  HearthPublicApiError,
} from "@hearthnpm/public-api-client";

try {
  await hearth.server("SERVER_ID");
} catch (error) {
  if (error instanceof HearthPublicApiError) {
    console.error(error.status, error.code, error.requestId);
  }
}

Versionnage

Le SDK suit son propre SemVer et est indépendant de la version de l'application Hearth :

• 1.0.x : corrections du SDK ;
• 1.x.0 : nouvelles méthodes compatibles avec Public API v1 ;
• 2.0.0 : rupture de compatibilité du SDK.

L'API HTTP reste versionnée séparément sous /api/v1.

Publication (mainteneurs)

Depuis la racine du dépôt :

npm run sdk:build
npm run sdk:pack
npm run sdk:publish

Ou directement :

cd packages/public-api-client
npm run build
npm pack --dry-run
npm publish --access public

OAuth 2.0 / PKCE

Le SDK 1.1.0 expose createHearthOAuthPkce, hearthOAuthAuthorizationUrl, exchangeHearthOAuthCode, refreshHearthOAuthToken et revokeHearthOAuthToken. Les access tokens hoat_... peuvent être passés à HearthPublicApiClient exactement comme un token applicatif.