> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vintr.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

> Use Vintr from Node.js or TypeScript with the official Node.js SDK.

The Vintr Node.js SDK is a small wrapper around the Vintr. API — a simple way to resolve aliases from Node.js or TypeScript, with built-in type declarations for autocomplete and type checking.

## Installation

```bash theme={null}
npm install @vintr/node-sdk
```

## Create a client

```typescript theme={null}
import { Vintr } from '@vintr/node-sdk';

const vintr = new Vintr('YOUR_VINTR_SECRET_KEY');
```

<Danger>
  Keep your secret key on your server. Never expose it in browser or client-side code.
</Danger>

## Resolve an alias

```typescript theme={null}
const location = await vintr.alias.resolve({
  alias: 'apple#vintr'
});
```

| Parameter | Type   | Required | Description                                                                          |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| `alias`   | string | Yes      | The Vintr alias to resolve, including its suffix (e.g. `apple#vintr`, `sushi#vintr`) |

### Response

```json theme={null}
{
  "alias": "apple#vintr",
  "type": "business",
  "location": {
    "address": {
      "line1": "1 Apple Park Way",
      "line2": "",
      "line3": "",
      "city": "Cupertino",
      "state": "California",
      "postal_code": "95014",
      "country": "US"
    },
    "geo": {
      "latitude": 37.335,
      "longitude": -122.0092,
      "altitude": null,
      "precision_meters": 5
    },
    "instructions": {
      "general": "Enter through the main visitor entrance.",
      "delivery": "Use the designated delivery entrance.",
      "autonomous": "Approach from the east access road."
    }
  },
  "createdAt": "2026-08-18T20:39:52.671Z",
  "updatedAt": "2026-08-18T20:39:52.671Z"
}
```

* **Address** — available under `location.address`
* **Coordinates** — available under `location.geo`, including `precision_meters`. `altitude` can be `null` when unavailable.
* **Instructions** — available under `location.instructions`:
  * `general` — accessing the location
  * `delivery` — for deliveries
  * `autonomous` — for autonomous systems

## TypeScript

```typescript theme={null}
import { Vintr } from '@vintr/node-sdk';
import type { AliasResponse } from '@vintr/node-sdk';

const vintr = new Vintr('YOUR_VINTR_SECRET_KEY');

const result: AliasResponse = await vintr.alias.resolve({
  alias: 'apple#vintr'
});
```

Other exported types: `Location`, `Address`, `Geo`, `Instructions`.

## Error handling

| Code  | Meaning              | Example                               |
| ----- | -------------------- | ------------------------------------- |
| `400` | Invalid alias format | `{ "error": "Invalid alias format" }` |
| `404` | Alias not found      | `{ "error": "Not found" }`            |

```typescript theme={null}
try {
  const result = await vintr.alias.resolve({ alias: 'apple#vintr' });
  console.log(result);
} catch (error) {
  console.error('Failed to resolve alias:', error);
}
```

## Complete example

```typescript theme={null}
import { Vintr } from '@vintr/node-sdk';

const vintr = new Vintr(process.env.VINTR_SECRET_KEY!);

async function main() {
  try {
    const result = await vintr.alias.resolve({ alias: 'apple#vintr' });

    console.log('Alias:', result.alias);
    console.log('Type:', result.type);
    console.log('Address:', result.location.address.line1, result.location.address.city);
    console.log('Coordinates:', result.location.geo.latitude, result.location.geo.longitude);
    console.log('Delivery instructions:', result.location.instructions.delivery);
  } catch (error) {
    console.error('Failed to resolve alias:', error);
  }
}

main();
```

## Keep your API key private

Load your secret key from an environment variable rather than hardcoding it:

```bash theme={null}
VINTR_SECRET_KEY=your_secret_key
```

```typescript theme={null}
import { Vintr } from '@vintr/node-sdk';

const vintr = new Vintr(process.env.VINTR_SECRET_KEY!);
```

Never commit your secret key to a public repository or expose it to users.

## API alternative

The SDK is optional. If you're not using Node.js, or prefer raw HTTP requests, see the [Quickstart](/quickstart) for the API integration guide.

|          |                         |
| -------- | ----------------------- |
| Package  | `@vintr/node-sdk`       |
| Version  | 1.0.0                   |
| Language | TypeScript / JavaScript |
| Runtime  | Node.js                 |

The SDK is intentionally minimal: install it, create a client, resolve an alias.