Protéger une fonctionnalité en 5 minutes

L'objectif : avant que votre code utilise un renseignement personnel à une fin donnée, il demande à Agreely si la personne a autorisé cet usage, et respecte la réponse. Toute l'intégration tient en un seul appel.

1. Installer et s'authentifier

npm install @agreely/sdk      # or: composer require agreely/sdk
export AGREELY_API_KEY=agr_live_xxx

Une clé à portée check est tout ce qu'il vous faut pour protéger des fonctionnalités.

2. Trouver la cellule

Une cellule de consentement est une catégorie de données croisée avec une finalité : Phone number x Billing. Utilisez les libellés exacts, lisibles par un humain, que déclare votre catalogue; le serveur les normalise (rogner, réduire les espaces, mettre en minuscules), de sorte que la casse et l'espacement n'ont pas d'importance. Ne les normalisez jamais vous-même.

agreely catalog --json    # discover your declared (category, purpose) cells

3. Encapsuler l'usage de données

import { Agreely } from "@agreely/sdk";

const agreely = new Agreely({ apiKey: process.env.AGREELY_API_KEY! });

async function chargeCard(customerId: string) {
  if (!(await agreely.check(customerId, "Phone number", "Billing"))) {
    return; // denied: do not use the phone number for billing
  }
  // allowed: proceed
}

check() renvoie un booléen et allow est le seul true. Une cellule révoquée, expirée, effacée ou jamais accordée vaut false.

4. Traiter les raisons quand cela compte

Pour l'expérience utilisateur ou la journalisation, checkDetailed() vous dit pourquoi :

const d = await agreely.checkDetailed(customerId, "Phone number", "Billing");
switch (d.status) {
  case "active":  /* allow */ break;
  case "none":    /* never granted: ask for consent */ break;
  case "revoked": /* withdrawn: stop, maybe re-ask */ break;
  case "expired": /* lapsed: re-ask */ break;
  case "erased":  /* erased: stop, do not re-ask automatically */ break;
}

Un refus est un 200 normal. checkDetailed le renvoie; il ne lève une exception que sur les erreurs d'authentification, de validation, de limite de débit ou de panne.

5. Connaître le mode de défaillance

La vérification fonctionne en refus par défaut. Si Agreely est injoignable, check() renvoie false (refus) et checkDetailed() lève AgreelyUnavailableError. C'est la valeur par défaut sûre : une panne n'accorde jamais l'accès en silence. Si une catégorie précise et à faible risque a réellement besoin de continuer à fonctionner pendant une panne, voir composer avec les pannes pour l'exception d'ouverture en cas de panne délibérée et auditée.

Ensuite