@urixen/linkvertise/README.md

A lightweight TypeScript SDK for converting URLs using Linkvertise

# @urixen/linkvertise

A lightweight TypeScript SDK for converting URLs using Linkvertise.  
Perfect for Node.js projects and fully typed for TypeScript.

---

## 📦 Installation

```bash
npm install @urixen/linkvertise
# or using yarn
yarn add @urixen/linkvertise
```

---

## 🔧 Usage

### Importing

```ts
import { linkvertise, convert, markup, str_is } from "@urixen/linkvertise";
```

---

### Converting a URL

```ts
const url = "https://example.com";
const userId = 12345;

async function getLink() {
    try {
        const converted = await linkvertise(url, userId);
        console.log("Converted Link:", converted);
    } catch (error) {
        console.error("Error:", error);
    }
}

getLink();
```

---

### Utilities

- **`convert(url: string, user_id: number, options?: any)`**  
  Convert a URL to a Linkvertise link manually.

- **`markup(href: string)`**  
  Normalize URLs by ensuring they end properly.

- **`str_is(pattern: string, value: string)`**  
  Check if a string matches a pattern (supports `*` wildcards).

---

### Options

You can optionally pass a `blacklist` or `whitelist` when using `convert`:

```ts
const options = {
    blacklist: ["https://blocked.com/*"],
    whitelist: ["https://example.com/*"]
};
```

---

## 📝 Example

```ts
const url = "https://example.com";
const userId = 123;

const converted = await convert(url, userId, {
    blacklist: ["https://bad.com/*"]
});

console.log(converted);
```

---

## ⚡ Features

- Full TypeScript support with typings
- Encrypts URLs securely using Node.js `crypto`
- Easy-to-use SDK for Linkvertise integration
- Supports optional whitelist/blacklist for URL validation

---

## 💻 Requirements

- Node.js v18 or higher
- TypeScript (for development)
- No external dependencies required

---

## 📄 License

MIT © [Urixen](https://github.com/urixen-org)