Accedi

Presentiamo gli SDK di SupDesk

SupDesk Team

Ogni prodotto serio finisce per scrivere uno strato di integrazione: uno script che legge da una casella di posta, un job cron che sincronizza una bacheca, un endpoint che invia feedback dalla tua interfaccia utente. La console SupDesk è fantastica quando sei alla tastiera. Nel momento in cui vuoi automatizzare, hai bisogno di un'API, e un'API è valida tanto quanto i client di cui disponi per comunicare con essa.

Oggi ne rilasciamo quattro.

Scopri gli SDK

  • JavaScript / TypeScript — supdesk su npm. Funziona non modificato in Node 18+, Deno, Bun e Cloudflare Workers, senza alcuna dipendenza a runtime.
  • Python — supdesk su PyPI. Un client sincrono SupDesk e un client asincrono AsyncSupDesk che condividono un unico core httpx.
  • Go — github.com/rabinapps/supdesk-go. Solo libreria standard, quindi si compila ovunque sia eseguibile Go 1.23+, compresi i Cloudflare Workers tramite GOOS=wasip1.
  • Dart — supdesk su pub.dev. Basato su dio, quindi intercettori, CancelToken e adattatori proxy funzionano esattamente come ti aspetti.

Installazione

npm install supdesk
pip install supdesk
go get github.com/rabinapps/supdesk-go
dependencies:
  supdesk: ^0.1.0

Un'API, quattro linguaggi

Gli SDK non sono quattro wrapper separati: sono la stessa API con le stesse semantiche in ogni linguaggio. Se sai leggere gli invii in uno, sai leggerli in tutti e quattro.

Paginazione automatica. list() restituisce una pagina che è anche un iterabile asincrono: percorri ogni pagina con un for await, oppure estrai solo la prima pagina quando è tutto ciò di cui hai bisogno.

Risorse tipizzate. Invii, feedback, voci di changelog, messaggi, iscrizioni alla lista d'attesa, programmi beta e tester, articoli e categorie del centro assistenza: ciascuno con i metodi attesi e parametri tipizzati, in modo che gli errori di battitura falliscano in fase di compilazione anziché in produzione.

Errori tipizzati. Ogni errore eredita da una singola classe base: SupDeskError in JS e Python, APIError in Go, SupDeskException in Dart — così un singolo catch gestisce tutto, mentre instanceof o errors.As restringono comunque al caso specifico.

Webhook. constructEventFromRequest, construct_event_from_headers, ConstructEvent e constructEventFromHeaders verificano la firma di SupDesk in tempo costante, così puoi fidarti delle azioni eseguite dal tuo ricevitore.

Resilienza integrata. Ogni client riprova con backoff esponenziale e jitter, rispetta Retry-After e non riprova mai una richiesta POST a consumo che potrebbe essere già stata accettata: una rete instabile non può duplicare il ticket di un utente.

Progettato per il lato server

Le chiavi API di SupDesk autenticano l'intero progetto, quindi gli SDK rifiutano di eseguirsi in un browser: i costruttori JS e Dart lanciano un'eccezione se rilevano un DOM o una build client, e i README spiegano chiaramente il motivo. Conserva la chiave in una variabile d'ambiente lato server, dietro un endpoint controllato da te.

Altre due cose utili da sapere: le letture funzionano su tutti i piani, mentre le scritture (POST/PATCH/DELETE) richiedono un piano a pagamento; e le chiavi hanno ambito di progetto, quindi assegna a ciascun ambiente la propria chiave in modo da poterne revocare una senza toccare le altre.

Dove si inserisce SupDesk

Gli SDK rappresentano la metà backend della guida all'integrazione SaaS di SupDesk: supporto multi-tenant, accesso API e webhook per prodotti che desiderano integrare il supporto nei propri sistemi. Il riferimento completo è disponibile nella documentazione dell'API.

Per iniziare

Prendi una chiave API da Impostazioni dello spazio di lavoro → Chiavi API, installa il client per il tuo stack ed esegui la guida rapida in questa pagina. Poi clona il repository e leggi il README.

Inizia su supdesk.app

SDK lato server per l'integrazione backend

Esempi di codice live caricati dal repository GitHub di ogni SDK.

RabinApps/supdesk-nodeJavaScript / TypeScript
import { SupDesk } from "supdesk";

const supdesk = new SupDesk({ apiKey: process.env.SUPDESK_API_KEY! });

// Auto-pages: iterating walks every page for you.
for await (const submission of await supdesk.submissions.list({
  status: "open",
})) {
  console.log(submission.title);
}

await supdesk.submissions.create({
  type: "bug",
  title: "Export button does nothing",
  email: "user@example.com",
  body: "Clicking Export on the reports page has no effect.",
});
RabinApps/supdesk-pythonPython
from supdesk import SupDesk

supdesk = SupDesk()  # api_key=... or $SUPDESK_API_KEY

# Auto-pages: iterating walks every page for you.
for submission in supdesk.submissions.list(status="open"):
    print(submission.title)

supdesk.submissions.create(
    type="bug",
    title="Export button does nothing",
    email="user@example.com",
    body="Clicking Export on the reports page has no effect.",
)
RabinApps/supdesk-goGo
import "github.com/rabinapps/supdesk-go/supdesk"

client, err := supdesk.New(os.Getenv("SUPDESK_API_KEY"))
if err != nil {
    log.Fatal(err)
}

page, err := client.Submissions.List(ctx, supdesk.SubmissionsListParams{
    Status: ptr("open"),
})
if err != nil {
    return err
}
// Auto-pages: All walks every page for you.
for sub, err := range page.All(ctx) {
    if err != nil {
        return err
    }
    fmt.Println(sub.Title)
}

_, err = client.Submissions.Create(ctx, supdesk.SubmissionsCreateParams{
    Type:  supdesk.SubmissionTypeBug,
    Title: "Export button does nothing",
    Email: "user@example.com",
    Body:  "Clicking Export on the reports page has no effect.",
})
RabinApps/supdesk-dartDart
import 'dart:io';
import 'package:supdesk/supdesk.dart';

final supdesk = SupDesk(apiKey: Platform.environment['SUPDESK_API_KEY']!);

// Auto-pages: the stream walks every page for you.
final page = await supdesk.submissions.list(status: PostStatus.open);
await for (final submission in page.autoPaging()) {
  print(submission.title);
}

await supdesk.submissions.create(
  type: SubmissionType.bug,
  title: 'Export button does nothing',
  email: 'user@example.com',
  body: 'Clicking Export on the reports page has no effect.',
);

Tag

#sdk#api#developers