SDK és példa-app

Az @dynex/app-sdk TypeScript-csomag és a dynex-app-hello példa-app: mit tudnak, hogyan telepíted őket, és mi változott a kiadások között.

Kb. 7 perc olvasás

Letöltés és telepítés

Az SDK és a példa-app letölthető csomag (nyilvános npm-en nincs). A csomagokat a kiadás állítja elő, ezért mindig az élő kóddal egyeznek.

Fájl	Mi ez	Verzió	Méret	SHA-256
dynex-app-sdk-0.2.0.tgz	SDK (npm-csomag, ESM, TypeScript-típusokkal)	0.2.0	128 kB	`a9ae50ab25152a115aa4a1ea1c4c1878abc59be2129d4c8f11c03e375e32c66b`
dynex-app-hello.zip	Példa-app (Express: OAuth, beágyazás, webhook)	-	145 kB	`e777d6e01bf4739fbcd892cd8dbf45373cdb19f54beff834a54ddf93450e9c4c`

Telepítés a projektedbe

npm install https://prod.dynex.hu/downloads/dynex-app-sdk-0.2.0.tgz

Két belépési pont van: az @dynex/app-sdk a szerveroldal (Node 18+), az @dynex/app-sdk/browser a beágyazott oldal böngészős hídja. Futásidejű függősége nincs.

Mit tartalmaz

Terület	Amit ad
API-kliens	`DynexClient` (contacts, reservations, availability, loyalty, orders, reviews, webhooks, me; `Idempotency-Key` támogatás), a generált `client.v3` és `client.v1` felület, `paginate`.
OAuth	`buildAuthorizeUrl`, `exchangeAuthorizationCode`, `createPkcePair`, `readCallbackParams`.
Webhook	`verifyWebhookSignature` / `parseWebhookEvent` (bérlői események), `isAppChannelEvent` / `parseAppEvent` (életciklus-események).
Beágyazás	`verifyEmbedToken` / `verifyEmbedTokenRemote`, és a böngészős `createAppBridge` (`@dynex/app-sdk/browser`).
Teszt-fiók	`isSandboxTenantId`.

1import { DynexClient, DynexApiError } from "@dynex/app-sdk";2 3const dynex = new DynexClient({ accessToken: install.accessToken });4const me = await dynex.me();5const { contacts } = await dynex.contacts.list({ updatedSince: lastSyncIso, limit: 100 });6const { reservation, reference } = await dynex.reservations.create(7  { date: "2026-10-01", startTime: "19:00", partySize: 4, customerName: "Kiss Anna", customerPhone: "+36301234567" },8  { idempotencyKey: "order-1234" },9);

A generált kliens

A client.v3 alatt a v3 API minden művelete elérhető, a client.v1 alatt a régi felület. A metódusok, a kérés- és a válasz-típusok a Dynex API szerződéséből készülnek, így azt tükrözik, amit a szerver elfogad. A bemenet alakja minden műveletnél ugyanaz: az útvonal paraméterei név szerint, mellettük a query és a body.

1import { DynexClient, paginate } from "@dynex/app-sdk";2 3const dynex = new DynexClient({ accessToken: install.accessToken });4 5// Egy művelet: tartomány, majd a művelet neve.6const page = await dynex.v3.contacts.list({ query: { limit: 50 } });7 8// Lapozott lista bejárása elemenként.9for await (const contact of paginate((p) => dynex.v3.contacts.list({ query: p }))) {10  console.log(contact);11}

A kézzel írt metódusok (például dynex.contacts.list) megmaradtak: ezek a generált műveletek aliasai, ugyanazzal az aláírással, mint a 0.1.0-ban.
A paginate a limit / offset lapozású listákon megy végig (pageSize alapból 100, maxItems nem kötelező), és megáll az első nem teli lapnál.
A client.v1 felület a kivezetés alatt álló régi API-t éri el; új appban a client.v3-at használd.

Ha SDK nélkül hívod az API-t, ugyanez a kérés így néz ki. Minden végpont mintája ott van az API-referenciában.

cURL

1curl -X GET 'https://prod.dynex.hu/api/v3/contacts' \2  -H 'Authorization: Bearer dxk_A_TELEPITES_KULCSA' \3  -H 'Accept: application/json'

Node.js

1// Node.js 18+ (beépített fetch, nem kell külön csomag).2async function main() {3  const res = await fetch("https://prod.dynex.hu/api/v3/contacts", {4    method: "GET",5    headers: {6      "Authorization": "Bearer dxk_A_TELEPITES_KULCSA",7      "Accept": "application/json"8    }9  });10 11  const data = await res.json();12  console.log(res.status, data);13}14 15main().catch(console.error);

Hibák és újrapróbálás

Hiba	Mikor jön
`DynexApiError`	A szerver hibaválaszt adott. Hordozza a státuszt, a hibakódot, a kérés-azonosítót (`requestId`) és a hiányzó hatókört (`requiredScope`).
`DynexTimeoutError`	A kérés túllépte az időkorlátot (`timeoutMs`).
`DynexNetworkError`	A kérés nem ért célba, vagy a válasz megszakadt.
`DynexError`	A fenti három közös őse.

Átmeneti hibánál (429, 502, 503, 504, hálózati hiba, időkorlát) a kliens magától újrapróbálkozik. A próbák számát a maxRetries adja (alapból 2, a 0 kikapcsolja). A 429-nél a Retry-After fejlécet követi.
A GET hívás mindig újrapróbálható. Író hívást a kliens csak akkor ismétel, ha a végpont a szerződés szerint idempotens, és a hívás idempotencyKey-t visz. A kulcs önmagában nem elég: ahol a végpont nem veszi figyelembe, az ismétlés kétszer írna.
Ha saját újrapróbálód van, állítsd a maxRetries értékét 0-ra, különben a kettő összeszorzódik.
A hívó saját signal-jával megszakított kérést a kliens soha nem próbálja újra.

A kérés-azonosítóról és a keret-fejlécekről a Kulcsok és biztonság oldal szól.

Verziók

A kliens minden kérésen elküldi a saját verzióját az X-Dynex-Sdk fejlécben; a csomagból a SDK_VERSION állandóval olvasható ki. A kiadások változásait a csomagban a CHANGELOG.md, itt a Változások oldal sorolja fel.

A letöltött fájl neve a verziót is tartalmazza. A verzió nélküli régi fájlnév tovább él, és mindig a legutóbbi kiadásra mutat; ha rögzített verzióra építesz, a verziós fájlnevet használd.

A példa-app

A dynex-app-hello egy minimális Express-app: OAuth callback token-cserével (sütihez kötött state + PKCE), beágyazott oldal a híddal (token → saját session → tiszta URL, frame-ancestors CSP, toast és navigálás gombok, a kontextus escape-elve kiírva), aláírás-ellenőrző webhook-fogadó mindkét csatornára (az app.uninstalled eseményre törli a telepítést), a hibáknál a kérés-azonosító naplózásával.

A README lépésről lépésre végigvisz a localhoston futó teszten (a http://localhost:3999 redirect URI regisztrálható). A környezeti változókat a csomagban lévő .env.example sorolja fel; indítás: npm install, majd npm start.

Ha most kezded, a Gyorsindítás ugyanezt az utat járja végig a teszt-fiókon.