@tekuna/sdk-node — מדריך התחלה מהירה

English summary: Hebrew quickstart for the official @tekuna/sdk-node SDK. Install, provision a partner API key, mint your first DILS on Chain 2027, and call every module method. Scroll down for code samples.

1. מה זה ה-SDK?

@tekuna/sdk-node היא ספריית ה-Node.js הרשמית לאינטגרציה עם תשתית הסליקה הריבונית של TEKUNA / DILS. עם ה-SDK תוכל:

• להנפיק (mint) DILS לארנק מועדון השותף שלך על Chain 2027 (פרודקשן) או Chain 2026 (סנדבוקס).
• לרשום ולנהל את משתמשי הקצה שלך (מודל ANIKAN, עד אלפי משתמשים לכל שותף).
• לקרוא יתרת DILS + TKN של הארנק שלך מהשרשרת.
• לדפדף בעסקאות עם מטא-דאטה של Source → Nature → Path (SNP).
• לאמת את זהות השותף (club, tier, modules).

הכלל הבסיסי: 1 DILS = 1 ש"ח = 100 אגורות. כל הסכומים ב-SDK מועברים באגורות (שלמים) כדי למנוע בעיות עיגול.

2. דרישות

• Node.js גרסה 18 ומעלה (תמיכה מובנית ב-fetch).
• מפתח API של שותף (sk_test_dils_… לסנדבוקס או sk_live_dils_… לפרודקשן).
• חיבור אינטרנט יוצא ל-https://api.dils.co.il.

3. התקנה

npm install @tekuna/sdk-node

מהמרשם הפנימי של TEKUNA ב-Artifact Registry:

npm install @tekuna/sdk-node \
  --registry=https://me-west1-npm.pkg.dev/tekuna-blockchain/tekuna-npm/

4. השגת מפתח API (provisioning)

מפתח השותף נוצר באמצעות בקשת POST ל-/api/sdk/provision עם פרטי KYB:

curl -X POST https://api.dils.co.il/api/sdk/provision \
  -H 'Content-Type: application/json' \
  -d '{
    "kyb": {
      "legalEntityId": "514123456",
      "name": "חברת הדגמה בע\"מ",
      "email": "ceo@demo.co.il",
      "address": "רוטשילד 1, תל אביב"
    },
    "tier": "starter",
    "chain": "testnet"
  }'

תשובה לדוגמה:

{
  "apiKey": "sk_test_dils_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "clubId": "uuid-…",
  "customerCardId": "uuid-…",
  "walletAddress": "0xabc…",
  "chain": "testnet",
  "tier": "starter",
  "modules": ["clubs", "payments"]
}

⚠️ שמור את ה-apiKey בצורה מאובטחת (Secret Manager / Vault). המערכת שומרת רק את ה-hash שלו; אין דרך לשחזר אותו.

5. הקוד הראשון — הנפקת DILS

import { Tekuna } from '@tekuna/sdk-node';

const tekuna = new Tekuna({
  apiKey: process.env.TEKUNA_API_KEY!,
});

const tx = await tekuna.dils.mint({ amount_agorot: 10000 });
//                                  ^^^^^^^^^^^^^^^^^^^^^^
//                                  100 ש"ח (10,000 אגורות)

console.log('Tx hash:', tx.tx_hash);
console.log('Chain:',   tx.chain_id);   // 2026 לסנדבוקס, 2027 לפרודקשן
console.log('Block:',   tx.block_number);

ה-tx_hash מוחזר זהו hash אמיתי על Chain 2027 (או 2026 בסנדבוקס) שניתן לאמת ב-RPC.

6. תיעוד מלא של המודולים

הקונסטרקטור:

const tekuna = new Tekuna({
  apiKey: 'sk_test_dils_…',     // חובה
  baseUrl: 'https://api.dils.co.il'  // אופציונלי; ברירת המחדל זו
});

tekuna.dils

mint({ amount_agorot, idempotency_key? })

הנפקת DILS לארנק מועדון השותף.

const tx = await tekuna.dils.mint({
  amount_agorot: 50000,            // 500 ש"ח
  idempotency_key: 'order-12345',  // אופציונלי, 24 שעות
});
// → { tx_hash, amount_agorot, amount_dils, chain_id, block_number, status }

תקרה: 10,000,000 אגורות (100,000 ש"ח) לכל קריאה.

tekuna.endUsers

list({ limit?, offset?, kyc_status? })

מחזיר את רשימת משתמשי הקצה השייכים לשותף המאומת.

const { users, total } = await tekuna.endUsers.list({
  limit: 100,
  offset: 0,
  kyc_status: 'verified',  // 'pending' | 'in_review' | 'verified' | 'rejected'
});
console.log(`${users.length} מתוך ${total} משתמשים`);

get(id)

מחזיר משתמש קצה יחיד לפי מזהה.

const user = await tekuna.endUsers.get('user-uuid');
// → { id, email, full_name, phone, wallet_address, kyc_status, kyc_level, created_at }

זורק TekunaApiError עם סטטוס 404 אם המשתמש לא קיים או לא שייך לשותף.

tekuna.wallet

balance()

תמונת מצב של יתרת DILS + TKN על השרשרת.

const bal = await tekuna.wallet.balance();
// → { club_id, wallet_address, dils_balance: "123.45",
//     dils_balance_agorot: 12345, tkn_balance: "0",
//     chain_id, block_number }

dils_balance_agorot הוא היחידה השלמה הקנונית — השתמש בו לחישובים פנימיים.

tekuna.transactions

list({ limit?, offset?, from_date?, to_date?, status? })

מחזיר את העסקאות של מועדון השותף, החדשות ביותר ראשונות.

const { transactions, total } = await tekuna.transactions.list({
  limit: 50,
  from_date: '2026-05-01T00:00:00Z',
  to_date:   '2026-05-25T00:00:00Z',
  status:    'confirmed',
});
for (const tx of transactions) {
  console.log(tx.tx_hash, tx.amount_dils, tx.snp_nature);
}

tekuna.auth

me()

זהות השותף המאומת.

const me = await tekuna.auth.me();
// → { club_id, club_name, wallet_address, tier, chain, modules, provisioned_at }
if (me.tier === 'starter') { /* … */ }

7. טיפול בשגיאות

כל קריאה זורקת TekunaApiError במקרה של תגובה שאינה 2xx (או שגיאת רשת לפני שהבקשה הגיעה לשרת):

import { Tekuna, TekunaApiError } from '@tekuna/sdk-node';

try {
  await tekuna.dils.mint({ amount_agorot: 10000 });
} catch (err) {
  if (err instanceof TekunaApiError) {
    console.error(`[${err.status}] ${err.code}: ${err.message}`);
    console.error('Raw body:', err.details);

    if (err.status === 401) {
      // מפתח לא תקין או שפג תוקפו → רענן מ-Secret Manager
    } else if (err.code === 'WALLET_NOT_DEPLOYED') {
      // הפרובוז'נינג לא הושלם → חכה או הרץ מחדש
    } else if (err.code === 'RPC_UNAVAILABLE') {
      // הרשת לא זמינה זמנית → נסה שוב עם backoff אקספוננציאלי
    }
  }
  throw err;
}

קודי שגיאה מרכזיים:

8. סנדבוקס מול פרודקשן

המעבר מסנדבוקס לפרודקשן דורש סבב אישור (KYB מלא + סקירת אבטחה). ה-SDK עצמו זהה — רק המפתח משתנה.

9. דוגמה מלאה — שילוב POS

תרחיש: עסק קולט תשלום של 49 ש"ח, מנפיק DILS למועדון, ושומר לקוח רישום עם SNP.

import { Tekuna, TekunaApiError } from '@tekuna/sdk-node';

const tekuna = new Tekuna({ apiKey: process.env.TEKUNA_API_KEY! });

async function settlePosCharge(orderId: string, ils: number, merchantId: string): Promise<string> {
  const amount_agorot = Math.round(ils * 100);

  try {
    const tx = await tekuna.dils.mint({
      amount_agorot,
      idempotency_key: `pos:${orderId}`,
    });

    console.log(`✓ Order ${orderId} settled: ${tx.tx_hash}`);
    return tx.tx_hash;

  } catch (err) {
    if (err instanceof TekunaApiError && err.code === 'WALLET_NOT_DEPLOYED') {
      throw new Error('המתן לסיום הפרוביז\'נינג של המועדון');
    }
    throw err;
  }
}

await settlePosCharge('ord-7891', 49.00, 'rest-001');

10. סופ"ש מצוין

תיעוד מלא של ה-REST API: https://api.dils.co.il/health (מחזיר 200 + מטא-דאטה). לתמיכה: orel@dils.co.il. לבעיות באבטחה (SOC 2 / NIMBUS L5): security@dils.co.il.

עודכן: 2026-05-25 · גרסת SDK: 0.1.0 · NIMBUS L5 me-west1