SDKs for Node.js and PHP
Two official clients with the same resources and methods as the reference. Both retry failed requests, set idempotency keys, verify webhook signatures and report errors with code and request ID.
The API is built and tested. Hosting at api.garanify.com is in preparation; until then it runs locally. Keys are available on request.
| Node.js / TypeScript | PHP | |
|---|---|---|
| Package | @garanify/sdk | garanify/sdk |
| Runtime | Node.js 18+, Deno, Bun, edge; ESM and CommonJS | PHP 8.1+, any PSR-18 client (e.g. Guzzle) |
| Types | generated from the OpenAPI file | PHPDoc shapes, responses as arrays |
| Dependencies | none | psr/http-client, psr/http-factory |
| Status | Built and tested, not published yet. | |
Install
# not on npm yet; until then from the repository
npm install ./packages/sdk-js# not on Packagist yet; until then as a path repository
composer config repositories.garanify path ./packages/sdk-php
composer require garanify/sdk:@dev guzzlehttp/guzzleSet up
The client only needs the key. It fetches the shop ID once with GET /v1/me; for publishable keys it reads it from the key. Without baseUrl it uses https://api.garanify.com (hosting in preparation).
import { Garanify } from '@garanify/sdk';
const garanify = new Garanify({
apiKey: process.env.GARANIFY_SECRET_KEY, // gfy_sk_… or gfy_sk_test_…
baseUrl: process.env.GARANIFY_BASE_URL, // optional, e.g. http://localhost:8788
maxRetries: 2,
timeout: 10_000,
});
const me = await garanify.me();
console.log(me.shop, me.plan, me.livemode);<?php
use Garanify\Garanify;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
$factory = new HttpFactory();
$garanify = new Garanify(getenv('GARANIFY_SECRET_KEY'), [ // gfy_sk_… or gfy_sk_test_…
'baseUrl' => getenv('GARANIFY_BASE_URL') ?: Garanify::DEFAULT_BASE_URL,
'maxRetries' => 2,
'httpClient' => new Client(['timeout' => 10]),
'requestFactory' => $factory,
'streamFactory' => $factory,
]);
$me = $garanify->me();
echo $me['shop'], ' ', $me['plan'], ' ', $me['livemode'] ? 'live' : 'test';Resources
| Resource | Methods |
|---|---|
me() | key, shop, plan, livemode |
shops | create, retrieve, update |
license | retrieve, link, unlink |
keys | list, create, rotate, revoke |
products | list, listAll, retrieve, upsert, delete, bulkUpsert, resolve, preview, renderGaran |
rules | list, replace |
evidence | export (CSV) |
render | garan, notice (no key needed) |
public | shop, product (publishable key) |
webhooks | retrieve, set, delete, test, deliveries, retry |
meta | health, languages, modules, webhookEvents |
Every reference page shows the matching call in both SDKs. The build checks that every method shown there exists in the SDK.
Products and labels
const product = await garanify.products.upsert('WCR870', {
name: 'Washing machine W1',
brand: 'Miele',
mpn: 'WCR 870 WPS', // model identifier on the label, never the EAN
garan: { years: 10 },
});
console.log(product.status); // 'label'
const why = await garanify.products.resolve('WCR870', { lang: 'de' });
console.log(why.reason.code);
const svg = await garanify.products.renderGaran('WCR870', { lang: 'de' }); // official SVG, null without a label<?php
$product = $garanify->products->upsert('WCR870', [
'name' => 'Washing machine W1',
'brand' => 'Miele',
'mpn' => 'WCR 870 WPS', // model identifier on the label, never the EAN
'garan' => ['years' => 10],
]);
echo $product['status']; // label
$why = $garanify->products->resolve('WCR870', 'de');
echo $why['reason']['code'];
$html = $garanify->products->renderGaran('WCR870', ['format' => 'html', 'lang' => 'de']); // null without a labelPagination
Lists are cursor-based (nextCursor). listAll fetches all pages one after another.
for await (const p of garanify.products.listAll({ status: 'invalid' })) {
console.log(p.sku, p.errors.map((e) => e.code));
}<?php
foreach ($garanify->products->listAll(['status' => 'invalid']) as $p) {
echo $p['sku'], ': ', implode(', ', array_column($p['errors'], 'code')), PHP_EOL;
}Errors
Every response from 400 up becomes a GaranifyError (PHP: GaranifyException) with status, the stable code from errors and codes, errors and requestId. Network errors have status 0 and the code network_error (Node.js also timeout).
import { Garanify, GaranifyError } from '@garanify/sdk';
try {
await garanify.products.upsert('X', { garan: { years: 'ten' } });
} catch (e) {
if (!(e instanceof GaranifyError)) throw e;
console.log(e.status, e.code, e.errors, e.requestId);
// 422 'validation_failed' [{ path: '/garan/years', message: '…' }] 'req_…'
}<?php
use Garanify\GaranifyException;
try {
$garanify->products->upsert('X', ['garan' => ['years' => 'ten']]);
} catch (GaranifyException $e) {
echo $e->status, ' ', $e->errorCode, ' ', $e->requestId;
// 422 validation_failed req_…
}Retries and idempotency
- Network errors, timeouts,
408,429and5xxare retried, twice by default with growing waits. On429the client waits forRetry-After(at most 60 s). - GET, PUT, DELETE and previews are always safe to retry. POSTs that create something get an
Idempotency-Keyautomatically, the same across all attempts. - With your own key, retries across processes are safe too. More in limits.
const importId = 'run-42';
const page = 1;
const batch = [{ sku: 'WCR870', brand: 'Miele', mpn: 'WCR 870 WPS', garan: { years: 10 } }];
await garanify.products.bulkUpsert(batch, { idempotencyKey: `import-${importId}-${page}` });<?php
$batch = [['sku' => 'WCR870', 'brand' => 'Miele', 'mpn' => 'WCR 870 WPS', 'garan' => ['years' => 10]]];
$garanify->products->bulkUpsert($batch, ['idempotencyKey' => "import-{$importId}-{$page}"]);Several shops
Agencies use the same secret key for other shops of the account.
const other = garanify.withShop('shp_7Rb2Kc9mQx4Z');
await other.products.list({ limit: 50 });<?php
$other = $garanify->withShop('shp_7Rb2Kc9mQx4Z');
$other->products->list(['limit' => 50]);