https://github.com/dubinc/dub-ts

Official Dub Typescript SDK
https://github.com/dubinc/dub-ts
api dub node npm sdk speakeasy speakeasyapi typescript
Last synced: 5 months ago
JSON representation
Official Dub Typescript SDK
Host: GitHub
URL: https://github.com/dubinc/dub-ts
Owner: dubinc
License: mit
Created: 2024-01-09T17:53:29.000Z (over 2 years ago)
Default Branch: main
Last Pushed: 2026-02-16T00:44:34.000Z (5 months ago)
Last Synced: 2026-02-16T08:22:33.352Z (5 months ago)
Topics: api, dub, node, npm, sdk, speakeasy, speakeasyapi, typescript
Language: TypeScript
Homepage: https://dub.co/solutions/typescript
Size: 5.87 MB
Stars: 62
Watchers: 2
Forks: 19
Open Issues: 3
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project

README

          


  

  Dub.co TypeScript SDK

  

  

    

  






Learn more about the Dub.co TypeScript SDK in the [official documentation](https://dub.co/docs/sdks/typescript/overview).

## Table of Contents

  * [SDK Installation](#sdk-installation)

  * [Requirements](#requirements)

  * [SDK Example Usage](#sdk-example-usage)

  * [Available Resources and Operations](#available-resources-and-operations)

  * [Error Handling](#error-handling)

  * [Server Selection](#server-selection)

  * [Custom HTTP Client](#custom-http-client)

  * [Authentication](#authentication)

  * [Retries](#retries)

  * [Pagination](#pagination)

  * [Standalone functions](#standalone-functions)

  * [Debugging](#debugging)

* [Development](#development)

  * [Contributions](#contributions)

## SDK Installation

The SDK can be installed with either [npm](https://www.npmjs.com/), [pnpm](https://pnpm.io/), [bun](https://bun.sh/) or [yarn](https://classic.yarnpkg.com/en/) package managers.

### NPM

```bash

npm add dub

```

### PNPM

```bash

pnpm add dub

```

### Bun

```bash

bun add dub

```

### Yarn

```bash

yarn add dub

```

> [!NOTE]

> This package is published with CommonJS and ES Modules (ESM) support.

## Requirements

For supported JavaScript runtimes, please consult [RUNTIMES.md](RUNTIMES.md).

## SDK Example Usage

### Example 1

```typescript

import { Dub } from "dub";

const dub = new Dub({

  token: "DUB_API_KEY",

});

async function run() {

  const result = await dub.links.create();

  console.log(result);

}

run();

```

### Example 2

```typescript

import { Dub } from "dub";

const dub = new Dub({

  token: "DUB_API_KEY",

});

async function run() {

  const result = await dub.links.upsert();

  console.log(result);

}

run();

```

## Available Resources and Operations

Available methods

### [Analytics](docs/sdks/analytics/README.md)

* [retrieve](docs/sdks/analytics/README.md#retrieve) - Retrieve analytics for a link, a domain, or the authenticated workspace.

### [Bounties](docs/sdks/bounties/README.md)

* [listSubmissions](docs/sdks/bounties/README.md#listsubmissions) - List bounty submissions

* [approveSubmission](docs/sdks/bounties/README.md#approvesubmission) - Approve a bounty submission

* [rejectSubmission](docs/sdks/bounties/README.md#rejectsubmission) - Reject a bounty submission

### [Commissions](docs/sdks/commissions/README.md)

* [list](docs/sdks/commissions/README.md#list) - List all commissions

* [update](docs/sdks/commissions/README.md#update) - Update a commission.

### [Customers](docs/sdks/customers/README.md)

* [list](docs/sdks/customers/README.md#list) - Retrieve a list of customers

* [get](docs/sdks/customers/README.md#get) - Retrieve a customer

* [delete](docs/sdks/customers/README.md#delete) - Delete a customer

* [update](docs/sdks/customers/README.md#update) - Update a customer

### [Domains](docs/sdks/domains/README.md)

* [list](docs/sdks/domains/README.md#list) - Retrieve a list of domains

* [create](docs/sdks/domains/README.md#create) - Create a domain

* [delete](docs/sdks/domains/README.md#delete) - Delete a domain

* [update](docs/sdks/domains/README.md#update) - Update a domain

* [register](docs/sdks/domains/README.md#register) - Register a domain

* [checkStatus](docs/sdks/domains/README.md#checkstatus) - Check the availability of one or more domains

### [EmbedTokens](docs/sdks/embedtokens/README.md)

* [referrals](docs/sdks/embedtokens/README.md#referrals) - Create a referrals embed token

### [Events](docs/sdks/events/README.md)

* [list](docs/sdks/events/README.md#list) - Retrieve a list of events

### [Folders](docs/sdks/folders/README.md)

* [list](docs/sdks/folders/README.md#list) - Retrieve a list of folders

* [create](docs/sdks/folders/README.md#create) - Create a folder

* [delete](docs/sdks/folders/README.md#delete) - Delete a folder

* [update](docs/sdks/folders/README.md#update) - Update a folder

### [Links](docs/sdks/links/README.md)

* [list](docs/sdks/links/README.md#list) - Retrieve a list of links

* [create](docs/sdks/links/README.md#create) - Create a link

* [count](docs/sdks/links/README.md#count) - Retrieve links count

* [get](docs/sdks/links/README.md#get) - Retrieve a link

* [delete](docs/sdks/links/README.md#delete) - Delete a link

* [update](docs/sdks/links/README.md#update) - Update a link

* [createMany](docs/sdks/links/README.md#createmany) - Bulk create links

* [deleteMany](docs/sdks/links/README.md#deletemany) - Bulk delete links

* [updateMany](docs/sdks/links/README.md#updatemany) - Bulk update links

* [upsert](docs/sdks/links/README.md#upsert) - Upsert a link

### [Partners](docs/sdks/partners/README.md)

* [list](docs/sdks/partners/README.md#list) - List all partners

* [create](docs/sdks/partners/README.md#create) - Create or update a partner

* [retrieveLinks](docs/sdks/partners/README.md#retrievelinks) - Retrieve a partner's links.

* [createLink](docs/sdks/partners/README.md#createlink) - Create a link for a partner

* [upsertLink](docs/sdks/partners/README.md#upsertlink) - Upsert a link for a partner

* [analytics](docs/sdks/partners/README.md#analytics) - Retrieve analytics for a partner

* [ban](docs/sdks/partners/README.md#ban) - Ban a partner

* [deactivate](docs/sdks/partners/README.md#deactivate) - Deactivate a partner

### [Payouts](docs/sdks/payouts/README.md)

* [list](docs/sdks/payouts/README.md#list) - List all payouts

### [QRCodes](docs/sdks/qrcodes/README.md)

* [get](docs/sdks/qrcodes/README.md#get) - Retrieve a QR code

### [Tags](docs/sdks/tags/README.md)

* [list](docs/sdks/tags/README.md#list) - Retrieve a list of tags

* [create](docs/sdks/tags/README.md#create) - Create a tag

* [delete](docs/sdks/tags/README.md#delete) - Delete a tag

* [update](docs/sdks/tags/README.md#update) - Update a tag

### [Track](docs/sdks/track/README.md)

* [lead](docs/sdks/track/README.md#lead) - Track a lead

* [sale](docs/sdks/track/README.md#sale) - Track a sale

## Error Handling

[`DubError`](./src/models/errors/duberror.ts) is the base class for all HTTP error responses. It has the following properties:

| Property            | Type       | Description                                                                             |

| ------------------- | ---------- | --------------------------------------------------------------------------------------- |

| `error.message`     | `string`   | Error message                                                                           |

| `error.statusCode`  | `number`   | HTTP response status code eg `404`                                                      |

| `error.headers`     | `Headers`  | HTTP response headers                                                                   |

| `error.body`        | `string`   | HTTP body. Can be empty string if no body is returned.                                  |

| `error.rawResponse` | `Response` | Raw HTTP response                                                                       |

| `error.data$`       |            | Optional. Some errors may contain structured data. [See Error Classes](#error-classes). |

### Example

```typescript

import { Dub } from "dub";

import * as errors from "dub/models/errors";

const dub = new Dub({

  token: "DUB_API_KEY",

});

async function run() {

  try {

    const result = await dub.links.list();

    for await (const page of result) {

      console.log(page);

    }

  } catch (error) {

    // The base class for HTTP error responses

    if (error instanceof errors.DubError) {

      console.log(error.message);

      console.log(error.statusCode);

      console.log(error.body);

      console.log(error.headers);

      // Depending on the method different errors may be thrown

      if (error instanceof errors.BadRequest) {

        console.log(error.data$.error); // errors.ErrorT

      }

    }

  }

}

run();

```

### Error Classes

**Primary errors:**

* [`DubError`](./src/models/errors/duberror.ts): The base class for HTTP error responses.

  * [`BadRequest`](./src/models/errors/badrequest.ts): The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). Status code `400`.

  * [`Unauthorized`](./src/models/errors/unauthorized.ts): Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. Status code `401`.

  * [`Forbidden`](./src/models/errors/forbidden.ts): The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. Status code `403`.

  * [`NotFound`](./src/models/errors/notfound.ts): The server cannot find the requested resource. Status code `404`.

  * [`Conflict`](./src/models/errors/conflict.ts): This response is sent when a request conflicts with the current state of the server. Status code `409`.

  * [`InviteExpired`](./src/models/errors/inviteexpired.ts): This response is sent when the requested content has been permanently deleted from server, with no forwarding address. Status code `410`.

  * [`UnprocessableEntity`](./src/models/errors/unprocessableentity.ts): The request was well-formed but was unable to be followed due to semantic errors. Status code `422`.

  * [`RateLimitExceeded`](./src/models/errors/ratelimitexceeded.ts): The user has sent too many requests in a given amount of time ("rate limiting"). Status code `429`.

  * [`InternalServerError`](./src/models/errors/internalservererror.ts): The server has encountered a situation it does not know how to handle. Status code `500`.

Less common errors (6)




**Network errors:**

* [`ConnectionError`](./src/models/errors/httpclienterrors.ts): HTTP client was unable to make a request to a server.

* [`RequestTimeoutError`](./src/models/errors/httpclienterrors.ts): HTTP request timed out due to an AbortSignal signal.

* [`RequestAbortedError`](./src/models/errors/httpclienterrors.ts): HTTP request was aborted by the client.

* [`InvalidRequestError`](./src/models/errors/httpclienterrors.ts): Any input used to create a request is invalid.

* [`UnexpectedClientError`](./src/models/errors/httpclienterrors.ts): Unrecognised or unexpected error.

**Inherit from [`DubError`](./src/models/errors/duberror.ts)**:

* [`ResponseValidationError`](./src/models/errors/responsevalidationerror.ts): Type mismatch between the data returned from the server and the structure expected by the SDK. See `error.rawValue` for the raw value and `error.pretty()` for a nicely formatted multi-line string.

## Server Selection

### Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the `serverURL: string` optional parameter when initializing the SDK client instance. For example:

```typescript

import { Dub } from "dub";

const dub = new Dub({

  serverURL: "https://api.dub.co",

  token: "DUB_API_KEY",

});

async function run() {

  const result = await dub.links.list();

  for await (const page of result) {

    console.log(page);

  }

}

run();

```

## Custom HTTP Client

The TypeScript SDK makes API calls using an `HTTPClient` that wraps the native

[Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). This

client is a thin wrapper around `fetch` and provides the ability to attach hooks

around the request lifecycle that can be used to modify the request or handle

errors and response.

The `HTTPClient` constructor takes an optional `fetcher` argument that can be

used to integrate a third-party HTTP client or when writing tests to mock out

the HTTP client and feed in fixtures.

The following example shows how to:

- route requests through a proxy server using [undici](https://www.npmjs.com/package/undici)'s ProxyAgent

- use the `"beforeRequest"` hook to add a custom header and a timeout to requests

- use the `"requestError"` hook to log errors

```typescript

import { Dub } from "dub";

import { ProxyAgent } from "undici";

import { HTTPClient } from "dub/lib/http";

const dispatcher = new ProxyAgent("http://proxy.example.com:8080");

const httpClient = new HTTPClient({

  // 'fetcher' takes a function that has the same signature as native 'fetch'.

  fetcher: (input, init) =>

    // 'dispatcher' is specific to undici and not part of the standard Fetch API.

    fetch(input, { ...init, dispatcher } as RequestInit),

});

httpClient.addHook("beforeRequest", (request) => {

  const nextRequest = new Request(request, {

    signal: request.signal || AbortSignal.timeout(5000)

  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;

});

httpClient.addHook("requestError", (error, request) => {

  console.group("Request Error");

  console.log("Reason:", `${error}`);

  console.log("Endpoint:", `${request.method} ${request.url}`);

  console.groupEnd();

});

const sdk = new Dub({ httpClient: httpClient });

```

## Authentication

### Per-Client Security Schemes

This SDK supports the following security scheme globally:

| Name    | Type | Scheme      |

| ------- | ---- | ----------- |

| `token` | http | HTTP Bearer |

To authenticate with the API the `token` parameter must be set when initializing the SDK client instance. For example:

```typescript

import { Dub } from "dub";

const dub = new Dub({

  token: "DUB_API_KEY",

});

async function run() {

  const result = await dub.links.list();

  for await (const page of result) {

    console.log(page);

  }

}

run();

```

## Retries

Some of the endpoints in this SDK support retries.  If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API.  However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retryConfig object to the call:

```typescript

import { Dub } from "dub";

const dub = new Dub({

  token: "DUB_API_KEY",

});

async function run() {

  const result = await dub.links.list(undefined, {

    retries: {

      strategy: "backoff",

      backoff: {

        initialInterval: 1,

        maxInterval: 50,

        exponent: 1.1,

        maxElapsedTime: 100,

      },

      retryConnectionErrors: false,

    },

  });

  for await (const page of result) {

    console.log(page);

  }

}

run();

```

If you'd like to override the default retry strategy for all operations that support retries, you can provide a retryConfig at SDK initialization:

```typescript

import { Dub } from "dub";

const dub = new Dub({

  retryConfig: {

    strategy: "backoff",

    backoff: {

      initialInterval: 1,

      maxInterval: 50,

      exponent: 1.1,

      maxElapsedTime: 100,

    },

    retryConnectionErrors: false,

  },

  token: "DUB_API_KEY",

});

async function run() {

  const result = await dub.links.list();

  for await (const page of result) {

    console.log(page);

  }

}

run();

```

## Pagination

Some of the endpoints in this SDK support pagination. To use pagination, you

make your SDK calls as usual, but the returned response object will also be an

async iterable that can be consumed using the [`for await...of`][for-await-of]

syntax.

[for-await-of]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of

Here's an example of one such pagination call:

```typescript

import { Dub } from "dub";

const dub = new Dub({

  token: "DUB_API_KEY",

});

async function run() {

  const result = await dub.links.list();

  for await (const page of result) {

    console.log(page);

  }

}

run();

```

## Standalone functions

All the methods listed above are available as standalone functions. These

functions are ideal for use in applications running in the browser, serverless

runtimes or other environments where application bundle size is a primary

concern. When using a bundler to build your application, all unused

functionality will be either excluded from the final bundle or tree-shaken away.

To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).

Available standalone functions

- [`analyticsRetrieve`](docs/sdks/analytics/README.md#retrieve) - Retrieve analytics for a link, a domain, or the authenticated workspace.

- [`bountiesApproveSubmission`](docs/sdks/bounties/README.md#approvesubmission) - Approve a bounty submission

- [`bountiesListSubmissions`](docs/sdks/bounties/README.md#listsubmissions) - List bounty submissions

- [`bountiesRejectSubmission`](docs/sdks/bounties/README.md#rejectsubmission) - Reject a bounty submission

- [`commissionsList`](docs/sdks/commissions/README.md#list) - List all commissions

- [`commissionsUpdate`](docs/sdks/commissions/README.md#update) - Update a commission.

- [`customersDelete`](docs/sdks/customers/README.md#delete) - Delete a customer

- [`customersGet`](docs/sdks/customers/README.md#get) - Retrieve a customer

- [`customersList`](docs/sdks/customers/README.md#list) - Retrieve a list of customers

- [`customersUpdate`](docs/sdks/customers/README.md#update) - Update a customer

- [`domainsCheckStatus`](docs/sdks/domains/README.md#checkstatus) - Check the availability of one or more domains

- [`domainsCreate`](docs/sdks/domains/README.md#create) - Create a domain

- [`domainsDelete`](docs/sdks/domains/README.md#delete) - Delete a domain

- [`domainsList`](docs/sdks/domains/README.md#list) - Retrieve a list of domains

- [`domainsRegister`](docs/sdks/domains/README.md#register) - Register a domain

- [`domainsUpdate`](docs/sdks/domains/README.md#update) - Update a domain

- [`embedTokensReferrals`](docs/sdks/embedtokens/README.md#referrals) - Create a referrals embed token

- [`eventsList`](docs/sdks/events/README.md#list) - Retrieve a list of events

- [`foldersCreate`](docs/sdks/folders/README.md#create) - Create a folder

- [`foldersDelete`](docs/sdks/folders/README.md#delete) - Delete a folder

- [`foldersList`](docs/sdks/folders/README.md#list) - Retrieve a list of folders

- [`foldersUpdate`](docs/sdks/folders/README.md#update) - Update a folder

- [`linksCount`](docs/sdks/links/README.md#count) - Retrieve links count

- [`linksCreate`](docs/sdks/links/README.md#create) - Create a link

- [`linksCreateMany`](docs/sdks/links/README.md#createmany) - Bulk create links

- [`linksDelete`](docs/sdks/links/README.md#delete) - Delete a link

- [`linksDeleteMany`](docs/sdks/links/README.md#deletemany) - Bulk delete links

- [`linksGet`](docs/sdks/links/README.md#get) - Retrieve a link

- [`linksList`](docs/sdks/links/README.md#list) - Retrieve a list of links

- [`linksUpdate`](docs/sdks/links/README.md#update) - Update a link

- [`linksUpdateMany`](docs/sdks/links/README.md#updatemany) - Bulk update links

- [`linksUpsert`](docs/sdks/links/README.md#upsert) - Upsert a link

- [`partnersAnalytics`](docs/sdks/partners/README.md#analytics) - Retrieve analytics for a partner

- [`partnersBan`](docs/sdks/partners/README.md#ban) - Ban a partner

- [`partnersCreate`](docs/sdks/partners/README.md#create) - Create or update a partner

- [`partnersCreateLink`](docs/sdks/partners/README.md#createlink) - Create a link for a partner

- [`partnersDeactivate`](docs/sdks/partners/README.md#deactivate) - Deactivate a partner

- [`partnersList`](docs/sdks/partners/README.md#list) - List all partners

- [`partnersRetrieveLinks`](docs/sdks/partners/README.md#retrievelinks) - Retrieve a partner's links.

- [`partnersUpsertLink`](docs/sdks/partners/README.md#upsertlink) - Upsert a link for a partner

- [`payoutsList`](docs/sdks/payouts/README.md#list) - List all payouts

- [`qrCodesGet`](docs/sdks/qrcodes/README.md#get) - Retrieve a QR code

- [`tagsCreate`](docs/sdks/tags/README.md#create) - Create a tag

- [`tagsDelete`](docs/sdks/tags/README.md#delete) - Delete a tag

- [`tagsList`](docs/sdks/tags/README.md#list) - Retrieve a list of tags

- [`tagsUpdate`](docs/sdks/tags/README.md#update) - Update a tag

- [`trackLead`](docs/sdks/track/README.md#lead) - Track a lead

- [`trackSale`](docs/sdks/track/README.md#sale) - Track a sale

## Debugging

You can setup your SDK to emit debug logs for SDK requests and responses.

You can pass a logger that matches `console`'s interface as an SDK option.

> [!WARNING]

> Beware that debug logging will reveal secrets, like API tokens in headers, in log messages printed to a console or files. It's recommended to use this feature only during local development and not in production.

```typescript

import { Dub } from "dub";

const sdk = new Dub({ debugLogger: console });

```

## Summary

Dub API: Dub is the modern link attribution platform for short links, conversion tracking, and affiliate programs.

# Development

## Contributions

While we value open-source contributions to this SDK, this library is generated programmatically.

Feel free to open a PR or a Github issue as a proof of concept and we'll do our best to include it in a future release!

### SDK Created by [Speakeasy](https://docs.speakeasyapi.dev/docs/using-speakeasy/client-sdks)
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/dubinc/dub-ts

Awesome Lists containing this project

README

Dub.co TypeScript SDK
