Référence

SDK npm

bash

npm install @recalled/sdk

Client

import { Recalled } from "@recalled/sdk";

const client = new Recalled({
  apiKey: process.env.RECALLED_API_KEY!,
  // baseUrl par défaut : https://api.recalled.dev/v1
});

Events

// create (strict, throw en cas d'échec)
await client.events.create({
  action: "user.password.changed",
  actor: { id: "user_1" },
});

// list
const { data, nextCursor } = await client.events.list({
  limit: 50,
  organization: "org_abc",
});

// search
const { data } = await client.events.search({ q: "invoice" });

// get one
const event = await client.events.retrieve("evt_xxx");

`emit()` résilient (recommandé)

emit() retourne immédiatement et livre l'event en arrière-plan. Si l'API est injoignable, le SDK garde l'event dans une queue en mémoire et retente automatiquement avec backoff exponentiel pendant 24 heures maximum. Ton request path ne voit jamais d'exception en cas de panne passagère, ce qui est ce que tu veux pour des logs d'audit dans 99 % des cas.

client.events.emit({
  action: "invoice.paid",
  actor: { id: user.id, email: user.email },
  organization: user.organizationId,
  metadata: { amount, currency },
});
// retourne immédiatement, pas besoin d'await

Les résultats de livraison sont exposés via des callbacks passés au constructeur Recalled :

const client = new Recalled({
  apiKey: process.env.RECALLED_API_KEY!,
  resilience: {
    onDelivered: (input, event) => {},
    onError:     (err, input) => {},
    onDrop:      (input, reason, err) => {
      // reason : "ttl_expired" | "fatal_error" | "queue_full"
    },
  },
});

Flush avant de sortir

Les process courts (CLI, cron, Lambda) doivent await client.flush() avant de sortir, sinon les events en attente sont perdus à la fermeture.

client.events.emit({ action: "job.completed" });
await client.flush(); // attend jusqu'à 30s que la queue se vide

Options de résilience

Option	Défaut	Description
`maxQueueSize`	`5000`	Events stockés en mémoire
`maxAgeMs`	`24h`	TTL avant de drop un event
`minBackoffMs`	`1000`	Premier délai de retry
`maxBackoffMs`	`10min`	Cap du backoff

Passe resilience: false pour désactiver le buffering (emit() devient un fire-and-forget brut).

`create` vs `emit`

	`create()`	`emit()`
Retour	`Promise<Event>`	`void`
Throw en cas d'échec	oui	non
Buffer en cas de panne	non	oui
Bloque le request path	oui	non
À utiliser quand	l'échec doit remonter	l'échec doit être invisible

Embed

const { token } = await client.embed.createToken({
  organization: "org_abc",
  ttlSeconds: 900,
});

Actors (RGPD)

await client.actors.delete({ id: "user_123" });

Exports

// Retourne le body brut de l'export (string CSV ou JSON selon le format).
const body = await client.exports.fetch({
  format: "csv",
  organization: "org_abc",
});

Types

Chaque méthode est entièrement typée et le package livre ses propres .d.ts. Importe les types directement quand tu en as besoin :

import type { Event, CreateEventInput } from "@recalled/sdk";