***

title: Use TypeScript SDKs generated in Postman
updated: 2026-02-20T00:00:00.000Z
max-toc-depth: 2
----------------

This guide provides instructions for using TypeScript SDKs generated by Postman SDK Generator. It covers how to import the SDK into your project, run example code, and best practices for using the SDK effectively in your applications.

## SDK structure

The TypeScript SDK includes the following key files:

* `src/index.ts` — Main entry point, exports SDK client, services, and models
* `src/services/` — Service classes organized in directories alongside their models
* `src/http/` — HTTP client, error types, handler chain, hooks, and transport layer
* `package.json` — Dependencies vary by transport (fetch built-in, or axios)

The following is an example of the typical structure of a generated TypeScript SDK:

<Folder name="your-sdk" defaultOpen>
  <Files>
    <File name="README.md">
      Main documentation
    </File>

    <File name="package.json">
      npm package configuration
    </File>

    <File name="tsconfig.json">
      TypeScript configuration
    </File>

    <File name=".gitignore">
      Git ignore rules
    </File>

    <File name="LICENSE" />

    <File name=".env.example" />
  </Files>

  <Folder name=".devcontainer">
    <File name="devcontainer.json">
      Dev container configuration
    </File>
  </Folder>

  <Folder name="scripts">
    <File name="prepublish.sh">
      Prepublish build script
    </File>
  </Folder>

  <Folder name="src">
    <File name="index.ts">
      Main SDK client export
    </File>

    <Folder name="services">
      <File name="base-service.ts">
        Base service class
      </File>

      <Folder name="common">
        <File name="[ModelName].ts">
          Shared models used by multiple services
        </File>
      </Folder>

      <Folder name="[serviceName]">
        <Files>
          <File name="[serviceName]-service.ts">
            Service-specific directory
          </File>

          <File name="request-params.ts" />
        </Files>

        <Folder name="models">
          <File name="[ModelName].ts" />
        </Folder>
      </Folder>
    </Folder>

    <Folder name="http">
      <Files>
        <File name="client.ts">
          HTTP client
        </File>

        <File name="types.ts">
          Config types (SdkConfig, RetryOptions)
        </File>

        <File name="error.ts">
          HttpError class
        </File>

        <File name="environment.ts">
          Environment enum
        </File>
      </Files>

      <Folder name="errors">
        <Files>
          <File name="throwable-error.ts">
            Error classes
          </File>

          <File name="validation-error.ts" />
        </Files>
      </Folder>

      <Folder name="handlers">
        <Files>
          <File name="handler-chain.ts">
            Request/response handler chain
          </File>

          <File name="retry-handler.ts" />

          <File name="hook-handler.ts" />

          <File name="...">
            Additional handlers
          </File>
        </Files>
      </Folder>

      <Folder name="hooks">
        <Files>
          <File name="hook.ts">
            Custom request/response hooks
          </File>

          <File name="custom-hook.ts" />
        </Files>
      </Folder>

      <Folder name="serialization">
        <Files>
          <File name="query-serializer.ts">
            Parameter serializers
          </File>

          <File name="...">
            Additional serializers
          </File>
        </Files>
      </Folder>

      <Folder name="transport">
        <Files>
          <File name="request.ts">
            HTTP transport layer
          </File>

          <File name="request-builder.ts" />

          <File name="...">
            Additional transport files
          </File>
        </Files>
      </Folder>
    </Folder>
  </Folder>

  <Folder name="examples">
    <Folder name="src">
      <File name="index.ts">
        Example usage code
      </File>
    </Folder>

    <Files>
      <File name="package.json">
        Example project dependencies
      </File>

      <File name="README.md">
        Example documentation
      </File>
    </Files>
  </Folder>

  <Folder name="documentation">
    <Folder name="services">
      <File name="[ServiceName].md">
        Service documentation
      </File>
    </Folder>

    <Folder name="models">
      <File name="[ModelName].md">
        Model documentation
      </File>
    </Folder>

    <Folder name="snippets">
      <File name="snippets.json">
        Code snippets
      </File>
    </Folder>
  </Folder>
</Folder>

## Example usage

Each generated SDK includes an `examples/` directory with a working project demonstrating SDK usage.

The example includes the following features:

* SDK initialization with authentication
* Making API calls to various endpoints
* Error handling patterns
* Working with typed request/response models

<Tabs>
  <Tab title="Location">
    `examples/src/index.ts`
  </Tab>

  <Tab title="Run the example">
    ```bash
    cd examples
    npm install
    npm start
    ```
  </Tab>

  <Tab title="Example code structure">
    ```typescript
    import { YourSdk } from 'your-sdk-package';

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

    try {
        // Call an API endpoint
        const result = await sdk.users.getUser({ userId: '123' });
        console.log('User:', result);
    } catch (error) {
        console.error('Error:', error);
    }
    })();
    ```
  </Tab>
</Tabs>

## Import the TypeScript SDK locally

You can import the generated SDK using npm, by file path, or using a workspace (for monorepos). Below are instructions for each method.

### Import using npm link

You can use `npm link` to create a symlink to the generated SDK, allowing you to import it as if it were installed from npm.

1. Run the following commands in the SDK directory:

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

   Alternatively, run the following commands in your project directory:

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

2. Use the SDK in your code.

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

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

### Import using a file path

To import the SDK from a local path, you can either install it using npm or add it as a dependency in your `package.json`.

* Using npm:

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

* Adding to package.json:

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

### Import using workspaces (for monorepos)

To import using workspaces, add the SDK path to the `workspaces` array in your root `package.json`:

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

## Publish to npm

To share your generated TypeScript SDK with the community, you can publish it to npm. This allows other developers to easily install it using npm. Follow the steps below.

### Prerequisites

To publish your SDK to npm, you need the following:

* An npm account. You can create it at [npmjs.com](https://www.npmjs.com).
* npm CLI installed. You can install it with Node.js from [nodejs.org](https://nodejs.org).
* A unique package name. You can check availability using the `npm search your-package-name` command.

### Publish your TypeScript SDK to npm

1. Configure `package.json`. Ensure these fields are set correctly:

   ```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"
   }
   ```

2. Build the SDK.

   ```bash
   npm install
   npm run build
   npm test
   ```

3. Log in to npm.

   ```bash
   npm login
   ```

4. Publish the package.

   * For public packages, use:

     ```bash
     npm publish --access public
     ```

   * For scoped private packages, use:

     ```bash
     npm publish
     ```

5. **Verify publication:**

   ```bash
   npm info @your-org/your-sdk
   ```

### Publish updates

To publish an updated SDK, update the version in the `package.json` following the [semantic versioning](https://semver.org/):

* Patch: `1.0.0` → `1.0.1` (bug fixes)
* Minor: `1.0.0` → `1.1.0` (new features, backward compatible)
* Major: `1.0.0` → `2.0.0` (breaking changes)

Alternatively, you can use the `npm version` command:

```bash
npm version patch  # or minor, or major
npm publish
```

### Best practices for publishing TypeScript SDKs

Use the following best practices when publishing your TypeScript SDK to npm:

* Use `.npmignore` to exclude unnecessary files.
* Include a comprehensive `README.md`.
* Add a `LICENSE` file.
* Tag releases in Git: `git tag v1.0.0 && git push --tags`.
* Set up CI/CD for automated publishing.
* Consider using `np` tool for streamlined publishing: `npx np`.

## Advanced usage

You can further customize the SDK by modifying the generated code, adding new features, or integrating it with your existing codebase. Here are some advanced topics to explore.

### Authentication

The SDK supports various authentication methods. You can configure authentication when initializing the SDK client.

<Tabs>
  <Tab title="API Key">
    ```typescript
    const sdk = new YourSdk({
    token: 'your-bearer-token'
    });
    ```
  </Tab>

  <Tab title="Bearer Token">
    ```python
    sdk = YourSdk(access_token="your-bearer-token")
    ```
  </Tab>

  <Tab title="Basic Auth">
    ```typescript
    const sdk = new YourSdk({
    username: 'your-username',
    password: 'your-password'
    });
    ```
  </Tab>

  <Tab title="OAuth 2.0 (Client Credentials)">
    ```typescript
    const sdk = new YourSdk({
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret'
    });

    // SDK automatically handles token refresh
    const result = await sdk.users.getUser({ userId: '123' });
    ```
  </Tab>

  <Tab title="OAuth 2.0 (Access Token)">
    ```typescript
    const sdk = new YourSdk({
    accessToken: 'your-access-token'
    });
    ```
  </Tab>
</Tabs>

### Environment management

The SDK supports multiple environments (for example, production, staging) with different base URLs.

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

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

// Or use custom base URL
const sdk = new YourSdk({
  baseUrl: 'https://custom.api.example.com',
  apiKey: 'your-api-key'
});
```

### Error handling

The SDK raises custom exceptions for API errors, which include details about the error message, status code, and response body. You can catch these exceptions to handle errors in your application.

To handle errors, do the following:

```typescript
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);
  }
}
```

To handle specific error codes, do the following:

```typescript
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);
    }
  }
}
```

### Timeouts and retries

To set a global timeout, do the following:

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

To set a per-request timeout, do the following:

Config can be overridden per-request using `requestConfig`:

```typescript
const user = await sdk.users.getUser(
  { userId: '123' },
  { timeoutMs: 5000 } // 5 seconds for this request only
);
```

To configure retries, do the following:

```typescript
const sdk = new YourSdk({
  apiKey: 'your-api-key',
  retry: {
    attempts: 3,
    delayMs: 1000,         // 1 second between retries
    maxDelayMs: 30000,     // max delay cap
    backoffFactor: 2,      // exponential backoff multiplier
    jitterMs: 100,         // random jitter
    statusCodesToRetry: [408, 429, 500, 502, 503, 504],
    httpMethodsToRetry: ['GET', 'POST', 'PUT', 'DELETE']
  }
});
```

## Additional resources

Consider the following resources for using and customizing your TypeScript SDK:

* SDK documentation — Check the `documentation/` directory in your SDK for detailed docs on services, models, and code snippets.
* Type definitions — All models and services are fully typed.
* Example usage — Refer to the `examples/` directory for working code samples demonstrating how to use the SDK in different scenarios.
* Dependencies — (vary by transport selection):
  * fetch (built-in) or axios: HTTP client
  * zod: Runtime validation (when response validation is enabled)