@squeletteapp/sdk

Client TypeScript de l'API Squelette. Sans dependance, bati sur fetch : il tourne dans un navigateur, dans Node, et dans un worker Cloudflare.

pnpm add @squeletteapp/sdk

Deux types de cle

| Prefixe | Ou | Acteur | | --------- | ------------- | --------------------------------------------------- | | sq_sk_ | serveur | un workspace_contributor_id pose directement | | sq_pk_ | navigateur | un jeton rendu par identify, borne dans le temps |

Une cle secrete ne doit jamais partir dans le navigateur : elle vaut acteur arbitraire dans le workspace.

Cote serveur

import { createClient } from '@squeletteapp/sdk';

const squelette = createClient({ apiKey: process.env.SQUELETTE_API_KEY });

// Sans acteur, les RLS ne montrent que ce qui est public.
const { data } = await squelette.tickets.list({ type: 'changelog', state: 'published' });

// Avec acteur, l'API agit sous son identite.
const asUser = squelette.withActor(contributorId);
await asUser.tickets.vote(42).set(1);

withActor rend une nouvelle instance : un serveur traite plusieurs requetes a la fois, et muter l'acteur en place ferait agir une requete sous l'identite d'une autre.

Cote navigateur

const squelette = createClient({ apiKey: 'sq_pk_...' });
const identity = await squelette.identify({ external_user_id: 'u_42', email: '[email protected]' });
const asUser = squelette.withActor(identity.actor_token);

Pour React, @squeletteapp/react fait cette partie, y compris le cookie et le cache.

Le texte des tickets

La description d'un ticket vit dans son commentaire racine. tickets.get la rend toujours, la liste seulement sur demande :

const page = await squelette.tickets.list({ type: 'changelog', include: 'content' });
page.data[0]?.content; // absent sans `include`, `null` s'il n'y a pas de texte

Erreurs

Toute methode leve une SqueletteError portant status, code et message.

import { isSqueletteError } from '@squeletteapp/sdk';

try {
  await squelette.tickets.get(1);
} catch (error) {
  if (isSqueletteError(error) && error.code === 'not_found') return null;
  throw error;
}

Types generes

src/api.ts est produit depuis le document OpenAPI par openapi-typescript, et src/types.ts n'en expose que les noms publics. Un champ qui change dans l'API casse la compilation ici plutot que de deriver en silence.

pnpm gen:openapi   # rafraichit openapi.json depuis api.squelette.app, puis regenere
pnpm gen:types     # regenere depuis le openapi.json commite
pnpm gen:check     # echoue si src/api.ts ne correspond plus (appele par check-types)

Le document est commite dans le paquet, donc le build est hors ligne et deterministe. Le rafraichir est un geste explicite.

Pour une route que le SDK n'expose pas encore, les types generes sont exportes :

import type { paths } from '@squeletteapp/sdk';

type Page = paths['/v1/tickets']['get']['responses'][200]['content']['application/json'];

Surface

• me(), identify()
• workspace et workspace.settings
• tickets, et par ticket : comments, metadata, categories, contributors, vote
• boards, et par board : categories, contributors
• contributors et leurs badges, members, badges, webhooks
• request(method, path, options) pour une route que le SDK n'expose pas encore