استفاده از SDKهای TypeScript تولیدشده در Postman

این راهنما روش استفاده از SDKهای TypeScript تولیدشده با Postman SDK Generator را توضیح می‌دهد: ساختار SDK، اجرای مثال، import محلی، انتشار در npm، authentication، environment، error handling و تنظیم timeout/retry.

ساختار SDK TypeScript

• src/index.ts: نقطه ورود اصلی و محل export کردن client، serviceها و modelها.
• src/services/: کلاس‌های service کنار modelهای مربوط به همان service.
• src/http/: HTTP client، نوع‌های خطا، handler chain، hookها و transport layer.
• package.json: وابستگی‌ها؛ بسته به transport می‌تواند از fetch داخلی یا axios استفاده کند.

اجرای نمونه SDK

هر SDK تولیدشده پوشه examples/ دارد. این مثال initialization، authentication، فراخوانی endpoint، error handling و کار با request/responseهای typed را نشان می‌دهد.

cd examples
npm install
npm start

import { YourSdk } from 'your-sdk-package';

(async () => {
  const sdk = new YourSdk({
    apiKey: 'your-api-key',
    baseUrl: 'https://api.example.com'
  });

  try {
    const result = await sdk.users.getUser({ userId: '123' });
    console.log('User:', result);
  } catch (error) {
    console.error('Error:', error);
  }
})();

Import کردن SDK به صورت local

روش npm link

cd path/to/your-sdk
npm install
npm run build
npm link

cd path/to/your-project
npm link your-sdk-package-name

import { YourSdk } from 'your-sdk-package-name';

const sdk = new YourSdk({ apiKey: 'test' });

روش file path

npm install ../path/to/your-sdk

{
  "dependencies": {
    "your-sdk": "file:../path/to/your-sdk"
  }
}

روش workspace برای monorepo

{
  "workspaces": [
    "packages/*",
    "path/to/your-sdk"
  ]
}

انتشار SDK در npm

برای انتشار عمومی یا داخلی SDK، به حساب npm، نصب npm CLI و نام package یکتا نیاز دارید. قبل از انتشار، package.json را کامل کنید.

{
  "name": "@your-org/your-sdk",
  "version": "1.0.0",
  "description": "SDK for Your API",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist", "README.md", "LICENSE"],
  "repository": {
    "type": "git",
    "url": "https://github.com/your-org/your-sdk"
  },
  "keywords": ["api", "sdk", "your-api"],
  "author": "Your Name",
  "license": "MIT"
}

npm install
npm run build
npm test
npm login
npm publish --access public
npm info @your-org/your-sdk

برای نسخه‌های بعدی از semantic versioning استفاده کنید: patch برای bug fix، minor برای قابلیت سازگار، و major برای breaking change.

npm version patch  # or minor, or major
npm publish

بهترین کارها برای npm

• با .npmignore فایل‌های غیرضروری را حذف کنید.
• README.md و LICENSE کامل داشته باشید.
• releaseها را در Git tag کنید.
• برای publish خودکار CI/CD بسازید.
• در صورت نیاز از ابزار np استفاده کنید: npx np.

Authentication

روش authentication به security schemeهای API شما بستگی دارد. نمونه‌های رایج:

const sdk = new YourSdk({ token: 'your-bearer-token' });

const sdk = new YourSdk({
  username: 'your-username',
  password: 'your-password'
});

const sdk = new YourSdk({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret'
});

const result = await sdk.users.getUser({ userId: '123' });

const sdk = new YourSdk({ accessToken: 'your-access-token' });

Environment management

import { YourSdk, Environment } from 'your-sdk';

const sdk = new YourSdk({
  environment: Environment.PRODUCTION,
  apiKey: 'your-api-key'
});

const customSdk = new YourSdk({
  baseUrl: 'https://custom.api.example.com',
  apiKey: 'your-api-key'
});

Error handling

SDK برای خطاهای API exceptionهای اختصاصی ایجاد می‌کند. این خطاها معمولا message، status code و response body را در اختیار شما می‌گذارند.

import { YourSdk, HttpError, ValidationError } from 'your-sdk';

const sdk = new YourSdk({ apiKey: 'your-api-key' });

try {
  const user = await sdk.users.getUser({ userId: '123' });
  console.log(user);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
  } else if (error instanceof HttpError) {
    console.error('HTTP error:', error.message);
    console.error('Status code:', error.metadata.status);
    console.error('Response:', error.raw);
  } else {
    console.error('Unexpected error:', error);
  }
}

try {
  await sdk.users.deleteUser({ userId: '123' });
} catch (error) {
  if (error instanceof HttpError) {
    switch (error.metadata.status) {
      case 404:
        console.log('User not found');
        break;
      case 403:
        console.log('Permission denied');
        break;
      default:
        console.log('HTTP error:', error.message);
    }
  }
}

Timeout و retry

const sdk = new YourSdk({
  apiKey: 'your-api-key',
  timeoutMs: 10000
});

const user = await sdk.users.getUser(
  { userId: '123' },
  { timeoutMs: 5000 }
);

const sdk = new YourSdk({
  apiKey: 'your-api-key',
  retry: {
    attempts: 3,
    delayMs: 1000,
    maxDelayMs: 30000,
    backoffFactor: 2,
    jitterMs: 100,
    statusCodesToRetry: [408, 429, 500, 502, 503, 504],
    httpMethodsToRetry: ['GET', 'POST', 'PUT', 'DELETE']
  }
});

منابع داخل SDK

• پوشه documentation/ برای مستندات serviceها، modelها و snippetها.
• type definitionهای کامل برای modelها و serviceها.
• پوشه examples/ برای نمونه‌های اجرایی.
• وابستگی‌هایی مثل fetch یا axios، و در صورت فعال بودن validation، کتابخانه zod.

منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.