# astro-shortlinks

Automatically create shortlinks for your [Astro](https://astro.build) site. This
integration hooks into your build process to generate short URLs for your pages
using various shortlink services.

## Installation

```bash
npm install astro-shortlinks
# or
pnpm add astro-shortlinks
# or
yarn add astro-shortlinks
```

## Basic Usage

Add the integration to your `astro.config.mjs`:

```javascript
import { defineConfig } from "astro/config";
import shortlinks, { chhotoUrl } from "astro-shortlinks";

export default defineConfig({
  site: "https://example.com", // Required for shortlinks
  integrations: [
    shortlinks(
      chhotoUrl({
        domain: "https://short.example.com",
        apiKey: process.env.CHHOTO_API_KEY,
      }),
      {
        getPageMapping: (pages) =>
          pages.map((page) => ({
            longlink: page.toString(),
            shortlink: page.pathname.replace(/^\//, ""),
          })),
      }
    ),
  ],
});
```

## Built-in Shortlinkers

### chhoto-url

Creates shortlinks using a
[chhoto-url](https://github.com/SinTan1729/chhoto-url) instance.

```javascript
import { chhotoUrl } from "astro-shortlinks";

const shortlinker = chhotoUrl({
  domain: "https://short.example.com",
  apiKey: process.env.CHHOTO_API_KEY, // Optional
  resetHits: false, // Reset hit counter when updating links (default: false)
});
```

### worker-links

Creates shortlinks using a [worker-links](https://github.com/erisa/worker-links)
Cloudflare Worker.

```javascript
import { workerLinks } from "astro-shortlinks";

const shortlinker = workerLinks({
  domain: "https://worker-links.example.workers.dev",
  secret: process.env.WORKER_LINKS_SECRET, // Required
});
```

### multi-shortlinker

Runs multiple shortlinkers in sequence, to create shortlinks on multiple
services.

```javascript
import { multiShortlinker, chhotoUrl, workerLinks } from "astro-shortlinks";

const shortlinker = multiShortlinker([
  chhotoUrl({
    domain: "https://short1.example.com",
    apiKey: process.env.CHHOTO_API_KEY,
  }),
  workerLinks({
    domain: "https://short2.example.workers.dev",
    secret: process.env.WORKER_LINKS_SECRET,
  }),
  // Add more shortlinkers as needed
]);
```

## Configuration

The second argument for `shortlinks` provides general configuration for
shortlinkers.

### `getPageMapping`

The `getPageMapping` function is required and determines how your page URLs are
mapped to shortlinks:

```javascript
{
  getPageMapping: (pages) => {
    // pages is an array of URL objects
    return pages.map((page) => ({
      longlink: page.toString(), // Full URL of the page
      shortlink: page.pathname.replace(/^\//, ""), // Path without leading slash
    }));
  };
}
```

You can customize this to:

- Use custom shortlink patterns
- Filter out certain pages
- Add custom prefixes or suffixes

### Example: Custom Shortlink Mapping

```javascript
{
  getPageMapping: (pages) => {
    return pages
      .filter((page) => !page.pathname.startsWith("/admin"))
      .map((page) => ({
        longlink: page.toString(),
        shortlink: "blog/" + page.pathname.split("/").pop(),
      }));
  };
}
```

## Creating a Custom Shortlinker

You can create your own shortlinker by implementing the `Shortlinker` interface:

```javascript
import type { Shortlinker } from 'astro-shortlinks';

interface MyShortlinkerOptions {
  apiKey: string;
  domain: string;
}

export const myShortlinker = ({ apiKey, domain }: MyShortlinkerOptions): Shortlinker => {
  return {
    name: 'my-shortlinker',
    async run(mappings, logger) {
      try {
        // Your implementation here
        for (const { longlink, shortlink } of mappings) {
          const response = await fetch(`${domain}/api/create`, {
            method: 'POST',
            headers: {
              'Authorization': `Bearer ${apiKey}`,
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              short: shortlink,
              long: longlink
            })
          });

          if (!response.ok) {
            logger.error(`Failed to create shortlink ${shortlink}: ${response.statusText}`);
            return false;
          }
        }

        logger.info(`Successfully created ${mappings.length} shortlinks`);
      } catch (error) {
        logger.error(`Error creating shortlinks: ${error}`);
        return false;
      }
    }
  };
};
```

### Shortlinker Interface

```typescript
interface Shortlinker {
  name: string;
  run(
    mappings: PageMapping[],
    logger: AstroIntegrationLogger
  ): Promise<void | boolean>;
}

type PageMapping = {
  longlink: string; // Full URL to redirect to
  shortlink: string; // Short URL path
};
```

**Important:**

- Return `false` from `run()` if the shortlinker fails and provides its own
  logging
- The logger is namespaced to your shortlinker for better debugging
- Handle errors gracefully and provide meaningful log messages
- Consider supporting both creating new links and updating existing ones

## Requirements

- Astro 5.0.0 or higher
- The `site` configuration option must be set in your Astro config

## Development

A [Nix flake](./flake.nix) is provided to easily set up a development
environment, otherwise read it to see the current required system dependencies
for developing astro-shortlinks.

```bash
# Install dependencies
pnpm install

# Build the project
pnpm build

# Development mode with TypeScript watch
pnpm dev
```

## License

[MIT License](./LICENSE)